You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit d3a2331
Browse filesBrowse the repository at this point in the historyBrowse files
fix(spec,core): ADR-0049 tombstones name the npm release that carries the removal, and a gate keeps them there (#19655)
Fixes#18048
Clause-②: no
ADR-0049 tombstones, refusal strings and doc pages across fifteen files
dated a removal to the next npm major of `@objectstack/spec` — a bare
**18** attached to the package name. There is no npm 18, and under
ADR-0087's level ruling (Amended 2026-09-13) there will not be one as
the carrier: *"A tombstone names the npm release it ships in, ⛔ never
the protocol major […] a retirement shipping `minor` lands in
`17.x.y`"*. A sibling repository had already hung a cleanup schedule on
"the PR that pushes the spec package to its next major" — an event that
will never come.
This is the class's **second** appearance. Ten sites of it were
corrected by hand in July with no gate, and that card closed
`completed`. So the prose fix is half of this PR; the other half is
`pnpm check:future-spec-major`.
## What replaces the bad number, and why it is two answers
Determined **per site** from `packages/spec/CHANGELOG.md`, never pasted.
The sites split cleanly, and the two halves take different spellings
because different things are known about them.
**Already shipped ⇒ the release that actually carries it — `17.3.0`**
(published on npm; `npm view @objectstack/spec versions` ends `…17.2.0,
17.3.0, 17.4.0`). Eighteen hand sites plus four generated rows:
| retirement | changeset in `CHANGELOG.md` | release |
|:--|:--|:--|
| `PluginHealthCheck.autoRestart` / `maxRestartAttempts` /
`restartBackoff` | `b72db01` | `17.3.0` |
| `HotReloadConfig.stateStrategy: 'disk'`/`'distributed'`,
`distributedConfig` | `4635f3e` | `17.3.0` |
| `HotReloadConfig.watchPatterns` | `ee3595c` | `17.3.0` |
| form-view `options[].default` | `c459da6` | `17.3.0` |
This is the version an upgrading reader greps in `CHANGELOG.md` after
the tombstone error, which is exactly what the changeset-to-CHANGELOG
contract exists to make findable.
**Not shipped yet ⇒ the bare published major, `17`.** Eleven hand sites
plus three generated rows, covering three removals that are still
unreleased changesets on this branch:
| retirement | pending changeset |
|:--|:--|
| the seven cron-typed positions (export schedules,
`ScheduleState.cronExpression`, `DataSyncConfig.schedule`,
`CacheWarmup.schedule`, backup / DR-test schedules) |
`.changeset/cron-typed-positions-retired.md` |
| `CacheWarmup.strategy: 'scheduled'` |
`.changeset/17157-cache-warmup-scheduled-strategy-retired.md` |
| `PluginStartupResult.startTime` / `plugin` / `health` |
`.changeset/16059-startup-orchestrator-shipped-shape.md` |
For these the carrier minor is **unknown at authoring time**, so any
digit is a guess — the same guess that produced this defect. Bare `17`
is the one spelling that is true, exists, and cannot go stale:
1. **It asserts exactly what is known.** Each of those three changesets
declares `minor`, and ADR-0087 guarantees a pre-GA retirement ships
`minor`, so the carrier is necessarily some `17.x.y`. The major is a
fact; the minor is not.
2. **It names a version that exists.** Bare `17` is the published major.
3. **It is the house form.** 588 bare-`17` citations sit in the tree,
measured with this PR's own matcher.
4. **It is what the ledger prescribes.** `docs/v17-docs-sweep.md` run 3
fixed "17 passages dating v17 removals to 18 → **17**" — bare, not a
guessed minor — and that row is this class's detection fingerprint.
5. **It cannot seed a fourth recurrence.** A guessed `17.5.0` goes stale
the moment the minor count moves; bare `17` does not.
6. **The neighbours already read that way.**
`startup-orchestrator.zod.ts`'s own surviving `duration` → `durationMs`
tombstone says bare `@objectstack/spec 17`, three lines from the three
this PR rewrites.
⛔ **No protocol-major reference is altered.** `toMajor: 18`, `step18`
and the `PROTOCOL_VERSION` ladder are correct and untouched — nothing
here matches a number that is not directly attached to the package name,
so "retired in protocol major 18" is out of reach by construction.
Untouched-control: `git grep -c 'toMajor: 18'` and `git grep -c
'step18'` read the same before and after.
## The gate — `pnpm check:future-spec-major`
`scripts/check-future-spec-major.mjs`, registered in the root
`package.json` and wired into `lint.yml` (the gate step and the
`--self-test` invocation `check:self-test-wired` requires; that gate
reads 0 findings over 223 scripts).
**The class is derived at runtime**, never hardcoded: "an
`@objectstack/spec` version whose major is above the major in
`packages/spec/package.json`". A gate hardcoding the literal goes
dormant the day the tree reaches that major, and the next stale
tombstone will name the one after.
**It joins the joints before matching**, because a single-line matcher
reads a false zero on live sites. `packages/core/src/health-monitor.ts`
splits the phrase as `"… in @objectstack/spec " + '18 (#12032, …'`;
there are JSDoc `*` continuations and plain wraps too. **And it reads
the backticked package name** — `` `@objectstack/spec` 18 `` in the same
file and in `content/docs/protocol/kernel/lifecycle.mdx` — which is a
second, independent way to read zero.
**The gap is bounded to a sentence continuation.** Exactly one space on
the same line, or a line break crossed through recognised joint syntax
(a closing quote, a `+`, a JSDoc `*`, indentation). A run of two or more
spaces or a tab is column alignment, never prose, so
`scripts/partition-test-shards.mjs`'s `@objectstack/spec 414 files
496.4s` is not a finding. That bound has its own self-test fixture,
carrying that row verbatim.
**Two exemption mechanisms, and neither is a path allowlist.** Three
sites cite the bad number in order to forbid it, and a gate that cannot
tell a tombstone from a quotation of a bad tombstone reds on the ruling
that forbids the bug.
- **R1, structural.** A citation wholly inside a Markdown
**double**-backtick code span is the phrase quoted as a PATTERN, which
is what a fingerprint row is — so `docs/v17-docs-sweep.md`'s table row
needs no ledger entry, and neither will the next fingerprint row. A
**single**-backtick span is not exempt; that is the live tombstone form.
- **R2, a witnessed self-invalidating ledger.** Each entry names a file,
the major it excuses, a `witness` regex that must still match the
quoting sentence, a pinned `covers` count, and a written `why` the
failure text prints. A path allowlist says "this file may say anything";
this says "this file may say exactly this, and must still say it". Three
refusals follow, each with its own battery: a **new** citation in an
exempt file matches no witness and reds; a witness that matches nothing
reds (editing the quotation away kills its exemption instead of leaving
a hole); a `covers` count that moves reds.
**The detector is excluded from its own corpus** — it documents the
class in its header and holds the adversarial fixtures in its self-test,
so it cites the bad form by necessity. ⛔ That would be a hole, so it
comes with a compensating control in the opposite direction: the file
MUST still carry at least `SELF_FIXTURE_FLOOR` citations above the
published major. Gut the fixtures — the one edit the exclusion would
otherwise hide — and the gate reds on itself.
**The self-test is the only instrument watching the rule**, because this
gate's defect class *is* its matching rule: green means the finding set
is empty, weakening can only shrink that set, and the empty set is the
fixed point of shrinking. 29 batteries with a pinned roster, a floor and
the module-flag handshake, including the wrapped fixture, the backticked
fixture, a fenced-code fixture, the column-aligned bound, a legitimate
bare-17 fixture that must pass, a derived-class fixture (the same corpus
goes green once the manifest says 18), and an empty-corpus refusal.
## Census, under the gate's own instrument
Re-runnable at this head:
```
node scripts/check-future-spec-major.mjs --census
```
| reading | before (`34545d6c6c`) | after |
|:--|--:|--:|
| live sites above the published major | 39 / 17 files | **0** |
| bare `18` remaining (all exempt quotations) | 39 / 17 files | 3 / 2
files |
| bare `17` control | 588 / 174 files | 602 / 176 files |
| dotted `17.x` control | 489 / 106 files | 511 / 113 files |
The bare-17 control moving is the fix landing, not over-matching:
fourteen of this PR's rewrites add a bare-`17` citation, and the dotted
bucket gains the twenty-two that now say `17.3.0`. Over an unchanged
file the matcher's verdict does not move.
## Verification
- `pnpm --filter @objectstack/spec test` — 511 files / 14933 tests pass.
`pnpm --filter @objectstack/core test` — 51 files / 1321 tests pass.
Both matter here: `health-monitor.test.ts` and `hot-reload.test.ts` pin
those guidance strings **by content**.
- `pnpm --filter @objectstack/spec --filter @objectstack/core typecheck`
— green.
- `pnpm --filter @objectstack/spec check:generated` — all 15 generated
artifacts up to date; `check:docs` green. The seven sites in
`content/docs/references/kernel/{plugin-lifecycle-advanced,startup-orchestrator}.mdx`
were **regenerated**, never hand-edited: the zod docblocks and
`retiredKey()` prescriptions moved and `gen:docs` projected them.
- `node scripts/pm/dispatch-gates.mjs --ran` — 151 derived families
accounted for, 148 run, 3 NOT MEASURED, 0 unrun. The three are named in
the report: two exit 3 (`PREREQUISITE NOT MET`, both needing a
whole-tree `pnpm build`) and `check:pm-dispatch-gates`, whose own
self-test is a recorded 597 s in `lint.yml` against this container's
~600 s foreground cap.
- **ESLint, narrowed and the narrowing proved.** Population read from
eslint's own config: 6992 tracked files with lintable extensions, none
globally ignored per its `isPathIgnored`. Linted: 12 files, the count
read from `--format json`, 0 errors / 0 warnings. Invariance:
`eslint.config.mjs` never enables type-aware linting for any file — zero
`parserOptions.project` and zero `projectService` in it, which its own
header states and measured with a positive control — so every verdict
depends only on that file's bytes plus the shared config. This PR
changes neither the config nor a byte of the other 6980 files, so no
untouched file's verdict can move. Quoted from `68ff8a1082`.
## Clause-②, measured rather than argued
Every affected string is a docblock, a doc page, or a `retiredKey()` /
`guidance` **message**. The key is refused before and after, so no
accept/reject result moves for any input. The control that decides it:
the phrase has **0 hits** across `packages/*/api-surface` and
`packages/*/export-origins`, so no published declaration baseline
carries these sentences and none moves. `node
scripts/check-changeset-no-major.mjs --base origin/main` is green; the
`--pair` C6 row is in the report.
Changeset grades `@objectstack/spec` and `@objectstack/core`, both
`patch`. `packages/core` is in scope although the card is anchored
`domain:spec`: the triage ruling makes the gate tree-wide, and a
tree-wide gate cannot be green on `main` while 11 live sites remain in
`packages/core` — six of them runtime refusal strings an operator reads.
## Acceptance notes
- **One bounded in-place fix, declared.**
`packages/spec/src/kernel/plugin-lifecycle-advanced.zod.ts` carried a
docblock reading "the watch-placeholder key retired in **18**" — the
same stale number, the same defect class, but with no package name
attached, so it is outside the card's stated class and outside this
gate's matcher by construction. It is now `17.3.0`, matching the
prescription three lines below it that this PR also rewrites. Evidence:
`git diff` on that file shows the two edits adjacent; the key's removal
is `ee3595c` in the `17.3.0` section of `packages/spec/CHANGELOG.md`.
- **Deliberately not changed.** `startup-orchestrator.zod.ts`'s
`duration` → `durationMs` tombstone says bare `@objectstack/spec 17` for
a rename that shipped in `17.4.0`. Bare `17` is correct and legitimate —
less specific than it could be, not wrong — so it is not in this card's
class and is left alone.
- **Two measurement readings are declared in the ledger, not
rewritten.** `packages/spec/src/migrations/{registry.ts,
entries/semantic/…}` record "controls objectstack 12966 and
`@objectstack/spec` 4997 on the same corpus" and `docs/adr/0021-…md`
records a `6526/6526` pass ratio. Those numbers are hit counts, not
versions, and they sit exactly one space after the package name, so no
whitespace rule can distinguish them from a citation. Rather than narrow
the matcher — the move that produces a false zero — they carry witnessed
`kind: 'measurement'` ledger entries.
- **Serial note.** #19598 (draft) touches
`packages/spec/src/ui/view.zod.ts` at hunks well clear of the site here,
which is on line 2780. Re-derived on this branch after merging
`origin/main`: no textual conflict.
---
_Generated by [Claude
Code](https://claude.ai/code/session_01AmH9bKvGoLjiY86Q4Z3og2)_
---------
Co-authored-by: Claude <noreply@anthropic.com>
|**watchPatterns**|`never`| optional |[REMOVED]`HotReloadConfig.watchPatterns` was removed in @objectstack/spec18 (ADR-0049 enforce-or-remove) — nothing ever read it. Its only two uses were log lines in `HotReloadManager`, and one of them announced 'File watching started' at INFO level while no watcher was ever constructed: `startWatching` held a placeholder, and `watchHandles` was read, deleted, iterated and cleared but never set. So an author could declare a glob and no file change could ever trigger a reload. Delete the key. File watching is the HOST's job in this host-driven library: run your own watcher, declare your globs wherever that watcher reads them, and call `HotReloadManager.scheduleReload(pluginName, reloadFn)` when one matches — the debounced integration point this class does implement, and which is unchanged. |
44
+
|**watchPatterns**|`never`| optional |[REMOVED]`HotReloadConfig.watchPatterns` was removed in @objectstack/spec17.3.0 (ADR-0049 enforce-or-remove) — nothing ever read it. Its only two uses were log lines in `HotReloadManager`, and one of them announced 'File watching started' at INFO level while no watcher was ever constructed: `startWatching` held a placeholder, and `watchHandles` was read, deleted, iterated and cleared but never set. So an author could declare a glob and no file change could ever trigger a reload. Delete the key. File watching is the HOST's job in this host-driven library: run your own watcher, declare your globs wherever that watcher reads them, and call `HotReloadManager.scheduleReload(pluginName, reloadFn)` when one matches — the debounced integration point this class does implement, and which is unchanged. |
45
45
|**debounceDelayMs**|`integer`| optional (default: `1000`) | Wait time after change detection before reload, in milliseconds |
46
46
|**debounceDelay**|`never`| optional |[REMOVED]`HotReloadConfig.debounceDelay` was renamed to `debounceDelayMs` in @objectstack/spec 17 — the unit of a duration-shaped number lives in the key name, not only in the describe prose. Its unit (milliseconds) lived in a source JSDoc only and the published describe named none, so the reference-page reader got a bare 1000. Rename the key to `debounceDelayMs`; the value (milliseconds) and the 1000 default are unchanged. |
47
47
|**preserveState**|`boolean`| optional (default: `true`) | Keep plugin state across reloads |
@@ -64,9 +64,9 @@ const result = HotReloadConfigSchema.parse(data);
64
64
|**failureThreshold**|`integer`| optional (default: `3`) | Consecutive failures needed to mark unhealthy |
65
65
|**successThreshold**|`integer`| optional (default: `1`) | Consecutive successes needed to mark healthy |
66
66
|**checkMethod**|`string`| optional | Method name to call for health check |
67
-
| **autoRestart** | `never` | optional | [REMOVED] `PluginHealthCheck.autoRestart` was removed in @objectstack/spec 18 (ADR-0049 enforce-or-remove) — it never restarted a plugin.A `PluginHealthMonitor` never restarted anything. `attemptRestart` called `plugin.destroy()` and stopped there — the in-source comment said "Call destroy and init to restart", but `init` appeared in `health-monitor.ts` ONLY inside that comment. What a plugin actually got was: destroy, a log line reading 'Plugin restarted', status `recovering`, and periodic health checks continuing against the destroyed instance — which the default check (`{ name: 'plugin-loaded', status: 'passed' }`, used whenever no `checkMethod` resolves) passes forever, so the terminal report on a destroyed, never-re-initialised plugin was `healthy`. Delete the key. Restarting a plugin is the HOST's job in this host-driven library, and the monitor could not do it even in principle: `Plugin.init(ctx)` needs a `PluginContext`, which only the kernel constructs and which it exposes to nobody (`ObjectKernel.context` is private; `KernelBase.createContext` is protected). Poll `getHealthStatus(pluginName)` / `getHealthReport(pluginName)` and act on `unhealthy` / `failed` at the level that owns the plugin's lifetime — recreate the kernel, or let your supervisor restart the process. The monitor reports; it does not act. |
68
-
| **maxRestartAttempts** | `never` | optional | [REMOVED] `PluginHealthCheck.maxRestartAttempts` was removed in @objectstack/spec 18 (ADR-0049 enforce-or-remove) — it capped a restart that never happened.A `PluginHealthMonitor` never restarted anything. `attemptRestart` called `plugin.destroy()` and stopped there — the in-source comment said "Call destroy and init to restart", but `init` appeared in `health-monitor.ts` ONLY inside that comment. What a plugin actually got was: destroy, a log line reading 'Plugin restarted', status `recovering`, and periodic health checks continuing against the destroyed instance — which the default check (`{ name: 'plugin-loaded', status: 'passed' }`, used whenever no `checkMethod` resolves) passes forever, so the terminal report on a destroyed, never-re-initialised plugin was `healthy`. The cap counted destroy calls, so raising it only scheduled further "restarts" of a plugin that was never brought back up. Delete the key. Restarting a plugin is the HOST's job in this host-driven library, and the monitor could not do it even in principle: `Plugin.init(ctx)` needs a `PluginContext`, which only the kernel constructs and which it exposes to nobody (`ObjectKernel.context` is private; `KernelBase.createContext` is protected). Poll `getHealthStatus(pluginName)` / `getHealthReport(pluginName)` and act on `unhealthy` / `failed` at the level that owns the plugin's lifetime — recreate the kernel, or let your supervisor restart the process. The monitor reports; it does not act. |
69
-
| **restartBackoff** | `never` | optional | [REMOVED] `PluginHealthCheck.restartBackoff` was removed in @objectstack/spec 18 (ADR-0049 enforce-or-remove) — it delayed a restart that never happened.A `PluginHealthMonitor` never restarted anything. `attemptRestart` called `plugin.destroy()` and stopped there — the in-source comment said "Call destroy and init to restart", but `init` appeared in `health-monitor.ts` ONLY inside that comment. What a plugin actually got was: destroy, a log line reading 'Plugin restarted', status `recovering`, and periodic health checks continuing against the destroyed instance — which the default check (`{ name: 'plugin-loaded', status: 'passed' }`, used whenever no `checkMethod` resolves) passes forever, so the terminal report on a destroyed, never-re-initialised plugin was `healthy`. The chosen strategy only moved when the destroy landed. Delete the key. Restarting a plugin is the HOST's job in this host-driven library, and the monitor could not do it even in principle: `Plugin.init(ctx)` needs a `PluginContext`, which only the kernel constructs and which it exposes to nobody (`ObjectKernel.context` is private; `KernelBase.createContext` is protected). Poll `getHealthStatus(pluginName)` / `getHealthReport(pluginName)` and act on `unhealthy` / `failed` at the level that owns the plugin's lifetime — recreate the kernel, or let your supervisor restart the process. The monitor reports; it does not act. |
67
+
| **autoRestart** | `never` | optional | [REMOVED] `PluginHealthCheck.autoRestart` was removed in @objectstack/spec 17.3.0 (ADR-0049 enforce-or-remove) — it never restarted a plugin.A `PluginHealthMonitor` never restarted anything. `attemptRestart` called `plugin.destroy()` and stopped there — the in-source comment said "Call destroy and init to restart", but `init` appeared in `health-monitor.ts` ONLY inside that comment. What a plugin actually got was: destroy, a log line reading 'Plugin restarted', status `recovering`, and periodic health checks continuing against the destroyed instance — which the default check (`{ name: 'plugin-loaded', status: 'passed' }`, used whenever no `checkMethod` resolves) passes forever, so the terminal report on a destroyed, never-re-initialised plugin was `healthy`. Delete the key. Restarting a plugin is the HOST's job in this host-driven library, and the monitor could not do it even in principle: `Plugin.init(ctx)` needs a `PluginContext`, which only the kernel constructs and which it exposes to nobody (`ObjectKernel.context` is private; `KernelBase.createContext` is protected). Poll `getHealthStatus(pluginName)` / `getHealthReport(pluginName)` and act on `unhealthy` / `failed` at the level that owns the plugin's lifetime — recreate the kernel, or let your supervisor restart the process. The monitor reports; it does not act. |
68
+
| **maxRestartAttempts** | `never` | optional | [REMOVED] `PluginHealthCheck.maxRestartAttempts` was removed in @objectstack/spec 17.3.0 (ADR-0049 enforce-or-remove) — it capped a restart that never happened.A `PluginHealthMonitor` never restarted anything. `attemptRestart` called `plugin.destroy()` and stopped there — the in-source comment said "Call destroy and init to restart", but `init` appeared in `health-monitor.ts` ONLY inside that comment. What a plugin actually got was: destroy, a log line reading 'Plugin restarted', status `recovering`, and periodic health checks continuing against the destroyed instance — which the default check (`{ name: 'plugin-loaded', status: 'passed' }`, used whenever no `checkMethod` resolves) passes forever, so the terminal report on a destroyed, never-re-initialised plugin was `healthy`. The cap counted destroy calls, so raising it only scheduled further "restarts" of a plugin that was never brought back up. Delete the key. Restarting a plugin is the HOST's job in this host-driven library, and the monitor could not do it even in principle: `Plugin.init(ctx)` needs a `PluginContext`, which only the kernel constructs and which it exposes to nobody (`ObjectKernel.context` is private; `KernelBase.createContext` is protected). Poll `getHealthStatus(pluginName)` / `getHealthReport(pluginName)` and act on `unhealthy` / `failed` at the level that owns the plugin's lifetime — recreate the kernel, or let your supervisor restart the process. The monitor reports; it does not act. |
69
+
| **restartBackoff** | `never` | optional | [REMOVED] `PluginHealthCheck.restartBackoff` was removed in @objectstack/spec 17.3.0 (ADR-0049 enforce-or-remove) — it delayed a restart that never happened.A `PluginHealthMonitor` never restarted anything. `attemptRestart` called `plugin.destroy()` and stopped there — the in-source comment said "Call destroy and init to restart", but `init` appeared in `health-monitor.ts` ONLY inside that comment. What a plugin actually got was: destroy, a log line reading 'Plugin restarted', status `recovering`, and periodic health checks continuing against the destroyed instance — which the default check (`{ name: 'plugin-loaded', status: 'passed' }`, used whenever no `checkMethod` resolves) passes forever, so the terminal report on a destroyed, never-re-initialised plugin was `healthy`. The chosen strategy only moved when the destroy landed. Delete the key. Restarting a plugin is the HOST's job in this host-driven library, and the monitor could not do it even in principle: `Plugin.init(ctx)` needs a `PluginContext`, which only the kernel constructs and which it exposes to nobody (`ObjectKernel.context` is private; `KernelBase.createContext` is protected). Poll `getHealthStatus(pluginName)` / `getHealthReport(pluginName)` and act on `unhealthy` / `failed` at the level that owns the plugin's lifetime — recreate the kernel, or let your supervisor restart the process. The monitor reports; it does not act. |
70
70
|**interval**|`never`| optional |[REMOVED]`PluginHealthCheck.interval` was renamed to `intervalMs` in @objectstack/spec 17 — the unit of a duration-shaped number lives in the key name, not only in the describe prose. Its unit (milliseconds) lived in a source JSDoc only, and the published describe named no unit: its one unit-shaped token was the parenthetical "(default: 30s)", which names SECONDS for a value carried in milliseconds. Rename the key to `intervalMs`; the value (milliseconds) and the 30000 default are unchanged. |
71
71
|**timeout**|`never`| optional |[REMOVED]`PluginHealthCheck.timeout` was renamed to `timeoutMs` in @objectstack/spec 17 — the unit of a duration-shaped number lives in the key name, not only in the describe prose. Its unit (milliseconds) lived in a source JSDoc only and the published describe named none, so the reference-page reader got a bare 5000. Rename the key to `timeoutMs`; the value (milliseconds) and the 5000 default are unchanged. |
0 commit comments