@intentius/chant 0.124.25 → 0.124.26

package/src/lifecycle/gate-checkpoint.test.ts

@@ -0,0 +1,128 @@
+/**
+ * #3947 on a real `chant/lifecycle` branch: the checkpoint lands at
+ * `_gates/<op>/checkpoints/<runId>.json` beside the gate ledger, the ledger's
+ * readers don't see it, and a run resumes from it at the checkout's own HEAD.
+ */
+
+import { describe, expect, test } from "vitest";
+import { withTestDir } from "@intentius/chant-test-utils";
+import { spawnSync } from "node:child_process";
+import { writeFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+  checkpointOutputs,
+  gateCheckpointDigest,
+  isCheckpointRunId,
+  parseGateCheckpoint,
+  readGateCheckpointText,
+  writeGateCheckpoint,
+  type GateCheckpoint,
+} from "./gate-checkpoint";
+import { appendGateResolution, readGateLedger } from "./gate-ledger";
+import { runOpLocally } from "../op/local-executor";
+import { gitGateLedgerPort } from "../op/gate";
+import { stepOutput } from "../op/step-output-ref";
+import type { ActivityFn } from "../op/activity-registry";
+import type { OpConfig } from "../op/types";
+
+function git(args: string[], cwd: string): string {
+  return spawnSync("git", args, { cwd, encoding: "utf-8" }).stdout ?? "";
+}
+
+function initRepo(dir: string): void {
+  git(["init", "-q", "-b", "main"], dir);
+  git(["config", "user.email", "test@chant.dev"], dir);
+  git(["config", "user.name", "Test"], dir);
+  writeFileSync(join(dir, "README.md"), "fixture\n");
+  git(["add", "README.md"], dir);
+  git(["commit", "-q", "-m", "init"], dir);
+}
+
+const checkpoint = (over: Partial<GateCheckpoint> = {}): GateCheckpoint => ({
+  version: 1, op: "upgrade", gate: "approve", runId: "run-1", commit: "c".repeat(40), outputs: { snap: { id: "s-1" } }, ...over,
+});
+
+describe("gate checkpoint files", () => {
+  test("the digest is over the JCS form, so key order and the file's layout don't move it", () => {
+    const a = checkpoint({ outputs: { snap: { id: "s-1", b: 1 } } });
+    const b = checkpoint({ outputs: { snap: { b: 1, id: "s-1" } } });
+    expect(gateCheckpointDigest(a)).toBe(gateCheckpointDigest(b));
+    expect(gateCheckpointDigest(a)).toMatch(/^jcs1-sha256:[0-9a-f]{64}$/);
+    expect(gateCheckpointDigest(checkpoint({ outputs: { snap: { id: "s-2" } } }))).not.toBe(gateCheckpointDigest(checkpoint()));
+  });
+
+  test("outputs are stored as JSON carries them, and one JSON can't hold is named", () => {
+    const outputs = new Map<string, unknown>([["a", { at: new Date(0), skip: undefined }], ["b", 1n]]);
+    expect(checkpointOutputs(outputs, ["a"])).toEqual({ outputs: { a: { at: "1970-01-01T00:00:00.000Z" } } });
+    expect(checkpointOutputs(outputs, ["a", "b"])).toEqual({ unstorable: "b" });
+  });
+
+  test("a run id that can't be a file name gets no checkpoint", () => {
+    expect(isCheckpointRunId("local-1760000000000")).toBe(true);
+    expect(isCheckpointRunId("../escape")).toBe(false);
+    expect(isCheckpointRunId(".hidden")).toBe(false);
+  });
+
+  test("a file that isn't a checkpoint reads as null", () => {
+    expect(parseGateCheckpoint("{")).toBeNull();
+    expect(parseGateCheckpoint(JSON.stringify({ ...checkpoint(), outputs: [] }))).toBeNull();
+  });
+
+  test("writes beside the gate ledger, which its readers don't see", async () => {
+    await withTestDir(async (dir) => {
+      initRepo(dir);
+      await writeGateCheckpoint(checkpoint(), { cwd: dir });
+      const text = await readGateCheckpointText("upgrade", "run-1", { cwd: dir });
+      expect(parseGateCheckpoint(text!)).toEqual(checkpoint());
+      expect(git(["ls-tree", "-r", "--name-only", "chant/lifecycle"], dir).trim()).toBe("_gates/upgrade/checkpoints/run-1.json");
+      expect(await readGateLedger("upgrade", { cwd: dir })).toEqual({ resolutions: [], pending: [], malformed: 0 });
+      expect(await readGateCheckpointText("upgrade", "run-2", { cwd: dir })).toBeNull();
+    });
+  });
+});
+
+describe("a resumed run on a real ledger", () => {
+  test("stops, is approved with the checkpoint's digest, and resumes at the gate at the same HEAD", async () => {
+    await withTestDir(async (dir) => {
+      initRepo(dir);
+      let snapshots = 0;
+      const applied: unknown[] = [];
+      const activities = new Map<string, ActivityFn>([
+        ["snapshot", async () => ({ id: `snap-${++snapshots}` })],
+        ["plan", async () => ({ planDigest: `jcs1-sha256:${"a".repeat(64)}` })],
+        ["apply", async (args) => {
+          applied.push(args.snapshot);
+          return {};
+        }],
+      ]);
+      const config: OpConfig = {
+        name: "upgrade",
+        overview: "upgrade",
+        phases: [
+          { name: "Prepare", steps: [{ kind: "activity", id: "snapshot", fn: "snapshot" }, { kind: "activity", id: "plan", fn: "plan" }] },
+          { name: "Gate", steps: [{ kind: "gate", gate: "approve", plan: stepOutput("plan", "planDigest"), resume: true }] },
+          { name: "Apply", steps: [{ kind: "activity", fn: "apply", args: { snapshot: stepOutput("snapshot", "id") } }] },
+        ],
+      };
+      const options = (runId: string, now: string) => ({ gates: gitGateLedgerPort({ cwd: dir }), cwd: dir, runId, now });
+
+      const first = await runOpLocally(config, activities, {}, undefined, options("run-1", "2026-10-12T12:00:00.000Z"));
+      expect(first.status).toBe("gated");
+      const digest = first.gate!.checkpointDigest!;
+      const stored = parseGateCheckpoint((await readGateCheckpointText("upgrade", "run-1", { cwd: dir }))!)!;
+      expect(stored.commit).toBe(git(["rev-parse", "HEAD"], dir).trim());
+      expect(gateCheckpointDigest(stored)).toBe(digest);
+
+      await appendGateResolution({
+        op: "upgrade", gate: "approve", resolvedBy: "alex", timestamp: "2026-10-12T12:05:00.000Z",
+        planDigest: first.gate!.planDigest!, checkpointDigest: digest,
+      }, { cwd: dir });
+
+      const second = await runOpLocally(config, activities, {}, undefined, options("run-2", "2026-10-12T12:10:00.000Z"));
+      expect(second.status).toBe("ok");
+      expect(second.resumed).toEqual({ gate: "approve", run: "run-1", checkpoint: digest });
+      expect(snapshots).toBe(1);
+      expect(applied).toEqual(["snap-1"]);
+    });
+  });
+});

package/src/lifecycle/gate-checkpoint.ts

@@ -0,0 +1,133 @@
+/**
+ * A gate's checkpoint (#3947): the step outputs a run held when it stopped at
+ * a gate that resumes, kept on `chant/lifecycle` at
+ * `_gates/<op>/checkpoints/<runId>.json`.
+ *
+ * The run writes the file just before it appends the pending fact, and puts
+ * the file's digest on that fact as `checkpointDigest`. `chant approve`
+ * copies the digest onto the approval, the way it copies the plan digest, and
+ * a seal covers it (`../workspace/trust/gate-seal.ts`). A later run that
+ * resumes at the gate reads the file back and checks it against the digest
+ * the approver saw, so a value pushed onto the branch after the approval is
+ * refused rather than carried into the steps after the gate.
+ *
+ * Only the outputs some step after the gate references are stored, worked
+ * out from the Op's references (`../op/gate-checkpoint.ts`). An output that
+ * an activity contract marks secret is never stored: the gate doesn't
+ * resume, and the next run starts at the first phase.
+ *
+ * Pure apart from the two git helpers at the bottom.
+ */
+
+import { canonicalJson } from "../effect-receipt";
+import { contentDigest } from "../content-digest";
+import { sortedJsonReplacer } from "../utils";
+import { readBlobFromPath, writeBlobToPath } from "./git";
+
+/** One gate checkpoint file. */
+export interface GateCheckpoint {
+  version: 1;
+  /** The op the gate belongs to. */
+  op: string;
+  /** The gate's name. */
+  gate: string;
+  /** The run that stopped at the gate, and the file's name. The pending fact names the same run. */
+  runId: string;
+  /** The commit the run ran at. A resumed run must be at the same one. */
+  commit: string;
+  /** The environment the run was started for (`--env`), when it named one. */
+  environment?: string;
+  /** The plan the run reached the gate with, when the gate binds one. */
+  planDigest?: string;
+  /** Step id to the output that step returned, for each step a later step references. */
+  outputs: Record<string, unknown>;
+}
+
+/** The prefix a checkpoint digest is written with: the JCS form of the file, hashed with SHA-256. */
+export const CHECKPOINT_DIGEST_PREFIX = "jcs1-sha256:";
+
+const CHECKPOINT_DIGEST_PATTERN = /^jcs1-sha256:[0-9a-f]{64}$/;
+
+/** Whether `raw` is a checkpoint digest this code wrote. */
+export function isCheckpointDigest(raw: unknown): raw is string {
+  return typeof raw === "string" && CHECKPOINT_DIGEST_PATTERN.test(raw);
+}
+
+/** The digest of a checkpoint: SHA-256 over its RFC 8785 (JCS) form. Throws when an output can't be put in JSON. */
+export function gateCheckpointDigest(checkpoint: GateCheckpoint): string {
+  return CHECKPOINT_DIGEST_PREFIX + contentDigest(canonicalJson(checkpoint)).slice("sha256:".length);
+}
+
+/**
+ * A run id is the checkpoint's file name, so it may hold only letters,
+ * digits, `.`, `_` and `-`, and may not start with a dot. A run named
+ * otherwise (a caller-chosen id with a slash in it) gets no checkpoint.
+ */
+export function isCheckpointRunId(runId: string): boolean {
+  return /^[A-Za-z0-9_-][A-Za-z0-9._-]*$/.test(runId) && runId.length <= 200;
+}
+
+/** Where the checkpoint of `runId` lives on `chant/lifecycle`: the directory and the file, as `writeBlobToPath` takes them. */
+export function gateCheckpointPath(op: string, runId: string): { dir: string; file: string } {
+  return { dir: `_gates/${op}/checkpoints`, file: `${runId}.json` };
+}
+
+/** The file's text: the checkpoint as JSON, keys sorted, one value per line. */
+export function gateCheckpointText(checkpoint: GateCheckpoint): string {
+  return `${JSON.stringify(checkpoint, sortedJsonReplacer, 2)}\n`;
+}
+
+/**
+ * Put `outputs` in the form a checkpoint stores: each value as JSON would
+ * carry it. Returns the step whose output JSON can't hold (a cycle, a bigint)
+ * instead, so the caller can say which one blocks the gate's resume.
+ */
+export function checkpointOutputs(outputs: ReadonlyMap<string, unknown>, ids: readonly string[]): { outputs: Record<string, unknown> } | { unstorable: string } {
+  const out: Record<string, unknown> = {};
+  for (const id of ids) {
+    if (!outputs.has(id)) continue;
+    const value = outputs.get(id);
+    try {
+      const text = JSON.stringify(value === undefined ? null : value);
+      const parsed: unknown = JSON.parse(text);
+      canonicalJson(parsed);
+      out[id] = parsed;
+    } catch {
+      return { unstorable: id };
+    }
+  }
+  return { outputs: out };
+}
+
+/** A checkpoint file's text read back, or null when it isn't one. */
+export function parseGateCheckpoint(text: string): GateCheckpoint | null {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(text);
+  } catch {
+    return null;
+  }
+  const r = raw as Partial<GateCheckpoint> | null;
+  if (
+    r === null || typeof r !== "object" || r.version !== 1 || typeof r.op !== "string" || typeof r.gate !== "string" ||
+    typeof r.runId !== "string" || typeof r.commit !== "string" ||
+    r.outputs === null || typeof r.outputs !== "object" || Array.isArray(r.outputs) ||
+    (r.environment !== undefined && typeof r.environment !== "string") ||
+    (r.planDigest !== undefined && typeof r.planDigest !== "string")
+  ) {
+    return null;
+  }
+  return r as GateCheckpoint;
+}
+
+/** Write a checkpoint to the local `chant/lifecycle` branch. Does not push: the pending fact appended after it does. */
+export async function writeGateCheckpoint(checkpoint: GateCheckpoint, opts?: { cwd?: string }): Promise<void> {
+  const { dir, file } = gateCheckpointPath(checkpoint.op, checkpoint.runId);
+  await writeBlobToPath(dir, file, gateCheckpointText(checkpoint), `Gate checkpoint for ${checkpoint.gate}`, opts);
+}
+
+/** The text of `runId`'s checkpoint for `op`, or null when there is none. */
+export async function readGateCheckpointText(op: string, runId: string, opts?: { cwd?: string }): Promise<string | null> {
+  const { dir, file } = gateCheckpointPath(op, runId);
+  return readBlobFromPath(dir, file, opts);
+}

package/src/lifecycle/gate-ledger.ts

@@ -138,6 +138,12 @@ export interface GateResolutionRecord {
    * such a record proves is that somebody approved *something*.
    */
   planDigest?: string;
+  /**
+   * The checkpoint this approval lets a run resume from (#3947), copied off
+   * the pending fact it answers. Set only on an approval of a gate that
+   * resumes (`resume: true`) whose run stored a checkpoint. A seal covers it.
+   */
+  checkpointDigest?: string;
   /**
    * The environment this approval is for (#2574), copied off the pending fact
    * it answers. Set for a component gate, whose ledger is keyed by component
@@ -204,6 +210,33 @@ export interface GateResolutionRecord {
    * `constrains` names the gate back (`gate:<op>/<gate>`).
    */
   answer?: GateAnswerRef;
+  /**
+   * The line this approval was carried from (#3949): an approval recorded
+   * under one of the gate's aliases, which a run counted toward the gate and
+   * wrote again under its new name. `op`, `gate` and `timestamp` name that
+   * line; `checkpointDigest` is the one it carried, if any, since a seal
+   * signs it. `resolvedBy`, the plan, the environment and the seal are the
+   * original's, and the seal verifies against the names in here. This
+   * record's own `timestamp` is when it was carried.
+   */
+  carriedFrom?: GateCarriedFrom;
+}
+
+/** Where a carried approval came from (#3949): the original line's op, gate and time, and its checkpoint digest when it had one. */
+export interface GateCarriedFrom {
+  op: string;
+  gate: string;
+  timestamp: string;
+  checkpointDigest?: string;
+}
+
+/** Whether `raw` is a {@link GateCarriedFrom}. */
+export function isGateCarriedFrom(raw: unknown): raw is GateCarriedFrom {
+  const c = raw as Partial<GateCarriedFrom> | null;
+  return (
+    !!c && typeof c === "object" && !Array.isArray(c) && typeof c.op === "string" && typeof c.gate === "string" &&
+    typeof c.timestamp === "string" && (c.checkpointDigest === undefined || typeof c.checkpointDigest === "string")
+  );
 }
 
 /** A gate approval's seal (#3163): who signed, the key's fingerprint (reported, never trusted), and the armored signature. */
@@ -211,6 +244,12 @@ export interface GateApprovalSeal {
   signer: string;
   key: string;
   signature: string;
+  /**
+   * The seal's version (#3947). `2` on a seal over an approval that carries a
+   * `checkpointDigest`, whose payload signs the digest as one more line.
+   * Absent on every other seal, which is version 1.
+   */
+  version?: 2;
 }
 
 export type GateResolutionInput = Omit<GateResolutionRecord, "version" | "kind">;
@@ -278,6 +317,16 @@ export interface PendingGateRecord {
    * binds one since #2574.
    */
   planDigest?: string;
+  /**
+   * The digest of the checkpoint the run stored when it stopped here (#3947),
+   * on a gate that resumes (`resume: true`). The file is at
+   * `_gates/<op>/checkpoints/<runId>.json` (`./gate-checkpoint.ts`). `chant
+   * approve` copies it onto the approval, and a run resumes at this gate only
+   * from a checkpoint that matches it. Absent when the gate doesn't resume,
+   * or when its run could not store one, such as when an output it needs is
+   * secret.
+   */
+  checkpointDigest?: string;
   /**
    * The environment the run reached this gate in (#2574). Set by the
    * component driver, whose gate ledger is keyed by component, so pending
@@ -470,6 +519,12 @@ export function parseGateLedger(
         malformed++;
         continue;
       }
+      // #3947: and for the checkpoint an approval lets a run resume from.
+      const rawCheckpoint: unknown = (parsed as { checkpointDigest?: unknown }).checkpointDigest;
+      if (rawCheckpoint !== undefined && typeof rawCheckpoint !== "string") {
+        malformed++;
+        continue;
+      }
       if (parsed.kind === "pending") {
         if (typeof parsed.expiresAt !== "string") {
           malformed++;
@@ -488,6 +543,12 @@ export function parseGateLedger(
         malformed++;
         continue;
       }
+      // #3949: a carried approval's seal is checked against the line it cites, so the citation must be whole.
+      const rawCarried: unknown = (parsed as { carriedFrom?: unknown }).carriedFrom;
+      if (rawCarried !== undefined && !isGateCarriedFrom(rawCarried)) {
+        malformed++;
+        continue;
+      }
       resolutions.push(parsed as GateResolutionRecord);
     } catch {
       malformed++;

package/src/lifecycle/run-ledger.ts

@@ -87,6 +87,8 @@ export function buildRunRecord(
     gate?: OpRunRecord["gate"];
     point?: OpRunRecord["point"];
     steward?: string;
+    /** The gate the run resumed at, for a run that resumed (#3947). */
+    resumed?: OpRunRecord["resumed"];
     /** Each phase's wall-clock time, by name, as the executor measured it. */
     phaseDurations?: Record<string, number>;
   },
@@ -112,6 +114,7 @@ export function buildRunRecord(
       ...(record.refusal !== undefined ? { refusal: record.refusal } : {}),
       ...(record.point ? { point: record.point } : {}),
       ...(record.gate ? { gate: record.gate } : {}),
+      ...(record.resumed ? { resumed: record.resumed } : {}),
     });
     if (record.outcome) outcomes[record.outcome.name] = record.outcome.value;
   }
@@ -134,6 +137,7 @@ export function buildRunRecord(
     ...(times.gate ? { gate: times.gate } : {}),
     ...(times.point ? { point: times.point } : {}),
     ...(times.steward ? { steward: times.steward } : {}),
+    ...(times.resumed ? { resumed: times.resumed } : {}),
   };
 }
 

package/src/lint/rules/op/index.ts

@@ -14,6 +14,8 @@ import { ops012 } from "./ops012-activity-contract";
 import { ops013 } from "./ops013-step-output-ref";
 import { ops014 } from "./ops014-converge-rule-refusals";
 import { ops015 } from "./ops015-gate-approval";
+import { ops016 } from "./ops016-gate-resume";
+import { ops017Check } from "./ops017-gate-alias";
 import { sys010Check } from "./sys010-key-over-plain-http";
 import type { DecideBackend } from "../../../op/decide-config";
 
@@ -21,18 +23,22 @@ export { ops012 } from "./ops012-activity-contract";
 export { ops013 } from "./ops013-step-output-ref";
 export { ops014 } from "./ops014-converge-rule-refusals";
 export { ops015 } from "./ops015-gate-approval";
+export { ops016 } from "./ops016-gate-resume";
+export { ops017, ops017Check, workspaceIdentityGates } from "./ops017-gate-alias";
 export { sys010, sys010Check } from "./sys010-key-over-plain-http";
 
 export interface CoreOpCheckOptions {
   /** `decide.backends` from the project's chant.config, for SYS010 (#2828). */
   decideBackends?: Record<string, Pick<DecideBackend, "url" | "key">>;
+  /** The workspace's `identity.gates`, gate to class, for OPS017 (#3949): `workspaceIdentityGates`' answer. */
+  identityGates?: ReadonlyMap<string, string | null>;
 }
 
 /**
  * Core's own post-synth checks over the Op model: OPS012, OPS013, OPS014,
- * OPS015, and SYS010 over the `decide` steps and the configured decide
- * backends.
+ * OPS015, OPS016, OPS017 over the workspace's `identity.gates`, and SYS010
+ * over the `decide` steps and the configured decide backends.
  */
 export function coreOpChecks(opts: CoreOpCheckOptions = {}): PostSynthCheck[] {
-  return [ops012, ops013, ops014, ops015, sys010Check(opts.decideBackends)];
+  return [ops012, ops013, ops014, ops015, ops016, ops017Check(opts.identityGates), sys010Check(opts.decideBackends)];
 }

package/src/lint/rules/op/ops016-gate-resume.test.ts

@@ -0,0 +1,53 @@
+/**
+ * OPS016 (#3947) — a gate with `resume: true`, checked over the build output.
+ */
+
+import { describe, test, expect } from "vitest";
+import { z } from "zod";
+import type { PostSynthContext } from "../../post-synth";
+import { DECLARABLE_MARKER } from "../../../declarable";
+import { activityContract } from "../../../op/activity-contract";
+import { stepOutput } from "../../../op/step-output-ref";
+import { ops016 } from "./ops016-gate-resume";
+
+function ctxWith(phases: unknown[], activityContracts?: PostSynthContext["activityContracts"]): PostSynthContext {
+  const entities = new Map<string, unknown>([["upgrade", {
+    [DECLARABLE_MARKER]: true,
+    entityType: "Chant::Op",
+    lexicon: "chant",
+    kind: "resource",
+    props: { name: "upgrade", overview: "test", phases },
+    attributes: {},
+  }]]);
+  return {
+    outputs: new Map([["chant", ""]]),
+    entities: entities as Map<string, never>,
+    buildResult: { outputs: new Map([["chant", ""]]), entities: entities as Map<string, never>, warnings: [], errors: [], sourceFileCount: 1 },
+    ...(activityContracts ? { activityContracts } : {}),
+  };
+}
+
+const phases = (gate: Record<string, unknown>) => [
+  { name: "Prepare", steps: [{ kind: "activity", id: "token", fn: "mintToken" }, { kind: "activity", id: "plan", fn: "planIt" }] },
+  { name: "Gate", steps: [{ kind: "gate", gate: "approve", plan: stepOutput("plan", "planDigest"), resume: true, ...gate }] },
+  { name: "Apply", steps: [{ kind: "activity", fn: "applyIt", args: { token: stepOutput("token", "value") } }] },
+];
+
+describe("OPS016", () => {
+  test("a gate that can resume passes", () => {
+    expect(ops016.check(ctxWith(phases({})))).toEqual([]);
+  });
+
+  test("a gate that asks a decision point is refused, naming the op, phase and gate", () => {
+    const [diag] = ops016.check(ctxWith(phases({ point: "prod-apply" })));
+    expect(diag?.checkId).toBe("OPS016");
+    expect(diag?.severity).toBe("error");
+    expect(diag?.message).toBe('Op "upgrade", phase "Gate", gate:approve: a gate that asks a decision point can\'t resume');
+  });
+
+  test("a secret output read after the gate is refused, from the contracts the build loaded", () => {
+    const contracts = new Map([["mintToken", activityContract("mintToken", z.object({}), z.object({ value: z.string() }), { secret: ["value"] })]]);
+    const [diag] = ops016.check(ctxWith(phases({}), contracts));
+    expect(diag?.message).toContain(`can't resume: step "token"'s output "value" is secret`);
+  });
+});

package/src/lint/rules/op/ops016-gate-resume.ts

@@ -0,0 +1,48 @@
+/**
+ * OPS016: a gate that resumes (`resume: true`, #3947) can. It sits at the top
+ * of a main phase, asks no decision point, is not in an Op with a
+ * `workLease`, names a plan step that runs before it when its plan is a
+ * reference, and no step after it reads an output an activity contract marks
+ * secret, since a checkpoint never stores one.
+ *
+ * The run itself treats a gate that fails one of these as one that doesn't
+ * resume. This check makes that a build error instead of a quiet re-run from
+ * the first phase. Contracts come from the same merged map OPS013 uses.
+ */
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "../../post-synth";
+import { mergeActivityContracts, type ActivityContract } from "../../../op";
+import type { OpConfig } from "../../../op";
+import { validateGateResume } from "../../../op/gate-checkpoint";
+import * as contracts from "../../../op/activities/activity-contracts";
+import { isOpEntity } from "./support";
+
+const CONTRACTS: Map<string, ActivityContract> = new Map(
+  Object.values(contracts).map((c) => [c.name, c]),
+);
+
+export const ops016: PostSynthCheck = {
+  id: "OPS016",
+  description:
+    "A gate with resume: true can resume: at the top of a main phase, no decision point or workLease, a plan step before it, and no secret output read after it",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+    const activeContracts = mergeActivityContracts(CONTRACTS, ctx.activityContracts);
+    for (const [entityKey, entity] of ctx.entities) {
+      if (!isOpEntity(entity)) continue;
+      const rec = entity as unknown as Record<string, unknown>;
+      const props = ((entity as { props?: Record<string, unknown> }).props ?? {}) as unknown as OpConfig;
+      if (typeof props.name !== "string" || !Array.isArray(props.phases)) continue;
+      for (const issue of validateGateResume(props, activeContracts)) {
+        diagnostics.push({
+          checkId: "OPS016",
+          severity: "error",
+          message: `Op "${issue.opName}", phase "${issue.phase}", ${issue.fn}: ${issue.message}`,
+          entity: entityKey,
+          lexicon: typeof rec.lexicon === "string" ? rec.lexicon : undefined,
+        });
+      }
+    }
+    return diagnostics;
+  },
+};

package/src/lint/rules/op/ops017-gate-alias.test.ts

@@ -0,0 +1,85 @@
+/**
+ * OPS017 (#3949) — a gate's aliases, checked over every Op in the build and
+ * the workspace's `identity.gates`.
+ */
+
+import { afterEach, describe, expect, test } from "vitest";
+import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
+import { rm } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import type { PostSynthContext } from "../../post-synth";
+import { DECLARABLE_MARKER } from "../../../declarable";
+import { ops017, ops017Check, workspaceIdentityGates } from "./ops017-gate-alias";
+
+const PLAN = `jcs1-sha256:${"a".repeat(64)}`;
+
+function ctxWith(ops: Array<{ name: string; phases: unknown[] }>): PostSynthContext {
+  const entities = new Map<string, unknown>(ops.map((op) => [op.name, {
+    [DECLARABLE_MARKER]: true,
+    entityType: "Chant::Op",
+    lexicon: "chant",
+    kind: "resource",
+    props: { name: op.name, overview: "test", phases: op.phases },
+    attributes: {},
+  }]));
+  return {
+    outputs: new Map([["chant", ""]]),
+    entities: entities as Map<string, never>,
+    buildResult: { outputs: new Map([["chant", ""]]), entities: entities as Map<string, never>, warnings: [], errors: [], sourceFileCount: 1 },
+  };
+}
+
+const merged = (gate: Record<string, unknown> = {}) => ({
+  name: "upgrade",
+  phases: [{ name: "Wave 1", steps: [{ kind: "gate", gate: "approve-tier-1", plan: PLAN, aliases: [{ op: "upgrade-tier-1", gate: "approve" }], ...gate }] }],
+});
+const tier1 = { name: "upgrade-tier-1", phases: [{ name: "Gate", steps: [{ kind: "gate", gate: "approve" }] }] };
+
+const dirs: string[] = [];
+afterEach(async () => {
+  for (const d of dirs.splice(0)) await rm(d, { recursive: true, force: true });
+});
+
+function workspace(gates: Record<string, { class?: string }>): string {
+  const dir = mkdtempSync(join(tmpdir(), "chant-ops017-"));
+  dirs.push(dir);
+  mkdirSync(join(dir, ".git"));
+  writeFileSync(join(dir, "chant.workspace.json"), JSON.stringify({ name: "acme", schema: 1, members: [], identity: { gates } }));
+  return dir;
+}
+
+describe("OPS017", () => {
+  test("an alias of a gate that is gone passes", () => {
+    expect(ops017.check(ctxWith([merged()]))).toEqual([]);
+  });
+
+  test("an alias of a gate still in the build is an error", () => {
+    const [d] = ops017.check(ctxWith([merged(), tier1]));
+    expect(d).toMatchObject({ checkId: "OPS017", severity: "error", entity: "upgrade" });
+    expect(d!.message).toBe(
+      'Op "upgrade", phase "Wave 1", gate:approve-tier-1: alias upgrade-tier-1/approve is still a gate; remove that gate, or this alias, so one approval doesn\'t answer two gates',
+    );
+  });
+
+  test("aliases on a gate with no plan are an error", () => {
+    expect(ops017.check(ctxWith([merged({ plan: undefined })]))[0]!.message).toContain("aliases need a plan");
+  });
+
+  test("a gate that drops its alias's identity.gates rule is an error", async () => {
+    const check = async (gates: Record<string, { class?: string }>) => {
+      const ctx = ctxWith([merged()]);
+      return ops017Check(await workspaceIdentityGates(workspace(gates), ctx.entities)).check(ctx);
+    };
+    expect((await check({ approve: {} }))[0]!.message).toContain("identity.gates names its alias approve");
+    expect((await check({ approve: { class: "human" }, "approve-tier-1": {} }))[0]!.message).toContain("must keep its alias's class");
+    expect(await check({ approve: {}, "approve-tier-1": {} })).toEqual([]);
+  });
+
+  test("the identity rules are read only when an Op has aliases, and only in a workspace", async () => {
+    const dir = workspace({ approve: {} });
+    expect(await workspaceIdentityGates(dir, ctxWith([tier1]).entities)).toBeUndefined();
+    expect(await workspaceIdentityGates(tmpdir(), ctxWith([merged()]).entities)).toBeUndefined();
+    expect(await workspaceIdentityGates(dir, ctxWith([merged()]).entities)).toEqual(new Map([["approve", null]]));
+  });
+});