@intentius/chant 0.124.45 → 0.124.48

package/src/workspace/work-evidence-ops.test.ts

@@ -0,0 +1,176 @@
+/**
+ * Work evidence that cites an ops result (#3171), on a workspace built from
+ * the reference workspace's work kind in a throwaway git repository.
+ *
+ * W-010 is in progress with a runtime criterion, "the web component runs
+ * green in staging". The staging run ledger of `deploy-web` holds an `ok`
+ * run, a `fail` run and a gated one. The run holding W-010's lease cites the
+ * ok run, the citation verifies against the ledger, and the criterion is met.
+ * The others, and citations the ledger does not hold, are refused and
+ * nothing is written.
+ */
+
+import { join } from "node:path";
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { readFileSync } from "node:fs";
+import { cleanScratch, contract, git, REPO, repo } from "./__fixtures__/contract-repo";
+import { queryRecords } from "./records-cli";
+import recordsSchema from "./records.schema.json";
+import { attachWorkEvidence } from "./work-evidence";
+import workEvidenceSchema from "./work-evidence.schema.json";
+import { appendRunRecord } from "../lifecycle/run-ledger";
+import { appendGateResolution } from "../lifecycle/gate-ledger";
+import { persistReleasePlan } from "../lifecycle/plan-ledger";
+import { claimWorkLease, releaseWorkLease } from "../lifecycle/work-lease";
+import type { OpRunRecordInput } from "../op/runtime";
+
+const REF = join(REPO, "reference-workspace");
+const KIND = "work/work.kind.mjs";
+
+function work(id: string, fields: Record<string, unknown>): string {
+  const data = {
+    schema: 1,
+    id,
+    title: `Work ${id}`,
+    state: "in-progress",
+    implements: [],
+    needs: [],
+    constrains: ["member:app"],
+    evidence: [],
+    owner: "alice",
+    opened_on: "2026-10-23",
+    closed_on: null,
+    source: { kind: "workspace", member: "app" },
+    supersedes: [],
+    ...fields,
+  };
+  return `---\n${JSON.stringify(data, null, 2)}\n---\n\n# ${id}\n`;
+}
+
+const run = (id: string, status: OpRunRecordInput["status"]): OpRunRecordInput => ({
+  id,
+  op: "deploy-web",
+  env: "staging",
+  started: "2026-10-23T10:00:00.000Z",
+  ended: "2026-10-23T10:05:00.000Z",
+  status,
+  labels: { Env: "staging" },
+  outcomes: {},
+  phases: [{ name: "Apply", status: status === "fail" ? "fail" : "ok", steps: [] }],
+});
+
+let root: string;
+let token: string;
+const evidenceDoc = contract(workEvidenceSchema);
+const records = contract(recordsSchema);
+
+beforeAll(async () => {
+  root = repo({
+    "chant.workspace.json": JSON.stringify({
+      name: "studio",
+      schema: 1,
+      members: [{ name: "app", dir: "app", kind: "other", because: "a plain Node server" }],
+      records: [{ kind: "decisions/decision.kind.mjs" }, { kind: KIND }],
+    }),
+    "app/server.mjs": "export const port = 8080;\n",
+    "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"),
+    [KIND]: readFileSync(join(REF, KIND), "utf-8"),
+    "work/work.schema.json": readFileSync(join(REF, "work/work.schema.json"), "utf-8"),
+    "work/W-010-staging.md": work("W-010", {
+      acceptance: [
+        { id: "AC-1", text: "The web component runs green in staging", verification: "runtime" },
+        { id: "AC-2", text: "The release plan for staging has no deletes", verification: "runtime" },
+      ],
+    }),
+  });
+  git(root, "config", "user.name", "t");
+  git(root, "config", "user.email", "t@example.com");
+  git(root, "config", "commit.gpgsign", "false");
+  git(root, "add", "-A");
+  git(root, "commit", "-q", "-m", "the work");
+  for (const [id, status] of [["r-ok", "ok"], ["r-fail", "fail"], ["r-gated", "gated"]] as const) await appendRunRecord(run(id, status), { cwd: root });
+  await appendGateResolution({ op: "deploy-web", gate: "promote", resolvedBy: "bob", timestamp: "2026-10-23T09:00:00.000Z" }, { cwd: root });
+  await persistReleasePlan({ digest: "sha256:abc", deletes: [] }, { cwd: root });
+  const claimed = await claimWorkLease("W-010", "box/verify@h1", { cwd: join(root, "work") });
+  if (!claimed.ok) throw new Error(claimed.message);
+  token = claimed.lease.token;
+});
+
+afterAll(async () => {
+  await releaseWorkLease("W-010", "box/verify@h1", { cwd: join(root, "work"), token });
+  cleanScratch();
+});
+
+const cite = (over: Partial<Parameters<typeof attachWorkEvidence>[0]>) =>
+  attachWorkEvidence({ cwd: root, item: "W-010", holder: "box/verify@h1", token, criterion: "AC-1", result: "pass", title: "staging run", ...over });
+
+async function w10() {
+  const doc = await queryRecords({ kind: join(root, KIND), cwd: root, workGaps: false });
+  records.expectValid(doc);
+  if ("error" in doc || !("records" in doc)) throw new Error(JSON.stringify(doc));
+  return doc.records.find((r) => r.id === "W-010")!;
+}
+
+describe("work evidence cites an ops result (#3171)", () => {
+  test("refusals write nothing: a run the ledger lacks, a failed run as a pass, a gated run, a wrong hash, two kinds of evidence", async () => {
+    const refused = async (over: Partial<Parameters<typeof attachWorkEvidence>[0]>, code: string) => {
+      const doc = await cite(over);
+      evidenceDoc.expectValid(doc);
+      expect(doc).toMatchObject({ error: { code } });
+    };
+    await refused({ ops: { ledger: "run", env: "staging", op: "deploy-web", id: "r-nope" } }, "work-evidence-ops-missing");
+    await refused({ ops: { ledger: "run", env: "prod", op: "deploy-web", id: "r-ok" } }, "work-evidence-ops-missing");
+    await refused({ ops: { ledger: "run", env: "staging", op: "deploy-web", id: "r-fail" } }, "work-evidence-ops-mismatch");
+    await refused({ ops: { ledger: "run", env: "staging", op: "deploy-web", id: "r-gated" } }, "work-evidence-ops-unfinished");
+    await refused({ ops: { ledger: "run", env: "staging", op: "deploy-web", id: "r-ok", sha256: "0".repeat(64) } }, "work-evidence-ops-mismatch");
+    await refused({ ops: { ledger: "run", env: "../x", op: "deploy-web", id: "r-ok" } as never }, "write-input-invalid");
+    await refused({ ops: { ledger: "run", env: "staging", op: "deploy-web", id: "r-ok" }, url: "https://example.com/x" }, "write-usage-invalid");
+    expect((await w10()).acceptance).toMatchObject({ met: 0, total: 2 });
+  });
+
+  test("a failed run cited as failing evidence is written, and does not meet the criterion", async () => {
+    const doc = await cite({ result: "fail", ops: { ledger: "run", env: "staging", op: "deploy-web", id: "r-fail" } });
+    evidenceDoc.expectValid(doc);
+    expect(doc).toMatchObject({ evidence: { ops: { ledger: "run", outcome: "fail" }, result: "fail" }, acceptance: { met: 0 } });
+  });
+
+  test("an ok run in staging ticks the runtime criterion, and the entry names the ledger line by its hash", async () => {
+    const doc = await cite({ ops: { ledger: "run", env: "staging", op: "deploy-web", id: "r-ok" } });
+    evidenceDoc.expectValid(doc);
+    if ("error" in doc) throw new Error(doc.error.message);
+    const line = git(root, "show", "chant/lifecycle:staging/runs__deploy-web.jsonl")
+      .split("\n")
+      .find((l) => l.includes('"r-ok"'))!
+      .trim();
+    const { createHash } = await import("node:crypto");
+    expect(doc.evidence).toMatchObject({
+      criterion: "AC-1",
+      verification: "runtime",
+      result: "pass",
+      by: "box/verify@h1",
+      ops: { ledger: "run", ref: "chant/lifecycle:staging/runs__deploy-web.jsonl", field: "id", value: "r-ok", env: "staging", outcome: "ok", sha256: createHash("sha256").update(line).digest("hex") },
+    });
+    expect(doc.acceptance).toMatchObject({ met: 1, total: 2 });
+    // The record still validates against the reference work schema with the ops entry in it.
+    const rec = await w10();
+    expect(rec.valid).toBe(true);
+    expect(rec.acceptance).toMatchObject({ met: 1, total: 2 });
+
+    // Citing it again with the hash it was given verifies too.
+    const again = await cite({ ops: { ledger: "run", env: "staging", op: "deploy-web", id: "r-ok", sha256: (doc.evidence.ops as { sha256: string }).sha256 } });
+    expect("error" in again).toBe(false);
+  });
+
+  test("a release plan and a gate answer can be cited, and a plan or gate the branch lacks is refused", async () => {
+    const plan = await cite({ criterion: "AC-2", title: "the staging plan", ops: { ledger: "plan", digest: "sha256:abc" } });
+    evidenceDoc.expectValid(plan);
+    expect(plan).toMatchObject({ evidence: { ops: { ledger: "plan", ref: "chant/lifecycle:_plans/sha256_abc.json", field: "digest", value: "sha256:abc" } }, acceptance: { met: 2, total: 2 } });
+    const gate = await cite({ criterion: "AC-2", title: "promote approved", ops: { ledger: "gate", op: "deploy-web", gate: "promote", at: "2026-10-23T09:00:00.000Z" } });
+    expect(gate).toMatchObject({ evidence: { ops: { ledger: "gate", ref: "chant/lifecycle:_gates/deploy-web.jsonl", field: "timestamp" } } });
+    expect(await cite({ ops: { ledger: "plan", digest: "sha256:nope" } })).toMatchObject({ error: { code: "work-evidence-ops-missing" } });
+    expect(await cite({ ops: { ledger: "gate", op: "deploy-web", gate: "promote", at: "2026-01-01T00:00:00.000Z" } })).toMatchObject({ error: { code: "work-evidence-ops-missing" } });
+    expect(await cite({ ops: { ledger: "deploy", env: "staging", runId: "r-ok" } })).toMatchObject({ error: { code: "work-evidence-ops-missing" } });
+    expect((await w10()).valid).toBe(true);
+  });
+});

package/src/workspace/work-evidence-ops.ts

@@ -0,0 +1,189 @@
+/**
+ * Evidence that cites an ops result (#3171): a run on the Op run ledger, a
+ * deploy on an environment's release ledger, a gate answer on a gate ledger,
+ * or a release plan in `_plans/`. `attachWorkEvidence` resolves the citation
+ * here before it writes anything, so a criterion is only ticked by a record
+ * the `chant/lifecycle` branch really holds.
+ *
+ * The citation names the record the way `chant workspace graph --intent`'s
+ * `trace` names its links (#4023): `ref` is the ledger file on the branch,
+ * `field` and `value` are what picks the record out of it, and `sha256` is
+ * the hash of the record as stored, a ledger line or a plan file. A citation
+ * that comes with a `sha256` is refused when the record no longer hashes to
+ * it.
+ *
+ * A run says what it showed: an `ok` run is passing evidence and a `fail`
+ * run failing evidence, and the result given must agree. A run that is
+ * still gated or waiting has no outcome yet and is refused. A deploy, a gate
+ * answer and a plan show what they record; whether that meets the criterion
+ * is the citer's `result`.
+ *
+ * Everything is read from the local `chant/lifecycle` branch. Nothing is
+ * fetched, the stance `graph --intent` takes.
+ */
+
+import { createHash } from "node:crypto";
+import { ledgerDir, readBlobFromPath } from "../lifecycle/git";
+import type { EvidenceResult } from "./work";
+
+/** The ledgers evidence can cite. */
+export const OPS_EVIDENCE_LEDGERS = ["run", "deploy", "gate", "plan"] as const;
+export type OpsEvidenceLedger = (typeof OPS_EVIDENCE_LEDGERS)[number];
+
+/** What a caller cites: which record, in which ledger, and optionally the hash it expects. */
+export type OpsCitation = {
+  /** The workspace member whose ledger holds the record, when it is not the flat layout. */
+  member?: string;
+  /** The hash of the record as stored, when the caller already has it. */
+  sha256?: string;
+} & (
+  | { ledger: "run"; env: string; op: string; id: string }
+  | { ledger: "deploy"; env: string; runId: string; component?: string }
+  | { ledger: "gate"; op: string; gate: string; at: string }
+  | { ledger: "plan"; digest: string }
+);
+
+/** The citation as the evidence entry stores it, once it resolved. */
+export interface OpsEvidence {
+  ledger: OpsEvidenceLedger;
+  /** The ledger file, as `chant/lifecycle:<path>`. */
+  ref: string;
+  /** The field of the record that picked it out, and its value. */
+  field: string;
+  value: string;
+  /** Hex SHA-256 of the record as stored. */
+  sha256: string;
+  /** The environment, for a run or a deploy. */
+  env?: string;
+  /** The run's status, for a run. */
+  outcome?: string;
+}
+
+export type OpsCitationError = { code: "write-input-invalid" | "work-evidence-ops-missing" | "work-evidence-ops-mismatch" | "work-evidence-ops-unfinished"; message: string };
+
+const NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const HEX64 = /^[0-9a-f]{64}$/;
+
+const sha256 = (s: string): string => createHash("sha256").update(s).digest("hex");
+
+function lines(text: string): { line: string; rec: Record<string, unknown> }[] {
+  const out: { line: string; rec: Record<string, unknown> }[] = [];
+  for (const raw of text.split("\n")) {
+    const line = raw.trim();
+    if (line === "") continue;
+    try {
+      const rec: unknown = JSON.parse(line);
+      if (rec !== null && typeof rec === "object" && !Array.isArray(rec)) out.push({ line, rec: rec as Record<string, unknown> });
+    } catch {
+      // A malformed line is skipped, as every ledger reader skips it.
+    }
+  }
+  return out;
+}
+
+/** Check a citation's shape, before anything is read. Returns the message for a bad one. */
+export function opsCitationProblem(cite: unknown): string | null {
+  if (cite === null || typeof cite !== "object" || Array.isArray(cite)) return "ops is an object naming a ledger";
+  const c = cite as Record<string, unknown>;
+  const str = (k: string) => typeof c[k] === "string" && (c[k] as string) !== "";
+  const name = (k: string) => typeof c[k] === "string" && NAME.test(c[k] as string);
+  if (!(OPS_EVIDENCE_LEDGERS as readonly string[]).includes(c.ledger as string)) return `ops.ledger is one of ${OPS_EVIDENCE_LEDGERS.join(", ")}, not ${JSON.stringify(c.ledger)}`;
+  if (c.member !== undefined && !name("member")) return "ops.member is a member name";
+  if (c.sha256 !== undefined && !(typeof c.sha256 === "string" && HEX64.test(c.sha256))) return "ops.sha256 is a hex SHA-256";
+  const allowed: Record<OpsEvidenceLedger, { names: string[]; strings: string[]; optional: string[] }> = {
+    run: { names: ["env", "op"], strings: ["id"], optional: [] },
+    deploy: { names: ["env"], strings: ["runId"], optional: ["component"] },
+    gate: { names: ["op"], strings: ["gate", "at"], optional: [] },
+    plan: { names: [], strings: ["digest"], optional: [] },
+  };
+  const spec = allowed[c.ledger as OpsEvidenceLedger];
+  for (const k of spec.names) if (!name(k)) return `a ${c.ledger} citation names ops.${k}`;
+  for (const k of spec.strings) if (!str(k)) return `a ${c.ledger} citation names ops.${k}`;
+  for (const k of spec.optional) if (c[k] !== undefined && !str(k)) return `ops.${k} is a string`;
+  const known = new Set(["ledger", "member", "sha256", ...spec.names, ...spec.strings, ...spec.optional]);
+  const extra = Object.keys(c).filter((k) => !known.has(k));
+  if (extra.length > 0) return `a ${c.ledger} citation takes ${[...known].join(", ")}, not ${extra.join(", ")}`;
+  if (c.ledger === "plan" && /[/\\]/.test(c.digest as string)) return "ops.digest is a plan digest, not a path";
+  return null;
+}
+
+/**
+ * Find the cited record on the local `chant/lifecycle` branch and check it
+ * against the citation and the result given. Never throws for a refusal.
+ */
+export async function resolveOpsCitation(cite: OpsCitation, result: EvidenceResult, cwd: string): Promise<{ ops: OpsEvidence } | { error: OpsCitationError }> {
+  const problem = opsCitationProblem(cite);
+  if (problem) return { error: { code: "write-input-invalid", message: problem } };
+  const loc = { cwd, ...(cite.member !== undefined ? { member: cite.member } : {}) };
+  const missing = (what: string): { error: OpsCitationError } => ({ error: { code: "work-evidence-ops-missing", message: `the local chant/lifecycle branch has no ${what}` } });
+
+  let found: { dir: string; file: string; text: string; field: string; value: string; env?: string; outcome?: string };
+  switch (cite.ledger) {
+    case "run": {
+      const file = `runs__${cite.op}.jsonl`;
+      const content = await readBlobFromPath(cite.env, file, loc);
+      const hit = content === null ? undefined : lines(content).find((l) => l.rec.id === cite.id);
+      if (!hit) return missing(`run ${cite.id} of ${cite.op} in ${cite.env}`);
+      const status = String(hit.rec.status);
+      if (status !== "ok" && status !== "fail") {
+        return { error: { code: "work-evidence-ops-unfinished", message: `run ${cite.id} of ${cite.op} is ${status}: it has no outcome yet to cite` } };
+      }
+      const shows: EvidenceResult = status === "ok" ? "pass" : "fail";
+      if (shows !== result) {
+        return { error: { code: "work-evidence-ops-mismatch", message: `run ${cite.id} of ${cite.op} in ${cite.env} ended ${status}, so it is ${shows} evidence, not ${result}` } };
+      }
+      found = { dir: cite.env, file, text: hit.line, field: "id", value: cite.id, env: cite.env, outcome: status };
+      break;
+    }
+    case "deploy": {
+      const file = "releases.jsonl";
+      const content = await readBlobFromPath(cite.env, file, loc);
+      const hits = content === null ? [] : lines(content).filter((l) => l.rec.runId === cite.runId && (cite.component === undefined || l.rec.component === cite.component));
+      if (hits.length === 0) return missing(`deploy by run ${cite.runId}${cite.component ? ` of ${cite.component}` : ""} in ${cite.env}`);
+      if (hits.length > 1) {
+        return { error: { code: "write-input-invalid", message: `run ${cite.runId} deployed ${hits.length} components in ${cite.env}: name the one cited in ops.component` } };
+      }
+      found = { dir: cite.env, file, text: hits[0].line, field: "runId", value: cite.runId, env: cite.env };
+      break;
+    }
+    case "gate": {
+      const file = `${cite.op}.jsonl`;
+      const content = await readBlobFromPath("_gates", file, loc);
+      const hit = content === null ? undefined : lines(content).find((l) => (l.rec.kind ?? "resolution") === "resolution" && l.rec.gate === cite.gate && l.rec.timestamp === cite.at);
+      if (!hit) return missing(`answer to gate ${cite.gate} of ${cite.op} at ${cite.at}`);
+      found = { dir: "_gates", file, text: hit.line, field: "timestamp", value: cite.at };
+      break;
+    }
+    case "plan": {
+      const file = `${cite.digest.replace(/:/g, "_")}.json`;
+      const content = await readBlobFromPath("_plans", file, loc);
+      if (content === null) return missing(`release plan ${cite.digest}`);
+      let digest: unknown;
+      try {
+        digest = (JSON.parse(content) as { digest?: unknown }).digest;
+      } catch {
+        digest = undefined;
+      }
+      if (digest !== cite.digest) return { error: { code: "work-evidence-ops-mismatch", message: `the plan stored for ${cite.digest} names another digest` } };
+      found = { dir: "_plans", file, text: content, field: "digest", value: cite.digest };
+      break;
+    }
+  }
+
+  const hash = sha256(found.text);
+  if (cite.sha256 !== undefined && cite.sha256 !== hash) {
+    return { error: { code: "work-evidence-ops-mismatch", message: `the ${cite.ledger} record cited hashes to ${hash}, not the ${cite.sha256} given: it is another record` } };
+  }
+  const ref = `chant/lifecycle:${await ledgerDir(found.dir, loc)}/${found.file}`;
+  return {
+    ops: {
+      ledger: cite.ledger,
+      ref,
+      field: found.field,
+      value: found.value,
+      sha256: hash,
+      ...(found.env !== undefined ? { env: found.env } : {}),
+      ...(found.outcome !== undefined ? { outcome: found.outcome } : {}),
+    },
+  };
+}

package/src/workspace/work-evidence.schema.json

@@ -45,7 +45,7 @@
         },
         "evidence": {
           "type": "object",
-          "description": "The entry appended: a title, a url or a path pinned by sha256, as_of, and the criterion, its verification, the result and by, the lease holder.",
+          "description": "The entry appended: a title, a url, a path pinned by sha256 or an ops result verified against its ledger (#3171), as_of, and the criterion, its verification, the result and by, the lease holder.",
           "required": [
             "title",
             "criterion",
@@ -91,6 +91,50 @@
             "by": {
               "type": "string",
               "description": "The lease holder that attached it."
+            },
+            "ops": {
+              "type": "object",
+              "description": "An ops result on the chant/lifecycle branch (#3171), named the way graph --intent's trace names a link: the ledger file in ref, the field and value that pick the record out of it, and the record's sha256 as stored. A run carries its env and outcome, a deploy its env.",
+              "required": [
+                "ledger",
+                "ref",
+                "field",
+                "value",
+                "sha256"
+              ],
+              "properties": {
+                "ledger": {
+                  "enum": [
+                    "run",
+                    "deploy",
+                    "gate",
+                    "plan"
+                  ]
+                },
+                "ref": {
+                  "type": "string",
+                  "pattern": "^chant/lifecycle:"
+                },
+                "field": {
+                  "type": "string"
+                },
+                "value": {
+                  "type": "string"
+                },
+                "sha256": {
+                  "type": "string",
+                  "pattern": "^[0-9a-f]{64}$"
+                },
+                "env": {
+                  "type": "string"
+                },
+                "outcome": {
+                  "enum": [
+                    "ok",
+                    "fail"
+                  ]
+                }
+              }
             }
           }
         },
@@ -207,7 +251,10 @@
                 "lease-held",
                 "lease-not-held",
                 "lease-token-mismatch",
-                "not-a-git-repository"
+                "not-a-git-repository",
+                "work-evidence-ops-missing",
+                "work-evidence-ops-mismatch",
+                "work-evidence-ops-unfinished"
               ]
             },
             "message": {

package/src/workspace/work-evidence.ts

@@ -17,6 +17,13 @@
  * one: the run holding the lease is the item's implementer, and a manual
  * verdict comes from someone else. A person records that verdict with
  * `records amend`, naming themselves in `by`.
+ *
+ * Evidence is a public link, a workspace file pinned by hash, or an ops
+ * result (#3171): a run, a deploy, a gate answer or a release plan on the
+ * `chant/lifecycle` branch, cited the way `graph --intent`'s trace cites it.
+ * The citation is resolved against the ledger it names before anything is
+ * written, and a run's outcome must agree with the result
+ * (`./work-evidence-ops.ts`).
  */
 
 import { relative, sep } from "node:path";
@@ -26,6 +33,7 @@ import { pinFile } from "./records-cli";
 import { AMEND_ERROR_CODES, amendRecord } from "./records-write";
 import { acceptanceCriteria, EVIDENCE_RESULTS, workAcceptance, type EvidenceResult, type VerificationType, type WorkAcceptance } from "./work";
 import { findWorkItem, WorkError } from "./work-cli";
+import { resolveOpsCitation, type OpsCitation } from "./work-evidence-ops";
 
 /** Why evidence was not attached. Closed. Nothing is written with any of them. */
 export const WORK_EVIDENCE_ERROR_CODES = [
@@ -40,6 +48,9 @@ export const WORK_EVIDENCE_ERROR_CODES = [
   "lease-not-held",
   "lease-token-mismatch",
   "not-a-git-repository",
+  "work-evidence-ops-missing",
+  "work-evidence-ops-mismatch",
+  "work-evidence-ops-unfinished",
 ] as const satisfies readonly ReasonCode[];
 export type WorkEvidenceErrorCode = (typeof WORK_EVIDENCE_ERROR_CODES)[number];
 
@@ -59,8 +70,10 @@ export interface AttachWorkEvidenceRequest {
   title: string;
   /** A public link, or */
   url?: string;
-  /** a workspace file, pinned by the hash of its bytes now. */
+  /** a workspace file, pinned by the hash of its bytes now, or */
   path?: string;
+  /** an ops result on the `chant/lifecycle` branch (#3171), verified against its ledger. */
+  ops?: OpsCitation;
   /** When the evidence was taken, as an ISO 8601 timestamp. Now by default. */
   asOf?: string;
 }
@@ -111,7 +124,9 @@ export async function attachWorkEvidence(req: AttachWorkEvidenceRequest): Promis
       throw new EvidenceError("write-usage-invalid", `result is pass or fail, not ${JSON.stringify(req.result)}`);
     }
     if (typeof req.title !== "string" || req.title.trim() === "") throw new EvidenceError("write-usage-invalid", "the evidence has no title");
-    if ((req.url === undefined) === (req.path === undefined)) throw new EvidenceError("write-usage-invalid", "the evidence is a url or a path, exactly one of them");
+    if ([req.url, req.path, req.ops].filter((v) => v !== undefined).length !== 1) {
+      throw new EvidenceError("write-usage-invalid", "the evidence is a url, a path or an ops result, exactly one of them");
+    }
     if (req.url !== undefined && !req.url.startsWith("https://")) throw new EvidenceError("write-input-invalid", `evidence links are https://, not ${JSON.stringify(req.url)}`);
 
     const found = await findWorkItem(req.item, req.cwd, req.kind);
@@ -139,7 +154,11 @@ export async function attachWorkEvidence(req: AttachWorkEvidenceRequest): Promis
     }
 
     let pin: Record<string, unknown>;
-    if (req.path !== undefined) {
+    if (req.ops !== undefined) {
+      const resolved = await resolveOpsCitation(req.ops, req.result, req.cwd);
+      if ("error" in resolved) throw new EvidenceError(resolved.error.code, resolved.error.message);
+      pin = { ops: resolved.ops };
+    } else if (req.path !== undefined) {
       const pinned = pinFile(req.path, req.cwd);
       if ("error" in pinned) throw new EvidenceError("write-input-invalid", pinned.error);
       pin = { path: pinned.path, sha256: pinned.sha256 };