fix(objectql): file-field hydration asks canReadObject before reading sys_file, so a record read logs no access denial

[objectstack-fleet]

Fixes #24335

Clause-②: no (no accept set or public surface moves: the served bodies and every refusal are unchanged; owes the seat's review of record at TIER_DEFAULT before the queue)

What changed

resolveFileReferences (packages/objectql/src/engine.ts) read sys_file as the caller and took the refused arm on the throw. A member with read on the record's object and without sys_file read therefore made a sys_file access attempt on every by-id and list read, and plugin-security logged [Security] Access denied: operation 'find' on object 'sys_file' is not permitted for positions [org_member, everyone] at WARN for each one.

The engine now asks before it reads, as the parent-record read gate does ("A skipped object is not an access attempt", parent-record-read-gate.ts):

• New private callerMayReadSysFile asks the registered security service's canReadObject('sys_file', caller). It goes through the slot the engine already resolves (resolveReadableIdsSecurity, wired by ObjectQLPlugin) and uses the caller's envelope minus its operation-private keys (withoutOperationPrivateKeys, as readParentDerivedFiles already does). No new security API.
• false: the refused arm is served without the read.
• true: the caller's read goes ahead exactly as before, and the middleware still decides.
• Unasked (no usable security service, no canReadObject, or an ask that throws): the read goes to the middleware as before. The ask can only narrow what is read.
• The refused arm moves verbatim into serveRefusedFileHydration. It is shared by the ask and by the existing PERMISSION_DENIED catch, which stays for any refusal the admission did not foresee.
• ⛔ plugin-security is not touched: its refusal, its log line and its level are unchanged.

Why this shape (four axes)

• Real business need: measured. Every member of a deployment whose app grants no sys_file read hits this on every record read (the WARN reproduced below on the booted composition).
• Long-term soundness: engine-only. The security layer stays the single judge of every read it sees, and canReadObject is its own object-level gate, arm for arm. The alternative, a context flag marking the hydration read internal, would cross into plugin-security (domain:services) and add a bypass marker.
• Guarding against AI mistakes: no bypass marker means there is nothing an author or agent can set to mute a denial. The refused value contract (FileRefusedValueSchema) is unchanged.
• Startup scope: no new API, option, error code or gate.

Measurements (M, booted composition)

New dogfood pin packages/qa/dogfood/test/file-field-hydration-no-denial.dogfood.test.ts. It runs on a real org-bound bootStack with the real SecurityPlugin, the real StorageServicePlugin (local adapter, real bytes), and one record object holding a field-owned file. "Before" is measured on the same boot with canReadObject withdrawn from the service, which is the engine's pre-change path.

read	reader	before: security denials	after: security denials	body
GET /data/fhn_doc/ID	member, no sys_file read	1 (on object 'sys_file')	0	byte-identical (res.text()), file hydrated
GET /data/fhn_doc	member, no sys_file read	1	0	byte-identical, file hydrated
GET /data/fhn_doc/ID and list	reader with sys_file read	0	0	byte-identical, same hydrated value
GET /data/sys_file/ID	member	-	1	403 PERMISSION_DENIED, unchanged

Run on df035c834: pnpm --filter @objectstack/dogfood exec vitest run test/file-field-hydration-no-denial.dogfood.test.ts, 5 passed.

Ablation (one, of the ask): done with scripts/ablation-replace.mjs (anchor hit once, blob 0186fa3c → b21c19e7). The ask was disabled, objectql was rebuilt, and ablation-dist-preflight found the marker in 4 dist/ files. The two member WARN-count pins went red with exactly the issue's line: expected [ "[Security] Access denied: operation 'find' on object 'sys_file' is not permitted for positions [org_member, everyone]" ] to deeply equal [] (2 failed, 3 passed). Restore: blob back to 0186fa3c, git diff HEAD empty, rebuilt, --absent preflight clean, 5 passed.

Cost of the ask: one canReadObject per hydration call, which is once per request for both by-id and list (measured: 1 ask per by-id read, 1 per list read), never per row. It is a cached permission check with no store read: 6.4 µs per ask (mean of 300 iterations on a shared box). The refused sys_file read it replaces cost about 1.2 ms. A reader with sys_file read pays the extra ask. End-to-end by-id latency on the shared box was within noise.

Pins beside it

packages/objectql/src/engine-file-hydrate-refused.test.ts reuses that file's existing driver double, so no new double is added. Its boot gains a security slot option and an attempts log on the refusing middleware. New cases:

• A refused admission makes no sys_file read and serves the refused marker. The ask is about sys_file, carries the caller's envelope and no __ keys.
• The list and by-id bodies are byte-identical to the unasked engine's, and that comparison is armed: the unasked engine did attempt the read.
• A direct sys_file read is still PERMISSION_DENIED / 403 and still reaches the security layer.
• Controls: an admitted reader is hydrated; an admitted read that is still refused takes the same arm; with no canReadObject, or an ask that throws, the engine reads as before; a record with no file id asks nothing.

Pin sweep: the existing pins on the refused arm and its debug line (engine-file-hydrate-refused.test.ts, engine-file-hydrate-parent-derived.test.ts, plugin-security file-field-hydration-refused.test.ts, service-storage field-owned-file-hydration-door-agreement.test.ts) wire no security service into the slot, so they still exercise the read-then-refuse arm, and they stay green unmodified.

Verification record (head df035c834, after merging origin/main e22defb13)

• pnpm --filter @objectstack/objectql typecheck: exit 0. pnpm --filter @objectstack/dogfood typecheck: exit 0. Both were run before and after the merge.
• pnpm --filter @objectstack/objectql exec vitest run: 445 files, 8366 tests passed.
• Dogfood pin: 5 passed (after the merge, on rebuilt objectql, plugin-auth and platform-objects).
• node scripts/pm/dispatch-gates.mjs --commands (no paths), 74 families. All 72 runnable families exit 0 on df035c834. --ran reconciliation: 74 derived, 72 run, 2 NOT-MEASURED, 0 UNRUN.
  • NOT MEASURED: check:query-options-erasure (repo-wide eslint scan). The first local attempt was in flight when the container killed the worker (exit 137), and the retry hit the 280 s local window. CI's Lint & Repo Gates runs it.
  • NOT MEASURED: check:type-check-debt (repo-wide tsc census). It hit the same window and is left to CI.
  • check:dual-build-cjs-loads first exited 3 (PREREQUISITE NOT MET: 8 unbuilt packages). It was built for and re-run, and passes: 111 require entry points load.
• node scripts/check-platform-checklist.mjs --changed-from origin/main: OK, 0 lost.

Acceptance notes

• canReadObject mirrors the middleware's object-level arms but not its public-form grant (publicFormGrant), which admits find only on the form's own target object. A form targeting sys_file is not a realistic declaration, so no such caller reaches this path. Noted, not filed.
• Locally, an interrupted gate run left packages/spec/dist without its .d.ts, and a spec rebuild restored it. This was local build state, not a finding.
• The dogfood pin is declared to domain:cli at review, per the claim.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/objectql, touching 4 documentable anchor(s).

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

• content/docs/api/plugin-endpoints.mdx (via sys_file (literal, a string literal in callerMayReadSysFile))
• content/docs/automation/approvals.mdx (via sys_file (literal, a string literal in callerMayReadSysFile))
• content/docs/deployment/cli.mdx (via sys_file (literal, a string literal in callerMayReadSysFile))
• content/docs/kernel/contracts/storage-service.mdx (via sys_file (literal, a string literal in callerMayReadSysFile))
• content/docs/permissions/attachments-access.mdx (via sys_file (literal, a string literal in callerMayReadSysFile))
• content/docs/protocol/objectql/types.mdx (via sys_file (literal, a string literal in callerMayReadSysFile))
• content/docs/ui/translations.mdx (via sys_file (literal, a string literal in callerMayReadSysFile))

⛔ 7 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/implementation-status.mdx (via sys_file (literal, a string literal in callerMayReadSysFile))
• content/docs/releases/index.mdx (via sys_file (literal, a string literal in callerMayReadSysFile))
• content/docs/releases/v15.mdx (via sys_file (literal, a string literal in callerMayReadSysFile))
• content/docs/releases/v16.mdx (via sys_file (literal, a string literal in callerMayReadSysFile))
• content/docs/releases/v17/17-0.mdx (via sys_file (literal, a string literal in callerMayReadSysFile))
• content/docs/releases/v17/17-5.mdx (via sys_file (literal, a string literal in callerMayReadSysFile))
• content/docs/releases/v17/index.mdx (via sys_file (literal, a string literal in callerMayReadSysFile))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

• 1 anchor(s) matched too much of the corpus to be a work list: ObjectQL (symbol, 72 pages)
• 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 — 17 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 e22defb13c171900e2c1c54d1d15c24ed85fe91b → packageMentionDocs.

Which tree this was computed on

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

node scripts/docs-audit/affected-docs.mjs --json e22defb13c171900e2c1c54d1d15c24ed85fe91b

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

[objectstack-fleet]

Contract review

Served-tier: TIER_DEFAULT
Head-sha: df035c8343a18c3197f7112454e30a6272a6b13e
Local-runs: none

What this record read:

• card file-field hydration: every record read by a user without sys_file read logs a security WARN 'Access denied: operation find on object sys_file', though the reader never asked for sys_file and the response is correct #24335's body and comments: triage 6250776423, claim 6257482074, dispatch 6257534748, and os-dev-report 6258562795, read as claims;
• the PR body, and the net diff against the merge base e22defb13c, read with git diff / git show on fetched refs: engine.ts +106/−34, the objectql pin, the dogfood pin and the changeset;
• the check-runs on this head;
• beyond the diff: plugin-security's canReadObject (security-plugin.ts about :5976) and its docblock, read at the head.

① Derived judgments

The ask: right, and it only narrows. resolveFileReferences now asks callerMayReadSysFile(execCtx) before it issues the caller's sys_file read.

• The ask calls the registered security service's canReadObject('sys_file', caller), through the engine's existing resolveReadableIdsSecurity slot. The caller's envelope is stripped of its operation-private __ keys, as readParentDerivedFiles already does for its verdict.
• true reads as the caller, exactly as before, so the middleware still decides and still logs.
• Unasked reads as before: no usable service, a contract without canReadObject, or a throwing ask.
• Any other answer serves the refused arm, which is the answer that read's refusal produced.

So no reader gains a file it could not read before. A reader canReadObject refuses where the middleware would have admitted is served less, not more. The dev's one such arm is publicFormGrant, which is not mirrored, and a form targeting sys_file is not a realistic declaration.

canReadObject mirrors the middleware's object-level gate, arm for arm, read at the head:

• isSystem admits, so system reads keep their hydration;
• a principal-less context denies, as ADR-0096 D5 strict mode does in the middleware;
• empty permission sets deny;
• unresolved posture denies;
• then the capability gate, the allowRead grant, and the ADR-0090 delegator.

It does not log on a denial. On an internal error it logs at error and denies, which the engine reads as the refused arm: narrowing again.

The refused arm: moved verbatim. serveRefusedFileHydration is the old inline arm unchanged:

• the field-owned verdict (readParentDerivedFiles, objectql: a file field's metadata follows the parent-derived verdict the download door applies — hydrate a field-owned file for a reader refused sys_file read (ruling B on #22624) #22637), per element and per record;
• { id, metadataRefused: true } for every other id;
• the debug line.

Both the up-front refusal and the existing PERMISSION_DENIED catch call it, so the two paths cannot drift.

Measured, on a booted composition, on one boot:

• a member's by-id read: denials 1 → 0, body byte-identical, file hydrated;
• a member's list read: 1 → 0, byte-identical;
• a sys_file reader's by-id and list reads: 0 → 0, byte-identical;
• the member's direct GET /data/sys_file/ID: still 403 PERMISSION_DENIED with its one denial;
• the ask costs about 6.4 µs (a cached permission check, no store read), once per request, never per row, against the roughly 1.2 ms refused read it replaces.

The pins: real controls. The objectql pin adds 7 cases to engine-file-hydrate-refused.test.ts on its existing driver double. The booted pin counts WARNs and compares bodies. Ablating the ask turned the WARN-count pins red, 2 of 5; the restore read back as the HEAD blob.

② Semver level

One patch changeset for @objectstack/objectql, Clause-②: no. Every served body and every refusal is unchanged; one access attempt that logged a denial is no longer made. Right.

③ Boundary flags

• Deviations, all accepted:
  • the detached shared checkout;
  • the two private helpers, inside the claimed engine.ts surface;
  • the reused driver double;
  • the model-free trailers;
  • step pushes on the one branch;
  • two repo-wide families NOT MEASURED locally (check:query-options-erasure, check:type-check-debt, a container kill and timeouts), declared to CI. Their CI lanes are this record's measure: Lint · scoped · query-options erasure and Type Check · debt ledger are green on this head.
• open_questions: both accepted.
  • A, ask before reading: engine-only, plugin-security untouched.
  • A, a throwing ask reads as the caller: it never widens, and B would change a served body on a broken service.
• out_of_scope_findings: the publicFormGrant asymmetry is unreached on any realistic declaration; noted, not filed.
• Cross-lane: the dogfood file is domain:cli's; the seat declares it before the queue.
• CI at this record: Test Core 1/6–6/6 are still running on df035c8, and every other check is green or a rostered skip. The ACCEPT queues the PR behind them; auto-merge waits on every required check.

Implemented-by: claude/issue-24335-file-hydration-no-warn
Reviewed-by: session_01JtSQQ3EWsbNPzyYMug1tXy

VERDICT: PASS

---

Generated by Claude Code

[objectstack-fleet]

席位核对 · domain:engine seat 1 · session_01JtSQQ3EWsbNPzyYMug1tXy · 2026-10-19T03:03Z · ACCEPT

Head: df035c8343 (the ask, the extracted refused arm, the pins, then a merge of main). Card #24335 (p2, area:files), claim 6257482074, dispatch 6257534748. Dev report: 6258562795.

Item	Reading
Shape	Draft PR → main. The body opens Fixes #24335. 4 files, +541 / −39. Not governed (check-governed-merges.mjs --pr 24434: 0 of 4 paths hit the register).
Scope	packages/objectql/src/engine.ts: resolveFileReferences asks callerMayReadSysFile (the security service's canReadObject, through the existing slot) before the caller's sys_file read. The refused arm moves verbatim into serveRefusedFileHydration, shared with the PERMISSION_DENIED catch. The objectql pin and a dogfood pin, declared to domain:cli. One patch changeset. plugin-security is untouched.
Seat's own read	canReadObject at the head admits isSystem, denies a principal-less context and empty sets, and mirrors the middleware's object-level arms. It does not log a denial. So the ask only narrows, and system reads keep their hydration.
Measured	On one boot: a member's by-id and list reads go from 1 denial WARN to 0, with byte-identical bodies. The direct sys_file read is still 403 with its one denial. A sys_file reader is unchanged. The ask costs about 6.4 µs per request, never per row.
Ablation	Removing the ask turned the WARN-count pins red, 2 of 5. The restore read back as the HEAD blob.
Review	TIER_DEFAULT record of record 6258712209 on this head: PASS, in-seat.
Declaration	Clause-②: no on the claim, the PR body and the changeset.
Gates	Dev: 74 derived, 72 run with exit 0, 2 NOT MEASURED. Those two (check:query-options-erasure, check:type-check-debt) are repo-wide scans killed or timed out locally; their CI lanes are green on this head. Typecheck exit 0 for objectql and the dogfood package.
CI	At this read on df035c8343: everything green or a rostered skip, except Test Core 3/6 and 4/6, still running. Auto-merge waits for them.

Disposition:

• open_questions: both accepted. A, ask before reading. A, a throwing ask reads as the caller, so it never widens.
• deviations: all accepted, as the record's ③ judges them.
• out_of_scope_findings: the publicFormGrant asymmetry narrows only, and is unreached; noted, not filed.

Landing: ordinary queue (pr_ready + automerge_enable through the relay), behind the two running Test Core shards. Fixes #24335 then closes the card.

---

Generated by Claude Code