docs(changeset): correct four statements in the pending enableOnInstall one-authority note (#19747)

Fixes #19735

## What this changes

Four statements in `.changeset/18605-enable-on-install-one-authority.md`
— a **pending, unreleased** fragment whose prose `changeset version`
publishes verbatim into `packages/spec/CHANGELOG.md`. One file, three
lines, `+3 / -3`. No other fragment and no other file in the tree is
touched, and the fragment's own `"@objectstack/spec": minor` header is
untouched.

The card named two of the four. The other two were found by the
re-derivation the card and the claim both demanded, and they are the
same defect in the same paragraph — a statement about the published
surface that the published surface no longer supports. Each of the four
is quoted old and new below, and the two extras are kept in their own
subsection so that what is being confirmed here is unambiguous.

## DELIBERATE CORRECTION — this is the written confirmation
`pr-automation.yml` route 0 requires, and `Check Changeset` is RED on
purpose

This PR **adds no changeset of its own**; it **changes a pending
changeset it did not add**. Route 0's discriminator, run against this
PR's merge base:

```
$ git diff --name-status 16d090e HEAD -- '.changeset/*.md'
M	.changeset/18605-enable-on-install-one-authority.md
```

Every row is `M`, none is `A` ⇒ route 0. The class is **DELIBERATE
CORRECTION, not COLLISION**: this PR did not draw that filename, nothing
of its own was overwritten, and the base copy must **not** be restored —
restoring it republishes the false sentences.
`check-empty-changeset.mjs` reaches the same reading on its own and
prints it in the job log unprompted.

| Route 0 prescribes | Here |
|---|---|
| ⛔ do **not** apply `skip-changeset` | Not applied, and it must not be:
the note corrected below is a release that is still pending, so the
label would be a false declaration. Ruling D on #18375 forbids it
outright for a PR that edits an existing changeset. |
| Write the confirmation on the PR, naming the note and what changed
under it | This section and the two that follow it. |
| Leave `Check Changeset` **RED** | It is red, deliberately. It is not
one of the seven required contexts, so its red blocks no merge. The red
is what puts this decision in front of a person. ⛔ Please do not turn it
green, and please do not read it as a failure — every *other* check
should be green. |

### The note

`.changeset/18605-enable-on-install-one-authority.md` —
`"@objectstack/spec": minor`, **pending**, added by commit `596090efbe`
(#19130) at 2026-09-20 10:43 UTC. `changeset version` deletes the
fragment and publishes its text verbatim into
`packages/spec/CHANGELOG.md`.

**The window is measured, not hypothetical.** `chore: version packages`
(**PR #17076**) is open right now and its file list carries `removed
.changeset/18605-enable-on-install-one-authority.md`. Whichever of the
two lands first decides whether the false sentences ship.

## What changed under it — old and new, verbatim

### The two the card named

**(1)** old — the kernel copy's read behaviour:

> Its published description now records that this layer does not read
it: the implementation reads `manifest` and `settings` only,

**(1)** new:

> Its published description now records what this layer does with it:
the implementation honours the key on the registry row (`true` enables,
`false` disables, an ABSENT key makes no lifecycle call at all, tested
`=== true` / `=== false` so absence is never collapsed into either),

The remainder of that sentence — "and the HTTP door does not forward the
key down that seam — it calls `installPackage({ manifest, settings })`
and performs the enable/disable flip itself, because the durable half
must follow the row that door returned rather than the request's intent"
— is **still true at `origin/main`** and is left byte-for-byte as
written.

**(2)** old:

> Same type, same default, same meaning,

**(2)** new:

> Same type, same optionality, same meaning,

### Two more, found by the re-derivation the claim demanded — ⚠️ not in
the card

These are the same class as (1) and (2): a statement about the published
surface that the published surface no longer supports, in the same
fragment, in the same release window, mechanically correctable to a form
already pinned in the tree, on a file no other open PR modifies. They
are called out separately so the confirmation above covers four
corrections knowingly rather than two plus two silent ones. ⛔ If the
seat prefers the card's exact two, (3) and (4) are a one-commit revert —
say so and they come out.

**(3)** old — the install door's rule:

> `POST /api/v1/packages` writes the registry row's `enabled` from
`enableOnInstall ?? true` (#18058)

**(3)** new:

> `POST /api/v1/packages` moves the registry row through the same verbs
`PATCH /packages/:id/enable` and `PATCH /packages/:id/disable` use:
`true` enables, `false` disables, and an ABSENT key makes no lifecycle
call at all, so the row the registry returned stands (#18058)

⭐ This one is the most consequential of the four, because it publishes
**a rule the maintainer re-ruled against**. `?? true` says an absent key
means enable; the live contract is 「缺省 = 保持，有旗 = 设置」 (maintainer ruling
batch #157 item 5 letter C). The tree already records that this exact
spelling is retired, in as many words —
`packages/objectql/src/protocol-install-package-enable-on-install.test.ts`
header: «The card that filed this work describes the target as
「`enableOnInstall ?? true` on install AND on re-install」. That sentence
was written before #19291 landed and it is SPENT: `?? true` on
re-install is precisely what the HTTP door stopped doing.» Publishing it
into a CHANGELOG would hand an upgrading reader the reading the repo
removed from its own declarations.

**(4)** old — a verbatim quotation of the authority's published
description:

> Its published description now says so: "honoured at POST
/api/v1/packages: the installed row's `enabled` is written from this
key".

**(4)** new:

> Its published description now says so, naming the door that honours
the key and the three states it honours.

The *claim* ("its published description now says so") is true; the
*quotation* is not — that tail no longer exists in the published string.
A verbatim quotation of a mutable published description is exactly the
shape that falls out of date, so the replacement names the mechanism
instead of quoting the string.

## Why these four are defects in the record and not dated readings

Every instrument below was read on **`origin/main` at `16d090ede0`**, at
2026-09-22T20:12Z–20:26Z. The card's own citations were treated as input
and re-derived at source, ⛔ never quoted.

| The statement's claim | Instrument at `16d090ede0` | Reading |
|---|---|---|
| (1) "this layer does not read it" |
`packages/metadata-protocol/src/protocol.ts:22785` | `const
requestedEnabled = request.enableOnInstall;` — the layer reads it. |
| (1) same | same file `:22786`–`:22792` | `if (requestedEnabled ===
true)` ⇒ `registry.enablePackage(manifest.id)`; `else if
(requestedEnabled === false)` ⇒ `registry.disablePackage(manifest.id)`;
no `else` ⇒ an absent key makes no lifecycle call. Never truthiness,
never `??`. |
| (1) "its published description records" that |
`packages/spec/src/kernel/package-registry.zod.ts:357` | The description
now reads "…this protocol primitive honours it on the registry row:
`true` enables, `false` disables, and ABSENT keeps the row's current
lifecycle state…" — the description states the opposite of the
fragment's report of it. |
| (1) tail: door does not forward, flips itself |
`packages/runtime/src/domains/packages.ts:1045`, `:1095`–`:1101`,
`:1145` | `protocolSvc.installPackage({ manifest, settings:
body.settings })` — no `enableOnInstall` in the call; then the door's
own `=== true` / `=== false` arms; then `setPackageDisabled(...)` for
the durable half. **Still true ⇒ left as written.** |
| (2) "same default" | `packages/spec/src/api/package-api.zod.ts:432`
and `packages/spec/src/kernel/package-registry.zod.ts:356` | Both are
`z.boolean().optional()`. Neither carries a default, so there is no
default to be "the same". What *is* the same, and is what the parity pin
holds, is the type, the optionality and the meaning. |
| (3) "`enableOnInstall ?? true`" |
`packages/runtime/src/domains/packages.ts:1095`–`:1101` | Three-state
arms, and the comment above them states the rule verbatim: "⚠️ `===
true` / `=== false`, never a truthiness test and never a `??` default".
|
| (3) same, at the fragment's own seeding commit | `git show
596090e:packages/runtime/src/domains/packages.ts`, `:819`–`:823` |
Already three-state **when the fragment was written**. `git log --all -S
"enableOnInstall ?? true"` finds the string in no source file in the
repo's history — only in prose. ⇒ (3) was false when written, not
overtaken. |
| (4) the quoted description tail |
`packages/spec/src/api/package-api.zod.ts:433` | The published string is
now "…honoured at POST /api/v1/packages: `true` enables the installed
row, `false` disables it, and ABSENT keeps the row's current lifecycle
state (a fresh install lands enabled)". The quoted tail "the installed
row's `enabled` is written from this key" is gone. |

**When each became false** — (1) and (2) were true when written and were
overtaken within the week; (3) was false when written; (4) was
overtaken. Either way the entry is release-notes input that has not
shipped yet, so it is amended where it stands: AGENTS.md's
release-artifact row rules that a factual error in a release-bound entry
is amended in that entry, ⛔ never by an erratum in a later entry and ⛔
never by a rider on code changes.

| Statement | True when written at `596090efbe`? | Falsified by |
|---|---|---|
| (1) | yes — the description then read "…this protocol primitive does
not read it" | `482d584121` (#19338, the primitive starts honouring it)
and `7e1b048a1d` (#19691, the description is rewritten) |
| (2) | yes — both were `z.boolean().default(true)` | `fb59fb5e37`
(#19690, both become `optional()`) |
| (3) | **no** — the door was already three-state at that commit | n/a;
false at seeding time |
| (4) | yes — the description then carried that exact tail | the same
rewrite that moved the api description to the three-state form |

All four replacements are **date-neutral**: they name the mechanism (the
three states and the verbs that apply them; the type/optionality/meaning
the parity pin holds) rather than a count, an enumeration or a quoted
string, so they stay true at `origin/main` and at publication alike.
"Same type, same optionality, same meaning" is in particular the
property `api/package-install-one-authority.test.ts` mechanically holds
— it parses both declarations over one matrix (absent, `false`, `true`,
a string, `null`) and reds on any cell where they disagree — so the
corrected sentence is kept true by a gate rather than by luck, which
"same default" never could be.

## What deliberately did NOT change

Every other byte of the fragment stays as written, and these in
particular were re-derived and **deliberately left**:

- Past tense, describing the **pre-#18605 state**, and true of it:

> What was left was three declarations that looked identical
(`z.boolean().default(true)`, same description)

Verified: both declarations really were `z.boolean().default(true)` at
`596090efbe`. A dated record's job is to say what was true when it was
made, so overwriting it would falsify history rather than correct a
record.
- A **scope statement about what #18605's own change did**, not a claim
about today's declarations:

> No key is added, removed, renamed or retyped, and no default changes:
the accept set of all three schemas is byte-for-byte what it was, and
`api-surface`, `authorable-surface` and `authorable-defaults` are all
unchanged.

True of that change then, and still true of it now. The later removal of
the defaults was a different change (#19273, #19690) carrying its own
notes.
- The whole **parity-pin paragraph** — re-derived and it stands:
`api/package-install-one-authority.test.ts` exists and pins the
five-cell matrix named there, and the `OS_EAGER_SCHEMAS=1` cycle it
describes is restated verbatim in `kernel/package-registry.zod.ts`'s own
doc block.
- The whole **marketplace paragraph** — re-derived and it stands:
`MarketplaceInstallRequestSchema`'s subject fields are `listingId`
(`marketplace.zod.ts:481`), `version`, `licenseKey` (`:487`) and
`tenantId` (`:545`), and its own description names itself "the
marketplace channel's own install option, not the platform install-door
key".
- The opening line's "declared in three published schemas" — re-derived:
`grep -rn "enableOnInstall: z" packages/spec/src/` returns exactly three
declarations, and each names the authority in its own description.
- The `"@objectstack/spec": minor` header and the `Clause-②: yes` line.

## Verification

Gate families derived from **this worktree**, ⛔ never from the shared
checkout:

```
node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands
```

It derived **19** families at commit `fbb8952c3e`, and confirmed the
`--repo` assertion against this checkout's `origin`. All 19 were run,
each exit code captured **before any pipe**, recorded as `command ::
exit code`, and reconciled:

```
✓ dispatch-gates --ran: 19 derived famil(ies) accounted for — 19 run,
  0 NOT-MEASURED (a DERIVED zero — all 19 recorded an exit code and none of them is 3).
```

**18 of 19 exit 0.** The one non-zero is the expected one:

- `node scripts/check-empty-changeset.mjs --base origin/main` — **exit
1, the route-0 red**. Its output names this PR's class as DELIBERATE
CORRECTION on its own and ends: "this gate stays red either way, and
staying red is what puts the decision in front of a person instead of
routing around it."

Run in addition, because `dispatch-gates` flagged that this family's
roster lives under `.changeset`, which is where this PR's only path is:

- `node scripts/check-changeset-fixed.mjs` — exit 0,
"`.changeset/config.json` "fixed" group is in sync with 70 public
workspace packages" (a verdict over a real population, not a vacuous
green).

**Repo-wide `pnpm lint` narrowed to this diff, and the narrowing proven
rather than asserted** — all three readings, so the narrowing is a
measurement and not a skip:

1. **Population, read from eslint's own predicate**, not guessed. On one
`ESLint({ cwd })` instance:
`isPathIgnored('.changeset/18605-enable-on-install-one-authority.md')`
is `true`, and the positive control
`isPathIgnored('scripts/check-nul-bytes.mjs')` is `false` — so the
predicate is shown able to answer either way. Every `files` glob in
`eslint.config.mjs` names TS/JS extensions only
(`**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}` and four narrower TS-only
globs), and a case-insensitive count of `markdown` or the markdown
extension in that config is **0**.
2. **File count, read from the `--format json` shape**: `lintFiles` over
both paths returns 2 entries; the changed path's entry is `errorCount 0,
warningCount 1` whose only message is "File ignored because no matching
configuration was supplied" — zero rules evaluated — while the control
path's entry is a genuinely linted `errorCount 0, warningCount 0` with
no ignore message.
3. **Invariance for untouched files**: the one changed path is in no
eslint population at all and no markdown processor is configured, so
this diff hands nothing to a parser and cannot move any untouched file's
verdict. Type-aware linting does not enter into it — the file is never
parsed.

**No package build, test or typecheck is owed**: the diff touches one
`.changeset/*.md` file and no package source, so there is no
affected-package closure to build and no package's public surface moves.
`dispatch-gates` independently reports the change set as 1 path, `+3 /
-3`, 6 changed lines.

**Control characters** — `grep -naP '[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]'`
over the changed file exits 1 (no hits), with the same pattern exiting 0
on a seeded BEL control file in the same run, and a near-miss class
(`[\x09]`) exiting 1 on that same control file so the class is doing the
discriminating. `pnpm check:nul-bytes` exits 0.

**Every zero above carries its controls.** On the `grep -c -F`
instrument over the changed file, at `fbb8952c3e` / 2026-09-22T20:26Z:
firing controls `same optionality` = 1 and `honours the key on the
registry row` = 1 (the subject is alive on this instrument);
measurements `enableOnInstall ?? true` = 0, `Same type, same default` =
0, `this layer does not read it` = 0, `is written from this key` = 0;
dark controls `same optionalities` = 0 and `enableOnInstall ?? false` =
0.

## Acceptance notes

Observations found while verifying, deliberately **not** acted on and
**not** filed:

- **The dispatch and the claim both describe the fragment's header as
`"@objectstack/spec": patch`; at source it is `minor`.** Re-derived at
`16d090ede0`: line 2 is `"@objectstack/spec": minor`. The header is not
this PR's to change either way, `check-changeset-no-major` exits 0 on
it, and the discrepancy is an input-vs-source one rather than a defect
in the tree. Recorded only so a re-measurer does not read it as drift.
- **The card's line numbers drift against `origin/main`, substance
identical.** The card cites `protocol.ts:22773–22779`; the arms are at
`:22785`–`:22792`. It cites `package-api.zod.ts:434`; the declaration is
at `:432`. `package-registry.zod.ts:356` is exact. Noted only so a
re-measurer does not read the drift as disagreement — this is precisely
why the claim demanded re-derivation.
- **The retired `?? true` spelling appears nowhere else in the repo's
release-bound prose.** `git grep -n "enableOnInstall ?? true"` at
`16d090ede0` returns exactly two carriers besides this fragment, both of
which are *about* the spelling being retired rather than asserting it:
`packages/objectql/src/protocol-install-package-enable-on-install.test.ts:23`
and `:188`. No other `.changeset/*.md` carries it. Carrier: none needed.

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

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

Author: os-support-ai

.changeset/18605-enable-on-install-one-authority.md

@@ -4,17 +4,17 @@
 
 `enableOnInstall` is declared in three published schemas; each one now says which of the three governs it, and the two that are not the authority say what they are (#18605).
 
-The install door already honours the key — `POST /api/v1/packages` writes the registry row's `enabled` from `enableOnInstall ?? true` (#18058). What was left was three declarations that looked identical (`z.boolean().default(true)`, same description) with nothing saying which one an author should read.
+The install door already honours the key — `POST /api/v1/packages` moves the registry row through the same verbs `PATCH /packages/:id/enable` and `PATCH /packages/:id/disable` use: `true` enables, `false` disables, and an ABSENT key makes no lifecycle call at all, so the row the registry returned stands (#18058). What was left was three declarations that looked identical (`z.boolean().default(true)`, same description) with nothing saying which one an author should read.
 
 Clause-②: yes
 
 **The authority**
 
-`PackageInstallRequestSchema` (`api/package-api.zod.ts`) is the one authority, because it is the request contract of the door that honours the key. Its published description now says so: "honoured at POST /api/v1/packages: the installed row's `enabled` is written from this key". Its doc block carries the map to the other two, so a reader never has to guess which of three identical-looking declarations governs.
+`PackageInstallRequestSchema` (`api/package-api.zod.ts`) is the one authority, because it is the request contract of the door that honours the key. Its published description now says so, naming the door that honours the key and the three states it honours. Its doc block carries the map to the other two, so a reader never has to guess which of three identical-looking declarations governs.
 
 **`kernel/InstallPackageRequest.enableOnInstall` — a COPY of the request key**
 
-Same type, same default, same meaning, restated on the in-process protocol primitive `ObjectStackProtocol.installPackage`. Its published description now records that this layer does not read it: the implementation reads `manifest` and `settings` only, and the HTTP door does not forward the key down that seam — it calls `installPackage({ manifest, settings })` and performs the enable/disable flip itself, because the durable half must follow the row that door returned rather than the request's intent.
+Same type, same optionality, same meaning, restated on the in-process protocol primitive `ObjectStackProtocol.installPackage`. Its published description now records what this layer does with it: the implementation honours the key on the registry row (`true` enables, `false` disables, an ABSENT key makes no lifecycle call at all, tested `=== true` / `=== false` so absence is never collapsed into either), and the HTTP door does not forward the key down that seam — it calls `installPackage({ manifest, settings })` and performs the enable/disable flip itself, because the durable half must follow the row that door returned rather than the request's intent.
 
 The copy is held to the authority by a **parity pin** rather than by a structural reference. The structural spelling is not available in this direction: the authority is built from `ManifestSchema` and `InstalledPackageSchema`, both declared in `kernel/package-registry.zod.ts`, so `PackageInstallRequestSchema.shape.enableOnInstall` spelled there is an import cycle, and under `OS_EAGER_SCHEMAS=1` — the mode `gen:schema` and `check:authorable-surface` run in — it dies with `ReferenceError: Cannot access 'InstalledPackageSchema' before initialization`. `api/package-install-one-authority.test.ts` parses both declarations over one matrix (absent, `false`, `true`, a string, `null`) and reds on any cell where they disagree.