@intentius/chant 0.124.46 → 0.124.48

package/dist/workspace/work-cli.js

@@ -307,7 +307,8 @@ export function formatWorkHistory(doc) {
  * <file|->` (#3159): the `workEvidence` activity (#2772) as a command, so a
  * writer that is not an Op, such as hud, attaches evidence through chant under
  * the lease it holds. `--from` gives the entry as JSON: criterion, result,
- * title, a url or a path, and optionally as_of. It always prints the
+ * title, a url, a path or an ops result to cite (#3171), and optionally
+ * as_of. It always prints the
  * work-evidence document; exit 0 when the entry was appended, 1 otherwise.
  */
 async function runWorkEvidence(ctx) {
@@ -326,7 +327,7 @@ async function runWorkEvidence(ctx) {
     if (!args.token)
         return fail("evidence needs --token <token>: the lease's fencing token, as its claim printed it");
     if (args.migrateFrom === undefined)
-        return fail("evidence needs --from <file|->: the entry as JSON, with criterion, result, title and a url or a path");
+        return fail("evidence needs --from <file|->: the entry as JSON, with criterion, result, title and a url, a path or an ops result");
     for (const [flag, v] of [["--ttl", args.ttl], ["--outcome", args.outcome], ["--note", args.note]]) {
         if (v !== undefined)
             return fail(`evidence takes no ${flag}`);
@@ -344,7 +345,7 @@ async function runWorkEvidence(ctx) {
     catch (err) {
         return print({ $schema: WORK_EVIDENCE_OUTPUT_SCHEMA_ID, contract: WORK_EVIDENCE_CONTRACT_VERSION, error: { code: "write-input-invalid", message: `--from ${args.migrateFrom} could not be read: ${err instanceof Error ? err.message : String(err)}` } }, 1);
     }
-    const known = ["criterion", "result", "title", "url", "path", "as_of"];
+    const known = ["criterion", "result", "title", "url", "path", "ops", "as_of"];
     const unknown = Object.keys(fields).filter((k) => !known.includes(k));
     if (unknown.length > 0)
         return fail(`the entry takes ${known.join(", ")}, not ${unknown.join(", ")}`);
@@ -360,6 +361,7 @@ async function runWorkEvidence(ctx) {
         title: str("title") ?? "",
         url: str("url"),
         path: str("path"),
+        ops: fields.ops,
         asOf: str("as_of"),
     });
     return print(doc, "error" in doc ? 1 : 0);

package/dist/workspace/work-evidence-ops.d.ts

@@ -0,0 +1,83 @@
+/**
+ * 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 type { EvidenceResult } from "./work.js";
+/** The ledgers evidence can cite. */
+export declare const OPS_EVIDENCE_LEDGERS: readonly ["run", "deploy", "gate", "plan"];
+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;
+};
+/** Check a citation's shape, before anything is read. Returns the message for a bad one. */
+export declare function opsCitationProblem(cite: unknown): string | 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 declare function resolveOpsCitation(cite: OpsCitation, result: EvidenceResult, cwd: string): Promise<{
+    ops: OpsEvidence;
+} | {
+    error: OpsCitationError;
+}>;
+//# sourceMappingURL=work-evidence-ops.d.ts.map

package/dist/workspace/work-evidence-ops.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"work-evidence-ops.d.ts","sourceRoot":"","sources":["../../src/workspace/work-evidence-ops.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,QAAQ,CAAC;AAE7C,qCAAqC;AACrC,eAAO,MAAM,oBAAoB,YAAI,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAU,CAAC;AAC/E,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEtE,8FAA8F;AAC9F,MAAM,MAAM,WAAW,GAAG;IACxB,0FAA0F;IAC1F,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wEAAwE;IACxE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,CACA;IAAE,MAAM,EAAE,KAAK,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GACtD;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GACpE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GACxD;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CACrC,CAAC;AAEF,sEAAsE;AACtE,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,iBAAiB,CAAC;IAC1B,oDAAoD;IACpD,GAAG,EAAE,MAAM,CAAC;IACZ,iEAAiE;IACjE,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,2CAA2C;IAC3C,MAAM,EAAE,MAAM,CAAC;IACf,8CAA8C;IAC9C,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,mCAAmC;IACnC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,MAAM,gBAAgB,GAAG;IAAE,IAAI,EAAE,qBAAqB,GAAG,2BAA2B,GAAG,4BAA4B,GAAG,8BAA8B,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAsB9K,4FAA4F;AAC5F,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAuB/D;AAED;;;GAGG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,cAAc,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAAE,GAAG,EAAE,WAAW,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,gBAAgB,CAAA;CAAE,CAAC,CA2E5J"}

package/dist/workspace/work-evidence-ops.js

@@ -0,0 +1,169 @@
+/**
+ * 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.js";
+/** The ledgers evidence can cite. */
+export const OPS_EVIDENCE_LEDGERS = ["run", "deploy", "gate", "plan"];
+const NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const HEX64 = /^[0-9a-f]{64}$/;
+const sha256 = (s) => createHash("sha256").update(s).digest("hex");
+function lines(text) {
+    const out = [];
+    for (const raw of text.split("\n")) {
+        const line = raw.trim();
+        if (line === "")
+            continue;
+        try {
+            const rec = JSON.parse(line);
+            if (rec !== null && typeof rec === "object" && !Array.isArray(rec))
+                out.push({ line, rec: rec });
+        }
+        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) {
+    if (cite === null || typeof cite !== "object" || Array.isArray(cite))
+        return "ops is an object naming a ledger";
+    const c = cite;
+    const str = (k) => typeof c[k] === "string" && c[k] !== "";
+    const name = (k) => typeof c[k] === "string" && NAME.test(c[k]);
+    if (!OPS_EVIDENCE_LEDGERS.includes(c.ledger))
+        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 = {
+        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];
+    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))
+        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, result, cwd) {
+    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) => ({ error: { code: "work-evidence-ops-missing", message: `the local chant/lifecycle branch has no ${what}` } });
+    let found;
+    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 = 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;
+            try {
+                digest = JSON.parse(content).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/dist/workspace/work-evidence.d.ts

@@ -17,10 +17,18 @@
  * 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 { type EvidenceResult, type WorkAcceptance } from "./work.js";
+import { type OpsCitation } from "./work-evidence-ops.js";
 /** Why evidence was not attached. Closed. Nothing is written with any of them. */
-export declare const WORK_EVIDENCE_ERROR_CODES: readonly ["kind-unreadable", "kind-invalid", "schema-unreadable", "schema-id-mismatch", "schema-invalid", "location-missing", "write-usage-invalid", "write-input-invalid", "record-not-found", "amend-id-immutable", "record-closed", "amend-supersede-instead", "record-sign-failed", "ratify-quorum-not-met", "record-conflict", "write-lock-timeout", "write-lock-not-held", "write-scope-member", "write-scope-kind", "write-scope-class-unknown", "agent-unknown", "principal-unidentified", "record-unparseable", "record-schema-invalid", "record-id-duplicate", "record-supersedes-unknown", "record-supersedes-conflict", "record-remediates-unknown", "record-remediates-not-closed", "record-seal-mismatch", "session-seal-mismatch", "session-verdict-unknown-record", "work-kind-missing", "work-kind-ambiguous", "work-item-unknown", "work-item-closed", "work-criterion-unknown", "work-acceptance-self-verified", "lease-held", "lease-not-held", "lease-token-mismatch", "not-a-git-repository"];
+export declare const WORK_EVIDENCE_ERROR_CODES: readonly ["kind-unreadable", "kind-invalid", "schema-unreadable", "schema-id-mismatch", "schema-invalid", "location-missing", "write-usage-invalid", "write-input-invalid", "record-not-found", "amend-id-immutable", "record-closed", "amend-supersede-instead", "record-sign-failed", "ratify-quorum-not-met", "record-conflict", "write-lock-timeout", "write-lock-not-held", "write-scope-member", "write-scope-kind", "write-scope-class-unknown", "agent-unknown", "principal-unidentified", "record-unparseable", "record-schema-invalid", "record-id-duplicate", "record-supersedes-unknown", "record-supersedes-conflict", "record-remediates-unknown", "record-remediates-not-closed", "record-seal-mismatch", "session-seal-mismatch", "session-verdict-unknown-record", "work-kind-missing", "work-kind-ambiguous", "work-item-unknown", "work-item-closed", "work-criterion-unknown", "work-acceptance-self-verified", "lease-held", "lease-not-held", "lease-token-mismatch", "not-a-git-repository", "work-evidence-ops-missing", "work-evidence-ops-mismatch", "work-evidence-ops-unfinished"];
 export type WorkEvidenceErrorCode = (typeof WORK_EVIDENCE_ERROR_CODES)[number];
 export interface AttachWorkEvidenceRequest {
     /** Where the workspace is found, and what `path` and `kind` resolve against. */
@@ -38,8 +46,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;
 }

package/dist/workspace/work-evidence.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"work-evidence.d.ts","sourceRoot":"","sources":["../../src/workspace/work-evidence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAOH,OAAO,EAAwD,KAAK,cAAc,EAAyB,KAAK,cAAc,EAAE,MAAM,QAAQ,CAAC;AAG/I,kFAAkF;AAClF,eAAO,MAAM,yBAAyB,q9BAYI,CAAC;AAC3C,MAAM,MAAM,qBAAqB,GAAG,CAAC,OAAO,yBAAyB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE/E,MAAM,WAAW,yBAAyB;IACxC,gFAAgF;IAChF,GAAG,EAAE,MAAM,CAAC;IACZ,qBAAqB;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,kFAAkF;IAClF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,6DAA6D;IAC7D,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,gDAAgD;IAChD,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,cAAc,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,wBAAwB;IACxB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,6EAA6E;IAC7E,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,4DAA4D;AAC5D,eAAO,MAAM,8BAA8B,IAAI,CAAC;AAEhD,kFAAkF;AAClF,eAAO,MAAM,8BAA8B,4FAA4F,CAAC;AAExI,UAAU,OAAO;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,sFAAsF;AACtF,MAAM,MAAM,oBAAoB,GAAG,OAAO,GACxC,CACI;IACE,IAAI,EAAE,MAAM,CAAC;IACb,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAC;IACb,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,mDAAmD;IACnD,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,wDAAwD;IACxD,UAAU,EAAE,cAAc,CAAC;CAC5B,GACD;IAAE,KAAK,EAAE;QAAE,IAAI,EAAE,qBAAqB,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAC9D,CAAC;AAWJ,sGAAsG;AACtG,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,yBAAyB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CA+DtG"}
+{"version":3,"file":"work-evidence.d.ts","sourceRoot":"","sources":["../../src/workspace/work-evidence.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAOH,OAAO,EAAwD,KAAK,cAAc,EAAyB,KAAK,cAAc,EAAE,MAAM,QAAQ,CAAC;AAE/I,OAAO,EAAsB,KAAK,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAE3E,kFAAkF;AAClF,eAAO,MAAM,yBAAyB,gjCAeI,CAAC;AAC3C,MAAM,MAAM,qBAAqB,GAAG,CAAC,OAAO,yBAAyB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE/E,MAAM,WAAW,yBAAyB;IACxC,gFAAgF;IAChF,GAAG,EAAE,MAAM,CAAC;IACZ,qBAAqB;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,kFAAkF;IAClF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,6DAA6D;IAC7D,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,gDAAgD;IAChD,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,cAAc,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,wBAAwB;IACxB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,gEAAgE;IAChE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0FAA0F;IAC1F,GAAG,CAAC,EAAE,WAAW,CAAC;IAClB,6EAA6E;IAC7E,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,4DAA4D;AAC5D,eAAO,MAAM,8BAA8B,IAAI,CAAC;AAEhD,kFAAkF;AAClF,eAAO,MAAM,8BAA8B,4FAA4F,CAAC;AAExI,UAAU,OAAO;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,sFAAsF;AACtF,MAAM,MAAM,oBAAoB,GAAG,OAAO,GACxC,CACI;IACE,IAAI,EAAE,MAAM,CAAC;IACb,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAC;IACb,4CAA4C;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,mDAAmD;IACnD,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,wDAAwD;IACxD,UAAU,EAAE,cAAc,CAAC;CAC5B,GACD;IAAE,KAAK,EAAE;QAAE,IAAI,EAAE,qBAAqB,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,CAC9D,CAAC;AAWJ,sGAAsG;AACtG,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,yBAAyB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAqEtG"}

package/dist/workspace/work-evidence.js

@@ -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";
 import { activeWorkLeases } from "../lifecycle/work-lease.js";
@@ -24,6 +31,7 @@ import { pinFile } from "./records-cli.js";
 import { AMEND_ERROR_CODES, amendRecord } from "./records-write.js";
 import { acceptanceCriteria, EVIDENCE_RESULTS, workAcceptance } from "./work.js";
 import { findWorkItem, WorkError } from "./work-cli.js";
+import { resolveOpsCitation } from "./work-evidence-ops.js";
 /** Why evidence was not attached. Closed. Nothing is written with any of them. */
 export const WORK_EVIDENCE_ERROR_CODES = [
     ...AMEND_ERROR_CODES,
@@ -37,6 +45,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",
 ];
 /** The version of the attach document this chant writes. */
 export const WORK_EVIDENCE_CONTRACT_VERSION = 1;
@@ -59,8 +70,9 @@ export async function attachWorkEvidence(req) {
         }
         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);
@@ -87,7 +99,13 @@ export async function attachWorkEvidence(req) {
             throw new EvidenceError("work-acceptance-self-verified", `${req.criterion} is verified by a person, and ${req.holder} holds ${req.item}'s lease, so it is the implementer: a manual verdict comes from someone else, with records amend`);
         }
         let pin;
-        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);

package/dist/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/dist/workspace/workspace-gates.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Workspace gates (#2554, #2524 D17, ws-039).
+ *
+ * A workspace gate is one approval for a change across members. A run of
+ * `chant workspace run --gate <name>` whose member runs stop at their own
+ * gates records a pending fact under `_members/_workspace/_gates/<name>.jsonl`
+ * that lists each stopped member gate and the plan it waits on (a cover),
+ * with the digest of that list. `chant workspace run approve <name>` records
+ * an approval of one such digest.
+ *
+ * The rule (ws-039): a workspace gate never satisfies a member gate, unless
+ * both hold:
+ *
+ * 1. its approval's digest covers the member's plan: the approval lists the
+ *    member, the Op, the gate and the plan digest the member run reached it
+ *    with, and the list still hashes to the approval's digest;
+ * 2. the member opts in at base: its entry in `chant.workspace.json`, read
+ *    from the base revision as other policy is, sets
+ *    `acceptWorkspaceGates: true`. A declaration read only from the working
+ *    tree never opts a member in.
+ *
+ * A member run started under the gate (`CHANT_WORKSPACE_GATE`) asks this
+ * module through `GateCheckInput.workspace` after its own approvals have
+ * not passed the gate. Nothing is written to the member's gate ledger: the
+ * run's step record says `via: "workspace"` and names the workspace gate.
+ */
+import type { WorkspaceGateStood } from "../op/gate.js";
+/** One member gate a workspace gate covers. */
+export interface WorkspaceGateCover {
+    member: string;
+    op: string;
+    gate: string;
+    planDigest: string;
+    /** The member gate's environment, when it is bound to one. */
+    environment?: string;
+}
+export interface WorkspaceGatePending {
+    version: 1;
+    kind: "pending";
+    gate: string;
+    /** The workspace run that recorded it. */
+    run: string;
+    timestamp: string;
+    digest: string;
+    covers: WorkspaceGateCover[];
+}
+export interface WorkspaceGateApproval {
+    version: 1;
+    kind: "approval";
+    gate: string;
+    digest: string;
+    covers: WorkspaceGateCover[];
+    approvedBy: string;
+    timestamp: string;
+    note?: string;
+}
+export type WorkspaceGateLine = WorkspaceGatePending | WorkspaceGateApproval;
+/** Covers in one order, so the same set always has the same digest. */
+export declare function sortCovers(covers: readonly WorkspaceGateCover[]): WorkspaceGateCover[];
+/** The digest a workspace gate's pending fact and approval carry: the member plans it covers. */
+export declare function workspaceGateDigest(covers: readonly WorkspaceGateCover[]): string;
+/** What a member gate asks about. */
+export interface MemberGateQuery {
+    op: string;
+    gate: string;
+    planDigest: string;
+    environment?: string;
+}
+/**
+ * The rule of ws-039, pure: the newest approval that stands in for the
+ * member gate `q`, or null. Null whenever the member has not opted in.
+ */
+export declare function workspaceGateStandsIn(q: MemberGateQuery, ctx: {
+    member: string;
+    optedIn: boolean;
+    approvals: readonly WorkspaceGateApproval[];
+}): WorkspaceGateApproval | null;
+/** A workspace gate's ledger, oldest first. */
+export declare function readWorkspaceGate(cwd: string, gate: string): Promise<{
+    pending: WorkspaceGatePending[];
+    approvals: WorkspaceGateApproval[];
+    malformed: number;
+}>;
+export declare function appendWorkspaceGatePending(cwd: string, input: Omit<WorkspaceGatePending, "version" | "kind" | "digest" | "covers"> & {
+    covers: readonly WorkspaceGateCover[];
+}): Promise<WorkspaceGatePending>;
+/**
+ * Approve a workspace gate's pending fact: the newest one, or the one whose
+ * digest is `digest`. The approval copies its covers. Throws when there is no
+ * such fact.
+ */
+export declare function approveWorkspaceGate(cwd: string, input: {
+    gate: string;
+    digest?: string;
+    approvedBy: string;
+    timestamp: string;
+    note?: string;
+}): Promise<WorkspaceGateApproval>;
+/**
+ * Whether the member holding `cwd` opts in to workspace gates at base, and
+ * its name. A member of a nested workspace, the root member and a directory
+ * no member owns never opt in.
+ */
+export declare function memberAcceptsWorkspaceGates(cwd: string): Promise<{
+    member: string | null;
+    accepts: boolean;
+}>;
+/** The stand-in a member run started under workspace gate `gate` asks (`GateCheckInput.workspace`). */
+export declare function memberGateStandIn(cwd: string, gate: string, q: MemberGateQuery): Promise<WorkspaceGateStood | null>;
+//# sourceMappingURL=workspace-gates.d.ts.map

package/dist/workspace/workspace-gates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-gates.d.ts","sourceRoot":"","sources":["../../src/workspace/workspace-gates.ts"],"names":[],"mappings":"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"}