feat(objectql): declare a legitimately org-less write instead of inferring it from NULL

.changeset/orgless-write-declaration-channel.md

@@ -0,0 +1,47 @@
+---
+"@objectstack/objectql": minor
+"@objectstack/metadata-protocol": minor
+"@objectstack/plugin-audit": minor
+"@objectstack/plugin-auth": minor
+"@objectstack/service-settings": minor
+---
+
+feat(objectql): an explicit per-write declaration for a legitimately org-less row
+
+Until now one `NULL` organization on a platform object meant two different
+things — a deliberate environment-level row, and a write that forgot to thread
+an organization — and `resolveSystemInsertOrganization` had no way to tell them
+apart. So the two objects that hold BOTH populations, `sys_metadata` (whose
+non-overridable-type write lands env-wide by adjudication) and `sys_audit_log`
+(whose writers enumerate their own legitimate org-less cases), had to stay
+outside the tenant-audit control entirely. They are two of the largest write
+populations in the platform namespace, which put the control's blind spot
+exactly where it was least affordable.
+
+Writes may now DECLARE that their rows belong to an adjudicated org-less
+population:
+
+```ts
+await engine.insert('sys_metadata', row, {
+  context: { isSystem: true },
+  orgLessWrite: { object: 'sys_metadata', reason: 'env-level-metadata' },
+});
+```
+
+The platform tenancy ledger gains a fourth verdict, `conditional`, and both
+objects are admitted under it. ⚠️ Admission makes them STRICTER, not looser: an
+org-less system write on either is now derived on a single-organization install
+and refused loudly on a walled one, exactly as a `tenant-scoped` object's is,
+and the declaration is the only way through. It is checked against the ledger
+before anything else the resolver does, so a declaration naming an object the
+ledger has not admitted, a reason that object does not admit, or an object other
+than the one being written throws `ERR_ORGLESS_WRITE_DECLARATION_REFUSED` — no
+spelling of the option is silently ignored, which is what separates a
+declaration from a bypass flag. ⛔ It is not a way to quiet a refusal: a write
+that simply forgot to thread an organization is the defect the refusal reports.
+
+The platform's own six org-less writers declare, each on a test a reader can
+check — the metadata repository on its own env-level scope, the audit writers on
+whether the audited subject resolves an organization column at all. A new gate,
+`pnpm check:orgless-write-declarations`, enumerates every declaration in the
+tree, holds each to the same ledger the runtime does, and prints the count.

.github/workflows/lint.yml

@@ -3596,6 +3596,20 @@ jobs:
       - name: Read-side tenant chokepoint gate
         run: pnpm check:tenant-chokepoint
 
+      # [#13636] The 'orgLessWrite' declaration census. The maintainer's
+      # 2026-08-31 ruling put 'loud, checkable, countable' in the decision text
+      # rather than in implementation notes; the engine discharges the first two
+      # at the write, and this is the third — every declaration in the monorepo
+      # enumerated, held to the same ledger the runtime holds it to, and COUNTED
+      # on every pass. A declaration nobody can count is the silent marker that
+      # ruling disqualified by name.
+      #
+      # Static scan over tracked sources, no build needed, so it belongs here.
+      # Runs its own --self-test first: a matcher that stopped matching would
+      # report OK while reading nothing.
+      - name: Org-less write declaration gate
+        run: pnpm check:orgless-write-declarations
+
       # Every committed `pnpm --filter <name>` must name a real workspace
       # package (#10853).
       #

content/docs/permissions/system-context.mdx

@@ -101,26 +101,26 @@ that silently does not happen.
 | 12 | Per-request performance timings disclosed | observability | Get: timing headers a normal caller cannot pull | `perf-timing.ts:474` |
 | 13 | Permission-set **overlay discard** skips the tenant-admin assertion | plugin-security | Get: an overlay can be discarded with no authenticated tenant administrator | `permission-set-overlay-discard.ts:142` |
 | 14 | MCP stdio bridge skips the object API-exposure gate | mcp | Get: the bridge reaches objects whose `apiEnabled` / `apiMethods` would refuse an external caller | `stdio-data-bridge.ts:246` |
-| 15 | **Read-audit rows are not written** | plugin-audit | Lose: the "a person opened this record" trail. `sudo()` keeps the caller's `userId`, so this flag is the only thing separating a human read from a platform one | `read-audit.ts:556` |
+| 15 | **Read-audit rows are not written** | plugin-audit | Lose: the "a person opened this record" trail. `sudo()` keeps the caller's `userId`, so this flag is the only thing separating a human read from a platform one | `read-audit.ts:583` |
 | 16 | Approval snapshot payload redaction skipped | plugin-approvals | Get: the whole snapshot on `find` / `findOne` — the audit/replay channel. Lose: field-visibility redaction over approval payloads | `payload-redaction-middleware.ts:115` |
 | 17 | REST anonymous-deny seam satisfied | rest | Get: `enforceAuth` passes with no `userId`. Not reachable from the wire — `isSystem` is never set on an inbound request | `rest-server.ts:1552` |
 
 ### 2. Write pipeline and data integrity
 
 | # | Behaviour when `isSystem` | Package | What you get / what you lose | Anchor |
 |:--|:---|:---|:---|:---|
-| 18 | **`readonly` strip bypassed — UPDATE, single row** | objectql | Get: a `readonly` field CAN be written. Lose: the protection that stops a caller seeding e.g. `approval_status` | `objectql/src/engine.ts:11289` |
-| 19 | **`readonly` strip bypassed — UPDATE, bulk/predicate** | objectql | Same, on the multi-row path | `objectql/src/engine.ts:11472` |
-| 20 | **`readonly` strip bypassed — INSERT (engine pass)** | objectql | Same, on create | `objectql/src/engine.ts:10024` |
+| 18 | **`readonly` strip bypassed — UPDATE, single row** | objectql | Get: a `readonly` field CAN be written. Lose: the protection that stops a caller seeding e.g. `approval_status` | `objectql/src/engine.ts:11351` |
+| 19 | **`readonly` strip bypassed — UPDATE, bulk/predicate** | objectql | Same, on the multi-row path | `objectql/src/engine.ts:11534` |
+| 20 | **`readonly` strip bypassed — INSERT (engine pass)** | objectql | Same, on create | `objectql/src/engine.ts:10086` |
 | 21 | **`readonly` strip bypassed — INSERT (protocol ingress)** | metadata-protocol | `isSystem` is the **only** exemption here. `preserveAudit` is deliberately not read on this path (#6640) — a non-system historical import is still stripped on create | `metadata-protocol/src/protocol.ts:1746` |
-| 22 | Strict-drop refusal never fires | objectql | Lose: a caller that opted into loud refusal gets **silence** — strict refuses exactly what the strip would have taken, and the strip took nothing | `objectql/src/engine.ts:10072`, `readonly-strict-errors.ts:66` |
-| 23 | **Referential-integrity check skipped** | objectql | Get: writes proceed against unreachable/unresolvable targets. Lose: an `isSystem` caller can write a **dangling reference** | `objectql/src/engine.ts:5891` |
-| 24 | Tenant-audit warning silenced; `bypassTenantAudit` threaded to the driver | objectql | Get: unscoped system writes stop warning. Lose: the signal that would flag a genuine user-path scoping bug | `objectql/src/engine.ts:3735`, `:3745`, `:3772` |
+| 22 | Strict-drop refusal never fires | objectql | Lose: a caller that opted into loud refusal gets **silence** — strict refuses exactly what the strip would have taken, and the strip took nothing | `objectql/src/engine.ts:10134`, `readonly-strict-errors.ts:66` |
+| 23 | **Referential-integrity check skipped** | objectql | Get: writes proceed against unreachable/unresolvable targets. Lose: an `isSystem` caller can write a **dangling reference** | `objectql/src/engine.ts:5931` |
+| 24 | Tenant-audit warning silenced; `bypassTenantAudit` threaded to the driver | objectql | Get: unscoped system writes stop warning. Lose: the signal that would flag a genuine user-path scoping bug | `objectql/src/engine.ts:3740`, `:3750`, `:3777` |
 | 25 | Engine-owned / append-only write guard bypassed | plugin-security | Get: generic writes to `managedBy` engine-owned objects | `system-write-guard.ts:96`, `:120` |
 | 26 | Identity write guard bypassed (ADR-0092) | plugin-auth | Get: direct writes to identity tables through the generic data path | `identity-write-guard.ts:98` |
-| 27 | Search-companion column **kept** in a read's rows when it was explicitly requested | objectql | Get: the internal companion column is readable. Lose: nothing for app code — this is the engine reading its own index | `objectql/src/engine.ts:6589` |
-| 28 | Dependent-count disclosure on a blocked delete | objectql | Get: the count of blocking children. Nothing was elevated past the caller, so nothing is withheld | `objectql/src/engine.ts:12084` |
-| 29 | Reference-cleanup log attributes the write to `'system'` | objectql | Get: an honest actor label instead of `anonymous` when the context carries neither `userId` nor `actor` | `objectql/src/engine.ts:12013` |
+| 27 | Search-companion column **kept** in a read's rows when it was explicitly requested | objectql | Get: the internal companion column is readable. Lose: nothing for app code — this is the engine reading its own index | `objectql/src/engine.ts:6629` |
+| 28 | Dependent-count disclosure on a blocked delete | objectql | Get: the count of blocking children. Nothing was elevated past the caller, so nothing is withheld | `objectql/src/engine.ts:12146` |
+| 29 | Reference-cleanup log attributes the write to `'system'` | objectql | Get: an honest actor label instead of `anonymous` when the context carries neither `userId` nor `actor` | `objectql/src/engine.ts:12075` |
 
 ### 3. Sharing (`plugin-sharing`)
 
@@ -179,8 +179,8 @@ a reader tracing where elevation travels needs them.
 
 | # | Site | Package | What it does |
 |:--|:---|:---|:---|
-| 62 | `objectql/src/engine.ts:3542` | objectql | Propagates `isSystem` into the hook session so hooks can tell engine self-writes from user writes |
-| 63 | `objectql/src/engine.ts:14433` | objectql | `ScopedContext.isSystem` getter — re-exposes the underlying execution context's flag |
+| 62 | `objectql/src/engine.ts:3547` | objectql | Propagates `isSystem` into the hook session so hooks can tell engine self-writes from user writes |
+| 63 | `objectql/src/engine.ts:14504` | objectql | `ScopedContext.isSystem` getter — re-exposes the underlying execution context's flag |
 | 64 | `plugin-reports/src/report-service.ts:556` | plugin-reports | Threads the flag into the engine call that runs a report |
 | 65 | `body-runner.ts:279` | runtime | Rebuilds an `ExecutionContext` from a hook session, carrying the flag across |
 
@@ -195,7 +195,7 @@ assuming `isSystem` covers it is a documented source of bugs.
 |:---|:---|:---|
 | "It suppresses triggers / record-change automation" | **No.** Only `skipTriggers` does. A bare `{ isSystem: true }` on a seed write re-fired automation on freshly seeded rows and wedged first boot | `metadata-protocol/src/seed-loader.ts:1971` (rationale at `:1881`–`1883`, #3760), `flow.zod.ts:702` |
 | "It skips the state machine" | **No.** That is `skipStateMachine`, carried by seed replay and by `treatAsHistorical` imports | `objectql/src/engine.ts` FSM gate; see [State Machine](/docs/protocol/objectql/state-machine) |
-| "It skips validation rules" | **No.** Field shape, `format`, `script` and the rest still run. The `readonly` strip runs *before* validation precisely so a discarded value is not judged | `objectql/src/engine.ts:10007`–`10024` |
+| "It skips validation rules" | **No.** Field shape, `format`, `script` and the rest still run. The `readonly` strip runs *before* validation precisely so a discarded value is not judged | `objectql/src/engine.ts:10069`–`10086` |
 | "It preserves a supplied `updated_at` / `updated_by`" | **No.** That is `preserveAudit`, a separate opt-in — and an UPDATE-path exemption only | `field.zod.ts:1537` (#3493 / #6640) |
 | "It stamps `created_by`" | **No.** Audit stamping reads `userId` from the context. A user-less system write stamps nothing — that is today's behaviour, not an error | `runtime-identity.ts:280`–`281` |
 | "It bypasses every guard" | **No.** The last-admin guard applies to **every** context, `isSystem` included — the deprovision path that actually locks an org out is the system one | `last-admin-guard.ts:299` |

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`

package.json

@@ -151,6 +151,7 @@
     "check:resume-authority-declared": "node scripts/check-resume-authority-declared.mjs --self-test && node scripts/check-resume-authority-declared.mjs",
     "check:spec-parsed-alias": "node scripts/check-spec-parsed-alias.mjs --self-test && node scripts/check-spec-parsed-alias.mjs",
     "check:tenant-chokepoint": "node scripts/check-tenant-chokepoint.mjs --self-test && node scripts/check-tenant-chokepoint.mjs",
+    "check:orgless-write-declarations": "node scripts/check-orgless-write-declarations.mjs --self-test && node scripts/check-orgless-write-declarations.mjs",
     "check:stall-guard": "node scripts/run-with-stall-guard.mjs --self-test",
     "check:stall-guard-budget": "node scripts/check-stall-guard-budget.mjs --self-test && node scripts/check-stall-guard-budget.mjs",
     "check:stall-guard-headroom": "node scripts/measure-stall-guard-headroom.mjs --self-test",

packages/metadata-protocol/src/sys-metadata-repository.ts

@@ -191,7 +191,20 @@ export interface SysMetadataEngine {
   insert(
     table: string,
     data: Record<string, unknown>,
-    options?: { context?: any },
+    options?: {
+      context?: any;
+      /**
+       * [#13636] The engine's per-write "these rows are legitimately org-less"
+       * declaration. Spelled structurally rather than imported: the canonical
+       * type is `OrgLessWriteDeclarationOptions` in
+       * `@objectstack/objectql`'s `tenancy/orgless-write-declaration.ts`, and
+       * THAT package depends on this one — importing it here would be a cycle.
+       * The engine validates every declaration against its ledger and throws on
+       * one it does not admit, so a drift between these two spellings fails
+       * loudly at the write rather than being tolerated.
+       */
+      orgLessWrite?: { object: string; reason: string };
+    },
   ): Promise<{ id: string }>;
   update(
     table: string,
@@ -608,7 +621,21 @@ export class SysMetadataRepository implements MetadataRepository {
         });
       } else {
         parentRowData.created_at = now;
-        await this.engine.insert('sys_metadata', parentRowData, { context: ctx });
+        // [#13636] An ENV-LEVEL repository writes `organization_id: null` on
+        // purpose — the #6190 option A population, a row that belongs to the
+        // installation rather than to any organization. `sys_metadata` is
+        // admitted as `conditional` in the engine's platform tenancy ledger, so
+        // without this declaration that write is indistinguishable from a
+        // forgotten stamp and is refused on a walled install. The condition is
+        // the repository's own scope, fixed at construction, not a property of
+        // the row being written — so an org-scoped repository never declares,
+        // and a missing stamp on ITS writes still refuses.
+        await this.engine.insert('sys_metadata', parentRowData, {
+          context: ctx,
+          ...(this.organizationId == null
+            ? { orgLessWrite: { object: 'sys_metadata', reason: 'env-level-metadata' } }
+            : {}),
+        });
       }
 
       // Durable history append — same transaction, so the parent write