Cleanup: drop seven unused type-import specifiers

[philcunliffe]

Automated neutral autophagy cleanup (LLP 0036). This PR only proposes; a human reviewer disposes. It is never auto-merged, and it is opened as a draft.

Seven unused type-import specifiers, in three .d.ts import headers and one JSDoc @import header. Type imports are erased at emit, so nothing here changes runtime behavior or the generated declaration tree. No construct, export, or file was removed.

Trims and reachability evidence

Each name was proven unreferenced by grepping the file that imports it (a type-import specifier can only be consumed inside its own file: it is an import, not a re-export, so no other module can reach it through this path). The exported types themselves are untouched and still live in hypaware-plugin-kernel-types.d.ts, src/core/config/types.d.ts, and src/core/observability/runtime.js.

1. src/core/cli/types.d.ts - AiGatewayCapability, PluginConfigInstance, CommandRegistration, CommandRunContext

$ grep -n '\bAiGatewayCapability\b' src/core/cli/types.d.ts
2: AiGatewayCapability,
$ grep -n '\bPluginConfigInstance\b' src/core/cli/types.d.ts
5: PluginConfigInstance,
$ grep -n '\bCommandRegistration\b' src/core/cli/types.d.ts
6: CommandRegistration,
$ grep -n '\bCommandRunContext\b' src/core/cli/types.d.ts
7: CommandRunContext,

Each name occurs exactly once in the file: on its own import line. Other modules that use AiGatewayCapability / PluginConfigInstance (src/core/commands/status.js, src/core/commands/clients.js, src/core/config/schema.js, several plugin index.js files, test/core/attach-policy.test.js) each declare their own @import from the kernel contract, not from this file.

2. src/core/daemon/types.d.ts - HypAwareV2Config, ConfigValidationError

$ grep -n '\bHypAwareV2Config\b' src/core/daemon/types.d.ts
2: HypAwareV2Config,
$ grep -n '\bConfigValidationError\b' src/core/daemon/types.d.ts
6:import type { ActionReconciler, ConfigControlStatus, ConfigLayerDrop, V1Diagnostic, ConfigValidationError } from '../config/types.d.ts'

Both occur only on their import lines. The other four specifiers on line 6 (ActionReconciler, ConfigControlStatus, ConfigLayerDrop, V1Diagnostic) are used and were left alone.

3. src/core/registry/types.d.ts - CapabilityRegistration

$ grep -n '\bCapabilityRegistration\b' src/core/registry/types.d.ts
4: CapabilityRegistration,

One occurrence, its own import line. Note CapabilityRegistry (used) is a different name and was kept.

4. src/core/observability/tracer.js - Span

$ grep -n '\bSpan\b' src/core/observability/tracer.js
10: * @import { Span } from './runtime.js'

One occurrence. tsc --noUnusedLocals independently flags this one: src/core/observability/tracer.js(10,4): error TS6133: 'Span' is declared but its value is never read. The Span type itself remains exported from src/core/observability/runtime.js.

The checks that were run against each candidate

• No importer: greped the whole tree for each symbol and for each module path. Import specifiers are not re-exported, so nothing outside these files can reach them.
• No test reference: nothing under test/, hypaware-core/smoke/, or scripts/ names them via these files; the tests that use AiGatewayCapability / PluginConfigInstance import from the kernel contract directly.
• No @ref annotation: none of the removed lines carry or sit under an // @ref LLP NNNN#anchor annotation.
• Not a package entry point: none of these files or names appear in package.jsonmain / exports / bin / scripts, or under bin/. src/core/cli/types.d.ts is not a published types target (./integration points at src/core/cli/integration.d.ts).
• Not a CLI surface or documented API: no README.md, docs/, llp/, or AGENTS.md text depends on these specifiers.
• No dynamic reachability: type-only specifiers are erased before runtime, so no plugin manifest, string-keyed dispatch, or registry lookup can reach them. No plugin, source, or sink code path was touched.

What was examined and deliberately left alone

The negative results, so the next run does not re-tread them:

• 73 exported symbols with no cross-file reference. All but two are used inside their own file, so removing them would mean deleting only the export keyword: a de-export refactor, not a deletion, and out of scope for autophagy.
• stopLaunchAgent (src/core/daemon/macos.js) and stopSystemdUnit (src/core/daemon/linux.js) were the only two symbols with zero references anywhere. They survive anyway: src/core/daemon/install.js:340 does export { macos, linux }, re-exporting both platform modules as whole namespace objects, so every export on them is reachable package surface. They are also the symmetric partners of start* / restart* / uninstall* in a deliberately complete platform adapter.
• Unused local declarations and unused runtime imports: a full scan found none.
• Unreachable code: tsc --allowUnreachableCode false reports zero TS7027 diagnostics across the tree.
• Commented-out code blocks: a scan for commented-out statements found only prose comments that happen to begin with a keyword.
• Unreferenced files: no file under src/, hypaware-core/plugins-workspace/, bin/, or scripts/ is unreferenced. The only basename-unreferenced files are test/** and hypaware-core/smoke/flows/**, which are discovered by glob at runtime.
• Unused function parameters (about 25 sites, mostly positional callback params): changing a signature is a refactor, not a deletion. Left alone.

Checks

npm run typecheck - green:

> hypaware@1.19.0 typecheck
> tsc -p tsconfig.json --noEmit

(no diagnostics)

npm test - 8 pre-existing failures, unchanged by this PR:

# tests 2777
# suites 0
# pass 2768
# fail 8
# cancelled 0
# skipped 1
# todo 0

All 8 are in test/core/leave-command.test.js and fail identically on unmodified origin/master (verified by stashing this diff and re-running: same 8 names, same pass 2768 / fail 8 counts):

not ok 799 - leave after join removes the seed and reports the server
not ok 800 - leave clears an applied central slot, not just the seed
not ok 801 - leave reverses org-driven attaches and drops the forward identity
not ok 803 - leave after join also warns about a local central sink that keeps forwarding
not ok 804 - leave is idempotent: a second leave is the not-connected no-op
not ok 805 - leave still tears down when only a stale attach marker survives a prior partial leave
not ok 806 - leave removes the assets its attach marker records, and leaves manual copies alone
not ok 807 - leave self-heals an org attach whose plugin is gone: drops the marker, warns, stays clean

They assert hyp leave exits 0 and get exit 1 after "removed the central config layer". Unrelated to type-import specifiers, which cannot affect runtime. Flagging it here rather than fixing it: a hyp leave regression on master is a behavior bug, out of scope for an autophagy cleanup.

Branch name

autophagy/cleanup-2026-07-28 already exists locally from an earlier pass today (merged as #420), as do -jsdoc-imports and -pass3. This run follows that established suffix convention rather than force-moving a stale branch.

🤖 Generated with Claude Code

[philcunliffe]

Neutral review: clean

Verdict: clean. No actionable findings. Nothing was pushed.

Reviewed head 8ce0936 in a detached worktree off the main checkout (LLP 0012 isolation). The branch contains exactly one commit vs origin/master, touching four files, +1 / -8, all inside import headers.

Independent reachability verification

I did not take the PR body's greps on trust. For every one of the seven removed specifiers I checked both the parent commit (HEAD~1) and the head commit, word-boundary anchored, in the file that imported it:

File	Removed name	occurrences at HEAD~1	occurrences at head
src/core/cli/types.d.ts	AiGatewayCapability	1 (its import line)	0
src/core/cli/types.d.ts	PluginConfigInstance	1	0
src/core/cli/types.d.ts	CommandRegistration	1	0
src/core/cli/types.d.ts	CommandRunContext	1	0
src/core/daemon/types.d.ts	HypAwareV2Config	1	0
src/core/daemon/types.d.ts	ConfigValidationError	1	0
src/core/registry/types.d.ts	CapabilityRegistration	1	0
src/core/observability/tracer.js	Span	1	0

Exactly one occurrence before and zero after means the only deleted text was the import line itself, so no annotation or declaration site was collateral damage. The diff bears that out: every deleted line is an import specifier.

Cross-file reachability, checked separately:

• None of the three touched .d.ts files contains an export *, export {, or export type {, so an import type specifier in them is a file-local alias and is structurally unreachable from any other module. Confirmed by grep over all three.
• The files that do import from these three paths (src/core/types.d.ts:9, src/core/cli/wizard/types.d.ts:2, src/core/sinks/types.d.ts:8, src/core/runtime/types.d.ts:29, src/core/cli/types.d.ts:8, src/core/daemon/types.d.ts:9,11, and the two plugin-workspace types.d.ts files) pull only locally declared interfaces (CapabilityRegistryHandle, ExtendedSourceRegistry, ExtendedSinkHandle, ExtendedSinkRegistry, CollectStatusOptions, HypAwareStatusReport, CommandRunner, DurableBinResult). No removed name appears among them.

Convention and scope

• CLAUDE.md type conventions are intact. No import path was rewritten, no @typedef introduced, no inline import('...') type added. The one JSDoc change removes @import { Span } from './runtime.js' from src/core/observability/tracer.js:10, leaving the root-anchored @import { ObservabilityEnv } from '../../../src/core/observability/types.js' in place, so the surviving header is the compliant form.
• No style churn, renames, reflows, or behaviour changes. src/core/daemon/types.d.ts:6 keeps its original single-line shape with only ConfigValidationError dropped from the specifier list; the other four names on that line are used and untouched.
• The two @ref annotations in tracer.js sit at lines 30 and 42, well clear of the removed line 10 JSDoc block, and neither references it. The three .d.ts files carry no @ref at all.
• Type imports are erased at emit, so there is no runtime surface here at all.

Local checks (corroborating; PR CI is the authority and is green)

• npm run typecheck (tsc -p tsconfig.json --noEmit): exit 0, no diagnostics.
• npm run build:types (tsc -p tsconfig.build.json): exit 0. Run explicitly because src/core/observability is a published exports target (./core/observability points at types/core/observability/index.d.ts), so a bad trim in tracer.js would surface in the declaration build rather than in --noEmit. It does not.
• npm test: tests 2777 / pass 2768 / fail 8 / skipped 1.

The 8 failures are pre-existing and unrelated. I reproduced them on a clean origin/master worktree (482bcea) rather than relying on the PR body: tests 2783 / pass 2774 / fail 8, and the failing test names are byte-identical to the head run (the ordinals shift only because master carries 6 more tests).

leave after join removes the seed and reports the server
leave clears an applied central slot, not just the seed
leave reverses org-driven attaches and drops the forward identity
leave after join also warns about a local central sink that keeps forwarding
leave is idempotent: a second leave is the not-connected no-op
leave still tears down when only a stale attach marker survives a prior partial leave
leave removes the assets its attach marker records, and leaves manual copies alone
leave self-heals an org attach whose plugin is gone: drops the marker, warns, stays clean

Agreed with the author that fixing them is out of scope for an autophagy trim, but they are a real hyp leave regression sitting on master and deserve their own issue.

Recommendation

Mergeable as-is. Ready for a human to take it out of draft.