@intentius/chant 0.124.5 → 0.124.6

package/src/point-decision.ts

@@ -20,6 +20,11 @@
  * TypeScript, zod or git code, which `point-decision-bundle.test.ts` holds
  * it to. `./op/gate-point-run.ts` re-exports it, and chant's own runs decide
  * by it.
+ *
+ * A gate's resolution is written only when its run asks again, so a resume
+ * job asks {@link pointGateResumable} whether a waiting job's question now
+ * has an answer that passes the gate (#3835), with the questions
+ * {@link chantPointQuestions} reads. `chant run resume` makes the same check.
  */
 
 import { execFile } from "node:child_process";
@@ -31,6 +36,7 @@ import { parseDuration } from "./op/duration";
 import type { GateLedgerPort } from "./op/gate";
 import { DEFAULT_GATE_POINT_PASS, defaultGatePointStore, gatePointInputs, gateSubject, type GatePoint, type GatePointFacts, type GatePointStore } from "./op/gate-point";
 import type { WaitingPoint } from "./op/steward-points";
+import { resolveGateRunLocator, type GateRunLocator } from "./op/gate-run-locator";
 
 export {
   DEFAULT_GATE_POINT_PASS,
@@ -40,12 +46,14 @@ export {
   gatePointOf,
   gatePointProblems,
   gateSubject,
+  parseGateSubject,
   type GatePoint,
   type GatePointFacts,
   type GatePointStore,
 } from "./op/gate-point";
 export type { GateAnswerRef, GateResolutionRecord, GateResolutionInput, PendingGateInput, PendingGateRecord } from "./lifecycle/gate-ledger";
 export type { WaitingPoint } from "./op/steward-points";
+export { isGateRunLocator, resolveGateRunLocator, type GateRunLocator } from "./op/gate-run-locator";
 
 /**
  * The gate ledger as {@link evaluatePointGate} uses it: read an op's facts,
@@ -107,6 +115,12 @@ export interface PointGateInput {
   /** The environment the run was started for: the `gate.env` input. Op gate facts on the ledger record none. */
   env?: string;
   now?: string;
+  /**
+   * Where this job runs, for `chant run resume` to start it again once the
+   * question is answered (#3835). Default: read from the CI environment
+   * ({@link resolveGateRunLocator}); false records none.
+   */
+  resume?: GateRunLocator | false;
 }
 
 /** What reaching a gate that asks a point decided. */
@@ -188,6 +202,7 @@ export async function evaluatePointGate(port: PointGateLedgerPort, asker: GatePo
     return { satisfied: false, waiting, pending: standing, recorded: false };
   }
   const url = resolveApprovalUrl();
+  const resume = input.resume === false ? undefined : (input.resume ?? resolveGateRunLocator());
   const { record, pushed, pushWarning } = await port.appendPending({
     op: input.op,
     gate: input.gate,
@@ -197,11 +212,77 @@ export async function evaluatePointGate(port: PointGateLedgerPort, asker: GatePo
     ...(input.runId ? { runId: input.runId } : {}),
     ...(url ? { url } : {}),
     ...(input.planDigest !== undefined ? { planDigest: input.planDigest } : {}),
-    answer: ref,
+    ...(resume ? { resume } : {}),
+    answer: { ...ref, ...(input.point.pass ? { pass: input.point.pass } : {}) },
   });
   return { satisfied: false, waiting, pending: record, recorded: true, pushed, ...(pushWarning ? { pushWarning } : {}) };
 }
 
+/**
+ * A question's state as a resume reads it: what `chant workspace points
+ * --json` lists for it. {@link chantPointQuestions} reads them through the
+ * chant bin; chant's own resume reads the workspace.
+ */
+export interface PointQuestionState {
+  id: string;
+  state: "escalated" | "proposed" | "answered";
+  /** The answer, or null while the question is open. */
+  answer: string | boolean | null;
+  answeredBy: string[];
+  /** When it was answered, as the record says, or null. */
+  answeredOn: string | null;
+}
+
+/** Whether a waiting point-asking gate can be resumed, and why not. */
+export type PointResumeCheck =
+  | {
+      resumable: true;
+      /** The answer that passes the gate, as the resumed run will cite it. */
+      answer: GateAnswerRef;
+      /** Who answered: the people, joined, or `quorum` when the record names none. */
+      answeredBy: string;
+      /** When it was answered, or null. A resume reads a run started after it as already resumed. */
+      answeredOn: string | null;
+    }
+  | {
+      resumable: false;
+      /** `open`: nobody has answered; `refused`: the answer does not pass the gate; `unknown`: no question with the id was read; `not-a-point`: the pending fact cites no question. */
+      why: "open" | "refused" | "unknown" | "not-a-point";
+      message: string;
+    };
+
+/**
+ * Whether the job behind `standing`, a pending fact a gate that asks a
+ * decision point recorded, can be started again (#3835): its question is
+ * answered with an answer the gate passes on (the pending fact's
+ * `answer.pass`, default a noul point's yes). A gate only writes its
+ * resolution when its run asks the point again, so nothing on the gate
+ * ledger says an answered question passes; this is the check
+ * `chant run resume` makes, and a product's own resume job makes the same
+ * call with the questions it read (`chantPointQuestions`). It approves
+ * nothing: the resumed run asks again and decides.
+ */
+export function pointGateResumable(standing: Pick<PendingGateRecord, "answer">, question: PointQuestionState | undefined): PointResumeCheck {
+  const ref = standing.answer;
+  if (!ref) return { resumable: false, why: "not-a-point", message: "the pending fact cites no decision point's question" };
+  if (!question || question.id !== ref.id) return { resumable: false, why: "unknown", message: `question ${ref.id} (${ref.point}) can't be read here` };
+  if (question.state !== "answered" || question.answer === null) return { resumable: false, why: "open", message: `question ${ref.id} (${ref.point}) is ${question.state}, not answered yet` };
+  const pass = ref.pass ?? DEFAULT_GATE_POINT_PASS;
+  if (!pass.includes(question.answer)) {
+    return {
+      resumable: false,
+      why: "refused",
+      message: `question ${ref.id} (${ref.point}) was answered ${JSON.stringify(question.answer)}, and the gate passes only on ${pass.map((a) => JSON.stringify(a)).join(" or ")}`,
+    };
+  }
+  return {
+    resumable: true,
+    answer: { point: ref.point, id: ref.id, path: ref.path, answer: question.answer, ...(question.answeredBy.length > 0 ? { answeredBy: question.answeredBy } : {}) },
+    answeredBy: question.answeredBy.length > 0 ? question.answeredBy.join(", ") : "quorum",
+    answeredOn: question.answeredOn,
+  };
+}
+
 /** How {@link chantGatePointAsker} runs chant. */
 export interface ChantGatePointAskerOptions {
   /** The chant command and its leading arguments, such as `["npx", "chant"]` or `[process.execPath, "/path/to/chant"]`. */
@@ -278,3 +359,18 @@ export function chantGatePointAsker(opts: ChantGatePointAskerOptions): GatePoint
     },
   };
 }
+
+/**
+ * Every question the workspace lists, by id, read through the chant bin with
+ * `chant workspace points --json` (the questions held on `chant/lifecycle`
+ * included), for {@link pointGateResumable} in a tool that bundles this
+ * module (#3835). Fetch `chant/lifecycle` first, as reading the gate ledger
+ * does, so an answer given from another clone is seen.
+ */
+export async function chantPointQuestions(opts: ChantGatePointAskerOptions): Promise<Map<string, PointQuestionState>> {
+  const listed = await runChantJson(opts, ["workspace", "points", "--json"]);
+  const bad = refusal("chant workspace points", listed);
+  if (bad) throw bad;
+  const questions = (listed.questions as PointQuestionState[] | undefined) ?? [];
+  return new Map(questions.map((q) => [q.id, { id: q.id, state: q.state, answer: q.answer ?? null, answeredBy: q.answeredBy ?? [], answeredOn: q.answeredOn ?? null }]));
+}

package/src/workspace/points-cli.ts

@@ -250,7 +250,7 @@ export function responseAsk(response: unknown): ModelAsk {
 const USAGE = [
   "chant workspace points [--open] [--kind <kind file>] [--at <rev>] [--json]",
   "chant workspace points ask <point> --inputs <file|-|json> [--candidates <file|-|json>] [--response <file>] [--subject <id>] [--kind <kind file>] [--dry-run]",
-  "chant workspace points answer <id> --answer <value> --by <name> [--by <name>...] [--note <text>] [--relayed-by <principal>] [--kind <kind file>] [--dry-run]",
+  "chant workspace points answer <id> --answer <value> --by <name> [--by <name>...] [--note <text>] [--relayed-by <principal>] [--kind <kind file>] [--resume] [--dry-run]",
   "chant workspace points retract <id> --by <name> [--by <name>...] [--note <text>] [--kind <kind file>] [--dry-run]",
 ].join("\n");
 
@@ -311,7 +311,12 @@ export async function runWorkspacePoints(ctx: CommandContext): Promise<number> {
     if (!id) return print(usage("answer", "answer needs the question's id"));
     if (args.answer === undefined) return print(usage("answer", "--answer <value> is required"));
     if (!args.bys || args.bys.length === 0) return print(usage("answer", "--by <name> is required, once for each person who answered"));
-    return print(await answerPoint({ cwd, id, answer: args.answer, by: args.bys, note: args.note, relayedBy: args.relayedBy, kind: args.kind, dryRun: args.dryRun }));
+    const answered = await answerPoint({ cwd, id, answer: args.answer, by: args.bys, note: args.note, relayedBy: args.relayedBy, kind: args.kind, dryRun: args.dryRun });
+    const code = print(answered);
+    // --resume (#3835): start the job waiting at the gate the question names, as `chant approve --resume` does.
+    if (code !== 0 || args.dryRun || !(args.resumeRun || args.resume !== undefined) || !("question" in answered)) return code;
+    const { resumeAfterAnswer } = await import("../cli/handlers/gate-resume");
+    return resumeAfterAnswer(answered.question, cwd);
   }
   if (verb === "retract") {
     const id = args.extraPositional2;

package/src/workspace/records-cli.ts

@@ -99,6 +99,13 @@ export interface RecordsQuery {
   workGaps?: boolean;
   /** List only the records that are modified or new against `HEAD` (#3160). Needs git and a working-tree read. */
   uncommitted?: boolean;
+  /**
+   * For an answer kind read in the working tree (#3833): fetch `chant/lifecycle`
+   * first, best effort, as `points answer` does, so an answer held there by
+   * another clone or a CI job is listed. The command sets it; other readers
+   * read the local ledger as it is.
+   */
+  fetchLedger?: boolean;
 }
 
 /**
@@ -146,6 +153,14 @@ export type RecordView = RecordEntry & {
    * steward keeps on the lifecycle ledger (#2786) laid over it.
    */
   answers?: WorkAnswer[];
+  /**
+   * For a record of an answer kind (one with an `answers` block) read in the
+   * working tree (#3833): where the record is held on the lifecycle ledger,
+   * `chant/lifecycle:<path>`, as `points` names it for a question, or null
+   * when it is the working tree's file. A record held on the ledger has no
+   * `worktree` or `lastWrite`, since the checkout doesn't hold it.
+   */
+  ledger?: string | null;
 };
 
 /** The role in the trust policy whose holders' verdicts the quorum does not count (#2671). */
@@ -398,7 +413,19 @@ export async function queryRecords(query: RecordsQuery): Promise<RecordsDocument
   // A revision has no working tree to hold anything uncommitted; the CLI and the MCP tool refuse the pair first.
   if (query.uncommitted && query.at !== undefined) throw new Error("--uncommitted reads the working tree and takes no --at");
   try {
-    const { loaded, root, top, at, workspaceRoot, tree, result } = await readRecordsFor(query);
+    // An answer kind's records include the answers held on the lifecycle ledger (#2786, #3815), as `points` lists them (#3833).
+    let heldOnLedger: Map<string, string> | undefined;
+    const { loaded, root, top, at, workspaceRoot, tree, result } = await readRecordsFor({
+      ...query,
+      overlay: async (base, { loaded: l, root: r }) => {
+        if (!l.kind.answers) return base;
+        const { readLedgerAnswers, refreshLedger, withLedgerAnswers } = await import("./answers-ledger");
+        if (query.fetchLedger) await refreshLedger(l.file);
+        const ledger = await readLedgerAnswers({ file: l.file, name: l.kind.name, dirRel: relative(r, l.dir).split(sep).join("/") || "." });
+        heldOnLedger = new Map([...ledger.byPath.values()].map((a) => [a.path, a.ledger]));
+        return withLedgerAnswers(base, ledger);
+      },
+    });
     // Provenance, judged by the policy at base and never by the tree read (#2547).
     const base = top ? resolveBase(top, query.base) : { commit: null, from: null };
     const policy = top ? policyAtBase(top, base) : policyAtBase(root, base);
@@ -426,6 +453,7 @@ export async function queryRecords(query: RecordsQuery): Promise<RecordsDocument
         ...(seals ? authorSeal(loaded.kind, r, recordPolicy, seals.checkRecordSeal) : {}),
       });
     }
+    if (heldOnLedger) for (const r of records) r.ledger = heldOnLedger.get(r.path) ?? null;
     if (loaded.kind.approval && !loaded.kind.work && top) {
       const decided = decidedCommits(top, at ?? "HEAD", records.map((r) => r.path), loaded.kind);
       for (const r of records) r.decidedIn = decided.get(r.path) ?? null;
@@ -461,13 +489,15 @@ export async function queryRecords(query: RecordsQuery): Promise<RecordsDocument
     if (at === null && top) {
       const { head, ...rest } = readCheckoutHead(top, query.base);
       const dir = relative(root, loaded.dir).split(sep).join("/") || ".";
+      // A record held on the ledger is not the checkout's: it has no worktree state, and is never uncommitted (#3833).
+      const inTree = records.filter((r) => !r.ledger);
       const { states, deleted } = worktreeStates(top, head, dir, records.map((r) => r.path), new RegExp(loaded.kind.location.match));
-      for (const r of records) r.worktree = states.get(r.path) ?? "new";
+      for (const r of inTree) r.worktree = states.get(r.path) ?? "new";
       const lastWrite = lastWriteReader(top);
-      for (const r of records) r.lastWrite = lastWrite(r.path, readTextOrNull(join(top, ...r.path.split("/"))));
+      for (const r of inTree) r.lastWrite = lastWrite(r.path, readTextOrNull(join(top, ...r.path.split("/"))));
       checkout = { branch: rest.branch, head, base: rest.base, baseFrom: rest.baseFrom, deleted };
       if (query.uncommitted) {
-        listed = records.filter((r) => r.worktree !== "committed");
+        listed = inTree.filter((r) => r.worktree !== "committed");
         summary = { ...summary, total: listed.length, valid: listed.filter((r) => r.valid).length, invalid: listed.filter((r) => !r.valid).length };
       }
     } else if (query.uncommitted && !top) {
@@ -664,7 +694,7 @@ export async function runWorkspaceRecords(ctx: CommandContext): Promise<number>
     else console.log(formatSince(since));
     return "error" in since ? 1 : 0;
   }
-  const doc = await queryRecords({ kind: args.kind, current: args.current, uncommitted: args.uncommitted, at: args.at, base: args.base, cwd: process.cwd() });
+  const doc = await queryRecords({ kind: args.kind, current: args.current, uncommitted: args.uncommitted, at: args.at, base: args.base, cwd: process.cwd(), fetchLedger: true });
   if (args.json) {
     console.log(JSON.stringify(doc, null, 2));
   } else if ("error" in doc) {
@@ -728,7 +758,7 @@ async function runDeclaredRecords(args: CommandContext["args"]): Promise<number>
     return 1;
   }
   if (args.since !== undefined) return runDeclaredSince(declared, args);
-  const set = await queryDeclaredRecords(declared, { current: args.current, uncommitted: args.uncommitted, at: args.at, base: args.base, cwd: process.cwd() });
+  const set = await queryDeclaredRecords(declared, { current: args.current, uncommitted: args.uncommitted, at: args.at, base: args.base, cwd: process.cwd(), fetchLedger: true });
   if (args.json) console.log(JSON.stringify(set, null, 2));
   for (const doc of args.json ? [] : set.kinds) {
     if ("error" in doc) {
@@ -827,7 +857,8 @@ function formatRecords(
     const attested = r.provenance.level === "attested" ? `  attested by ${r.provenance.principal}` : "";
     const sealed = r.attested === true ? `  sealed by ${(r.data?.[RECORD_SEAL_FIELD] as { signer: string }).signer}` : "";
     const uncommitted = r.worktree === "new" || r.worktree === "modified" ? `  (${r.worktree}, uncommitted)` : "";
-    lines.push(`${(r.id ?? "-").padEnd(idWidth)}  ${(r.state ?? "-").padEnd(stateWidth)}  ${title}${superseded}${remediated}${attested}${sealed}${uncommitted}${flag}`);
+    const ledger = r.ledger ? `  (held on ${r.ledger})` : "";
+    lines.push(`${(r.id ?? "-").padEnd(idWidth)}  ${(r.state ?? "-").padEnd(stateWidth)}  ${title}${superseded}${remediated}${attested}${sealed}${uncommitted}${ledger}${flag}`);
     if (r.ready !== undefined) {
       const blocked = (r.blockedBy ?? []).map((b) => `${b.id} (${b.state ?? "unknown"})`).join(", ");
       const implemented = (r.implements ?? []).map((d) => `${d.id} (${d.state ?? "unknown"})`).join(", ");

package/src/workspace/records.schema.json

@@ -327,6 +327,10 @@
           "type": "array",
           "items": { "$ref": "#/$defs/workAnswer" }
         },
+        "ledger": {
+          "type": ["string", "null"],
+          "description": "Added in contract 1 by #3833, on every record of an answer kind (one with an answers block) read in the working tree; absent under --at. Where the record is held on the lifecycle ledger, chant/lifecycle:<path on the branch>, as chant workspace points names it for a question, or null when it is the working tree's file. An answer held on the ledger (a question a steward asked, or one asked with --store ledger) reads as if it sat in the kind's directory and wins over a file of the same name; it has no worktree or lastWrite and is never listed by --uncommitted. The command fetches chant/lifecycle first, best effort."
+        },
         "lease": {
           "description": "Added in contract 1 by #2732, on every record of a work kind with an id, read in the working tree (absent under --at). The item's active work lease (chant workspace work claim), or null when nobody holds one live. Read from the local lease refs, refs/chant/lease/[_members/<member>/]work/<id> and the remote's as last fetched, of the ledger owning the work kind file; records never fetches.",
           "oneOf": [{ "type": "null" }, { "$ref": "#/$defs/workLease" }]