fix(metadata-core): the object-schema field mask also removes a denied field's references from the served document (ADR-0106 D1)

[objectstack-fleet]

Fixes #21723

Clause-②: yes (widening) — one new exported type, FlsContractRetention, on @objectstack/metadata-core's published ./testing entry; graded minor.

What changed

ADR-0106 D1 says a field the caller cannot read is removed from the served object schema whole. applyObjectSchemaMask (@objectstack/metadata-core) only removed the field's entry from fields. Other parts of the document that named the field went out unchanged. The mask now also removes a denied field's references from the rest of the served object document. Every exit that serves an object schema runs this one projection: the by-name read, the list read and the layered view, on the REST server and the runtime dispatcher. So all of them get the fix, and no exit needed its own edit.

The new module packages/metadata-core/src/object-schema-fls-references.ts classifies every position once. It has a table for the object level and a table for the field level:

Position kind	Examples	What happens to a reference to a denied field
Rule entry	validations[], indexes[], activityMilestones[]	The entry is dropped whole. The caller cannot evaluate a rule over a value it never receives, and the rule's text describes the field. The platform still enforces the stored rule on every write.
Role pointer	nameField, displayNameField, imageField, stageField, tenancy.tenantField, lifecycle.ttl.field, a field's referenceVia	The key is deleted, so the role falls back to its default.
Name list	highlightFields, searchableFields, publicSharing.redactFields, list-view column lists, external.columnMap, and a readable field's relatedListColumns / dependsOn	The denied entries are filtered out. A list left empty is deleted.
Expression	titleFormat, field-group and row-CRUD predicates, publicSharing.eligibility, lifecycle onlyWhen, and a readable field's formula expression, visibleWhen / readonlyWhen / requiredWhen, relatedListFilter, defaultValue, autonumberFormat, per-option visibleWhen	The key is deleted. The readable field itself stays.
Presentation entry	listViews.*, actions[]	Column lists are filtered. An entry whose filter, sort, predicate or params read a denied field is dropped, because serving it without that part would change what it does.
Inline grid	inlineColumns, inlineAmountField (declared on the child's own master-detail field, naming the child's own columns)	A column that is, or is computed (expr) from, a denied field is dropped; a denied amount field is deleted.
Foreign	lookupColumns, lookupFilters, displayField, descriptionField, summaryOperations	Left alone. These name another object's fields, which that object's own projection governs.

"References" is an identifier-token test: a string mentions x when one of its identifier tokens is exactly x. So record.x > 0 and {x} match, and x_code and X do not. In a classified position a key is a reference only inside a field-keyed block (a filter condition, lifecycle onlyWhen, an action patch; $ operator keys excluded), and values under closed-vocabulary keys (type, dialect, severity, …) are not read; the unclassified path tests every key. A list view keyed by a denied name is dropped. A list-view column in object form is dropped when any of its facets (field, prefix.field, summary.field) names a denied field; the column, prefix and summary tables are pinned to the live spec. A field's dependsOn object entries are read the same way. A dotted path whose root segment is a denied field counts as a reference to it. The reference walk carries a cycle guard. A key neither table classifies is deleted when it mentions a denied field. A new spec key therefore over-masks rather than leaks until it is classified. A pin holds the tables equal to the live ObjectSchema / FieldSchema / InlineGridColumnSchema / ListColumnSchema / ColumnPrefixSchema / ColumnSummaryConfigSchema key sets, in both directions, so a new key fails CI on the day it lands.

The projection is still pure. The shared cache's full copy is never mutated. A caller who is denied nothing gets the same document reference back, which is the D3 byte-identical guarantee. Key order is kept.

Scope decisions

1. Object-level validation rules that reference a denied field are dropped, not redacted. A redacted rule (condition removed, message kept) still says the field exists. A rule is server policy, so dropping it from the served document loses no enforcement.
2. References inside readable fields. Same-object name lists are filtered. Same-object expressions are deleted, and the field and its other facets are kept. Foreign-object name positions are not touched.
3. Other top-level keys that carry field names. All are covered by the classification above. The full list is in OBJECT_REFERENCE_POSITIONS.

The contract

FLS_CONTRACT_OBJECT (@objectstack/metadata-core/testing) still has four fields, so the consumer suites that count them are unchanged. It now names those fields in every position kind above. The residue check in assertObjectSchemaMaskCase used to look for a quoted name. It now looks for an identifier token in every string leaf and key of the served document, so a name inside an expression fails it. Before, the contract's own readable-formula case passed while serving a formula that read the denied field. Projection cases also carry retained facts: things the masked document must still say, such as the rule over readable fields, the filtered lists and the readable sibling predicates. So a mask that deletes too much fails too. The unmasked cases check that every reference survives.

Verification

Second review round (head 80e5f775d): the contract-tier review's object-form list-view column finding and the dotted-path key gap are addressed. metadata-core 369/369 + typecheck; rest mask consumers 123/123; runtime meta-object-fls 85/85; ablation of the object-entry change turns 5 pins red, including three contract cases. dispatch-gates 59/62 green locally, 3 not measured (workspace-build / time-limit), left to CI.

Review round (head c0a2b9990 + changeset grade 8a8f488ae): an independent pre-merge review asked for the inline-grid positions, key-reading precision, a cycle guard, denied-name list-view keys and contract coverage; all are addressed. metadata-core vitest + typecheck 362/362; rest mask consumers 123/123; runtime meta-object-fls 85/85; ablation of the inline-grid and key-reading changes turns their pins red (5 and 1 failures); dispatch-gates 60/62 run green, 2 not measured (check:dual-build-cjs-loads needs a full workspace build, check:type-check-debt timed out locally — CI runs both). The figures below are from the first round.

All runs below are on head 4ab5f92b9. The final head, bbaec097c, changes only a docblock example. On it, metadata-core's build, typecheck and test passed again (350/350). So did check:nul-bytes, check:type-check-coverage, check:type-check-debt, check:doc-authoring, check:issue-citations, check:published-files, check:cross-package-test-inputs and check:test-source-alias, all exit 0.

• pnpm --filter @objectstack/metadata-core build && … typecheck && … test: 18 files, 350 tests passed.
• The contract table through every exit, after rebuilding metadata-core's dist:
  • @objectstack/rest: meta-object-fls, meta-item-save-capability-gate and meta-compound-save-and-reset-capability-gate, 3 files, 123 tests passed.
  • @objectstack/runtime: domains/meta-object-fls, 1 file, 85 tests passed.
• Other mask consumers:
  • @objectstack/rest: 4 files, 445 tests passed.
  • @objectstack/runtime: 8 meta read/list/parity files, 856 tests passed.
• Ablation, done through scripts/ablation-replace.mjs on the committed tree. The reference projection was replaced by the old { ...rec, fields: kept }. The anchor went 1 to 0 and the blob changed.
  • Result: 16 of 24 tests in object-schema-fls-references.test.ts failed. That includes all three contract projection cases, for example 'salary_grade' is gone from fields but is still referenced at $.stageField.
  • The file was restored to the HEAD blob, with an empty git diff HEAD.
• Live check on a fresh boot of the stock example app:
  • The caller was a restricted member: a field-level grant withholds readable on several fields of one object.
  • The member's by-name, list and layered reads of that object were scanned for identifier references to any denied field. All three had zero, including the code and effective layers.
  • The admin control read of the same object still serves the field definitions, the rule and the related-list column.
• Gates: dispatch-gates.mjs --commands derived 62 families for this change set. All 62 ran and exited 0. The reconciliation (--ran) reports 62 accounted for, with a derived zero NOT-MEASURED.
• Lint, narrowed to the 4 changed TypeScript files: pnpm exec eslint --no-inline-config --format json reported 4 files, 0 errors and 0 warnings. eslint.config.mjs never enables type-aware linting, so this diff cannot change the verdict on any untouched file. The full pnpm lint is left to CI.

Acceptance notes

• Out of scope, as ADR-0106 D5(4) defers it: other metadata types (view, page, dataset, …) that name a hidden field are a separate follow-up. This PR covers the object schema only.
• Foreign-object positions. Object B's lookup to object A may list A's fields in lookupColumns / displayField, and a parent's summaryOperations.field names a child field. Those names are judged against B's denied set, never A's. Masking them needs A's readable set while B is served. That is a cross-object projection, not attempted here. On the stock example app no such position names a denied field (measured on the member's full list read).
• Prose is not matched in readable field definitions or in list views and actions. Labels and descriptions are display text. Prose inside a dropped rule goes with the rule.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/metadata-core, touching 100 documentable anchor(s).

69 hand-written doc(s) name something this change touched — list omitted above 15 rows. Re-derive on the tree named below: node scripts/docs-audit/affected-docs.mjs --json 1289925c0a5649768db44f47c04bbe4002e8f777.

⛔ 14 release-owned page(s) also affected — read-only, see AGENTS.md Documentation Guardrails.

What this run could not see

• 2 anchor(s) matched too much of the corpus to be a work list: defaultValue (symbol, 30 pages), sharingModel (symbol, 43 pages)
• 32 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 54 of 206 client-bound route-ledger rows — the other 152 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 152: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 55 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 97 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 4 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 1289925c0a5649768db44f47c04bbe4002e8f777 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 85667e9d0597cf43f2e2e336516dd1dc2a79a589 — the merge of head 80e5f775deba32e6be3a0ef8a1a5f438037b9701 into base 1289925c0a5649768db44f47c04bbe4002e8f777, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 85667e9d0597cf43f2e2e336516dd1dc2a79a589 && git checkout 85667e9d0597cf43f2e2e336516dd1dc2a79a589
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 1289925c0a5649768db44f47c04bbe4002e8f777 80e5f775deba32e6be3a0ef8a1a5f438037b9701 && git checkout -B drift-repro 1289925c0a5649768db44f47c04bbe4002e8f777 && git merge --no-ff 80e5f775deba32e6be3a0ef8a1a5f438037b9701

node scripts/docs-audit/affected-docs.mjs --json 1289925c0a5649768db44f47c04bbe4002e8f777

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 1289925c0a5649768db44f47c04bbe4002e8f777 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[objectstack-fleet]

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 8a8f488ae5bffcb5b69050d773f1e7ce1e398e2e
Local-runs: probe — the dispatching seat asked for the metadata-core vitest run at this head plus a scratch read of the reference-mask module over the position classes the prior review flagged; nothing else was built or re-run

① Derived judgments

1. Published surface of @objectstack/metadata-core. ./testing: one new exported interface (FlsContractRetention); the fields arm of the exported FlsContractVerdict union gains an optional retained member; the as const fixture FLS_CONTRACT_OBJECT gains list-view, action and inline-grid facets and its formula field now uses the spec's expression key (the former spelling was never a FieldSchema key). assertObjectSchemaMaskCase, OBJECT_SCHEMA_MASK_CASES, ObjectSchemaMaskCase, ObjectSchemaMaskExit, ObjectSchemaMaskOutcome — signatures unchanged. Runtime entry: applyObjectSchemaMask signature unchanged; a project posture now also removes a denied field's references. Judged: accurate, and a widening.
2. "Every position is classified, pinned both ways against the live ObjectSchema / FieldSchema / InlineGridColumnSchema key sets." Verified: the pins exist and run in both directions. Caveat: they are key-set pins on three shapes only; a nested shape under a classified key is not pinned, which is where the defect in item 3 lives.
3. "Name lists — the denied entries are filtered out" (list-view column lists). INCORRECT for the object form of a column entry. The scrub judges an entry by its own field name alone; a same-object field pointer the spec declares on the entry's own shape (its prefix and footer-summary pointers) is served when it names a denied field. Class: residual same-object reference inside a classified name-list position. Severity: medium — a disclosure of the kind ADR-0106 D1 closes, in a position the PR table claims handled, not exercised by the contract fixture, so the suite stays green. Remedy class: read an object entry's other facets with the same reference test (drop the entry or the view) and give the fixture one entry in object form.
4. The prior review's six items (inline grid classified as this object's; keys read only inside field-keyed blocks with a closed-vocabulary skip; cycle guard; denied-name list-view key; fixture key and coverage; docblock limitations): verified fixed by reading and by probe. No over-deletion found in the closed-vocabulary skip set; no classified position holding a field-keyed block was found outside the field-keyed key set.
5. Low, not blocking: inside a field-keyed block the key is compared whole, while every other key and string reading is identifier-token based, so a path-spelled key whose root segment is a denied field is not read. Informational: a presentation entry whose non-field identifier (an action parameter name) equals a denied field is dropped — over-masking, never a leak.
6. Disclosure hygiene: PR body, changeset, commit messages and code comments name no example-app object, field or persona and carry no reproduction recipe.

② Semver level

• Clause-②: yes (widening) with a minor changeset: correct. A new exported type on the published ./testing subpath and an optional member added to an exported union arm are widenings; yes takes at least minor.
• The behaviour change — a restricted caller's served object document omits more — enforces the already-declared ADR-0106 D1 contract on the runtime entry. No authorable key, export or config is removed or renamed, so no BREAKING arm and no ADR-0087 disposition is due. The fixture's key correction is test-only data consumed through the published driver; the four in-repo consumer suites read none of its properties. Judged: not a narrowing.

③ Boundary flags

• Dev flags — other metadata types deferred per D5(4); foreign-object positions judged by their own object's projection; prose not matched in readable fields, list views and actions: acknowledged and consistent with ADR-0106. The prose boundary holds for the keys skipped — none of them interpolates record fields (action success copy interpolates the server result scope only).
• Check-runs on this head when read (2026-10-04T14:54Z): 21 success, 5 skipped, 12 still in progress, 0 failed — not yet a full-green reading.
• Regen-provenance: not applicable.

Implemented-by: claude/issue-21723-metadata-mask
Reviewed-by: session_018zT8d8NpiQ1ExhuNd5TxY6

VERDICT: FAIL — item ① 3: a classified name-list position still serves a same-object reference to a denied field through an entry's nested pointer; the PR's D1 claim does not hold for that position until it is read.

---

Generated by Claude Code

[objectstack-fleet]

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 80e5f775deba32e6be3a0ef8a1a5f438037b9701
Local-runs: probe — the dispatching seat asked for the metadata-core vitest run at this head (18 files, 369/369) and a scratch read of the reference-mask module over the position classes the prior record flagged, with one spec build to serve both; nothing else was built or re-run

① Derived judgments

1. The prior record's FAIL item (comment 5981291233, ① 3 — an object-form list-view column serving a same-object pointer to a denied field through its nested facets): fixed. A column entry now goes through a classified table; the entry is dropped when ANY facet reads a denied field (its own field, its prefix.field, its summary.field), and a facet the table does not classify is read fail-safe (any mention drops the entry). The column, prefix and summary tables are pinned both ways against the live ListColumnSchema / ColumnPrefixSchema / ColumnSummaryConfigSchema key sets, and the shared contract fixture carries a view in object form whose retained facts hold the readable sibling column. Verified by reading and by probe. No new over-deletion: a readable column stays when only a sibling column is denied; the bare summary vocabulary, a renderer type and a click action id are not read as fields; an emptied list is deleted and the view stays.
2. The prior record's low item (① 5 — a path-spelled key whose root segment is a denied field was not read): fixed. A name, a pointer and a field-keyed key are matched on the root segment as well as whole, so a dotted path through a denied field is a reference to it in a field-keyed block (including under a $ operator), a name list and a role pointer alike. Controls hold: a path rooted at a readable field is kept, and a NON-root segment equal to the denied name is not a reference.
3. dependsOn object entries are classified: field is a sibling pointer, param is the lookup target's key and is kept. An unclassified facet on such an entry is read fail-safe. Judged: accurate, and not an over-deletion.
4. Published surface. No export is added to or changed on the ./testing entry this round; the as const fixture FLS_CONTRACT_OBJECT gains one list view in object form (a widening of the exported fixture's literal type). The new *_POSITIONS constants are exported from the references module only, which the package's runtime index does not re-export — package-internal, read by the pin test. The runtime entry applyObjectSchemaMask keeps its signature; a project posture removes more.
5. Sweep for remaining nested same-object pointers under a classified position: none found. Every same-object pointer declared on a nested list-view shape (the board, calendar, gantt, gallery, timeline, chart, map, tree, grouping, row-colour, conditional-formatting, sort, filter-rule and user-filter sub-configs) and on a nested action shape (params and their options, patch, ai.paramHints, the row-id field, the target template, the body extras, the predicates) sits under a key the classified reading reads, so a denied name there drops the entry whole; none sits under a prose or vocabulary key. On the field level the remaining nested shapes (select options, inline-grid column options, roll-up summary, lookup columns and filters, currency config, storage) either name another object's fields or carry no field pointer.
6. The informational over-mask from the prior record (an action param whose name equals a denied field drops the action) is now written into the module's accepted-limitations list with its reason. Consistent: over-masking never discloses.
7. Disclosure hygiene: the PR body, the changeset, the two commit messages and the code comments of this round name no example-app object, field or persona and carry no reproduction recipe.

② Semver level

• The PR body's Clause-②: yes (widening) with a minor changeset for @objectstack/metadata-core: still correct. The widening is the one the prior record graded (one new exported interface and one optional member on the ./testing entry); this round adds no further export there, and the fixture's literal-type growth is the same class. yes takes at least minor; minor is declared. No authorable key, export or config is removed or renamed, so no BREAKING arm and no ADR-0087 disposition is due.
• The changeset body carries Clause-②: no with no direction arm. The gate that reads that carrier looks for a narrowing arm, and none is declared, which is right for this diff; but the value disagrees with the PR body's yes on the same question. Not blocking (neither gate cross-reads the other carrier and the diff narrows nothing); flagged below for alignment.

③ Boundary flags

• Dev flags acknowledged and consistent with ADR-0106: other metadata types deferred per D5(4); foreign-object positions judged by their own object's projection; prose not matched in readable field definitions, list views and actions; a param name equal to a denied field over-masks by design.
• The vocabulary skip for schema is total in a classified position. The only schema-keyed subtrees reachable there describe a JSON field's value shape (a json_schema rule on a readable field) or a metadata type's shape (a list view's schema data provider), not this object's record, so a name inside one is not a reference to a field; this sits inside the prose-and-vocabulary boundary the dev already recorded. Informational.
• Owning seat: align the changeset body's Clause-② value with the PR body's yes (widening) so the two carriers say the same thing; a follow-up edit, not a condition of this verdict.
• Check-runs on this head when read (2026-10-04T15:46Z): 31 success, 5 skipped, 4 still in progress (three Test Core shards and Lint and Repo Gates), 0 failed — not yet a full-green reading; the Tier S landing waits for it.
• Regen-provenance: not applicable.

Implemented-by: claude/issue-21723-metadata-mask
Reviewed-by: session_018zT8d8NpiQ1ExhuNd5TxY6

VERDICT: PASS

---

Generated by Claude Code