feat(8.0): visibility field (public/internal/system) on nouns + verbs

Adds a reserved, top-level `visibility` field (mirrors the subtype rollout):
'public' (default, surfaced) | 'internal' (developer app-internal — hidden from
default find/count/stats, opt-in via includeInternal) | 'system' (Brainy
plumbing, library-set only).

Fixes a real leak: the VFS root entity counted in getNounCount() and appeared in
find() (a fresh brain reported 1 entity). It is now visibility:'system' →
excluded from every user-facing surface. Developers also get a first-class
hidden-unless-asked tier (e.g. learned internals vs user-exposed data).

- Reserved (RESERVED_ENTITY_FIELDS / RESERVED_RELATION_FIELDS) — spoof-proof from metadata.
- Threaded through add/relate/update/transact; surfaced top-level on reads.
- Default exclusion in counts (baseStorage), find()/related() (hard candidate
  filter via excludeVisibility — keeps topK/limit correct), and stats;
  includeInternal/includeSystem opt-ins.
- VFS root marked 'system'.

Tests: visibility.test.ts 17/17 (fresh-brain getNounCount()===0, internal hidden
+ opt-in, verb symmetry, top-level surfacing, metadata-spoof rejection). Unit
1431 green; count-synchronization integration now passes (off-by-one fixed).
This commit is contained in:
David Snelling 2026-06-16 15:20:26 -07:00
parent 0ca0e5c6cc
commit f4dea80176
10 changed files with 777 additions and 41 deletions

View file

@ -549,6 +549,7 @@ export function validateUpdateParams(params: UpdateParams): void {
!params.type &&
!params.vector &&
params.subtype === undefined &&
params.visibility === undefined &&
params.confidence === undefined &&
params.weight === undefined
) {

View file

@ -116,6 +116,11 @@ export async function rebuildCounts(storage: BaseStorage): Promise<RebuildCounts
for (const noun of result.items) {
const metadata = await storage.getNounMetadata(noun.id)
if (metadata?.noun) {
// 8.0 visibility: the user-facing counts only include public entities.
// Internal/system entities (e.g. the VFS root) are excluded — keeping this
// rebuild consistent with the incremental gating in baseStorage.
const visibility = metadata.visibility
if (visibility === 'internal' || visibility === 'system') continue
const entityType = metadata.noun
entityCounts.set(entityType, (entityCounts.get(entityType) || 0) + 1)
totalNouns++
@ -146,6 +151,8 @@ export async function rebuildCounts(storage: BaseStorage): Promise<RebuildCounts
for (const verb of result.items) {
if (verb.verb) {
// 8.0 visibility: exclude internal/system edges from the user-facing counts.
if (verb.visibility === 'internal' || verb.visibility === 'system') continue
const verbType = verb.verb
verbCounts.set(verbType, (verbCounts.get(verbType) || 0) + 1)
totalVerbs++