@pmelab/gtd 23.2.0 → 24.1.0

package/src/wire/Land.test.ts

@@ -0,0 +1,120 @@
+import { describe, expect, it } from "vitest"
+import {
+  landFields,
+  landProseText,
+  noopText,
+  renderLandJson,
+  renderLandPlain,
+  type LandFields,
+  type LandResultSource,
+} from "./Land.js"
+import { WIRE_SCHEMA } from "./index.js"
+
+describe("landFields / renderLandJson", () => {
+  const sample: LandFields = {
+    schema: WIRE_SCHEMA,
+    script: "printf '%s %s\\n' '[commit]' 'gtd(agent): build.fixing'\ngit commit ...\n",
+    settled: false,
+    idle: false,
+    state: "build.review.closing",
+    subject: "gtd(agent): build.fixing",
+    cost: 0.42,
+    model: "smart",
+  }
+
+  it("renderLandJson emits exactly schema/script/settled/idle/state/subject/cost/model, newline-terminated", () => {
+    const line = renderLandJson(landFields(sample))
+    expect(line.endsWith("\n")).toBe(true)
+    expect(JSON.parse(line)).toEqual(sample)
+  })
+
+  it("renderLandJson carries null subject/cost/model verbatim for a genuine no-op — never omitted", () => {
+    const noop: LandFields = {
+      schema: WIRE_SCHEMA,
+      script: "printf '%s\\n' 'nothing to do at \"idle\"'\n",
+      settled: true,
+      idle: true,
+      state: "idle",
+      subject: null,
+      cost: null,
+      model: null,
+    }
+    expect(renderLandJson(landFields(noop))).toBe(JSON.stringify(noop) + "\n")
+  })
+
+  it("landFields is a real reorder, not an identity copy: takes a LandResultSource-shaped value (Program.ts's LandResult field order) and pins it into LandFields' own declared order", () => {
+    // Written in `LandResultSource`'s (== `LandResult`'s) own field order —
+    // state/subject/cost/model/script/settled/idle — the opposite of
+    // `LandFields`' script/settled/idle/state/subject/cost/model, so this
+    // test would fail if `landFields` stopped reordering.
+    const resultShaped: LandResultSource = {
+      state: "build.review.closing",
+      subject: "gtd(agent): build.fixing",
+      cost: 0.42,
+      model: "smart",
+      script: "printf '%s %s\\n' '[commit]' 'gtd(agent): build.fixing'\ngit commit ...\n",
+      settled: false,
+      idle: false,
+    }
+    expect(Object.keys(landFields(resultShaped))).toEqual([
+      "schema",
+      "script",
+      "settled",
+      "idle",
+      "state",
+      "subject",
+      "cost",
+      "model",
+    ])
+  })
+})
+
+describe("noopText / landProseText", () => {
+  it("noopText names the state", () => {
+    expect(noopText("idle")).toBe('nothing to do at "idle"\n')
+  })
+
+  it("landProseText names the commit subject, newline-terminated", () => {
+    expect(landProseText("gtd(human): idle → working")).toBe(
+      "commit everything with this message: gtd(human): idle → working\n",
+    )
+  })
+
+  it("landProseText carries no ANSI escape sequence", () => {
+    // eslint-disable-next-line no-control-regex -- asserting the ABSENCE of an escape byte
+    expect(landProseText("gtd(agent): drafting")).not.toMatch(/\x1b/)
+  })
+})
+
+describe("renderLandPlain", () => {
+  const sample: LandFields = {
+    schema: WIRE_SCHEMA,
+    script: "printf '%s %s\\n' '[commit]' 'gtd(agent): build.fixing'\ngit commit ...\n",
+    settled: false,
+    idle: false,
+    state: "build.review.closing",
+    subject: "gtd(agent): build.fixing",
+    cost: 0.42,
+    model: "smart",
+  }
+
+  it("names the commit subject and points at gtd land --json=script at a real landing", () => {
+    const plain = renderLandPlain(sample)
+    expect(plain).toContain("gtd(agent): build.fixing")
+    expect(plain).toContain("gtd land --json=script")
+  })
+
+  it("prints the no-op note when nothing landed", () => {
+    const noop: LandFields = {
+      schema: WIRE_SCHEMA,
+      script: "printf '%s\\n' 'nothing to do at \"idle\"'\n",
+      settled: true,
+      idle: true,
+      state: "idle",
+      subject: null,
+      cost: null,
+      model: null,
+    }
+    expect(renderLandPlain(noop)).toBe(noopText("idle"))
+  })
+})

package/src/wire/Land.ts

@@ -0,0 +1,75 @@
+import type { StateName } from "./types.js"
+import { renderFormat, WIRE_SCHEMA } from "./constants.js"
+
+/**
+ * `gtd land`'s whole field set, in the object's own key order (also the JSON
+ * key order). `subject`/`cost`/`model` are `null` (never omitted) for a
+ * genuine no-op, mirroring `LandResult` itself.
+ */
+export interface LandFields {
+  readonly schema: number
+  readonly script: string
+  readonly settled: boolean
+  readonly idle: boolean
+  readonly state: StateName
+  readonly subject: string | null
+  readonly cost: number | null
+  readonly model: string | null
+}
+
+/**
+ * `Program.ts`'s `LandResult`, expressed structurally so `wire` never
+ * imports it — the seven fields `LandFields` carries beside `schema`, but in `LandResult`'s
+ * own declaration order (`state, subject, cost, model, script, settled,
+ * idle`), not the wire's. Deliberately a different shape from `LandFields`:
+ * `landFields` below reorders INTO the wire's pinned key order, so its input
+ * type cannot equal its output type — an identity-typed
+ * `(input: LandFields) => LandFields` would let a future caller pass an
+ * already-wire-shaped object through unchanged, silently hiding a dropped
+ * reorder.
+ */
+export interface LandResultSource {
+  readonly state: StateName
+  readonly subject: string | null
+  readonly cost: number | null
+  readonly model: string | null
+  readonly script: string
+  readonly settled: boolean
+  readonly idle: boolean
+}
+
+/** Assembles one `gtd land` result's fields in `LandFields`' declared order — the ONLY place `gtd land --json`'s wire shape is built. */
+export const landFields = (input: LandResultSource): LandFields => ({
+  schema: WIRE_SCHEMA,
+  script: input.script,
+  settled: input.settled,
+  idle: input.idle,
+  state: input.state,
+  subject: input.subject,
+  cost: input.cost,
+  model: input.model,
+})
+
+export const renderLandJson = (fields: LandFields): string => JSON.stringify(fields) + "\n"
+
+const FMT_NOOP = 'nothing to do at "%s"\n'
+const FMT_LAND_PROSE = "commit everything with this message: %s\n"
+
+/** `nothing to do at "<state>"` — a no-op step's plain-text line, and the text a print-only script's own `printf` carries. */
+export const noopText = (state: string): string => renderFormat(FMT_NOOP, state)
+
+/** `commit everything with this message: <subject>` — plain `gtd land`'s own stdout at a pending diff (no script); `--json` keeps emitting the script itself, unaffected. */
+export const landProseText = (subject: string): string => renderFormat(FMT_LAND_PROSE, subject)
+
+/**
+ * `gtd land`'s plain-text encoding — names the commit subject at a real
+ * landing and points at `--json=script`, since the script itself is
+ * unreachable from plain output; prints the existing no-op note otherwise.
+ * `command` names the invocation to point at — `"land"` by default, but
+ * `gtd judge answer` (the only other caller of `planLanding`/`landFields`)
+ * passes its own two-word name so the hint stays runnable verbatim.
+ */
+export const renderLandPlain = (fields: LandFields, command = "land"): string =>
+  fields.subject !== null
+    ? `${landProseText(fields.subject).trimEnd()}\n(run \`gtd ${command} --json=script | sh\` to get the landing script)\n`
+    : noopText(fields.state)

package/src/wire/Select.test.ts

@@ -0,0 +1,148 @@
+import { readFileSync } from "node:fs"
+import { describe, expect, it } from "vitest"
+import { selectPath } from "./Select.js"
+
+describe("selectPath — scalar/boolean/list leaves", () => {
+  it("returns value with the raw string for a scalar leaf", () => {
+    expect(selectPath({ kind: "prompt" }, "kind")).toEqual({ kind: "value", text: "prompt" })
+  })
+
+  it("returns value with true/false for a boolean leaf", () => {
+    expect(selectPath({ idle: true }, "idle")).toEqual({ kind: "value", text: "true" })
+    expect(selectPath({ idle: false }, "idle")).toEqual({ kind: "value", text: "false" })
+  })
+
+  it("returns value with one JSON.stringify per entry, newline-joined, for a list leaf", () => {
+    const result = selectPath({ changes: [{ path: "a" }, { path: "b" }] }, "changes")
+    expect(result).toEqual({
+      kind: "value",
+      text: '{"path":"a"}\n{"path":"b"}',
+    })
+  })
+
+  it("never carries a trailing newline in value.text", () => {
+    const result = selectPath({ changes: [{ path: "a" }, { path: "b" }] }, "changes")
+    expect(result.kind).toBe("value")
+    if (result.kind === "value") {
+      expect(result.text.endsWith("\n")).toBe(false)
+    }
+  })
+})
+
+describe("selectPath — absent vs unknown", () => {
+  it("returns absent for a key that is present with an undefined value", () => {
+    expect(selectPath({ label: undefined }, "label")).toEqual({ kind: "absent" })
+  })
+
+  it("returns unknown for a key that is missing from the object", () => {
+    expect(selectPath({ kind: "prompt" }, "nope")).toEqual({ kind: "unknown", path: "nope" })
+  })
+
+  it("returns absent for the whole remaining path when a parent is present-but-undefined", () => {
+    expect(selectPath({ session: undefined }, "session.id")).toEqual({ kind: "absent" })
+  })
+
+  it("resolves an in-range all-digits segment against a list, descending into that entry", () => {
+    expect(selectPath({ changes: [{ path: "a" }] }, "changes.0.path")).toEqual({
+      kind: "value",
+      text: "a",
+    })
+  })
+
+  it("returns unknown for an out-of-range index against a list", () => {
+    expect(selectPath({ skills: ["a"] }, "skills.1")).toEqual({
+      kind: "unknown",
+      path: "skills.1",
+    })
+  })
+
+  it("returns unknown for a non-numeric segment against a list — no inherited array member (length, map, ...) resolves", () => {
+    expect(selectPath({ skills: ["a"] }, "skills.length")).toEqual({
+      kind: "unknown",
+      path: "skills.length",
+    })
+  })
+})
+
+describe("selectPath — array indexing", () => {
+  it("skills.0 reads the first declared skill, matching a driver's own read", () => {
+    expect(selectPath({ skills: ["code-review", "testing"] }, "skills.0")).toEqual({
+      kind: "value",
+      text: "code-review",
+    })
+  })
+})
+
+describe("selectPath — never throws", () => {
+  it("returns unknown when descending a path through a plain scalar", () => {
+    expect(selectPath({ a: 5 }, "a.b")).toEqual({ kind: "unknown", path: "a.b" })
+  })
+
+  it("returns unknown when the root itself is a primitive", () => {
+    expect(selectPath(5, "a")).toEqual({ kind: "unknown", path: "a" })
+  })
+
+  it("returns absent for the whole remaining path when a parent is null — never descends into it, never unknown", () => {
+    expect(selectPath({ a: null }, "a.b")).toEqual({ kind: "absent" })
+  })
+})
+
+describe('selectPath — a null leaf is absent, never the string "null"', () => {
+  it('returns absent, not a value with text "null", for a null-valued leaf', () => {
+    expect(selectPath({ subject: null }, "subject")).toEqual({ kind: "absent" })
+  })
+
+  it("BeatDocument.next is | null on no match — next.target reads as absent, not unknown, so a driver's read is never fatal", () => {
+    expect(selectPath({ next: null }, "next.target")).toEqual({ kind: "absent" })
+  })
+})
+
+describe("selectPath — own-property presence only, never inherited/prototype members", () => {
+  const fields = { kind: "message", changes: [{ path: "a" }] }
+
+  it("returns unknown for constructor — inherited from Object.prototype, not a document field", () => {
+    expect(selectPath(fields, "constructor")).toEqual({ kind: "unknown", path: "constructor" })
+  })
+
+  it("returns unknown for toString — inherited from Object.prototype", () => {
+    expect(selectPath(fields, "toString")).toEqual({ kind: "unknown", path: "toString" })
+  })
+
+  it("returns unknown for hasOwnProperty — inherited from Object.prototype", () => {
+    expect(selectPath(fields, "hasOwnProperty")).toEqual({
+      kind: "unknown",
+      path: "hasOwnProperty",
+    })
+  })
+
+  it("returns unknown for valueOf — inherited from Object.prototype", () => {
+    expect(selectPath(fields, "valueOf")).toEqual({ kind: "unknown", path: "valueOf" })
+  })
+
+  it("returns unknown for changes.length — inherited from Array.prototype, not an index into the array", () => {
+    expect(selectPath(fields, "changes.length")).toEqual({
+      kind: "unknown",
+      path: "changes.length",
+    })
+  })
+
+  it("returns unknown for changes.map — inherited from Array.prototype", () => {
+    expect(selectPath(fields, "changes.map")).toEqual({ kind: "unknown", path: "changes.map" })
+  })
+})
+
+describe("selectPath — nested field reach", () => {
+  it("reaches a nested scalar field", () => {
+    expect(selectPath({ session: { id: "abc123" } }, "session.id")).toEqual({
+      kind: "value",
+      text: "abc123",
+    })
+  })
+})
+
+describe("src/wire/Select.ts — zero imports", () => {
+  it("contains no import statement", () => {
+    const source = readFileSync(new URL("./Select.ts", import.meta.url), "utf8")
+    expect(source).not.toMatch(/^\s*import\b/m)
+  })
+})

package/src/wire/Select.ts

@@ -0,0 +1,78 @@
+// Zero imports on purpose — a pure, dependency-free vocabulary tier; keep it that way.
+
+export type Selection =
+  | { readonly kind: "value"; readonly text: string }
+  | { readonly kind: "absent" }
+  | { readonly kind: "unknown"; readonly path: string }
+
+/**
+ * Renders a fully-walked leaf value: scalars/booleans stringify directly,
+ * arrays become one `JSON.stringify` per entry, newline-joined.
+ * `selectPath`'s loop already returns `absent` for `undefined`/`null` after
+ * every segment (including the last), so neither ever reaches here.
+ */
+const toSelection = (value: unknown): Selection => {
+  if (Array.isArray(value)) {
+    return { kind: "value", text: value.map((entry) => JSON.stringify(entry)).join("\n") }
+  }
+  if (typeof value === "object") {
+    return { kind: "value", text: JSON.stringify(value) }
+  }
+  return { kind: "value", text: String(value) }
+}
+
+/** A segment that resolves to no key at all (missing from an object, out-of-range or non-numeric against an array) — distinct from a present key holding `undefined`. */
+const NOT_FOUND: unique symbol = Symbol("not-found")
+
+/** An all-digits segment (`"0"`, `"12"`) — the only shape an array segment resolves against. */
+const ARRAY_INDEX = /^\d+$/
+
+/**
+ * One step of the walk: looks `segment` up on `current`, or reports
+ * `NOT_FOUND` for a key that was never there (a primitive has no keys).
+ * Against an array, only an all-digits segment resolves — an in-range index
+ * (`skills.0` reads the first declared skill), never a non-index own key
+ * (`length`/`map`/every other inherited array member stays `NOT_FOUND`).
+ * Against an object, presence is an OWN-property test
+ * (`Object.prototype.hasOwnProperty`), never the `in` operator — `in` walks
+ * the prototype chain, so it would resolve inherited members
+ * (`constructor`, `toString`, `hasOwnProperty`, `valueOf`, ...) as real
+ * document fields.
+ */
+const resolveSegment = (current: unknown, segment: string): unknown => {
+  if (Array.isArray(current)) {
+    return ARRAY_INDEX.test(segment) && Number(segment) < current.length
+      ? current[Number(segment)]
+      : NOT_FOUND
+  }
+  if (typeof current === "object" && current !== null) {
+    const record = current as Record<string, unknown>
+    return Object.prototype.hasOwnProperty.call(record, segment) ? record[segment] : NOT_FOUND
+  }
+  return NOT_FOUND
+}
+
+/**
+ * Walks `fields` by dotted key path. Never throws — any unwalkable shape
+ * (a primitive mid-path, an out-of-range or non-numeric array segment)
+ * degrades to `unknown`, and a present-but-`undefined` value anywhere along
+ * the path short-circuits the whole remaining path to `absent` rather than
+ * reporting a key that was never actually missing.
+ */
+export const selectPath = (fields: unknown, path: string): Selection => {
+  try {
+    let current: unknown = fields
+    for (const segment of path.split(".")) {
+      current = resolveSegment(current, segment)
+      if (current === NOT_FOUND) return { kind: "unknown", path }
+      // `null` is treated exactly like `undefined` here: a `null`-typed field
+      // (e.g. `BeatDocument.next`, `LandFields.subject`/`cost`/`model`) is a
+      // legitimate "nothing here" value, not a value to descend into or print
+      // as the literal string "null".
+      if (current === undefined || current === null) return { kind: "absent" }
+    }
+    return toSelection(current)
+  } catch {
+    return { kind: "unknown", path }
+  }
+}

package/src/wire/Sessions.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from "vitest"
+import { GTD_SESSION_NAMESPACE, resolveSession, uuidv5 } from "./Sessions.js"
+
+// RFC 4122 §4.3 test vector — the DNS namespace uuidv5-hashing "www.example.com"
+// is the standard, tool-independent proof that a hand-rolled v5 implementation
+// is correct (unlike a gtd-namespace id, which no external source publishes).
+const DNS_NAMESPACE = "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
+
+describe("uuidv5", () => {
+  it("matches the RFC 4122 test vector", () => {
+    expect(uuidv5(DNS_NAMESPACE, "www.example.com")).toBe("2ed6657d-e927-568b-95e1-2665a8aea6a2")
+  })
+
+  it("sets the version nibble to 5 and the variant bits to 10xx", () => {
+    const id = uuidv5(GTD_SESSION_NAMESPACE, "build.fix#abc1234")
+    expect(id[14]).toBe("5")
+    expect(["8", "9", "a", "b"]).toContain(id[19])
+  })
+
+  it("is deterministic: the same name always yields the same id", () => {
+    expect(uuidv5(GTD_SESSION_NAMESPACE, "root#abc1234")).toBe(
+      uuidv5(GTD_SESSION_NAMESPACE, "root#abc1234"),
+    )
+  })
+
+  it("a one-character-different name yields a different id", () => {
+    expect(uuidv5(GTD_SESSION_NAMESPACE, "root#abc1234")).not.toBe(
+      uuidv5(GTD_SESSION_NAMESPACE, "root#abc1235"),
+    )
+  })
+})
+
+describe("resolveSession", () => {
+  it("derives the same id for the same memory key, passing resume through verbatim", () => {
+    expect(resolveSession("root#abc1234", false)).toEqual({
+      sessionId: uuidv5(GTD_SESSION_NAMESPACE, "root#abc1234"),
+      resume: false,
+    })
+    expect(resolveSession("root#abc1234", true)).toEqual({
+      sessionId: uuidv5(GTD_SESSION_NAMESPACE, "root#abc1234"),
+      resume: true,
+    })
+  })
+
+  it("a different memory key derives a different id", () => {
+    const a = resolveSession("root#abc1234", false)
+    const b = resolveSession("root#feed000", false)
+    expect(a.sessionId).not.toBe(b.sessionId)
+  })
+
+  it("mints a random, non-repeating id and forces resume: false when there is no memory key", () => {
+    let calls = 0
+    const mint = () => `minted-${++calls}`
+    const first = resolveSession(undefined, true, mint)
+    const second = resolveSession(undefined, true, mint)
+    expect(first).toEqual({ sessionId: "minted-1", resume: false })
+    expect(second).toEqual({ sessionId: "minted-2", resume: false })
+  })
+})

package/src/wire/Sessions.ts

@@ -0,0 +1,39 @@
+import { createHash, randomUUID } from "node:crypto"
+
+/** Fixed forever — every derived session id descends from this one constant. */
+export const GTD_SESSION_NAMESPACE = "ca4be249-805e-41c1-8b6a-75a11c011e25"
+
+const toBytes = (uuid: string): Buffer => Buffer.from(uuid.replace(/-/g, ""), "hex")
+
+const toUuidString = (bytes: Buffer): string => {
+  const hex = bytes.toString("hex")
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`
+}
+
+/**
+ * UUIDv5 (RFC 4122 §4.3), hand-rolled over `node:crypto`'s SHA-1 rather than
+ * a dependency — correctness is checked against the RFC's own DNS-namespace
+ * test vector in `Sessions.test.ts`.
+ */
+export const uuidv5 = (namespace: string, name: string): string => {
+  const hash = createHash("sha1").update(toBytes(namespace)).update(name, "utf8").digest()
+  const bytes = hash.subarray(0, 16)
+  bytes[6] = (bytes[6]! & 0x0f) | 0x50
+  bytes[8] = (bytes[8]! & 0x3f) | 0x80
+  return toUuidString(bytes)
+}
+
+/**
+ * Resolves a `prompt` rest's session id: with no `memoryKey` there's no
+ * history to derive a stable id from, so it mints an ephemeral one and forces
+ * `resume: false`; otherwise the id is deterministic (`uuidv5`) and `resume`
+ * is passed through as given.
+ */
+export const resolveSession = (
+  memoryKey: string | undefined,
+  resume: boolean,
+  mint: () => string = randomUUID,
+): { readonly sessionId: string; readonly resume: boolean } =>
+  memoryKey === undefined
+    ? { sessionId: mint(), resume: false }
+    : { sessionId: uuidv5(GTD_SESSION_NAMESPACE, memoryKey), resume }

package/src/wire/WireSchema.test.ts

@@ -0,0 +1,162 @@
+import { readdirSync, readFileSync } from "node:fs"
+import { resolve } from "node:path"
+import { describe, expect, it } from "vitest"
+import {
+  BEAT_KINDS,
+  beatDocument,
+  demandOf,
+  judgeJson,
+  landFields,
+  renderBeatJson,
+  renderLandJson,
+  statusOf,
+  WIRE_SCHEMA,
+  type BeatKind,
+} from "./index.js"
+
+const GOLDEN = resolve(import.meta.dirname, "golden")
+
+// One golden set per schema. Removing or renaming a field bumps WIRE_SCHEMA
+// and adds golden/<WIRE_SCHEMA>/ beside the old sets; adding a field needs
+// neither. Only shape is compared, so reworded content never asks for a bump.
+const DIR = resolve(GOLDEN, String(WIRE_SCHEMA))
+const golden: ReadonlyMap<string, unknown> = new Map(
+  readdirSync(DIR)
+    .sort()
+    .map((file) => [file, JSON.parse(readFileSync(resolve(DIR, file), "utf8"))]),
+)
+
+/** Every key path with its leaf type; `judge` is a JSON document carried as a string, so it is parsed first. */
+const shape = (value: unknown, path = ""): string[] => {
+  if (path === "judge" && typeof value === "string") return shape(JSON.parse(value), path)
+  if (Array.isArray(value)) return value.flatMap((item) => shape(item, `${path}[]`))
+  if (value !== null && typeof value === "object")
+    return Object.entries(value).flatMap(([key, item]) =>
+      shape(item, path ? `${path}.${key}` : key),
+    )
+  return [`${path}: ${value === null ? "null" : typeof value}`]
+}
+
+const missing = (actual: unknown, expected: unknown): string[] => {
+  const has = new Set(shape(actual))
+  return [...new Set(shape(expected))].filter((leaf) => !has.has(leaf))
+}
+
+const JUDGE = judgeJson({ diff: "…" }, [
+  {
+    id: "q1",
+    primitive: "noul",
+    instructions: "Is the change done?",
+    criteria: "yes: every item ticked",
+  },
+])
+
+const beat = (kind: BeatKind): string => {
+  const rendered = {
+    state: "build.fixing",
+    actor: "agent",
+    content: "fix it",
+    model: "opus",
+    system: "You are a careful senior engineer.",
+    memory: "build#a1b2c3d",
+    file: "TODO.md",
+    mode: "qa",
+    label: "Fixing",
+    judge: JUDGE,
+    skills: ["code-review"],
+    access: { read: null, write: [".gtd/TODO.md"] },
+  }
+  const demand = demandOf(
+    kind === "prompt"
+      ? {
+          rendered,
+          kind,
+          session: { id: "8f2c", resume: true },
+          validate: "gtd check qa 'TODO.md'",
+        }
+      : { rendered, kind },
+  )
+  const status = statusOf({
+    rendered,
+    idle: false,
+    initial: false,
+    workflow: "feature",
+    log: ".git/gtd-loop.log",
+    changes: [{ status: "M", path: "TODO.md" }],
+    next: { target: "idle" },
+    cost: 12,
+    costByModel: [{ model: "opus", cost: 12 }],
+  })
+  return renderBeatJson(beatDocument(demand, status))
+}
+
+const documents: Readonly<Record<string, string>> = {
+  ...Object.fromEntries(BEAT_KINDS.map((kind) => [`beat-${kind}.json`, beat(kind)])),
+  "land.json": renderLandJson(
+    landFields({
+      state: "build.review.closing",
+      subject: "gtd(agent): build.fixing",
+      cost: 0.42,
+      model: "smart",
+      script: "git commit ...\n",
+      settled: false,
+      idle: false,
+    }),
+  ),
+  "land-noop.json": renderLandJson(
+    landFields({
+      state: "idle",
+      subject: null,
+      cost: null,
+      model: null,
+      script: "printf '%s\\n' 'nothing to do at \"idle\"'\n",
+      settled: true,
+      idle: true,
+    }),
+  ),
+  "judge.json": JUDGE,
+}
+
+describe(`wire schema ${WIRE_SCHEMA}`, () => {
+  it("the golden set covers every document kind", () => {
+    expect([...golden.keys()]).toEqual(Object.keys(documents).sort())
+  })
+
+  for (const [file, json] of Object.entries(documents)) {
+    it(`${file}: still emits every golden field under its name and type — removing or renaming one needs a WIRE_SCHEMA bump`, () => {
+      expect(golden.get(file)).toHaveProperty("schema", WIRE_SCHEMA)
+      expect(missing(JSON.parse(json), golden.get(file))).toEqual([])
+    })
+  }
+
+  describe("the shape check", () => {
+    const land = JSON.parse(documents["land.json"]!) as Record<string, unknown>
+    const { subject, ...rest } = land
+
+    it("reports a removed field", () => {
+      expect(missing(rest, golden.get("land.json"))).toEqual(["subject: string"])
+    })
+
+    it("reports a renamed field", () => {
+      expect(missing({ ...rest, title: subject }, golden.get("land.json"))).toEqual([
+        "subject: string",
+      ])
+    })
+
+    it("accepts an added field and changed content", () => {
+      expect(missing({ ...land, extra: true, script: "other" }, golden.get("land.json"))).toEqual(
+        [],
+      )
+    })
+
+    it("reads inside the judge document a beat carries", () => {
+      const beat = JSON.parse(documents["beat-message.json"]!) as Record<string, unknown>
+      const judge = JSON.parse(beat.judge as string) as Record<string, unknown>
+      const { state, ...withoutState } = judge
+      expect(state).toBeDefined()
+      expect(
+        missing({ ...beat, judge: JSON.stringify(withoutState) }, golden.get("beat-message.json")),
+      ).toEqual(["judge.state.diff: string"])
+    })
+  })
+})