@intentius/chant 0.101.0 → 0.102.0

package/src/workspace/intent-cli.ts

@@ -1,9 +1,10 @@
 /**
- * `chant workspace graph --intent <path[:start-end]> [--at <rev>] [--kind <kind file>...] [--json]`
- * (#2651): the intent graph over one region (`intent.ts`), printed as JSON
+ * `chant workspace graph --intent <path[:start-end]|path#symbol> [--at <rev>] [--kind <kind file>...] [--json]`
+ * (#2651, #3034): the intent graph over one region (`intent.ts`), printed as JSON
  * with `--json` or as a walk, one line per node, in the order of #2650
  * section B: the region, its decisions, their artifacts, the commits, and the
- * findings. Under each decision come the commits made inside its window, and
+ * findings, then why the region is like this: who made its current lines and
+ * the decisions governing it, most relevant first. Under each decision come the commits made inside its window, and
  * when any of them is not the decision's own work, the question #2650 B puts
  * to the person about it (#2656). Without `--kind`, the walk reads every
  * record kind the declaration names (#2680).
@@ -13,9 +14,9 @@ import { resolve } from "node:path";
 import { formatError } from "../cli/format";
 import type { CommandContext } from "../cli/registry";
 import { intentRecord, type IntentRecordDocument } from "./intent-record";
-import { intentGraph, type ArtifactNode, type CommitNode, type DecisionNode, type IntentDocument, type IntentEdge, type IntentNode, type WorkNode } from "./intent";
+import { intentGraph, type ArtifactNode, type CommitNode, type DecisionNode, type IntentDocument, type IntentEdge, type IntentNode, type RunNode, type WhyAnswer, type WorkNode } from "./intent";
 
-const USAGE = "chant workspace graph --intent <path[:start-end]> [--at <rev>] [--kind <kind file>...] [--json]";
+const USAGE = "chant workspace graph --intent <path[:start-end]|path#symbol> [--at <rev>] [--kind <kind file>...] [--json]";
 const RECORD_USAGE = "chant workspace graph --intent --record <id> [--at <rev>] [--kind <kind file>...] [--json]";
 
 type Result = Exclude<IntentDocument, { error: unknown }>;
@@ -45,7 +46,10 @@ function withinLines(doc: Result, d: DecisionNode): string[] {
       .map((p) => doc.nodes.find((n) => n.id === p.to))
       .map((n) => (n && "ref" in n ? n.ref : undefined))
       .filter(Boolean);
-    const by = unit.length > 0 ? `unit ${unit.join(", ")}` : "no unit";
+    const carried = (c.joins?.records ?? []).filter((r) => r.node !== null).map((r) => `${r.kind}:${r.id}`);
+    const item = c.joins?.lease?.item;
+    if (item && !carried.some((r) => r.endsWith(`:${item}`))) carried.push(`lease on ${item}`);
+    const by = unit.length > 0 ? `unit ${unit.join(", ")}` : carried.length > 0 ? `carries ${carried.join(", ")}` : "no unit";
     const label = e.state === "decided" ? "decided " : "within  ";
     out.push(`  ${label}  ${short(c.sha)} ${c.subject}; ${by}${e.state === "decided" ? `, ${d.record}'s own work` : `, in ${d.record}'s window and not its work`}`);
   }
@@ -85,6 +89,17 @@ function artifactLine(doc: Result, a: ArtifactNode): string {
   return `artifact  ${a.path} ${a.pinState}; pinned by ${by.join(", ")}; now ${short(a.currentSha256)}`;
 }
 
+/** What chant's own trailers on a commit say (#3149), one line each. */
+function joinLines(j: CommitNode["joins"] | undefined): string[] {
+  if (!j) return [];
+  const out: string[] = [];
+  if (j.agent) out.push(`  agent     ${j.agent}`);
+  if (j.lease) out.push(`  lease     ${j.lease.token}${j.lease.item ? ` on ${j.lease.item}` : ", no lease history names it"}`);
+  for (const r of j.records) out.push(`  record    ${r.kind}:${r.id}${r.node ? "" : ", in no kind read"}`);
+  if (j.applied) out.push(`  applied   by ${j.applied.by}${j.applied.at ? ` at ${j.applied.at}` : ""}${j.applied.commit ? `, ${short(j.applied.commit)}` : ""}`);
+  return out;
+}
+
 function commitLine(doc: Result, c: CommitNode): string[] {
   const lines = c.lines && c.lines.length > 0 ? `, lines ${c.lines.map((l) => (l.start === l.end ? `${l.start}` : `${l.start}-${l.end}`)).join(", ")}` : "";
   const out = [`commit    ${short(c.sha)} ${c.date.slice(0, 10)} ${c.author.name}: ${c.subject}${lines}; ${c.signature.level}`];
@@ -94,6 +109,40 @@ function commitLine(doc: Result, c: CommitNode): string[] {
     for (const s of edgesFrom(doc, e.to, "serves")) out.push(`  contract  ${s.to.slice("contract:".length)}`);
     for (const s of edgesFrom(doc, e.to, "cites-evidence")) out.push(`  evidence  ${s.to.slice("evidence:".length)}`);
   }
+  out.push(...joinLines(c.joins));
+  for (const e of edgesFrom(doc, c.id, "made-by")) {
+    const r = doc.nodes.find((n): n is RunNode => n.kind === "run" && n.id === e.to);
+    if (!r) continue;
+    const what = r.recorded ? `${[r.harness?.name, r.model].filter(Boolean).join("/") || "no model recorded"}${r.by ? ` for ${r.by}` : ""}${r.cost ? `, ${r.cost.amount} ${r.cost.currency}` : ", unpriced"}` : "not in the run ledger";
+    out.push(`  run       ${r.run}: ${what}`);
+  }
+  return out;
+}
+
+const span = (l: { start: number; end: number }) => (l.start === l.end ? `${l.start}` : `${l.start}-${l.end}`);
+
+/** Why the region is like this (#3034): the decisions most relevant first, then who made each span of its current lines, then the gaps. */
+export function whyLines(doc: Result, why: WhyAnswer): string[] {
+  const out: string[] = [];
+  const record = (id: string) => {
+    const n = doc.nodes.find((x) => x.id === id);
+    return n && (n.kind === "decision" || n.kind === "work") ? n.record : id;
+  };
+  const runLabel = (id: string) => {
+    const r = doc.nodes.find((n): n is RunNode => n.kind === "run" && n.id === id);
+    if (!r) return id;
+    const what = [r.harness?.name, r.model].filter(Boolean).join("/");
+    return `${r.run}${what ? ` (${what})` : r.recorded ? "" : " (not in the run ledger)"}${r.unit ? ` on ${r.unit}` : ""}`;
+  };
+  out.push(`why       ${why.explained ? "explained" : "unexplained"}${why.lines ? `, lines ${span(why.lines)}` : ""}`);
+  for (const d of why.decisions) {
+    out.push(`  decision  ${record(d.decision)} ${d.relevance}${d.lines > 0 ? `, ${d.lines} ${d.lines === 1 ? "line" : "lines"}` : ""}${d.current ? "" : ", superseded"}${d.closed ? ", closed" : ""}`);
+  }
+  for (const b of why.blame) {
+    const by = b.runs.length > 0 ? `; ${b.runs.map(runLabel).join(", ")}${b.narrowedBy ? " (by its hunks)" : ""}` : b.sha ? "; no run" : "";
+    out.push(`  lines     ${span(b)} ${b.sha ? short(b.sha) : "uncommitted"}${by}`);
+  }
+  for (const g of why.gaps) out.push(`  gap       ${g.code}: ${g.message}${g.lines ? ` (lines ${g.lines.map(span).join(", ")})` : ""}`);
   return out;
 }
 
@@ -104,7 +153,8 @@ export function formatIntent(doc: Result): string {
   if (region?.kind === "region") {
     const lines = region.lines ? `:${region.lines.start}${region.lines.end === region.lines.start ? "" : `-${region.lines.end}`}` : "";
     const where = doc.at ? `at ${short(doc.at)}` : "in the working tree";
-    out.push(`region    ${region.path}${lines} (${region.type}, member ${region.member ?? "none"}${region.generated ? ", generated" : ""}) ${where}${region.node ? `, from node ${region.node}` : ""}`);
+    const symbol = region.symbol ? `#${region.symbol.name} (${region.symbol.kind} ${region.symbol.qualified}, lines ${region.lines ? span(region.lines) : "none"})` : lines;
+    out.push(`region    ${region.path}${symbol} (${region.type}, member ${region.member ?? "none"}${region.generated ? ", generated" : ""}) ${where}${region.node ? `, from node ${region.node}` : ""}`);
   }
   const files = ofKind(doc, "file");
   if (files.length > 0) out.push(`files     ${files.length} under the region, ${files.filter((f) => f.generated).length} generated`);
@@ -121,6 +171,7 @@ export function formatIntent(doc: Result): string {
     out.push(`finding   ${f.code}: ${f.message}${by}`);
   }
   for (const r of doc.reasons) out.push(`reason    ${r.code}: ${r.message}`);
+  if (doc.why) out.push(...whyLines(doc, doc.why));
   const kinds = doc.kinds.length === 0 ? "; no --kind, so no decisions were read" : "";
   const work = ofKind(doc, "work").length;
   out.push(`${doc.summary.commits} commits, ${doc.summary.decisions} decisions, ${work > 0 ? `${work} work ${work === 1 ? "item" : "items"}, ` : ""}${doc.summary.artifacts} artifacts, ${doc.summary.findings} findings${kinds}`);
@@ -136,13 +187,16 @@ export function formatIntentRecord(doc: RecordResult): string {
   for (const c of doc.commits) {
     const why =
       c.bucket === "own"
-        ? `unit ${c.unit}`
+        ? c.unit !== null
+          ? `unit ${c.unit}`
+          : `carries ${[...(c.joins?.records ?? []).filter((x) => x.node !== null).map((x) => `${x.kind}:${x.id}`), ...(c.joins?.lease?.item ? [`lease on ${c.joins.lease.item}`] : [])].join(", ")}`
         : c.bucket === "worked"
           ? `worked by ${c.workedBy.map((w) => w.record).join(", ")}`
           : c.bucket === "within-other"
             ? `within ${c.alsoWithin.map((w) => w.record).join(", ")}`
             : "nothing else accounts for it";
-    out.push(`${c.bucket.padEnd(12)} ${short(c.sha)} ${c.date.slice(0, 10)} ${c.subject}; ${why}; ${c.files.join(", ") || c.entries.join(", ")}`);
+    const runs = (c.runs ?? []).map((r) => `run ${r.id}${r.model ? ` (${r.model})` : ""}`).join(", ");
+    out.push(`${c.bucket.padEnd(12)} ${short(c.sha)} ${c.date.slice(0, 10)} ${c.subject}; ${why}${runs ? `; ${runs}` : ""}; ${c.files.join(", ") || c.entries.join(", ")}`);
   }
   for (const x of doc.reasons) out.push(`reason    ${x.code}: ${x.message}`);
   const n = doc.counts;
@@ -172,7 +226,7 @@ export async function runWorkspaceIntent(ctx: CommandContext, cwd: string): Prom
     return runRecord(ctx, cwd, args.kinds ?? (args.kind !== undefined ? [args.kind] : undefined));
   }
   if (!args.intent) {
-    console.error(formatError({ message: "--intent needs a region: a path, path:line or path:start-end", hint: USAGE }));
+    console.error(formatError({ message: "--intent needs a region: a path, path:line, path:start-end or path#symbol", hint: USAGE }));
     return 1;
   }
   // No --kind: undefined, so the walk reads the kinds the declaration names (#2680).

package/src/workspace/intent-record.schema.json

@@ -402,6 +402,16 @@
             "$ref": "#/$defs/recordRef"
           },
           "description": "Each other decision whose window holds the commit and whose path: entries cover one of the commit's files."
+        },
+        "joins": {
+          "$ref": "#/$defs/trailerJoins"
+        },
+        "runs": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/runRef"
+          },
+          "description": "The agent runs that made the commit (#3033). Added within version 1, so an older document may lack it."
         }
       }
     },
@@ -524,6 +534,204 @@
         },
         "commits": false
       }
+    },
+    "trailerJoins": {
+      "type": "object",
+      "description": "What chant's own commit trailers join the commit to (#3149, ws-075). Added within version 1, so an older document may lack it.",
+      "required": [
+        "agent",
+        "lease",
+        "run",
+        "records",
+        "applied"
+      ],
+      "properties": {
+        "agent": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "Chant-Agent: the agent session that wrote the commit (ws-067)."
+        },
+        "lease": {
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "object",
+              "required": [
+                "token",
+                "item"
+              ],
+              "properties": {
+                "token": {
+                  "type": "string",
+                  "description": "Chant-Lease: the work lease's fencing token."
+                },
+                "item": {
+                  "type": [
+                    "string",
+                    "null"
+                  ],
+                  "description": "The work item a lease history on the local chant/lifecycle branch names for the token, or null when none does."
+                }
+              }
+            }
+          ]
+        },
+        "run": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "Chant-Run: the agent run that made the commit (#3033)."
+        },
+        "records": {
+          "type": "array",
+          "description": "Each well-formed Chant-Record value, <kind>:<id>, in order.",
+          "items": {
+            "type": "object",
+            "required": [
+              "kind",
+              "id",
+              "node"
+            ],
+            "properties": {
+              "kind": {
+                "type": "string",
+                "description": "The record kind's name."
+              },
+              "id": {
+                "type": "string"
+              },
+              "node": {
+                "type": [
+                  "string",
+                  "null"
+                ],
+                "description": "The id of the record's node, record:<kind>/<id>, when a kind read has the record; null otherwise."
+              }
+            }
+          }
+        },
+        "applied": {
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "object",
+              "required": [
+                "by",
+                "at",
+                "commit"
+              ],
+              "properties": {
+                "by": {
+                  "type": "string",
+                  "description": "Chant-Applied-By: who applied the branch."
+                },
+                "at": {
+                  "type": [
+                    "string",
+                    "null"
+                  ],
+                  "description": "Chant-Applied-At, ISO 8601, or null when it is missing."
+                },
+                "commit": {
+                  "type": [
+                    "string",
+                    "null"
+                  ],
+                  "description": "Chant-Applied-Commit: the applied branch's tip, or null when it is missing or not a commit id."
+                }
+              }
+            }
+          ]
+        }
+      }
+    },
+    "runRef": {
+      "type": "object",
+      "description": "An agent run that made the commit (#3033).",
+      "required": [
+        "id",
+        "recorded",
+        "state",
+        "harness",
+        "model",
+        "provider",
+        "by",
+        "agent",
+        "unit",
+        "joinedBy"
+      ],
+      "properties": {
+        "id": {
+          "type": "string"
+        },
+        "recorded": {
+          "type": "boolean",
+          "description": "Whether the run ledger on the local chant/lifecycle branch has the run. When false, only the id is known."
+        },
+        "state": {
+          "enum": [
+            "running",
+            "ended",
+            null
+          ]
+        },
+        "harness": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "model": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "provider": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "by": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "The principal the run worked for."
+        },
+        "agent": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "unit": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "The work item it worked on."
+        },
+        "joinedBy": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "enum": [
+              "trailer",
+              "record"
+            ]
+          },
+          "description": "trailer: the commit carries Chant-Run with the run's id. record: the run's end lists the commit."
+        }
+      }
     }
   }
 }

package/src/workspace/intent-record.ts

@@ -17,7 +17,8 @@
  *
  * - `own`: the record's own work, as the region walk judges it: a commit a
  *   plugin joins to a unit whose unit or contract names the record, or that
- *   serves a contract the record constrains.
+ *   serves a contract the record constrains; or a commit whose own trailers
+ *   (#3149) name the record, or a work item that implements it.
  * - `worked`: inside the window of a work item that is not dropped and that
  *   implements the record, or whose `path:` entries cover a file the commit
  *   changed in the record's region.
@@ -52,6 +53,8 @@ import { constraintCovers, isWorkspacePath, memberHolding } from "./record-asset
 import type { DecidedIn } from "./record-decided";
 import { RecordReadError } from "./records";
 import type { RecordView } from "./records-cli";
+import { runsForCommits, type RunRef } from "./runs";
+import { readTrailerJoins, type CommitTrailerJoins } from "./trailer-joins";
 import { joinPath } from "./tree";
 import { locateWorkspace } from "./which-chant";
 import { idList } from "./work";
@@ -91,6 +94,10 @@ export interface RecordCommit {
   pullRequest: number | null;
   /** The unit a plugin joined the commit to, or null. */
   unit: string | null;
+  /** What chant's own trailers join the commit to (#3149), as a commit node in `graph --intent` reports it. */
+  joins: CommitTrailerJoins;
+  /** The agent runs that made the commit (#3033): the one its Chant-Run names, and any whose record lists it. */
+  runs: RunRef[];
   /** The record's constrains entries whose history listed the commit. */
   entries: string[];
   /** The files the commit changed in the record's region, from the workspace root. Empty when git lists none, as for a merge that changed nothing against its first parent there. */
@@ -299,11 +306,36 @@ async function walk(query: IntentRecordQuery, head: Head): Promise<IntentRecordR
   const failedPlugins = new Set<string>();
   const constrainedContracts = constrains.filter((c) => c.granularity === "contract").map((c) => c.entry);
   const commits: RecordCommit[] = [];
+  // chant's own trailers (#3149): the record named outright, or a work item that implements it.
+  const trailerJoins = readTrailerJoins(top, [...details.values()]);
+  const recordKinds = new Map(kinds.filter((k) => k.records).map((k) => [k.records!.loaded.kind.name, k]));
+  const workKinds = kinds.filter((k) => k.records?.loaded.kind.work);
+  const runJoins = await runsForCommits(
+    top,
+    located.rootOnDisk,
+    shas.map((sha) => ({ sha, run: trailerJoins.get(sha)?.joins.run ?? null })),
+  );
+  const workImplements = (k: LoadedKind, id: string): boolean | undefined => {
+    const v = k.records!.views.find((x) => x.id === id);
+    return v ? idList(v.data, k.records!.loaded.kind.work!.implements).includes(view.id!) : undefined;
+  };
   for (const sha of shas) {
     const c = details.get(sha);
     if (!c) continue;
     let unit: string | null = null;
     let isOwn = false;
+    const joins = trailerJoins.get(sha)!.joins;
+    for (const r of joins.records) {
+      const k = recordKinds.get(r.kind);
+      if (!k || !k.records!.views.some((v) => v.id === r.id)) continue;
+      r.node = `record:${r.kind}/${r.id}`;
+      if (k.records!.loaded.kind.work ? workImplements(k, r.id) : r.kind === kind.name && r.id === view.id) isOwn = true;
+    }
+    const item = joins.lease?.item;
+    if (item) {
+      const holding = workKinds.filter((k) => k.records!.views.some((v) => v.id === item));
+      if (holding.length === 1 && workImplements(holding[0], item)) isOwn = true;
+    }
     for (const k of kinds) {
       if (!k.joins) continue;
       let result;
@@ -334,6 +366,8 @@ async function walk(query: IntentRecordQuery, head: Head): Promise<IntentRecordR
       trailers: c.trailers,
       pullRequest: pr ? Number(pr[1]) : null,
       unit,
+      joins,
+      runs: runJoins.refs.get(sha) ?? [],
       entries: listed.get(sha)!,
       files: files.get(sha) ?? [],
       bucket: isOwn ? "own" : workedBy.length > 0 ? "worked" : alsoWithin.length > 0 ? "within-other" : "unexplained",