@company-semantics/contracts 98.0.0 → 99.1.0

package/src/ingestion/types.ts

@@ -7,7 +7,7 @@
  * private dispatch fields locally) and the app upload UI (which derives its
  * `accept` attribute and supported-formats copy from this).
  *
- * Types only — no runtime behavior. The backend-only normalizer routing
+ * Types plus the `FORMAT_CLASSES` and `TREATMENTS` vocabulary constants. The backend-only normalizer routing
  * (`canonicalKind`, `normalizerKey`) deliberately does NOT live here; it is an
  * implementation detail of the backend dispatch and would pollute the shared
  * vocabulary.
@@ -17,7 +17,7 @@
 
 /**
  * The semantic family a format belongs to. A SURFACE (an upload picker and the
- * route behind it) declares which families it consumes; the accept-set and the
+ * route behind it) declares a treatment per family it consumes; the accept-set and the
  * byte ceiling for that surface derive from the registry through this field.
  * Public and semantic — NOT the backend normalizer dispatch (`canonicalKind` /
  * `normalizerKey` stay backend-local, ADR-CONTRACTS-075).
@@ -27,6 +27,29 @@
 export type IngestionFamily =
   "text" | "document" | "image" | "diagram" | "audio" | "video";
 
+/**
+ * The coarse, provider-agnostic kind of a format, used wherever the system
+ * classes a file without reading it: the Source Sync inventory `mime_class`,
+ * the discovery topology mix, probe groups, and the spreadsheet `source_kind`.
+ * Declared ON the format entry — no consumer keeps an extension → class table.
+ * Canonical order (the inventory CHECK and every derived list follow it).
+ */
+export const FORMAT_CLASSES = [
+  "docs",
+  "slides",
+  "sheets",
+  "pdf",
+  "text",
+  "image",
+  "diagram",
+  "audio",
+  "video",
+] as const;
+export type FormatClass = (typeof FORMAT_CLASSES)[number];
+
+/** A Source Sync inventory class: a format class, or a provider shortcut row. */
+export type InventoryClass = FormatClass | "shortcut";
+
 /**
  * One accepted upload format, keyed by its canonical MIME type.
  *
@@ -35,14 +58,17 @@ export type IngestionFamily =
  * - `extensions` are lowercase, dot-prefixed (e.g. `.docx`).
  * - `label` is the human display GROUP and is intentionally shared across
  *   related formats (`.docx` + `.doc` are both `Word`; the rasters are all
- *   `Image`; `.svg` + `.drawio` are `Diagram`).
+ *   `Image`; `.svg` is `Diagram`).
  * - `family` is the semantic family a surface selects on; every entry has one.
+ * - `class` is the coarse class (one of `FORMAT_CLASSES`); every entry has one.
  */
 export interface IngestionFormat {
   /** Canonical MIME type (the registry key). */
   mime: string;
-  /** Semantic family the format belongs to (what a surface selects on). */
+  /** Semantic family the format belongs to (what a surface declares a treatment for). */
   family: IngestionFamily;
+  /** Coarse class for classing without reading (inventory, topology, probes). */
+  class: FormatClass;
   /** Lowercase, dot-prefixed filename extensions for this format. */
   extensions: readonly string[];
   /** Human display group label (e.g. `Word`, `Image`, `Audio`). */
@@ -51,23 +77,62 @@ export interface IngestionFormat {
   maxBytes: number;
 }
 
-/** The upload surfaces that consume the registry. */
-export type IngestionSurfaceKey = "company-md" | "org-chart";
-
 /**
- * What one upload surface consumes: the families it admits and, optionally, a
- * byte ceiling tighter than the registry caps of those families.
+ * What a surface does with an admitted family. The backend proves at load that
+ * it can perform every declared (surface, family, treatment) for every admitted
+ * format, or it refuses to start.
  *
- * @see ADR-CONTRACTS-159
+ * - `text`: normalize to text only (a PDF is text-extracted).
+ * - `vision`: hand the model the richest native form — images as image parts,
+ *   a PDF as a binary document, text-native formats (docx, csv, …) as text.
+ * - `transcript`: audio/video become a transcript.
+ * - `store`: bytes are kept as-is (after format-preserving preparation such as
+ *   HEIC → JPEG); nothing is extracted.
+ */
+export const TREATMENTS = ["text", "vision", "transcript", "store"] as const;
+export type Treatment = (typeof TREATMENTS)[number];
+
+/** The surfaces that consume the registry. */
+export type IngestionSurfaceKey =
+  "company-md" | "org-chart" | "chat" | "profile-image";
+
+/**
+ * One surface: the treatment it applies per admitted family, and its byte
+ * ceiling. `families` is derived (`familiesOf`), never declared.
  */
 export interface IngestionSurface {
   /** The surface this declaration describes. */
   key: IngestionSurfaceKey;
-  /** Families the surface admits; a format outside them is refused (415). */
-  families: readonly IngestionFamily[];
+  /** Admitted family → what the surface does with it. Absent family = refused (415). */
+  treatments: Readonly<Partial<Record<IngestionFamily, Treatment>>>;
+  /** Surface byte ceiling (required). Caps every admitted format below its registry `maxBytes`. */
+  maxBytes: number;
   /**
-   * Surface-level byte ceiling. When set it caps every admitted format below
-   * its registry `maxBytes`; absent means the registry caps apply as-is.
+   * Most files one turn may carry. Declared only on `chat` (required there,
+   * pinned by test); upload surfaces take one file per request and omit it.
    */
-  maxBytes?: number;
+  maxFilesPerTurn?: number;
+}
+
+/** External sources that hand the pipeline provider-native files. */
+export type IngestionProviderKey = "google-drive";
+
+/** A provider-native type that is exported to a registry format before ingestion. */
+export interface ProviderNativeFormat {
+  /** The provider's own MIME (e.g. a Google Workspace type). */
+  mime: string;
+  /** Human label for the native type (e.g. `Google Doc`). */
+  label: string;
+  /** Registry MIME the provider exports this type to. Must resolve via `byMime`. */
+  exportsTo: string;
+}
+
+/** One provider: its native types and the structural container MIMEs it lists. */
+export interface IngestionProvider {
+  /** The provider this declaration describes. */
+  key: IngestionProviderKey;
+  /** Native types the provider exports to registry formats. */
+  nativeFormats: readonly ProviderNativeFormat[];
+  /** Structural (non-file) MIMEs the provider lists: folders and shortcuts. */
+  containerMimes: { readonly folder: string; readonly shortcut: string };
 }

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",
+    );
+  });
+});