@miadi/tide-contract 0.3.0 → 0.3.1

package/README.md

@@ -1,33 +1,61 @@
 # @miadi/tide-contract
 
-Schema-first contract for the Tide operator cockpit boundary.
+The shared schema for steering agents in terminals: what the `tide` runtime answers and what a
+client can expect back.
 
-This package is the shared covenant between:
+In the Miadi stack, `@miadi/tide` reads and steers the agents working in tmux or herdr panes,
+and the `tide` runtime (the `ironsilk` Python package) does the work on the machine. This
+package is the agreement between the two: one JSON Schema, and TypeScript types that follow
+it. A Python runtime validates against the schema, a TypeScript client compiles against the
+types, and a change to either shows up as a difference here first.
 
-- the IronSilk `tide` runtime,
-- the `@miadi/tide` TypeScript client,
-- the `/api/tide/*` Next.js routes,
-- and the cockpit UI at `/tide`.
+Works with:
 
-## Current shape
+- `@miadi/tide`: the TypeScript client, whose verbs return these types.
+- the `tide` CLI and daemon from `ironsilk`: the runtime these shapes describe.
 
-- `schema/tide-api.schema.json` is the planned source of truth.
-- `src/index.ts` carries hand-written TypeScript types for this scaffold, edited in lockstep with the schema (guarded by `npm test`, `test/schema-patterns.test.ts`).
-- 0.2.0 adds the `multiplexer` discriminator (`"tmux" | "herdr"`, absent ⇒ `"tmux"`), pane targets in both formats, optional `pane_label`, the `TideSendKeysResult` discriminated union, and optional `agent_status` on `EpisodeLane` / `TidePendingApproval`.
-- 0.2.1 corrects the herdr pane-id story from the EP137 live smoke (herdr 0.7.4): real ids are `w1:p2` (legacy `1-2` still accepted), **session-scoped and monotonic** — they do not compact or get reused when panes close, a stale id fails loudly with `pane_not_found`, and `pane rename` sets the `label` field that label→id resolution matches at action time.
-- 0.2.2 types the remaining live-verified herdr envelopes: `TideHerdrPaneInfo` (`pane list` rows), `TideHerdrWaitOutputResult` (`wait output` hit), and `TideHerdrAgentStatusEvent` (`wait agent-status` hits print an EVENT envelope, not a result envelope).
-- 0.2.3 adds the one-call inventory snapshot `TideHerdrInventory` (+ `TideHerdrWorkspaceInfo`/`TideHerdrTabInfo`) behind `getHerdrInventory()`, and widens every pane-id pattern to ALPHANUMERIC segments — live herdr allocates pane suffixes past `p9` as letters (`w2:pE` observed 2026-07-18), which the digits-only patterns rejected.
-- 0.2.4 (unpublished) covenants the peek response from live EP152 cockpit receipts — the previously documented `pane?`/`lines?` fields were fiction; `TidePeekResult` is now the `TideTmuxPeekResult` (`{target, resolved, content}`) / `TideHerdrPeekResult` (`{multiplexer, pane, lines, text}`) union — and lands the deterministic schema→TS drift gate (see Drift posture).
-- Runtime identity constants are exported from `src/index.ts` and mirrored in the schema `x-tide` metadata: `tide`, `MIADI_HOME`, `~/.miadi/navigator`, and `miadi.tide.daemon.v2`.
-- Future work should generate the TypeScript types from the schema and validate IronSilk runtime payloads with Python `jsonschema`.
+## Install
 
-## Drift posture
+```bash
+npm i @miadi/tide-contract
+```
 
-Steps 1–2 of the intended CI shape are live in `npm test` (jgwill/Miadi#378):
+```ts
+import type { ContextSnapshot, TidePeekResult, TideSendKeysResult } from "@miadi/tide-contract"
+import { TIDE_DAEMON_CONTRACT_VERSION } from "@miadi/tide-contract"
+import schema from "@miadi/tide-contract/schema/tide-api.schema.json" with { type: "json" }
+```
 
-1. **Done** — `scripts/generate-schema-reference.mjs` deterministically emits reference types from `schema/tide-api.schema.json` into `test/schema-reference.generated.ts` (committed; regenerate with `npm run generate:reference`).
-2. **Done** — `test/drift-gate.test.ts` byte-checks the committed reference (`npm run drift:check`) and compile-asserts exact assignability between every public export and its reference type. Pre-existing divergences sit in explicit waiver sections whose pins fail the build once reconciled. **Layered claims (post-W11):** the byte-check is the schema-movement tripwire — constraint-only edits (pattern/bounds) reach it via the emitted `SCHEMA_CONSTRAINTS` manifest, and unknown or co-occurring schema constructs make generation throw; the type layer proves hand-written parity at assignability granularity only (an optional field added over a loose shape's index signature is byte-layer-visible, not type-layer-visible). Review discipline: a `.generated.ts` diff *is* the schema change — read it.
-3. Validate runtime fixture JSON from IronSilk.
-4. Fail when the contract, client, routes, and runtime drift.
+## What it describes
 
-Ref: jgwill/Miadi#378
+| area | types |
+|---|---|
+| live context | `ContextSnapshot`, `TerminalContext`, `WindowEvent`, `TideHealthResult` |
+| terminals and detection | `TideTerminalsResult`, `TideTerminalTarget`, `TideDetectResult`, `TideDetectMatch` |
+| reading and steering a pane | `TidePeekResult`, `TideSteerResult`, `TideSendResult`, `TideSendKeysResult` |
+| herdr | `TideHerdrPaneInfo`, `TideHerdrInventory`, `TideHerdrWorkspaceInfo`, `TideHerdrTabInfo`, `TideHerdrWaitOutputResult`, `TideHerdrAgentStatusEvent` |
+| agent lanes in an episode | `EpisodeLane`, `EpisodeLaneTopology`, `TideLaneCheckpoint`, `TideResumeLink`, `TideAudioManifestLink`, `TidePendingApproval`, `ObserverControllerPosture` |
+
+Results that differ by multiplexer are unions discriminated by `multiplexer` (`"tmux"` or
+`"herdr"`; absent means `"tmux"`). A peek is `{ target, resolved, content }` on tmux and
+`{ multiplexer, pane, lines, text }` on herdr.
+
+herdr pane ids look like `w1:p2`. Both segments are alphanumeric, because herdr allocates
+letters past `p9` (`w2:pE`). The legacy form `1-2` is still accepted. Ids are scoped to a herdr
+session: they are never reused while it runs and do not survive a restart. A stale id fails
+with `pane_not_found`, and a pane `label` set with `herdr pane rename` is what a client matches
+to find the current id.
+
+## Runtime constants
+
+Exported from the package and mirrored in the schema's `x-tide` metadata:
+
+| constant | value |
+|---|---|
+| `TIDE_CLI_COMMAND` | `tide` |
+| `TIDE_STATE_ROOT_ENV` | `MIADI_HOME` |
+| `TIDE_DEFAULT_STATE_ROOT` | `~/.miadi/navigator` |
+| `TIDE_DAEMON_CONTRACT_VERSION` | `miadi.tide.daemon.v2` |
+
+The TypeScript types are written by hand and checked against the schema by a test that fails
+when the two drift apart. Generating them from the schema is planned.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miadi/tide-contract",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Schema-first Tide API contract shared by Miadi and the IronSilk tide runtime.",
   "license": "MIT",
   "publishConfig": {

package/schema/tide-api.schema.json

@@ -148,6 +148,8 @@
       "properties": {
         "multiplexer": { "$ref": "#/$defs/multiplexer" },
         "tmux_pane": { "type": "string", "pattern": "^(%?[0-9]+|[0-9]+-[0-9]+|w[0-9A-Za-z]+:p[0-9A-Za-z]+)$", "description": "Pane id in the owning multiplexer: tmux (e.g., '%56') or herdr (e.g., 'w1:p2' as of herdr 0.7; legacy '1-2' accepted). Field name is historical." },
+        "session_name": { "type": "string", "description": "Name of the owning tmux session (#{session_name}) — the human-readable half of a pane's identity, which the pane id alone does not carry. OPTIONAL: a producer older than this field omits it, and a consumer must fall back to the pane id rather than render an empty title." },
+        "window_name": { "type": "string", "description": "Name of the owning tmux window (#{window_name}). Optional for the same reason as session_name." },
         "pid": { "type": "integer" },
         "cwd": { "type": "string" },
         "domain_id": { "type": ["string", "null"] },