[huangyiirene]

Fixes #19198

Clause-②: no

The defect

ApprovalService.resolveLookupFields admitted type: 'user' fields but resolved their target from the materialized reference carrier. The spec declares the opposite for exactly that type — IMPLICIT_REFERENCE_TARGETS in packages/spec/src/data/field-value.zod.ts, re-read verbatim on origin/main at 7d0f911da before this branch was cut:

user is the only member: field.zod defines it as "a lookup specialized to the sys_user system object … target fixed to the sys_user system object", and the Field.user() builder — unlike Field.lookup(reference, …) / Field.masterDetail(reference, …) — takes NO target argument and writes reference: 'sys_user' itself. The target is a CONSTANT OF THE TYPE, so reference on a user field materializes that constant; it does not supply it. Metadata authored without it (hand-written JSON, an AI author, a Studio form) is fully specified, not under-specified.

So the one spelling the contract calls complete was the one the reader refused — and it refused it silently: no refusal, no diagnostic, the field simply absent from payload_display, and a business reviewer reading a raw user id where every other reference field showed a name. referenceTargetOf lives in that same module precisely to supply the constant (Framework#4443 / cloud#983 fixed the identical blindness at the $expand gate and in the expansion engine).

The repair

resolveLookupFields now asks referenceTargetOf — the spec's single arbiter of what a reference field points at — instead of reading the carrier.

• Nothing else widens. The admitted types are unchanged (lookup, master_detail, user). A lookup / master_detail whose author-chosen target is absent still names nothing, is still left out, and still issues no read; tree is deliberately not added (see acceptance notes).
• The unreadable-carrier behaviour is unchanged. referenceTargetOf reads the carrier through referenceCarrierOf, so the TypeError is still raised for an object- or array-valued reference and is still caught per field, and the existing pins in src/lookup-field-reference-carrier.test.ts pass untouched. The warning line now names this reader in its own prefix, because the message the arbiter throws names itself.
• No authoring change. Metadata that already spells reference: 'sys_user' resolves to the same target it always did. Making authors restate the constant was rejected on the card as the 消费端宽容 direction the charter rejects.

Tests — silence is the defect, so both halves are pinned

New src/implicit-reference-target-lookup.test.ts (5 cases):

1. a { type: 'user' } field with no reference resolves to sys_user, and that value is asserted to equal referenceTargetOf({ type: 'user' }) — so a hand-copied sys_user literal in this package would not satisfy it;
2. implicit and materialized spellings answer identically;
3. an author-chosen target that names nothing is still left out, with no warning;
4. the consumer-level pin: on an object whose ONLY reference field is the implicit-target one, the enrichment now issues exactly one sys_user read for the payload's id (toHaveLength(1), ids ['u7']) and produces payload_display = { assignee: 'Grace Hopper' }. The read is the half a happy-value assertion cannot see — before the repair that read was never issued at all;
5. the opposite direction: a genuinely targetless lookup produces no read against any referenced object and leaves payload_display unset, so "the implicit target is enriched" cannot be read as "everything is enriched now".

Reverse verification (ablation), run from the committed state through scripts/ablation-replace.mjs — anchor hit 1 time, blob 703a308132 → b1fa2e3f0300 on disk, mutation replacing the arbiter call with the pre-repair carrier read:

Test Files  1 failed | 1 passed (2)
     Tests  3 failed | 6 passed (9)

Cases 1, 2 and 4 go red (expected undefined to deeply equal { key: 'owner', reference: 'sys_user' }; expected [] to have a length of 1 but got +0); cases 3 and 5 stay green because they are the controls, and the whole sibling carrier suite stays green — the mutation is narrow. Restored and proven restored: blob back to 703a308132, identical to HEAD, git diff HEAD empty.

Gates

Everything below was captured with the exit code read before any pipe, at aef74f0fa.

• pnpm --filter @objectstack/plugin-approvals test — exit 0, 49 files / 780 tests passed.
• pnpm --filter @objectstack/plugin-approvals typecheck — exit 0, all three legs this package's script names (tsc --noEmit, tsc --noEmit -p tsconfig.scripts.json, check:test-typecheck). The test-layer ledger is unmoved: 8 file(s) / 324 error(s) / 27 pinned signature(s) — the new test file adds none and takes no entry.
• node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands derived 61 families; all 61 were run and reconciled with --ran: "61 derived famil(ies) accounted for — 61 run, 0 NOT-MEASURED (a DERIVED zero — all 61 recorded an exit code and none of them is 3)."
• Six of those first answered exit 3 = PREREQUISITE NOT MET = NOT MEASURED (check:dts-closure, check:dual-build-cjs-loads, check:i18n, check:lean-entry-closure, check:sourcemap-no-sources-content, check:type-check-debt). Each prerequisite was cleared — the dependency closure, then turbo run build over all packages — and each re-run to exit 0. None is reported as a zero.
• pnpm lint (eslint . --no-inline-config, the repo's only style authority) — exit 0 over the whole tree, so no narrowing is being claimed.
• grep os-regen .gitattributes read on the spot: no path in this diff is merge-driver managed.

Acceptance notes

Noted, not filed — each states who would meet it:

• tree is a reference type this enrichment still does not admit. REFERENCE_VALUE_TYPES has four members; resolveLookupFields carries three, and plugin-audit deliberately carries the same three (audit-writers.ts: "tree is NOT on the list: it carries no reference"). Admitting it would widen what the inbox resolves rather than repair what it silently dropped, which is not this card. Successor: whoever next touches the shared three-type vocabulary in either package.
• The warning text moved. The reader's name is now in the approvals prefix rather than inherited from the arbiter's message, because referenceTargetOf takes no reader label. The existing assertion on it still passes unchanged.

Reported to the dispatching seat rather than filed here (dev agents report findings with dedupe words; they do not file): one class-(b) sibling of this defect in plugin-audit, and a reading that partly falsifies this card's own unverified note about the analytics resolver.

Not this PR

packages/spec is read-only on this lane — referenceTargetOf and IMPLICIT_REFERENCE_TARGETS are imported and nothing in them is edited. No release-notes page is touched.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/plugin-approvals, touching 2 documentable anchor(s).

1 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/automation/flows.mdx (via ApprovalService (symbol, a top-level class))

What this run could not see

• the SDK route bridge reached 60 of 215 client-bound route-ledger rows — the other 155 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 155: 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; 100 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 — 6 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 7d0f911da9ab9af94b72c0dfcfed16f676879bd5 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 705be093d0a7f5e7a8b0c0c9370ee30482174028 — the merge of head aef74f0fa5df95511af4c166b8e49d80391bf947 into base 7d0f911da9ab9af94b72c0dfcfed16f676879bd5, 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 705be093d0a7f5e7a8b0c0c9370ee30482174028 && git checkout 705be093d0a7f5e7a8b0c0c9370ee30482174028
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 7d0f911da9ab9af94b72c0dfcfed16f676879bd5 aef74f0fa5df95511af4c166b8e49d80391bf947 && git checkout -B drift-repro 7d0f911da9ab9af94b72c0dfcfed16f676879bd5 && git merge --no-ff aef74f0fa5df95511af4c166b8e49d80391bf947

node scripts/docs-audit/affected-docs.mjs --json 7d0f911da9ab9af94b72c0dfcfed16f676879bd5

⚠️ 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 7d0f911da9ab9af94b72c0dfcfed16f676879bd5 → pass the list as
args.docs, on the commit named under Which tree this was computed on.