fix(#14923 review): respell the gate's bare-root literal, register the wire code, and align the vocabulary with the writer

B1 — `check-orgless-write-declarations.mjs` spelled the repo tooling root as a
quoted literal, which the dispatch derivation reads as this gate DECLARING that
tree as a population it reads. It excludes it. Respelled as an anchored regex
(remedy (b), `check-published-files.mjs`' worked instance), so the escapable-
literal row discharges by construction rather than by a new ledger line.

B4 — `ERR_ORGLESS_WRITE_DECLARATION_REFUSED` is `status` 500 and REST forwards a
string code on any `status >= 500`, so it is wire vocabulary and belongs in the
ADR-0112 ledger beside its sibling `ERR_SYSTEM_WRITE_ORGANIZATION_REQUIRED`.
One entry plus its generated rows.

Contradiction — the reason vocabulary and the `sys_audit_log` ledger evidence
claimed a population no writer declares (a subject whose organization column is
present but NULL). `audit-writers.ts` deliberately leaves that case to the
refusal; both texts now say so, and both are runtime strings that reach
operators.

A1 — an empty batch built no row hook contexts, so a bogus declaration on one
was the single spelling of the option that was silently ignored. It now reads
the caller's options on that path, and two pins hold both directions.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0112hMx9hjJ9BgB28X97DS68

Author: claude

content/docs/references/api/contract.mdx

@@ -27,7 +27,7 @@ const result = ApiErrorSchema.parse(data);
 
 | Property | Type | Required | Description |
 | :--- | :--- | :--- | :--- |
-| **code** | `Enum<'VALIDATION_ERROR' \| 'INVALID_FIELD' \| 'MISSING_REQUIRED_FIELD' \| 'INVALID_FORMAT' \| 'VALUE_TOO_LONG' \| 'VALUE_TOO_SHORT' \| 'VALUE_OUT_OF_RANGE' \| … +292 more>` | ✅ | Error code (e.g. VALIDATION_ERROR; StandardErrorCode ∪ the ledger the serving side registers — ERROR_CODE_LEDGER for framework packages) |
+| **code** | `Enum<'VALIDATION_ERROR' \| 'INVALID_FIELD' \| 'MISSING_REQUIRED_FIELD' \| 'INVALID_FORMAT' \| 'VALUE_TOO_LONG' \| 'VALUE_TOO_SHORT' \| 'VALUE_OUT_OF_RANGE' \| … +293 more>` | ✅ | Error code (e.g. VALIDATION_ERROR; StandardErrorCode ∪ the ledger the serving side registers — ERROR_CODE_LEDGER for framework packages) |
 | **declaredCode** | `string` | optional | The producer-declared code, verbatim, when it is not a member of the closed `code` vocabulary — the open, author-authored channel (app-specific spellings; ADR-0112) |
 | **message** | `string` | ✅ | Readable error message |
 | **userMessage** | `string` | optional | Producer-marked user-facing refusal text, verbatim. Present exactly when the producer opted in at throw time; consumers render it to end users and keep their generic substitution for anything unmarked. Status-agnostic; never replaces `message`. |
@@ -156,6 +156,7 @@ const result = ApiErrorSchema.parse(data);
 * `ERR_FILE_CONSTRAINT`
 * `ERR_FILE_REFERENCE_COPY`
 * `ERR_HOOK_TARGET_REBIND`
+* `ERR_ORGLESS_WRITE_DECLARATION_REFUSED`
 * `ERR_READONLY_FIELD_REJECTED`
 * `ERR_SUMMARY_RECOMPUTE`
 * `ERR_SYSTEM_WRITE_ORGANIZATION_REQUIRED`

content/docs/references/api/error-code-ledger.mdx

@@ -272,6 +272,7 @@ const result = ErrorCode.parse(data);
 * `ERR_FILE_CONSTRAINT`
 * `ERR_FILE_REFERENCE_COPY`
 * `ERR_HOOK_TARGET_REBIND`
+* `ERR_ORGLESS_WRITE_DECLARATION_REFUSED`
 * `ERR_READONLY_FIELD_REJECTED`
 * `ERR_SUMMARY_RECOMPUTE`
 * `ERR_SYSTEM_WRITE_ORGANIZATION_REQUIRED`

packages/objectql/src/engine.ts

@@ -9981,7 +9981,21 @@ export class ObjectQL implements IObjectQLEngine {
         // resolver — the one reader it exists to inform — ever saw it. Widening
         // `PLATFORM_PROVISIONED_COLUMNS` is closed off by that door's own ⛔, and
         // rightly: a declaration is not a column.
-        readOrgLessWriteDeclaration(rowHookContexts[0]?.input.options),
+        //
+        // The row context is the source for every non-empty write, because a
+        // `beforeInsert` hook may legitimately have replaced `input.options`.
+        // ⚠️ An EMPTY BATCH builds no row contexts at all, so that read comes
+        // back `undefined` and a bogus declaration would be the ONE spelling of
+        // this option that is silently ignored. Nothing is written on that path,
+        // so the gap costs no rows — it costs the PROPERTY, and the property is
+        // the whole of what separates a declaration from a renamed bypass flag
+        // (the ruling's 「静默可选标记不合格」). So the empty batch falls back to
+        // the caller's own options, which is where the declaration was spelled.
+        // ⛔ Not a general `??` fallback: on a non-empty batch the hooks' options
+        // stay the only source, so nothing about the measured path moves.
+        readOrgLessWriteDeclaration(
+          rowHookContexts.length > 0 ? rowHookContexts[0]?.input.options : opCtx.options,
+        ),
       );
       const optionsBase = rowHookContexts[0]?.input.options as any;
       const driverOptions = this.buildDriverOptions(

packages/objectql/src/tenancy-orgless-write-declaration.test.ts

@@ -286,6 +286,35 @@ describe('#13636 the declaration is not a bypass — every unadmitted spelling T
     );
   });
 
+  it('refuses an unadmitted declaration on an EMPTY BATCH — the absolute has no asterisk', async () => {
+    // ⭐ The one spelling that used to be silent. An empty batch builds NO row
+    // hook contexts, so the declaration — read off `rowHookContexts[0]` — came
+    // back `undefined` and the write returned `[]` without a word. Nothing is
+    // written, so there was no security consequence; the cost was to the
+    // PROPERTY, which is the whole of what separates this option from a renamed
+    // bypass. "Every unadmitted spelling throws" has to hold with no asterisk,
+    // or the next reader learns to expect asterisks and stops checking.
+    const { engine } = await makeEngine({ posture: 'single' });
+    await expectRefusal(
+      engine.insert('sys_file', [], {
+        context: SYSTEM_CTX,
+        orgLessWrite: { object: 'sys_file', reason: 'env-level-metadata' },
+      } as any),
+      'ERR_ORGLESS_WRITE_DECLARATION_REFUSED',
+    );
+  });
+
+  it('and an ADMITTED declaration on an empty batch still writes nothing, quietly', async () => {
+    // The other half: reading the caller's options on an empty batch must not
+    // turn a LEGAL declaration into a refusal. A batch with no rows is a no-op
+    // on every other axis and stays one here.
+    const { engine, observed } = await makeEngine({ posture: 'isolated' });
+    await expect(
+      engine.insert('sys_metadata', [], { context: SYSTEM_CTX, ...ENV_METADATA } as any),
+    ).resolves.toEqual([]);
+    expect(lastWrite(observed, 'sys_metadata')).toBeUndefined();
+  });
+
   it.each([
     ['a bare boolean', true],
     ['a string', 'env-level-metadata'],

packages/objectql/src/tenancy/orgless-write-declaration.ts

@@ -94,11 +94,27 @@ export type OrgLessWriteReason =
    */
   | 'env-level-metadata'
   /**
-   * An audit record whose SUBJECT has no organization to inherit — a row on an
-   * object with no organization column at all (single-tenant stacks and
-   * ADR-0066 platform-global objects), or one whose organization column is
-   * itself NULL. The enumeration is the audit writer's own
-   * (`plugin-audit/src/audit-writers.ts`); this names it.
+   * An audit record whose SUBJECT resolves NO organization column at all, so
+   * there is no organization for the audit row to inherit: a record on an
+   * object with no tenant field (single-tenant stacks, ADR-0066 platform-global
+   * objects, the better-auth identity tables), or an installation-level subject
+   * that behaves the same way — a `global`-scope setting, an import run. That
+   * is case 1 of the audit writer's own enumeration
+   * (`plugin-audit/src/audit-writers.ts`); this names it, and names ONLY it.
+   *
+   * ⛔ Case 2 — the subject HAS an organization column and its value is NULL —
+   * is deliberately OUTSIDE this reason. At the writing call site it is
+   * indistinguishable from the missing-stamp defect the control exists to find,
+   * so no writer declares it: `audit-writers.ts` declares only when
+   * `organizationFieldFor(subject) === null`, `read-audit.ts` only when every
+   * subject in the batch does, and the three fixed-subject writers only because
+   * their one subject does. Those rows keep meeting the refusal.
+   *
+   * ⚠️ This text is not commentary — the vocabulary and the ledger `evidence`
+   * beside it are runtime strings that reach operators, so a reason describing
+   * a population no writer produces would read as a claim the platform makes.
+   * If a writer is ever taught to declare case 2, that is a ruling, and this
+   * paragraph is what has to change with it.
    */
   | 'audit-of-untenanted-record';
 

packages/objectql/src/tenancy/platform-object-tenancy.ts

@@ -265,17 +265,25 @@ export const PLATFORM_OBJECT_TENANCY: Readonly<Record<string, PlatformObjectTena
       "The env-level write declares itself ('env-level-metadata'); an undeclared org-less write on this " +
       'object is a missing stamp and is refused.',
   },
-  // #13636 specimen 2; the enumeration is the writer's own
+  // #13636 specimen 2; the enumeration is the writer's own, and this entry
+  // states CASE 1 of it only — `audit-writers.ts` declares exactly when
+  // `organizationFieldFor(subject) === null` and deliberately leaves case 2
+  // (column present, value NULL) to the refusal. ⛔ Do not widen this prose to
+  // the writer's whole enumeration: `evidence` is a runtime string, so it would
+  // tell an operator the platform blesses a population no writer declares.
   sys_audit_log: {
     tenancy: 'conditional',
     orgLessReasons: ['audit-of-untenanted-record'],
     evidence:
       'Holds both populations, and its writer enumerates the org-less one in its own source: an audit row ' +
       'inherits the organization of the RECORD it describes, falling back to the acting session ' +
-      "(`audit-writers.ts`), and neither answers for a record on an object with no organization column at " +
-      'all (single-tenant stacks and ADR-0066 platform-global objects) or a record whose own column is ' +
-      "NULL. Those rows declare themselves ('audit-of-untenanted-record'); an undeclared org-less audit " +
-      'row is the invisible-audit-row defect that writer already guards against, and is refused.',
+      "(`audit-writers.ts`), and neither answers for a record whose object resolves no organization column " +
+      'at all — single-tenant stacks, ADR-0066 platform-global objects, the better-auth identity tables, ' +
+      "and the installation-level subjects that behave the same way. Exactly those rows declare themselves " +
+      "('audit-of-untenanted-record'). A record whose column is PRESENT and NULL is deliberately NOT " +
+      'declared by any writer: at the call site it cannot be told apart from a missing stamp, so it keeps ' +
+      'meeting the refusal, as does every other undeclared org-less audit row — the invisible-audit-row ' +
+      'defect that writer already guards against.',
   },
 
   // ── global ───────────────────────────────────────────────────────────────

packages/spec/src/api/error-code-ledger.zod.ts

@@ -513,6 +513,18 @@ export const ERROR_CODE_LEDGER = {
     // `hook-target-rebind-errors.ts`), during a write the dispatcher is
     // serving. Same #8087-gate family.
     'ERR_HOOK_TARGET_REBIND',
+    // [#13636] A write carried an `orgLessWrite` declaration the platform
+    // tenancy ledger does not admit — an object it has not classified
+    // `conditional`, a reason that object does not admit, a malformed value, or
+    // an object other than the one being written
+    // (`OrgLessWriteDeclarationRefusedError`, `tenancy/orgless-write-declaration.ts`).
+    // Registered for the same reason its sibling
+    // `ERR_SYSTEM_WRITE_ORGANIZATION_REQUIRED` below is: it carries `status` 500
+    // and the REST layer forwards a string `code` on any `status >= 500`, so it
+    // is WIRE vocabulary whether or not a route means it to be. Not a synonym of
+    // any standard member — the fault is server-side code making a claim it is
+    // not entitled to make, not a client's bad input.
+    'ERR_ORGLESS_WRITE_DECLARATION_REFUSED',
     // [#5320] Third EMITTER of the code (metadata-protocol and plugin-security
     // already register it) — the registration loop's `views:` tighten refuses a
     // non-container entry, and the `viewItems:` channel refuses an entry the

scripts/check-orgless-write-declarations.mjs

@@ -96,9 +96,44 @@ const DECLARATION_SITES = {
     'a tenant id is a missing stamp and keeps meeting the refusal.',
 };
 
-/** Files this scan never reads: tests state their own fixtures, including bad ones. */
+/**
+ * Files this scan never reads.
+ *
+ * Both exclusions are about a file STATING a declaration rather than making
+ * one: a test states its own fixtures, including deliberately bad ones, and the
+ * repo's own tooling tree states them too — this gate's `--self-test` corpus
+ * carries the literal spelling as data, and a sibling gate or codemod written
+ * in `.mts` would carry it the same way.
+ *
+ * ⚠️ The tooling half is an anchored REGEX, and that is load-bearing rather
+ * than stylistic (#10705). `extractWatchHints` in `scripts/pm/dispatch-gates.mjs`
+ * reads any quoted span carrying a separator as this gate DECLARING that
+ * population, so the quoted literal this used to be — `file.startsWith(…)` over
+ * the repo tooling root — announced that root as a tree this gate READS. It
+ * does the exact opposite: the literal's whole job is to keep that tree OUT.
+ * The false announcement then collapsed to a bare top-level word `hintCovers`
+ * refuses as too generic, so the gate scored `silent` for every card in the
+ * tree while appearing to name a root it never opens, and
+ * `check:pm-dispatch-gates` reds on precisely that — the escapable-literal
+ * ledger, which is SHRINK-ONLY, so a new line in it is not a remedy.
+ *
+ * Two things not to do here, both of which look like the fix and are not:
+ *   - ⛔ do NOT restore the quoted form. `check:pm-dispatch-gates` decides with
+ *     the derivation's OWN extractor rather than a copy of it, so the row comes
+ *     straight back;
+ *   - ⛔ do NOT reach for the `ROOT_DIR_WATCH_HINTS` escape (the subtree
+ *     spelling, as `check-parse-guard` and `check-role-word` legitimately use).
+ *     For THIS gate that declaration would be false in the strongest way
+ *     available — it would name the gate for every repo-root tooling edit as a
+ *     tree it reads, when the predicate exists to exclude that tree. A
+ *     fabricated lead costs more than a missing one (+139084, measured in
+ *     `hintCovers`' docblock).
+ *
+ * The population this gate really reads is announced by {@link LEDGER_PATH} and
+ * the {@link DECLARATION_SITES} keys above — both already hints, both true.
+ */
 const isScannable = (file) =>
-  /\.(ts|mts|tsx)$/.test(file) && !/\.(test|spec)\.[cm]?tsx?$/.test(file) && !file.startsWith('scripts/');
+  /\.(ts|mts|tsx)$/.test(file) && !/\.(test|spec)\.[cm]?tsx?$/.test(file) && !/^scripts\//.test(file);
 
 /** Every tracked source file, from git rather than a walk (untracked ≠ shipped). */
 export function trackedSources(cwd = process.cwd()) {