Skip to content

docs: reconcile Disposable claim with shipped core () => void#40

Merged
thorwhalen merged 1 commit into
mainfrom
docs/reconcile-disposable
Jun 9, 2026
Merged

docs: reconcile Disposable claim with shipped core () => void#40
thorwhalen merged 1 commit into
mainfrom
docs/reconcile-disposable

Conversation

@thorwhalen

Copy link
Copy Markdown
Member

Three design docs claimed every `register*` returns a `Disposable` (`{ dispose(): void }`), but shipped core (`packages/core/src/registry.ts`) returns a bare `() => void` unregister thunk:

  • `register(cmd): () => void`
  • `registerAll(cmds): () => void` — the returned thunk unregisters the whole group atomically (the owner-scoped unload primitive)
  • `onCommandsChanged(listener): () => void`

This sides with the implementation (the intended design — docs/hand-written-sandbox.md's "Faithfulness note" already documents the `() => void` reality and the deliberate divergence from research-9's idealized interfaces). Changing core to return a `Disposable` would be a breaking public-API change for no functional gain.

Changed (3 files)

  • `docs/redesign_takeaways.md` §1.5 — heading + body
  • `docs/v1_plan.md` — Owner-scoped lifecycle table row
  • `docs/reference_notes.md` — the acture-directed "Dos" lesson in the VS Code ref_11 note

Left intact (intentional)

  • The VS Code factual line in `reference_notes.md` (`registerCommand` returns a `Disposable` — correct about VS Code).
  • `docs/hand-written-sandbox.md` (already correct), the research-9 design artifact, and `wrapex_carryover.md`.
  • Other packages' legitimate `.dispose()` methods (`acture-undo`, `acture-sandbox` runner, telemetry/devtools).

Verified by a 3-lens adversarial pass (API fidelity vs shipped core / residual-claim sweep / internal-consistency) — all clean.

Closes #39

Three design docs claimed every register* returns a Disposable
({ dispose(): void }); shipped core (packages/core/src/registry.ts)
returns a bare () => void unregister thunk, and registerAll's thunk
gives atomic group unload. Correct the docs to match the implementation
(the intended design — see hand-written-sandbox.md's Faithfulness note).

VS Code prior-art references (reference_notes.md ref_11) and other
packages' legitimate .dispose() methods are left intact.

Closes #39
@thorwhalen thorwhalen merged commit 29ecf7e into main Jun 9, 2026
1 check passed
@thorwhalen thorwhalen deleted the docs/reconcile-disposable branch June 9, 2026 19:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs: reconcile Disposable claim — core register* returns () => void, not { dispose(): void }

1 participant