feat(types): generic harness contracts (P3 Slice Zero, Task 1) #1166

2026-08-11T23:48:10Z

jason.woltje commented

2026-08-11 23:48:10 +00:00

P3 Slice Zero, Task 1 — generic harness contract types

Adds the generic harness contract types for @mosaicstack/types (pure TypeScript: interfaces, discriminated unions, typed const arrays). No runtime behavior, no adapters, no Gateway/Web wiring — those are later Slice Zero tasks.

Traceability

Approved design: docs/plans/2026-08-11-p3-pi-first-harness-adapter-design.md, approval recorded in 18e0488d0.
Approved implementation plan: 575ad743a; base-pin/lane SSOT 5f3ababd8.
Base: branched off next @ 9185b0cc (unchanged at PR time).

Files (6, path-fenced)

packages/types/src/harness/contracts.ts (new)
packages/types/src/harness/events.ts (new)
packages/types/src/harness/errors.ts (new)
packages/types/src/harness/contracts.spec.ts (new)
packages/types/src/harness/index.ts (new)
packages/types/src/index.ts (append export * from './harness/index.js';)

Design conformance (independently reviewed)

3 core interfaces (HarnessAdapter, HarnessSessionHandle, HarnessConversationService) reproduced verbatim.
Exactly 9 capabilities; exactly 19 stable error codes (both as typed const arrays with exhaustive assertNever switches).
HarnessEventEnvelope carries every persisted field (conversationId, nativeSessionId, turnId?, correlationId, sequence, nativeEntryCursor?, occurredAt, harnessId, selection).
No-substitution invariant type-enforced: effective selection is absent or exactly equals the selected selection; there is no field through which a divergent effective selection could be reported (spec runtime-asserts 'effectiveSelection' in error/receipt === false).
harness/provider/model/conversation/nativeSession/process/seat kept as 7 distinct identifiers (spec asserts Set(ids).size === 7).
No extension of / import from IProviderAdapter, AgentRuntimeProvider, or packages/types/src/agent/**.

Independent gates (author = pi ≠ verifier ≠ reviewer)

Integrator-verify: PASS — focused spec 6/6, full @mosaicstack/types package 77/77, typecheck/build/lint rc=0; path-fence holds (exactly the 6 files); parent == base.
Code + security review: PASS — no blocker/major findings; no secrets in DTOs; no any escape hatches defeating the discriminated-union exhaustiveness.
Red-first was a module-load failure (harness modules absent at base → 0 tests collected), the honest red for a from-scratch module.

Pre-push hook (typecheck/lint/format) passed on push. Merge-gate re-derivation to follow before merge.

## P3 Slice Zero, Task 1 — generic harness contract types Adds the generic harness contract **types** for `@mosaicstack/types` (pure TypeScript: interfaces, discriminated unions, typed const arrays). No runtime behavior, no adapters, no Gateway/Web wiring — those are later Slice Zero tasks. ### Traceability - **Approved design:** `docs/plans/2026-08-11-p3-pi-first-harness-adapter-design.md`, approval recorded in `18e0488d0`. - **Approved implementation plan:** `575ad743a`; base-pin/lane SSOT `5f3ababd8`. - **Base:** branched off `next` @ `9185b0cc` (unchanged at PR time). ### Files (6, path-fenced) - `packages/types/src/harness/contracts.ts` (new) - `packages/types/src/harness/events.ts` (new) - `packages/types/src/harness/errors.ts` (new) - `packages/types/src/harness/contracts.spec.ts` (new) - `packages/types/src/harness/index.ts` (new) - `packages/types/src/index.ts` (append `export * from './harness/index.js';`) ### Design conformance (independently reviewed) - 3 core interfaces (`HarnessAdapter`, `HarnessSessionHandle`, `HarnessConversationService`) reproduced verbatim. - Exactly 9 capabilities; exactly 19 stable error codes (both as typed const arrays with exhaustive `assertNever` switches). - `HarnessEventEnvelope` carries every persisted field (conversationId, nativeSessionId, turnId?, correlationId, sequence, nativeEntryCursor?, occurredAt, harnessId, selection). - **No-substitution invariant type-enforced:** effective selection is absent or exactly equals the selected selection; there is no field through which a divergent effective selection could be reported (spec runtime-asserts `'effectiveSelection' in error/receipt === false`). - harness/provider/model/conversation/nativeSession/process/seat kept as 7 distinct identifiers (spec asserts `Set(ids).size === 7`). - No extension of / import from `IProviderAdapter`, `AgentRuntimeProvider`, or `packages/types/src/agent/**`. ### Independent gates (author = pi ≠ verifier ≠ reviewer) - **Integrator-verify:** PASS — focused spec 6/6, full `@mosaicstack/types` package 77/77, typecheck/build/lint rc=0; path-fence holds (exactly the 6 files); parent == base. - **Code + security review:** PASS — no blocker/major findings; no secrets in DTOs; no `any` escape hatches defeating the discriminated-union exhaustiveness. - Red-first was a module-load failure (harness modules absent at base → 0 tests collected), the honest red for a from-scratch module. Pre-push hook (typecheck/lint/format) passed on push. Merge-gate re-derivation to follow before merge.

jason.woltje added 1 commit 2026-08-11 23:48:11 +00:00

feat(types): add generic harness contracts

ci/woodpecker/pr/ci Pipeline was canceled

Details

ddf8616716

jason.woltje merged commit 400a21ca18 into next

2026-08-11 23:51:51 +00:00

jason.woltje referenced this pull request

2026-08-11 23:52:57 +00:00

fix(gateway): resolve InteractionCoordinationService handoff factory via optional DI token (#1145) #1167

jason.woltje referenced this pull request

2026-08-12 00:34:53 +00:00