docs(adr-0104): a write references only a file its writer may read - #25971

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 3d14f9ae5c7220890b0c42dfa335b469e617b7fa
Local-runs: none
Scope: docs/adr/0104-field-runtime-value-shape-contract.md + packages/services/service-storage/src/file-reference-lifecycle.ts, packages/services/service-storage/src/storage-service-plugin.ts, packages/services/service-storage/src/attachment-access-hooks.ts, packages/services/service-storage/src/storage-routes.ts (the download door's own arms), all read on main at 3761710927

Face: rules (docs/adr/**), read against the merged code the amendment describes (PR #25951, merge commit 3761710927), card #25692 and its comments, and the check-runs on this head. Adversarial read: each normative sentence of the +60 is judged on its own against the merged code.

① Derived judgments

• Status bullet (2026-10-26). Right. The claim path's single lookup (findReferenceableFile) feeds both copy-on-claim (applyCopyOnClaim, the before-hooks) and the claim (claimFile, the after-hooks); with a bound verdict and a caller, a refused file is answered as null, the same answer the organization-scoped lookup gives a row it cannot see. #25682 (e2b40a264b) is the commit that introduced that organization-scoped lookup, so the precedent citation is correct.
• Note under the 2026-07-27 worst-case table. Right. Steps 1 and 2 of the resequencing list are ownership bookkeeping and governed download, as the addendum names them; before 3761710927 the claim path asked the organization-scoped lookup and nothing else, which the merged PR body states in the same words.
• The rule ("claims or copies only a file its caller may read, by the download door's own verdict"). Right. The plugin binds buildFileReferenceReadAuthorizer into installFileReferenceHooks from the live registry; the lifecycle module decides nothing itself and both halves of the claim path ask through one function.
• "One judgement, two callers ... neither restates it." Right for the judgement: judgeFileRead is one function, called by the download door under its request-resolved context and by the claim path under the write's caller context. Its four arms are as listed: uploader (owner_id), a reader of the one owning record via readableFieldOwners (delegate or raw read, fail-closed), the organization arm for a file no record owns (#25693), any readable sys_attachment parent for an attachments-scope file. One precision point, non-blocking: the fifth item, "anyone for a public_read file", is not an arm of the shared function. The door serves a public_read file in storage-routes.ts before it asks its authorizer, and the claim path's binding mirrors that pre-judgement arm (and the door's no-user answer) in its own two lines. The per-file outcome is the same at both doors, which is what the rule promises; the sentence slightly overstates where that one arm lives. The organization arm is a summary of the wall's verdict for the posture in force, the same wording the shipped changeset uses.
• "The quiet answer." Right. A refused file leaves the id as written; nothing is claimed or copied; no new code or status is introduced. The cross-organization precedent is correctly attributed.
• "A write's own copy." Right for the stated path: a copy minted in the before-phase is remembered per write and claimed without a second question. The addendum omits the fail-safe the merged code carries when a write's two phases share no key (the copy is then judged as any unclaimed file and, if refused, left unclaimed). An omission, not a misstatement.
• "Outage." Right at the before-write gate, which every write referencing a file passes: AuthzStoreUnavailableError is re-raised by the binding, not caught by the lookup, and fails the write under the error's own code and status. Any other fault in the judgement answers as a refusal.
• "No caller, no question." Right. referencingCallerOf returns no caller for a system write or a session-less programmatic call; an anonymous session is a caller and is refused for every file but a public_read one. The system-write exemption is registered as row 47f on the system-context census. The "deliberate server-side copy runs as a system write" line is the shipped changeset's prescribed fix, restated.
• "What it qualifies" / "Why this stays inside ADR-0104." Right. The exclusive row's "duplicated bytes, recoverable" rating is left intact and gains the precondition; exclusivity and copy-on-claim are not revisited; step 1 of the resequencing still deletes nothing.
• Omission, non-blocking: the merged binding asks nothing on a kernel with no auth service, where the door binds no gate and serves every file. The addendum does not say so, but "by the download door's own verdict" covers it, since the reference rule is exactly as strong as the door there.
• No sentence of the +60 is false of the merged code. Disclosure: the text states mechanism only, and nothing in it goes beyond what the merged PR body and shipped changeset already say publicly.

② Semver level

Docs-only diff, one file under docs/adr/, nothing from any released package. skip-changeset is the right level; the changeset check on this head is green.

③ Boundary flags

• Tier H. The one path is docs/adr/**. This record is the contract-tier reading on the rules face; it does not lift the landing. The PR lands only on an authorized APPROVED review by a GOVERNED_APPROVERS account, then by the owning seat, as the PR body's acceptance note says. The PR is correctly still a draft.
• Cross-reference, optional. D3's "Authorization" bullet ("possession of a URL stops being possession of the bytes") is the clause this rule extends to a file id; the addendum does not cite it. A one-line pointer there would land a grep from that bullet on the rule, but nothing conflicts and no clause of the 2026-07-27, 2026-08-07 or 2026-09-05 addenda is contradicted.
• Precision, optional. The two non-blocking points above (where the public_read arm lives; the no-auth-service kernel) could each take one clause if the maintainer wants the ADR to match the binding line for line. Neither changes the rule.
• Check-runs on this head, read at 2026-10-26T07:02Z: 57 check-runs, all completed; 38 success, 19 skipped, 0 failed, 0 pending. Governed Surface Queue Guard, Check Changeset, Check Documentation Links and the card-claim checks are among the green ones.

Implemented-by: claude/project-thread-n8sx5h
Reviewed-by: session_01TFnDdepdwyDJeM2kJ4GtMy

VERDICT: PASS

Generated by Claude Code

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: 13d9a1adf7d301e437e4b4a650827270cf37079b
Local-runs: none
Scope: docs/adr/0104-field-runtime-value-shape-contract.md + packages/services/service-storage/src/file-reference-lifecycle.ts, packages/services/service-storage/src/storage-service-plugin.ts, packages/services/service-storage/src/attachment-access-hooks.ts, packages/services/service-storage/src/storage-routes.ts, packages/services/service-storage/src/verify-file-references.ts, packages/objectql/src/engine.ts, packages/objectql/src/hook-wrappers.ts, packages/spec/src/data/hook.zod.ts, packages/spec/src/automation/flow.zod.ts, packages/services/service-automation/src/runtime-identity.ts, packages/core/src/security/resolve-authz-context.ts, all read on main at 431f065177 (the lifecycle and plugin unchanged since 3761710927)

Face: rules (docs/adr/**). Follow-up record: 6410217722 PASSed head 3d14f9ae; this head is that head plus one wording commit (git diff 3d14f9ae..13d9a1ad, +18/-7 in the 2026-10-26 addendum). The whole +71 against main was re-read; the sentences the prior record judged are unchanged, and the judgments there stand. What follows judges the new sentences, each against the merged code. Inputs: the PR body, the diff, card #25692 and its comments, issue #26043, and the check-runs on this head.

① Derived judgments

"At the write door" (the qualifier). Right. The quiet answer is given in the lifecycle's beforeInsert / beforeUpdate and afterInsert / afterUpdate hooks, which is the record write; findReferenceableFile answers a file the caller may not read as null, the same answer the organization-scoped lookup gives a row it cannot see, and only there. The read side and the download door each answer differently (the refused marker; 403 FILE_DOWNLOAD_DENIED), so scoping the "cannot tell the two apart" statement to the write door is the precise statement, not a weaker one.

"Unless the record already owned the file, the kept id gives no reader anything through it." Right. On hydration (resolveFileReferences), an id is served by the record only through readParentDerivedFiles, whose lookup is ref_object = this object and ref_id in this result's record ids, and the hit is applied per record (hit.ownerId must equal the record's own id). A kept id names a file this record does not own, so that arm never serves it. A reader admitted to sys_file reads the row by sys_file's own rule, which is not through the record.

"A reader refused sys_file read gets the refused marker (metadataRefused)." Right. serveRefusedFileHydration marks every id its record does not own as { id, metadataRefused: true } (FileRefusedValueSchema), on both the admission-refused arm (#24335) and the read-refused arm (#6116).

"The download door judges the file by its own rule, never by this record." Right. judgeFileRead reads the file row's owner_id, then its own ref_object / ref_id, then its scope; the record holding the kept id is not an input. The door's public_read and no-user arms precede it in storage-routes.ts, as the prior record noted.

"A slot holding a file it does not own is a state that step 5's verify-references classifies as blocking." Right. Step 5's text names "a file held by a slot that does not own it" among the blocking kinds, and verify-file-references.ts puts both shapes the kept id can take, unowned_reference and foreign_owner, in BLOCKING_ISSUE_KINDS. The ADR is quoting its own step 5 accurately.

"#26043 tracks replacing this answer with a field-level refusal." Right. #26043 is open, asks for exactly that (a 400 VALIDATION_ERROR with an ADR-0114 invalid_value entry naming the field only), and names this addendum's paragraph as the text it will amend. An issue citation in an ADR is the ADR convention this file already follows.

"Everything else has a caller." Right. referencingCallerOf returns null only for a context with no session or a session marked isSystem; every other write, an anonymous session included, is a caller. This restates the merged code's own doc line.

"A flow runs as runAs: 'user' by default and is judged as the user it acts for." Right. FlowSchema.runAs is z.enum(['system', 'user']).default('user'); runtime-identity.ts builds a runAs: 'user' run's data context as the triggering user's principal (the decider after an approval decision, which "the user it acts for" covers), and its writes reach the lifecycle with that user's session.

"A hook's data operations take the context of the write that fired them by default (runAs: 'inherit'), or the triggering user's (runAs: 'user')." Right. HookSchema.runAs is z.enum(['system', 'user', 'inherit']).default('inherit'); hook-wrappers.ts installs nothing under 'inherit' (the engine-built ctx.api carries the firing write's context) and derives the triggering user's api under 'user'. The ADR's two clauses are the schema's describe text, condensed.

"An API-key caller is judged as the key's user." Right. resolveAuthzContext step 1 sets userId = keyPrincipal.userId and credential = 'api_key'; the write's session carries that user, and judgeFileRead reads context.userId. An API key resolves to no other identity.

"Only a declared runAs: 'system' run, or a write already made as the system, is exempt." Right. A 'system' flow run or hook writes under isSystem: true, which referencingCallerOf answers with no caller; so does an engine self-write, a migration or a seed. The exemption's extent is exactly referencingCallerOf's null arm, which the prior record checked against the system-context census (row 47f).

Disclosure. The new text states mechanism only: what a kept id yields on read and at the door, which identities count as callers, and a public follow-up card. Nothing in it goes beyond the merged code's own comments, the shipped changeset, and the public text of #26043.

Omissions, non-blocking. The prior record's two precision points stand unchanged (where the public_read arm lives; the kernel with no auth service). The new paragraph does not say that a sys_file-admitted reader hydrates the kept id's metadata by sys_file's own rule; "gives no reader anything through it" is true as worded, since that reader gets nothing the record adds.

No new sentence is false of the merged code.

② Semver level

Docs-only diff, one file under docs/adr/, nothing from any released package. skip-changeset holds; the Check Changeset runs on this head are skipped by that label.

③ Boundary flags

• Tier H. The one path is docs/adr/**. This record is the contract-tier reading on the rules face; it does not lift the landing. The PR lands only on an authorized APPROVED review by a GOVERNED_APPROVERS account, then by the owning seat. The PR is correctly still a draft.
• Cross-reference, optional. The files: a record write that names a file its writer may not read keeps a dangling id (the quiet answer of #25951); refuse the field instead, so no slot holds a file it does not own #26043 citation makes the addendum's quiet-answer paragraph the text that card will amend; when it lands, the "kept id" sentences here become history and should be dated, not deleted.
• Check-runs on this head, read at 2026-10-26T10:23Z: 52 check-runs; 35 success, 16 skipped, 0 failed, 1 still in progress (Test Core 1/8). Governed Surface Queue Guard, Check Documentation Links, every Lint and Type Check job and the card-claim checks are green. The verdict below is on the text against the merged code; the landing waits on every check as PD feat: Comprehensive CRM example demonstrating all ObjectStack protocol features #14 states.

Implemented-by: claude/project-thread-n8sx5h
Reviewed-by: session_01TFnDdepdwyDJeM2kJ4GtMy

VERDICT: PASS

Generated by Claude Code