@intentius/chant 0.106.3 → 0.107.1

package/src/op/local-executor.ts

@@ -28,9 +28,12 @@ import { parseDuration } from "./duration";
 import { stepTimeoutProblem } from "./activity-profiles";
 import { describeGateMismatch, evaluateGate, gateIsSealed, gitGateLedgerPort, type GateCheck, type GateLedgerPort } from "./gate";
 import { gateName } from "./gate-name";
+import { gatePointOf } from "./gate-point";
+import { evaluatePointGate, workspaceGatePointAsker, type GatePointAsker } from "./gate-point-run";
 import type { ResolvedGateApproval } from "./gate-approval";
+import { GATE_PLAN_CONTEXT_KEY, gatePlanSummaryOfResult } from "./gate-plan-context";
 import { withOpRunContext, type OpRunContext, type PassedGate } from "./run-context";
-import type { PendingGateRecord } from "../lifecycle/gate-ledger";
+import type { GateAnswerRef, PendingGateRecord } from "../lifecycle/gate-ledger";
 import { isPointWait, type WaitingPoint } from "./steward-points";
 import { isGateWait } from "./gate-wait";
 import { currentStewardTurn, enterStewardTurn } from "./steward-turn";
@@ -72,10 +75,12 @@ export interface StepRecord {
     resolvedBy: string;
     timestamp: string;
     url?: string;
-    /** On a gate with an `approval` block (#2508): whether a quorum or a policy permit passed it. */
-    via?: "quorum" | "policy";
+    /** On a gate with an `approval` block (#2508): whether a quorum or a policy permit passed it. `"point"` on a gate that asks a decision point (#3170). */
+    via?: "quorum" | "policy" | "point";
     /** On a gate with a quorum (#2508): every approver who counted toward it. */
     approvers?: string[];
+    /** On a gate that asks a decision point (#3170): the answer record that passed it, which the gate ledger's resolution cites too. */
+    answer?: GateAnswerRef;
   };
   /**
    * Why a step declined to proceed on something that is not a failure
@@ -489,6 +494,10 @@ interface GateContext {
   passed?: PassedGate[];
   /** The run's hold on its work item's lease (#2748). Absent in compensation phases, which run whatever the lease did. */
   work?: RunWorkLease;
+  /** How a gate that names a decision point asks it (#3170). */
+  points?: GatePointAsker;
+  /** The environment the run was started for, a point gate's `gate.env` input. */
+  env?: string;
 }
 
 /**
@@ -584,6 +593,13 @@ function resolveGateApproval(
       if (resolved !== undefined && resolved !== null) context[key] = resolved;
     }
   }
+  // #3182: a policy also sees what the plan does. When the gate's `plan`
+  // names the step that planned it and that step returned a change set, its
+  // summary lands under `context.plan` with no context code in the Op.
+  if (authored.policy && isStepOutputRef(step.plan)) {
+    const summary = gatePlanSummaryOfResult(resultsById.get(step.plan.step));
+    if (summary) context = { ...(context ?? {}), [GATE_PLAN_CONTEXT_KEY]: summary };
+  }
   return {
     ...(authored.quorum ? { quorum: authored.quorum } : {}),
     ...(authored.policy ? { policy: authored.policy } : {}),
@@ -604,6 +620,7 @@ async function runGateStep(
   gates: GateContext,
   resultsById: ReadonlyMap<string, unknown> = new Map(),
 ): Promise<{ record: StepRecord; pending?: PendingGateRecord; pushed?: boolean; pushWarning?: string }> {
+  if (step.point !== undefined) return runPointGateStep(step, phaseName, gates, resultsById);
   const start = Date.now();
   // #2300: `plan` is authored as a reference into the Plan phase's result
   // (`plan.out.planDigest`), and is resolved here through the same walk an
@@ -689,6 +706,57 @@ async function runGateStep(
   };
 }
 
+/**
+ * Decide a gate that asks a decision point (#3170, `./gate-point-run.ts`).
+ * An answer it passes on lands on the step record as the approval, citing
+ * the answer record; an open question puts the question on the record, as an
+ * activity's open point does, and the caller ends the run `waiting`; any
+ * other answer fails the step.
+ */
+async function runPointGateStep(
+  step: GateStep,
+  phaseName: string,
+  gates: GateContext,
+  resultsById: ReadonlyMap<string, unknown>,
+): Promise<{ record: StepRecord; pushed?: boolean; pushWarning?: string }> {
+  const start = Date.now();
+  const point = gatePointOf(step.point)!;
+  const base = { phase: phaseName, fn: gateFn(step), args: {} };
+  const resolvedPlan = resolveStepOutputRefs(step.plan, resultsById);
+  const planDigest = typeof resolvedPlan === "string" && resolvedPlan !== "" ? resolvedPlan : undefined;
+  const inputs = point.inputs ? (resolveStepOutputRefs(point.inputs, resultsById) as Record<string, unknown>) : undefined;
+  try {
+    const check = await evaluatePointGate(gates.port, gates.points ?? workspaceGatePointAsker(process.cwd()), {
+      op: gates.op,
+      gate: gateName(step),
+      point,
+      ...(inputs ? { inputs } : {}),
+      ...(step.description ? { description: step.description } : {}),
+      ...(step.timeout ? { timeout: step.timeout } : {}),
+      ...(gates.runId ? { runId: gates.runId } : {}),
+      ...(planDigest !== undefined ? { planDigest } : {}),
+      ...(gates.env !== undefined ? { env: gates.env } : {}),
+      ...(gates.now ? { now: gates.now } : {}),
+    });
+    if (check.satisfied) {
+      const approval: NonNullable<StepRecord["approval"]> = {
+        gate: gateName(step),
+        resolvedBy: check.resolution.resolvedBy,
+        timestamp: check.resolution.timestamp,
+        via: "point",
+        ...(check.answer.answeredBy ? { approvers: check.answer.answeredBy } : {}),
+        answer: check.answer,
+      };
+      gates.passed?.push({ gate: gateName(step), approval });
+      return { record: { ...base, status: "ok", durationMs: Date.now() - start, approval }, pushed: check.pushed, ...(check.pushWarning ? { pushWarning: check.pushWarning } : {}) };
+    }
+    if ("refused" in check) return { record: { ...base, status: "fail", durationMs: Date.now() - start, error: check.refused } };
+    return { record: { ...base, status: "skipped", durationMs: Date.now() - start, point: check.waiting }, pushed: check.pushed, ...(check.pushWarning ? { pushWarning: check.pushWarning } : {}) };
+  } catch (err) {
+    return { record: { ...base, status: "fail", durationMs: Date.now() - start, error: errMessage(err) } };
+  }
+}
+
 /**
  * Run one effect step: read-compare-run-write. On a match the nested steps are
  * recorded as skipped ("effect already applied") and nothing is written. On a
@@ -778,6 +846,11 @@ async function runEffectStep(
         skipRest(i + 1);
         return { records, failed: false, pending, pushed, ...(pushWarning ? { pushWarning } : {}) };
       }
+      if (record.point) {
+        // A gate's open decision point (#3170): as for an activity's.
+        skipRest(i + 1);
+        return { records, failed: false, point: record.point };
+      }
       continue;
     }
     const ran = await runStep(nested, phaseName, activities, profiles, resultsById, signal);
@@ -866,6 +939,13 @@ async function runPhase(
         }
         throw new GateStop(gateRecords, pending, phase.name, pushed, pushWarning);
       }
+      if (record.point) {
+        // A gate's open decision point (#3170): nothing fans out.
+        for (const skipped of phase.steps.filter(isActivity)) {
+          pushRecord(gateRecords, gates, skippedRecord(phase.name, skipped.fn, skipped.args));
+        }
+        throw new PointStop(gateRecords, record.point, phase.name);
+      }
     }
     const steps = phase.steps.filter(isActivity);
     const settled = await Promise.all(steps.map((s) => runStep(s, phase.name, activities, profiles, resultsById, signal)));
@@ -921,6 +1001,12 @@ async function runPhase(
         skipRemaining(i + 1);
         throw new GateStop(records, pending, phase.name, pushed, pushWarning);
       }
+      if (record.point) {
+        // A gate that asks a decision point (#3170) and found it open: the
+        // run waits on the question, as at an activity's open point.
+        skipRemaining(i + 1);
+        throw new PointStop(records, record.point, phase.name);
+      }
       continue;
     }
     if (isEffect(step)) {
@@ -980,6 +1066,11 @@ export interface RunOpOptions {
   now?: string;
   /** Identifies this run on any pending fact it records. */
   runId?: string;
+  /**
+   * How a gate that names a decision point asks it (#3170). Defaults to the
+   * workspace holding `cwd` (`workspaceGatePointAsker`); a test passes a stub.
+   */
+  points?: GatePointAsker;
   /**
    * The environment the run was started for (`--env`, #2522). The executor
    * only hands it to activities through the run context (`./run-context.ts`).
@@ -1102,6 +1193,8 @@ async function runOpInTurn(
     runId,
     ...(options.onRecord ? { onRecord: options.onRecord } : {}),
     passed: run.passedGates,
+    points: options.points ?? workspaceGatePointAsker(options.cwd ?? process.cwd()),
+    ...(options.env !== undefined ? { env: options.env } : {}),
   };
 
   // Effect steps are ordered (read-compare-run-write): refuse them in a

package/src/op/op-ir.ts

@@ -149,6 +149,8 @@ export interface OpIRGateStep {
   plan?: GateStep["plan"];
   /** Quorum, roles and policy (#2508), carried as authored. Absent on a gate that passes on one approval. */
   approval?: GateStep["approval"];
+  /** The decision point the gate asks (#3170), carried as authored. Absent on a gate that `chant approve` passes. */
+  point?: GateStep["point"];
 }
 
 export interface OpIREffectStep {
@@ -258,6 +260,7 @@ function irGateStep(step: GateStep): OpIRGateStep {
     ...(step.description ? { description: step.description } : {}),
     ...(step.plan !== undefined ? { plan: step.plan } : {}),
     ...(step.approval !== undefined ? { approval: step.approval } : {}),
+    ...(step.point !== undefined ? { point: step.point } : {}),
   };
 }
 
@@ -412,6 +415,7 @@ function opStepFromIR(step: OpIRStep): StepDefinition {
       ...(step.description ? { description: step.description } : {}),
       ...(step.plan !== undefined ? { plan: step.plan } : {}),
       ...(step.approval !== undefined ? { approval: step.approval } : {}),
+      ...(step.point !== undefined ? { point: step.point } : {}),
     };
   }
   return {

package/src/op/types.ts

@@ -9,6 +9,7 @@ import type { EffectReceiptRef } from "./receipt-store";
 import type { ActivityProfileName } from "./activity-profiles";
 import type { StepOutputRef } from "./step-output-ref";
 import type { GateApproval } from "./gate-approval";
+import type { GatePoint } from "./gate-point";
 
 export interface OpConfig {
   /** Kebab-case identifier. Names the Op's output directory (`dist/ops/<name>/`), and is the name `chant run <name>` and another Op's `depends` refer to. */
@@ -276,6 +277,16 @@ export interface GateStepBase {
    * `./gate-approval.ts`.
    */
   approval?: GateApproval;
+  /**
+   * A declared decision point this gate asks (#3170), by name or as a
+   * {@link GatePoint}. Reaching the gate asks the point: its deciders and
+   * quorum decide, the answer is an answer record, and `chant workspace
+   * points answer` answers an open question. The run passes the gate on an
+   * answer in `pass`, and the resolution it writes cites the record. A gate
+   * with a point takes no `approval`: the point's quorum is the gate's. See
+   * `./gate-point.ts`.
+   */
+  point?: string | GatePoint;
 }
 
 /**

package/src/workspace/status-gates.ts

@@ -72,8 +72,18 @@ export interface StatusGate {
    * `--sign`. Null when any approval counts.
    */
   signed: { class: string | null } | null;
-  /** The command that approves it, run in the member's directory. */
+  /**
+   * The command that approves it, run in the member's directory. For a gate
+   * that asks a decision point (#3170), the `chant workspace points answer`
+   * line for its open question.
+   */
   approve: string;
+  /**
+   * The open question the gate waits on, when it asks a decision point
+   * (#3170): the point, the answer record's id and its path. Absent on a
+   * gate `chant approve` passes.
+   */
+  answer?: { point: string; id: string; path: string };
 }
 
 /** The rule for a gate, by name, as `identity.gates` at base sets it (#3163). Null when it sets none. */
@@ -171,7 +181,8 @@ function decide(component: string, standing: PendingGateRecord, all: GateResolut
     approvals: approvals.map(approvalOf),
     needed,
     signed: rule === null ? null : { class: rule.requirement.class },
-    approve: approveCommand(component, gate, env, planDigest, rule !== null),
+    approve: standing.answer ? `chant workspace points answer ${standing.answer.id} --answer <value> --by <name>` : approveCommand(component, gate, env, planDigest, rule !== null),
+    ...(standing.answer ? { answer: { point: standing.answer.point, id: standing.answer.id, path: standing.answer.path } } : {}),
   };
 }
 

package/src/workspace/status.schema.json

@@ -848,7 +848,17 @@
             }
           ]
         },
-        "approve": { "type": "string", "description": "The chant approve line for the gate, run in the member's directory: chant approve <component> <gate>, with --env <env> when env is not null and --plan <planDigest> when planDigest is not null (#2832), so the line approves the plan this read showed, and --sign when signed is not null (#3163). The caller adds --actor <principal>." }
+        "approve": { "type": "string", "description": "The chant approve line for the gate, run in the member's directory: chant approve <component> <gate>, with --env <env> when env is not null and --plan <planDigest> when planDigest is not null (#2832), so the line approves the plan this read showed, and --sign when signed is not null (#3163). The caller adds --actor <principal>. For a gate that asks a decision point (#3170), the chant workspace points answer line for the question in answer." },
+        "answer": {
+          "type": "object",
+          "description": "The open question the gate waits on, when it asks a decision point (#3170): absent on a gate chant approve passes. Answered with chant workspace points answer <id>; the run that passes the gate then cites the answer record on the ledger.",
+          "required": ["point", "id", "path"],
+          "properties": {
+            "point": { "type": "string" },
+            "id": { "type": "string", "description": "The answer record's id." },
+            "path": { "type": "string", "description": "The answer record, from the repository root." }
+          }
+        }
       }
     },
     "environment": {