SubMiner/backlog/tasks/task-80 - Strengthen-IPC-contract-typing-and-runtime-payload-validation.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-80	Strengthen IPC contract typing and runtime payload validation	Done	opencode-task80-ipc-contract	2026-02-18 11:43	2026-02-22 07:49	ipc type-safety reliability		medium	75000

Description

IPC handlers still rely on many unknown payload casts in main process paths. This task formalizes typed IPC contracts and validates runtime payloads before dispatch to reduce runtime-only failures.

Suggestions

• Define canonical channel map (channel -> request/response/error types).
• Add boundary validators for untrusted renderer payloads.
• Keep channel registration centralized to avoid drift.

Action Steps

1. Inventory IPC channels and payload shapes in src/main/ipc-runtime.ts and registration callsites.
2. Introduce shared IPC type map and typed registration helpers.
3. Add runtime guards/validators at IPC entry points.
4. Remove unsafe casts where typed contracts are introduced.
5. Add negative tests for malformed payloads and expected error responses.
6. Document IPC contract extension process.

Acceptance Criteria

• #1 IPC channels are defined in a typed central contract
• #2 Runtime payload validation exists for externally supplied IPC data
• #3 Unsafe cast usage in IPC boundary code is materially reduced
• #4 Malformed payloads are handled gracefully and test-covered

Implementation Plan

Plan of record (2026-02-22):

1. Add central typed IPC contract module at src/shared/ipc/contracts.ts and migrate src/core/services/ipc.ts, src/core/services/anki-jimaku-ipc.ts, and src/preload.ts from string literals to contract constants/types.
2. Add runtime IPC payload validators at src/shared/ipc/validators.ts for externally supplied payloads (runtime option id/direction/value boundary, subsync request shape, overlay modal, subtitle position, and kiku/jimaku payloads where renderer-supplied).
3. Wire validators at IPC boundaries so malformed payloads are handled gracefully (return structured { ok: false, error } for invoke handlers or no-op/log for fire-and-forget channels) and avoid unsafe as casts in boundary code.
4. Reduce unsafe casts in runtime IPC wiring (src/main/dependencies.ts, src/main.ts, IPC composer generics) by narrowing types before domain calls.
5. Add/extend IPC tests for malformed payload behavior (src/core/services/ipc.test.ts, src/core/services/anki-jimaku-ipc.test.ts), then run bun run build, bun run test:core:src, and bun run test:core:dist.
6. Update docs/architecture.md with central IPC contract and boundary-validation conventions; then finalize TASK-80 AC/DoD evidence in Backlog MCP.

Implementation Notes

2026-02-22: Started execution session opencode-task80-ipc-contract-20260222T001728Z-obrv. Loading IPC boundary code and preparing implementation plan via writing-plans before any code edits.

Saved plan document: docs/plans/2026-02-22-task-80-ipc-contract-validation.md. Proceeding with executing-plans implementation flow as requested.

Implemented central IPC contract module (src/shared/ipc/contracts.ts) and boundary validators (src/shared/ipc/validators.ts). Migrated preload/main IPC registrations from repeated literals to shared contract constants.

Hardened runtime payload validation at IPC boundaries in src/core/services/ipc.ts and src/core/services/anki-jimaku-ipc.ts with graceful malformed-payload handling (structured invoke errors or safe no-op for fire-and-forget channels).

Reduced IPC boundary casts by tightening runtime dependency signatures and wiring (src/main/dependencies.ts, src/main.ts, src/main/runtime/composers/ipc-runtime-composer.ts).

Added malformed payload regression coverage in src/core/services/ipc.test.ts and new src/core/services/anki-jimaku-ipc.test.ts; wired dist lane command list in package.json.

Validation run: bun run build (pass), bun run test:core:src (pass), bun run test:core:dist (pass). Updated IPC architecture conventions in docs/architecture.md.

Final Summary

Implemented TASK-80 by introducing a centralized IPC contract (src/shared/ipc/contracts.ts) and reusable boundary validators (src/shared/ipc/validators.ts), then migrating main/preload IPC wiring to those shared definitions. Main-process IPC handlers now validate renderer-supplied payloads before dispatch, returning structured errors for malformed invoke requests and ignoring invalid fire-and-forget payloads safely.

The runtime boundary typing was tightened to remove several unsafe casts in IPC paths (src/main.ts, src/main/dependencies.ts, src/main/runtime/composers/ipc-runtime-composer.ts) while preserving behavior. Added malformed payload tests for both core IPC and Anki/Jimaku IPC handler surfaces (src/core/services/ipc.test.ts, src/core/services/anki-jimaku-ipc.test.ts), and updated architecture docs with contract/validator ownership and boundary rules (docs/architecture.md). Verified with bun run build, bun run test:core:src, and bun run test:core:dist (all passing).

Definition of Done

• #1 IPC-related tests pass
• #2 IPC contract docs updated