feat(service-settings)!: the settings audit trail's global rung moves to a deployment-level sibling, sys_platform_setting_audit (18.x step 2, expand-first) (#24590)

Closes #24530
Clause-②: yes (narrowing)

**18.x line, step 2 (8b-0e′), expand-first. This is PR 2a only.**
- Ruling record 6257510973 (#24377, Q4 A).
- Ruling records 6266750393 and 6267391172 on #15194 (the line).
- The epic seat's binding scope correction, from step 0's measured plan
(os-dev-report 6268559156 on #24522).

The `sys_secret` / `sys_flow_credential` flip (ruling record 6259141885,
#24435 Q1 A, for the latter) is **not in this PR**. It moves to step 6,
with the opened ceremony; see "Measured" below.

⛔ **Merge gate.** This PR stays a draft until #24522's upgrade harness
(#24552) has merged. Then it merges `main`, runs the harness, and lands
only when R1–R4 hold with the harness green.

## What changes

1. **New `sys_platform_setting_audit`**, the settings audit trail's
global rung, created fresh:
   - `systemFields: { tenant: false }`: no organization column;
- `requiredPermissions: ['manage_platform_settings']`, as
`sys_platform_setting` has;
   - `managedBy: 'engine-owned'`, with reads only on the data API;
- the same row shape as `sys_setting_audit`, with `scope` always
`global`.

It registers with service-settings (the manifest), joins
`SETTINGS_READ_DOOR_OBJECTS` (so each namespace's `readPermission`
applies there too), and joins `PLATFORM_OBJECTS_BY_PACKAGE`.
2. **The writer routes by rung** (`buildSettingAuditWriter`, through one
predicate, `settingAuditObjectFor`):
   - `scope === 'global'` goes to the sibling, with no organization;
- tenant and user rows stay in `sys_setting_audit`, stamped as before;
- each insert names its table literally, so the tenant-audit census
keeps every write site statically decidable.
3. **Regenerated with the repo's tooling:**
- `scripts/platform-object-tenancy-census.json`: the sibling is added,
out of reach because `systemFields.tenant` is `false`;
- the tenant-audit census page and counts: one more write call site,
with the hand-written figures the gate holds updated to match.
4. **Inventory:** the sibling's row, placed next to
`sys_setting_audit`'s (`column-drop`, no column).
5. **Platform checklist:** two items that read the global rung's audit
rows from `sys_setting_audit` are re-pointed, each with a revision bump
and a history entry.

## Measured: why `sys_secret` and `sys_flow_credential` are untouched

**Measured:** the 18.0 DDL for the two tables, populated with
18.0-shaped rows, then the engine's schema sync and the v18 boot guard's
own predicate.

| declared shape | boot guard (`findV17ShapeTables`) | drift
(`detectManagedDrift`) |
|:--|:--|:--|
| `systemFields: { tenant: false }`, `organization_id` not declared |
**refuses**: `["sys_flow_credential","sys_secret"]` | `drop_column`,
`destructive`, on both tables |
| `tenancy: { enabled: false }`, `organization_id` kept declared | `[]`
| `[]` |

The first row refuses every 18.0 database at boot, which breaks R2. The
second escapes the guard, and the epic seat rules that escape a gap, not
a route. The kept ceremony class would also block its `column-drops`
step on a column the runtime still declares: measured on
`organization-ownership-boot-refusal-order.dogfood.test.ts` when the two
objects' inventory fates were moved, and reverted. So both objects ship
as 18.0 shipped them, and their flip lands with step 6.

## 18.0 rows

- Nothing is moved, deleted or re-stamped, and no column is dropped.
- An 18.0 install wrote its global-rung audit rows into
`sys_setting_audit`, **stamped with the Default Organization**. They
stay there, readable through the data API as before.
- The global rung's history is the sibling **plus** `sys_setting_audit`
rows **selected by `scope = 'global'`**, never by a NULL organization.
- There is no in-process history reader to union today: the only readers
are the two data-API grids behind the settings read door. Both serve
their rows, as the dogfood pin shows.

## The step-5/6 ceremony owes

| table | owed |
|:--|:--|
| `sys_setting_audit` | move the `scope = 'global'` rows to
`sys_platform_setting_audit`: an inventory `departures` entry, plus a
`MOVES` entry in `organization-ownership-apply.ts` like `sys_setting`'s
`global-rung-move`. Then `scope`'s `global` option can retire, and 8e's
NOT NULL applies to the rest. |
| `sys_secret` | the column-less flip with step 6: the declaration goes
to `systemFields: { tenant: false }`, the inventory fate goes 3 →
`column-drop`, and the `column-drops` step drops `organization_id`. The
settings writer stops stamping it. |
| `sys_flow_credential` | the same flip with step 6, plus
`column-drops`. |
| `sys_platform_setting_audit` | nothing. |

Step 7 removes the dual read: once the move has run, the global rung's
history is the sibling alone.

## Proof

- **R1:** a fresh `pnpm dev -- --fresh` showcase boot.
  - `GET /api/v1/discovery` answered 200.
- `PUT /api/settings/ai` (encrypted, global) and `PUT
/api/settings/branding` (tenant) answered 200.
- `/data/sys_platform_setting_audit` lists the global rows with no
organization, and `/data/sys_setting_audit` the tenant rows, stamped.
- **R2:**
- The pins below, including an 18.0-shaped global audit row booted over
with the ownership guard composed.
- #24522's harness at branch head `f6128e3`, run locally on this branch:
5/5 green (its files are not committed here).
- **R3:** the same harness run's v17 case is refused with the guard's
code.
- **R4:** `OS_TENANCY_POSTURE=isolated pnpm dev -- --fresh` exits 1 with
`tenancy posture 'isolated' is not supported in 18.0 (NOT_IMPLEMENTED)`.

**New pins:**
- `service-settings/src/settings-deployment-level-expand.test.ts`: a
real engine under `single` with a live D9-stamp control. The new write
shape, and the dual read on an 18.0-shaped row.
- `service-settings/src/settings-secret-organization.test.ts`: per-rung
routing through the one predicate.
- `qa/dogfood/test/settings-audit-global-rung-sibling.dogfood.test.ts`:
two showcase boots over one file, the second with an 18.0-shaped stamped
global audit row.
- The sibling also joins the D7 family pin, the read-door pin and the
manifest pin.

**Ablation X6:** the routing predicate was pinned to
`sys_setting_audit`, via `scripts/ablation-replace.mjs`, rebuilt, and
checked by `ablation-dist-preflight` in both directions.
- Red: the expand pin 2/4, the routing pin 2/6, the dogfood pin 2/4.
- Restored to the `HEAD` blob.
- The first attempt was a no-op: the build refused the marker spelling,
and no pin ran.

## Acceptance notes

- A global-rung audit row now needs `manage_platform_settings` to be
read through the data API. That is the narrowing the changeset states,
with its remedy.
- `docs/qa` checklist items 7 and 29 were re-pointed because their
clauses stopped being true. Not in the claim's named surface; noted for
the seat.

---
_Generated by [Claude
Code](https://claude.ai/code/session_01HZT9daB4YX41N1SVVxYcek)_

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: objectstack-fleet[bot]

.changeset/24530-settings-audit-global-rung-sibling.md

@@ -0,0 +1,20 @@
+---
+'@objectstack/platform-objects': minor
+'@objectstack/service-settings': minor
+'@objectstack/spec': minor
+'@objectstack/cli': minor
+---
+
+feat(service-settings)!: the settings audit trail's global rung moves to the new deployment-level `sys_platform_setting_audit`
+
+Clause-②: yes (narrowing)
+
+<!-- adr-0087: not-required (no-migration-prescription) No key of any metadata schema is removed, renamed or re-shaped, so there is nothing for `objectstack migrate meta` to rewrite and no tombstone: sys_setting_audit.scope keeps its global option because 18.0 rows hold it. What narrows is where a NEW global-rung audit row is stored and who may read it; the remedy is a run-time one, stated below. -->
+
+**BREAKING** for a reader of the settings audit trail, shipped as `minor` under the repo's launch-window convention for breaking changes (ADR-0131 D7; ruling record 6257510973, Q4 A). This is the expand half of the change: it adds the new write shape, and the 18.0 rows stay where they are and readable. No row an 18.0 install wrote is moved, deleted or re-stamped.
+
+- **Before.** A write of a global-scope settings key appended its history row to `sys_setting_audit`, stamped with the Default Organization under `single`. Any principal the settings read door let read the namespace could list it there.
+- **Now.** That row goes to the new `sys_platform_setting_audit`. It has the same row shape, `scope` is always `global`, and there is no organization column (`systemFields: { tenant: false }`). Reading it through the generic data API requires the `manage_platform_settings` capability, as `sys_platform_setting` does, and each namespace's `readPermission` applies there too. Tenant and user rows stay in `sys_setting_audit`, stamped as before.
+- **18.0 rows.** Global-rung rows an 18.0 install wrote stay in `sys_setting_audit`, stamped, until the upgrade ceremony moves them. The global rung's history is both tables: the sibling, plus `sys_setting_audit` rows at `scope = global`.
+
+**The remedy.** If you list or filter the global rung's settings history (`sys_setting_audit` with `scope = global`), read `sys_platform_setting_audit` as well, with a principal that holds `manage_platform_settings`. Select the 18.0 rows by `scope`, never by a missing organization: they carry the Default Organization. Nothing changes for a reader of tenant or user rows.

content/docs/permissions/tenant-audit-census.mdx

@@ -83,7 +83,7 @@ what moved this page's population from 225 to 227; nothing about the two sites
 changed, only whether this instrument could see them.
 
 **The expensive failure direction is a keyword.** Sites whose receiver the author
-typed `any` have no type to read, and there are 40 of them — just under a fifth
+typed `any` have no type to read, and there are 41 of them — just under a fifth
 of the population, concentrated in exactly the seed and bootstrap paths this
 control exists for. Scoring an unreadable receiver as "not an engine" would have
 dropped every one of them silently, with a clean exit and a smaller number that
@@ -122,7 +122,7 @@ are reported as `undecidable` rather than assumed either way.
 
 The same holds twice over for the context. An options argument spelled as a
 literal can be read; one spelled `options`, `{ ...opts }`, or handed through a
-forwarding shim cannot, and **52 of the 231 sites are spelled that way**. A
+forwarding shim cannot, and **52 of the 232 sites are spelled that way**. A
 context resolved from an inline literal or a local `const` can be tested for
 `isSystem`; one arriving from a helper call cannot.
 
@@ -187,10 +187,10 @@ reproduce them. Where it disagrees, it disagrees on the page:
 
 | carried figure | where it survives | this census |
 | :--- | :--- | ---: |
-| 175 write call sites | quoted in the merged changeset | **231** |
+| 175 write call sites | quoted in the merged changeset | **232** |
 | 24 carrying no tenant context | quoted in the merged changeset | **2** provable and tenancy-enabled; **31** more whose options argument is unreadable |
-| 127 of 175 statically decidable, 48 runtime-parameter-name sites | restated on the `isSystem`-scoping card | **157 of 231** decidable, **74** undecidable |
-| 135 (77%) silenced by the `isSystem` guard before the posture gate | the lost issue body — **no surviving corroboration** | **not reproduced**: 128 decidably elevated, 0 decidably not, 95 undecidable |
+| 127 of 175 statically decidable, 48 runtime-parameter-name sites | restated on the `isSystem`-scoping card | **158 of 232** decidable, **74** undecidable |
+| 135 (77%) silenced by the `isSystem` guard before the posture gate | the lost issue body — **no surviving corroboration** | **not reproduced**: 129 decidably elevated, 0 decidably not, 95 undecidable |
 | 141 and 132, two independent re-derivations | the card that filed this work | — |
 
 **The differences are not reconciled, and deliberately so.** The old census's
@@ -200,18 +200,18 @@ be stated is what this instrument counts, which is written above and re-runnable
 at any commit.
 
 Two structural facts do plausibly widen this reading against any hand or regex
-one, and both are counted in the generated tables below: the 40 sites reached
+one, and both are counted in the generated tables below: the 41 sites reached
 through an erased (`any`) receiver, and the 51 that name their object through a
 `const` rather than inline. An instrument that read either the way a person does
 would report a smaller number and would not say so.
 
 The fourth row is the one worth flagging to anyone citing it. **The 135 / 77%
 figure has no surviving corroboration anywhere in the tree.** This census reads
-128 of 231 (55%) as decidably elevated, with 95 more whose elevation is a
+129 of 232 (56%) as decidably elevated, with 95 more whose elevation is a
 run-time fact — so the claim is neither confirmed nor refuted, and the honest
 answer is that a static reading cannot settle it.
 
-⇒ **Cite `2 / 231`, and say what it is**: the sites whose options argument was
+⇒ **Cite `2 / 232`, and say what it is**: the sites whose options argument was
 READ and holds no tenant context, against a decidably tenancy-enabled object.
 That is the control's provable yield surface. ⛔ Do not cite it as "the sites
 without tenant context" — **31 further sites** have an options argument this
@@ -223,28 +223,28 @@ cannot read, and they are neither in nor out.
 
 | what | count |
 | :--- | ---: |
-| write call sites on the application surface | **231** |
-| …whose object name is statically decidable | 157 |
+| write call sites on the application surface | **232** |
+| …whose object name is statically decidable | 158 |
 | …whose object name is chosen at run time | 74 |
-| …against an object with tenancy ENABLED | 156 |
+| …against an object with tenancy ENABLED | 157 |
 | …against an object that declares tenancy off | 1 |
-| threading a tenant context | 171 |
+| threading a tenant context | 172 |
 | PROVABLY carrying none (options read, no context key) | **8** |
 | …of those, against a decidably tenancy-enabled object | **2** |
 | options argument UNREADABLE — may or may not carry one | 52 |
 | …of those, against a decidably tenancy-enabled object | 31 |
-| threading a decidably ELEVATED (`isSystem`) context | 128 |
+| threading a decidably ELEVATED (`isSystem`) context | 129 |
 | threading a context that is decidably NOT elevated | 0 |
 | threading a context whose elevation is a run-time fact | 95 |
 
 | how the instrument reached the site | count |
 | :--- | ---: |
 | receiver carried a readable engine type | 191 |
-| receiver erased, placed by the object NAME | 30 |
+| receiver erased, placed by the object NAME | 31 |
 | receiver erased, placed by an `object: string` PARAMETER | 5 |
 | receiver erased, placed by an `UNTYPED_RECEIVERS` row | 5 |
 
-| object name spelled inline | 106 |
+| object name spelled inline | 107 |
 | object name spelled through a `const` | 51 |
 | object name is an `object: string` parameter | 7 |
 | object name is some other run-time expression | 67 |
@@ -297,13 +297,13 @@ holds still. They are required to be HERE and to say WHEN they were true;
 their values are not compared. The reasoning, and the measurement behind it,
 are in `scripts/check-tenant-audit-census.mjs`.
 
-Measured on 2026-10-19 at `ebe85c6d3`.
+Measured on 2026-10-19 at `030483e7f`.
 
 | corpus scale (not enforced) | count |
 | :--- | ---: |
 | tracked non-test sources scanned | 672 |
 | engine-shaped types recognised | 79 |
-| declared objects in the registry | 117 |
+| declared objects in the registry | 118 |
 | same-named calls subtracted as non-engine | 166 |
 
 {/* END GENERATED: tenant-audit-census */}

docs/audits/2026-08-tenant-audit-write-call-sites.counts.md

@@ -33,17 +33,17 @@ silent, and `node scripts/tenant-audit-census.mjs --write` is the resolution.
 
 | Measure | Value |
 |---|---:|
-| Write call sites | 231 |
-| Object name statically decidable | 157 |
+| Write call sites | 232 |
+| Object name statically decidable | 158 |
 | Object name chosen at run time | 74 |
-| Against a tenancy-enabled object | 156 |
+| Against a tenancy-enabled object | 157 |
 | Against an object declaring tenancy off | 1 |
-| Threading a tenant context | 171 |
+| Threading a tenant context | 172 |
 | Provably carrying none | 8 |
 | …and decidably tenancy-enabled | 2 |
 | Options argument unreadable | 52 |
 | …and decidably tenancy-enabled | 31 |
-| Threading a decidably elevated context | 128 |
+| Threading a decidably elevated context | 129 |
 | Threading a decidably non-elevated context | 0 |
 | Threading a context of undecidable elevation | 95 |
 
@@ -90,13 +90,13 @@ holds still. They are required to be HERE and to say WHEN they were true;
 their values are not compared. The reasoning, and the measurement behind it,
 are in `scripts/check-tenant-audit-census.mjs`.
 
-Measured on 2026-10-19 at `ebe85c6d3`.
+Measured on 2026-10-19 at `030483e7f`.
 
 | corpus scale (not enforced) | count |
 | :--- | ---: |
 | tracked non-test sources scanned | 672 |
 | engine-shaped types recognised | 79 |
-| declared objects in the registry | 117 |
+| declared objects in the registry | 118 |
 | same-named calls subtracted as non-engine | 166 |
 
 ## Every site
@@ -229,6 +229,7 @@ Measured on 2026-10-19 at `ebe85c6d3`.
 | `packages/services/service-settings/src/config-change-audit.ts` | `insert` | `sys_audit_log` | enabled | context, elevation undecidable | 1 |
 | `packages/services/service-settings/src/settings-service-plugin.ts` | `insert` | `objectName` | undecidable | options unreadable | 1 |
 | `packages/services/service-settings/src/settings-service-plugin.ts` | `update` | `objectName` | undecidable | options unreadable | 2 |
+| `packages/services/service-settings/src/settings-service-plugin.ts` | `insert` | `sys_platform_setting_audit` | enabled | elevated | 1 |
 | `packages/services/service-settings/src/settings-service-plugin.ts` | `delete` | `sys_secret` | enabled | elevated | 1 |
 | `packages/services/service-settings/src/settings-service-plugin.ts` | `insert` | `sys_secret` | enabled | elevated | 1 |
 | `packages/services/service-settings/src/settings-service-plugin.ts` | `update` | `sys_secret` | enabled | elevated | 1 |