@intentius/chant 0.56.0 → 0.58.0

package/src/op/generate-pipeline.ts

@@ -16,7 +16,7 @@
  * `resolveComponentGraph`; each `ScheduledOpSpec` is generated independently.
  */
 
-import { discoverOps } from "./discover";
+import { discoverOps, type DiscoveredOp } from "./discover";
 import {
   isLexiconPlugin,
   type LexiconPlugin,
@@ -46,6 +46,23 @@ async function loadLexiconPlugin(name: string): Promise<LexiconPlugin | null> {
   return null;
 }
 
+/**
+ * Copy each discovered Op's own `schedule` (#2120) onto its spec, so a CI
+ * generator can render the cron the Op already declares — `WatchOp({ name,
+ * schedule })` then needs no second cron in the `generateOpsPipeline` call.
+ * The spec's own `trigger`/`schedule` still win; `resolveOpTrigger` reads
+ * `opSchedule` last. Specs for Ops with no cadence pass through untouched.
+ */
+export function withOpSchedules(
+  specs: ScheduledOpSpec[],
+  discovered: Map<string, DiscoveredOp>,
+): ScheduledOpSpec[] {
+  return specs.map((spec) => {
+    const schedule = discovered.get(spec.name)?.config.schedule;
+    return schedule ? { ...spec, opSchedule: schedule } : spec;
+  });
+}
+
 /** Result of generating scheduled CI for a set of Ops (generate mode's Op counterpart, #927). */
 export interface GenerateOpsPipelineResult {
   success: boolean;
@@ -94,6 +111,6 @@ export async function generateOpsPipeline(
     };
   }
 
-  const { files, jobs } = plugin.generateOpPipeline(ops, options);
+  const { files, jobs } = plugin.generateOpPipeline(withOpSchedules(ops, discovered.ops), options);
   return { success: true, files, jobs };
 }

package/src/op/index.ts

@@ -3,18 +3,34 @@ export { Op, phase, activity, gate, effect, build, kubectlApply, helmInstall, he
          k3sInstall, k3sUninstall, flociUp, flociDown,
          flociAzUp, flociAzDown, flociGcpUp, flociGcpDown, httpCheck,
          azGroupEnsure, azGroupDelete, azApply, azDelete, awsApply, awsDelete, gcpApply, gcpDelete, policyGate,
+         guardValidate,
          spriteCreate, spriteExec, spriteCheckpoint, spriteRestore, listCheckpoints, spriteDestroy,
          spriteWriteFile, spriteReadFile, spriteListDir, spriteRemove,
          spriteApplyNetworkPolicy, spriteApplyServices,
          spriteTaskCreate, spriteTaskRefresh, spriteTaskRelease,
          spritesUp, spritesDown } from "./builders";
 export { OpResource } from "./resource";
-export { safeHeartbeat, sleep } from "./activity-runtime";
+export { sleep } from "./activity-runtime";
 export { emulatorLifecycle, emulatorsOf, endpointEnvVars } from "./emulator-lifecycle";
 export type { EmulatorSpec, EmulatorCapability, EmulatorDeclaration, EmulatorUpArgs, EmulatorLifecycle } from "./emulator-lifecycle";
 export { checkFreshness, compare, formatResult, latestRelease, parseVersion, unpinned } from "./emulator-freshness";
 export type { FreshnessResult } from "./emulator-freshness";
-export type { OpConfig, PhaseDefinition, StepDefinition, ActivityStep, GateStep, EffectStep } from "./types";
+export type { OpConfig, OpSchedule, PhaseDefinition, StepDefinition, ActivityStep, GateStep, EffectStep, OutcomeAttribute } from "./types";
+export { outcomeAttributesOf } from "./types";
+export { isValidCronExpression, cronSyntaxMessage, cronMatches, cronDueBetween } from "./cron";
+export {
+  WatchOp, ReconcileOp, ApplyOp, ConvergeOp,
+  WorkflowAuditOp, PipelineAuditOp, LexiconUpgradeOp, IN_SCOPE_LEXICONS,
+} from "./composites";
+export type {
+  WatchOpConfig, WatchOpResources,
+  ReconcileOpConfig, ReconcileOpResources,
+  ApplyOpConfig, ApplyOpResources,
+  ConvergeOpConfig, ConvergeOpResources, ConvergeDial,
+  WorkflowAuditOpConfig, WorkflowAuditOpResources,
+  PipelineAuditOpConfig, PipelineAuditOpResources,
+  LexiconUpgradeOpConfig, LexiconUpgradeOpResources,
+} from "./composites";
 export { receiptActivities, receiptCheckInput } from "./receipt-store";
 export type {
   ReceiptStore, EffectReceiptRef, ReceiptCheckInput, ReceiptActivities, ReceiptActivityOptions,
@@ -23,12 +39,29 @@ export type {
 } from "./receipt-store";
 export { discoverOps } from "./discover";
 export type { DiscoveredOp, OpDiscoveryResult } from "./discover";
-export { generateOpsPipeline } from "./generate-pipeline";
+export { generateOpsPipeline, withOpSchedules } from "./generate-pipeline";
 export type { GenerateOpsPipelineResult } from "./generate-pipeline";
 export { loadActivities, loadProfiles, resolveActivity } from "./activity-registry";
-export type { ActivityFn, ActivityProfile } from "./activity-registry";
-export { runOpLocally, parseDuration, findGate, LocalGateUnsupportedError, OpRunFailure } from "./local-executor";
-export type { StepRecord, OpRunResult } from "./local-executor";
+export type { ActivityFn } from "./activity-registry";
+export { loadActivityContracts, mergeActivityContracts } from "./activity-contract-registry";
+export type { LexiconActivityContractContributor } from "./activity-contract-registry";
+export { ACTIVITY_PROFILES, ACTIVITY_PROFILE_NAMES } from "./activity-profiles";
+export type { ActivityProfile, ActivityProfileName } from "./activity-profiles";
+export { NonRetryableActivityError, nonRetryableFailure } from "./activity-failure";
+export { runOpLocally, parseDuration, OpRunFailure } from "./local-executor";
+export type { StepRecord, OpRunResult, RunOpOptions } from "./local-executor";
+export { evaluateGate, gitGateLedgerPort, memoryGateLedgerPort, approveCommand } from "./gate";
+export type { GateLedgerPort, GateCheck, GateCheckInput } from "./gate";
+export { createLocalOpRuntime } from "./runtimes/local";
+export { runStateOf } from "./runtime";
+export type {
+  OpRuntimeProvider, OpRunHandle, OpRunStartOptions, OpRunState, OpRunStatus,
+  OpRunRecord, OpRunRecordInput, OpRunPhaseRecord, OpRunStepRecord,
+} from "./runtime";
+export { buildOpIR, serializeOpIR, opConfigFromIR, OP_IR_FORMAT_VERSION } from "./op-ir";
+export type {
+  OpIR, OpIRPhase, OpIRStep, OpIRActivityStep, OpIRGateStep, OpIREffectStep, OpIRActivityContract,
+} from "./op-ir";
 export { renderHuman, renderJson } from "./local-output";
 export {
   activityContract, isActivityContract, collectActivityContracts, validateActivitySteps, KNOWN_ACTIVITY_PROFILES,

package/src/op/local-executor.test.ts

@@ -4,23 +4,23 @@ import type { ActivityFn, ActivityProfile } from "./activity-registry";
 import {
   runOpLocally,
   parseDuration,
-  findGate,
-  LocalGateUnsupportedError,
   OpRunFailure,
 } from "./local-executor";
+import { memoryGateLedgerPort } from "./gate";
+import type { GateResolutionRecord, PendingGateRecord } from "../lifecycle/gate-ledger";
 import { stepOutput } from "./step-output-ref";
 
 // Fast profiles so retry/timeout tests run in milliseconds.
 const PROFILES: Record<string, ActivityProfile> = {
   fastIdempotent: {
-    startToCloseTimeout: "5m",
+    timeout: "5m",
     retry: { maximumAttempts: 3, initialInterval: "5ms", backoffCoefficient: 2 },
   },
   quickTimeout: {
-    startToCloseTimeout: "50ms",
+    timeout: "50ms",
     retry: { maximumAttempts: 2, initialInterval: "1ms", backoffCoefficient: 1 },
   },
-  single: { startToCloseTimeout: "5m", retry: { maximumAttempts: 1 } },
+  single: { timeout: "5m", retry: { maximumAttempts: 1 } },
 };
 
 function op(partial: Partial<OpConfig>): OpConfig {
@@ -56,7 +56,7 @@ describe("runOpLocally — sequencing", () => {
     });
     const result = await runOpLocally(config, activities, PROFILES);
     expect(order).toEqual(["a", "b", "c"]);
-    expect(result.ok).toBe(true);
+    expect(result.status).toBe("ok");
     expect(result.records.map((r) => r.fn)).toEqual(["a", "b", "c"]);
   });
 
@@ -115,11 +115,11 @@ describe("runOpLocally — retry + timeout", () => {
   test("honors a step's non-default profile timeout (not the default)", async () => {
     // The default profile would time out at 50ms; the step is tagged longInfra,
     // which gives it room. Guards the bug where a profiled step silently got the
-    // default cap (local vs --temporal disagreement).
+    // default cap (a per-runtime disagreement).
     const slow: ActivityFn = async () => { await new Promise((r) => setTimeout(r, 150)); return "done"; };
     const profiles = {
-      fastIdempotent: { startToCloseTimeout: "50ms", retry: { maximumAttempts: 1 } },
-      longInfra: { startToCloseTimeout: "5m", retry: { maximumAttempts: 1 } },
+      fastIdempotent: { timeout: "50ms", retry: { maximumAttempts: 1 } },
+      longInfra: { timeout: "5m", retry: { maximumAttempts: 1 } },
     };
     const config = op({
       phases: [{ name: "P", steps: [{ kind: "activity", fn: "slow", profile: "longInfra" }] }],
@@ -140,7 +140,7 @@ describe("runOpLocally — cancellation", () => {
       throw new Error("abandoned");
     };
     const config = op({ phases: [{ name: "P", steps: [{ kind: "activity", fn: "hang" }] }] });
-    const profiles = { ...PROFILES, fastIdempotent: { startToCloseTimeout: "30ms", retry: { maximumAttempts: 1 } } };
+    const profiles = { ...PROFILES, fastIdempotent: { timeout: "30ms", retry: { maximumAttempts: 1 } } };
     await expect(runOpLocally(config, new Map([["hang", hang]]), profiles)).rejects.toBeInstanceOf(OpRunFailure);
     expect(abortedSeen).toBe(true);
   });
@@ -187,7 +187,7 @@ describe("runOpLocally — non-retryable errors", () => {
     const profiles = {
       ...PROFILES,
       fastIdempotent: {
-        startToCloseTimeout: "5m",
+        timeout: "5m",
         retry: { maximumAttempts: 3, initialInterval: "1ms", nonRetryableErrorTypes: ["ValidationError"] },
       },
     };
@@ -207,11 +207,40 @@ describe("runOpLocally — outcomeAttribute", () => {
     });
     const result = await runOpLocally(config, new Map([["lifecycleDiff", diff]]), PROFILES);
     expect(result.records[0].outcome).toEqual({ name: "Drift", value: false });
+    expect(result.records[0].outcomes).toEqual([{ name: "Drift", value: false }]);
+  });
+
+  test("an array captures every attribute off one result, and `outcome` stays the first (#2105)", async () => {
+    const livePlan: ActivityFn = async () => ({ drift: true, unowned: 3, adoptable: 2 });
+    const config = op({
+      phases: [{ name: "Plan", steps: [
+        { kind: "activity", fn: "choudoufuLivePlan", outcomeAttribute: [
+          { name: "Drift", from: "drift" },
+          { name: "Unowned", from: "unowned" },
+          { name: "Adoptable", from: "adoptable" },
+        ] },
+      ] }],
+    });
+    const result = await runOpLocally(config, new Map([["choudoufuLivePlan", livePlan]]), PROFILES);
+    expect(result.records[0].outcomes).toEqual([
+      { name: "Drift", value: true },
+      { name: "Unowned", value: 3 },
+      { name: "Adoptable", value: 2 },
+    ]);
+    expect(result.records[0].outcome).toEqual({ name: "Drift", value: true });
+  });
+
+  test("a step with no attribute leaves both fields absent", async () => {
+    const noop: ActivityFn = async () => ({ ok: true });
+    const config = op({ phases: [{ name: "Plan", steps: [{ kind: "activity", fn: "noop" }] }] });
+    const result = await runOpLocally(config, new Map([["noop", noop]]), PROFILES);
+    expect(result.records[0].outcome).toBeUndefined();
+    expect(result.records[0].outcomes).toBeUndefined();
   });
 });
 
 describe("runOpLocally — onFailure", () => {
-  test("runs compensation phases in reverse and rejects with ok=false", async () => {
+  test("runs compensation phases in reverse and rejects with status=fail", async () => {
     const order: string[] = [];
     const make = (tag: string, fail = false): ActivityFn => async () => {
       order.push(tag);
@@ -231,35 +260,135 @@ describe("runOpLocally — onFailure", () => {
     });
     const err = await runOpLocally(config, activities, PROFILES).catch((e) => e);
     expect(err).toBeInstanceOf(OpRunFailure);
-    expect(err.result.ok).toBe(false);
+    expect(err.result.status).toBe("fail");
     // Main fails (3 attempts), then compensation runs in reverse: comp2, comp1.
     expect(order).toEqual(["main", "main", "main", "comp2", "comp1"]);
   });
 });
 
-describe("runOpLocally — gate rejection", () => {
-  test("rejects before running any step when a gate is present", async () => {
-    const ran = vi.fn();
-    const activities = new Map<string, ActivityFn>([["a", async () => { ran(); }]]);
-    const config = op({
+describe("runOpLocally — gate as fact (#2119)", () => {
+  const NOW = "2026-09-05T12:00:00.000Z";
+
+  const resolution = (over: Partial<GateResolutionRecord> = {}): GateResolutionRecord => ({
+    version: 1, op: "test-op", gate: "approve-prod", resolvedBy: "alex",
+    timestamp: "2026-09-05T11:00:00.000Z", ...over,
+  });
+  const pending = (over: Partial<PendingGateRecord> = {}): PendingGateRecord => ({
+    version: 1, kind: "pending", op: "test-op", gate: "approve-prod",
+    timestamp: "2026-09-05T10:00:00.000Z", expiresAt: "2026-09-07T10:00:00.000Z", ...over,
+  });
+
+  /** A gate between two steps, so "no phase after the gate ran" is observable. */
+  function gatedOp(): OpConfig {
+    return op({
       phases: [
-        { name: "P", steps: [
-          { kind: "activity", fn: "a" },
-          { kind: "gate", signalName: "approve-prod" },
+        { name: "P1", steps: [
+          { kind: "activity", fn: "before" },
+          { kind: "gate", signalName: "approve-prod", description: "release manager signs off", timeout: "24h" },
+          { kind: "activity", fn: "after" },
         ] },
+        { name: "P2", steps: [{ kind: "activity", fn: "later" }] },
       ],
+      onFailure: [{ name: "Comp", steps: [{ kind: "activity", fn: "compensate" }] }],
+    });
+  }
+
+  function tracked() {
+    const calls: string[] = [];
+    const fn = (tag: string): ActivityFn => async () => { calls.push(tag); };
+    return {
+      calls,
+      activities: new Map<string, ActivityFn>([
+        ["before", fn("before")], ["after", fn("after")],
+        ["later", fn("later")], ["compensate", fn("compensate")],
+      ]),
+    };
+  }
+
+  test("with no resolution: ends gated, records the pending fact, runs nothing after the gate", async () => {
+    const { calls, activities } = tracked();
+    const port = memoryGateLedgerPort();
+    const result = await runOpLocally(gatedOp(), activities, PROFILES, undefined, { gates: port, now: NOW });
+
+    expect(result.status).toBe("gated");
+    expect(calls).toEqual(["before"]);
+    expect(result.gate).toMatchObject({ op: "test-op", gate: "approve-prod", description: "release manager signs off" });
+    // The gate's own `timeout` is the pending fact's expiry.
+    expect(result.gate?.expiresAt).toBe("2026-09-06T12:00:00.000Z");
+    expect(port.appended).toHaveLength(1);
+    expect(result.records.map((r) => [r.fn, r.status])).toEqual([
+      ["before", "ok"],
+      ["gate:approve-prod", "skipped"],
+      ["after", "skipped"],
+      ["later", "skipped"],
+    ]);
+  });
+
+  test("onFailure phases do not run on a gated run", async () => {
+    const { calls, activities } = tracked();
+    await runOpLocally(gatedOp(), activities, PROFILES, undefined, { gates: memoryGateLedgerPort(), now: NOW });
+    expect(calls).not.toContain("compensate");
+  });
+
+  test("a resolution newer than the pending fact passes the gate and carries the approver", async () => {
+    const { calls, activities } = tracked();
+    const port = memoryGateLedgerPort({
+      pending: [pending()],
+      resolutions: [resolution({ url: "https://github.com/org/repo/pull/7" })],
+    });
+    const result = await runOpLocally(gatedOp(), activities, PROFILES, undefined, { gates: port, now: NOW });
+
+    expect(result.status).toBe("ok");
+    expect(calls).toEqual(["before", "after", "later"]);
+    expect(result.records.find((r) => r.fn === "gate:approve-prod")?.approval).toEqual({
+      gate: "approve-prod",
+      resolvedBy: "alex",
+      timestamp: "2026-09-05T11:00:00.000Z",
+      url: "https://github.com/org/repo/pull/7",
+    });
+    expect(port.appended).toHaveLength(0);
+  });
+
+  test("a resolution dated before the pending fact is ignored", async () => {
+    const port = memoryGateLedgerPort({
+      pending: [pending({ timestamp: "2026-09-05T11:30:00.000Z" })],
+      resolutions: [resolution({ timestamp: "2026-09-05T09:00:00.000Z" })],
     });
-    await expect(runOpLocally(config, activities, PROFILES)).rejects.toBeInstanceOf(LocalGateUnsupportedError);
-    await expect(runOpLocally(config, activities, PROFILES)).rejects.toThrow(/--temporal/);
-    expect(ran).not.toHaveBeenCalled();
+    const result = await runOpLocally(gatedOp(), tracked().activities, PROFILES, undefined, { gates: port, now: NOW });
+    expect(result.status).toBe("gated");
   });
 
-  test("findGate locates a gate in phases or onFailure", () => {
-    expect(findGate(op({ phases: [{ name: "P", steps: [{ kind: "activity", fn: "a" }] }] }))).toBeUndefined();
-    const gated = findGate(op({
-      phases: [{ name: "P", steps: [{ kind: "gate", signalName: "g" }] }],
-    }));
-    expect(gated?.signalName).toBe("g");
+  test("a live pending fact is reused, not re-recorded", async () => {
+    const port = memoryGateLedgerPort({ pending: [pending()] });
+    const result = await runOpLocally(gatedOp(), tracked().activities, PROFILES, undefined, { gates: port, now: NOW });
+    expect(result.status).toBe("gated");
+    expect(port.appended).toHaveLength(0);
+    expect(result.gate?.timestamp).toBe("2026-09-05T10:00:00.000Z");
+  });
+
+  test("an expired pending fact is ignored and re-recorded", async () => {
+    const port = memoryGateLedgerPort({ pending: [pending({ expiresAt: "2026-09-05T11:00:00.000Z" })] });
+    const result = await runOpLocally(gatedOp(), tracked().activities, PROFILES, undefined, { gates: port, now: NOW });
+    expect(result.status).toBe("gated");
+    expect(port.appended).toHaveLength(1);
+    expect(result.gate?.timestamp).toBe(NOW);
+  });
+
+  test("approve then re-run completes the op", async () => {
+    const port = memoryGateLedgerPort();
+    const first = await runOpLocally(gatedOp(), tracked().activities, PROFILES, undefined, { gates: port, now: NOW });
+    expect(first.status).toBe("gated");
+
+    // `chant approve` writes the counterpart fact, dated after the pending one.
+    const approved = memoryGateLedgerPort({
+      pending: [first.gate!],
+      resolutions: [resolution({ timestamp: "2026-09-05T12:30:00.000Z" })],
+    });
+    const second = await runOpLocally(gatedOp(), tracked().activities, PROFILES, undefined, {
+      gates: approved,
+      now: "2026-09-05T13:00:00.000Z",
+    });
+    expect(second.status).toBe("ok");
   });
 });
 
@@ -277,7 +406,7 @@ describe("runOpLocally — step-output references (#1290)", () => {
       ] }],
     });
     const result = await runOpLocally(config, activities, PROFILES);
-    expect(result.ok).toBe(true);
+    expect(result.status).toBe("ok");
     expect(received).toEqual([{ stacks: ["a", "b"] }]);
     // The recorded step also shows the resolved value, not the raw ref object.
     expect(result.records[1].args).toEqual({ stacks: ["a", "b"] });
@@ -332,11 +461,11 @@ describe("runOpLocally — step-output references (#1290)", () => {
       ] }],
     });
     const result = await runOpLocally(config, activities, PROFILES);
-    expect(result.ok).toBe(true);
+    expect(result.status).toBe("ok");
     expect(received).toEqual([{ v: undefined }]);
   });
 
-  test("e2e: chant run (non-temporal) end to end — producer object flows to consumer", async () => {
+  test("e2e: chant run on the local runtime, end to end — producer object flows to consumer", async () => {
     const activities = new Map<string, ActivityFn>([
       ["lifecycleDiff", async () => ({ driftedStacks: ["stack-a"], drifted: true })],
       ["applyStacks", async (args) => ({ applied: args.stacks })],
@@ -348,7 +477,7 @@ describe("runOpLocally — step-output references (#1290)", () => {
       ],
     });
     const result = await runOpLocally(config, activities, PROFILES);
-    expect(result.ok).toBe(true);
+    expect(result.status).toBe("ok");
     expect(result.records.every((r) => r.status === "ok")).toBe(true);
     expect(result.records[1].args).toEqual({ stacks: ["stack-a"] });
   });