feat: add executable T4 API v1 contract and SDK

[usr-bin-roygbiv]

OP-03 — Executable T4 API v1 contract and SDK

Architecture line item

OP-03. Add an executable OpenAPI 3.1 contract for the authenticated HTTPS T4 API v1 and a generated TypeScript SDK boundary with strict conformance fixtures. Depends on OP-01 in #135; this PR remains draft until that dependency merges and the exact final GitHub/Woodpecker runs are terminal green.

Observable contract

• Discovery and every declared success/error route are dispatched relative to the configured base path and fail closed on undeclared route, status, media type, required response header, malformed/oversized body, duplicate uniqueItems, invalid UTF-8, and Unicode code-point bound violations.
• T4-API-Version, mutation Idempotency-Replayed, and SSE Cache-Control: no-store are required and validated where declared; 401 intentionally omits selected-version requirements.
• Workspace/session create, PATCH, DELETE, cancellation, command submission, snapshot, pagination, and watch requests enforce strict schemas, declared JSON media, bounds, scoped authorization, If-Match ordering, and JCS/default-before-fingerprint idempotency semantics before mutation or idempotency recording.
• Successful scoped DELETE and exact PATCH replays return recorded results before current absence/revision checks; target IDs remain part of the idempotency scope, so the same key on different targets executes independently.
• Snapshot and bounded SSE watch validate exact status/media/header contracts, fatal UTF-8, frame/aggregate bounds, EOF delimiters, stream cancellation, cursor progress, retry-budget reset, and bounded reconnects. Low-level .http SSE callers use typed parseAs: "stream"; watchSession is the bounded validated API.
• A typed valid 503 is bounded-retryable. Malformed/oversized/non-JSON envelopes or invalid present Retry-After become terminal 502/nonretryable. RFC 9110 delay-seconds and all HTTP-date forms, including the rolling RFC 850 pivot, are validated.
• RFC 3339 calendar/offset/lowercase delimiters are strict; leap seconds are accepted only on known IERS UTC insertion dates after offset normalization.
• OpenAPI PATCH replay headers, required response Header Objects, Unicode/UTF-8 constraints, heartbeat bounds, optional command metadata, generated TypeScript, and validator pins remain deterministic and checked by permanent GitHub and Woodpecker gates.

Non-goals

• No cluster-server behavior, controller, canonical architecture HTML, Terzo, OMP runtime integration, deployment, or public-exposure change.
• No alternate transport, generic wrapper around openapi-fetch, private infrastructure representation, retry-policy expansion, or change to cross-target idempotency scope.

Migration and rollback

Additive package/workspace and CI changes only. No persisted data or deployed API is migrated. Consumers can adopt the generated v1 client and watchSession; low-level SSE consumers must request parseAs: "stream". Rollback before publication is a clean revert of this PR and removal of the unpublished packages. After adoption, rollback requires retaining the v1 compatibility boundary or an explicit major-version migration.

Exact proof ledger

• Original five-finding tests-only red: 3ee50db5091ed1f23d3c9ef7bc7b5abe3134e048; GitHub run https://github.com/LycaonLLC/t4-code/actions/runs/29868362479 (generation 88762273067, core 88762273064); authoritative Woodpecker repo 38 pipeline 97: https://woodpecker-ci-dev.tailb18de3.ts.net/repos/38/pipeline/97.
• Final accepted request-media/RFC850 tests-only red: 60d155e2d33ba792d87c0370b4c2da08f6de8772; GitHub run https://github.com/LycaonLLC/t4-code/actions/runs/29881688659; generation 88803751573 and core 88803751538 failed on the independent observable assertions.
• Exact reviewed candidate: 39f06a541d9ae0aac021ca40cf26410292a9279f.
• Final GitHub run: https://github.com/LycaonLLC/t4-code/actions/runs/29882034444 is terminal green at the exact reviewed SHA; generation 88804820690, core 88804820689, and every matrix/verify job succeeded.
• Authorized deterministic generation artifact: GitHub artifact 8513874653 (t4-api-generated-29878493403), generated schema SHA-256 be0a3e3bf25e6b612053bb58e170d75b8807464da6ea4eb8d388c15512ac3b57; installed byte-for-byte without local generation.
• Independent exact detached-tree review of 39f06a541d9ae0aac021ca40cf26410292a9279f: APPROVE, no P1/P2 findings.
• Exact final Woodpecker pipeline: authoritative repo 38 handle 38:102, pipeline id 13346, workflow 13490, exact commit 39f06a541d9ae0aac021ca40cf26410292a9279f: http://woodpecker-ci-dev.tailb18de3.ts.net/repos/z-peterson/t4-code/pipeline/102. Trigger accepted HTTP 200 (manual/development, deploy=false, idempotent=false); terminal result is pending.
• No local test, build, lint, formatting, or generation command was run; all executable proof came from authorized CI.

Dependency

Blocked on and references #135 (OP-01). Keep draft until #135 merges and both final CI systems are terminal green.

[wolfiesch]

Current head 2415979 is appropriately red after the new contract tests. One additional contract/client mismatch to resolve while implementing them: the OpenAPI snapshot schema permits up to 1,000 entries of 1,048,576 code points each, but the TypeScript client caps the complete JSON response at 16 MiB. A schema-valid snapshot of roughly 65 maximum-sized entries is rejected as a protocol error. Align the aggregate schema bound and client transport limit, and reject duplicate SSE cursors rather than yielding them as forward progress.