@eir-labs/coltrane 0.24.32 → 0.24.34

package/agents/release-note-verifier.json

@@ -0,0 +1,32 @@
+{
+  "slug": "release-note-verifier",
+  "primitives": [
+    "VERIFY"
+  ],
+  "input_types": [
+    "release-record",
+    "release-note"
+  ],
+  "output_types": [
+    "release-note-verdict"
+  ],
+  "domain": "release",
+  "identity": "You are the release-note-verifier. A release note is about to be published under the project's name, so you check it against the record it was written from — not against whether it reads well. You refuse a claim the record does not support, and you name a surface change the prose left out. You have no tools: the record and the note are both in front of you.",
+  "method": "1. For each entry in the note's `claims`: resolve its `evidence` path against the record. Absent path, or a value that disagrees with what the record holds, goes into `unsupported_claims` with what the record actually says.\n2. Read both registers for claims that are NOT in `claims` — an assertion with no evidence entry is unsupported by construction; add it with evidence 'none stated'.\n3. Walk the record's surface lists: every added or removed entry either appears in a register or goes into `missing_from_prose`.\n4. `register_faults`: plain prose carrying internal vocabulary (gig ids, chair or seat terms, costs, commit hashes), or a formal register that disagrees with the record's own fields.\n5. `pass` is true only when `unsupported_claims`, `missing_from_prose` and `register_faults` are all empty.\n6. `checks` records what you actually compared, one row per check, naming the path and the outcome.",
+  "constraints": [
+    "Ground every claim in your inputs or a tool result from this run; mark anything else as unverified rather than asserting it.",
+    "If your inputs are insufficient for the task, say so in the output (a caveat field or equivalent) — do not fill gaps by invention.",
+    "Prefer deterministic checks over reasoning; state which checks actually ran versus what was inferred.",
+    "Report failures verbatim (messages, counts, names), not summaries of them.",
+    "Judge the note against the record, never against your own sense of the release.",
+    "Report the record's own words verbatim when a claim disagrees with it.",
+    "A claim you cannot resolve to a record path is unsupported — never give it the benefit of the doubt.",
+    "Do not rewrite the note; state what is wrong with it."
+  ],
+  "behavioral_primitives": [
+    "critic",
+    "analyst"
+  ],
+  "allowed_tools": [],
+  "model_tier": "economy"
+}

package/agents/release-writer.json

@@ -0,0 +1,32 @@
+{
+  "slug": "release-writer",
+  "primitives": [
+    "CREATE"
+  ],
+  "input_types": [
+    "release-record"
+  ],
+  "output_types": [
+    "release-note"
+  ],
+  "domain": "release",
+  "identity": "You are the release-writer. You are handed a release record compiled from git — the commits a tag carries, the law counts at both ends, and the surface that changed: tool slugs, tool arguments, CLI flags, environment variables, domain types. You write two registers of the same release and nothing else: a plain one for someone who USES coltrane, and a formal one for someone auditing what shipped. You have no tools and you need none: everything true about this release is in the record. What the record does not say, you do not say.",
+  "method": "1. Read the record. The surface lists are the substance: an added CLI flag, a new tool argument, a domain type whose version moved, a variable a deployment must now set. A surface that is null was not readable — it is not evidence of no change.\n2. `headline`: one line naming what a reader would notice. Name the thing (`--max-context-tokens`, `gig_dispatch.effort`). Never 'various improvements', never 'performance and stability'.\n3. `plain_md`: what this release means for someone using coltrane, in their vocabulary — a flag they can pass, a tool argument they can send, a variable they must set, a type whose version moved and what that obliges. Lead with what they can now do. Say plainly when a release is internal only. Use no gig ids, no costs, no chair or seat vocabulary, no commit hashes.\n4. `formal_md`: the record as a record — version, tag, date, bump, the commits by subject, the law counts at both ends, and every surface change exactly as the record states it. This register adds nothing; it restates.\n5. `claims`: every factual claim either register makes, each with the record path that supports it (`surface.cli_flags.added[1]`, `laws.after`, `commits[0].subject`) and the value read there. If you cannot name the path, the claim does not belong in the prose.\n6. `unreadable`: copy the record's `surface_unread`, and say in the plain register that those surfaces could not be read for this release rather than implying they held no change.\n7. A release whose surfaces are all empty is an internal release. Say so in one line; do not inflate it.",
+  "constraints": [
+    "Ground every claim in your inputs or a tool result from this run; mark anything else as unverified rather than asserting it.",
+    "If your inputs are insufficient for the task, say so in the output (a caveat field or equivalent) — do not fill gaps by invention.",
+    "Create only from upstream inputs and the declared task context; introduce no new external facts.",
+    "Where the creation makes a non-obvious choice, record the rationale alongside it.",
+    "Every claim in either register must appear in `claims` with the record path that supports it.",
+    "Never describe a change the record does not carry — no inference from a commit subject about what it did to the surface.",
+    "The plain register carries no internal vocabulary: no gig ids, no chair or seat terms, no costs, no commit hashes.",
+    "A null surface is 'could not be read', never 'nothing changed'. Say which.",
+    "No superlatives and no promises about future releases."
+  ],
+  "behavioral_primitives": [
+    "synthesizer",
+    "executor"
+  ],
+  "allowed_tools": [],
+  "model_tier": "standard"
+}

package/dist/src/cli.d.ts

@@ -34,7 +34,7 @@ export interface CliIO {
      *  every other command reads process.env directly, and moving them is not this change's scope. */
     env?: Record<string, string | undefined>;
 }
-export declare const USAGE = "coltrane 0.24.32\n\n  coltrane validate                     load the genome; exit non-zero on load errors OR on an\n                                        orphan \u2014 a standards/|domain_types/|agents/ file with no\n                                        genome_mutation seal in the tracked genome ledger\n  coltrane seal-genome [<genome_dir>]   bulk-seal a pre-sealing genome: append a genome_mutation\n                                        seal for every standards/|domain_types/|agents/ file not yet\n                                        sealed, via the blessed sealDefinition path. Content is\n                                        byte-unchanged; a second run seals nothing already sealed.\n                                        (default genome_dir: cwd)\n  coltrane dispatch <standard>          run a standard\n  coltrane monitor <gig-id>             report a gig's progress\n  coltrane logs <gig-id>                per-chair logs for a gig\n  coltrane abort <gig-id>               stop a running gig\n  coltrane trace <output-id>            walk an output's provenance\n  coltrane simulate <standard>          cost/shape a standard without running it\n  coltrane health                       engine + store health\n  coltrane serve                        run the MCP server on stdio\n  coltrane enqueue <standard>           queue a gig on the LOCAL file queue (no store, no key)\n                                        (env: COLTRANE_QUEUE_DIR \u2014 its absence is the whole\n                                         difference between local and hosted)\n  coltrane work                         claim one queued gig from the org store and run it\n  coltrane work --check                  report whether this box's drain environment is configured\n                                        and exit without claiming (0 ready, 1 not ready)\n                                        (env: COLTRANE_STORE_URL, COLTRANE_STORE_ANON,\n                                         COLTRANE_AGENT_TOKEN; results drain via\n                                         COLTRANE_DRAIN_URL + COLTRANE_DRAIN_KEY;\n                                         checkpoints under COLTRANE_WORKER_CHECKPOINTS,\n                                         default ~/.coltrane/worker-checkpoints;\n                                         exit 0 complete or parked, 1 failed, 3 queue empty)\n  coltrane reside [--any|--residency <id>]  hold a residency: claim a seat, ack its channel in\n                                         reflex, answer every wake, and drain the org's due work\n                                         orders through its institution's governed verbs\n                                        (env: the same contract work uses \u2014 COLTRANE_STORE_URL,\n                                         COLTRANE_STORE_ANON, COLTRANE_SERVICE_URL, plus\n                                         COLTRANE_DRAIN_KEY + COLTRANE_INSTANCE for venue mode;\n                                         no new credential class\n                                         exit 0 released, 1 cortex failed, 2 misconfigured or a\n                                         seam no deployment wired, 3 nothing claimable)\n\nOptions\n  --input <json|@file|->                dispatch payload; @file reads a file, - reads stdin\n  --depth <skim|standard|deep>          tighten the per-chair turn cap\n  --effort <low|medium|high|xhigh|max>  the reasoning effort the seat runs at\n  --max-context-tokens <n>              per-round context ceiling for a chat-completions seat\n  --budget <dollars>                    per-gig ceiling; the run stops when it is gone\n  --reuse                               allow chair-level reuse of prior sealed outputs\n  --resume <gig-id>                     continue a gig that died mid-pipeline\n  --approve <role>=<json|@file>         a human chair's verdict; repeat once per chair\n  --as <name>                           who is approving; sealed as the verdict's author\n  --wait                                block until the run finishes\n  --follow                              poll until the gig reaches a terminal state\n  --direction <upstream|downstream|both>  for trace\n  --json                                print the raw result to stdout\n  --genome <path>                       genome root (default: $COLTRANE_GENOME or cwd)\n  --help, --version\n\nA dispatch that reaches a chair a HUMAN holds parks: it names the waiting chair and exits 0,\nbecause a gig waiting on a person is not a failed gig. Approve it on the resume \u2014\n\n  coltrane dispatch <standard> --resume <gig> \\\n      --approve approve=@verdict.json --as eugene\n\n--input is NOT required on an approve-only resume: when every remaining chair is human the\ncheckpoint's recorded payload stands and the omission inherits it. If you DO pass --input it is\nchecked against the checkpoint, and a disagreement still refuses the resume.\n";
+export declare const USAGE = "coltrane 0.24.34\n\n  coltrane validate                     load the genome; exit non-zero on load errors OR on an\n                                        orphan \u2014 a standards/|domain_types/|agents/ file with no\n                                        genome_mutation seal in the tracked genome ledger\n  coltrane seal-genome [<genome_dir>]   bulk-seal a pre-sealing genome: append a genome_mutation\n                                        seal for every standards/|domain_types/|agents/ file not yet\n                                        sealed, via the blessed sealDefinition path. Content is\n                                        byte-unchanged; a second run seals nothing already sealed.\n                                        (default genome_dir: cwd)\n  coltrane dispatch <standard>          run a standard\n  coltrane monitor <gig-id>             report a gig's progress\n  coltrane logs <gig-id>                per-chair logs for a gig\n  coltrane abort <gig-id>               stop a running gig\n  coltrane trace <output-id>            walk an output's provenance\n  coltrane simulate <standard>          cost/shape a standard without running it\n  coltrane health                       engine + store health\n  coltrane serve                        run the MCP server on stdio\n  coltrane enqueue <standard>           queue a gig on the LOCAL file queue (no store, no key)\n                                        (env: COLTRANE_QUEUE_DIR \u2014 its absence is the whole\n                                         difference between local and hosted)\n  coltrane work                         claim one queued gig from the org store and run it\n  coltrane work --check                  report whether this box's drain environment is configured\n                                        and exit without claiming (0 ready, 1 not ready)\n                                        (env: COLTRANE_STORE_URL, COLTRANE_STORE_ANON,\n                                         COLTRANE_AGENT_TOKEN; results drain via\n                                         COLTRANE_DRAIN_URL + COLTRANE_DRAIN_KEY;\n                                         checkpoints under COLTRANE_WORKER_CHECKPOINTS,\n                                         default ~/.coltrane/worker-checkpoints;\n                                         exit 0 complete or parked, 1 failed, 3 queue empty)\n  coltrane reside [--any|--residency <id>]  hold a residency: claim a seat, ack its channel in\n                                         reflex, answer every wake, and drain the org's due work\n                                         orders through its institution's governed verbs\n                                        (env: the same contract work uses \u2014 COLTRANE_STORE_URL,\n                                         COLTRANE_STORE_ANON, COLTRANE_SERVICE_URL, plus\n                                         COLTRANE_DRAIN_KEY + COLTRANE_INSTANCE for venue mode;\n                                         no new credential class\n                                         exit 0 released, 1 cortex failed, 2 misconfigured or a\n                                         seam no deployment wired, 3 nothing claimable)\n\nOptions\n  --input <json|@file|->                dispatch payload; @file reads a file, - reads stdin\n  --depth <skim|standard|deep>          tighten the per-chair turn cap\n  --effort <low|medium|high|xhigh|max>  the reasoning effort the seat runs at\n  --max-context-tokens <n>              per-round context ceiling for a chat-completions seat\n  --budget <dollars>                    per-gig ceiling; the run stops when it is gone\n  --reuse                               allow chair-level reuse of prior sealed outputs\n  --resume <gig-id>                     continue a gig that died mid-pipeline\n  --approve <role>=<json|@file>         a human chair's verdict; repeat once per chair\n  --as <name>                           who is approving; sealed as the verdict's author\n  --wait                                block until the run finishes\n  --follow                              poll until the gig reaches a terminal state\n  --direction <upstream|downstream|both>  for trace\n  --json                                print the raw result to stdout\n  --genome <path>                       genome root (default: $COLTRANE_GENOME or cwd)\n  --help, --version\n\nA dispatch that reaches a chair a HUMAN holds parks: it names the waiting chair and exits 0,\nbecause a gig waiting on a person is not a failed gig. Approve it on the resume \u2014\n\n  coltrane dispatch <standard> --resume <gig> \\\n      --approve approve=@verdict.json --as eugene\n\n--input is NOT required on an approve-only resume: when every remaining chair is human the\ncheckpoint's recorded payload stands and the omission inherits it. If you DO pass --input it is\nchecked against the checkpoint, and a disagreement still refuses the resume.\n";
 interface Parsed {
     cmd: string | undefined;
     positional: string[];

package/dist/src/index.d.ts

@@ -47,3 +47,4 @@ export * from "./acoustics.js";
 export * from "./document_factory.js";
 export * from "./local_queue.js";
 export * from "./residency.js";
+export * from "./releases.js";

package/dist/src/index.js

@@ -57,4 +57,8 @@ export * from "./document_factory.js";
 // caller: "wire it or export it." Wiring is a separate act; reachability is not.
 export * from "./local_queue.js";
 export * from "./residency.js";
+// The release-record compiler — reads, at each v* tag, the surface an integrator sees (MCP tools, CLI
+// flags, worker env, domain-type versions, law counts) and reports what each release changed. A public
+// entrypoint, exported here so the public-entrypoint rule can name it.
+export * from "./releases.js";
 //# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,wBAAwB,CAAC;AACvC,cAAc,eAAe,CAAC;AAC9B,cAAc,uBAAuB,CAAC;AACtC,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,2BAA2B,CAAC;AAC1C,cAAc,qBAAqB,CAAC;AACpC,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,sBAAsB,CAAC;AACrC,cAAc,YAAY,CAAC;AAC3B,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,4BAA4B,CAAC;AAC3C,cAAc,0BAA0B,CAAC;AACzC,6FAA6F;AAC7F,iGAAiG;AACjG,qFAAqF;AACrF,2FAA2F;AAC3F,cAAc,qBAAqB,CAAC;AACpC,cAAc,aAAa,CAAC;AAC5B,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,0BAA0B,CAAC;AACzC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,uBAAuB,CAAC;AAEtC,8FAA8F;AAC9F,mGAAmG;AACnG,8FAA8F;AAC9F,oGAAoG;AACpG,+FAA+F;AAC/F,iFAAiF;AACjF,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,wBAAwB,CAAC;AACvC,cAAc,eAAe,CAAC;AAC9B,cAAc,uBAAuB,CAAC;AACtC,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,2BAA2B,CAAC;AAC1C,cAAc,qBAAqB,CAAC;AACpC,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,sBAAsB,CAAC;AACrC,cAAc,YAAY,CAAC;AAC3B,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,4BAA4B,CAAC;AAC3C,cAAc,0BAA0B,CAAC;AACzC,6FAA6F;AAC7F,iGAAiG;AACjG,qFAAqF;AACrF,2FAA2F;AAC3F,cAAc,qBAAqB,CAAC;AACpC,cAAc,aAAa,CAAC;AAC5B,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,0BAA0B,CAAC;AACzC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,uBAAuB,CAAC;AAEtC,8FAA8F;AAC9F,mGAAmG;AACnG,8FAA8F;AAC9F,oGAAoG;AACpG,+FAA+F;AAC/F,iFAAiF;AACjF,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAE/B,sGAAsG;AACtG,uGAAuG;AACvG,uEAAuE;AACvE,cAAc,eAAe,CAAC"}

package/dist/src/releases.d.ts

@@ -0,0 +1,107 @@
+/** One commit in a release's range: its full sha and its subject line. */
+export interface Commit {
+    sha: string;
+    subject: string;
+}
+/** A surface delta against the predecessor tag: both lists sorted, plain strings. `null` when the
+ *  file the list is read from was absent or unparseable AT THE TAG — distinguishable from an empty
+ *  list, which means "present and nothing changed". */
+export type SurfaceList = {
+    added: string[];
+    removed: string[];
+} | null;
+/** The surface an integrator sees, keyed by what it is read from. */
+export interface ReleaseSurface {
+    mcp_tools: SurfaceList;
+    mcp_tool_args: SurfaceList;
+    cli_flags: SurfaceList;
+    env_vars: SurfaceList;
+    domain_types: SurfaceList;
+}
+/** One release, compiled from git at a v* tag. */
+export interface ReleaseRecord {
+    /** The semver — the tag without its `v`. */
+    version: string;
+    /** The ref. */
+    tag: string;
+    /** The tag's commit date, ISO. */
+    date: string;
+    /** The range since the previous tag, oldest first; the earliest tag's range is every commit up to it. */
+    commits: Commit[];
+    /** Derived the scripts/next_version.mjs way from the range's subjects and trailers, never the tag numbers. */
+    bump: "major" | "minor" | "patch";
+    /** Law/file counts read from scripts/laws.sh: `after` at this tag, `before` the predecessor's `after`
+     *  (`null` for the earliest tag — there is no predecessor count, and `0` would falsely claim an
+     *  empty suite the day before). */
+    laws: {
+        before: number | null;
+        after: number | null;
+        files: number | null;
+    };
+    surface: ReleaseSurface;
+    /** The surface keys that were PRESENT at the tag but yielded no readable entry, sorted. A surface
+     *  whose FILE is absent is NOT unread — it is simply absent, and its list is `null` for that reason;
+     *  only a file that was there and could not be parsed is named here. Always present, empty when
+     *  every present surface read. Named so a changelog can say "could not read the tool registry here"
+     *  instead of showing a silent gap that reads as "nothing changed". */
+    surface_unread: string[];
+    /** `false` for a tagged release; `true` for the one PENDING record `compileReleases({ pending })`
+     *  appends — the version about to be published, compiled from HEAD before its tag is pushed. The
+     *  field is always present so a consumer never has to guess whether a record is settled. */
+    pending: boolean;
+}
+/** One claim in a release note, and the evidence path that backs it. `value` is the string a writing
+ *  seat recorded as "the value read at that path"; the renderer resolves `evidence` against the record
+ *  and marks the row UNSUPPORTED when the path is absent or holds a different value. */
+export interface ReleaseNoteClaim {
+    text: string;
+    evidence: string;
+    value?: string;
+}
+/** A release note (release-notes-v0): two registers of prose, the claims that back the headline, and
+ *  the surfaces a compiler could not read. The renderer turns this into markdown; it never presents a
+ *  claim the record does not support. */
+export interface ReleaseNote {
+    version: string;
+    headline: string;
+    plain_md: string;
+    formal_md: string;
+    claims: ReleaseNoteClaim[];
+    unreadable?: string[];
+}
+/**
+ * Compile a ReleaseRecord per v* tag, oldest first, reading every field AT the tag. Throws — never
+ * returns `[]` — when `tree_root` is not a git repository, or is one that holds no v* tag: an empty
+ * list would read as "this project has no releases", a different and false claim from "there is no
+ * repository to read" or "there are no tags yet".
+ *
+ * With `pending: { version }`, ONE further record is appended for the commits since the last tag,
+ * compiled through the same path as a tagged release (tag = `v<version>`, date/commits/laws/surface
+ * read from HEAD against the last tag) and marked `pending: true`. It is the record the tag WOULD
+ * carry once cut — the package can then ship the history it is itself part of. A pending version a tag
+ * already holds is refused by name, rather than emit two records for one version.
+ */
+export declare function compileReleases(opts: {
+    tree_root: string;
+    pending?: {
+        version: string;
+    };
+}): ReleaseRecord[];
+/** The whole release history as a stable JSON document, NEWEST first — the file the package ships so
+ *  the changelog UI reads a settled artifact rather than shelling out to git. Pretty-printed (2-space)
+ *  with a single trailing newline, byte-identical for the same inputs. Same options as
+ *  `compileReleases`, so a pending version leads the document. */
+export declare function releasesJson(options: {
+    tree_root: string;
+    pending?: {
+        version: string;
+    };
+}): string;
+/** Render one release note to markdown: the headline as a heading, then the plain register, then the
+ *  formal register, then an evidence section with one row per claim. Every field the note declares is
+ *  rendered; a surface named in `unreadable` is STATED as unreadable, never omitted. A claim whose
+ *  `evidence` path does not resolve in the record, or resolves to a different value than its `value`,
+ *  is marked UNSUPPORTED naming what the record actually holds — it is never dropped and never shown
+ *  as if evidenced. The rendering is derived from the NOTE: no evidence row appears that the note did
+ *  not claim (I2). */
+export declare function renderReleaseNote(note: ReleaseNote, record: ReleaseRecord): string;

package/dist/src/releases.js

@@ -0,0 +1,414 @@
+// THE RELEASE RECORD, COMPILED FROM GIT (contract-release-record-v1).
+//
+// The measured problem: `.github/workflows/publish.yml` cuts a release on every push to main and
+// derives the version from conventional-commit prefixes. Across v0.24.20..v0.24.31, 0 of 11 subjects
+// carried a prefix, so every tag shipped as a patch — including one that added a domain-type version,
+// two CLI flags, a gig_dispatch argument and three refusal kinds. A changelog grouped by the bump
+// renders one flat list, and the bump cannot be trusted to say what changed.
+//
+// So the repo answers the question MECHANICALLY. Every surface an integrator sees is data readable at
+// any tag with `git show <tag>:<path>`: the MCP tool registry (src/mcp.ts), the CLI help block
+// (src/cli.ts), the worker env table (src/worker_env.ts), each domain type's version
+// (domain_types/*.json) and the law/file counts (scripts/laws.sh). `compileReleases({ tree_root })`
+// reads those at each v* tag and reports a ReleaseRecord per tag: derived, deterministic, refusing
+// rather than guessing.
+//
+// Every git read goes through execFileSync("git", ["-C", tree_root, ...]) — no network, no shell
+// string, no process.cwd(), and everything is read AT THE TAG so a record compiled today equals the
+// record compiled the day the tag was cut. The parse is regex over the text at that revision, in the
+// style of src/repo_index.ts (no AST): an old tag's module may not compile against today's types, so
+// the surface is text at that revision, never an import of it.
+import { execFileSync } from "node:child_process";
+// ── the conventional-commit bump rule, byte-for-byte scripts/next_version.mjs ────────────────────────
+const BREAKING = /^[a-zA-Z]+(\([^)]*\))?!:/;
+const BREAKING_TRAILER = /^BREAKING[ -]CHANGE:/;
+const FEAT = /^feat(\([^)]*\))?:/;
+/** Run git under `tree_root`, capturing stdout. Throws on a non-zero exit (an absent path, a bad ref),
+ *  which the surface readers catch and turn into `null`. stderr is discarded so a missing file does not
+ *  spam the caller's console. */
+function gitCapture(root, args) {
+    return execFileSync("git", ["-C", root, ...args], {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+        maxBuffer: 64 * 1024 * 1024,
+    });
+}
+/** The text of `<path>` AT `<tag>`, or `null` when it does not exist there. */
+function showAtTag(root, tag, path) {
+    try {
+        return gitCapture(root, ["show", `${tag}:${path}`]);
+    }
+    catch {
+        return null;
+    }
+}
+/** The MCP tool slugs and their advertised argument names from src/mcp.ts. Read from the tool
+ *  ENTRIES themselves — any `{ slug: "<name>" … input_schema: obj({ … }) }` object — so the array's
+ *  NAME, its type annotation and any `.map()` export are irrelevant: the real registry is a typed
+ *  `TOOL_DEFS` array exported through `.map()`, and the simplified control fixture is
+ *  `export const MCP_TOOLS = [`, and both parse the same way. `null` when no such entry can be read
+ *  (the file is absent, or present but not a tool registry). Args are `"<slug>.<argument>"`. */
+function parseMcp(content) {
+    if (content === null)
+        return null;
+    const tools = new Set();
+    const args = new Set();
+    const toolRe = /slug:\s*"([^"]+)"[\s\S]*?input_schema:\s*obj\(\{([\s\S]*?)\}\)/g;
+    let m;
+    while ((m = toolRe.exec(content)) !== null) {
+        const slug = m[1];
+        tools.add(slug);
+        // TOP-LEVEL keys only. A nested object argument (`budget: { type: "object", properties: { … } }`)
+        // carries JSON-Schema keywords, and a flat scan reports `type` and `properties` as arguments the
+        // tool accepts — measured on this repo's own gig_dispatch. Walk the body tracking brace depth and
+        // take a key only at depth 0; the nested argument is still named, by its own key.
+        const body = m[2];
+        let depth = 0;
+        let key = "";
+        for (let i = 0; i < body.length; i++) {
+            const ch = body[i];
+            if (ch === "{" || ch === "(" || ch === "[") {
+                depth++;
+                key = "";
+                continue;
+            }
+            if (ch === "}" || ch === ")" || ch === "]") {
+                depth = Math.max(0, depth - 1);
+                key = "";
+                continue;
+            }
+            if (depth > 0)
+                continue;
+            if (/[A-Za-z0-9_$]/.test(ch)) {
+                key += ch;
+                continue;
+            }
+            if (ch === ":" && key.length > 0)
+                args.add(`${slug}.${key}`);
+            if (!/\s/.test(ch) || ch === ",")
+                key = "";
+            if (/\s/.test(ch) && key.length > 0)
+                continue;
+        }
+    }
+    // No tool ENTRY could be read — the file is present but not a tool registry. `null`, so the record
+    // NAMES it unread rather than passing an empty tool set off as "nothing changed".
+    if (tools.size === 0)
+        return null;
+    return { tools, args };
+}
+/** The long `--flags` from src/cli.ts. A flag is any line whose FIRST non-space characters are
+ *  `--<name>`, anywhere in the file; the leading token is taken WITHOUT its `<placeholder>`
+ *  (`--effort <low|…>` → `--effort`). No `HELP`/`USAGE` constant is required — the real block is a
+ *  `USAGE` template literal — and a `--` token that is NOT the start of its line (`--check` inside a
+ *  `coltrane …` usage example) is not a flag. `null` when no flag line can be read. */
+function parseCli(content) {
+    if (content === null)
+        return null;
+    const flags = new Set();
+    const lineRe = /^[ \t]*(--[a-z][a-z0-9-]*)/;
+    for (const line of content.split("\n")) {
+        const m = lineRe.exec(line);
+        if (m)
+            flags.add(m[1]);
+    }
+    if (flags.size === 0)
+        return null;
+    return flags;
+}
+/** The variable names from the worker environment contract in src/worker_env.ts, read from the
+ *  `name: "…"` values of the ENTRIES — not from the bare identifier. A file that only MENTIONS
+ *  WORKER_ENV_CONTRACT (a comment, a type whose `name: string;` field carries no quotes) but declares
+ *  no entry array yields nothing, so it reads `null` (present-but-unread, NAMED by the record) rather
+ *  than an empty set that would render the predecessor's whole env table as removed. `null` also when
+ *  the file is absent. */
+function parseEnv(content) {
+    if (content === null)
+        return null;
+    const names = new Set();
+    const re = /name:\s*"([^"]+)"/g;
+    let m;
+    while ((m = re.exec(content)) !== null)
+        names.add(m[1]);
+    if (names.size === 0)
+        return null;
+    return names;
+}
+/** EXPECTED_LAWS and EXPECTED_FILES from scripts/laws.sh, each `null` when the count is absent. */
+function parseLaws(content) {
+    if (content === null)
+        return { laws: null, files: null };
+    const lm = /EXPECTED_LAWS="\$\{EXPECTED_LAWS:-(\d+)\}"/.exec(content);
+    const fm = /EXPECTED_FILES="\$\{EXPECTED_FILES:-(\d+)\}"/.exec(content);
+    return { laws: lm ? Number(lm[1]) : null, files: fm ? Number(fm[1]) : null };
+}
+/** `"<slug>@<version>"` per file under domain_types/ AT `<tag>`. `null` when no domain_types directory
+ *  exists at the tag; an individual unparseable file contributes nothing rather than nulling the set. */
+function parseDomainTypes(root, tag) {
+    let listing;
+    try {
+        listing = gitCapture(root, ["ls-tree", "-r", "--name-only", tag, "domain_types"]);
+    }
+    catch {
+        return null;
+    }
+    const files = listing.split("\n").filter((p) => p.endsWith(".json"));
+    if (files.length === 0)
+        return null;
+    const set = new Set();
+    for (const file of files) {
+        const content = showAtTag(root, tag, file);
+        if (content === null)
+            continue;
+        try {
+            const j = JSON.parse(content);
+            if (j.slug !== undefined && j.version !== undefined)
+                set.add(`${j.slug}@${j.version}`);
+        }
+        catch {
+            /* an unparseable domain-type file contributes nothing */
+        }
+    }
+    return set;
+}
+/** The surface delta: everything in `after` not in `before` is added, and vice versa, both sorted.
+ *  `null` when the file is absent/unparseable AT THE TAG (`after` is `null`); a `before` that is
+ *  absent (an older release predating the file, or no predecessor at all) counts as the empty set, so
+ *  the tag that introduced a file reports its whole contents as `added`, never `null`. */
+function diffSurface(after, before) {
+    if (after === null)
+        return null;
+    const prev = before ?? new Set();
+    const added = [...after].filter((x) => !prev.has(x)).sort();
+    const removed = [...prev].filter((x) => !after.has(x)).sort();
+    return { added, removed };
+}
+/** The commits in `prev..tag`, oldest first; the earliest tag's range is every commit up to it. */
+function rangeCommits(root, prevTag, tag) {
+    const range = prevTag ? `${prevTag}..${tag}` : tag;
+    const out = gitCapture(root, ["log", "--reverse", "--format=%H%x09%s", range]);
+    return out
+        .split("\n")
+        .filter(Boolean)
+        .map((line) => {
+        const tab = line.indexOf("\t");
+        return { sha: line.slice(0, tab), subject: line.slice(tab + 1) };
+    });
+}
+/** The bump for `prev..tag`, derived the scripts/next_version.mjs way over the range's full commit
+ *  bodies (subjects and trailers): a `!:` prefix or a BREAKING-CHANGE trailer is major, a feat: is
+ *  minor, everything else is patch. Highest bump wins. */
+function rangeBump(root, prevTag, tag) {
+    const range = prevTag ? `${prevTag}..${tag}` : tag;
+    const body = gitCapture(root, ["log", "--format=%B", range]);
+    const lines = body.split("\n").map((l) => l.trim()).filter(Boolean);
+    let bump = "patch";
+    for (const line of lines) {
+        if (BREAKING.test(line) || BREAKING_TRAILER.test(line))
+            return "major";
+        if (FEAT.test(line))
+            bump = "minor";
+    }
+    return bump;
+}
+/** Read and parse every surface at `tag` with the minimum number of git reads — one `git show` per
+ *  text surface, one `ls-tree` (+ a show per domain-type file) for domain_types, one for laws.sh. */
+function surfacesAtTag(root, tag) {
+    const mcpContent = showAtTag(root, tag, "src/mcp.ts");
+    const cliContent = showAtTag(root, tag, "src/cli.ts");
+    const envContent = showAtTag(root, tag, "src/worker_env.ts");
+    return {
+        mcp: parseMcp(mcpContent),
+        mcpPresent: mcpContent !== null,
+        cli: parseCli(cliContent),
+        cliPresent: cliContent !== null,
+        env: parseEnv(envContent),
+        envPresent: envContent !== null,
+        domainTypes: parseDomainTypes(root, tag),
+        laws: parseLaws(showAtTag(root, tag, "scripts/laws.sh")),
+    };
+}
+/** Assemble one record from an already-parsed surface bundle. `ref` is the git ref the date and the
+ *  commit range END are read from — a tag for a settled release, `HEAD` for the pending one — and
+ *  `rangeStart` is the predecessor the range and the surface diff run against (`null` for the earliest
+ *  release, which reports its whole surface as added). Pulling this out of the loop lets the pending
+ *  record be compiled through EXACTLY the same path as a tagged one, so the two can only differ in the
+ *  `pending` flag (I1). `laws.before` is filled by the caller's chaining pass. */
+function assembleRecord(root, meta, after, before) {
+    // F1 — a surface whose FILE was present but yielded nothing readable is NAMED, so a bare `null` is
+    // never mistaken for "nothing changed"; an absent file is not named. mcp.ts backs two surface keys.
+    const surfaceUnread = [];
+    if (after.mcpPresent && after.mcp === null)
+        surfaceUnread.push("mcp_tools", "mcp_tool_args");
+    if (after.cliPresent && after.cli === null)
+        surfaceUnread.push("cli_flags");
+    if (after.envPresent && after.env === null)
+        surfaceUnread.push("env_vars");
+    surfaceUnread.sort();
+    return {
+        version: meta.version,
+        tag: meta.tag,
+        date: gitCapture(root, ["log", "-1", "--format=%cI", meta.ref]).trim(),
+        commits: rangeCommits(root, meta.rangeStart, meta.ref),
+        bump: rangeBump(root, meta.rangeStart, meta.ref),
+        laws: { before: null, after: after.laws.laws, files: after.laws.files },
+        surface: {
+            mcp_tools: diffSurface(after.mcp ? after.mcp.tools : null, before?.mcp ? before.mcp.tools : null),
+            mcp_tool_args: diffSurface(after.mcp ? after.mcp.args : null, before?.mcp ? before.mcp.args : null),
+            cli_flags: diffSurface(after.cli, before?.cli ?? null),
+            env_vars: diffSurface(after.env, before?.env ?? null),
+            domain_types: diffSurface(after.domainTypes, before?.domainTypes ?? null),
+        },
+        surface_unread: surfaceUnread,
+        pending: meta.pending,
+    };
+}
+/**
+ * Compile a ReleaseRecord per v* tag, oldest first, reading every field AT the tag. Throws — never
+ * returns `[]` — when `tree_root` is not a git repository, or is one that holds no v* tag: an empty
+ * list would read as "this project has no releases", a different and false claim from "there is no
+ * repository to read" or "there are no tags yet".
+ *
+ * With `pending: { version }`, ONE further record is appended for the commits since the last tag,
+ * compiled through the same path as a tagged release (tag = `v<version>`, date/commits/laws/surface
+ * read from HEAD against the last tag) and marked `pending: true`. It is the record the tag WOULD
+ * carry once cut — the package can then ship the history it is itself part of. A pending version a tag
+ * already holds is refused by name, rather than emit two records for one version.
+ */
+export function compileReleases(opts) {
+    const root = opts.tree_root;
+    // F2 — a tree_root that is not a git repository. Refuse by name rather than return [].
+    try {
+        execFileSync("git", ["-C", root, "rev-parse", "--git-dir"], {
+            stdio: ["ignore", "ignore", "ignore"],
+        });
+    }
+    catch {
+        throw new Error(`compileReleases: "${root}" is not a git repository — no releases to compile`);
+    }
+    // Tags in version order, oldest first.
+    const tags = gitCapture(root, ["tag", "--list", "v*", "--sort=version:refname"])
+        .split("\n")
+        .filter(Boolean);
+    // F2 — a git repository with no v* tag. Refuse by name rather than return [].
+    if (tags.length === 0) {
+        throw new Error(`compileReleases: "${root}" is a git repository but holds no v* tags — there are no releases to compile`);
+    }
+    // F1 (history) — a pending version a tag already holds would be two records for one version. Refuse
+    // by name, before any compilation, naming both the version and the tag that already holds it.
+    const pendingTag = opts.pending ? `v${opts.pending.version}` : null;
+    if (opts.pending && pendingTag !== null && tags.includes(pendingTag)) {
+        throw new Error(`compileReleases: pending version ${opts.pending.version} is already released as tag ${pendingTag} — refusing to emit a second record for one version`);
+    }
+    const records = [];
+    let before = null;
+    for (let i = 0; i < tags.length; i++) {
+        const tag = tags[i];
+        const prevTag = i > 0 ? tags[i - 1] : null;
+        // Parse every surface at this tag ONCE; the previous iteration's bundle is this tag's "before",
+        // so no tag's content is fetched twice. Presence and readability are kept apart inside assemble.
+        const after = surfacesAtTag(root, tag);
+        records.push(assembleRecord(root, { version: tag.replace(/^v/, ""), tag, ref: tag, rangeStart: prevTag, pending: false }, after, before));
+        before = after;
+    }
+    // The pending release: HEAD compiled as if it were the tag `v<version>`, diffed against the last
+    // tag (which `before` still holds), marked pending. Same path as a tagged record, so it equals the
+    // record that tag would carry save the flag.
+    if (opts.pending && pendingTag !== null) {
+        const lastTag = tags[tags.length - 1];
+        const headSurfaces = surfacesAtTag(root, "HEAD");
+        records.push(assembleRecord(root, { version: opts.pending.version, tag: pendingTag, ref: "HEAD", rangeStart: lastTag, pending: true }, headSurfaces, before));
+    }
+    // laws.before chains from the predecessor's after; the earliest release keeps null.
+    for (let i = 1; i < records.length; i++) {
+        records[i].laws.before = records[i - 1].laws.after;
+    }
+    return records;
+}
+/** The whole release history as a stable JSON document, NEWEST first — the file the package ships so
+ *  the changelog UI reads a settled artifact rather than shelling out to git. Pretty-printed (2-space)
+ *  with a single trailing newline, byte-identical for the same inputs. Same options as
+ *  `compileReleases`, so a pending version leads the document. */
+export function releasesJson(options) {
+    const releases = compileReleases(options).reverse();
+    return JSON.stringify({ generated_from: "compileReleases", releases }, null, 2) + "\n";
+}
+/** Resolve a dotted/indexed evidence path (`laws.after`, `surface.cli_flags.added[0]`) against a
+ *  record. Returns whether the path resolved and the value it reached — the plain way: a segment is a
+ *  key, and any `[n]` on it is an array index applied in order. A key missing on an object, or an
+ *  index off the end of an array, does not resolve. */
+function resolveEvidencePath(record, path) {
+    let cur = record;
+    for (const segment of path.split(".")) {
+        const keyMatch = /^[^[\]]*/.exec(segment);
+        const key = keyMatch ? keyMatch[0] : "";
+        const steps = [];
+        if (key !== "")
+            steps.push(key);
+        const idxRe = /\[(\d+)\]/g;
+        let idx;
+        while ((idx = idxRe.exec(segment)) !== null)
+            steps.push(Number(idx[1]));
+        for (const step of steps) {
+            if (cur === null || cur === undefined)
+                return { resolved: false, value: undefined };
+            if (typeof step === "number") {
+                if (!Array.isArray(cur) || step >= cur.length)
+                    return { resolved: false, value: undefined };
+                cur = cur[step];
+            }
+            else {
+                if (typeof cur !== "object" || cur === null || !(step in cur)) {
+                    return { resolved: false, value: undefined };
+                }
+                cur = cur[step];
+            }
+        }
+    }
+    return { resolved: true, value: cur };
+}
+/** The value at an evidence path, as the string a claim's `value` is compared against: a string is
+ *  itself, anything else is JSON-stringified so `150` reads as `"150"` and an array reads as its JSON. */
+function evidenceValueString(value) {
+    return typeof value === "string" ? value : JSON.stringify(value);
+}
+/** Render one release note to markdown: the headline as a heading, then the plain register, then the
+ *  formal register, then an evidence section with one row per claim. Every field the note declares is
+ *  rendered; a surface named in `unreadable` is STATED as unreadable, never omitted. A claim whose
+ *  `evidence` path does not resolve in the record, or resolves to a different value than its `value`,
+ *  is marked UNSUPPORTED naming what the record actually holds — it is never dropped and never shown
+ *  as if evidenced. The rendering is derived from the NOTE: no evidence row appears that the note did
+ *  not claim (I2). */
+export function renderReleaseNote(note, record) {
+    const lines = [];
+    lines.push(`# ${note.headline}`, "");
+    lines.push(note.plain_md, "");
+    lines.push(note.formal_md, "");
+    lines.push("## Evidence", "");
+    for (const claim of note.claims) {
+        const { resolved, value } = resolveEvidencePath(record, claim.evidence);
+        const held = resolved ? evidenceValueString(value) : null;
+        const claimed = claim.value;
+        // Supported iff the path resolved AND (no value was claimed, or the claimed value matches what the
+        // record holds). Otherwise the row is marked UNSUPPORTED naming what the record actually holds.
+        const supported = resolved && (claimed === undefined || held === claimed);
+        if (supported) {
+            lines.push(`- ${claim.text} — \`${claim.evidence}\` → \`${held ?? ""}\``);
+        }
+        else if (!resolved) {
+            lines.push(`- ${claim.text} — \`${claim.evidence}\` → UNSUPPORTED (the path does not resolve in the record)`);
+        }
+        else {
+            lines.push(`- ${claim.text} — \`${claim.evidence}\` → UNSUPPORTED (the record holds \`${held}\`)`);
+        }
+    }
+    const unreadable = note.unreadable ?? [];
+    if (unreadable.length > 0) {
+        lines.push("", "## Unreadable surfaces", "");
+        for (const surface of unreadable) {
+            lines.push(`- \`${surface}\` could not be read at this release`);
+        }
+    }
+    return lines.join("\n") + "\n";
+}
+//# sourceMappingURL=releases.js.map