[objectstack-fleet]

Fixes #22283
Clause-②: no (narrowing)

Setup's File Storage page renders a "Limits" group (max_upload_mb, presigned_ttl, session_ttl) and an admin's save persisted it, but nothing read it. This PR implements triage's direction ("honour the three keys at the doors that own them"; implement, not retire): StorageServicePlugin reads the group on every settings pass and every upload door honours it, on the plugin's own mount and on a host's mountStorageRoutes mount.

What changed

• storage-limits.ts (new, package-internal logic). The one place the three keys are READ out of a getNamespace('storage') payload (readStorageLimits) and RESOLVED against a mount's own options (resolveStorageLimits). A numeric string is admitted because the settings service admits it for a number specifier; a present value that is not a positive number is not applied and is logged at warn naming the key and value.
• storage-service-plugin.ts. applySettings reads the Limits group on every pass, AHEAD of the adapter gate (that gate returns early when no adapter key is authored, and a save that touched only a limit must still land). The snapshot is held on the SwappableStorageService the plugin registers as storage, and composeStorageRoutes binds it for the doors from that service, so both mounts read it from the one place it is written, the same path an adapter save already takes. One info line names the snapshot when it changes.
• storage-routes.ts. Each request resolves the limits once (never hoisted to registration), so a save reaches the next request without a restart.
  • Size gate, before any row is written or byte stored: presigned door (declared size), chunked start (declared totalSize), local raw PUT (declared content-length before the body is read, then the bytes read), chunk door (bytes held so far plus this chunk, the same two ways).
  • The chunk door counts the latest recorded size per chunk index: both adapters replace a re-sent part, so a retried chunk is not counted twice. Each stored parts entry now records its size; a session whose parts predate that is judged by its running uploaded_size, the upper bound.
  • TTLs: presigned upload URLs and non-gated download URLs take the resolved presignedTtl; new chunked sessions take the resolved sessionTtl. Already-issued URLs and sessions keep the lifetime stamped at issue.
• swappable-storage-service.ts: setLimitsSnapshot() / getLimitsSnapshot(). index.ts: type exports StorageLimitsSnapshot, StorageLimitReading. mount-storage-routes.ts: option docs. README section, changeset.

Measurements (H1 to H5 from the dispatch)

• H1 holds. At 238222d8, non-test readers outside service-settings: max_upload_mb 0, presigned_ttl 0, session_ttl 0; controls in the same manifest local_root 4 files, s3_bucket 1 file. A settings change reaches the plugin through settings.subscribe('storage', ...), which re-runs applySettings; the three keys now ride that path.
• H2. Manifest defaults vs the built-in defaults: presigned_ttl 3600 = 3600; session_ttl 86400 = 86400; max_upload_mb 100 vs no limit. So the one observable change with nothing saved is the 100 MB (104,857,600 bytes) cap; the changeset states it.
  • Precedence: the seat's lead is falsified, and the measured behaviour is followed. The adapter keys do NOT let the constructor win over a save: an authored save rebuilds the adapter over the constructor's (buildAdapterFromValues, "settings value wins over any constructor-provided local.rootDir"), while a manifest default never moves it (the authored-source gate). Followed per key: saved value (admin save or env override) wins over the host option (presignedTtl / sessionTtl on the constructor or on mountStorageRoutes), which wins over the namespace default, which wins over the built-in default. max_upload_mb has no host option.
• H3, the code: the lead PAYLOAD_TOO_LARGE is not usable inside the fence. The ledger lists it under @objectstack/rest only; @objectstack/service-storage's row does not, so stamping it here would make check:error-code-provenance red, and the row lives in packages/spec (fenced out). The refusal is 413 with the standard member the platform itself derives for a 413 (standardErrorCodeForHttpStatus(413) is VALIDATION_ERROR; the catalog names no 413 member). No code was added. The message names the measured size, the limit in MB and bytes, and the setting key.
• H3, the doors. There is no single-request multipart door in registerStorageRoutes; the single-request path is presign plus the local adapter's raw PUT. On S3 the presigned PUT goes straight to the bucket, so that upload is judged by its declared size only (Acceptance notes).
• H4, H5: pinned below.

Each door, before and after (status, code)

Door	Before (no reader)	After, over the resolved limit	Stored on refusal
POST upload/presigned (declared size)	200, pending sys_file row, URL minted	413 VALIDATION_ERROR	nothing: createFile and getPresignedUpload not called
POST upload/chunked (declared totalSize)	200, file + session rows, backend multipart	413 VALIDATION_ERROR	nothing: createFile, createSession, initiateChunkedUpload not called
PUT _local/raw/:token (body)	200, bytes stored	413 VALIDATION_ERROR (by content-length before reading, and by bytes read)	nothing: upload not called, key absent on disk
PUT upload/chunked/:id/chunk/:n (held + chunk)	200, chunk stored	413 VALIDATION_ERROR (same two ways)	nothing: uploadChunk not called, uploaded_size unchanged

The Before column is read from main's code (no reader of the key) and from ablations A1 to A4 below, where each door with its check removed answers 200 to the same over-limit request. At exactly the limit each door answers 200 (control in the same test). With no settings namespace bound (bare kernel, bindToSettings: false) no door limits (control: a 1 GiB declared size answers 200).

TTLs: with nothing saved, presigned URL 3600 s and session 86400 s before and after. With a saved presigned_ttl 120 and session_ttl 600: before 3600 / 86400 (saved value unread); after 120 (expiresIn and the token's exp, upload and non-gated download URLs) and 600 (expiresAt). A session issued before a save keeps its original expiresAt.

Tests (final head 46d7554dc8, origin/main 799eb000c7 merged in)

• pnpm --filter @objectstack/service-storage exec vitest run --maxWorkers=2: 44 files, 736 passed; this PR adds 19 of them (18 in the new storage-limits.test.ts, 1 in the envelope file).
• pnpm --filter @objectstack/service-storage typecheck: exit 0, including check:test-typecheck: OK (both tsc programs list all 44 test files, the new one included, counted with --listFiles).
• Dogfood, real boot (storage-upload-limits.dogfood.test.ts, 2 cases; re-run at the final head with field-file-collection, attachments-permission-matrix and route-ledger-live-mount-parity: 34 passed, 1 declared skip; @objectstack/dogfood typecheck exit 0): nothing saved enforces 100 MB and 3600 s; PUT /api/settings/storage {max_upload_mb: 1, presigned_ttl: 120} reaches the doors without a restart, the presign refuses 1 MiB + 1, the URL carries 120 s, and the raw PUT refuses a 1 MiB + 1 body and accepts exactly 1 MiB. 2 passed.
• Consumer sweep at 73ce441fe8 (before the second merge), direction ...@objectstack/service-storage (downstream), storage-touching files only: organizations 2 wall files 20 passed; plugin-dev 9 files 86 passed; cli unit tier, 4 storage files, 32 passed (its integration tier is declared to CI); dogfood, the 9 storage-touching files plus the new one, 93 passed, 1 skipped (the declared enterprise-package skip).
• storage-limits.test.ts sections: section 1, each door refuses over the limit with nothing stored, plus the retry and legacy-session chunk cases; section 2, TTLs and the precedence table; section 3, the plugin end to end through applySettings (defaults hold, saved values reach the doors, a save after boot reaches the next request while an issued session keeps its deadline, constructor TTL vs saved, bindToSettings: false control); section 4, mountStorageRoutes honours the snapshot and resolves the TTL against its host option. error-envelope.conformance.test.ts gains the 413 case.

Ablations (each committed first; restore proven against HEAD; run at 071760b844..102ce46155, which the two main merges did not touch)

Mutations went through scripts/ablation-replace.mjs (anchor must hit once; blob change and restore proven on disk; git diff HEAD empty after every leg). The unit pins import src/ relatively, so no build or dist preflight is involved there.

Leg	Mutation	Red
A1	presign size check removed	5: presign door, envelope 413 case, defaults-hold, saved-values, host door
A2	chunked-start check removed	2: chunked start, save-after-boot
A3 / A3b	raw PUT bytes check / content-length pre-check removed	1 each
A4 / A4b	chunk bytes check / content-length pre-check removed	1 each
A5	plugin no longer stores the snapshot	4 (section 3 except the bindToSettings: false control)
A6	composition no longer binds the snapshot	5 (section 3 and section 4)
A7	saved value no longer beats the host option	2
R1	chunk door counts the running total again	1: the retry case
R2	legacy-session branch removed	1: the legacy case
D1 (dogfood, through dist/)	size gate answers "within" for everything; built; ablation-dist-preflight marker present in dist/index.js and dist/index.cjs	2 of 2 dogfood cases ("expected 200 to be 413"); restored, rebuilt, preflight --absent exit 0, rerun 2 passed

D1's first attempt was void and is not counted: its marker was a comment (stripped by the bundler) and its replacement broke the DTS build, so dist/ never carried it. It was redone with a string-literal marker that type-checks.

Gates

node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack at 46d7554dc8: 71 commands, the same list as at 73ce441fe8 and 102ce46155. All were run at the final head, plus pnpm --filter @objectstack/spec run check:error-code-provenance (the reason for the code choice). Verdicts are in the dispatch report on the card. The error-envelope and code families (check:route-envelope, check:dispatcher-error-vocabulary, check:error-code-provenance) are green.

Lint, narrowed and proven: eslint --no-inline-config --format json over all 11 changed paths at 46d7554dc8. eslint's own config lints 9 of them and ignores the two markdown files ("no matching configuration"). Result: 9 linted, 0 errors, 0 warnings. eslint.config.mjs enables no type-aware linting (no parserOptions.project, no projectService), so this diff cannot move the verdict of an untouched file. The full pnpm lint run is CI's.

Acceptance notes

• S3 presigned uploads are judged by declared size only. The bytes go to the bucket directly; binding the size into the signature needs a StorageUploadOptions field in the spec contract (fenced out here). The local adapter's byte door judges real bytes. Not filed: not measured against a live bucket.
• Pre-existing: the chunk door's uploaded_size / uploaded_chunks double-count a retried chunk index. Measured on this branch's build with no limit: a 1 MiB session whose 600 KiB chunk 0 is sent twice reports uploadedSize 1228800 and percentComplete 100 while holding 600 KiB. This PR fixed only the part it touched: the size limit no longer counts a retry twice (without that fix the retry was refused 413 while holding 600 KiB). The progress accounting itself is unchanged and is handed to the seat as a finding.
• The commit door (POST upload/complete) does not re-measure stored bytes; the declared size was judged at presign.
• Pre-existing, untouched here: a resumed chunked upload can commit without its earlier chunks. Measured on this branch's build through the doors, in the order the SDK's resumeUpload drives them (progress, then the chunks from uploadedChunks on, then completion listing only those parts): a 2-chunk upload whose chunk 0 (5 MiB) was stored in the first pass commits with 200 and size 5242890 while the stored file is 10 bytes. The completion door assembles only the parts the request lists. Handed to the seat as a finding.
• plugin-email's inbound attachment storage writes through storage.upload server-side; it is not an upload door and is not capped.
• Out of the fence and untouched: which organization an upload belongs to, the uploader-ownership checks, the organization-change answers, packages/spec, the settings manifest.

Seat's append (domain:services seat 1, #6021), carried verbatim from the dev's round-2 report 6063587901 (with the dev's one stated correction: 25 to 32 minutes); the dev never edits a PR body.

Round 2 (seat review, R1)

• R1: check:error-status-conformance was red on 46d7554dc8. Per the ruling, this PR ships 413 VALIDATION_ERROR (option A). The switch to PAYLOAD_TOO_LARGE is carried by spec(error-code-ledger), service-storage: the upload size refusal (PR #22311) answers 413 VALIDATION_ERROR; register the existing PAYLOAD_TOO_LARGE under @objectstack/service-storage and stamp it, before the release that ships #22311 #22314. The 413 is now documented as an exception to the code's 400, mirroring how MISSING_REQUIRED_FIELD documents its 422.
  • content/docs/api/error-catalog.mdx: a callout in the VALIDATION_ERROR section, and a 413 exception row in the HTTP Status Quick Reference ("this row is an exception to the 400 row, not a second home for the code").
  • content/docs/protocol/kernel/error-handling.mdx: **HTTP Status:** 400 — with one documented exception, which answers **413** (see below), a "the one 413" bullet under Where it comes from, and a 413 row in the HTTP Status Codes table.
  • Every added line names the storage upload doors and max_upload_mb, so the switch removes exactly these lines. Once VALIDATION_ERROR is no longer emitted at 413, the gate's direction B goes red on any line left behind.
• Which page the gate needs. Measured at 736713afc8 with proven-restore ablations: either page's claim is enough on its own.
  • Catalog row removed: green, 29 pairs.
  • Protocol status line reduced to 400: green, 29 pairs.
  • Both removed: red, 1 finding, 28 pairs.
  • Before the docs (46d7554dc8) the gate was red with the CI finding. After: ✓ every derivable runtime status is documented, and every documented status is reachable, 29 (code, status) pairs.
• Why the derivation did not name this gate. dispatch-gates places check:error-status-conformance only by four file literals: errors.zod.ts, the two doc pages and its baseline.
  • The gate walks packages/** through const SCAN_ROOT = 'packages' (scripts/check-error-status-conformance.mjs:222, walked at :2099). That is a bare single-segment literal, and the hint extractor refuses those by design.
  • So for a diff under packages/** the gate sat in the artifact-roster block, silent and outside the 71 commands. With this round's doc paths it is matched, and it is now one of the 97.
  • Reported to the seat as a finding; no gate added.
• CI.
  • On 46d7554dc8, Test Core (1/6) was cancelled at 15:20:41 when the round-2 push superseded the run. It had run 19 minutes; the shard takes 25 to 32 minutes on recent main runs. The aggregate Test Core then reported a missing shard attestation, not a test failure.
  • On 736713afc8: Lint & Repo Gates, TypeScript Type Check, Build Core, Dogfood Regression Gate, Temporal Conformance and Governed Surface Queue Guard succeeded, as did Test Core 2 to 6. Test Core (1/6) was still in progress at report time.
• Local verification at 736713afc8.
  • Derivation: 97 families (the docs added 26); all run, plus check:error-code-provenance, 98 of 98 exit 0. --ran reconciliation: 97 of 97, 0 NOT-MEASURED.
  • service-storage: 736 passed. Typecheck: exit 0. Dogfood storage-limits file: 2 passed.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/service-storage, touching 46 documentable anchor(s). ⚠️ 2 changed file(s) yielded no anchor (packages/services/service-storage/README.md, 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.

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

• content/docs/api/client-sdk.mdx (via VALIDATION_ERROR (literal, a string literal in UPLOAD_TOO_LARGE_CODE))
• content/docs/api/error-catalog.mdx (via VALIDATION_ERROR (literal, a string literal in UPLOAD_TOO_LARGE_CODE), max_upload_mb (literal, a string literal in LIMIT_KEYS; a string literal in describeStorageLimits))
• content/docs/api/error-handling-client.mdx (via VALIDATION_ERROR (literal, a string literal in UPLOAD_TOO_LARGE_CODE))
• content/docs/api/error-handling-server.mdx (via VALIDATION_ERROR (literal, a string literal in UPLOAD_TOO_LARGE_CODE))
• content/docs/api/plugin-endpoints.mdx (via chunkIndex (symbol, a field of interface StoredChunkPart), storage.uploadPart (sdk, the route ledger binds it to PUT /api/v1/storage/upload/chunked/:uploadId/chunk/:chunkIndex), uploadPart (sdk, the bare tail of client method storage.uploadPart, bound to PUT /api/v1/storage/upload/chunked/:uploadId/chunk/:chunkIndex))
• content/docs/automation/jobs.mdx (via VALIDATION_ERROR (literal, a string literal in UPLOAD_TOO_LARGE_CODE))
• content/docs/automation/webhooks.mdx (via VALIDATION_ERROR (literal, a string literal in UPLOAD_TOO_LARGE_CODE))
• content/docs/data-modeling/drivers.mdx (via VALIDATION_ERROR (literal, a string literal in UPLOAD_TOO_LARGE_CODE))
• content/docs/kernel/contracts/storage-service.mdx (via eTag (symbol, a field of interface StoredChunkPart))
• content/docs/kernel/runtime-services/storage-service.mdx (via eTag (symbol, a field of interface StoredChunkPart))
• content/docs/protocol/kernel/error-handling.mdx (via VALIDATION_ERROR (literal, a string literal in UPLOAD_TOO_LARGE_CODE), max_upload_mb (literal, a string literal in LIMIT_KEYS; a string literal in describeStorageLimits))
• content/docs/protocol/objectql/types.mdx (via VALIDATION_ERROR (literal, a string literal in UPLOAD_TOO_LARGE_CODE))
• content/docs/ui/forms.mdx (via VALIDATION_ERROR (literal, a string literal in UPLOAD_TOO_LARGE_CODE))

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

• content/docs/releases/v17/17-1.mdx (via VALIDATION_ERROR (literal, a string literal in UPLOAD_TOO_LARGE_CODE))
• content/docs/releases/v17/17-5.mdx (via VALIDATION_ERROR (literal, a string literal in UPLOAD_TOO_LARGE_CODE))
• content/docs/releases/v17/17-6.mdx (via VALIDATION_ERROR (literal, a string literal in UPLOAD_TOO_LARGE_CODE))
• content/docs/releases/v17/17-7.mdx (via VALIDATION_ERROR (literal, a string literal in UPLOAD_TOO_LARGE_CODE))

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

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

Which tree this was computed on

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

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

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