fix(service-storage): a file field's accept/maxSize refusal answers 400 ERR_FILE_CONSTRAINT

[objectstack-fleet]

Fixes #21730
Clause-②: no

What changed

FileConstraintError (packages/services/service-storage/src/file-reference-lifecycle.ts) declares status = 400, as FileFieldBulkWriteError in the same file already does. It also carries field and constraint ('accept' | 'maxSize') as members, set by the constructor, and both throw sites in assertFileConstraints pass them. The constructor is now new FileConstraintError(field, constraint, message), and the FileConstraint type is exported beside the class. The message text is byte-identical.

A file field's accept / maxSize refusal now answers 400 ERR_FILE_CONSTRAINT with a sentence naming the field and the constraint. Before, it answered the sanitised 500 INTERNAL_ERROR. The accept set does not change: the same files are refused, and a refused write still persists no row and claims no file.

Measured at the /api/v1/data door

Real stack (bootStack + StorageServicePlugin), object ffc_doc with doc: { type: 'file', accept: ['.pdf'], maxSize: 10 }, sys_file rows seeded under a system context.

write	before (ff29410e)	after (415514d0)
POST, text/plain file	500 {"error":"Internal server error","code":"INTERNAL_ERROR"}	400 {"error":"File type 'text/plain' is not permitted by the accept list declared for 'doc' (.pdf)","code":"ERR_FILE_CONSTRAINT","object":"ffc_doc"}
POST, 5005-byte PDF	500, same body	400 {"error":"File exceeds the maximum size declared for 'doc' (5005 bytes > 10 bytes)","code":"ERR_FILE_CONSTRAINT","object":"ffc_doc"}
PATCH onto the 5005-byte PDF	500, same body	400, same body as the POST
POST, 6-byte PDF (control)	201	201

Read-back on both sides: neither refused POST wrote a row, and no refused write claimed its sys_file (ref_object / ref_id / ref_field stay null).

The PM's mechanism hypotheses, measured

• H1 holds. ERR_FILE_CONSTRAINT is registered at packages/spec/src/api/error-code-ledger.zod.ts:506. No ledger edit.
• H2 holds. The 400 body carries exactly the keys error, code and object. field and constraint are declared on the error, but the declared-status passthrough (packages/types/src/data-error-classification.ts, 4xx arm of classifyDataError) forwards only the bounded message, the narrowed code and the route's object. The exported mapDataError wrapper can add a producer-marked userMessage, and this error sets none. So on the wire, the field and the constraint are named by the message only. Triage's direction asked for members "the thrown-error resolver forwards". That half is not met, because no such member exists without a packages/types edit, and this card was fenced away from that file. See Acceptance notes.
• H3 holds. Both messages reach the body byte-identical (error === thrown message for accept, maxSize and the update). The 4xx arm strips only a leading restatement of the producer's own code, which this message has none of. It then applies the 500-character truncation bound. No leak heuristic runs on this arm.
• H4 holds. Create and update reach the same throw site (applyCopyOnClaim, called from both beforeInsert and beforeUpdate). Both are pinned, at the unit seam and at the door.

Tests

• packages/services/service-storage/src/file-reference-lifecycle.test.ts: the accept and maxSize create refusals and a new update refusal each assert { code: 'ERR_FILE_CONSTRAINT', status: 400, field: 'image', constraint }, that the message names the field, and that no row was written or file claimed. 51/51 pass. The whole @objectstack/service-storage suite passes 634/634 (41 files), and typecheck (including check:test-typecheck) exits 0. Both at 9251e230.
• packages/qa/dogfood/test/file-field-constraint-refusal.dogfood.test.ts (new): the door-level pin from the table above, in 5 cases. Both refusals, the update refusal, the small-PDF control, and an update-onto-a-permitted-file control. Each refusal asserts code and status and reads back the rows and the sys_file ownership columns. 5/5 pass, at 415514d0 (the main merge that followed brought only packages/cli files). The dogfood tsc --noEmit exits 0 and its program lists this file.
• Ablation (committed fix first, so restore points at HEAD). I planted readonly ablation21730 = true; in place of readonly status = 400; on FileConstraintError, using scripts/ablation-replace.mjs (anchor 1 → 0, blob 632a803a → 487a00f9). Then I rebuilt service-storage. ablation-dist-preflight proved the marker present in 2 built files. Results:
  • Unit: 3 failed / 48 passed. The three refusal cases failed with expected Error: File exceeds the maximum size decl… to match object { code: 'ERR_FILE_CONSTRAINT', …(3) }.
  • Dogfood: 3 failed / 2 passed. The three refusals failed with {"error":"Internal server error","code":"INTERNAL_ERROR"}: expected 500 to be 400. Both controls stayed green.
  • Restore: blob after restore 632a803a equals HEAD, git diff HEAD is empty, the whole-tree git status --porcelain is empty, and the rebuild's preflight in --absent mode shows the marker absent from all 6 built files. The unit (51/51) and dogfood (5/5) re-runs passed.
  • The ablation exercised the status assertions. The no-row read-backs were not ablated separately, because no product mutation answers 400 and lands the row. What shows the readers can see a landed write is the control cases: the same rowsNamed / owner readers return the row and its claimed file.

Gates

node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack at 9251e230 derived 70 commands. I ran every one, recording each exit code. --ran reports: 70 derived famil(ies) accounted for — 68 run, 2 NOT-MEASURED (2 DERIVED from a recorded exit 3).

• NOT MEASURED: pnpm check:dual-build-cjs-loads, reason: PREREQUISITE NOT MET, because 33 packages outside this diff's closure have no dist/. Supplementary reading: require() of service-storage/dist/index.cjs and import() of dist/index.js both load, and each constructs a FileConstraintError with status: 400 and both members.
• NOT MEASURED: pnpm check:i18n, reason: PREREQUISITE NOT MET (unbuilt config imports). This diff touches no translation bundle or label.
• node scripts/check-plugin-teardown-shape.mjs --self-test first exited 3, because its pinned fixture commit was absent from this shallow clone. It exited 0 after git fetch --depth=1 of that commit.

Acceptance notes

• QA checklist clause, routed to the next run, not edited here. docs/qa/platform-checklist/areas/attachments-storage.json, item attachments-storage.field-accept-maxsize-server-enforced, carries a knownGap and clause 2. Both predict the sanitised 500 and say a measured 4xx carrying ERR_FILE_CONSTRAINT means "revise this clause with the measurement". The FOLLOW-UPS.md row D13 describes the same 500. The item's own clause routes that revision to the next QA run. The message prose that clause greps ('exceeds the maximum size declared for', 'not permitted by the accept list declared for') is unchanged.
• The field and the constraint are on the wire through the message only. That is what the door forwards today (H2). Forwarding field / constraint as structured body members would take a packages/types change (an ERR_FILE_CONSTRAINT arm in structuredCodeAnswer, or a generic declared-4xx detail channel). That file belongs to another lane, so the seat routes it. Nothing measured here reads such a member.
• Observation, not filed: a declared-4xx refusal at the data door still prints [REST] Unhandled error with a stack (logUnexpectedRouteError treats only 403/404/409/502/503 and a few query codes as expected). This refusal shares that with FILE_FIELD_BULK_WRITE_REFUSED and every hook-declared 400. It is log noise only, and the wire is unaffected. Carrier: none.
• Observation, not filed: content/docs/data-modeling/field-types.mdx (Media Types) says file constraints "are configured at the storage-provider layer, not on the field". accept / maxSize have been declared on FieldSchema and enforced on write since 17.0. This was already false before this change, which does not touch it. Carrier: none.
• The changeset is patch. The exported FileConstraintError constructor gains two leading parameters. The only constructor in the repository is the module's own throw sites.

Patch round 1

Appended by the seat (domain:services#1, session_011K3zqE8Pv1Evw5hc8tZCnN) from the dev's patch-round report 5981408643, after seat review 5981327964.

• content/docs/data-modeling/field-types.mdx, "Media Types" paragraph (f18345a4). The sentence saying file constraints "are configured at the storage-provider layer, not on the field" is replaced. The paragraph now says that accept and maxSize apply to the media family (file, image, avatar, video, audio), and what each one means, following the spec's own .describe() text: accept is the permitted upload types as MIME types or extensions, offered to the file picker and enforced on write. maxSize is the maximum file size in bytes, enforced on write against the stored file size. It also says a create or update whose referenced file violates either is refused with 400 ERR_FILE_CONSTRAINT, and that the message names the field and the constraint. It keeps the true half: storage itself is configured at the storage-provider layer. No other sentence on the page mentions accept or maxSize, so nothing else on the page changed.
• main merged at aa33b2e3. It brought 5 commits, and none of them touches this PR's files.
• Gates at aa33b2e3. dispatch-gates --commands derives 95 commands. The doc edit adds 25 of them, and the dev ran those 25 plus check:nul-bytes: all exited 0. The other 70 codes are the code-half results recorded at 9251e230, reused as recorded. --ran reports: 95 derived, 93 run, 2 NOT-MEASURED (check:dual-build-cjs-loads and check:i18n, each exit 3 with its prerequisite not met, unchanged from the code half), 0 UNRUN.
• Acceptance notes revision: the field-types.mdx observation above is resolved by this round.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/service-storage, touching 4 documentable anchor(s). ⚠️ 1 changed file(s) yielded no anchor (packages/services/service-storage/src/index.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

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

• content/docs/data-modeling/field-types.mdx (via maxSize (literal, a string literal in FileConstraint; a string literal in assertFileConstraints))
• content/docs/data-modeling/validation-rules.mdx (via maxSize (literal, a string literal in FileConstraint; a string literal in assertFileConstraints))
• content/docs/kernel/contracts/cache-service.mdx (via maxSize (literal, a string literal in FileConstraint; a string literal in assertFileConstraints))
• content/docs/plugins/packages.mdx (via maxSize (literal, a string literal in FileConstraint; a string literal in assertFileConstraints))
• content/docs/protocol/kernel/metadata-service.mdx (via maxSize (literal, a string literal in FileConstraint; a string literal in assertFileConstraints))
• content/docs/ui/actions.mdx (via maxSize (literal, a string literal in FileConstraint; a string literal in assertFileConstraints))

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

• content/docs/releases/index.mdx (via maxSize (literal, a string literal in FileConstraint; a string literal in assertFileConstraints))
• content/docs/releases/v16.mdx (via maxSize (literal, a string literal in FileConstraint; a string literal in assertFileConstraints))
• content/docs/releases/v17/17-0.mdx (via FileConstraintError (symbol, a top-level class), maxSize (literal, a string literal in FileConstraint; a string literal in assertFileConstraints))
• content/docs/releases/v17/17-4.mdx (via maxSize (literal, a string literal in FileConstraint; a string literal in assertFileConstraints))

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 changed file(s) yielded no anchor (packages/services/service-storage/src/index.ts) — pages documenting those are invisible to this run
• 2 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 — 7 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 ea7ff394b6d802de9ad0448130bef86d4407760d → packageMentionDocs.

Which tree this was computed on

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

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

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