guard: fail any `Plugin` implementation that declares `stop()` (or `shutdown()`/`close()`) with no `destroy()` — the kernel only ever calls `destroy()`

[os-zhuang]

Class-closing half of #10371, split out by lane (the six repairs are the services-lane card; this guard is devx gate work). The guard was already ruled FOR by the domain:devx PM on the #9371 thread — this card is the workpiece, not a re-ask.

Why a guard and not six fixes

Plugin (packages/core/src/types.ts:170) declares init(), start?(ctx), destroy?() — and NOT stop(). The trap is the asymmetry: start?() IS on the interface and fires, so a start/stop pair reads symmetric in review while only one half is wired. This survived review in two packages and was only ever found by merge-queue evictions (#9371: two green PRs evicted). Fix six plugins and the seventh arrives spelled shutdown() or close(); the guard makes the class unreachable.

Spec of the check

• Population: Plugin implementations across packages/** (the six known instances are enumerated in plugin-reports: the timers started by ReportsPlugin are released from stop(), which the kernel never calls #10371).
• Red condition: class implements a teardown-shaped method (stop/shutdown/close — exact roster is the dev's first design decision, document it in the gate header) and does not implement destroy().
• Positive control (from the devx seat's note): MessagingServicePlugin at main before PR fix(service-messaging): stop the delivery dispatchers on the kernel's own teardown hook (#9371) #10375 must red — a real fixture, not a synthetic one.
• Delegating-alias pattern (stop() calling destroy() or vice versa, the flaky: a vitest worker teardown race (EnvironmentTeardownError: Closing rpc while onUserConsoleLog was pending) fails app-showcase with 334/334 tests passing #9371 repair shape) must stay green.
• Wire into CI + dispatch-gates population literals (avoid the [finding] dispatch-gates leaves check:entry-guard in the undetermined bucket though its population is exactly scripts/** — a dev adding a scripts/ file shipped a red it should have run first #10516 undetermined-bucket shape).

Ordering

No hard dependency on the six repairs landing first, but the guard will red on all six until they do — either land after the services-lane repairs (#10371), or land with the six known instances baselined and the baseline burned down by that card. Dev picks; say which in the PR.

Refs: #10371 (repairs, same class) · #9371 / PR #10375 (root cause + ruling) · #10374 (upstream amplifier).

Triage: pm:queue, domain:devx, Task — gate addition with a named population and a ruled mandate.

[claude]

Claim — PM dispatch (devx seat)

• Session: c970724d-303c-5614-9d20-a3f92205cfad
• Branch: claude/issue-10619-teardown-shape-guard

Premise re-verified on origin/main = 78ac958552: Plugin (packages/core/src/types.ts)
declares init(), start?(ctx) and destroy?(): Promise<void> | void — and no stop().
The asymmetry the card names is real: start?() is on the interface and fires, so a
start/stop pair reads symmetric in review while only one half is wired.

The guard was already ruled for by the domain:devx PM on the #9371 thread, so this card is
the workpiece, not a re-ask.

⚠️ The landing hazard is the whole question here, and it is the same shape as #10658's. The
six known instances live in the services lane (#10371). Once the guard exists it reds on all
six until those repairs land, which would redden this PR's own CI. The card names both routes —
land after #10371, or land with the six baselined. The dev must check whether #10371 has
landed and then choose deliberately, with a ⛔ SHRINK-ONLY baseline if it has not. ⛔ Repairing
the six here is not an option: that is another lane's work and it would make this PR
unreviewable against its card.

Two constraints carried from the card: the positive control must be the real fixture
(MessagingServicePlugin at main before PR #10375), not a synthetic one; and the
delegating-alias shape (stop() calling destroy() or vice versa — the #9371 repair) must stay
green. The exact teardown-name roster (stop / shutdown / close) is the dev's first
design decision and belongs in the gate header.

---

Generated by Claude Code

[claude]

{
 "issue": 10619,
 "status": "done",
 "branch": "claude/issue-10619-teardown-shape-guard",
 "pr": "https://github.com/objectstack-ai/objectstack/pull/10774",
 "premise_still_valid": true,
 "summary": "Added scripts/check-plugin-teardown-shape.mjs: a Plugin implementation that declares a teardown-shaped method (stop / shutdown / close / dispose) and no destroy() fails, because destroy() is the only teardown hook ObjectKernel.performShutdown() and LiteKernel.destroy() call. Wired into lint.yml's already-required 'Lint & Repo Gates' job as a node scripts/... step (root package.json is inside the #9465 fence), self-test leg first. LANDING HAZARD: #10371 has NOT landed - verified by reading the code at origin/main 78ac958552, not the card - so the guard lands with the pre-existing instances in a shrink-only KNOWN_TEARDOWN_UNREACHED list, each entry naming #10371, and the failure text REFUSES new members outright rather than marking them (check:ratchet-remedy-authority classifies it 'refused', its fourth such instance; its CONTROL corpus gained the required declaration entry - the one bounded edit outside the new file). The baseline is ELEVEN, not six: re-deriving the population rather than adopting #10371's list found five instances that card does not name - MetadataPlugin / AppPlugin / ExternalValidationPlugin spell the alias as an arrow PROPERTY (a method-only scan misses them) and EmailServicePlugin / WebhookOutboxPlugin spell it dispose(), i.e. the 'seventh arrives spelled differently' case is already present. ExternalValidationPlugin owns setInterval timers that shutdown never clears. Filed as #10772 (sub-issue of #10371), not repaired here.",
 "tests": "All run at final HEAD b97bab513d, working tree clean, exit codes captured before any pipe (cmd > file 2>&1; EXIT=$?); every verdict below is the gate's own printed line, not a bare $?.\n\nNEW GATE. `node scripts/check-plugin-teardown-shape.mjs --self-test` EXIT=0 -> 'check-plugin-teardown-shape self-test: 47 cases pass (real pre-#10375 fixture reds, the repaired file and both delegating-alias directions stay green, every roster name reds, every excluded name stays green, and all five refusals are paired with a tree that still returns a verdict).' `node scripts/check-plugin-teardown-shape.mjs` EXIT=0 -> 'check:plugin-teardown-shape: 54 Plugin implementation(s) across 4371 source(s) under packages/**; every teardown-shaped method (stop / shutdown / close / dispose) sits beside a real destroy() (11 known-unreached, SHRINK-ONLY, repair tracked on #10371).'\n\nPOSITIVE CONTROL is the real fixture, per the card: MessagingServicePlugin extracted with `git show` at 621a487607881c66b2899b7e3477115229a156b4 (PR #10375's squash-merge first parent) - async stop(), no destroy() - reds with exactly one finding. Pinned to a COMMIT, not a checked-in copy, so the fixture cannot be edited into passing; an unreachable revision refuses and prints the deepen command instead of skipping. NEGATIVE CONTROLS: the same file after the #9371 repair (stop() delegating to this.destroy()) stays green; both delegating directions pinned synthetically; destroy()-with-no-alias green; ConnectorMcpPlugin's real `private close?: () => Promise<void>` handle shape green with AND without a destroy().\n\nREFUSALS, each paired with a readable tree that still returns a verdict so 'refuses unconditionally' cannot satisfy the battery: missing population root (paired tree still REDS), zero sources (paired tree returns green), zero Plugin implementations, an unreadable source (a dangling symlink named p.ts - EISDIR/chmod would not hold for root), and an unparseable source asserted OUT OF PROCESS. Deviation from the brief's literal wording, deliberate: an unparseable source exits EXIT_UNPARSEABLE (3) from scripts/ts-parse.mjs, not 1 - routing every parse through that module is what check:parse-guard enforces and it ends the process itself. The self-test asserts non-zero AND that the file is named.\n\nABLATION - prediction stated before running: blinding the red condition (`hasKernelHook: declared.has(KERNEL_HOOK)` -> `true`) reddens 10 of 47 cases. Observed: EXACTLY 10 of 47, and the named cases matched the enumeration one for one (real pre-#10375 fixture, all 4 roster names, the arrow-property spelling, the structural-Plugin case, the test-source case, the paired tree that must still red, and the live-tree ratchet agreement); the live gate also went red with 11 stale entries. NO BUILD IS INVOLVED - the gate is a plain .mjs run directly by node, resolving nothing through any package's dist/, so there is no rebuild leg to state and no dist marker to preflight. MUTATION CONFIRMED ON DISK by anchored grep counts, not by an editor exit code: before `original-anchor=1 injected=0`, after `original-anchor=0 injected=1`. RESTORE LEG confirmed the same way: `original-anchor=1 injected=0`, `git status --porcelain` empty, and the self-test back to 47/47 EXIT=0.\n\nDISPATCH-GATES NAMEABILITY (the #10705 trap). `node scripts/pm/dispatch-gates.mjs packages/plugins/plugin-reports/src/reports-plugin.ts` EXIT=0 prints under 'Local gates for this card': '- node scripts/check-plugin-teardown-shape.mjs [lint.yml] matched via packages/plugins/plugin-reports/src/reports-plugin.ts => gate source \\'packages/**\\''. MATCHED, not undetermined and not silent - the population is declared as the subtree spelling packages/**, never the bare word hintCovers refuses.\n\nGATE UNION re-derived with `node scripts/pm/dispatch-gates.mjs` (NO paths - it took the change set off the merge base itself: 3 paths vs merge base 78ac95855). All 14 legs green at b97bab513d: check-plugin-teardown-shape --self-test (47 cases) | check-plugin-teardown-shape | check:entry-guard ('126 scripts/ file(s) ... 10 known-unsafe' - ledger gained no member) | check:parse-guard ('125 scripts/ file(s) - every TypeScript parse goes through ts-parse.mjs') | check:ratchet-remedy-authority ('112 scripts swept ... 4 turn it down outright ... Control corpus: 20 hand-classified scripts, set-equality audited both ways') + its --self-test | check:required-contexts | check:aggregator-roster ('roster == needs: in both directions') | check:workflow-status-functions | check:cross-package-test-inputs | check:node-version | check:shard-attestation | check:type-check-coverage | check:nul-bytes ('scanned 6235 text file(s) ... no raw ASCII control bytes'), plus a manual `grep -naP '[\\x00-\\x08\\x0b\\x0c\\x0e-\\x1f\\x7f]'` over the three edited files - no hits.\n\nDECLARED NARROWING: check:type-check-debt (check-type-check-coverage.mjs --re-measure) was NOT run. Attempted under scripts/pm/os-verify-lock.sh (waited 458s, acquired, ran); it REFUSED with '55 workspace dependenc(ies) of the ledgered packages have no built type entry point on disk' - it needs the full built closure. This diff adds no package source and changes no tsconfig, so the frozen raw-error counts cannot move, and the leg of that gate which actually reads the lint.yml edited here (check-type-check-coverage.mjs, no flag) is green above. CI runs the re-measure on the built closure regardless.\n\nNO CHANGESET - a new gate publishes nothing. skip-changeset applied additively via POST /issues/10774/labels and READ BACK after the bots ran: ['ci/cd', 'size/l', 'skip-changeset']. PR body read back after creation and byte-identical to what was sent except a trimmed trailing newline; the session-URL signature footer survived. CI on PR #10774 is in_progress at report time - per the dispatch contract the report lands at draft-PR time and CI convergence is the PM's read.",
 "open_questions": [],
 "out_of_scope_findings": [
 "filed as #10772: five more Plugin implementations release teardown from a hook the kernel never calls - MetadataPlugin, AppPlugin, ExternalValidationPlugin (arrow-property `stop`), EmailServicePlugin, WebhookOutboxPlugin (`dispose`) - the #10371 enumeration is short by five; linked as a sub-issue of #10371, unassigned, labels domain:services + bug, no pm:queue. ExternalValidationPlugin owns setInterval drift-check timers that kernel shutdown never clears, which is the #9371 mechanism verbatim."
 ]
}

---

Generated by Claude Code