@intentius/chant 0.124.24 → 0.124.26

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

@@ -0,0 +1,89 @@
+/**
+ * OPS017: a gate's aliases (#3949) can stand. An alias admits approvals of
+ * the plan a run planned, so the gate must bind a `plan`, and a gate that
+ * asks a decision point takes none. An alias must not name a gate that still
+ * exists in the build, or one approval would answer two gates, and two gates
+ * must not claim one alias. When the workspace's `identity.gates` names an
+ * alias, the new gate must be named too, with the alias's class, or
+ * approvals that needed a seal would count without one.
+ *
+ * The identity rules come from the caller, as SYS010's decide backends do:
+ * `chant build` and `chant lint` read them with
+ * {@link workspaceIdentityGates}, which loads workspace code only when an Op
+ * has aliases and the project sits in a workspace. Without them that part
+ * is skipped.
+ */
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "../../post-synth";
+import type { OpConfig } from "../../../op";
+import { gateStepsOf, validateGateAliases } from "../../../op/gate-alias";
+import { findWorkspaceRoot } from "../../../project-root";
+import { isOpEntity } from "./support";
+
+/** The Op configs among a build's entities, each with its entity key and lexicon. */
+function opsOf(entities: Iterable<[string, unknown]>): Array<{ entityKey: string; lexicon?: string; config: OpConfig }> {
+  const ops: Array<{ entityKey: string; lexicon?: string; config: OpConfig }> = [];
+  for (const [entityKey, entity] of entities) {
+    if (!isOpEntity(entity as never)) continue;
+    const rec = entity 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;
+    ops.push({ entityKey, ...(typeof rec.lexicon === "string" ? { lexicon: rec.lexicon } : {}), config: props });
+  }
+  return ops;
+}
+
+const hasAliases = (ops: ReadonlyArray<{ config: OpConfig }>): boolean =>
+  ops.some(({ config }) => gateStepsOf(config).some(({ step }) => step.aliases !== undefined));
+
+/**
+ * The gates the workspace around `projectDir` names under `identity.gates`,
+ * each with its class (null for any signer), for OPS017. Undefined when no
+ * Op among `entities` has aliases, outside a workspace, or when the
+ * declaration can't be read, which `chant workspace check` reports. The
+ * workspace modules load only past the first two checks, so a level-0
+ * build loads none.
+ */
+export async function workspaceIdentityGates(
+  projectDir: string,
+  entities: Iterable<[string, unknown]>,
+): Promise<Map<string, string | null> | undefined> {
+  if (!hasAliases(opsOf(entities))) return undefined;
+  const found = findWorkspaceRoot(projectDir);
+  if (!found) return undefined;
+  try {
+    const { readDeclaration } = await import("../../../workspace/declaration");
+    const { workingTree } = await import("../../../workspace/tree");
+    const gates = readDeclaration(workingTree(found.dir)).identity?.gates ?? {};
+    return new Map(Object.values(gates).map((g) => [g.gate, g.class]));
+  } catch {
+    return undefined;
+  }
+}
+
+/** OPS017, judging `identity.gates` by `identityGates` when given. */
+export function ops017Check(identityGates?: ReadonlyMap<string, string | null>): PostSynthCheck {
+  return {
+    id: "OPS017",
+    description:
+      "A gate's aliases need a plan and no decision point, must not name a gate that still exists or another gate's alias, and keep any identity.gates rule an alias had",
+
+    check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+      const ops = opsOf(ctx.entities);
+      if (!hasAliases(ops)) return [];
+      const byName = new Map(ops.map((o) => [o.config.name, o]));
+      return validateGateAliases(ops.map((o) => o.config), identityGates).map((issue) => {
+        const op = byName.get(issue.opName);
+        return {
+          checkId: "OPS017",
+          severity: "error",
+          message: `Op "${issue.opName}", phase "${issue.phase}", gate:${issue.gate}: ${issue.message}`,
+          ...(op ? { entity: op.entityKey } : {}),
+          ...(op?.lexicon ? { lexicon: op.lexicon } : {}),
+        };
+      });
+    },
+  };
+}
+
+/** OPS017 without the workspace's identity rules. */
+export const ops017: PostSynthCheck = ops017Check();

package/src/op/activity-contract.ts

@@ -89,6 +89,26 @@ export interface ActivityContract<Args = unknown, Return = unknown> {
    * stack members internally) simply declares none.
    */
   entities?: string[];
+  /**
+   * What the activity returns that is secret (#3947): `true` for the whole
+   * return value, or the names of its top-level fields that are. A gate that
+   * resumes never stores a secret output in its checkpoint, so a gate whose
+   * later steps reference one doesn't resume, and OPS016 says so at build.
+   */
+  secret?: true | string[];
+}
+
+/**
+ * Whether a reference into `contract`'s return value at `path` reads a value
+ * the contract marks secret (#3947). A whole-value reference reads every
+ * field, so it is secret when any field is.
+ */
+export function readsSecretOutput(contract: Pick<ActivityContract, "secret"> | undefined, path?: string): boolean {
+  const secret = contract?.secret;
+  if (secret === undefined) return false;
+  if (secret === true) return true;
+  if (!path) return secret.length > 0;
+  return secret.includes(path.split(".")[0]!);
 }
 
 /** Declare an activity contract. */
@@ -96,7 +116,7 @@ export function activityContract<ArgsSchema extends z.ZodTypeAny, ReturnSchema e
   name: string,
   args: ArgsSchema,
   returns?: ReturnSchema,
-  opts?: { entities?: string[] },
+  opts?: { entities?: string[]; secret?: true | string[] },
 ): ActivityContract<z.infer<ArgsSchema>, ReturnSchema extends z.ZodTypeAny ? z.infer<ReturnSchema> : unknown> {
   return {
     [CONTRACT_BRAND]: true,
@@ -104,6 +124,7 @@ export function activityContract<ArgsSchema extends z.ZodTypeAny, ReturnSchema e
     args,
     ...(returns ? { returns } : {}),
     ...(opts?.entities && opts.entities.length > 0 ? { entities: opts.entities } : {}),
+    ...(opts?.secret === true || (Array.isArray(opts?.secret) && opts.secret.length > 0) ? { secret: opts!.secret } : {}),
   } as ActivityContract<z.infer<ArgsSchema>, ReturnSchema extends z.ZodTypeAny ? z.infer<ReturnSchema> : unknown>;
 }
 

package/src/op/builders.ts

@@ -5,6 +5,7 @@ import { isEffectReceipt, type EffectReceiptDeclaration } from "../effect-receip
 import { receiptCheckInput } from "./receipt-store";
 import { gateApprovalProblems } from "./gate-approval";
 import { gatePointProblems } from "./gate-point";
+import { gateAliasProblems } from "./gate-alias";
 import { makeOutProxy, stepOutput, type StepOutputRef, type WithStepRefs } from "./step-output-ref";
 import type { ChantBuildArgs } from "./activities/build";
 import type { ShellCmdArgs } from "./activities/shell";
@@ -135,10 +136,23 @@ export function activity(
  * The point's deciders and quorum decide, `chant workspace points answer`
  * answers an open question, and the run passes on the answer. See
  * {@link GateStep.point}.
+ *
+ * Pass `aliases` to keep the approvals recorded under the gate's old names
+ * after an Op is restructured (#3949): `gate("approve-tier-1", { plan:
+ * plan.out.planDigest, aliases: [{ op: "upgrade-tier-1", gate: "approve" }] })`.
+ * A gate with aliases must bind a plan. See {@link GateStep.aliases}.
  */
 export function gate(
   name: string,
-  opts?: { timeout?: string; description?: string; plan?: GateStep["plan"]; approval?: GateStep["approval"]; point?: GateStep["point"] },
+  opts?: {
+    timeout?: string;
+    description?: string;
+    plan?: GateStep["plan"];
+    approval?: GateStep["approval"];
+    point?: GateStep["point"];
+    resume?: boolean;
+    aliases?: GateStep["aliases"];
+  },
 ): GateStep {
   if (opts?.approval !== undefined) {
     const problems = gateApprovalProblems(opts.approval);
@@ -148,6 +162,10 @@ export function gate(
     const problems = gatePointProblems(opts.point, opts.approval !== undefined);
     if (problems.length > 0) throw new Error(`gate(${JSON.stringify(name)}): ${problems[0]}`);
   }
+  if (opts?.aliases !== undefined) {
+    const problems = gateAliasProblems(opts.aliases, { plan: opts.plan, point: opts.point });
+    if (problems.length > 0) throw new Error(`gate(${JSON.stringify(name)}): ${problems[0]}`);
+  }
   return {
     kind: "gate",
     gate: name,
@@ -156,6 +174,8 @@ export function gate(
     ...(opts?.plan !== undefined ? { plan: opts.plan } : {}),
     ...(opts?.approval !== undefined ? { approval: opts.approval } : {}),
     ...(opts?.point !== undefined ? { point: opts.point } : {}),
+    ...(opts?.resume ? { resume: true } : {}),
+    ...(opts?.aliases !== undefined && opts.aliases.length > 0 ? { aliases: opts.aliases.map((a) => ({ ...(a.op !== undefined ? { op: a.op } : {}), gate: a.gate })) } : {}),
   };
 }
 

package/src/op/effect-step.test.ts

@@ -12,7 +12,8 @@
  *   differing receipts as findings and never writes.
  */
 import { describe, test, expect, vi } from "vitest";
-import { EffectReceipt, receiptExpectation, EXISTENCE_EXPECTATION } from "../effect-receipt";
+import { EffectReceipt, receiptExpectation, EXISTENCE_EXPECTATION, declaredExpectation, withStepOutputs } from "../effect-receipt";
+import { stepOutput } from "./step-output-ref";
 import { INTRINSIC_MARKER, type Intrinsic } from "../intrinsic";
 import { effect, phase } from "./builders";
 import {
@@ -324,3 +325,96 @@ describe("runOpLocally — effect steps", () => {
     ).rejects.toThrow(/parallel phase/);
   });
 });
+
+// ── Step outputs inside an effect (#3948) ───────────────────────────────────
+
+describe("runOpLocally — an effect's nested steps read step outputs (#3948)", () => {
+  function refOp(): OpConfig {
+    return {
+      name: "seed-op",
+      overview: "",
+      phases: [
+        phase("Pick", [{ kind: "activity", fn: "pick", id: "pick" }]),
+        phase("Seed", [effect(seeded, [step("runSeed", { file: stepOutput("pick", "file") })])]),
+      ],
+    };
+  }
+
+  test("the resolved value reaches the nested step, and the receipt holds its digest", async () => {
+    const { store, values } = memStore();
+    const received: unknown[] = [];
+    let file = "a.sql";
+    const activities = activityMap(store, {
+      pick: async () => ({ file }),
+      runSeed: async (args) => void received.push(args),
+    });
+    const first = await runOpLocally(refOp(), activities, PROFILES);
+    expect(first.status).toBe("ok");
+    expect(received).toEqual([{ file: "a.sql" }]);
+    const written = values.get("seeded")!;
+    expect(written).not.toBe(receiptExpectation(seeded));
+    expect(declaredExpectation(written)).toBe(receiptExpectation(seeded));
+
+    // The same value: the receipt matches and the effect is skipped.
+    const second = await runOpLocally(refOp(), activities, PROFILES);
+    expect(received).toHaveLength(1);
+    expect(second.records.find((r) => r.fn === "receiptRead")?.outcome).toEqual({ name: "EffectApplied", value: true });
+
+    // A changed value fires the effect again, though the declared inputs did not change.
+    file = "b.sql";
+    await runOpLocally(refOp(), activities, PROFILES);
+    expect(received).toEqual([{ file: "a.sql" }, { file: "b.sql" }]);
+    expect(values.get("seeded")).not.toBe(written);
+  });
+
+  test("a receipt written before the effect read outputs re-fires the effect once", async () => {
+    const { store, values } = memStore({ seeded: receiptExpectation(seeded) });
+    const ran = vi.fn();
+    const activities = activityMap(store, { pick: async () => ({ file: "a.sql" }), runSeed: async () => { ran(); } });
+    await runOpLocally(refOp(), activities, PROFILES);
+    expect(ran).toHaveBeenCalledTimes(1);
+    expect(declaredExpectation(values.get("seeded")!)).toBe(receiptExpectation(seeded));
+  });
+
+  test("an existence receipt takes no outputs: it says the effect ran once", async () => {
+    const booted = EffectReceipt("booted", { effect: "bootstrap", flavor: "existence" });
+    const config: OpConfig = {
+      name: "boot-op",
+      overview: "",
+      phases: [
+        phase("Pick", [{ kind: "activity", fn: "pick", id: "pick" }]),
+        phase("Boot", [effect(booted, [step("boot", { file: stepOutput("pick", "file") })])]),
+      ],
+    };
+    const { store, values } = memStore();
+    const activities = activityMap(store, { pick: async () => ({ file: "a.sql" }), boot: async () => {} });
+    await runOpLocally(config, activities, PROFILES);
+    expect(values.get("booted")).toBe(EXISTENCE_EXPECTATION);
+  });
+
+  test("an effect in onFailure whose source step did not complete is skipped whole (A6)", async () => {
+    const config: OpConfig = {
+      name: "seed-op",
+      overview: "",
+      phases: [phase("Pick", [{ kind: "activity", fn: "pick", id: "pick" }])],
+      onFailure: [phase("Undo", [effect(seeded, [step("unseed", { file: stepOutput("pick", "file") })])])],
+    };
+    const { store, writes } = memStore();
+    const ran = vi.fn();
+    const activities = activityMap(store, { pick: async () => { throw new Error("boom"); }, unseed: async () => { ran(); } });
+    const failure = (await runOpLocally(config, activities, PROFILES).catch((e) => e)) as OpRunFailure;
+    expect(failure).toBeInstanceOf(OpRunFailure);
+    expect(ran).not.toHaveBeenCalled();
+    expect(writes).toEqual([]);
+    const skipped = failure.result.records.find((r) => r.fn === "effect:seeded");
+    expect(skipped?.status).toBe("skipped");
+    expect(skipped?.refusal).toMatch(/step "pick" did not complete/);
+  });
+
+  test("receiptStaleness compares the declared part of a value written with outputs", async () => {
+    const expected = receiptExpectation(seeded);
+    const { store } = memStore({ seeded: withStepOutputs(expected, "sha256:abc") });
+    const { receiptStaleness } = receiptActivities(store);
+    expect(await receiptStaleness({ receipts: [receiptCheckInput(seeded)] })).toEqual({ stale: false, findings: [] });
+  });
+});

package/src/op/gate-alias.e2e.test.ts

@@ -0,0 +1,78 @@
+/**
+ * #3949 against a real `chant/lifecycle` branch: an approval recorded under
+ * a per-tier Op's gate passes the merged Op's gate that lists it as an
+ * alias. The run reads the old Op's ledger file, writes the carried line to
+ * its own, and the next run passes on that line alone.
+ */
+
+import { afterAll, beforeAll, describe, expect, test } from "vitest";
+import { cleanScratch, commitAll, git, repo } from "../workspace/__fixtures__/contract-repo";
+import { appendGateResolution, appendPendingGate, readGateLedger } from "../lifecycle/gate-ledger";
+import { runOpLocally } from "./local-executor";
+import { gitGateLedgerPort } from "./gate";
+import { stepOutput } from "./step-output-ref";
+import type { ActivityFn } from "./activity-registry";
+import type { OpConfig } from "./types";
+
+const PLAN = `jcs1-sha256:${"a".repeat(64)}`;
+
+let root: string;
+beforeAll(() => {
+  root = repo({ "chant.config.json": "{}\n" }, false);
+  git(root, "config", "user.name", "Gate Test");
+  git(root, "config", "user.email", "gate@example.com");
+  commitAll(root, "c0");
+});
+afterAll(cleanScratch);
+
+const applied: string[] = [];
+const ACTIVITIES = new Map<string, ActivityFn>([
+  ["plan", async () => ({ planDigest: PLAN })],
+  ["apply", async (args) => (applied.push(String((args as { tier: string }).tier)), { ok: true })],
+]);
+
+const merged: OpConfig = {
+  name: "upgrade",
+  overview: "upgrade every tier, one wave each",
+  phases: [
+    { name: "Plan", steps: [{ kind: "activity", id: "plan", fn: "plan" }] },
+    {
+      name: "Wave 1",
+      steps: [{ kind: "gate", gate: "approve-tier-1", plan: stepOutput("plan", "planDigest"), aliases: [{ op: "upgrade-tier-1", gate: "approve" }] }],
+    },
+    { name: "Apply 1", steps: [{ kind: "activity", fn: "apply", args: { tier: "1" } }] },
+  ],
+};
+
+describe("a gate alias on a real ledger", () => {
+  test("the merged Op passes on the old Op's approval, and keeps passing on the carried line", async () => {
+    const now = Date.now();
+    const iso = (s: number) => new Date(now + s * 1000).toISOString();
+    await appendPendingGate(
+      { op: "upgrade-tier-1", gate: "approve", timestamp: iso(-60), expiresAt: iso(3600), planDigest: PLAN, runId: "old-run" },
+      { cwd: root },
+    );
+    await appendGateResolution({ op: "upgrade-tier-1", gate: "approve", resolvedBy: "alice", timestamp: iso(-30), planDigest: PLAN }, { cwd: root });
+
+    const port = gitGateLedgerPort({ cwd: root });
+    const first = await runOpLocally(merged, ACTIVITIES, {}, undefined, { cwd: root, gates: port, runId: "run-1" });
+    expect(first.status).toBe("ok");
+    expect(first.records.find((r) => r.fn === "gate:approve-tier-1")?.approval).toMatchObject({ resolvedBy: "alice", via: "alias" });
+
+    const ledger = await readGateLedger("upgrade", { cwd: root });
+    expect(ledger.resolutions).toHaveLength(1);
+    expect(ledger.resolutions[0]).toMatchObject({
+      op: "upgrade",
+      gate: "approve-tier-1",
+      resolvedBy: "alice",
+      planDigest: PLAN,
+      carriedFrom: { op: "upgrade-tier-1", gate: "approve", timestamp: iso(-30) },
+    });
+
+    const second = await runOpLocally(merged, ACTIVITIES, {}, undefined, { cwd: root, gates: port, runId: "run-2" });
+    expect(second.status).toBe("ok");
+    expect(second.records.find((r) => r.fn === "gate:approve-tier-1")?.approval?.via).toBeUndefined();
+    expect((await readGateLedger("upgrade", { cwd: root })).resolutions).toHaveLength(1);
+    expect(applied).toEqual(["1", "1"]);
+  });
+});