@intentius/chant 0.57.0 → 0.59.0

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

@@ -0,0 +1,78 @@
+/**
+ * PipelineAuditOp composite — the live include/component audit of GitLab
+ * pipelines as a chant Op with an optional schedule (#303).
+ *
+ * The gitlab post-synth checks (#297) own everything answerable from the
+ * deterministic build. This Op owns *only* the checks that require live
+ * resolution against a moving upstream truth — a pinned component/include ref
+ * that no longer resolves, an archived or moved upstream project, or a new
+ * advisory covering a component/image in use. It sits at **observe** on the
+ * lifecycle dial, with a finding-mode (`report | issue | merge-request`) as the
+ * **reconcile** step — for GitLab the PR mode is a merge request.
+ *
+ * Runs one-shot on the local Op executor via `chant run`; a `schedule` puts
+ * the cadence on the Op itself (#2120).
+ *
+ * @example
+ * ```typescript
+ * export const { op } = PipelineAuditOp({
+ *   name: "pipeline-audit",
+ *   schedule: "0 6 * * *",
+ *   onFinding: "merge-request",
+ * });
+ * ```
+ *
+ * @see #297 — the deterministic counterpart this freshens.
+ */
+
+import { Op, phase } from "../builders";
+import type { OpResource } from "../resource";
+import type { PipelineAuditMode } from "../activities/pipeline-audit";
+
+export interface PipelineAuditOpConfig {
+  /** 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`; omit for one-shot. */
+  schedule?: string;
+  /**
+   * Path to the emitted `.gitlab-ci.yml` to audit at run time.
+   * @default ".gitlab-ci.yml"
+   */
+  pipelineFile?: string;
+  /**
+   * What to produce on findings. Default: "report".
+   * @default "report"
+   */
+  onFinding?: PipelineAuditMode;
+}
+
+export interface PipelineAuditOpResources {
+  /** Op resource — the audit Op, emitted on `chant build`. */
+  op: InstanceType<typeof OpResource>;
+}
+
+export function PipelineAuditOp(config: PipelineAuditOpConfig): PipelineAuditOpResources {
+  const onFinding = config.onFinding ?? "report";
+
+  const op = Op({
+    name: config.name,
+    overview: "Resolve pipeline include/component/image references against live upstreams and report drift",
+    labels: {
+      Audit: "true",
+      Surface: "gitlab-pipeline",
+    },
+    ...(config.schedule ? { schedule: { cron: config.schedule, overlap: "skip" as const } } : {}),
+    phases: [
+      phase("Audit", [
+        {
+          kind: "activity",
+          fn: "pipelineSupplyChainAudit",
+          args: { pipelineFile: config.pipelineFile ?? ".gitlab-ci.yml", mode: onFinding },
+          outcomeAttribute: { name: "Findings", from: "findings" },
+        },
+      ]),
+    ],
+  });
+
+  return { op };
+}

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

@@ -0,0 +1,51 @@
+import { describe, test, expect } from "vitest";
+import { ReconcileOp } from "./reconcile-op";
+
+/** Reach into the generated Op's phases → the reconcilePr step. */
+function reconcileStep(op: unknown): Record<string, unknown> {
+  const config = (op as { props: Record<string, unknown> }).props;
+  const phases = config.phases as Array<{ name: string; steps: Array<Record<string, unknown>> }>;
+  const reconcile = phases.find((p) => p.name === "Reconcile");
+  if (!reconcile) throw new Error("no Reconcile phase");
+  return reconcile.steps[0];
+}
+
+describe("ReconcileOp composite — PR/issue URL outcome (#8)", () => {
+  test("pull-request mode (default) exposes prUrl as the PR outcome attribute", () => {
+    const { op } = ReconcileOp({ name: "prod-reconcile", env: "prod" });
+    const step = reconcileStep(op);
+    expect(step.fn).toBe("reconcilePr");
+    expect((step.args as { mode: string }).mode).toBe("pull-request");
+    expect(step.outcomeAttribute).toEqual({ name: "PR", from: "prUrl" });
+  });
+
+  test("issue mode exposes issueUrl as the Issue outcome attribute", () => {
+    const { op } = ReconcileOp({ name: "prod-reconcile", env: "prod", onDrift: "issue" });
+    const step = reconcileStep(op);
+    expect((step.args as { mode: string }).mode).toBe("issue");
+    expect(step.outcomeAttribute).toEqual({ name: "Issue", from: "issueUrl" });
+  });
+
+  test("report mode opens nothing, so carries no URL outcome", () => {
+    const { op } = ReconcileOp({ name: "prod-reconcile", env: "prod", onDrift: "report" });
+    const step = reconcileStep(op);
+    expect((step.args as { mode: string }).mode).toBe("report");
+    expect(step.outcomeAttribute).toBeUndefined();
+  });
+});
+
+describe("ReconcileOp composite — cadence on the op (#2120)", () => {
+  function opProps(op: unknown): Record<string, unknown> {
+    return (op as { props: Record<string, unknown> }).props;
+  }
+
+  test("one-shot form carries no schedule", () => {
+    const { op } = ReconcileOp({ name: "prod-reconcile", env: "prod" });
+    expect(opProps(op).schedule).toBeUndefined();
+  });
+
+  test("a cron lands on the op as { cron, overlap: \"skip\" }", () => {
+    const { op } = ReconcileOp({ name: "prod-reconcile", env: "prod", schedule: "0 * * * *" });
+    expect(opProps(op).schedule).toEqual({ cron: "0 * * * *", overlap: "skip" });
+  });
+});

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

@@ -0,0 +1,110 @@
+/**
+ * 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, or the comment
+  // it posted on the triggering pull request) 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" }
+        : onDrift === "comment"
+          ? { name: "Comment", from: "commentUrl" }
+          : 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);
+  });
+});