Merge remote-tracking branch 'origin/main' into claude/issue-14059-governed-enqueue-precondition

Author: claude

.changeset/rest-passthrough-strips-declared-code-prefix.md

@@ -0,0 +1,56 @@
+---
+"@objectstack/rest": minor
+---
+
+fix(rest): every `/data` exit and the approvals door now hand the caller the human half of a declared-code-prefixed message (#13095)
+
+The 2026-08-29 ruling on #12975 made the by-id `/data` door strip the
+ADR-0111 `CODE:` prefix from the human-readable `error` string — one
+envelope semantics: `error` is human language, `code` is the machine token.
+`resolveErrorResponse`'s declared-4xx `passThroughStatus` arm is a second
+declared-4xx arm the ruling did not name, checked BEFORE the door it
+delegates to — so the same refusal read two ways depending on which route
+caught it: `PATCH /data/:object/:id` answered the bare localized sentence
+while `POST /data/:object/batch` (and every bulk/clone exit reporting
+through `handleRouteError`) and the record-share classified arm still
+shipped `FORBIDDEN: <sentence>`. Maintainer ruling 2026-08-31 (option 1):
+converge them.
+
+On-wire changes, all subtractive on message text only, all 4xx, statuses
+and `code`/`declaredCode` fields untouched:
+
+- `resolveErrorResponse`'s declared-4xx arm now applies the same
+  declared-code-anchored strip (`withoutDeclaredCodePrefix`) the by-id door
+  applies: a message opening with the producer's own declared `code`
+  followed by a colon loses that prefix — and only that prefix. A message
+  that is nothing but the prefix degrades to `Request failed`. This
+  converges the `/data` batch/createMany/updateMany/deleteMany/clone exits
+  and — because the record-share classified arm re-dresses the same
+  classification — `GET/POST/DELETE /data/:object/:id/shares*` with them.
+- The approvals door's prefix strip is now anchored to the code the row
+  answers instead of the blanket `/^[A-Z_]+:\s*/` regex (the shape #12975
+  rejected): a sentence opening with a DIFFERENT `SCREAMING_SNAKE:` token
+  than the answered code is no longer eaten.
+
+Not moved, deliberately: a declared 4xx with NO `code` keeps its message
+verbatim (the token is nowhere else on the wire); a prefix that does not
+restate the declared code is left alone; declared-5xx prose withholding is
+unchanged; the share family's bare-`Error` prefix-idiom arm already
+stripped and is untouched; an empty-string message through the passthrough
+still ships as itself (that TYPE-keyed degrade is a standing pin this
+ruling did not move).
+
+**Migration.** Consumers that parsed the `CODE:` prefix off the front of
+`error` (flat `/data` doors) or `error.message` (nested record-share
+envelope) on these routes must read the `code` field instead — it has
+carried the same token all along, with unregistered spellings demoted to
+the `declaredCode` sibling (#9232). The consumer census behind this change
+covered `objectstack`, `objectui` and `hotcrm` (re-run 2026-09-01, each
+scope with a positive control) and found zero consumers branching on the
+prefix. `objectstack-ai/cloud` was NOT MEASURED — it was unreachable from
+the implementing session — and is deliberately not reported as clean: the
+zero above is a statement about the three repos named, not about every
+deployment. An operator whose code parses the leading token off these
+routes' error text should locate and update those reads before upgrading.
+Per #13347's precedent an error-envelope shape change ships as `minor`
+with this note.

.claude/workflows/docs-accuracy-audit.js

@@ -1871,17 +1871,19 @@ jobs:
       - name: Template version-time rewriter self-test
         run: pnpm check:template-version-sync
 
-      # #4851: the docs-accuracy-audit workflow carries its default scope inline
+      # #4851: the docs-accuracy-audit workflow's default scope is a generated list
       # (a workflow script runs in a vm with no filesystem, so it cannot enumerate
-      # content/docs/ itself). Hand-kept, that list rotted in BOTH directions —
-      # 16 entries pointing at files that no longer existed after the
-      # protocol/objectos → protocol/kernel rename, and 48 existing docs missing
-      # from it — while every "FULL audit" run reported green, which is how the
-      # accuracy defects in #4781 and #4817 survived ~2 months. This regenerates
-      # the list from the filesystem and fails when the two disagree either way.
-      # It lives in this job deliberately: the change that breaks the list is a
-      # docs rename, so a `packages/**` paths filter would blind the gate to
-      # exactly its own failure mode.
+      # content/docs/ itself — the caller hands the list in). Hand-kept, that list
+      # rotted in BOTH directions — 16 entries pointing at files that no longer
+      # existed after the protocol/objectos → protocol/kernel rename, and 48
+      # existing docs missing from it — while every "FULL audit" run reported
+      # green, which is how the accuracy defects in #4781 and #4817 survived
+      # ~2 months. This derives the list from the filesystem and fails when it and
+      # scripts/docs-audit/handwritten-docs.json disagree either way; it also runs
+      # the workflow against stub agents to check the body still consumes what it
+      # is handed. It lives in this job deliberately: the change that breaks the
+      # list is a docs rename, so a `packages/**` paths filter would blind the gate
+      # to exactly its own failure mode.
       - name: Docs-audit scope is derived, not hand-kept
         run: pnpm check:docs-audit-scope
 

.github/workflows/lint.yml

@@ -301,15 +301,15 @@ localStorage / auth gotchas.
     land, split the governed files into their own PR. **Those four lift only for an authorized approval pinned to the
     current head** (2026-08-27; guard 2026-08-28): APPROVED, by an account in `GOVERNED_APPROVERS`
     (`scripts/pm/check-governed-queue-guard.mjs`), `commit_id` = that sha — then the queue lands it, re-validating as
-    it merges, and any later push expires it. Even a **pure-regeneration** PR requests its pinned approval proactively,
-    before queueing — the queue-time leg installs no dependencies and never evaluates the byte-equality lift
-    (2026-08-29). Unpinned, the maintainer's bypass direct merge (人工直合) is the only landing. ⛔ **No agent seat
-    submits an approving review on a governed-surface PR, under any account** — an authorized account is
-    agent-operated too. Nothing else substitutes: under #13 an accepted ADR *is* the decision, so merging one is the act
-    of adopting a governance position — the one class of change about which "CI is green" carries no information at
-    all (a thorough, fully-green ADR draft has been closed by the maintainer on demand grounds no gate could evaluate).
-    The other surfaces are reserved for a reason of the same shape, spelled out in the audit header below; the published
-    catalog also lands in codebases this repo cannot see.
+    it merges, and any later push expires it. Hand-authored governed content needs that approval; a PR whose only
+    governed paths are register rows the queue leg regenerates byte-exact clears with zero approvals (2026-09-01) — an
+    uncertified recompute, drift or a hand-authored sibling keeps it governed. Unpinned, the maintainer's bypass direct
+    merge (人工直合) is the only landing. ⛔ **No agent seat submits an approving review on a governed-surface PR,
+    under any account** — an authorized account is agent-operated too. Nothing else substitutes: under #13 an accepted
+    ADR *is* the decision, so merging one is the act of adopting a governance position — the one class of change about
+    which "CI is green" carries no information at all (a thorough, fully-green ADR draft has been closed by the
+    maintainer on demand grounds no gate could evaluate). The other surfaces are reserved for a reason of the same
+    shape, spelled out in the audit header below; the published catalog also lands in codebases this repo cannot see.
 
     **Already armed or queued when you read this?** ⚠️ Converting the PR back to **draft** is the only action that
     reliably removes it from the merge queue; `disable_pr_auto_merge` alone drops the arming but **not** queue

AGENTS.md

@@ -6481,23 +6481,46 @@ export class SecurityPlugin implements Plugin {
       // every later by-id write through the stored-row leg below. The residual
       // envelope asymmetry is confined to exactly those shapes.
       //
-      // [#8959, re-measured 2026-08-16] "Confined" is still NOT a publish-time
-      // bound today, though the reason has moved on from #8959's finding. #8772
-      // has since been RULED (2026-08-16, comment 5306089973) — it is no longer
-      // "open and unruled" — but the ramp it ordered has two code legs and
-      // neither has landed yet: Direction 2 (the authoring builder forces
-      // `required: true` under `controlled_by_parent`, #9138) is dispatchable
-      // now but not yet merged; Direction 1 (`relationship/master-detail-required`
-      // promoted `warning` → `error`, scoped to `controlled_by_parent`, #9139) is
-      // deliberately held for the **v18** boundary (`main` is still 17.x as of
-      // this note). So the lint measured by #8959 is unchanged: `master_detail`
-      // with no `required` still draws only `severity: 'warning'`, and
-      // `required` + `readonly` / `required` + `system` still draw nothing at
-      // all (`packages/lint/src/data-model-rules.ts`). A freshly authored detail
-      // therefore still reaches this branch and its `422` — the residue is a
-      // live, newly-authorable surface, not a shrinking legacy tail, until BOTH
-      // #9138 and #9139 land. Re-check this paragraph before trusting it; once
-      // both have landed it is the one that goes stale next.
+      // [#8959, re-measured 2026-09-01] "Confined" is now a PARTIAL publish-time
+      // bound: of the three shapes above, ONE is fenced at authoring time and
+      // two are not. #8772 was RULED (2026-08-16, comment 5306089973) and the
+      // ramp it ordered has two code legs, of which exactly one has landed.
+      // Direction 2 (#9138) IS merged: `ObjectSchema.create()` now runs
+      // `forceCbpMasterDetailRequired` (`packages/spec/src/data/object.zod.ts`)
+      // — under `controlled_by_parent`, a `master_detail` reference with
+      // `required` omitted is forced to `required: true`, and an explicit
+      // `required: false` is refused with a located error. Direction 1
+      // (`relationship/master-detail-required` promoted `warning` → `error`,
+      // scoped to `controlled_by_parent`, #9139) has NOT landed — that card is
+      // open and `pm:on-hold`, deliberately held for the **v18** boundary
+      // (`main` is still 17.x as of this note).
+      //
+      // ⛔ #9138 landing is NOT "the residue is gone". It narrows the FIRST
+      // shape only, and only on the builder path:
+      //   • no `required` — no longer newly authorable through
+      //     `ObjectSchema.create()`, but it survives on the raw
+      //     `.parse()`/`.safeParse()` path, which #9138 left untouched ON
+      //     PURPOSE so metadata already at rest keeps loading (its docblock
+      //     says so). Measured: `safeParse` of a `controlled_by_parent` object
+      //     takes both an omitted `required` and an explicit `required: false`.
+      //   • `required` + `readonly` and `required` + `system` — STILL newly
+      //     authorable through `ObjectSchema.create()` itself: the force
+      //     returns early on `required === true` and never inspects
+      //     `readonly`/`system`. It in fact MINTS them — a `readonly`/`system`
+      //     master reference authored with no `required` comes out of
+      //     `create()` as `required: true` plus the flag, which is exactly a
+      //     shape `validateRecord` skips.
+      //
+      // And nothing warns on the way past: the lint measured by #8959 is
+      // unchanged — the predicate is still `def.required !== true` at
+      // `severity: 'warning'` (`packages/lint/src/data-model-rules.ts`), so the
+      // two flagged shapes draw NO finding at ANY severity and only the
+      // un-flagged one draws a warning. A freshly authored detail therefore
+      // still reaches this branch and its `422`: for the two flagged shapes
+      // straight through the builder, for the third through raw parse. It is a
+      // live surface, not a shrinking legacy tail. Re-check this paragraph
+      // before trusting it — it goes stale when #9139 lands, or when the
+      // builder force grows to cover the two flagged shapes.
       //
       // ⛔ [#9137] FREEZE NOTE — maintainer ruling on #8772, Direction 4,
       // "immediately": until the two legs above both land, this `if` is the

packages/plugins/plugin-security/src/security-plugin.ts

@@ -1762,11 +1762,44 @@ function resolveErrorResponse(error: any, object?: string): { status: number; bo
         // means moving the STATUS this arm decided, which is the contract
         // question this card was fenced away from — filed separately.
         const businessMessage = sandboxBusinessMessage(error);
-        const safeMsg = businessMessage !== undefined
-            ? truncateClientMessage(businessMessage)
-            : typeof error.message !== 'string'
+        // [#13095] The sentence this arm hands the caller is the HUMAN half
+        // only — the same #12975 rule `classifyDataError`'s declared-4xx arm
+        // applies, spread here by the 2026-08-31 maintainer ruling (option 1:
+        // one envelope semantics on every `/data` exit). This arm is checked
+        // BEFORE it delegates to `mapDataError`, so every route that reports
+        // through `handleRouteError` / `sendThrownError` (batch, createMany,
+        // updateMany, deleteMany, clone, and the record-share classified arm,
+        // which re-dresses this very answer through `classifiedRefusalAnswer`)
+        // was still shipping the ADR-0111 `CODE:` prefix the by-id door had
+        // stopped shipping — one refusal, two readings, decided by which
+        // route caught it.
+        //
+        // Anchored to the DECLARED code ({@link withoutDeclaredCodePrefix} —
+        // ⛔ never a SCREAMING_SNAKE pattern; that function's docblock carries
+        // the safety argument), and run BEFORE the bound for #12975's reason:
+        // the prefix is not text addressed to the caller, so it must not
+        // spend the caller's #5423 budget. A message that is nothing but the
+        // prefix has no human half to ship and degrades to 'Request failed',
+        // the sibling arm's rule travelling WITH the strip.
+        //
+        // ⛔ What deliberately does NOT converge here: a genuinely EMPTY
+        // string message still ships as itself. This arm's degrade is keyed
+        // on the TYPE, unlike `classifyDataError`'s sibling which also checks
+        // length — a standing pin (`rest-hook-refusal-message-parity.test.ts`)
+        // this card's ruling did not authorise moving. The 'Request failed'
+        // limb below therefore fires only when the STRIP emptied a non-empty
+        // message, never for a message that arrived empty.
+        const addressed = businessMessage !== undefined
+            ? businessMessage
+            : typeof error.message === 'string' ? error.message : undefined;
+        const authored = addressed === undefined
+            ? undefined
+            : withoutDeclaredCodePrefix(addressed, error);
+        const safeMsg = authored === undefined
+            ? 'Request failed'
+            : authored.length === 0 && addressed !== undefined && addressed.length > 0
                 ? 'Request failed'
-                : truncateClientMessage(error.message);
+                : truncateClientMessage(authored);
         // [#9232] Narrowed, same as the three arms above.
         return withDeclaredUserMessage(error, {
             status: error.status,