Skip to content

Commit d3a2331

Browse files
os-steveclaude
andauthored
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>
1 parent 8f30c18 commit d3a2331

19 files changed

Lines changed: 1165 additions & 37 deletions
Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
---
2+
'@objectstack/spec': patch
3+
'@objectstack/core': patch
4+
---
5+
6+
fix(spec,core): every ADR-0049 tombstone names the npm release that actually carries its removal, and a gate keeps it that way (#18048)
7+
8+
Clause-②: no
9+
10+
Thirty-six sites across fifteen files dated a removal to the next npm major of
11+
`@objectstack/spec` — a bare **18** attached to the package name.
12+
There is no npm 18, and under ADR-0087's level ruling (Amended 2026-09-13) there
13+
will not be one as the carrier for a retirement: *"A tombstone names the npm
14+
release it ships in, ⛔ never the protocol major […] a retirement shipping
15+
`minor` lands in `17.x.y`"*. An author who met one of these was sent to a
16+
version that does not exist. A sibling repository had already hung a cleanup
17+
schedule on "the PR that pushes the spec package to its next major" — an event
18+
that will never come.
19+
20+
**The number was determined per site from `packages/spec/CHANGELOG.md`, not
21+
pasted.** The sites split cleanly in two, and the two halves take different
22+
spellings because different things are known about them:
23+
24+
- **Already shipped ⇒ the release that carries it.** The three
25+
`PluginHealthCheck` restart keys (`b72db01`), `HotReloadConfig.stateStrategy`
26+
/ `distributedConfig` (`4635f3e`), `HotReloadConfig.watchPatterns`
27+
(`ee3595c`) and the form-view `options[].default` narrowing (`c459da6`) all
28+
landed in **`17.3.0`**, which is published. These say `17.3.0` — the version
29+
an upgrading reader greps in the CHANGELOG.
30+
- **Not shipped yet ⇒ the bare published major `17`.** The seven cron-typed
31+
positions, the `scheduled` cache-warmup strategy and the three
32+
`PluginStartupResult` members are still unreleased changesets, so the carrier
33+
minor is unknown at authoring time and any digit would be a guess — the same
34+
guess that produced this defect. ADR-0087 guarantees the major: a pre-GA
35+
retirement ships `minor`, so the carrier is some `17.x.y`. Bare `17` asserts
36+
exactly what is known, cannot go stale as minors accumulate, and is the house
37+
form already on 588 other sites.
38+
39+
**Why `Clause-②: no`.** Every affected string is a docblock, a doc page, or a
40+
`retiredKey()` / `guidance` MESSAGE. The key is refused before and after, so the
41+
accept/reject result does not move for any input. The control that decides it:
42+
the phrase has 0 hits across `packages/*/api-surface` and
43+
`packages/*/export-origins`, so no published declaration baseline carries these
44+
sentences and none moves.
45+
46+
**No protocol-major reference is altered.** `toMajor: 18`, `step18` and the
47+
`PROTOCOL_VERSION` ladder are correct and untouched — ADR-0087: *"the two move
48+
independently"*.
49+
50+
**Three sites are deliberately left saying 18**, because they quote the wrong
51+
number in order to forbid it: the ADR-0087 ruling itself, and the two
52+
`docs/v17-docs-sweep.md` rows that carry this class's detection fingerprint.
53+
Four more say `99` on purpose — a synthetic "next major" fixture that must name
54+
a version that does not exist.
55+
56+
**A gate lands with the prose**, because this is the class's second appearance:
57+
ten sites of it were corrected by hand in July with no gate, and the card closed
58+
`completed`. `pnpm check:future-spec-major` derives the class from
59+
`packages/spec/package.json` at runtime — a major above the published one, never
60+
a hardcoded 18 — joins string-concatenation, JSDoc and plain-wrap line breaks
61+
before matching, and reads the backticked package name, because each of those is
62+
an independent way for a matcher to read zero and print green.

‎.github/workflows/lint.yml‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5633,6 +5633,44 @@ jobs:
56335633
- name: Check every agent definition declares a model
56345634
run: pnpm check:agent-model-declared
56355635

5636+
# ADR-0049 tombstones, refusal strings and doc pages name the release that
5637+
# carries a removal, and ADR-0087's level ruling (Amended 2026-09-13) settles
5638+
# which number that is: "A tombstone names the npm release it ships in, ⛔ never
5639+
# the protocol major" — a pre-GA retirement ships `minor`, so it lands in a
5640+
# version of the CURRENT major, never in the next one. Prose dating a removal to
5641+
# the next major sends the reader to a version that does not exist.
5642+
#
5643+
# This is a RECURRENCE with a measured downstream cost. Ten sites of the class
5644+
# were corrected by hand in July, the card closed `completed`, and no gate landed
5645+
# with it; the class came back at 36 live sites across 15 files. Meanwhile a
5646+
# sibling repository had hung a cleanup schedule on "the PR that pushes
5647+
# `@objectstack/spec` to 18" — an event that will never come.
5648+
#
5649+
# Two axes make a naive matcher read a FALSE ZERO on live sites, and both are
5650+
# measured: the phrase spans string-concatenation, JSDoc `*` and plain-wrap line
5651+
# breaks (a single-line grep reads 33 where the tree holds 39), and the package
5652+
# name is often a backticked code span. A gate written against a single-line
5653+
# unbackticked grep would read zero and print green, which is worse than no gate.
5654+
# Its `--self-test` carries a wrapped fixture, a backticked fixture, a fenced-code
5655+
# fixture and a legitimate bare-17 fixture that must pass, and that self-test is
5656+
# the ONLY instrument watching the rule: this gate's defect class IS its matching
5657+
# rule, so a clean tree cannot observe a weakened one.
5658+
#
5659+
# The class is DERIVED from `packages/spec/package.json` at runtime — a major
5660+
# above the published one — never a hardcoded 18, which goes dormant the day the
5661+
# tree reaches 18. 588 legitimate bare-17 citations sit inside the naive class, so
5662+
# a gate refusing every bare major would fail the tree on day one.
5663+
#
5664+
# Same job and same reasons as its neighbours: no paths filter and required, so it
5665+
# cannot go dormant on exactly the PR that writes the next stale tombstone — and
5666+
# a `packages/spec/**` filter would blind it to `packages/core`, which held 11 of
5667+
# the 36 sites, six of them runtime refusal strings an operator reads.
5668+
#
5669+
# The `--self-test` invocation is what `check:self-test-wired` requires; the pnpm
5670+
# script runs it before the production pass.
5671+
- name: Check no prose dates a change to an unreleased `@objectstack/spec` major
5672+
run: pnpm check:future-spec-major
5673+
56365674
# The #8435 ratchet-remedy authority convention, enforced farm-wide instead of
56375675
# gate by gate. A gate whose second remedy is editing a shrink-only ratchet must
56385676
# either mark that path `⛔ MAINTAINER-ONLY` or turn it down outright; six gates

‎content/docs/protocol/kernel/lifecycle.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -753,7 +753,7 @@ logged as `Plugin restarted`, marked `recovering`, and kept under periodic
753753
checks it went on passing from the grave: the default check when no
754754
`checkMethod` resolves is `plugin-loaded`, which a destroyed object satisfies
755755
forever. So the terminal report on a torn-down plugin was `healthy`. The three
756-
keys were removed in `@objectstack/spec` 18 under ADR-0049 enforce-or-remove;
756+
keys were removed in `@objectstack/spec` 17.3.0 under ADR-0049 enforce-or-remove;
757757
`PluginHealthMonitor.registerPlugin` refuses a config that still carries one.
758758

759759
At the default `successThreshold: 1` none of this is observable: the first

‎content/docs/references/kernel/plugin-lifecycle-advanced.mdx‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,7 @@ const result = HotReloadConfigSchema.parse(data);
4141
| Property | Type | Required | Description |
4242
| :--- | :--- | :--- | :--- |
4343
| **enabled** | `boolean` | optional (default: `false`) | |
44-
| **watchPatterns** | `never` | optional | [REMOVED] `HotReloadConfig.watchPatterns` was removed in @objectstack/spec 18 (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/spec 17.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. |
4545
| **debounceDelayMs** | `integer` | optional (default: `1000`) | Wait time after change detection before reload, in milliseconds |
4646
| **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. |
4747
| **preserveState** | `boolean` | optional (default: `true`) | Keep plugin state across reloads |
@@ -64,9 +64,9 @@ const result = HotReloadConfigSchema.parse(data);
6464
| **failureThreshold** | `integer` | optional (default: `3`) | Consecutive failures needed to mark unhealthy |
6565
| **successThreshold** | `integer` | optional (default: `1`) | Consecutive successes needed to mark healthy |
6666
| **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. |
7070
| **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. |
7171
| **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. |
7272

0 commit comments

Comments
 (0)