SubMiner/backlog/tasks/task-97 - Normalize-runtime-composer-contracts.md

id, title, status, assignee, created_date, updated_date, labels, dependencies, priority, ordinal

id	title	status	assignee	created_date	updated_date	labels	dependencies	priority	ordinal
TASK-97	Normalize runtime composer contracts	Done	opencode	2026-02-21 07:15	2026-02-22 07:49	architecture type-safety maintainability	TASK-94 TASK-71	high	87000

Description

Runtime composer interfaces currently allow optional/null drift. Standardize contracts via shared context types and stricter per-composer dependency interfaces.

Action Steps

1. Inventory all composer entrypoints in src/main/runtime/composers/ and classify current optional/nullable fields.
2. Introduce shared RuntimeContext types in src/main/runtime/ with explicit non-null guarantees where required.
3. Narrow each composer input type to only required fields; remove permissive any/optional drift.
4. Add compile-time contract tests (type assertions) and runtime seam tests for wiring regressions.
5. Update composition root adapters in src/main.ts and domain registries to satisfy strict contracts.
6. Run verification gate: bun run build, bun run check:main-fanin, bun run test:core:dist.
7. Document contract rules in architecture/development docs.

Acceptance Criteria

• #1 Shared runtime context/types exist and are consumed by all composers.
• #2 Composer inputs reject missing required dependencies at compile time.
• #3 No behavior regression in runtime wiring tests.
• #4 Main fan-in guard remains within configured threshold.

Implementation Plan

1. Add shared composer contract helpers (ComposerInputs, ComposerOutputs, BuiltMainDeps) in src/main/runtime/composers/contracts.ts and consume them across all runtime composers.
2. Tighten high-risk composer boundaries (mpv-runtime-composer.ts, jellyfin-remote-composer.ts, ipc-runtime-composer.ts) and align src/main.ts callsites with normalized contract types.
3. Add compile-time contract checks in src/main/runtime/composers/composer-contracts.type-test.ts for required composer deps.
4. Update composer contract conventions in docs (docs/architecture.md, docs/development.md) and validate gates (bun run build, bun run check:main-fanin, bun run test:core:dist).

Implementation Notes

2026-02-21: started execution pass in current session; loaded task context and scanning composer contracts/tests before writing implementation plan.

Implemented shared runtime composer contract module and rewired all composer option/result types to use shared contract helpers.

Normalized MPV/Jellyfin/IPC composer boundaries, removed composer-level cast escape hatches where possible, and aligned src/main.ts runtime composer callsites to compile against stricter contracts.

Added compile-only type contract coverage in src/main/runtime/composers/composer-contracts.type-test.ts to assert required dependency keys fail when omitted.

Verification: bun run build PASS; focused composer tests PASS (dist/main/runtime/composers/{mpv,jellyfin,ipc}-runtime-composer.test.js); bun run check:main-fanin PASS (86 import lines, 10 runtime paths); bun run test:core:dist PASS (204 pass, 10 skipped).

Final Summary

Normalized runtime composer contracts by introducing shared contract helpers (ComposerInputs, ComposerOutputs, BuiltMainDeps) and applying them across all composer modules. Tightened MPV/Jellyfin/IPC composer interfaces and main callsites to enforce required dependency surfaces at compile time, added compile-only contract assertions, updated architecture/development conventions, and revalidated build/fan-in/core-runtime test gates with no behavior regressions.

Definition of Done

• #1 Type-level contract tests added for composer boundaries.
• #2 bun run build, bun run check:main-fanin, and bun run test:core:dist pass.
• #3 Docs updated with composer contract conventions.