mirror of
https://github.com/ksyasuda/SubMiner.git
synced 2026-02-28 06:22:45 -08:00
81 lines
4.1 KiB
Markdown
81 lines
4.1 KiB
Markdown
---
|
|
id: TASK-97
|
|
title: Normalize runtime composer contracts
|
|
status: Done
|
|
assignee:
|
|
- opencode
|
|
created_date: '2026-02-21 07:15'
|
|
updated_date: '2026-02-22 07:49'
|
|
labels:
|
|
- architecture
|
|
- type-safety
|
|
- maintainability
|
|
dependencies:
|
|
- TASK-94
|
|
- TASK-71
|
|
priority: high
|
|
ordinal: 87000
|
|
---
|
|
|
|
## Description
|
|
|
|
<!-- SECTION:DESCRIPTION:BEGIN -->
|
|
Runtime composer interfaces currently allow optional/null drift. Standardize contracts via shared context types and stricter per-composer dependency interfaces.
|
|
<!-- SECTION:DESCRIPTION:END -->
|
|
|
|
## Action Steps
|
|
|
|
<!-- SECTION:PLAN:BEGIN -->
|
|
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.
|
|
<!-- SECTION:PLAN:END -->
|
|
|
|
## Acceptance Criteria
|
|
<!-- AC:BEGIN -->
|
|
- [x] #1 Shared runtime context/types exist and are consumed by all composers.
|
|
- [x] #2 Composer inputs reject missing required dependencies at compile time.
|
|
- [x] #3 No behavior regression in runtime wiring tests.
|
|
- [x] #4 Main fan-in guard remains within configured threshold.
|
|
<!-- AC:END -->
|
|
|
|
## Implementation Plan
|
|
|
|
<!-- SECTION:PLAN:BEGIN -->
|
|
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`).
|
|
<!-- SECTION:PLAN:END -->
|
|
|
|
## Implementation Notes
|
|
|
|
<!-- SECTION:NOTES:BEGIN -->
|
|
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).
|
|
<!-- SECTION:NOTES:END -->
|
|
|
|
## Final Summary
|
|
|
|
<!-- SECTION:FINAL_SUMMARY:BEGIN -->
|
|
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.
|
|
<!-- SECTION:FINAL_SUMMARY:END -->
|
|
|
|
## Definition of Done
|
|
<!-- DOD:BEGIN -->
|
|
- [x] #1 Type-level contract tests added for composer boundaries.
|
|
- [x] #2 `bun run build`, `bun run check:main-fanin`, and `bun run test:core:dist` pass.
|
|
- [x] #3 Docs updated with composer contract conventions.
|
|
<!-- DOD:END -->
|