@company-semantics/contracts 99.0.0 → 99.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@company-semantics/contracts",
-  "version": "99.0.0",
+  "version": "99.1.0",
   "private": false,
   "repository": {
     "type": "git",

package/src/index.ts

@@ -324,7 +324,10 @@ export * from "./product-intake/index";
 // for one target document; the wire carries facts and a count, never content.
 // See ./source-sync/vocabulary.ts and ./source-sync/schemas.ts.
 export * from "./source-sync/index";
-
 // Quality control plane vocabulary (PRD-01088 / quality-control-plane)
 // Closed evaluation/decision sets plus QualityRunReportSchema — ids, scores and failure kinds only. See ./quality/index.ts.
 export * from "./quality/index";
+// Scheduled-execution vocabulary (PRD-01175 / schedule-execution-wire-types)
+// Schedule definitions, slot-derived execution identity, lifecycle, the pure
+// UTC cron evaluator and the schedule route responses. See ./schedules/README.md.
+export * from "./schedules";

package/src/schedules/README.md

@@ -0,0 +1,118 @@
+# schedules/
+
+The shared vocabulary of scheduled execution: what a schedule promises, how one
+execution of it is named, the states it moves through, and the UTC cron
+evaluator both control and the backend use to decide when a slot is due.
+
+## Purpose
+
+Name, time and track every scheduled job across the fleet with one vocabulary,
+so control (which authors the registry) and the backend (which stores the
+ledger and reconciles) can never disagree about a slot.
+
+## Invariants
+
+- An execution is named by its INTENDED slot: `execution_id = <schedule_id>/<YYYY-MM-DDTHH:MM:00Z>`;
+  a dispatch attempt is `<execution_id>#<attempt>` and is the workflow's `run-name`.
+  A run without one never satisfies a slot.
+- `parseCron` is the only cron evaluator: five fields, UTC, Vixie day matching,
+  no names / `L` / `W` / `#`; an expression that can never fire does not parse.
+- Every ScheduleDefinition declares `effects`; `fenced` and `unsafe` require
+  `idempotency: "required"`; `catchUp: "all"` never replays `unsafe` effects.
+- `canonicalScheduleRegistryJson` is the only serialization the snapshot's
+  `contentHash` is computed over.
+- Response schemas only; request bodies live in the backend beside their routes
+  (ScheduleTickRequest is a type, not a schema).
+- Pure: no clock reads, no I/O, only `zod`.
+
+## Dependencies
+
+`zod` only. Reached through the package root; there is no `./schedules` subpath.
+
+<!-- BEGIN GENERATED: readme-public-api — derived from code by `pnpm readme-api`. Do not edit. -->
+
+## Public API
+
+- `CronField` _(type)_ — Five-field UTC cron evaluator for the schedule registry.
+- `CronParseResult` _(type)_
+- `ParsedCron` _(type)_
+- `ParsedDisplayTitle` _(type)_
+- `ParsedExecutionId` _(type)_
+- `SCHEDULE_CATCH_UP_POLICIES`
+- `SCHEDULE_CLAIM_REFUSALS`
+- `SCHEDULE_CLOCK_SOURCES` — Independent tick sources.
+- `SCHEDULE_DEFINITION_KEYS` — Key order used by canonicalScheduleRegistryJson.
+- `SCHEDULE_DISPATCH_INPUTS` — The workflowdispatch inputs every registered workflow declares once it leaves mode `off`.
+- `SCHEDULE_DISPATCH_OUTCOMES`
+- `SCHEDULE_EFFECTS` — What the workflow's side effects tolerate.
+- `SCHEDULE_EXECUTION_STATES` — Scheduled-execution lifecycle, recovery and incident vocabulary.
+- `SCHEDULE_EXECUTION_TRANSITIONS` — Allowed moves.
+- `SCHEDULE_FINISH_REJECTIONS`
+- `SCHEDULE_IDEMPOTENCY_LEVELS`
+- `SCHEDULE_ID_MAX_LENGTH`
+- `SCHEDULE_ID_PATTERN` — Kebab-case, no `/` or `#`, so an executionid and a display title parse unambiguously.
+- `SCHEDULE_INCIDENT_CLASSES`
+- `SCHEDULE_INFRA_LABEL`
+- `SCHEDULE_LOSS_ACK_LABEL`
+- `SCHEDULE_MAX_CATCH_UP_SLOTS`
+- `SCHEDULE_MAX_TIMEOUT_MINUTES` — GitHub-hosted job ceiling.
+- `SCHEDULE_METRICS_NAMESPACE` — CloudWatch EMF metric names (backend emits; control's watchdog script alarms).
+- `SCHEDULE_METRIC_ENVIRONMENT_DIMENSION` — Every Schedules metric carries this dimension (value: the backend deploy environment, e.g. "production" /…
+- `SCHEDULE_METRIC_RECONCILE_SUCCESS`
+- `SCHEDULE_METRIC_TICK`
+- `SCHEDULE_METRIC_TICK_SOURCE_DIMENSION`
+- `SCHEDULE_MODES` — off: GitHub cron only, clock ignores it. shadow: clock plans, never dispatches. live: clock dispatches…
+- `SCHEDULE_OUTPUT_VERIFIERS` — Closed catalog. v0 has one verifier.
+- `SCHEDULE_REGISTRY_SCHEMA_VERSION`
+- `SCHEDULE_RUN_CONCLUSIONS`
+- `SCHEDULE_RUN_NAME` — The exact `run-name:` a registered workflow declares, so displaytitle = executionid#attempt.
+- `SCHEDULE_SEVERITIES`
+- `SCHEDULE_SLOT_ISO_PATTERN`
+- `SCHEDULE_TICK_PATH` — The tick route.
+- `SCHEDULE_TIMEZONE`
+- `ScheduleCatchUpPolicy` _(type)_
+- `ScheduleClaimRefusal` _(type)_
+- `ScheduleClaimResponse` _(type)_
+- `ScheduleClaimResponseSchema`
+- `ScheduleClockSource` _(type)_
+- `ScheduleDefinition` _(type)_
+- `ScheduleDefinitionSchema`
+- `ScheduleDispatchInput` _(type)_
+- `ScheduleDispatchOutcome` _(type)_
+- `ScheduleEffects` _(type)_
+- `ScheduleExecutionSettlementInput` _(type)_
+- `ScheduleExecutionState` _(type)_
+- `ScheduleFinishRejection` _(type)_
+- `ScheduleFinishResponse` _(type)_
+- `ScheduleFinishResponseSchema`
+- `ScheduleIdempotency` _(type)_
+- `ScheduleIncidentClass` _(type)_
+- `ScheduleMode` _(type)_
+- `ScheduleOutputVerifier` _(type)_
+- `ScheduleRegistrySnapshot` _(type)_
+- `ScheduleRegistrySnapshotSchema`
+- `ScheduleRunConclusion` _(type)_
+- `ScheduleSeverity` _(type)_
+- `ScheduleTickRequest` _(type)_ — Tick request body, as a TYPE only: request schemas stay in the backend beside the route (contracts…
+- `ScheduleTickResponse` _(type)_
+- `ScheduleTickResponseSchema` — One tick's outcome, reported to the tick source that triggered it.
+- `SlotWindow` _(type)_
+- `canTransitionScheduleExecution`
+- `canonicalScheduleRegistryJson` — Deterministic serialization: definitions sorted by id, keys in SCHEDULEDEFINITIONKEYS order, no whitespace.
+- `cronMatches` — True when `instant` is exactly a slot of `cron` (whole minute, UTC).
+- `displayTitleFor`
+- `executionIdFor`
+- `isScheduleExecutionSettled` — Settled = nothing further will happen to this slot without a human.
+- `isScheduleId`
+- `maxIntervalMinutes` — The longest gap, in minutes, between consecutive slots among the `samples` intervals ending at or before…
+- `mayReexecuteAutomatically` — none: read-only. idempotent: downstream writes keyed by executionid. fenced: downstream writes carry…
+- `nextSlot` — The earliest slot strictly after `after`, or null when none exists in the search window.
+- `parseCron` — Parse a five-field UTC cron expression.
+- `parseDisplayTitle` — Inverse of displayTitleFor; null for any run title that is not a scheduled dispatch.
+- `parseExecutionId`
+- `previousSlot` — The latest slot at or before `atOrBefore`, or null when none exists in the search window.
+- `scheduleIncidentKey` — Dedupe key for an incident.
+- `slotIso` — `YYYY-MM-DDTHH:MM:00Z`.
+- `slotsBetween` — Slots in (afterExclusive, atOrBefore, newest `limit` kept, returned ascending.
+
+<!-- END GENERATED: readme-public-api -->

package/src/schedules/__tests__/README.md

@@ -0,0 +1,27 @@
+# schedules/\_\_tests\_\_/
+
+## Purpose
+
+Locks the scheduled-execution vocabulary's behavior with table tests.
+
+- `cron.test.ts` — locks the UTC cron evaluator: every cron the fleet's
+  workflows carry today parses (the `IN_USE` table, measured 2026-10-10);
+  unsupported syntax (names, `L`, `W`, `#`, `?`, macros, a step on a single
+  value) and expressions that can never fire are rejected; day-of-week 7 folds
+  into Sunday; Vixie day matching (OR only when both day fields are restricted);
+  previous/next slots across month ends and leap days; truncated slot windows
+  keep the newest slots; and the longest interval of an irregular schedule.
+
+## Invariants
+
+- Every instant is passed in explicitly; no test reads the clock.
+- The `IN_USE` table is a measurement of the fleet's workflows. A new cron in a
+  workflow belongs here too, so the evaluator is proven against it.
+
+## Public API
+
+None — test-only.
+
+## Dependencies
+
+`vitest` and `../cron`.

package/src/schedules/__tests__/api.test.ts

@@ -0,0 +1,72 @@
+import { describe, expect, it } from "vitest";
+import {
+  SCHEDULE_METRICS_NAMESPACE,
+  SCHEDULE_METRIC_RECONCILE_SUCCESS,
+  SCHEDULE_METRIC_TICK,
+  SCHEDULE_METRIC_TICK_SOURCE_DIMENSION,
+  SCHEDULE_METRIC_ENVIRONMENT_DIMENSION,
+  SCHEDULE_TICK_PATH,
+  ScheduleClaimResponseSchema,
+  ScheduleFinishResponseSchema,
+  ScheduleTickResponseSchema,
+} from "../api";
+
+describe("schedules api responses", () => {
+  it("admits a legacy run without an execution id", () => {
+    expect(
+      ScheduleClaimResponseSchema.safeParse({
+        outcome: "legacy",
+        scheduleId: "pin-audit",
+        mode: "shadow",
+      }).success,
+    ).toBe(true);
+    expect(
+      ScheduleClaimResponseSchema.safeParse({
+        outcome: "legacy",
+        scheduleId: "pin-audit",
+        mode: "shadow",
+        executionId: "x",
+      }).success,
+    ).toBe(false);
+    expect(
+      ScheduleClaimResponseSchema.safeParse({
+        outcome: "refused",
+        reason: "legacy_run_not_admitted",
+      }).success,
+    ).toBe(true);
+    expect(
+      ScheduleFinishResponseSchema.safeParse({
+        recorded: false,
+        reason: "stale_epoch",
+      }).success,
+    ).toBe(true);
+    expect(
+      ScheduleTickResponseSchema.safeParse({
+        source: "edge",
+        tickedAt: "2026-10-10T10:00:00Z",
+        reconcileOk: true,
+        registryVersion: null,
+        dispatched: 0,
+        incidentsOpened: 0,
+        incidentsResolved: 0,
+      }).success,
+    ).toBe(true);
+  });
+
+  it("keeps the tick path and metric names stable", () => {
+    expect(SCHEDULE_TICK_PATH).toBe("/api/schedules/tick");
+    expect([
+      SCHEDULE_METRICS_NAMESPACE,
+      SCHEDULE_METRIC_TICK,
+      SCHEDULE_METRIC_TICK_SOURCE_DIMENSION,
+      SCHEDULE_METRIC_RECONCILE_SUCCESS,
+      SCHEDULE_METRIC_ENVIRONMENT_DIMENSION,
+    ]).toEqual([
+      "Schedules",
+      "Tick",
+      "source",
+      "ReconcileSuccess",
+      "environment",
+    ]);
+  });
+});

package/src/schedules/__tests__/cron.test.ts

@@ -0,0 +1,140 @@
+import { describe, expect, it } from "vitest";
+import {
+  maxIntervalMinutes,
+  nextSlot,
+  parseCron,
+  previousSlot,
+  slotsBetween,
+  type ParsedCron,
+} from "../cron";
+
+function cron(expression: string): ParsedCron {
+  const result = parseCron(expression);
+  if (!result.ok) throw new Error(`${expression}: ${result.reason}`);
+  return result.cron;
+}
+
+const at = (iso: string) => new Date(iso);
+const iso = (d: Date | null) => (d === null ? null : d.toISOString());
+
+/** Every distinct cron on the seven Node repos' origin/main workflows, measured 2026-10-10. */
+const IN_USE = [
+  "*/30 * * * *",
+  "7 * * * *",
+  "13,43 * * * *",
+  "17 * * * *",
+  "30 */6 * * *",
+  "0 6 * * *",
+  "0 7 * * *",
+  "0 8 * * *",
+  "0 10 * * *",
+  "0 14 * * *",
+  "0 15 * * *",
+  "17 16 * * *",
+  "17 9 * * 1",
+  "30 9 * * 1,4",
+  "0 2 * * *",
+  "0 3 * * *",
+  "0 4 * * *",
+  "20 4 * * *",
+  "30 4 * * *",
+  "40 4 * * *",
+  "17 5 * * *",
+  "50 5 * * *",
+];
+
+describe("schedules cron", () => {
+  it("parses every cron the registry carries today", () => {
+    for (const expression of IN_USE)
+      expect(parseCron(expression).ok).toBe(true);
+  });
+
+  it("rejects names, L/W/#, a step on a single value and impossible dates", () => {
+    for (const expression of [
+      "0 0 * JAN *",
+      "0 0 * * MON",
+      "0 0 L * *",
+      "0 0 1W * *",
+      "0 0 * * 1#2",
+      "0 0 ? * *",
+      "@hourly",
+      "5/15 * * * *",
+      "60 * * * *",
+      "* * *",
+      "0 0 31 2 *",
+    ]) {
+      expect(parseCron(expression).ok).toBe(false);
+    }
+  });
+
+  it("folds day-of-week 7 into Sunday", () => {
+    expect(iso(nextSlot(cron("0 0 * * 7"), at("2026-10-10T13:25:00Z")))).toBe(
+      "2026-10-11T00:00:00.000Z",
+    );
+  });
+
+  it("applies Vixie OR when both day fields are restricted", () => {
+    const c = cron("0 0 1 * 0");
+    // Sunday 2026-10-11 matches day-of-week even though it is not the 1st.
+    expect(iso(nextSlot(c, at("2026-10-10T13:25:00Z")))).toBe(
+      "2026-10-11T00:00:00.000Z",
+    );
+  });
+
+  it("treats a star-step day-of-month as unrestricted (Vixie)", () => {
+    // */2 counts as unrestricted, so both must match: odd day AND Sunday.
+    const c = cron("0 0 */2 * 0");
+    expect(iso(nextSlot(c, at("2026-10-12T00:00:00Z")))).toBe(
+      "2026-10-25T00:00:00.000Z",
+    );
+  });
+
+  it("finds the previous and next slot across month ends and leap days", () => {
+    expect(iso(nextSlot(cron("0 0 31 * *"), at("2026-10-31T00:00:00Z")))).toBe(
+      "2026-12-31T00:00:00.000Z",
+    );
+    const leap = cron("0 0 29 2 *");
+    expect(iso(previousSlot(leap, at("2026-10-10T00:00:00Z")))).toBe(
+      "2024-02-29T00:00:00.000Z",
+    );
+    expect(iso(nextSlot(leap, at("2026-10-10T00:00:00Z")))).toBe(
+      "2028-02-29T00:00:00.000Z",
+    );
+    expect(
+      iso(previousSlot(cron("*/30 * * * *"), at("2026-10-10T13:00:00Z"))),
+    ).toBe("2026-10-10T13:00:00.000Z");
+  });
+
+  it("keeps the newest slots when a window is truncated", () => {
+    const window = slotsBetween(
+      cron("*/5 * * * *"),
+      at("2026-10-10T12:00:00Z"),
+      at("2026-10-10T13:00:00Z"),
+      4,
+    );
+    expect(window.truncated).toBe(true);
+    expect(window.slots.map(iso)).toEqual([
+      "2026-10-10T12:45:00.000Z",
+      "2026-10-10T12:50:00.000Z",
+      "2026-10-10T12:55:00.000Z",
+      "2026-10-10T13:00:00.000Z",
+    ]);
+    const exact = slotsBetween(
+      cron("*/30 * * * *"),
+      at("2026-10-10T12:00:00Z"),
+      at("2026-10-10T13:00:00Z"),
+      10,
+    );
+    expect(exact).toEqual({
+      slots: [at("2026-10-10T12:30:00Z"), at("2026-10-10T13:00:00Z")],
+      truncated: false,
+    });
+  });
+
+  it("measures the longest interval of an irregular schedule", () => {
+    const now = at("2026-10-10T13:25:52Z");
+    expect(maxIntervalMinutes(cron("13,43 * * * *"), now)).toBe(30);
+    expect(maxIntervalMinutes(cron("30 9 * * 1,4"), now)).toBe(4 * 24 * 60);
+    expect(maxIntervalMinutes(cron("17 9 * * 1"), now)).toBe(7 * 24 * 60);
+  });
+});

package/src/schedules/__tests__/definition.test.ts

@@ -0,0 +1,97 @@
+import { describe, expect, it } from "vitest";
+import {
+  ScheduleDefinitionSchema,
+  ScheduleRegistrySnapshotSchema,
+  canonicalScheduleRegistryJson,
+  type ScheduleDefinition,
+} from "../definition";
+
+const PRODUCTION_SIGNALS: ScheduleDefinition = {
+  id: "production-signals-signals",
+  repo: "company-semantics-control",
+  workflow: "production-signals.yml",
+  cron: "*/30 * * * *",
+  timezone: "UTC",
+  graceMinutes: 5,
+  timeoutMinutes: 15,
+  admissionTimeoutMinutes: 10,
+  catchUp: "latest",
+  maxCatchUpSlots: 4,
+  idempotency: "required",
+  effects: "idempotent",
+  verify: "production_signal_fresh",
+  mode: "off",
+  severity: "red-main",
+};
+
+describe("schedules definition", () => {
+  it("accepts the production-signals definition", () => {
+    expect(ScheduleDefinitionSchema.safeParse(PRODUCTION_SIGNALS).success).toBe(
+      true,
+    );
+  });
+
+  it("requires idempotency required for fenced or unsafe effects", () => {
+    for (const effects of ["fenced", "unsafe"] as const) {
+      const result = ScheduleDefinitionSchema.safeParse({
+        ...PRODUCTION_SIGNALS,
+        effects,
+        idempotency: "best_effort",
+      });
+      expect(result.success).toBe(false);
+    }
+    const replayUnsafe = ScheduleDefinitionSchema.safeParse({
+      ...PRODUCTION_SIGNALS,
+      effects: "unsafe",
+      catchUp: "all",
+    });
+    expect(replayUnsafe.success).toBe(false);
+  });
+
+  it("rejects an unknown field", () => {
+    expect(
+      ScheduleDefinitionSchema.safeParse({ ...PRODUCTION_SIGNALS, extra: 1 })
+        .success,
+    ).toBe(false);
+    expect(
+      ScheduleDefinitionSchema.safeParse({
+        ...PRODUCTION_SIGNALS,
+        cron: "0 0 31 2 *",
+      }).success,
+    ).toBe(false);
+    expect(
+      ScheduleDefinitionSchema.safeParse({
+        ...PRODUCTION_SIGNALS,
+        timezone: "America/New_York",
+      }).success,
+    ).toBe(false);
+  });
+
+  it("serializes the registry canonically regardless of input order", () => {
+    const other: ScheduleDefinition = {
+      ...PRODUCTION_SIGNALS,
+      id: "audit-rollup",
+      cron: "0 6 * * *",
+    };
+    const reordered = Object.fromEntries(
+      Object.entries(PRODUCTION_SIGNALS).reverse(),
+    ) as ScheduleDefinition;
+    expect(canonicalScheduleRegistryJson([PRODUCTION_SIGNALS, other])).toBe(
+      canonicalScheduleRegistryJson([other, reordered]),
+    );
+    expect(
+      canonicalScheduleRegistryJson([other]).startsWith(
+        '[{"id":"audit-rollup","repo"',
+      ),
+    ).toBe(true);
+  });
+
+  it("rejects a snapshot with duplicate ids", () => {
+    const result = ScheduleRegistrySnapshotSchema.safeParse({
+      schemaVersion: 1,
+      contentHash: "a".repeat(64),
+      schedules: [PRODUCTION_SIGNALS, PRODUCTION_SIGNALS],
+    });
+    expect(result.success).toBe(false);
+  });
+});

package/src/schedules/__tests__/execution.test.ts

@@ -0,0 +1,75 @@
+import { describe, expect, it } from "vitest";
+import {
+  SCHEDULE_EXECUTION_STATES,
+  SCHEDULE_EXECUTION_TRANSITIONS,
+  canTransitionScheduleExecution,
+  isScheduleExecutionSettled,
+  mayReexecuteAutomatically,
+  scheduleIncidentKey,
+} from "../execution";
+
+describe("schedules execution lifecycle", () => {
+  it("allows no transition out of a terminal state", () => {
+    for (const terminal of [
+      "output_verified",
+      "superseded",
+      "missed",
+      "acknowledged_loss",
+    ] as const) {
+      expect(SCHEDULE_EXECUTION_TRANSITIONS[terminal]).toEqual([]);
+    }
+    for (const state of SCHEDULE_EXECUTION_STATES) {
+      for (const target of SCHEDULE_EXECUTION_TRANSITIONS[state]) {
+        expect(SCHEDULE_EXECUTION_STATES).toContain(target);
+      }
+    }
+    expect(
+      canTransitionScheduleExecution(
+        "dispatch_requested",
+        "dispatch_requested",
+      ),
+    ).toBe(true);
+    expect(canTransitionScheduleExecution("started", "superseded")).toBe(false);
+  });
+
+  it("settles a successful completion only without a verifier", () => {
+    expect(
+      isScheduleExecutionSettled({
+        state: "completed",
+        conclusion: "success",
+        requiresVerification: false,
+      }),
+    ).toBe(true);
+    expect(
+      isScheduleExecutionSettled({
+        state: "completed",
+        conclusion: "success",
+        requiresVerification: true,
+      }),
+    ).toBe(false);
+    expect(
+      isScheduleExecutionSettled({
+        state: "completed",
+        conclusion: "failure",
+        requiresVerification: false,
+      }),
+    ).toBe(false);
+    expect(
+      isScheduleExecutionSettled({
+        state: "timed_out",
+        conclusion: null,
+        requiresVerification: false,
+      }),
+    ).toBe(false);
+  });
+
+  it("never re-executes unsafe effects automatically", () => {
+    expect(mayReexecuteAutomatically("unsafe")).toBe(false);
+    for (const effects of ["none", "idempotent", "fenced"] as const) {
+      expect(mayReexecuteAutomatically(effects)).toBe(true);
+    }
+    expect(scheduleIncidentKey("delivery", "pin-audit")).toBe(
+      "schedule:delivery:pin-audit",
+    );
+  });
+});

package/src/schedules/__tests__/identity.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, it } from "vitest";
+import {
+  displayTitleFor,
+  executionIdFor,
+  parseDisplayTitle,
+  parseExecutionId,
+  slotIso,
+} from "../identity";
+
+describe("schedules identity", () => {
+  it("round-trips an execution id and a display title", () => {
+    const slot = new Date("2026-10-10T10:00:00Z");
+    const executionId = executionIdFor("production-signals-signals", slot);
+    expect(executionId).toBe("production-signals-signals/2026-10-10T10:00:00Z");
+    expect(parseExecutionId(executionId)).toEqual({
+      scheduleId: "production-signals-signals",
+      slot,
+    });
+    expect(displayTitleFor(executionId, 2)).toBe(
+      "production-signals-signals/2026-10-10T10:00:00Z#2",
+    );
+    expect(parseDisplayTitle(displayTitleFor(executionId, 2))).toEqual({
+      scheduleId: "production-signals-signals",
+      slot,
+      executionId,
+      attempt: 2,
+    });
+  });
+
+  it("refuses a slot that is not a whole UTC minute", () => {
+    expect(() => slotIso(new Date("2026-10-10T10:00:30Z"))).toThrow(RangeError);
+    expect(parseExecutionId("x/2026-10-10T10:00:30Z")).toBeNull();
+    expect(() =>
+      executionIdFor("Bad/Id", new Date("2026-10-10T10:00:00Z")),
+    ).toThrow(RangeError);
+    expect(() => displayTitleFor("x/2026-10-10T10:00:00Z", 0)).toThrow(
+      RangeError,
+    );
+  });
+
+  it("does not parse a manual run title", () => {
+    for (const title of [
+      "Production signals",
+      "x/2026-10-10T10:00:00Z",
+      "x/2026-10-10T10:00:00Z#0",
+      "#1",
+    ]) {
+      expect(parseDisplayTitle(title)).toBeNull();
+    }
+  });
+});

package/src/schedules/__tests__/schedules-exports.test.ts

@@ -0,0 +1,26 @@
+import { describe, expect, it } from "vitest";
+import * as root from "../../index";
+
+describe("schedules exports", () => {
+  it("exports the scheduled-execution vocabulary from the package root", () => {
+    for (const name of [
+      "parseCron",
+      "previousSlot",
+      "slotsBetween",
+      "executionIdFor",
+      "parseDisplayTitle",
+      "SCHEDULE_RUN_NAME",
+      "SCHEDULE_DISPATCH_INPUTS",
+      "SCHEDULE_EXECUTION_TRANSITIONS",
+      "SCHEDULE_EFFECTS",
+      "ScheduleDefinitionSchema",
+      "ScheduleRegistrySnapshotSchema",
+      "canonicalScheduleRegistryJson",
+      "ScheduleClaimResponseSchema",
+      "SCHEDULE_TICK_PATH",
+      "SCHEDULE_METRICS_NAMESPACE",
+    ]) {
+      expect(root).toHaveProperty(name);
+    }
+  });
+});