@intentius/chant 0.57.0 → 0.58.0

package/src/op/composites/reconcile-op.ts

@@ -0,0 +1,107 @@
+/**
+ * ReconcileOp composite — the cloud → code workflow as an Op.
+ *
+ * Keeps source tracking reality: when live drifts from declarations, open a PR
+ * that regenerates the affected TypeScript. Mirrors the {@link WatchOp} shape.
+ *
+ * Phases: snapshot → plan → regenerate (live import) → open PR. The
+ * regenerate-and-PR step is the `reconcilePr` activity (#122), which derives
+ * the change set from `chant lifecycle plan` and opens a reviewable PR.
+ *
+ * Runs one-shot on the local Op executor for a `chant run`; with a `schedule`
+ * the cadence rides on the Op itself (#2120) for whichever runtime honours it.
+ *
+ * @example
+ * ```typescript
+ * // one-shot, local executor
+ * export const { op } = ReconcileOp({ name: "prod-reconcile", env: "prod" });
+ *
+ * // hourly
+ * export const { op } = ReconcileOp({
+ *   name: "prod-reconcile",
+ *   env: "prod",
+ *   schedule: "0 * * * *",
+ *   scope: { owned: true },
+ * });
+ * ```
+ *
+ * @see #112 — stateless-authoritative state model + live import
+ */
+
+import { Op, phase, activity } from "../builders";
+import type { OpResource } from "../resource";
+import type { ReconcileMode } from "../activities/reconcile";
+
+export interface ReconcileOpConfig {
+  /** Op name (kebab-case). Names the Op's output directory and is what `chant run` takes. */
+  name: string;
+  /** Environment to reconcile (e.g. "prod"). */
+  env: string;
+  /**
+   * Cron expression. When set, it lands on the Op as `schedule`; omit for
+   * one-shot `chant run` on the local executor.
+   */
+  schedule?: string;
+  /**
+   * What to produce on drift. Default: "pull-request".
+   * @default "pull-request"
+   */
+  onDrift?: ReconcileMode;
+  /** Restrict reconciliation to chant-owned resources. */
+  scope?: { owned?: boolean };
+}
+
+export interface ReconcileOpResources {
+  /** Op resource — the snapshot→plan→regenerate→PR Op. */
+  op: InstanceType<typeof OpResource>;
+}
+
+export function ReconcileOp(config: ReconcileOpConfig): ReconcileOpResources {
+  const onDrift = config.onDrift ?? "pull-request";
+  const owned = config.scope?.owned ?? false;
+
+  // The reconcile's headline output is the opened PR (or issue) URL. Expose it as
+  // an outcome attribute so it prints in `chant run` and lands on the ledger.
+  // `report` mode opens nothing, so it has no URL outcome.
+  const reconcileOutcome =
+    onDrift === "pull-request"
+      ? { name: "PR", from: "prUrl" }
+      : onDrift === "issue"
+        ? { name: "Issue", from: "issueUrl" }
+        : undefined;
+
+  const op = Op({
+    name: config.name,
+    overview: `Reconcile the ${config.env} environment into source (cloud → code)`,
+    labels: {
+      Reconcile: "true",
+      Env: config.env,
+    },
+    ...(config.schedule ? { schedule: { cron: config.schedule, overlap: "skip" as const } } : {}),
+    phases: [
+      phase("Snapshot", [activity("lifecycleSnapshot", { env: config.env })]),
+      phase("Plan", [
+        {
+          kind: "activity",
+          fn: "lifecycleDiff",
+          args: { env: config.env, live: true },
+          outcomeAttribute: { name: "Drift", from: "drifted" },
+        },
+      ]),
+      phase("Reconcile", [
+        // reconcilePr derives the change set from `chant lifecycle plan`,
+        // regenerates via `chant import --from`, and opens a PR. Surface the
+        // opened PR/issue URL as an outcome so `chant run` prints it — the
+        // reconcile's result is the link.
+        {
+          kind: "activity" as const,
+          fn: "reconcilePr",
+          args: { env: config.env, mode: onDrift, owned },
+          ...(reconcileOutcome ? { outcomeAttribute: reconcileOutcome } : {}),
+        },
+      ]),
+    ],
+  });
+
+  return { op };
+}

package/src/op/composites/watch-op.ts

@@ -0,0 +1,108 @@
+/**
+ * WatchOp composite — periodic state observation as an Op.
+ *
+ * Composes existing pieces:
+ *   - The local executor (`../local-executor.ts`) runs the phases in order and
+ *     files each step's record under the phase it belongs to
+ *   - The pre-built lifecycleSnapshot + lifecycleDiff activities
+ *   - `schedule` puts the cadence on the Op itself (#2120)
+ *
+ * The cron is Op data, not a resource: `chant operator` ticks on it, the
+ * github/gitlab/forgejo generators render it as a CI cron, and a hosting
+ * lexicon hands it to its own scheduler.
+ *
+ * @example
+ * ```typescript
+ * export const { op } = WatchOp({
+ *   name: "prod-watch",
+ *   env: "prod",
+ *   schedule: "0,15,30,45 * * * *", // every 15 minutes
+ * });
+ * ```
+ *
+ * @see #31 — Continuous observation (the issue this composite addresses)
+ */
+
+import { Op, phase, activity } from "../builders";
+import { receiptCheckInput } from "../receipt-store";
+import type { OpResource } from "../resource";
+import type { EffectReceiptDeclaration } from "../../effect-receipt";
+
+export interface WatchOpConfig {
+  /** Op name (kebab-case). Names the Op's output directory and is what `chant run` takes. */
+  name: string;
+  /** Environment to snapshot + diff (e.g. "prod"). */
+  env: string;
+  /**
+   * Cron expression controlling how often the watch runs. Omit for a
+   * one-shot `chant run` on the local executor.
+   * @example "0,15,30,45 * * * *" — every 15 minutes
+   * @example "0 * * * *" — hourly
+   */
+  schedule?: string;
+  /**
+   * Run `chant lifecycle diff --live` (queries cloud APIs) instead of the
+   * default digest-only diff. Recommended for real drift detection.
+   * @default true
+   */
+  live?: boolean;
+  /**
+   * Effect receipts to check for staleness between change windows (#1834,
+   * epic #1703). Typed references only — import each EffectReceipt const.
+   * Read-only: the watch reads each receipt through the receipt store
+   * (provided by the receipt row's lexicon, #1835) and reports absent or
+   * differing values as findings. It never runs an effect and never writes
+   * a receipt — the `effect()` step is the sole writer.
+   */
+  receipts?: EffectReceiptDeclaration[];
+}
+
+export interface WatchOpResources {
+  /** Op resource — the snapshot+diff Op, emitted on `chant build`. */
+  op: InstanceType<typeof OpResource>;
+}
+
+export function WatchOp(config: WatchOpConfig): WatchOpResources {
+  const live = config.live ?? true;
+
+  const op = Op({
+    name: config.name,
+    overview: `Periodically snapshot and diff the ${config.env} environment`,
+    labels: {
+      Watch: "true",
+      Env: config.env,
+    },
+    ...(config.schedule ? { schedule: { cron: config.schedule, overlap: "skip" as const } } : {}),
+    phases: [
+      phase("Snapshot", [activity("lifecycleSnapshot", { env: config.env })]),
+      phase("Diff", [
+        // outcomeAttribute surfaces lifecycleDiff's `drifted` boolean as the
+        // run's `Drift` outcome on the run ledger, so a reader of the ledger
+        // can pick out the runs that detected drift.
+        {
+          kind: "activity",
+          fn: "lifecycleDiff",
+          args: { env: config.env, live },
+          outcomeAttribute: { name: "Drift", from: "drifted" },
+        },
+      ]),
+      // Receipt staleness (#1834): read-only over the receipt store — absent
+      // or differing receipts surface as findings (and a StaleReceipts run
+      // outcome); nothing runs and nothing is written.
+      ...(config.receipts && config.receipts.length > 0
+        ? [
+            phase("Receipts", [
+              {
+                kind: "activity" as const,
+                fn: "receiptStaleness",
+                args: { receipts: config.receipts.map(receiptCheckInput) },
+                outcomeAttribute: { name: "StaleReceipts", from: "stale" },
+              },
+            ]),
+          ]
+        : []),
+    ],
+  });
+
+  return { op };
+}

package/src/op/composites/workflow-audit-op.test.ts

@@ -0,0 +1,25 @@
+import { describe, test, expect } from "vitest";
+import { WorkflowAuditOp } from "./workflow-audit-op";
+
+function opProps(op: unknown): Record<string, unknown> {
+  return (op as { props: Record<string, unknown> }).props;
+}
+
+describe("WorkflowAuditOp composite (#292)", () => {
+  test("one-shot form: op only, no cadence", () => {
+    const { op } = WorkflowAuditOp({ name: "actions-audit" });
+    expect(op).toBeDefined();
+    expect(opProps(op).schedule).toBeUndefined();
+  });
+
+  test("scheduled form: the cron rides on the op (#2120)", () => {
+    const { op } = WorkflowAuditOp({
+      name: "actions-audit",
+      schedule: "0 6 * * *",
+      onFinding: "pull-request",
+    });
+    expect(opProps(op).schedule).toEqual({ cron: "0 6 * * *", overlap: "skip" });
+    const step = (opProps(op).phases as Array<{ steps: Array<{ args: { mode: string } }> }>)[0].steps[0];
+    expect(step.args.mode).toBe("pull-request");
+  });
+});

package/src/op/composites/workflow-audit-op.ts

@@ -0,0 +1,88 @@
+/**
+ * WorkflowAuditOp composite — the live supply-chain audit of GitHub workflows
+ * as a chant Op with an optional schedule (#292).
+ *
+ * The github post-synth checks (#286-#291) own everything answerable from the
+ * deterministic build. This Op owns *only* the checks that require live
+ * resolution against a moving upstream truth — stale SHA pins, impostor refs,
+ * symbolic-ref confusion, pin/comment mismatch, advisories, archived upstreams.
+ * It sits at **observe** on the lifecycle dial, with a finding-mode (mirroring
+ * `ReconcileOp`: `report | issue | pull-request`) as the **reconcile** step.
+ *
+ * Runs one-shot on the local Op executor via `chant run`; a `schedule` puts
+ * the cadence on the Op itself (#2120), for continuous re-audit between
+ * change windows.
+ *
+ * @example
+ * ```typescript
+ * // one-shot, local executor
+ * export const { op } = WorkflowAuditOp({ name: "actions-audit" });
+ *
+ * // daily, opening a PR that bumps a stale pin
+ * export const { op } = WorkflowAuditOp({
+ *   name: "actions-audit",
+ *   schedule: "0 6 * * *",
+ *   onFinding: "pull-request",
+ * });
+ * ```
+ *
+ * @see #286 — the deterministic counterpart this freshens.
+ */
+
+import { Op, phase } from "../builders";
+import type { OpResource } from "../resource";
+import type { WorkflowAuditMode } from "../activities/workflow-audit";
+
+export interface WorkflowAuditOpConfig {
+  /** Op name (kebab-case). Names the Op's output directory and is what `chant run` takes. */
+  name: string;
+  /**
+   * Cron expression. When set, it lands on the Op as `schedule` for
+   * continuous re-audit; omit for one-shot `chant run` on the local executor.
+   */
+  schedule?: string;
+  /**
+   * Directory of emitted workflow files to audit at run time.
+   * @default ".github/workflows"
+   */
+  workflowsDir?: string;
+  /**
+   * What to produce on findings. Default: "report".
+   * @default "report"
+   */
+  onFinding?: WorkflowAuditMode;
+}
+
+export interface WorkflowAuditOpResources {
+  /** Op resource — generates the audit workflow on `chant build`. */
+  op: InstanceType<typeof OpResource>;
+}
+
+export function WorkflowAuditOp(config: WorkflowAuditOpConfig): WorkflowAuditOpResources {
+  const onFinding = config.onFinding ?? "report";
+
+  const op = Op({
+    name: config.name,
+    overview: "Resolve workflow action references against live upstreams and report supply-chain drift",
+    labels: {
+      Audit: "true",
+      Surface: "github-workflows",
+    },
+    ...(config.schedule ? { schedule: { cron: config.schedule, overlap: "skip" as const } } : {}),
+    phases: [
+      phase("Audit", [
+        {
+          kind: "activity",
+          fn: "workflowSupplyChainAudit",
+          args: { workflowsDir: config.workflowsDir ?? ".github/workflows", mode: onFinding },
+          // Surface the finding count as the run's `Findings` outcome on the
+          // run ledger, so a reader can pick out the audits that found
+          // something.
+          outcomeAttribute: { name: "Findings", from: "findings" },
+        },
+      ]),
+    ],
+  });
+
+  return { op };
+}

package/src/op/converge-rule.ts

@@ -5,10 +5,10 @@
  * The issue's illustrative sketch writes a rule's condition as a JS arrow
  * function (`s => s.status === "drifted"`). That reads well but can't
  * actually ship: a rule is evaluated per-tick against live, freshly-observed
- * data inside a Temporal activity, and an activity's arguments — including
- * whatever a `ConvergeOp` composite bakes into its generated workflow — must
- * be plain JSON (see `step-output-ref.ts`'s module doc on why a value
- * crossing the workflow/activity boundary can't carry a closure). A rule
+ * data inside an activity, and an activity's arguments — including whatever a
+ * `ConvergeOp` composite bakes into the Op it builds — must be plain JSON (see
+ * `step-output-ref.ts`'s module doc on why a value crossing an activity
+ * boundary can't carry a closure). A rule
  * "outside the evaluable subset" is one of the build-time refusals #1484
  * names explicitly, which only makes sense if there IS an evaluable subset
  * to be outside of — so rules here are data: a small comparison language
@@ -25,7 +25,8 @@
  * produces" refusal, satisfied for free. {@link isWellFormedPredicate} is the
  * runtime backstop for a rule assembled by hand (bypassing `when()`/the
  * comparison builders) rather than authored through them, and is what a
- * build-time check (TMP014) re-validates the serialized rule table against.
+ * build-time check (OPS014, ../lint/rules/op/ops014-converge-rule-refusals.ts)
+ * re-validates the serialized rule table against.
  */
 
 // ── Predicates ───────────────────────────────────────────────────────────────
@@ -76,8 +77,9 @@ const FIELD_TRUTHINESS_OPS: ReadonlySet<string> = new Set(["truthy", "falsy"]);
 
 /**
  * Structural validator for a value claiming to be a {@link SymptomPredicate}
- * — the runtime backstop `TMP014` (lexicons/temporal's post-synth check)
- * re-checks a serialized rule table against, since nothing forces a rule
+ * — the runtime backstop OPS014
+ * (../lint/rules/op/ops014-converge-rule-refusals.ts) re-checks a serialized
+ * rule table against, since nothing forces a rule
  * assembled by hand (rather than through the builders below) to match this
  * shape. Recurses through `allOf`/`anyOf`; `fieldWhitelist`, when given,
  * additionally refuses a field name the symptom record doesn't actually
@@ -152,9 +154,9 @@ export function evaluatePredicate<S>(predicate: SymptomPredicate<S>, symptom: S)
  * Does a predicate reference the given symptom field anywhere in it,
  * recursing through `allOf`/`anyOf`? The build-time backstop for a claim
  * about a *category* of rule (e.g. "a rule reading `adoptCount`") rather
- * than a single comparison — `TMP014`'s adopt-safety check
- * (../../../lexicons/temporal/src/lint/post-synth/tmp014-converge-rule-refusals.ts)
- * uses this to refuse a rule that both reads `adoptCount` and dispatches a
+ * than a single comparison — OPS014's adopt-safety check
+ * (../lint/rules/op/ops014-converge-rule-refusals.ts) uses this to refuse a
+ * rule that both reads `adoptCount` and dispatches a
  * mutating op, rather than merely documenting that authors shouldn't write
  * one.
  */

package/src/op/cron.test.ts

@@ -0,0 +1,128 @@
+/**
+ * Cron tests (#2120) — the validator ported from TMP010, and the matcher
+ * `chant operator` ticks on.
+ */
+
+import { describe, test, expect } from "vitest";
+import { isValidCronExpression, cronSyntaxMessage, cronMatches, cronDueBetween } from "./cron";
+
+/** Local-time date literal, so a matcher reading `getHours()` sees what the test wrote. */
+function at(y: number, m: number, d: number, h: number, min: number): Date {
+  return new Date(y, m - 1, d, h, min, 0, 0);
+}
+
+describe("isValidCronExpression — the shared parser", () => {
+  test("accepts 5- and 6-field expressions", () => {
+    expect(isValidCronExpression("*/10 * * * *")).toBe(true);
+    expect(isValidCronExpression("0 6 * * 1")).toBe(true);
+    expect(isValidCronExpression("0 0 6 * * *")).toBe(true);
+  });
+
+  test("rejects the wrong field count", () => {
+    expect(isValidCronExpression("* * * *")).toBe(false);
+    expect(isValidCronExpression("* * * * * * *")).toBe(false);
+  });
+
+  test("rejects prose and named fields", () => {
+    expect(isValidCronExpression("every ten minutes")).toBe(false);
+    expect(isValidCronExpression("0 6 * * MON")).toBe(false);
+  });
+
+  test("tolerates surrounding whitespace and repeated separators", () => {
+    expect(isValidCronExpression("  0   6 * * *  ")).toBe(true);
+  });
+
+  test("the message names the expression, so the Op refusal and a lexicon's cron check read alike", () => {
+    expect(cronSyntaxMessage("nope")).toBe(
+      'cron expression "nope" does not look like valid 5- or 6-field cron syntax',
+    );
+  });
+});
+
+describe("cronMatches", () => {
+  test("every minute", () => {
+    expect(cronMatches("* * * * *", at(2026, 9, 6, 13, 37))).toBe(true);
+  });
+
+  test("a step fires on the multiples and nothing else", () => {
+    expect(cronMatches("*/10 * * * *", at(2026, 9, 6, 13, 30))).toBe(true);
+    expect(cronMatches("*/10 * * * *", at(2026, 9, 6, 13, 31))).toBe(false);
+  });
+
+  test("a list fires on each member", () => {
+    for (const m of [0, 15, 30, 45]) {
+      expect(cronMatches("0,15,30,45 * * * *", at(2026, 9, 6, 1, m))).toBe(true);
+    }
+    expect(cronMatches("0,15,30,45 * * * *", at(2026, 9, 6, 1, 16))).toBe(false);
+  });
+
+  test("a range fires inside it only", () => {
+    expect(cronMatches("0 9-17 * * *", at(2026, 9, 6, 9, 0))).toBe(true);
+    expect(cronMatches("0 9-17 * * *", at(2026, 9, 6, 17, 0))).toBe(true);
+    expect(cronMatches("0 9-17 * * *", at(2026, 9, 6, 18, 0))).toBe(false);
+  });
+
+  test("a bare number in a field means only that value", () => {
+    expect(cronMatches("0 6 * * *", at(2026, 9, 6, 6, 0))).toBe(true);
+    expect(cronMatches("0 6 * * *", at(2026, 9, 6, 7, 0))).toBe(false);
+  });
+
+  test("day-of-week — 2026-09-07 is a Monday", () => {
+    expect(cronMatches("0 6 * * 1", at(2026, 9, 7, 6, 0))).toBe(true);
+    expect(cronMatches("0 6 * * 1", at(2026, 9, 8, 6, 0))).toBe(false);
+  });
+
+  test("day-of-week 7 is Sunday, like 0 — 2026-09-06 is a Sunday", () => {
+    expect(cronMatches("0 6 * * 7", at(2026, 9, 6, 6, 0))).toBe(true);
+    expect(cronMatches("0 6 * * 0", at(2026, 9, 6, 6, 0))).toBe(true);
+  });
+
+  test("dom and dow both restricted: either one matching is enough", () => {
+    // The 1st of the month, or any Monday.
+    expect(cronMatches("0 6 1 * 1", at(2026, 9, 1, 6, 0))).toBe(true);
+    expect(cronMatches("0 6 1 * 1", at(2026, 9, 7, 6, 0))).toBe(true);
+    expect(cronMatches("0 6 1 * 1", at(2026, 9, 8, 6, 0))).toBe(false);
+  });
+
+  test("a 6-field expression drops the seconds field", () => {
+    expect(cronMatches("30 0 6 * * *", at(2026, 9, 6, 6, 0))).toBe(true);
+  });
+
+  test("a Quartz extension the evaluator cannot read matches everything rather than nothing", () => {
+    expect(cronMatches("0 6 L * ?", at(2026, 9, 6, 6, 0))).toBe(true);
+  });
+
+  test("a malformed expression matches nothing", () => {
+    expect(cronMatches("not a cron", at(2026, 9, 6, 6, 0))).toBe(false);
+  });
+});
+
+describe("cronDueBetween", () => {
+  test("a firing minute inside the window is due", () => {
+    expect(cronDueBetween("*/10 * * * *", at(2026, 9, 6, 13, 22), at(2026, 9, 6, 13, 35))).toBe(true);
+  });
+
+  test("a window with no firing minute is not due", () => {
+    expect(cronDueBetween("*/10 * * * *", at(2026, 9, 6, 13, 31), at(2026, 9, 6, 13, 39))).toBe(false);
+  });
+
+  test("the window is half-open: the `after` minute itself does not count again", () => {
+    expect(cronDueBetween("*/10 * * * *", at(2026, 9, 6, 13, 30), at(2026, 9, 6, 13, 30))).toBe(false);
+  });
+
+  test("the upper bound counts", () => {
+    expect(cronDueBetween("*/10 * * * *", at(2026, 9, 6, 13, 39), at(2026, 9, 6, 13, 40))).toBe(true);
+  });
+
+  test("several missed fires collapse into one due answer", () => {
+    expect(cronDueBetween("* * * * *", at(2026, 9, 6, 13, 0), at(2026, 9, 6, 13, 30))).toBe(true);
+  });
+
+  test("a window longer than the scan cap is due without scanning", () => {
+    expect(cronDueBetween("0 6 1 1 *", at(2020, 1, 1, 0, 0), at(2026, 9, 6, 0, 0))).toBe(true);
+  });
+
+  test("a backwards window is never due", () => {
+    expect(cronDueBetween("* * * * *", at(2026, 9, 6, 13, 30), at(2026, 9, 6, 13, 0))).toBe(false);
+  });
+});

package/src/op/cron.ts

@@ -0,0 +1,149 @@
+/**
+ * Cron for an Op's own schedule (#2120) — validation at `Op()` construction
+ * and minute-granularity matching for `chant operator`'s per-op cadence.
+ *
+ * `OpConfig.schedule.cron` is runtime-neutral data: the github lexicon turns
+ * it into `on.schedule`, a hosting lexicon hands it to its own scheduler,
+ * `chant operator` reads it as that Op's tick cadence, and the local one-shot
+ * executor ignores it entirely. Nothing here talks to a scheduler.
+ *
+ * The validator a lexicon's own post-synth cron check imports rather than
+ * keeping its own copy:
+ * deliberately permissive, a pre-submission guard rather than a full parser,
+ * since the final word belongs to whichever scheduler runs the cron.
+ *
+ * {@link cronMatches} is stricter about what it can *evaluate* than
+ * {@link isValidCronExpression} is about what it accepts, so a field carrying
+ * a Quartz extension the evaluator does not implement (`L`, `W`, `#`, `?`)
+ * matches everything rather than nothing — an operator that ticks too often
+ * is a wasted converge, one that never ticks is a silent outage.
+ */
+
+/** Very permissive cron field pattern — catches obvious syntax errors. */
+const CRON_FIELD = /^[0-9*,/\-?LW#]+$/;
+
+/**
+ * True when `expr` looks like 5- or 6-field cron. Field-shape only: it does
+ * not check that a number is in range for its position, and it accepts the
+ * Quartz extensions (`L`, `W`, `#`, `?`) some schedulers take.
+ */
+export function isValidCronExpression(expr: string): boolean {
+  const fields = expr.trim().split(/\s+/);
+  if (fields.length < 5 || fields.length > 6) return false;
+  return fields.every((f) => CRON_FIELD.test(f));
+}
+
+/**
+ * The message `Op()` throws with and a lexicon's post-synth cron check
+ * reports, so one wording covers both the build-time refusal and the
+ * post-synth diagnostic.
+ */
+export function cronSyntaxMessage(expr: string): string {
+  return `cron expression "${expr}" does not look like valid 5- or 6-field cron syntax`;
+}
+
+/** A parsed cron field: either "matches anything" or the exact set it matches. */
+type FieldSpec = { any: true } | { any: false; values: Set<number> };
+
+const ANY: FieldSpec = { any: true };
+
+/**
+ * Parse one field into the set of values it matches. Anything the evaluator
+ * cannot make sense of — a Quartz extension, an inverted range, a zero step —
+ * degrades to {@link ANY} rather than throwing: this runs on an expression
+ * `Op()` already accepted, and refusing at tick time would strand the Op.
+ */
+function parseField(field: string, min: number, max: number): FieldSpec {
+  if (field === "*" || field === "?" || /[LW#]/.test(field)) return ANY;
+
+  const values = new Set<number>();
+  for (const part of field.split(",")) {
+    const [rangePart, stepPart] = part.split("/");
+    const step = stepPart === undefined ? 1 : Number(stepPart);
+    if (!Number.isInteger(step) || step < 1) return ANY;
+
+    let lo: number;
+    let hi: number;
+    if (rangePart === "*" || rangePart === "") {
+      lo = min;
+      hi = max;
+    } else if (rangePart.includes("-")) {
+      const [a, b] = rangePart.split("-");
+      lo = Number(a);
+      hi = Number(b);
+    } else {
+      lo = Number(rangePart);
+      // `5/10` means "from 5, every 10" — a bare `5` means only 5.
+      hi = stepPart === undefined ? lo : max;
+    }
+    if (!Number.isInteger(lo) || !Number.isInteger(hi) || lo > hi) return ANY;
+
+    for (let v = lo; v <= hi; v += step) values.add(v);
+  }
+  return values.size === 0 ? ANY : { any: false, values };
+}
+
+function fieldMatches(spec: FieldSpec, value: number): boolean {
+  return spec.any || spec.values.has(value);
+}
+
+/**
+ * True when `date` falls on a minute `expr` fires at, in the host's local
+ * time zone (the only clock the operator daemon has).
+ *
+ * A 6-field expression is read as Quartz's `second minute hour dom month dow`
+ * and the seconds field is dropped — nothing in chant ticks sub-minute.
+ * Day-of-month and day-of-week follow the usual cron rule: when both are
+ * restricted, either one matching is enough.
+ */
+export function cronMatches(expr: string, date: Date): boolean {
+  const fields = expr.trim().split(/\s+/);
+  const five = fields.length === 6 ? fields.slice(1) : fields;
+  if (five.length !== 5) return false;
+
+  const [minuteF, hourF, domF, monthF, dowF] = five;
+  if (!fieldMatches(parseField(minuteF, 0, 59), date.getMinutes())) return false;
+  if (!fieldMatches(parseField(hourF, 0, 23), date.getHours())) return false;
+  if (!fieldMatches(parseField(monthF, 1, 12), date.getMonth() + 1)) return false;
+
+  const dom = parseField(domF, 1, 31);
+  const dow = parseField(dowF, 0, 7);
+  const weekday = date.getDay();
+  const domOk = fieldMatches(dom, date.getDate());
+  const dowOk = fieldMatches(dow, weekday) || (weekday === 0 && fieldMatches(dow, 7));
+
+  if (dom.any && dow.any) return true;
+  if (dom.any) return dowOk;
+  if (dow.any) return domOk;
+  return domOk || dowOk;
+}
+
+/**
+ * The longest window {@link cronDueBetween} scans minute by minute. Past it
+ * the answer is "yes" without scanning: an operator that has not looked at an
+ * op for two days has certainly missed a fire of any cron worth putting on an
+ * Op, and the alternative — 100k iterations on a clock jump — buys nothing.
+ */
+const MAX_SCAN_MINUTES = 2 * 24 * 60;
+
+/**
+ * True when `expr` fires at some minute in `(after, upTo]` — what a round
+ * asks for an Op it last ticked at `after`. Level-triggered on purpose: a
+ * round that arrives late still ticks the Op it owes rather than waiting for
+ * the next exact match, and several missed fires collapse into the one tick a
+ * convergent verb needs.
+ */
+export function cronDueBetween(expr: string, after: Date, upTo: Date): boolean {
+  if (upTo.getTime() <= after.getTime()) return false;
+
+  const startMs = Math.floor(after.getTime() / 60_000) * 60_000 + 60_000;
+  if (startMs > upTo.getTime()) return false;
+
+  const spanMinutes = Math.floor((upTo.getTime() - startMs) / 60_000) + 1;
+  if (spanMinutes > MAX_SCAN_MINUTES) return true;
+
+  for (let i = 0; i < spanMinutes; i++) {
+    if (cronMatches(expr, new Date(startMs + i * 60_000))) return true;
+  }
+  return false;
+}