@intentius/chant 0.101.0 → 0.104.0

package/src/workspace/symbols.ts

@@ -0,0 +1,191 @@
+/**
+ * Symbol regions for the intent walk (#3034): `graph --intent <path>#<symbol>`
+ * names a function, class, method, type or constant instead of a line range,
+ * because a line range means something else once the file is edited.
+ *
+ * A resolver turns a symbol into its current lines in the tree read, and the
+ * walk follows those lines through history as it follows any line range
+ * (`git log -L`). Resolvers are chosen by file extension. Core ships one for
+ * TypeScript and JavaScript, parsed with the TypeScript compiler chant already
+ * depends on. A lexicon can contribute more through its plugin's
+ * `symbolResolvers()` (#3313), which the intent walk loads for a file in a
+ * member that configures the lexicon (`lexicon-symbols.ts`); core's resolver
+ * stays the one for `.ts` and `.js`. A file with no resolver is refused with
+ * `intent-symbol-unsupported`, and a line range still works for it.
+ *
+ * A symbol is a name, or a dotted path through classes, namespaces,
+ * interfaces, enums and object literals bound to a constant, such as
+ * `createApp` or `Server.listen`. A bare name is looked up among the
+ * file's top-level declarations first, then among every nested one; when it
+ * matches more than one declaration it is refused as ambiguous, with the
+ * qualified names that would pick one. The lines run from the declaration's
+ * doc comment, when it has one, to its last line.
+ */
+
+import * as ts from "typescript";
+import type { LineRange } from "./intent";
+
+/** One declaration a resolver found. */
+export interface SymbolDeclaration {
+  /** The dotted path from the file's top level, such as `Server.listen`. */
+  qualified: string;
+  /** What declares it: function, class, method, property, interface, type, enum, namespace, variable, member. */
+  kind: string;
+  lines: LineRange;
+}
+
+export type SymbolResolution =
+  | { ok: true; declaration: SymbolDeclaration }
+  | { ok: false; reason: "unsupported" | "unknown" | "ambiguous"; message: string; candidates: string[] };
+
+/** A language-aware resolver: every declaration in a file, by qualified name. */
+export interface SymbolResolver {
+  /** The language it reads, for messages. */
+  language: string;
+  extensions: readonly string[];
+  declarations(path: string, text: string): SymbolDeclaration[];
+}
+
+// ── TypeScript and JavaScript ────────────────────────────────────────────────
+
+function scriptKind(path: string): ts.ScriptKind {
+  if (/\.tsx$/.test(path)) return ts.ScriptKind.TSX;
+  if (/\.jsx$/.test(path)) return ts.ScriptKind.JSX;
+  if (/\.[cm]?js$/.test(path)) return ts.ScriptKind.JS;
+  return ts.ScriptKind.TS;
+}
+
+function nameText(name: ts.PropertyName | ts.BindingName | ts.ModuleName | undefined): string | undefined {
+  if (!name) return undefined;
+  if (ts.isIdentifier(name) || ts.isPrivateIdentifier(name) || ts.isStringLiteral(name) || ts.isNumericLiteral(name)) return name.text;
+  return undefined;
+}
+
+const typescriptResolver: SymbolResolver = {
+  language: "TypeScript and JavaScript",
+  extensions: [".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs"],
+  declarations(path, text) {
+    const sf = ts.createSourceFile(path, text, ts.ScriptTarget.Latest, true, scriptKind(path));
+    const out: SymbolDeclaration[] = [];
+    const lineOf = (pos: number) => sf.getLineAndCharacterOfPosition(pos).line + 1;
+    // The span: from the doc comment (or the statement holding a lone variable) to the node's end.
+    const push = (qualified: string, kind: string, node: ts.Node) => {
+      out.push({ qualified, kind, lines: { start: lineOf(node.getStart(sf, true)), end: lineOf(node.getEnd()) } });
+    };
+    const visitMembers = (prefix: string, members: ts.NodeArray<ts.Node>) => {
+      for (const m of members) {
+        const name = nameText((m as ts.NamedDeclaration).name as ts.PropertyName | undefined);
+        if (name === undefined) {
+          if (ts.isConstructorDeclaration(m)) push(`${prefix}.constructor`, "method", m);
+          continue;
+        }
+        const q = `${prefix}.${name}`;
+        if (ts.isMethodDeclaration(m) || ts.isMethodSignature(m) || ts.isGetAccessorDeclaration(m) || ts.isSetAccessorDeclaration(m)) push(q, "method", m);
+        else if (ts.isPropertyDeclaration(m) || ts.isPropertySignature(m)) {
+          push(q, "property", m);
+          if (ts.isPropertyDeclaration(m) && m.initializer) visitValue(q, m.initializer);
+        } else if (ts.isEnumMember(m)) push(q, "member", m);
+        else if (ts.isPropertyAssignment(m)) {
+          push(q, "property", m);
+          visitValue(q, m.initializer);
+        } else if (ts.isShorthandPropertyAssignment(m)) push(q, "property", m);
+      }
+    };
+    // A class expression or object literal bound to a name has members of its own.
+    const visitValue = (prefix: string, value: ts.Expression) => {
+      let v = value;
+      while (ts.isParenthesizedExpression(v) || ts.isAsExpression(v) || ts.isSatisfiesExpression(v)) v = v.expression;
+      if (ts.isClassExpression(v)) visitMembers(prefix, v.members);
+      else if (ts.isObjectLiteralExpression(v)) visitMembers(prefix, v.properties);
+    };
+    const visitStatements = (prefix: string, statements: ts.NodeArray<ts.Statement>) => {
+      const q = (name: string) => (prefix ? `${prefix}.${name}` : name);
+      for (const s of statements) {
+        if (ts.isFunctionDeclaration(s) && s.name) push(q(s.name.text), "function", s);
+        else if (ts.isClassDeclaration(s) && s.name) {
+          push(q(s.name.text), "class", s);
+          visitMembers(q(s.name.text), s.members);
+        } else if (ts.isInterfaceDeclaration(s)) {
+          push(q(s.name.text), "interface", s);
+          visitMembers(q(s.name.text), s.members);
+        } else if (ts.isTypeAliasDeclaration(s)) push(q(s.name.text), "type", s);
+        else if (ts.isEnumDeclaration(s)) {
+          push(q(s.name.text), "enum", s);
+          visitMembers(q(s.name.text), s.members);
+        } else if (ts.isModuleDeclaration(s)) {
+          const name = nameText(s.name);
+          if (name === undefined) continue;
+          push(q(name), "namespace", s);
+          let body = s.body;
+          let inner = q(name);
+          while (body && ts.isModuleDeclaration(body)) {
+            inner = `${inner}.${nameText(body.name)}`;
+            body = body.body;
+          }
+          if (body && ts.isModuleBlock(body)) visitStatements(inner, body.statements);
+        } else if (ts.isVariableStatement(s)) {
+          const lone = s.declarationList.declarations.length === 1;
+          for (const d of s.declarationList.declarations) {
+            const name = nameText(d.name);
+            if (name === undefined) continue;
+            // A lone declaration takes its statement's lines, so `export const x = ...` and its doc comment are in the region.
+            push(q(name), "variable", lone ? s : d);
+            if (d.initializer) visitValue(q(name), d.initializer);
+          }
+        } else if (ts.isExportAssignment(s) && !s.isExportEquals) {
+          push(q("default"), "variable", s);
+          visitValue(q("default"), s.expression);
+        }
+      }
+    };
+    visitStatements("", sf.statements);
+    return out;
+  },
+};
+
+/** The resolvers core ships, chosen by the file's extension. */
+export const SYMBOL_RESOLVERS: readonly SymbolResolver[] = [typescriptResolver];
+
+/**
+ * The resolver for a path, or undefined when none reads its language. Core's
+ * resolvers come first, so a lexicon's never takes `.ts` or `.js` from them;
+ * among `extra`, the first that names the extension wins.
+ */
+export function symbolResolverFor(path: string, extra: readonly SymbolResolver[] = []): SymbolResolver | undefined {
+  const lower = path.toLowerCase();
+  return [...SYMBOL_RESOLVERS, ...extra].find((r) => r.extensions.some((e) => lower.endsWith(e.toLowerCase())));
+}
+
+/**
+ * Resolve `symbol` in the file `path` holding `text`: its current lines, or
+ * why it can't be. `extra` are the resolvers a lexicon contributed for the
+ * file's member (#3313).
+ */
+export function resolveSymbol(path: string, text: string, symbol: string, extra: readonly SymbolResolver[] = []): SymbolResolution {
+  const resolver = symbolResolverFor(path, extra);
+  if (!resolver) {
+    const known = [...new Set([...SYMBOL_RESOLVERS, ...extra].flatMap((r) => r.extensions))].join(", ");
+    return { ok: false, reason: "unsupported", message: `${path} has no symbol resolver: symbols resolve in ${known} files. Give a line range, ${path}:<start>-<end>, instead`, candidates: [] };
+  }
+  const all = resolver.declarations(path, text);
+  const exact = all.filter((d) => d.qualified === symbol);
+  // A name declared twice at one path, such as an overload or a merged declaration, is one region from the first to the last.
+  if (exact.length > 0) {
+    const start = Math.min(...exact.map((d) => d.lines.start));
+    const end = Math.max(...exact.map((d) => d.lines.end));
+    return { ok: true, declaration: { qualified: symbol, kind: exact[0].kind, lines: { start, end } } };
+  }
+  const nested = [...new Set(all.filter((d) => d.qualified.endsWith(`.${symbol}`)).map((d) => d.qualified))];
+  if (nested.length === 1) return resolveSymbol(path, text, nested[0], extra);
+  if (nested.length > 1) {
+    return { ok: false, reason: "ambiguous", message: `${symbol} names ${nested.length} declarations in ${path}: ${nested.join(", ")}. Give the qualified name`, candidates: nested };
+  }
+  const top = [...new Set(all.filter((d) => !d.qualified.includes(".")).map((d) => d.qualified))];
+  const shown = top.slice(0, 20);
+  return {
+    ok: false,
+    reason: "unknown",
+    message: `${path} declares no ${symbol}${top.length > 0 ? `; its top-level declarations are ${shown.join(", ")}${top.length > shown.length ? `, and ${top.length - shown.length} more` : ""}` : ", and no top-level declaration a resolver reads"}`,
+    candidates: shown,
+  };
+}

package/src/workspace/trailer-joins.test.ts

@@ -0,0 +1,171 @@
+/**
+ * chant's commit trailers (#3149): the vocabulary, and the joins `graph
+ * --intent` and `graph --intent --record` make through it.
+ *
+ * - c0 adds the workspace and s-001, decided, which constrains path:app.
+ * - c1 adds W-001, open, implementing s-001.
+ * - c2 edits app/main.js with Chant-Record: work:W-001, Chant-Run and Chant-Agent.
+ * - c3 edits app/main.js with only a Chant-Lease, whose token the lease
+ *   history of W-001 on chant/lifecycle names.
+ * - c4 edits app/main.js with Chant-Record: decision:s-001.
+ * - c5 edits app/main.js with nothing to account for it.
+ * - c6 edits app/main.js with a Chant-Record no kind has, and the apply trailers.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { writeBlobToPath } from "../lifecycle/git";
+import { cleanScratch, contract, git, REPO, repo, writeFiles } from "./__fixtures__/contract-repo";
+import { intentGraph, type CommitNode, type IntentDocument } from "./intent";
+import { intentRecord, type IntentRecordDocument } from "./intent-record";
+import intentRecordSchema from "./intent-record.schema.json";
+import intentSchema from "./intent.schema.json";
+import { parseFrontMatter } from "./records";
+import { formatChantTrailers, parseRecordRef, readChantTrailers } from "./trailers";
+
+const REF = join(REPO, "reference-workspace");
+const BASE = (() => {
+  const fm = parseFrontMatter(readFileSync(join(REF, "decisions", "ref-001-how-the-app-is-deployed.md"), "utf-8"));
+  if (!fm.ok) throw new Error(fm.message);
+  return fm.value;
+})();
+
+function decision(id: string, fields: Record<string, unknown>): string {
+  const data = { ...BASE, id, title: `Decision ${id}`, state: "decided", supersedes: [], evidence: [], reviews: [], ...fields };
+  return `---\n${JSON.stringify(data, null, 2)}\n---\n\n# ${id}\n`;
+}
+
+function work(id: string, fields: Record<string, unknown>): string {
+  const data = { schema: 1, id, title: `Work ${id}`, state: "open", implements: [], needs: [], constrains: [], evidence: [], opened_on: "2026-10-01", supersedes: [], ...fields };
+  return `---\n${JSON.stringify(data, null, 2)}\n---\n\n# ${id}\n\nWhat the work is.\n`;
+}
+
+const TOKEN = "3f0c7d2e-lease-token";
+const TIP = "a".repeat(40);
+let root: string;
+const sha: Record<string, string> = {};
+let tick = 0;
+
+function commit(message: string[]): string {
+  const date = `2026-10-01T12:00:${String(tick++).padStart(2, "0")}Z`;
+  process.env.GIT_AUTHOR_DATE = date;
+  process.env.GIT_COMMITTER_DATE = date;
+  try {
+    git(root, "add", "-A");
+    git(root, "commit", "-q", ...message.flatMap((m) => ["-m", m]));
+  } finally {
+    delete process.env.GIT_AUTHOR_DATE;
+    delete process.env.GIT_COMMITTER_DATE;
+  }
+  return git(root, "rev-parse", "HEAD");
+}
+
+const KINDS = ["decisions/decision.kind.mjs", "work/work.kind.mjs"];
+
+beforeAll(async () => {
+  root = repo({
+    "chant.workspace.json": JSON.stringify({ name: "trailers", schema: 1, members: [{ name: "app", dir: "app", kind: "other", because: "the app" }] }),
+    "decisions/decision.kind.mjs": readFileSync(join(REF, "decisions", "decision.kind.mjs"), "utf-8"),
+    "decisions/decision.schema.json": readFileSync(join(REF, "decisions", "decision.schema.json"), "utf-8"),
+    "work/work.kind.mjs": readFileSync(join(REF, "work", "work.kind.mjs"), "utf-8"),
+    "work/work.schema.json": readFileSync(join(REF, "work", "work.schema.json"), "utf-8"),
+    "app/main.js": "export const n = 0;\n",
+    "decisions/s-001-app.md": decision("s-001", { constrains: ["path:app"] }),
+  });
+  sha.c0 = commit(["the workspace, and s-001"]);
+  writeFiles(root, { "work/W-001-app.md": work("W-001", { implements: ["s-001"] }) });
+  sha.c1 = commit(["W-001"]);
+  writeFiles(root, { "app/main.js": "export const n = 1;\n" });
+  sha.c2 = commit(["one", formatChantTrailers({ agent: "factory", run: "r-0001", records: ["work:W-001"] }).join("\n")]);
+  writeFiles(root, { "app/main.js": "export const n = 2;\n" });
+  sha.c3 = commit(["two", `Chant-Lease: ${TOKEN}`]);
+  writeFiles(root, { "app/main.js": "export const n = 3;\n" });
+  sha.c4 = commit(["three", "Chant-Record: decision:s-001"]);
+  writeFiles(root, { "app/main.js": "export const n = 4;\n" });
+  sha.c5 = commit(["four"]);
+  writeFiles(root, { "app/main.js": "export const n = 5;\n" });
+  sha.c6 = commit(["five", formatChantTrailers({ records: [{ kind: "contract", id: "C-001" }], applied: { by: "alice", at: "2026-10-01T12:00:06Z", commit: TIP } }).join("\n")]);
+  const line = { version: 1, event: "claim", item: "W-001", holder: "factory", by: "factory", token: TOKEN, acquiredAt: "2026-10-01T12:00:00Z", expiresAt: "2026-10-01T12:10:00Z", timestamp: "2026-10-01T12:00:00Z" };
+  await writeBlobToPath("_leases", "W-001.jsonl", JSON.stringify(line), "Work lease claim: W-001", { cwd: root });
+});
+afterAll(cleanScratch);
+
+describe("the trailer vocabulary", () => {
+  test("formats in a fixed order and reads back what it wrote", () => {
+    const lines = formatChantTrailers({ applied: { by: "bob", commit: TIP }, records: ["work:W-1", { kind: "decision", id: "ws-075" }], run: "r-1", lease: "tok", agent: "factory" });
+    expect(lines).toEqual(["Chant-Agent: factory", "Chant-Lease: tok", "Chant-Run: r-1", "Chant-Record: work:W-1", "Chant-Record: decision:ws-075", "Chant-Applied-By: bob", `Chant-Applied-Commit: ${TIP}`]);
+    const trailers: Record<string, string[]> = {};
+    for (const l of lines) (trailers[l.slice(0, l.indexOf(":"))] ??= []).push(l.slice(l.indexOf(":") + 1).trim());
+    expect(readChantTrailers(trailers)).toEqual({
+      agent: "factory",
+      lease: "tok",
+      run: "r-1",
+      records: [
+        { kind: "work", id: "W-1" },
+        { kind: "decision", id: "ws-075" },
+      ],
+      applied: { by: "bob", at: null, commit: TIP },
+    });
+  });
+
+  test("refuses a value git would read differently", () => {
+    expect(() => formatChantTrailers({ run: "a\nb" })).toThrow(/one line/);
+    expect(() => formatChantTrailers({ records: ["W-1"] })).toThrow(/<kind>:<id>/);
+    expect(() => formatChantTrailers({ applied: { by: "x", commit: "abc" } })).toThrow(/full commit id/);
+  });
+
+  test("reads keys without case and skips malformed record refs", () => {
+    expect(parseRecordRef("Work:W-1")).toBeUndefined();
+    const t = readChantTrailers({ "chant-record": ["work:W-1", "nonsense", "work:W-1"], "CHANT-RUN": ["r-9"] });
+    expect(t.records).toEqual([{ kind: "work", id: "W-1" }]);
+    expect(t.run).toBe("r-9");
+    expect(t.applied).toBeNull();
+  });
+});
+
+const intentContract = contract(intentSchema);
+const recordContract = contract(intentRecordSchema);
+
+async function region(): Promise<Exclude<IntentDocument, { error: unknown }>> {
+  const { doc } = await intentGraph({ cwd: root, region: "app/main.js", kinds: KINDS.map((k) => join(root, k)) });
+  intentContract.expectValid(doc);
+  if ("error" in doc) throw new Error(`${doc.error.code}: ${doc.error.message}`);
+  return doc;
+}
+
+describe("graph --intent joins a commit through chant's trailers", () => {
+  test("each commit node reports what its trailers name", async () => {
+    const doc = await region();
+    const commit = (k: string) => doc.nodes.find((n) => n.id === `commit:${sha[k]}`) as CommitNode;
+    expect(commit("c2").joins).toEqual({ agent: "factory", lease: null, run: "r-0001", records: [{ kind: "work", id: "W-001", node: "record:work/W-001" }], applied: null });
+    expect(commit("c3").joins.lease).toEqual({ token: TOKEN, item: "W-001" });
+    expect(commit("c4").joins.records).toEqual([{ kind: "decision", id: "s-001", node: "record:decision/s-001" }]);
+    expect(commit("c5").joins).toEqual({ agent: null, lease: null, run: null, records: [], applied: null });
+    expect(commit("c6").joins.records).toEqual([{ kind: "contract", id: "C-001", node: null }]);
+    expect(commit("c6").joins.applied).toEqual({ by: "alice", at: "2026-10-01T12:00:06Z", commit: TIP });
+  });
+
+  test("a carried record makes the commit the decision's own work", async () => {
+    const doc = await region();
+    const state = (k: string) => (doc.nodes.find((n) => n.id === `commit:${sha[k]}`) as CommitNode).state;
+    expect(state("c2")).toBe("decided");
+    expect(state("c3")).toBe("decided");
+    expect(state("c4")).toBe("decided");
+    expect(state("c5")).toBe("decided-by-window");
+    expect(state("c6")).toBe("decided-by-window");
+    const carries = doc.edges.filter((e) => e.kind === "carries").map((e) => `${e.from} ${e.to}`);
+    // Newest first, as the history lists the commits.
+    expect(carries).toEqual([`commit:${sha.c4} record:decision/s-001`, `commit:${sha.c3} record:work/W-001`, `commit:${sha.c2} record:work/W-001`]);
+    expect(doc.nodes.some((n) => n.id === "record:work/W-001" && n.kind === "work")).toBe(true);
+  });
+
+  test("graph --intent --record buckets the same commits as own", async () => {
+    const { doc } = await intentRecord({ cwd: root, record: "s-001", kinds: KINDS.map((k) => join(root, k)) });
+    recordContract.expectValid(doc);
+    if ("error" in doc) throw new Error(doc.error.message);
+    const bucket = (k: string) => (doc as Exclude<IntentRecordDocument, { error: unknown }>).commits.find((c) => c.sha === sha[k])?.bucket;
+    expect([bucket("c2"), bucket("c3"), bucket("c4"), bucket("c5")]).toEqual(["own", "own", "own", "worked"]);
+    expect(doc.commits.find((c) => c.sha === sha.c3)?.joins.lease).toEqual({ token: TOKEN, item: "W-001" });
+  });
+});

package/src/workspace/trailer-joins.ts

@@ -0,0 +1,82 @@
+/**
+ * Joining a commit through chant's own trailers (#3149, ws-075), for `graph
+ * --intent` and `graph --intent --record`.
+ *
+ * A plugin's `commitJoins` reads a kind's own trailers (`intent-joins.ts`).
+ * These are core's: a `Chant-Record` names a record by kind and id, and a
+ * `Chant-Lease` names a work lease by its fencing token, which the lease
+ * histories on `chant/lifecycle` turn into the work item it was taken on.
+ * Both read the local branch and never fetch.
+ */
+
+import { execFileSync } from "node:child_process";
+import { parseLeaseHistory } from "../lifecycle/work-lease";
+import { readChantTrailers, type AppliedTrailers, type ChantTrailers } from "./trailers";
+
+/** The branch the lease histories are on. */
+const LEDGER_BRANCH = "refs/heads/chant/lifecycle";
+
+/** What chant's trailers on one commit join it to, as a commit in `graph --intent` reports it. */
+export interface CommitTrailerJoins {
+  /** `Chant-Agent`: the agent session that wrote the commit. */
+  agent: string | null;
+  /** `Chant-Lease`: the work lease's token, and the work item a lease history on `chant/lifecycle` names for it, or null when none does. */
+  lease: { token: string; item: string | null } | null;
+  /** `Chant-Run`: the agent run that made the commit. */
+  run: string | null;
+  /** Each `Chant-Record`, with the id of its node in the graph, or null when no kind read has the record. */
+  records: { kind: string; id: string; node: string | null }[];
+  /** The `Chant-Applied-*` trailers of a commit that applied a leased branch. */
+  applied: AppliedTrailers | null;
+}
+
+function git(top: string, args: string[]): string | undefined {
+  try {
+    return execFileSync("git", args, { cwd: top, encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"], maxBuffer: 256 * 1024 * 1024 });
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The work item each lease token names, from the lease histories
+ * (`_leases/<item>.jsonl`, any member's) on the local `chant/lifecycle`
+ * branch. A token no history names is left out. Never fetches.
+ */
+export function leaseItemsByToken(top: string, tokens: string[]): Map<string, string> {
+  const out = new Map<string, string>();
+  const wanted = [...new Set(tokens.filter((t) => t !== ""))];
+  if (wanted.length === 0 || git(top, ["rev-parse", "--verify", "--quiet", LEDGER_BRANCH]) === undefined) return out;
+  const listed = git(top, ["grep", "-l", "-F", ...wanted.flatMap((t) => ["-e", t]), LEDGER_BRANCH, "--", ":(glob)**/_leases/*.jsonl"]);
+  for (const line of (listed ?? "").split("\n")) {
+    const path = line.startsWith(`${LEDGER_BRANCH}:`) ? line.slice(LEDGER_BRANCH.length + 1) : "";
+    const m = path.match(/(?:^|\/)_leases\/([^/]+)\.jsonl$/);
+    if (!m) continue;
+    const text = git(top, ["show", `${LEDGER_BRANCH}:${path}`]);
+    for (const r of parseLeaseHistory(text ?? "").records) if (wanted.includes(r.token) && r.item === m[1] && !out.has(r.token)) out.set(r.token, r.item);
+  }
+  return out;
+}
+
+/** Read chant's trailers from each commit, and the work items their lease tokens name. */
+export function readTrailerJoins(top: string, commits: { sha: string; trailers: Record<string, string[]> }[]): Map<string, { trailers: ChantTrailers; joins: CommitTrailerJoins }> {
+  const read = commits.map((c) => ({ sha: c.sha, trailers: readChantTrailers(c.trailers) }));
+  const items = leaseItemsByToken(
+    top,
+    read.map((r) => r.trailers.lease).filter((t): t is string => t !== null),
+  );
+  const out = new Map<string, { trailers: ChantTrailers; joins: CommitTrailerJoins }>();
+  for (const { sha, trailers } of read) {
+    out.set(sha, {
+      trailers,
+      joins: {
+        agent: trailers.agent,
+        lease: trailers.lease === null ? null : { token: trailers.lease, item: items.get(trailers.lease) ?? null },
+        run: trailers.run,
+        records: trailers.records.map((r) => ({ kind: r.kind, id: r.id, node: null })),
+        applied: trailers.applied,
+      },
+    });
+  }
+  return out;
+}

package/src/workspace/trailers.ts

@@ -0,0 +1,148 @@
+/**
+ * chant's commit trailers (#3149, ws-075): the vocabulary a commit uses to
+ * name the lease, the agent run, the records and the apply behind it.
+ *
+ * A trailer is how a commit points at a fact kept elsewhere: a work lease on
+ * `chant/lifecycle`, an agent run in the run ledger (#3033), a record in the
+ * working tree. Provenance is keyed to those ids, never to commit SHAs, so a
+ * commit that keeps its message through a rebase or a cherry-pick keeps its
+ * joins (#3037). chant never writes a commit itself (ws-074): whoever makes
+ * the commit adds the trailers, and chant reads them back in `graph
+ * --intent`, `graph --intent --record` and `workspace runs`.
+ *
+ * | Trailer | Value | Names |
+ * |---|---|---|
+ * | `Chant-Agent` | an agent session | the session that wrote the commit (ws-067) |
+ * | `Chant-Lease` | a fencing token | the work lease the commit was made under |
+ * | `Chant-Run` | a run id | the agent run that made the commit (#3033) |
+ * | `Chant-Record` | `<kind>:<id>` | a record the commit carries out or changes; repeatable |
+ * | `Chant-Applied-By` | a principal | who applied a leased branch, on the apply commit |
+ * | `Chant-Applied-At` | ISO 8601 | when it was applied |
+ * | `Chant-Applied-Commit` | a commit id | the tip of the branch that was applied |
+ *
+ * Every other trailer is a plugin's, and core gives it no meaning; a kind's
+ * `commitJoins` may (`intent-joins.ts`).
+ */
+
+import { trailerValue, trailerValues } from "./intent-joins";
+
+/** The agent session that wrote a commit (ws-067). */
+export const AGENT_TRAILER = "Chant-Agent";
+/** The fencing token of the work lease a commit was made under. */
+export const LEASE_TRAILER = "Chant-Lease";
+/** The agent run that made a commit (#3033). */
+export const RUN_TRAILER = "Chant-Run";
+/** A record a commit carries out or changes, as `<kind>:<id>`. Repeatable. */
+export const RECORD_TRAILER = "Chant-Record";
+/** Who applied a leased branch, on the commit that applied it. */
+export const APPLIED_BY_TRAILER = "Chant-Applied-By";
+/** When the branch was applied, ISO 8601. */
+export const APPLIED_AT_TRAILER = "Chant-Applied-At";
+/** The tip of the branch that was applied. */
+export const APPLIED_COMMIT_TRAILER = "Chant-Applied-Commit";
+
+/** Every trailer key core reads, in the order a writer should add them. */
+export const CHANT_TRAILERS = [AGENT_TRAILER, LEASE_TRAILER, RUN_TRAILER, RECORD_TRAILER, APPLIED_BY_TRAILER, APPLIED_AT_TRAILER, APPLIED_COMMIT_TRAILER] as const;
+
+/** A record kind's name, as a kind file's `recordKind.name` gives it. */
+const KIND_NAME = /^[a-z][a-z0-9-]*$/;
+/** A record id, as the record kinds allocate them and as a work lease keys them. */
+const RECORD_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const COMMIT_ID = /^[0-9a-f]{40,64}$/;
+
+/** One `Chant-Record` value. */
+export interface RecordRef {
+  /** The record kind's name, such as `decision` or `work`. */
+  kind: string;
+  id: string;
+}
+
+/** An apply, from the `Chant-Applied-*` trailers. */
+export interface AppliedTrailers {
+  by: string;
+  /** ISO 8601, or null when the trailer is missing. */
+  at: string | null;
+  /** The applied branch's tip, or null when the trailer is missing or is not a commit id. */
+  commit: string | null;
+}
+
+/** What chant's own trailers on one commit say. */
+export interface ChantTrailers {
+  agent: string | null;
+  lease: string | null;
+  run: string | null;
+  /** Each well-formed `Chant-Record` value, in order, without repeats. */
+  records: RecordRef[];
+  applied: AppliedTrailers | null;
+}
+
+/** Parse one `Chant-Record` value, `<kind>:<id>`, or undefined when it is not one. */
+export function parseRecordRef(value: string): RecordRef | undefined {
+  const colon = value.indexOf(":");
+  if (colon <= 0) return undefined;
+  const kind = value.slice(0, colon).trim();
+  const id = value.slice(colon + 1).trim();
+  return KIND_NAME.test(kind) && RECORD_ID.test(id) ? { kind, id } : undefined;
+}
+
+/** Read chant's own trailers from a commit's parsed trailers. Keys compare without case, as git's do. */
+export function readChantTrailers(trailers: Record<string, string[]>): ChantTrailers {
+  const records: RecordRef[] = [];
+  for (const v of trailerValues(trailers, RECORD_TRAILER)) {
+    const ref = parseRecordRef(v);
+    if (ref && !records.some((r) => r.kind === ref.kind && r.id === ref.id)) records.push(ref);
+  }
+  const by = trailerValue(trailers, APPLIED_BY_TRAILER) ?? null;
+  const commit = trailerValue(trailers, APPLIED_COMMIT_TRAILER) ?? null;
+  return {
+    agent: trailerValue(trailers, AGENT_TRAILER) ?? null,
+    lease: trailerValue(trailers, LEASE_TRAILER) ?? null,
+    run: trailerValue(trailers, RUN_TRAILER) ?? null,
+    records,
+    applied: by === null ? null : { by, at: trailerValue(trailers, APPLIED_AT_TRAILER) ?? null, commit: commit !== null && COMMIT_ID.test(commit) ? commit : null },
+  };
+}
+
+/** Whether a commit carries any of chant's own trailers. */
+export function hasChantTrailers(t: ChantTrailers): boolean {
+  return t.agent !== null || t.lease !== null || t.run !== null || t.records.length > 0 || t.applied !== null;
+}
+
+/** What a writer passes to {@link formatChantTrailers}. */
+export interface ChantTrailerInput {
+  agent?: string;
+  lease?: string;
+  run?: string;
+  records?: (RecordRef | string)[];
+  applied?: { by: string; at?: string; commit?: string };
+}
+
+/**
+ * The trailer lines for a commit message, in {@link CHANT_TRAILERS} order.
+ * Throws when a value holds a line break or a record ref is malformed, since
+ * either would write a trailer git parses differently.
+ */
+export function formatChantTrailers(input: ChantTrailerInput): string[] {
+  const lines: string[] = [];
+  const add = (key: string, value: string | undefined) => {
+    if (value === undefined) return;
+    const v = value.trim();
+    if (v === "" || /[\r\n]/.test(v)) throw new Error(`${key} takes one line of text, not ${JSON.stringify(value)}`);
+    lines.push(`${key}: ${v}`);
+  };
+  add(AGENT_TRAILER, input.agent);
+  add(LEASE_TRAILER, input.lease);
+  add(RUN_TRAILER, input.run);
+  for (const r of input.records ?? []) {
+    const ref = typeof r === "string" ? parseRecordRef(r) : r;
+    if (!ref || !KIND_NAME.test(ref.kind) || !RECORD_ID.test(ref.id)) throw new Error(`${RECORD_TRAILER} takes <kind>:<id>, not ${JSON.stringify(r)}`);
+    add(RECORD_TRAILER, `${ref.kind}:${ref.id}`);
+  }
+  if (input.applied) {
+    add(APPLIED_BY_TRAILER, input.applied.by);
+    add(APPLIED_AT_TRAILER, input.applied.at);
+    if (input.applied.commit !== undefined && !COMMIT_ID.test(input.applied.commit)) throw new Error(`${APPLIED_COMMIT_TRAILER} takes a full commit id, not ${JSON.stringify(input.applied.commit)}`);
+    add(APPLIED_COMMIT_TRAILER, input.applied.commit);
+  }
+  return lines;
+}