fix(service-storage): answer an upload's organization change with 409 RESOURCE_CONFLICT, not an outage 500

[objectstack-fleet]

Fixes #22175
Clause-②: no

The commit door and the chunked-completion door of @objectstack/service-storage now answer an uploader whose active organization changed after starting an upload with 409 RESOURCE_CONFLICT, in the ADR-0112 envelope, with a message that names the organization change. They used to answer 500 INTERNAL with the store's data-engine outage text. The operator log gets one warning that names the cause. Which organization an upload belongs to does not change, and the tenant scope of every write is unchanged.

Rulings carried (triage 6052856225, verbatim)

• "answer with a worded 4xx that names the organization change, in the ADR-0112 envelope"
• "the operator log names the cause"
• "⛔ No change to which organization an upload belongs to: security(service-storage): three upload doors authorize by session alone, with no ownership or resume-token check on the file or upload they name (the owner-check class the #21908 ruling sent to its own card) #22046's ruling keeps the tenant scope as it is."
• "Clause-②: no. Patch changeset for the storage service."
• From the card: "⛔ No catch-all that hides a real engine failure."

What changed

• metadata-store.ts: a new module-level function, organizationOutOfWriteReach(store, row, context). It is not re-exported from the package entry, and the public face is unchanged. It answers one question about the by-id write the store would issue under context: can that write reach row? If it cannot, the function returns the organization the row was started in. Otherwise it returns null.
  • It returns null for the engine-absent stand-in, which does not scope its writes. A module-private WeakSet filled in the constructor records which stores are engine-backed.
  • It returns null when no organization is threaded. It reuses writeOptionsFor, the same rule that decides whether the write carries a tenantId.
  • It returns null for a row stamped with no organization, because the driver keeps org-less rows in reach.
  • Otherwise, a row is in reach exactly when its organization is the acting one.
  • It composes no predicate. The statement's tenant term stays the driver's.
• storage-routes.ts: a new gate, requireStartingOrganization(writeContext, rows, …). It runs right after the ownership rule from fix(service-storage)!: the upload commit, chunked-completion and progress doors act only for the uploader #22170 and before any write, so only the uploader ever reaches it. It asks the store about every row the door is about to write. When a row is out of reach, the gate logs one warn line naming the door, the upload id, the starting organization and the active one. It then answers 409 / RESOURCE_CONFLICT with a constant message that names no organization.
  • Commit door (POST …/upload/complete): it asks about the sys_file row. The write context is now bound once and passed both to the question and to updateFile, so the two cannot differ.
  • Chunked-completion door (POST …/upload/chunked/:uploadId/complete): it asks about the upload session and its file, and it asks before the expiry stamp, which is the first scoped write. The file row that the ownership rule reads is now bound to a variable rather than read inline.
• Changeset: .changeset/22175-upload-org-change-4xx.md, a patch for @objectstack/service-storage.

Code choice. RESOURCE_CONFLICT is the standard-catalog member that HTTP 409 derives, so no ledger entry and no packages/spec change were needed. The request conflicts with where the upload stands, and the caller can resolve it: the same call succeeds after switching back, and the wall pin shows this. PERMISSION_DENIED would merge this answer with the ownership rule's one refusal, and this caller is the uploader. PRECONDITION_REQUIRED (428) means the request is missing a precondition, and nothing is missing here.

Before and after, on the booted organization wall

Measured with packages/plugins/organizations: bootStack with OrganizationsPlugin and StorageServicePlugin, posture isolated, and the uploader switched through the product's own set-active door.

door	before (1e5d322c)	after (af2811c51c)
commit, organization changed	500 INTERNAL, "StorageMetadataStore: sys_file update failed against the data engine … Restore the data engine …", cause "Record … not found in sys_file"	409 RESOURCE_CONFLICT, "This upload was started in a different organization than your active one. …"; row unchanged; switching back commits it (200)
chunked completion, organization changed	500 INTERNAL, the same text for sys_upload_session	409 RESOURCE_CONFLICT; session and file rows unchanged; switching back completes it (200)
commit / chunked completion, same organization	200	200 (control)
progress, organization changed	200	200 (unchanged)

H1, measured: the scoped miss is a throw, not zero rows. The SQL driver's scoped UPDATE … WHERE id touches no row and its scoped read-back returns null. The engine then raises "Record ID not found in OBJECT", and engineOp wraps that as StorageMetadataStoreError.

Why the question lives in the store, not as a bare comparison at the door

A comparison written only at the door would also refuse on the engine-absent stand-in. The stand-in records the organization on insert but does not scope its writes, and it finishes this upload today (200). Refusing there would narrow an accept set that is published (registerStorageRoutes and StorageMetadataStore are both public), and that reads as Clause-②: no (narrowing) against the ruled Clause-②: no. A public getter on StorageMetadataStore would widen the public face instead. The module-level function changes neither, and it keeps the stand-in's answers unchanged, which is H4.

Tests

• storage-routes.metadata-outage.test.ts: a new block, an organization change is not an outage, with 14 cases on that file's existing fake engine. The double was reused and no new double was pinned.
  • At both doors: 409 with the code and first sentence, rows unchanged, and the warn line naming the upload and both organizations.
  • Same-organization control (200).
  • Same-organization real engine failure still answers 500 INTERNAL with "Restore the data engine", at both doors.
  • No active organization (200), an org-less row (200), an org-less session whose file is out of reach (409), and the question asked before the expiry write.
  • The ownership rule runs first: a non-uploader in another organization still gets 403 PERMISSION_DENIED, which says nothing about organizations.
  • The progress door is unchanged, and the stand-in is unchanged (200 from either organization).
• metadata-store.test.ts: 6 cases on organizationOutOfWriteReach.
• error-envelope.conformance.test.ts: one case for the new code, parsed against the declared envelope.
• packages/plugins/organizations/src/storage-upload-organization-change.wall.test.ts (new): the premise, both doors' negative pins with switch-back, both same-organization controls, and the progress door unchanged.

Ablation (from committed af2811c51c)

The mutation went through scripts/ablation-replace.mjs in wrap mode, run under the verify lock. It replaced the question with const started = null (marker ABLATION-22175).

• On-disk evidence: anchor count went 1 to 0, marker 0 to 1, blob fd950d45ec2a to eba43b779bd2.
• Both suites resolve the subject from src: the organizations package's vitest alias maps @objectstack/service-storage to src/index.ts, and the unit tests import relatively. So no dist leg applied.
• Wall: the 2 negative pins turned red. Each received 500 INTERNAL with the outage text, the original defect reproduced. The other 4 stayed green.
• Unit: 5 cases turned red, the conformance case among them. The fake engine does not scope, so the doors answered 200, or 410 on the expiry case.
• Restore: proven by the tool (blob equals HEAD fd950d45ec2a, git diff HEAD empty) and re-read afterwards (anchor 1, marker 0).

Gates (at af2811c51c)

• Derivation. Run from this worktree with node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack, after git fetch origin main (origin/main 13aea18959, merge base 1e5d322c1). It derived 68 commands. That is the seat's 66 plus check:dispatcher-error-vocabulary and check-dev-prereqs.mjs --self-test.
• Reconciliation. --ran was run with every exit code recorded. It printed: "68 derived famil(ies) accounted for — 67 run, 1 NOT-MEASURED (1 DERIVED from a recorded exit 3)".
• Exit 0: 67 commands. One of them, check:i18n, first answered PREREQUISITE NOT MET (exit 3). After its stated build closure, it printed: "check-i18n-bundles: OK (9 package(s) — all bundles in sync, no undeclared authoring keys)".
• NOT MEASURED: check:dual-build-cjs-loads. Its prerequisite is a whole-workspace build (33 packages have no dist/). In its place I ran a narrow probe on the only package whose source this diff touches: the rebuilt service-storage loads through require('./packages/services/service-storage/dist/index.cjs') (exit 0). The new function is absent from dist/index.d.ts. CI runs the full gate.
• Error-envelope and error-code families.
  • From the derivation: check:route-envelope passes, and check:dispatcher-error-vocabulary answered "OK — 54 unregistered code-stamping site(s), all classified".
  • From the roster families the derivation lists but cannot place: check:error-code-casing ("no unlisted lowercase error codes in 7791 scanned file(s)"), check:error-status-conformance ("every derivable runtime status is documented, and every documented status is reachable") and @objectstack/spec check:error-code-provenance (OK).
  • Also run beyond the derivation, all exit 0: check:authz-resolver, check:filter-alias-parity, check-changeset-fixed.mjs, check:tenant-chokepoint and check:durability-log-level.
• Package suites at af2811c51c. @objectstack/service-storage: 43 files, 704 tests pass. @objectstack/organizations: 11 files, 147 tests pass. typecheck exits 0 for both, with check:test-typecheck: OK for each.
• Lint, narrowed. I ran eslint --no-inline-config --format json over the 6 touched TypeScript files: files=6, errors=0, warnings=0. Population: there was no "file ignored" warning, so all 6 were linted under eslint.config.mjs. Invariance: that config never enables type-aware linting (no parserOptions.project, no typed rules), so this diff cannot change the verdict on an untouched file. The full pnpm lint is CI's.

Acceptance notes

• Same family, outside this card's two doors. These were measured on the same wall with a throwaway probe that was deleted after the run:
  • the chunk door (PUT …/upload/chunked/:uploadId/chunk/:chunkIndex), after the uploader switches organization, answers 500 INTERNAL with the sys_upload_session outage text;
  • the progress door, for a session past its expires_at, answers the same 500, because its expiry stamp is a scoped write. From the starting organization it answers 200 with expired.
  • The store question this PR adds would answer both of these scoped writes. They are reported to the seat as one finding and are not fixed here, because the dispatch fenced the two doors.
• The dispatch said the card had 3 comments. The REST read shows 2, the triage and the claim. The newest Claim: names this branch.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/service-storage, touching 8 documentable anchor(s).

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

• content/docs/api/error-catalog.mdx (via RESOURCE_CONFLICT (literal, a string literal in ORGANIZATION_CHANGED_CODE))
• content/docs/api/error-handling-server.mdx (via RESOURCE_CONFLICT (literal, a string literal in ORGANIZATION_CHANGED_CODE))

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

• content/docs/releases/v17/17-6.mdx (via RESOURCE_CONFLICT (literal, a string literal in ORGANIZATION_CHANGED_CODE))
• content/docs/releases/v17/17-7.mdx (via RESOURCE_CONFLICT (literal, a string literal in ORGANIZATION_CHANGED_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

• 1 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 7d7943dd0dfba6c98afa2200a08983ec85f9849a → packageMentionDocs.

Which tree this was computed on

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

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

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