@intentius/chant 0.124.24 → 0.124.26

package/src/op/runtimes/local.ts

@@ -22,6 +22,8 @@ import { lexiconNames } from "../../lexicon-module";
 import { loadChantConfig } from "../../config";
 import { loadActivities, loadProfiles } from "../activity-registry";
 import { runOpLocally, OpRunFailure, type OpRunResult } from "../local-executor";
+import { loadActivityContracts } from "../activity-contract-registry";
+import { resumeGatesOf } from "../gate-checkpoint";
 import { stepHeartbeatMs } from "../step-console";
 import { runComponents } from "../../components/cli-support";
 import { discoverOps } from "../discover";
@@ -139,6 +141,8 @@ export function createLocalOpRuntime(opts: { projectPath?: string } = {}): OpRun
       }
 
       const [activities, profiles] = await Promise.all([loadActivities(lexicons), loadProfiles()]);
+      // #3947: a gate that resumes stores no output a contract marks secret.
+      const contracts = resumeGatesOf(op).length > 0 ? await loadActivityContracts(lexicons) : undefined;
 
       // A caller that names the run (#3539: `chant acp` on fountain passes the
       // conversation id) gets its id on the record; otherwise one is minted.
@@ -179,6 +183,7 @@ export function createLocalOpRuntime(opts: { projectPath?: string } = {}): OpRun
               stepOutput: (line) => process.stderr.write(`${line}\n`),
               stepHeartbeatMs: stepHeartbeatMs(process.env, (message) => process.stderr.write(`warning: ${message}\n`)),
               ...(startOpts.work ? { work: startOpts.work } : {}),
+              ...(contracts ? { contracts } : {}),
               onWorkLeaseWarning: (message) =>
                 process.stderr.write(`warning: "${op.name}" could not renew its work lease, retrying at the next beat: ${message}\n`),
             },

package/src/op/step-output-ref.test.ts

@@ -10,7 +10,7 @@ import { z } from "zod";
 import { activity, phase, effect } from "./builders";
 import type { OpConfig } from "./types";
 import { activityContract, type ActivityContract } from "./activity-contract";
-import { stepOutput, isStepOutputRef, collectStepOutputRefs, validateStepOutputRefs } from "./step-output-ref";
+import { stepOutput, isStepOutputRef, collectStepOutputRefs, validateStepOutputRefs, validateStepOutputRefScope } from "./step-output-ref";
 import { EffectReceipt } from "../effect-receipt";
 
 const lifecycleDiffContract = activityContract(
@@ -248,39 +248,83 @@ describe("validateStepOutputRefs() — structural coverage", () => {
     expect(issues.some((i) => i.message.includes("declares no return schema"))).toBe(true);
   });
 
-  it("flags a reference authored inside onFailure", () => {
+  it("reports every issue across multiple refs, not just the first", () => {
+    const apply1 = activity("applyStacks", { stacks: stepOutput("nope1", "x") });
+    const apply2 = activity("applyStacks", { stacks: stepOutput("nope2", "x") });
+    const config = opWith({ phases: [phase("P", [apply1, apply2])] });
+    const issues = validateStepOutputRefs(config, new Map([["applyStacks", applyStacksContract]]));
+    expect(issues.some((i) => i.message.includes("nope1"))).toBe(true);
+    expect(issues.some((i) => i.message.includes("nope2"))).toBe(true);
+  });
+});
+
+// ── onFailure and effect steps (#3948) ───────────────────────────────────────
+
+describe("validateStepOutputRefs() — onFailure and effect steps (#3948)", () => {
+  const seeded = EffectReceipt("seeded", { effect: "db-seed", flavor: "hash", inputs: { file: "seed.sql", version: 3 } });
+  const contracts = new Map<string, ActivityContract>([
+    ["lifecycleDiff", lifecycleDiffContract],
+    ["applyStacks", applyStacksContract],
+  ]);
+
+  it("an onFailure step may reference any main-phase step", () => {
     const diff = activity("lifecycleDiff", { env: "prod" }, { id: "diff" });
+    const apply = activity("applyStacks", { stacks: ["a"] });
     const rollback = activity("applyStacks", { stacks: stepOutput("diff", "driftedStacks") });
+    const config = opWith({ phases: [phase("Diff", [diff]), phase("Apply", [apply])], onFailure: [phase("Rollback", [rollback])] });
+    expect(validateStepOutputRefs(config, contracts)).toEqual([]);
+  });
+
+  it("an onFailure step's reference is still checked against the producer's contract", () => {
+    const diff = activity("lifecycleDiff", { env: "prod" }, { id: "diff" });
+    const rollback = activity("applyStacks", { stacks: stepOutput("diff", "nope") });
     const config = opWith({ phases: [phase("P", [diff])], onFailure: [phase("Rollback", [rollback])] });
-    const contracts = new Map<string, ActivityContract>([
-      ["lifecycleDiff", lifecycleDiffContract],
-      ["applyStacks", applyStacksContract],
-    ]);
     const issues = validateStepOutputRefs(config, contracts);
-    expect(issues.some((i) => i.message.includes("onFailure compensation"))).toBe(true);
+    expect(issues).toHaveLength(1);
+    expect(issues[0].phase).toBe("Rollback");
+    expect(issues[0].message).toMatch(/path "nope", which does not exist/);
+  });
+
+  it("an onFailure step cannot reference another onFailure step", () => {
+    const diff = activity("lifecycleDiff", { env: "prod" }, { id: "undoDiff" });
+    const rollback = activity("applyStacks", { stacks: stepOutput("undoDiff", "driftedStacks") });
+    const config = opWith({ phases: [phase("P", [activity("applyStacks", { stacks: [] })])], onFailure: [phase("Rollback", [diff, rollback])] });
+    expect(validateStepOutputRefScope(config)[0].message).toMatch(/unknown step id "undoDiff"/);
   });
 
-  it("flags a reference authored inside an effect step's nested steps", () => {
-    const receipt = EffectReceipt("seeded", { effect: "db-seed", flavor: "hash", inputs: { file: "seed.sql", version: 3 } });
+  it("a step inside an effect may reference a step that runs before the effect", () => {
     const diff = activity("lifecycleDiff", { env: "prod" }, { id: "diff" });
     const nested = activity("applyStacks", { stacks: stepOutput("diff", "driftedStacks") });
-    const effectStep = effect(receipt, [nested]);
-    const config = opWith({ phases: [phase("P", [diff, effectStep])] });
-    const contracts = new Map<string, ActivityContract>([
-      ["lifecycleDiff", lifecycleDiffContract],
-      ["applyStacks", applyStacksContract],
-    ]);
-    const issues = validateStepOutputRefs(config, contracts);
-    expect(issues.some((i) => i.message.includes("nested inside an effect step"))).toBe(true);
+    const config = opWith({ phases: [phase("P", [diff, effect(seeded, [nested])])] });
+    expect(validateStepOutputRefs(config, contracts)).toEqual([]);
   });
 
-  it("reports every issue across multiple refs, not just the first", () => {
-    const apply1 = activity("applyStacks", { stacks: stepOutput("nope1", "x") });
-    const apply2 = activity("applyStacks", { stacks: stepOutput("nope2", "x") });
-    const config = opWith({ phases: [phase("P", [apply1, apply2])] });
-    const issues = validateStepOutputRefs(config, new Map([["applyStacks", applyStacksContract]]));
-    expect(issues.some((i) => i.message.includes("nope1"))).toBe(true);
-    expect(issues.some((i) => i.message.includes("nope2"))).toBe(true);
+  it("a step inside an effect in onFailure may reference a main-phase step", () => {
+    const diff = activity("lifecycleDiff", { env: "prod" }, { id: "diff" });
+    const nested = activity("applyStacks", { stacks: stepOutput("diff", "driftedStacks") });
+    const config = opWith({ phases: [phase("P", [diff])], onFailure: [phase("Undo", [effect(seeded, [nested])])] });
+    expect(validateStepOutputRefs(config, contracts)).toEqual([]);
+  });
+
+  it("a step inside an effect cannot reference a step after the effect", () => {
+    const nested = activity("applyStacks", { stacks: stepOutput("diff", "driftedStacks") });
+    const diff = activity("lifecycleDiff", { env: "prod" }, { id: "diff" });
+    const config = opWith({ phases: [phase("P", [effect(seeded, [nested]), diff])] });
+    expect(validateStepOutputRefScope(config)[0].message).toMatch(/step "diff" does not run before this step/);
+  });
+
+  it("nothing can reference a step nested inside an effect (decision A7)", () => {
+    const inner = activity("lifecycleDiff", { env: "prod" }, { id: "inner" });
+    const sibling = activity("applyStacks", { stacks: stepOutput("inner", "driftedStacks") });
+    const later = activity("applyStacks", { stacks: stepOutput("inner", "driftedStacks") });
+    const rollback = activity("applyStacks", { stacks: stepOutput("inner", "driftedStacks") });
+    const config = opWith({
+      phases: [phase("P", [effect(seeded, [inner, sibling]), later])],
+      onFailure: [phase("Rollback", [rollback])],
+    });
+    const issues = validateStepOutputRefScope(config);
+    expect(issues).toHaveLength(3);
+    for (const issue of issues) expect(issue.message).toMatch(/"inner", which is nested inside an effect step/);
   });
 });
 

package/src/op/step-output-ref.ts

@@ -23,15 +23,20 @@
  * Scope, kept deliberately tight (see the issue's "Open questions"):
  *  - same-Op only — no cross-Op plumbing (that needs a durable place to put
  *    the value, which #1290 explicitly defers).
- *  - main `phases` only — a step inside `onFailure` or nested inside an
- *    `EffectStep` can neither produce nor consume a step-output reference.
- *    `onFailure` compensation runs only when something upstream already
- *    failed, so a main-phase step's captured result isn't reliably
- *    available there; an effect step's nested steps run only when the
- *    receipt comparison mismatches, so a value it produces isn't reliably
- *    available to anything outside it either. Both are conditional
- *    execution paths, which is exactly the class of thing #1290 keeps out
- *    of an Op's inert-data model.
+ *  - producers are the top-level activity steps of the main `phases`. A step
+ *    in `onFailure` or nested inside an `EffectStep` produces nothing another
+ *    step may reference: an effect's nested steps run only when the receipt
+ *    comparison mismatches, so a value one of them returns isn't reliably
+ *    there for anything else (#3948 decision A7, "for now").
+ *  - consumers are those producers, plus (#3948) every activity step in
+ *    `onFailure` and every activity step nested inside an effect. An
+ *    `onFailure` step may reference any main-phase producer. Compensation
+ *    runs after a failure, so its producer may never have completed; the
+ *    executor then skips the compensation step and records why (decision
+ *    A6), rather than calling it with an `undefined` in place of the value.
+ *    A step nested inside an effect may reference a producer that runs
+ *    before the effect, and the executor folds the resolved values into the
+ *    effect's expectation, so a changed value re-fires the effect.
  *  - producer must run to completion before the consumer starts: an earlier
  *    phase, or an earlier step within the same non-parallel phase. Two
  *    steps in the same parallel phase run concurrently (`Promise.all`) with
@@ -243,26 +248,63 @@ function locateStepOutputRefPath(value: unknown, target: StepOutputRef, path: st
 // ── Validation ──────────────────────────────────────────────────────────────
 
 interface StepLocation {
+  /** Index into `phases`; every `onFailure` phase sits after all of them. */
   phaseIndex: number;
+  /** Index into the phase's `steps`. A step nested in an effect takes the effect's. */
   stepIndex: number;
   parallel: boolean;
   step: ActivityStep;
+  phaseName: string;
 }
 
-/** Top-level `ActivityStep`s of `phases`, in authored (phase, then step) order — gates, effects, and steps nested inside an effect are not producers or consumers (see the module doc's scope note). */
+/** Top-level `ActivityStep`s of `phases`, in authored (phase, then step) order: the producers (see the module doc's scope note). */
 function locateActivitySteps(phases: PhaseDefinition[]): StepLocation[] {
   const locations: StepLocation[] = [];
   phases.forEach((phase, phaseIndex) => {
-    let stepIndex = 0;
-    for (const step of phase.steps) {
-      if (step.kind !== "activity") continue;
-      locations.push({ phaseIndex, stepIndex, parallel: phase.parallel === true, step });
-      stepIndex++;
-    }
+    phase.steps.forEach((step, stepIndex) => {
+      if (step.kind !== "activity") return;
+      locations.push({ phaseIndex, stepIndex, parallel: phase.parallel === true, step, phaseName: phase.name });
+    });
   });
   return locations;
 }
 
+/**
+ * Every activity step that may hold a reference (#3948): the producers, each
+ * step nested inside an effect of a main phase, and every activity step of
+ * `onFailure`, effect-nested ones included. An `onFailure` step is placed after
+ * every main phase, so any main-phase producer precedes it.
+ */
+function locateConsumers(config: Pick<OpConfig, "phases" | "onFailure">): StepLocation[] {
+  const consumers: StepLocation[] = [];
+  const visit = (phases: PhaseDefinition[], offset: number) => {
+    phases.forEach((phase, i) => {
+      const at = { phaseIndex: offset + i, parallel: phase.parallel === true, phaseName: phase.name };
+      phase.steps.forEach((step, stepIndex) => {
+        if (step.kind === "activity") consumers.push({ ...at, stepIndex, step });
+        if (step.kind === "effect") {
+          for (const nested of step.steps) if (nested.kind === "activity") consumers.push({ ...at, stepIndex, step: nested });
+        }
+      });
+    });
+  };
+  visit(config.phases, 0);
+  visit(config.onFailure ?? [], config.phases.length);
+  return consumers;
+}
+
+/** Ids of the activity steps nested inside an effect, in any phase. Nothing may reference them (#3948 decision A7). */
+function effectNestedIds(config: Pick<OpConfig, "phases" | "onFailure">): Set<string> {
+  const ids = new Set<string>();
+  for (const phase of [...config.phases, ...(config.onFailure ?? [])]) {
+    for (const step of phase.steps) {
+      if (step.kind !== "effect") continue;
+      for (const nested of step.steps) if (nested.kind === "activity" && nested.id) ids.add(nested.id);
+    }
+  }
+  return ids;
+}
+
 /** True when `producer` is guaranteed to have completed before `consumer` starts. */
 function producerPrecedes(producer: StepLocation, consumer: StepLocation): boolean {
   if (producer.phaseIndex !== consumer.phaseIndex) return producer.phaseIndex < consumer.phaseIndex;
@@ -270,10 +312,6 @@ function producerPrecedes(producer: StepLocation, consumer: StepLocation): boole
   return producer.stepIndex < consumer.stepIndex;
 }
 
-function effectNestedActivitySteps(phase: PhaseDefinition): ActivityStep[] {
-  return phase.steps.flatMap((s) => (s.kind === "effect" ? s.steps.filter((n) => n.kind === "activity") : []));
-}
-
 /** `byId`/`duplicateIds` over an Op's top-level main-phase activity steps — shared by {@link validateStepOutputRefScope} and {@link validateStepOutputRefs}. */
 function indexById(locations: StepLocation[]): { byId: Map<string, StepLocation>; duplicateIds: Set<string> } {
   const byId = new Map<string, StepLocation>();
@@ -298,46 +336,28 @@ function indexById(locations: StepLocation[]): { byId: Map<string, StepLocation>
  * a public export a caller can invoke directly, bypassing that lint pass —
  * this is its own defense-in-depth.
  *
- * Flags:
- *  - a reference authored inside `onFailure`, or inside an `EffectStep`'s
- *    nested steps — out of scope by design (see the module doc); flagged
- *    explicitly here rather than left to fall through as "unknown producer",
+ * Consumers are the main-phase activity steps, the steps nested inside an
+ * effect, and every `onFailure` activity step (#3948). Flags:
+ *  - a reference to a step nested inside an effect step, from anywhere
+ *    (#3948 decision A7) — flagged explicitly here rather than left to fall
+ *    through as "unknown producer",
  *  - a reference to an unregistered step id (no step in scope declares it),
  *  - a duplicate step id (ambiguous producer),
  *  - a reference to a step that does not precede the referencing step
  *    (a later phase, a later step in the same phase, itself, or a step in
- *    the same parallel phase).
+ *    the same parallel phase). A step nested inside an effect takes the
+ *    effect's position, so it may reference only a step that runs before
+ *    the effect. An `onFailure` step comes after every main phase.
  */
 export function validateStepOutputRefScope(
   config: Pick<OpConfig, "name" | "phases" | "onFailure"> & Partial<Pick<OpConfig, "workLease">>,
 ): ActivityContractIssue[] {
   const issues: ActivityContractIssue[] = [];
 
-  const flagOutOfScope = (steps: ActivityStep[], phaseName: string, reason: string) => {
-    for (const step of steps) {
-      for (const ref of collectStepOutputRefs(step.args)) {
-        issues.push({
-          opName: config.name,
-          phase: phaseName,
-          fn: step.fn,
-          message: `references step "${ref.step}"'s output, but ${reason}`,
-        });
-      }
-    }
-  };
-  for (const phase of config.onFailure ?? []) {
-    const steps = phase.steps.filter((s): s is ActivityStep => s.kind === "activity").concat(effectNestedActivitySteps(phase));
-    flagOutOfScope(steps, phase.name, "step-output references are not supported in onFailure compensation phases");
-  }
-  for (const phase of config.phases) {
-    flagOutOfScope(effectNestedActivitySteps(phase), phase.name, "step-output references are not supported for a step nested inside an effect step");
-  }
-
-  const locations = locateActivitySteps(config.phases);
-  const { byId, duplicateIds } = indexById(locations);
-  const phaseNameOf = (loc: StepLocation): string => config.phases[loc.phaseIndex]!.name;
+  const { byId, duplicateIds } = indexById(locateActivitySteps(config.phases));
+  const nestedIds = effectNestedIds(config);
 
-  for (const consumer of locations) {
+  for (const consumer of locateConsumers(config)) {
     const refs = collectStepOutputRefs(consumer.step.args);
     for (const ref of refs) {
       // The run's work lease (#2748) is published under a reserved id once it
@@ -346,7 +366,7 @@ export function validateStepOutputRefScope(
       if (duplicateIds.has(ref.step)) {
         issues.push({
           opName: config.name,
-          phase: phaseNameOf(consumer),
+          phase: consumer.phaseName,
           fn: consumer.step.fn,
           message: `references step id "${ref.step}", but that id is used by more than one step in this Op — ids must be unique`,
         });
@@ -357,9 +377,11 @@ export function validateStepOutputRefScope(
       if (!producer) {
         issues.push({
           opName: config.name,
-          phase: phaseNameOf(consumer),
+          phase: consumer.phaseName,
           fn: consumer.step.fn,
-          message: `references unknown step id "${ref.step}" — no step in this Op's main phases declares that id`,
+          message: nestedIds.has(ref.step)
+            ? `references step "${ref.step}", which is nested inside an effect step — a step inside an effect runs only when the effect fires, so no other step can reference its output`
+            : `references unknown step id "${ref.step}" — no step in this Op's main phases declares that id`,
         });
         continue;
       }
@@ -373,7 +395,7 @@ export function validateStepOutputRefScope(
               : `step "${ref.step}" does not run before this step`;
         issues.push({
           opName: config.name,
-          phase: phaseNameOf(consumer),
+          phase: consumer.phaseName,
           fn: consumer.step.fn,
           message: `references ${reason} — a step can only reference an earlier step's output`,
         });
@@ -385,10 +407,10 @@ export function validateStepOutputRefScope(
 }
 
 /**
- * Validate every step-output reference in an Op's main phases against a
- * contract map and the Op's own step ordering. Scope: `config.phases` only
- * (never `onFailure`, never a step nested inside an `EffectStep` — see the
- * module doc). Layers contract-based checks on top of {@link
+ * Validate every step-output reference in an Op against a contract map and
+ * the Op's own step ordering, over the consumers {@link
+ * validateStepOutputRefScope} covers (see the module doc). Layers
+ * contract-based checks on top of {@link
  * validateStepOutputRefScope}'s scope/ordering checks.
  *
  * Flags everything {@link validateStepOutputRefScope} does, plus:
@@ -404,11 +426,9 @@ export function validateStepOutputRefs(
 ): ActivityContractIssue[] {
   const issues = validateStepOutputRefScope(config);
 
-  const locations = locateActivitySteps(config.phases);
-  const { byId, duplicateIds } = indexById(locations);
-  const phaseNameOf = (loc: StepLocation): string => config.phases[loc.phaseIndex]!.name;
+  const { byId, duplicateIds } = indexById(locateActivitySteps(config.phases));
 
-  for (const consumer of locations) {
+  for (const consumer of locateConsumers(config)) {
     const refs = collectStepOutputRefs(consumer.step.args);
     for (const ref of refs) {
       // Already flagged by validateStepOutputRefScope — nothing to validate
@@ -421,7 +441,7 @@ export function validateStepOutputRefs(
       if (!producerContract) {
         issues.push({
           opName: config.name,
-          phase: phaseNameOf(consumer),
+          phase: consumer.phaseName,
           fn: consumer.step.fn,
           message: `references step "${ref.step}"'s output, but "${producer.step.fn}" has no registered activity contract to validate the reference against`,
         });
@@ -430,7 +450,7 @@ export function validateStepOutputRefs(
       if (!producerContract.returns) {
         issues.push({
           opName: config.name,
-          phase: phaseNameOf(consumer),
+          phase: consumer.phaseName,
           fn: consumer.step.fn,
           message: `references step "${ref.step}"'s output, but "${producer.step.fn}"'s contract declares no return schema`,
         });
@@ -439,7 +459,7 @@ export function validateStepOutputRefs(
       if (ref.path && !pathExistsInSchema(producerContract.returns as z.ZodTypeAny, ref.path)) {
         issues.push({
           opName: config.name,
-          phase: phaseNameOf(consumer),
+          phase: consumer.phaseName,
           fn: consumer.step.fn,
           message: `references step "${ref.step}"'s output path "${ref.path}", which does not exist on "${producer.step.fn}"'s declared return type`,
         });
@@ -466,7 +486,7 @@ export function validateStepOutputRefs(
           if (consumerKind && producerKind && consumerKind !== producerKind) {
             issues.push({
               opName: config.name,
-              phase: phaseNameOf(consumer),
+              phase: consumer.phaseName,
               fn: consumer.step.fn,
               message: `references step "${ref.step}"'s output path "${ref.path}" (${producerKind}), but arg "${argPath.join(".")}" on "${consumer.step.fn}" declares ${consumerKind} — type mismatch`,
             });

package/src/op/types.ts

@@ -298,6 +298,38 @@ export interface GateStepBase {
    * `./gate-point.ts`.
    */
   point?: string | GatePoint;
+  /**
+   * A run that stops at this gate can be resumed here once it is approved
+   * (#3947), rather than starting again at the first phase. The run stores
+   * the step outputs a later step references in a checkpoint on
+   * `chant/lifecycle`, and the next run after `chant approve` re-runs the
+   * step that produced the gate's `plan`, checks the checkpoint, and carries
+   * on from the gate. Any check that fails starts the run at the first phase,
+   * and the run says why. See `./gate-checkpoint.ts`.
+   *
+   * Only a gate at the top of a main phase resumes, and not one that asks a
+   * decision point or sits in an Op with a `workLease`. OPS016 refuses the
+   * rest at build.
+   */
+  resume?: boolean;
+  /**
+   * The names this gate had before an Op was restructured (#3949), so the
+   * approvals already recorded under them still count. `op` defaults to this
+   * Op. An approval recorded under an alias counts toward this gate when it
+   * answers that name's standing pending fact, the fact hasn't expired, it
+   * is for the plan this run planned and the same environment, it hasn't
+   * been spent, it passes this gate's `identity.gates` rule, and a person
+   * made it. The run then writes it again under this gate's name, citing
+   * the line it came from (`carriedFrom`). Only a gate bound to a `plan`
+   * takes aliases, and OPS017 refuses an alias that is still a gate.
+   */
+  aliases?: GateAlias[];
+}
+
+/** A name a gate had before (#3949): a gate of `op`, or of the gate's own Op when `op` is absent. */
+export interface GateAlias {
+  op?: string;
+  gate: string;
 }
 
 /**

package/src/workspace/agent-cli.ts

@@ -91,6 +91,8 @@ export async function agentSession(q: { cwd: string; name: string }): Promise<Ag
   try {
     const source = scopeSource(q.cwd);
     if (source.declaration === null || source.from === null) {
+      // A declaration that is there but fails validation says so (#3433).
+      if (source.failure && source.failure.code !== "declaration-missing") throw source.failure;
       throw new WorkspaceReadError("declaration-missing", "no chant.workspace.json or .jsonc between this directory and the git root, so no agent session is declared");
     }
     const decl = source.declaration;

package/src/workspace/conformance/__writer_fixture__/answers/answer.schema.json

@@ -2,7 +2,7 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "urn:intentius:chant:point-answer:1",
   "title": "Decision point answer front matter",
-  "description": "The front matter of one answer to a decision point (ws-058, #2739), as `chant workspace points ask` and `points answer` write it into the records directory of a record kind with an `answers` block. One record per point, declaration and inputs: its id is the point's name and the first 12 hex digits of the inputs hash, so the same question is answered once. A table's answer is `answered`; a model's answer at or above its threshold is `proposed` until a person confirms it; a question no decider before the quorum answered is `escalated`, open for people. An answer never changes in place: `points retract` escalates the question to people again and moves the answer into `retractions` (#3351, ws-084). An ad-hoc point's answer keeps the question and candidates its ask gave as `asked`, and they are part of the inputs hash (#3403). A workspace copies this file next to its answer kind, as reference-workspace/answers/ does. Values stay within what YAML and JSON share. Fields other than these must start with x-.",
+  "description": "The front matter of one answer to a decision point (ws-058, #2739), as `chant workspace points ask` and `points answer` write it into the records directory of a record kind with an `answers` block. One record per point, declaration and inputs: its id is the point's name and the first 12 hex digits of the inputs hash, so the same question is answered once. A table's answer is `answered`; a model's answer at or above its threshold is `proposed` until a person confirms it; a question no decider before the quorum answered is `escalated`, open for people. An answer never changes in place: `points retract` escalates the question to people again and moves the answer into `retractions` (#3351, ws-084). An open question that no longer applies is `withdrawn` (`points withdraw`, #2888), and asking it again opens it again. An ad-hoc point's answer keeps the question and candidates its ask gave as `asked`, and they are part of the inputs hash (#3403). A workspace copies this file next to its answer kind, as reference-workspace/answers/ does. Values stay within what YAML and JSON share. Fields other than these must start with x-.",
   "type": "object",
   "additionalProperties": false,
   "patternProperties": { "^x-": {} },
@@ -65,6 +65,17 @@
       "description": "Answers people took back, oldest first (`points retract`, #3351): each answer as it was, and who retracted it, when and why. A retracted question is escalated to people again.",
       "items": { "$ref": "#/definitions/retraction" }
     },
+    "withdrawn": {
+      "type": "object",
+      "description": "An open question that no longer applies, such as one about a work item its author changed, which a run asks about anew (`points withdraw`, #2888): who withdrew it, when and why. A withdrawn question is not open, and nobody answers it; asking it again opens it again.",
+      "required": ["by", "on"],
+      "properties": {
+        "by": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1 }, "description": "Who withdrew it." },
+        "on": { "$ref": "#/definitions/date" },
+        "note": { "type": "string", "minLength": 1, "description": "Why it was withdrawn (`points withdraw --note`)." }
+      },
+      "additionalProperties": false
+    },
     "asked_on": { "$ref": "#/definitions/date" },
     "answered_on": { "$ref": "#/definitions/date" },
     "source": {
@@ -85,6 +96,10 @@
       "if": { "properties": { "state": { "const": "escalated" } }, "required": ["state"] },
       "then": { "not": { "required": ["answer"] }, "properties": { "decider": { "properties": { "kind": { "const": "quorum" } } } } }
     },
+    {
+      "if": { "required": ["withdrawn"] },
+      "then": { "properties": { "state": { "enum": ["escalated", "proposed"] } } }
+    },
     {
       "if": { "properties": { "decider": { "properties": { "kind": { "const": "model" } }, "required": ["kind"] } }, "required": ["decider"] },
       "then": { "required": ["probabilities", "confidence", "threshold"], "properties": { "decider": { "required": ["backend", "model"] } } }

package/src/workspace/conformance/writer.ts

@@ -614,7 +614,7 @@ export function isReadCall(argv: readonly string[]): boolean {
     case "runs":
       return !["start", "end", "record"].includes(sub ?? "");
     case "points":
-      return !["ask", "answer", "retract"].includes(sub ?? "");
+      return !["ask", "answer", "retract", "withdraw"].includes(sub ?? "");
     case "work":
       return sub === "history";
     case "wip":

package/src/workspace/decide.test.ts

@@ -10,7 +10,7 @@ import { join } from "node:path";
 import { afterAll, beforeAll, describe, expect, test } from "vitest";
 import { runDeclarationChecks } from "./checks";
 import { cleanScratch, commitAll, contract, REPO, repo } from "./__fixtures__/contract-repo";
-import { answerFields, answerPoint, askPoint, reasonFields, retractAnswer, type PointsWriteDocument } from "./decide";
+import { answerFields, answerPoint, askPoint, reasonFields, retractAnswer, withdrawQuestion, type PointsWriteDocument } from "./decide";
 import pointAnswerSchema from "./point-answer.schema.json";
 import { responseAsk, workspacePoints } from "./points-cli";
 import pointsSchema from "./points.schema.json";
@@ -293,13 +293,13 @@ describe("the intent walk's points, a note on an answer, and retracting it (#335
   });
 
   test("a workspace whose answer schema predates notes and retractions refuses them, rather than dropping them", () => {
-    expect(answerFields(pointAnswerSchema)).toEqual({ note: true, retractions: true, relayedBy: true, asked: true });
+    expect(answerFields(pointAnswerSchema)).toEqual({ note: true, retractions: true, relayedBy: true, asked: true, withdrawn: true });
     const old = JSON.parse(JSON.stringify(pointAnswerSchema));
     delete old.properties.note;
     delete old.properties.retractions;
     delete old.properties.relayed_by;
     delete old.properties.asked;
-    expect(answerFields(old)).toEqual({ note: false, retractions: false, relayedBy: false, asked: false });
+    expect(answerFields(old)).toEqual({ note: false, retractions: false, relayedBy: false, asked: false, withdrawn: true });
   });
 
   test("an answer relayed for a person records who relayed it, and a retraction keeps it (#3402)", async () => {
@@ -399,6 +399,90 @@ describe("an ad-hoc question whose candidates come with the ask (#3403)", () =>
   });
 });
 
+describe("withdrawing an open question that no longer applies (#2888)", () => {
+  const item = (title: string) => ({
+    "work-item.state": "proposed",
+    "work-item.title": title,
+    "work-item.source.ask.said": "make the port configurable",
+    "work-item.source.ask.by": "alice",
+    "work-item.source.ask.via": "hud",
+    "work-item.acceptance": [],
+  });
+
+  test("the earlier question about a changed item is withdrawn, and --open leaves it out", async () => {
+    const first = ok(await askPoint({ cwd: root, point: "understand", inputs: item("Configurable port"), subject: "W-101", on }));
+    expect(first.question).toMatchObject({ state: "escalated", open: true, withdrawn: null });
+    // The author changes the item: the next ask is another question about W-101, and both are open.
+    const second = ok(await askPoint({ cwd: root, point: "understand", inputs: item("Make the server port configurable"), subject: "W-101", on }));
+    expect(second.id).not.toBe(first.id);
+    const openAbout = async () => {
+      const listed = await workspacePoints({ cwd: root, open: true });
+      read.expectValid(listed);
+      if ("error" in listed) throw new Error(listed.error.message);
+      return listed.questions.filter((q) => q.subject === "W-101").map((q) => q.id);
+    };
+    expect((await openAbout()).sort()).toEqual([first.id, second.id].sort());
+
+    const withdrawn = ok(await withdrawQuestion({ cwd: root, id: first.id, by: ["factory"], note: `W-101 changed; ${second.id} asks it now.`, on: "2026-09-26" }));
+    expect(withdrawn).toMatchObject({ verb: "withdraw", written: true });
+    expect(withdrawn.question).toMatchObject({ state: "escalated", open: false, answer: null, withdrawn: { by: ["factory"], on: "2026-09-26", note: `W-101 changed; ${second.id} asks it now.` } });
+    expect(withdrawn.question.title).toMatch(/: withdrawn$/);
+    expect(fm(first.path)).toContain('withdrawn:\n  by:\n    - "factory"');
+    expect(await openAbout()).toEqual([second.id]);
+  });
+
+  test("a withdrawn question is closed: nobody answers it, and refusals", async () => {
+    const asked = ok(await askPoint({ cwd: root, point: "understand", inputs: item("Refusals"), on }));
+    expect(refused(await withdrawQuestion({ cwd: root, id: asked.id, by: [" "] }))).toBe("write-usage-invalid");
+    expect(ok(await withdrawQuestion({ cwd: root, id: asked.id, by: ["factory"], dryRun: true }))).toMatchObject({ verb: "withdraw", written: false, question: { open: false } });
+    expect(fm(asked.path)).not.toContain("withdrawn:");
+    ok(await withdrawQuestion({ cwd: root, id: asked.id, by: ["factory"], on }));
+    expect(refused(await answerPoint({ cwd: root, id: asked.id, answer: "proceed", by: ["alice"] }))).toBe("record-closed");
+    expect(refused(await withdrawQuestion({ cwd: root, id: asked.id, by: ["factory"] }))).toBe("record-closed");
+    const table = ok(await askPoint({ cwd: root, point: "slice-tier", inputs: { "work-item.fits_small": true }, on }));
+    expect(refused(await withdrawQuestion({ cwd: root, id: table.id, by: ["factory"] }))).toBe("record-closed");
+    const all = await workspacePoints({ cwd: root });
+    if ("error" in all) throw new Error(all.error.message);
+    expect(all.summary.withdrawn).toBe(all.questions.filter((q) => q.withdrawn !== null).length);
+    expect(all.summary.withdrawn).toBeGreaterThan(0);
+  });
+
+  test("asking a withdrawn question again opens it again", async () => {
+    const asked = ok(await askPoint({ cwd: root, point: "understand", inputs: item("Port, again"), subject: "W-102", on }));
+    ok(await withdrawQuestion({ cwd: root, id: asked.id, by: ["factory"], on }));
+    // The item changed back: the same inputs ask the same question.
+    const again = ok(await askPoint({ cwd: root, point: "understand", inputs: item("Port, again"), on: "2026-09-27" }));
+    expect(again).toMatchObject({ id: asked.id, reused: false, written: true, question: { state: "escalated", open: true, withdrawn: null, subject: "W-102", askedOn: "2026-09-27" } });
+    expect(fm(asked.path)).not.toContain("withdrawn:");
+  });
+
+  test("a retracted question withdrawn and asked again is open for people again, its retractions kept", async () => {
+    const inputs = { "region.id": "region:app/server.mjs:1-1", "node.id": "decision:ref-009" };
+    const asked = ok(await askPoint({ cwd: root, point: "intent-origin", inputs, on }));
+    ok(await answerPoint({ cwd: root, id: asked.id, answer: "incidental", by: ["alice"], on }));
+    ok(await retractAnswer({ cwd: root, id: asked.id, by: ["alice"], on }));
+    ok(await withdrawQuestion({ cwd: root, id: asked.id, by: ["factory"], on }));
+    const again = ok(await askPoint({ cwd: root, point: "intent-origin", inputs, on }));
+    expect(again).toMatchObject({ reused: false, question: { state: "escalated", open: true, withdrawn: null, retractions: [{ answer: "incidental" }] } });
+    expect(again.question.title).toMatch(/: open for people$/);
+  });
+
+  test("a workspace whose answer schema predates withdrawn refuses to withdraw", async () => {
+    expect(answerFields(pointAnswerSchema).withdrawn).toBe(true);
+    const asked = ok(await askPoint({ cwd: root, point: "understand", inputs: item("Old schema"), on }));
+    const schemaFile = join(root, "answers", "answer.schema.json");
+    const original = readFileSync(schemaFile, "utf-8");
+    const old = JSON.parse(original);
+    delete old.properties.withdrawn;
+    writeFileSync(schemaFile, JSON.stringify(old, null, 2));
+    try {
+      expect(refused(await withdrawQuestion({ cwd: root, id: asked.id, by: ["factory"] }))).toBe("answer-field-unsupported");
+    } finally {
+      writeFileSync(schemaFile, original);
+    }
+  });
+});
+
 describe("the points file in check and on read (#2738)", () => {
   test("a changed point warns on its answers, and an invalid points file is WSP116 and a points-invalid source", async () => {
     const file = join(root, "decisions", "points.json");