Published plugin types do not enforce what CommandRegistry.register now enforces at runtime

[philcunliffe]

Found by Neutral's ship-risk shadow gate on PR #1004 (record: #1004 (comment), classified high e4).

The gap

PR #1004 makes CommandRegistry.register copy the registration with a spread before validating and storing it. A spread carries own enumerable properties only, so the runtime now narrows what it accepts. The gate measured a base-vs-head differential and found three shapes went from working to throwing, and two semantics from live to snapshotted:

Shape	Before #1004	After #1004
class MyCommand with run() on the prototype	worked (stored with prototype run intact)	throws missing run()
Object.create(proto) registration	worked	throws
non-enumerable run	worked	throws
getter properties	live on every read	snapshotted at register time
post-register mutation of the registration object	visible to the registry	invisible

That narrowing is deliberate and correct, and the gate confirmed zero in-repo reliance on any of it across all 248 .register( sites (the only such uses are the PR's own negative tests).

The problem is that the published types do not say so. hypaware-plugin-kernel-types.d.ts ships in package.json#files for hypaware@1.25.0, so CommandRegistry.register is a third-party plugin API. A plugin author writing:

class MyCommand implements CommandRegistration {
  name = 'my cmd'
  summary = '...'
  usage = '...'
  run() { /* ... */ }        // on the prototype
}

compiles clean against the shipped .d.ts (tsc --strict exits 0) and then throws at runtime. PR #1004 states the rule in a JSDoc comment, which is prose a compiler cannot enforce.

Blast radius is bounded but not nil: src/core/runtime/loader.js:108 catches per plugin and logs plugin.activate_failed, so the kernel and other plugins keep running. The failing plugin simply does not load.

Options

1. Tighten the type so the compiler rejects what the runtime rejects. Most durable, but needs care: expressing "own enumerable properties only" in TypeScript is awkward, and an over-tight type could reject shapes that do still work.
2. A release note on whichever release carries PR Deferred PR #857 review findings: registry copy, group headers, doc hygiene #1004 naming the three rejected shapes and the two snapshotted semantics, so plugin authors upgrading have something to search for when their plugin stops loading.
3. Both. Option 2 is cheap and should probably happen regardless of whether option 1 is judged practical.

Worth deciding before the next published release, since the failure mode for a third-party plugin author is a plugin that silently does not load with only a log line to go on.

Backlink

Deferred from PR #1004 at head 20dd24cb6d6c95aaa15adc0125f9eb95e111dae9.

---

Correction (later tick): this issue originally named 1.26.0 as the release to note this in. That was wrong. 850fee36 published v1.26.0 without PR #1004, so the narrowing described above is not in 1.26.0 and will first ship in whatever release carries #1004. The hypaware@1.25.0 reference above is still accurate for where the published .d.ts stands today.

[philcunliffe]

Stuck: the remaining work here is an undecided choice, not a defect with a fix

What neutral was doing. Issue-fix intake (neutral:fix): walking the
needs-fix queue in order, classifying each entry as mechanically fixable or
blocked on an undecided question, and spending one fix slot on the first
mechanically fixable one. This issue is third in the queue.

Why neutral cannot proceed. Neutral checked what has already landed on
origin/master and what is left, and what is left is exactly the choice this
issue posed, with both of its options now problematic:

• Option 1 (tighten the type) is not expressible. The rule the runtime
  enforces is "own enumerable properties only" (src/core/registry/commands.js:61,
  const record = { ...command }, with the shape checks reading record).
  TypeScript has no notion of property ownership or enumerability, so a class
  instance whose run() sits on the prototype is structurally identical to a
  plain object under --strict. The shipped declaration already says this in
  as many words (hypaware-plugin-kernel-types.d.ts:952-957: "This declaration
  cannot express that rule ... Register a plain object, or assign the members
  onto the instance itself"), and so does the runtime
  (src/core/registry/commands.js:247-249). Neutral has no way to write a
  failing-then-passing regression test for a type the type system cannot state,
  and the issue itself flags that "an over-tight type could reject shapes that do
  still work" - which is a judgment call, not a mechanical fix.

• Option 2 (a release note) has no in-repo home and its window has closed.
  There is no CHANGELOG or release-notes file anywhere in the tree
  (git ls-tree -r origin/master finds none), so the note would mean creating a
  new file, which the repo convention ("reuse before you add") does not obviously
  authorize; the alternative home is the GitHub release body, which neutral does
  not write. And the note was scoped to "whichever release carries PR Deferred PR #857 review findings: registry copy, group headers, doc hygiene #1004": that
  PR merged 2026-08-25 and package.json on master now reads 1.30.0, so the
  release it was meant to accompany has already shipped. Whether to backfill a
  note now, and where it should live, is a call for a human.

What did land, so the gap is narrower than the issue records. The runtime
diagnosis is no longer a bare missing run(). copyMiss
(src/core/registry/commands.js:262) detects the case where a member is present
on the registration as passed but absent from the own-enumerable copy, and
appends an explaining clause to the thrown TypeError
(:78-79). It uses in rather than a read, so a prototype accessor or a Proxy
has trap cannot hijack the boundary error. So a plugin author whose class-based
registration is rejected now gets a message that names the real cause, and the
published .d.ts carries the same warning in prose. What is still missing is only
compiler enforcement (option 1) and a searchable upgrade note (option 2).

What neutral needs from a human. A decision on the two open questions:

1. Is option 1 dead? If TypeScript genuinely cannot express the rule, say so and
   this issue can close as "documented, not enforceable" - or, if a partial
   approximation is wanted (a branded/nominal CommandRegistration that a class
   instance cannot satisfy by accident, at the cost of rejecting some shapes that
   work today), authorize that trade explicitly, because it is a breaking change
   to a published plugin API and needs the LLP treatment, not a patch.
2. Where does the upgrade note go, given there is no changelog in the repo and
   the release that carried Deferred PR #857 review findings: registry copy, group headers, doc hygiene #1004 has shipped? Options: a GitHub release-note
   edit (outside neutral's reach), a new CHANGELOG.md (a new file, so a
   convention call), or a section in an existing plugin-authoring doc
   (docs/PLUGIN_AUTHORING.md exists and is the closest fit).

How to unstick. Reply with a comment on this issue answering those two
questions - in particular naming the destination for the note if one is still
wanted. Neutral will re-engage with that guidance on a later tick. No branch, no
PR, and no fix slot was spent on this issue.