@greatwait/contracts 0.3.0 → 0.3.2

package/dist/service-mode.d.ts

@@ -0,0 +1,88 @@
+/** The modes a request may name. `auto` is what omission means. */
+export declare const REQUESTED_LATENCY_CLASSES: readonly ["auto", "bulk", "realtime"];
+export type RequestedLatencyClass = (typeof REQUESTED_LATENCY_CLASSES)[number];
+/** The concrete services an occurrence resolves to. */
+export type ResolvedLatencyClass = "bulk" | "realtime";
+/** The internal bands. Not on the wire: only the concrete service is. */
+export declare const SERVICE_BANDS: readonly ["realtime", "short_bulk", "bulk"];
+export type ServiceBand = (typeof SERVICE_BANDS)[number];
+export interface ServiceResolution {
+    readonly band: ServiceBand;
+    readonly latencyClass: ResolvedLatencyClass;
+    readonly quantumMs: number;
+}
+/** The concrete service a band is charged and reported as. */
+export declare function bandLatencyClass(band: ServiceBand): ResolvedLatencyClass;
+/**
+ * The service, band and quantum for one occurrence.
+ *
+ * `spacingMs` is the one-off lead or the recurrence's shorter adjacent gap
+ * (see the module comment). A non-finite spacing — a recurrence with no
+ * adjacent instant — is treated as long.
+ */
+export declare function resolveService(requested: RequestedLatencyClass, spacingMs: number): ServiceResolution;
+/** A one-off's lead: planned instant minus the captured acceptance time. */
+export declare function oneOffSpacingMs(acceptedAtMs: number, plannedForMs: number): number;
+/**
+ * A recurrence occurrence's shorter adjacent planned gap. Either neighbour may
+ * be unknown — a series' first occurrence has no predecessor — and the gap to
+ * a known neighbour decides alone.
+ */
+export declare function recurrenceSpacingMs(previousMs: number | undefined, plannedForMs: number, nextMs: number | undefined): number;
+/**
+ * An instant's first eligibility in its band: `ceil(instant / quantum) *
+ * quantum`, so a boundary stays where it is.
+ *
+ * Applied once, to the planned instant or to a retry's backed-off instant.
+ * Work that becomes claimable late is claimable now, never at another
+ * boundary: nothing rounds a rounded instant, and nothing rounds `now`. The
+ * last quantum of year 9999 has no boundary the contract can name, so it is
+ * eligible at the end of that year instead.
+ */
+export declare function roundEligibilityMs(instantMs: number, band: ServiceBand): number;
+export interface OccurrenceResolution extends ServiceResolution {
+    /** `plannedForMs` rounded up to the band's quantum. */
+    readonly eligibleAtMs: number;
+}
+/**
+ * One occurrence's service, band and rounded first eligibility: the entry
+ * point create, replacement and a recurrence's successor all use.
+ *
+ * A one-off is measured from its captured acceptance time; a recurrence by its
+ * neighbours, which the caller took from the existing recurrence evaluator.
+ */
+export declare function resolveOccurrence(input: {
+    readonly kind: "one-off";
+    readonly requested: RequestedLatencyClass;
+    readonly acceptedAtMs: number;
+    readonly plannedForMs: number;
+} | {
+    readonly kind: "recurring";
+    readonly requested: RequestedLatencyClass;
+    readonly plannedForMs: number;
+    readonly previousMs?: number;
+    readonly nextMs?: number;
+}): OccurrenceResolution;
+/** Stored requested intent; `legacy` predates recording it (W12-02). */
+export type StoredRequestedLatencyClass = RequestedLatencyClass | "legacy";
+/**
+ * What a replacement runs under (implementation-guide § W02, step 4).
+ *
+ * - A request naming a mode other than the stored one is a mode edit.
+ * - A timing or cadence edit resolves again. An explicit stored mode survives
+ *   it; a legacy schedule's enters `auto`.
+ * - Anything else — payload, headers, name, tags, a mode named as it already
+ *   was — preserves the stored service and tariff, and a legacy schedule stays
+ *   legacy.
+ */
+export declare function replacementMode(input: {
+    readonly stored: StoredRequestedLatencyClass;
+    readonly requested: RequestedLatencyClass | undefined;
+    readonly timingChanged: boolean;
+}): {
+    readonly kind: "preserve";
+    readonly requested: StoredRequestedLatencyClass;
+} | {
+    readonly kind: "resolve";
+    readonly requested: RequestedLatencyClass;
+};

package/dist/service-mode.js

@@ -0,0 +1,130 @@
+/**
+ * W12-02 (FXO-3171): the one resolver for service modes.
+ *
+ * Design: docs/archive/warm-worker-scheduling/project-spec.md § Customer
+ * contract, and implementation-guide.md § W02. A request names a mode —
+ * `auto`, `bulk` or `realtime` — and every occurrence resolves to a concrete
+ * service (`bulk` or `realtime`, what is charged and what a read reports), an
+ * internal band (`realtime`, `short_bulk` or `bulk`) and that band's quantum.
+ *
+ * Pure: every input is a parameter, nothing here reads a clock, and the
+ * spacing it classifies by is measured by the caller from instants the
+ * existing recurrence evaluator produced. There is deliberately no cron
+ * arithmetic in this module: a second evaluator is a second opinion about when
+ * a schedule fires, and two opinions eventually disagree.
+ *
+ * The spacing is:
+ *
+ * - for a one-off, the lead from the captured acceptance time to the original
+ *   planned instant (an instant already past has no lead), measured once at
+ *   acceptance — a replayed request reads the stored answer and never measures
+ *   again; and
+ * - for a recurrence, the shorter adjacent planned gap. A one-minute heartbeat
+ *   is short bulk however soon its next run happens to be due.
+ *
+ * Every recurrence the product accepts is at least a minute apart — `every`
+ * starts at sixty seconds and cron names whole minutes — so `auto` never
+ * resolves a recurrence to `realtime`, and an occurrence's service is the
+ * schedule's for its whole series. Only the band moves with irregular gaps.
+ */
+import { SERVICE_MODE_POLICY } from "./operational-config.js";
+/** The modes a request may name. `auto` is what omission means. */
+export const REQUESTED_LATENCY_CLASSES = ["auto", "bulk", "realtime"];
+/** The internal bands. Not on the wire: only the concrete service is. */
+export const SERVICE_BANDS = ["realtime", "short_bulk", "bulk"];
+/** The concrete service a band is charged and reported as. */
+export function bandLatencyClass(band) {
+    return band === "realtime" ? "realtime" : "bulk";
+}
+/**
+ * The service, band and quantum for one occurrence.
+ *
+ * `spacingMs` is the one-off lead or the recurrence's shorter adjacent gap
+ * (see the module comment). A non-finite spacing — a recurrence with no
+ * adjacent instant — is treated as long.
+ */
+export function resolveService(requested, spacingMs) {
+    const spacing = Number.isNaN(spacingMs) ? Infinity : Math.max(0, spacingMs);
+    const band = requested === "realtime" ||
+        (requested === "auto" && spacing < SERVICE_MODE_POLICY.autoRealtimeBelowMs)
+        ? "realtime"
+        : spacing < SERVICE_MODE_POLICY.shortBulkBelowMs
+            ? "short_bulk"
+            : "bulk";
+    return {
+        band,
+        latencyClass: bandLatencyClass(band),
+        quantumMs: SERVICE_MODE_POLICY.quantumMs[band],
+    };
+}
+/** A one-off's lead: planned instant minus the captured acceptance time. */
+export function oneOffSpacingMs(acceptedAtMs, plannedForMs) {
+    return plannedForMs - acceptedAtMs;
+}
+/**
+ * A recurrence occurrence's shorter adjacent planned gap. Either neighbour may
+ * be unknown — a series' first occurrence has no predecessor — and the gap to
+ * a known neighbour decides alone.
+ */
+export function recurrenceSpacingMs(previousMs, plannedForMs, nextMs) {
+    const gaps = [
+        previousMs === undefined ? Infinity : plannedForMs - previousMs,
+        nextMs === undefined ? Infinity : nextMs - plannedForMs,
+    ].filter((gap) => gap > 0);
+    return gaps.length === 0 ? Infinity : Math.min(...gaps);
+}
+/** The last instant the contract's four-digit-year timestamps express. */
+const LATEST_EXPRESSIBLE_MS = Date.parse("9999-12-31T23:59:59.999Z");
+/**
+ * An instant's first eligibility in its band: `ceil(instant / quantum) *
+ * quantum`, so a boundary stays where it is.
+ *
+ * Applied once, to the planned instant or to a retry's backed-off instant.
+ * Work that becomes claimable late is claimable now, never at another
+ * boundary: nothing rounds a rounded instant, and nothing rounds `now`. The
+ * last quantum of year 9999 has no boundary the contract can name, so it is
+ * eligible at the end of that year instead.
+ */
+export function roundEligibilityMs(instantMs, band) {
+    const quantum = SERVICE_MODE_POLICY.quantumMs[band];
+    return Math.min(Math.ceil(instantMs / quantum) * quantum, Math.max(instantMs, LATEST_EXPRESSIBLE_MS));
+}
+/**
+ * One occurrence's service, band and rounded first eligibility: the entry
+ * point create, replacement and a recurrence's successor all use.
+ *
+ * A one-off is measured from its captured acceptance time; a recurrence by its
+ * neighbours, which the caller took from the existing recurrence evaluator.
+ */
+export function resolveOccurrence(input) {
+    const spacing = input.kind === "one-off"
+        ? oneOffSpacingMs(input.acceptedAtMs, input.plannedForMs)
+        : recurrenceSpacingMs(input.previousMs, input.plannedForMs, input.nextMs);
+    const resolution = resolveService(input.requested, spacing);
+    return {
+        ...resolution,
+        eligibleAtMs: roundEligibilityMs(input.plannedForMs, resolution.band),
+    };
+}
+/**
+ * What a replacement runs under (implementation-guide § W02, step 4).
+ *
+ * - A request naming a mode other than the stored one is a mode edit.
+ * - A timing or cadence edit resolves again. An explicit stored mode survives
+ *   it; a legacy schedule's enters `auto`.
+ * - Anything else — payload, headers, name, tags, a mode named as it already
+ *   was — preserves the stored service and tariff, and a legacy schedule stays
+ *   legacy.
+ */
+export function replacementMode(input) {
+    if (input.requested !== undefined && input.requested !== input.stored) {
+        return { kind: "resolve", requested: input.requested };
+    }
+    if (input.timingChanged) {
+        return {
+            kind: "resolve",
+            requested: input.stored === "legacy" ? "auto" : input.stored,
+        };
+    }
+    return { kind: "preserve", requested: input.stored };
+}

package/dist/signatures.d.ts

@@ -409,7 +409,7 @@ export declare const CALLBACK_DELIVERY_PROTOCOL: {
         };
         readonly secret: "greatwait-signature-vector-key-not-a-credential";
         readonly signingInputBase64: "MjAyNi0wNy0yOFQxNTowMDowMC4wMDBaLmRsdl8wMTIzNDU2Nzg5YWJjZGVmZ2hqa21ucHFycy57InZlcnNpb24iOiIyMDI2LTA3LTAxIiwidHlwZSI6InNjaGVkdWxlLm9jY3VycmVuY2UiLCJzY2hlZHVsZUlkIjoic2NoXzAxMjM0NTY3ODlhYmNkZWZnaGprbW5wcXJzIiwib2NjdXJyZW5jZUlkIjoib2NjXzAxMjM0NTY3ODlhYmNkZWZnaGprbW5wcXJzIiwicGxhbm5lZEZvciI6IjIwMjYtMDctMjhUMTU6MDA6MDAuMDAwWiIsImF0dGVtcHQiOjEsImRhdGEiOnt9fQ==";
-        readonly signingInputUtf8: "2026-07-28T15:00:00.000Z.dlv_0123456789abcdefghjkmnpqrs.{\"version\":\"2026-07-01\",\"type\":\"schedule.occurrence\",\"scheduleId\":\"sch_0123456789abcdefghjkmnpqrs\",\"occurrenceId\":\"occ_0123456789abcdefghjkmnpqrs\",\"plannedFor\":\"2026-07-28T15:00:00.000Z\",\"attempt\":1,\"data\":{}}";
+        readonly signingInputUtf8: string;
     };
     /**
      * The retired `2026-08-08` envelope **without** `completion`, kept as a known
@@ -445,7 +445,7 @@ export declare const CALLBACK_DELIVERY_PROTOCOL: {
         };
         readonly secret: "greatwait-signature-vector-key-not-a-credential";
         readonly signingInputBase64: "MjAyNi0wNy0yOFQxNTowMDowMC4wMDBaLmRsdl8wMTIzNDU2Nzg5YWJjZGVmZ2hqa21ucHFycy57InZlcnNpb24iOiIyMDI2LTA4LTA4IiwidHlwZSI6InNjaGVkdWxlLm9jY3VycmVuY2UiLCJzY2hlZHVsZUlkIjoic2NoXzAxMjM0NTY3ODlhYmNkZWZnaGprbW5wcXJzIiwib2NjdXJyZW5jZUlkIjoib2NjXzAxMjM0NTY3ODlhYmNkZWZnaGprbW5wcXJzIiwicGxhbm5lZEZvciI6IjIwMjYtMDctMjhUMTU6MDA6MDAuMDAwWiIsImF0dGVtcHQiOjEsInRyaWdnZXIiOnsia2luZCI6ImF1dG9tYXRpYyJ9LCJkYXRhIjp7fX0=";
-        readonly signingInputUtf8: "2026-07-28T15:00:00.000Z.dlv_0123456789abcdefghjkmnpqrs.{\"version\":\"2026-08-08\",\"type\":\"schedule.occurrence\",\"scheduleId\":\"sch_0123456789abcdefghjkmnpqrs\",\"occurrenceId\":\"occ_0123456789abcdefghjkmnpqrs\",\"plannedFor\":\"2026-07-28T15:00:00.000Z\",\"attempt\":1,\"trigger\":{\"kind\":\"automatic\"},\"data\":{}}";
+        readonly signingInputUtf8: string;
     };
     /**
      * The retired `2026-08-08` envelope **with** `completion`, kept as a known
@@ -489,7 +489,7 @@ export declare const CALLBACK_DELIVERY_PROTOCOL: {
         };
         readonly secret: "greatwait-signature-vector-key-not-a-credential";
         readonly signingInputBase64: "MjAyNi0wNy0yOFQxNTowMDowMC4wMDBaLmRsdl8wMTIzNDU2Nzg5YWJjZGVmZ2hqa21ucHFycy57InZlcnNpb24iOiIyMDI2LTA4LTA4IiwidHlwZSI6InNjaGVkdWxlLm9jY3VycmVuY2UiLCJzY2hlZHVsZUlkIjoic2NoXzAxMjM0NTY3ODlhYmNkZWZnaGprbW5wcXJzIiwib2NjdXJyZW5jZUlkIjoib2NjXzAxMjM0NTY3ODlhYmNkZWZnaGprbW5wcXJzIiwicGxhbm5lZEZvciI6IjIwMjYtMDctMjhUMTU6MDA6MDAuMDAwWiIsImF0dGVtcHQiOjEsImNvbXBsZXRpb24iOnsidG9rZW4iOiJ2MS5leGFtcGxlLWNsYWltLW5vdC1hLXJlYWwtdG9rZW4uZXhhbXBsZS1tYWMiLCJ1cmwiOiJodHRwczovL2dyZWF0d2FpdC1zY2hlZHVsZXIuZXhhbXBsZS9jYWxsYmFja3MvY29tcGxldGlvbiJ9LCJ0cmlnZ2VyIjp7ImtpbmQiOiJhdXRvbWF0aWMifSwiZGF0YSI6e319";
-        readonly signingInputUtf8: "2026-07-28T15:00:00.000Z.dlv_0123456789abcdefghjkmnpqrs.{\"version\":\"2026-08-08\",\"type\":\"schedule.occurrence\",\"scheduleId\":\"sch_0123456789abcdefghjkmnpqrs\",\"occurrenceId\":\"occ_0123456789abcdefghjkmnpqrs\",\"plannedFor\":\"2026-07-28T15:00:00.000Z\",\"attempt\":1,\"completion\":{\"token\":\"v1.example-claim-not-a-real-token.example-mac\",\"url\":\"https://greatwait-scheduler.example/callbacks/completion\"},\"trigger\":{\"kind\":\"automatic\"},\"data\":{}}";
+        readonly signingInputUtf8: string;
     };
     /**
      * A redelivery, which is the only vector that discriminates this change.
@@ -530,7 +530,7 @@ export declare const CALLBACK_DELIVERY_PROTOCOL: {
         };
         readonly secret: "greatwait-signature-vector-key-not-a-credential";
         readonly signingInputBase64: "MjAyNi0wNy0yOFQxNTowMDowMC4wMDBaLmRsdl8wMTIzNDU2Nzg5YWJjZGVmZ2hqa21ucHFycy57InZlcnNpb24iOiIyMDI2LTA4LTIzIiwidHlwZSI6InNjaGVkdWxlLm9jY3VycmVuY2UiLCJzY2hlZHVsZUlkIjoic2NoXzAxMjM0NTY3ODlhYmNkZWZnaGprbW5wcXJzIiwib2NjdXJyZW5jZUlkIjoib2NjXzAxMjM0NTY3ODlhYmNkZWZnaGprbW5wcXJzIiwicGxhbm5lZEZvciI6IjIwMjYtMDctMjhUMTU6MDA6MDAuMDAwWiIsImF0dGVtcHQiOjIsImNvbXBsZXRpb24iOnsidG9rZW4iOiJ2Mi5leGFtcGxlLWNsYWltLW5vdC1hLXJlYWwtdG9rZW4uZXhhbXBsZS1tYWMiLCJ1cmwiOiJodHRwczovL2dyZWF0d2FpdC1zY2hlZHVsZXIuZXhhbXBsZS9jYWxsYmFja3MvY29tcGxldGlvbiIsImRlYWRsaW5lIjoiMjAyNi0wNy0yOFQxNTowMDowNS4wMDBaIn0sInRyaWdnZXIiOnsia2luZCI6InJlZGVsaXZlcnkiLCJzb3VyY2VBdHRlbXB0SWQiOiJhdHRfMDEyMzQ1Njc4OWFiY2RlZmdoamttbnBxcnMifSwiZGF0YSI6e319";
-        readonly signingInputUtf8: "2026-07-28T15:00:00.000Z.dlv_0123456789abcdefghjkmnpqrs.{\"version\":\"2026-08-23\",\"type\":\"schedule.occurrence\",\"scheduleId\":\"sch_0123456789abcdefghjkmnpqrs\",\"occurrenceId\":\"occ_0123456789abcdefghjkmnpqrs\",\"plannedFor\":\"2026-07-28T15:00:00.000Z\",\"attempt\":2,\"completion\":{\"token\":\"v2.example-claim-not-a-real-token.example-mac\",\"url\":\"https://greatwait-scheduler.example/callbacks/completion\",\"deadline\":\"2026-07-28T15:00:05.000Z\"},\"trigger\":{\"kind\":\"redelivery\",\"sourceAttemptId\":\"att_0123456789abcdefghjkmnpqrs\"},\"data\":{}}";
+        readonly signingInputUtf8: string;
     };
     /**
      * The ordinary current-version delivery: automatic, and carrying completion
@@ -566,7 +566,7 @@ export declare const CALLBACK_DELIVERY_PROTOCOL: {
         };
         readonly secret: "greatwait-signature-vector-key-not-a-credential";
         readonly signingInputBase64: "MjAyNi0wNy0yOFQxNTowMDowMC4wMDBaLmRsdl8wMTIzNDU2Nzg5YWJjZGVmZ2hqa21ucHFycy57InZlcnNpb24iOiIyMDI2LTA4LTIzIiwidHlwZSI6InNjaGVkdWxlLm9jY3VycmVuY2UiLCJzY2hlZHVsZUlkIjoic2NoXzAxMjM0NTY3ODlhYmNkZWZnaGprbW5wcXJzIiwib2NjdXJyZW5jZUlkIjoib2NjXzAxMjM0NTY3ODlhYmNkZWZnaGprbW5wcXJzIiwicGxhbm5lZEZvciI6IjIwMjYtMDctMjhUMTU6MDA6MDAuMDAwWiIsImF0dGVtcHQiOjEsImNvbXBsZXRpb24iOnsidG9rZW4iOiJ2Mi5leGFtcGxlLWNsYWltLW5vdC1hLXJlYWwtdG9rZW4uZXhhbXBsZS1tYWMiLCJ1cmwiOiJodHRwczovL2dyZWF0d2FpdC1zY2hlZHVsZXIuZXhhbXBsZS9jYWxsYmFja3MvY29tcGxldGlvbiIsImRlYWRsaW5lIjoiMjAyNi0wNy0yOFQxNTowMDowNS4wMDBaIn0sInRyaWdnZXIiOnsia2luZCI6ImF1dG9tYXRpYyJ9LCJkYXRhIjp7fX0=";
-        readonly signingInputUtf8: "2026-07-28T15:00:00.000Z.dlv_0123456789abcdefghjkmnpqrs.{\"version\":\"2026-08-23\",\"type\":\"schedule.occurrence\",\"scheduleId\":\"sch_0123456789abcdefghjkmnpqrs\",\"occurrenceId\":\"occ_0123456789abcdefghjkmnpqrs\",\"plannedFor\":\"2026-07-28T15:00:00.000Z\",\"attempt\":1,\"completion\":{\"token\":\"v2.example-claim-not-a-real-token.example-mac\",\"url\":\"https://greatwait-scheduler.example/callbacks/completion\",\"deadline\":\"2026-07-28T15:00:05.000Z\"},\"trigger\":{\"kind\":\"automatic\"},\"data\":{}}";
+        readonly signingInputUtf8: string;
     };
     readonly unicodeTestVector: {
         readonly envelope: {
@@ -600,7 +600,7 @@ export declare const CALLBACK_DELIVERY_PROTOCOL: {
         };
         readonly secret: "greatwait-signature-vector-key-not-a-credential";
         readonly signingInputBase64: "MjAyNi0wNy0yOFQxNTowMDowMC4wMDBaLmRsdl8wMTIzNDU2Nzg5YWJjZGVmZ2hqa21ucHFycy57InZlcnNpb24iOiIyMDI2LTA4LTIzIiwidHlwZSI6InNjaGVkdWxlLm9jY3VycmVuY2UiLCJzY2hlZHVsZUlkIjoic2NoXzAxMjM0NTY3ODlhYmNkZWZnaGprbW5wcXJzIiwib2NjdXJyZW5jZUlkIjoib2NjXzAxMjM0NTY3ODlhYmNkZWZnaGprbW5wcXJzIiwicGxhbm5lZEZvciI6IjIwMjYtMDctMjhUMTU6MDA6MDAuMDAwWiIsImF0dGVtcHQiOjEsImNvbXBsZXRpb24iOnsidG9rZW4iOiJ2Mi5leGFtcGxlLWNsYWltLW5vdC1hLXJlYWwtdG9rZW4uZXhhbXBsZS1tYWMiLCJ1cmwiOiJodHRwczovL2dyZWF0d2FpdC1zY2hlZHVsZXIuZXhhbXBsZS9jYWxsYmFja3MvY29tcGxldGlvbiIsImRlYWRsaW5lIjoiMjAyNi0wNy0yOFQxNTowMDowNS4wMDBaIn0sInRyaWdnZXIiOnsia2luZCI6ImF1dG9tYXRpYyJ9LCJkYXRhIjp7Im5vdGUiOiJjYWbDqSDimIMifX0=";
-        readonly signingInputUtf8: "2026-07-28T15:00:00.000Z.dlv_0123456789abcdefghjkmnpqrs.{\"version\":\"2026-08-23\",\"type\":\"schedule.occurrence\",\"scheduleId\":\"sch_0123456789abcdefghjkmnpqrs\",\"occurrenceId\":\"occ_0123456789abcdefghjkmnpqrs\",\"plannedFor\":\"2026-07-28T15:00:00.000Z\",\"attempt\":1,\"completion\":{\"token\":\"v2.example-claim-not-a-real-token.example-mac\",\"url\":\"https://greatwait-scheduler.example/callbacks/completion\",\"deadline\":\"2026-07-28T15:00:05.000Z\"},\"trigger\":{\"kind\":\"automatic\"},\"data\":{\"note\":\"café ☃\"}}";
+        readonly signingInputUtf8: string;
     };
     readonly version: "2026-08-23";
 };

package/dist/signatures.js

@@ -34,9 +34,9 @@ export const SIGNATURE_TOLERANCE_SECONDS = 300;
 export const CALLBACK_DELIVERY_PROTOCOL_VERSION = "2026-08-23";
 /** The media type sent on every occurrence delivery. */
 export const CALLBACK_CONTENT_TYPE = "application/json";
-export const signatureHeaderSchema = z
+export const signatureHeaderSchema = /* @__PURE__ */ (() => z
     .string()
-    .regex(/^v1=[0-9a-f]{64}$/u, "must be v1= followed by a lowercase hex SHA-256 HMAC");
+    .regex(/^v1=[0-9a-f]{64}$/u, "must be v1= followed by a lowercase hex SHA-256 HMAC"))();
 /**
  * The exact bytes that are signed: `<timestamp>.<delivery-id>.` followed by the
  * raw body, with no re-serialization anywhere in the path. Re-encoding JSON
@@ -130,13 +130,13 @@ export function isTimestampFresh(timestamp, nowMs, toleranceSeconds = SIGNATURE_
  * an unauthenticated hint has handed anyone who can reach its endpoint a
  * duplicate-execution button.
  */
-export const callbackTriggerSchema = z.discriminatedUnion("kind", [
+export const callbackTriggerSchema = /* @__PURE__ */ (() => z.discriminatedUnion("kind", [
     z.object({ kind: z.literal("automatic") }),
     z.object({
         kind: z.literal("redelivery"),
         sourceAttemptId: attemptIdSchema,
     }),
-]);
+]))();
 /**
  * The envelope version this service emits.
  *
@@ -178,7 +178,7 @@ export const CALLBACK_ENVELOPE_VERSIONS = [
     CALLBACK_ENVELOPE_VERSION_2026_08_08,
     CALLBACK_ENVELOPE_VERSION,
 ];
-const callbackEnvelopeShape = {
+const callbackEnvelopeShape = /* @__PURE__ */ (() => ({
     attempt: z.number().int().positive(),
     /**
      * The customer's payload, delivered verbatim. Deliberately any JSON value:
@@ -190,7 +190,7 @@ const callbackEnvelopeShape = {
     plannedFor: timestampSchema,
     scheduleId: scheduleIdSchema,
     type: z.literal("schedule.occurrence"),
-};
+}))();
 /**
  * Where a `callback` receiver reports that it finished, and with what.
  *
@@ -207,12 +207,12 @@ const callbackEnvelopeShape = {
  * later attempt is refused by the same fence that refuses a late executor
  * result.
  */
-export const callbackCompletionSchema = z.object({
+export const callbackCompletionSchema = /* @__PURE__ */ (() => z.object({
     /** Bearer credential for the report. Send it, do not inspect it. */
     token: z.string().min(1),
     /** Absolute URL to POST to when the work is done. */
     url: z.url(),
-});
+}))();
 /**
  * The completion material every `2026-08-23` delivery carries.
  *
@@ -227,21 +227,21 @@ export const callbackCompletionSchema = z.object({
  * ask for an earlier instant in its acknowledgement and may not ask for a
  * later one.
  */
-export const callbackDeferredCompletionSchema = z.object({
+export const callbackDeferredCompletionSchema = /* @__PURE__ */ (() => z.object({
     /** When this attempt stops being waited for. Absolute, not a duration. */
     deadline: timestampSchema,
     /** Bearer credential for the report. Send it, do not inspect it. */
     token: z.string().min(1),
     /** Absolute URL to POST to when the work is done. */
     url: z.url(),
-});
+}))();
 /**
  * The report body, whose vocabulary lives in the Zod-free `delivery` module so
  * the scheduler's completion route can read it without importing Zod.
  */
-export const callbackCompletionReportSchema = z.object({
+export const callbackCompletionReportSchema = /* @__PURE__ */ (() => z.object({
     outcome: z.enum(CALLBACK_COMPLETION_OUTCOMES).default("succeeded"),
-});
+}))();
 /**
  * The versioned JSON envelope delivered to a customer endpoint.
  *
@@ -251,7 +251,7 @@ export const callbackCompletionReportSchema = z.object({
  * envelope. Collapsing the two would leave a receiver unable to know whether
  * silence about a redelivery is an answer or an absence.
  */
-export const callbackEnvelopeSchema = z.discriminatedUnion("version", [
+export const callbackEnvelopeSchema = /* @__PURE__ */ (() => z.discriminatedUnion("version", [
     z.object({
         ...callbackEnvelopeShape,
         /** Envelope version, dated and independent of the contract version. */
@@ -284,7 +284,7 @@ export const callbackEnvelopeSchema = z.discriminatedUnion("version", [
         trigger: callbackTriggerSchema,
         version: z.literal(CALLBACK_ENVELOPE_VERSION),
     }),
-]);
+]))();
 /**
  * What caused a delivery, for an envelope of any published version.
  *
@@ -436,20 +436,20 @@ export function extractCanonicalEnvelopeIds(rawBody) {
         ? { occurrenceId: occurrenceId.data, scheduleId: scheduleId.data }
         : undefined;
 }
-export const callbackHeadersSchema = z.object({
+export const callbackHeadersSchema = /* @__PURE__ */ (() => z.object({
     [CALLBACK_HEADERS.deliveryId]: deliveryIdSchema,
     [CALLBACK_HEADERS.keyId]: callbackSigningKeyIdSchema,
     [CALLBACK_HEADERS.occurrenceId]: occurrenceIdSchema,
     [CALLBACK_HEADERS.signature]: signatureHeaderSchema,
     [CALLBACK_HEADERS.timestamp]: timestampSchema,
-});
+}))();
 const VECTOR_PREFIX = "2026-07-28T15:00:00.000Z.dlv_0123456789abcdefghjkmnpqrs.";
 const CALLBACK_DELIVERY_VECTOR_BODY = '{"version":"2026-08-23","type":"schedule.occurrence","scheduleId":"sch_0123456789abcdefghjkmnpqrs","occurrenceId":"occ_0123456789abcdefghjkmnpqrs","plannedFor":"2026-07-28T15:00:00.000Z","attempt":1,"completion":{"token":"v2.example-claim-not-a-real-token.example-mac","url":"https://greatwait-scheduler.example/callbacks/completion","deadline":"2026-07-28T15:00:05.000Z"},"trigger":{"kind":"automatic"},"data":{}}';
-const CALLBACK_DELIVERY_VECTOR_INPUT = `${VECTOR_PREFIX}${CALLBACK_DELIVERY_VECTOR_BODY}`;
+const CALLBACK_DELIVERY_VECTOR_INPUT = /* @__PURE__ */ (() => `${VECTOR_PREFIX}${CALLBACK_DELIVERY_VECTOR_BODY}`)();
 const CALLBACK_DELIVERY_UNICODE_VECTOR_BODY = '{"version":"2026-08-23","type":"schedule.occurrence","scheduleId":"sch_0123456789abcdefghjkmnpqrs","occurrenceId":"occ_0123456789abcdefghjkmnpqrs","plannedFor":"2026-07-28T15:00:00.000Z","attempt":1,"completion":{"token":"v2.example-claim-not-a-real-token.example-mac","url":"https://greatwait-scheduler.example/callbacks/completion","deadline":"2026-07-28T15:00:05.000Z"},"trigger":{"kind":"automatic"},"data":{"note":"café ☃"}}';
-const CALLBACK_DELIVERY_UNICODE_VECTOR_INPUT = `${VECTOR_PREFIX}${CALLBACK_DELIVERY_UNICODE_VECTOR_BODY}`;
+const CALLBACK_DELIVERY_UNICODE_VECTOR_INPUT = /* @__PURE__ */ (() => `${VECTOR_PREFIX}${CALLBACK_DELIVERY_UNICODE_VECTOR_BODY}`)();
 const CALLBACK_DELIVERY_REDELIVERY_VECTOR_BODY = '{"version":"2026-08-23","type":"schedule.occurrence","scheduleId":"sch_0123456789abcdefghjkmnpqrs","occurrenceId":"occ_0123456789abcdefghjkmnpqrs","plannedFor":"2026-07-28T15:00:00.000Z","attempt":2,"completion":{"token":"v2.example-claim-not-a-real-token.example-mac","url":"https://greatwait-scheduler.example/callbacks/completion","deadline":"2026-07-28T15:00:05.000Z"},"trigger":{"kind":"redelivery","sourceAttemptId":"att_0123456789abcdefghjkmnpqrs"},"data":{}}';
-const CALLBACK_DELIVERY_REDELIVERY_VECTOR_INPUT = `${VECTOR_PREFIX}${CALLBACK_DELIVERY_REDELIVERY_VECTOR_BODY}`;
+const CALLBACK_DELIVERY_REDELIVERY_VECTOR_INPUT = /* @__PURE__ */ (() => `${VECTOR_PREFIX}${CALLBACK_DELIVERY_REDELIVERY_VECTOR_BODY}`)();
 /**
  * The `2026-08-08` body with no `completion`, byte for byte as published.
  *
@@ -461,9 +461,9 @@ const CALLBACK_DELIVERY_REDELIVERY_VECTOR_INPUT = `${VECTOR_PREFIX}${CALLBACK_DE
  * receiver mid-rollout is still being handed.
  */
 const CALLBACK_DELIVERY_TRIGGER_VECTOR_BODY = '{"version":"2026-08-08","type":"schedule.occurrence","scheduleId":"sch_0123456789abcdefghjkmnpqrs","occurrenceId":"occ_0123456789abcdefghjkmnpqrs","plannedFor":"2026-07-28T15:00:00.000Z","attempt":1,"trigger":{"kind":"automatic"},"data":{}}';
-const CALLBACK_DELIVERY_TRIGGER_VECTOR_INPUT = `${VECTOR_PREFIX}${CALLBACK_DELIVERY_TRIGGER_VECTOR_BODY}`;
+const CALLBACK_DELIVERY_TRIGGER_VECTOR_INPUT = /* @__PURE__ */ (() => `${VECTOR_PREFIX}${CALLBACK_DELIVERY_TRIGGER_VECTOR_BODY}`)();
 const CALLBACK_DELIVERY_COMPLETION_VECTOR_BODY = '{"version":"2026-08-08","type":"schedule.occurrence","scheduleId":"sch_0123456789abcdefghjkmnpqrs","occurrenceId":"occ_0123456789abcdefghjkmnpqrs","plannedFor":"2026-07-28T15:00:00.000Z","attempt":1,"completion":{"token":"v1.example-claim-not-a-real-token.example-mac","url":"https://greatwait-scheduler.example/callbacks/completion"},"trigger":{"kind":"automatic"},"data":{}}';
-const CALLBACK_DELIVERY_COMPLETION_VECTOR_INPUT = `${VECTOR_PREFIX}${CALLBACK_DELIVERY_COMPLETION_VECTOR_BODY}`;
+const CALLBACK_DELIVERY_COMPLETION_VECTOR_INPUT = /* @__PURE__ */ (() => `${VECTOR_PREFIX}${CALLBACK_DELIVERY_COMPLETION_VECTOR_BODY}`)();
 /**
  * The `2026-07-01` body, byte for byte as it was published, with the MAC it was
  * published with.
@@ -476,12 +476,12 @@ const CALLBACK_DELIVERY_COMPLETION_VECTOR_INPUT = `${VECTOR_PREFIX}${CALLBACK_DE
  * published verifier is wrong.
  */
 const CALLBACK_DELIVERY_LEGACY_VECTOR_BODY = '{"version":"2026-07-01","type":"schedule.occurrence","scheduleId":"sch_0123456789abcdefghjkmnpqrs","occurrenceId":"occ_0123456789abcdefghjkmnpqrs","plannedFor":"2026-07-28T15:00:00.000Z","attempt":1,"data":{}}';
-const CALLBACK_DELIVERY_LEGACY_VECTOR_INPUT = `${VECTOR_PREFIX}${CALLBACK_DELIVERY_LEGACY_VECTOR_BODY}`;
+const CALLBACK_DELIVERY_LEGACY_VECTOR_INPUT = /* @__PURE__ */ (() => `${VECTOR_PREFIX}${CALLBACK_DELIVERY_LEGACY_VECTOR_BODY}`)();
 /**
  * Language-neutral known-answer contract for one complete delivery request.
  * The secret is synthetic and deliberately not shaped like a credential.
  */
-export const CALLBACK_DELIVERY_PROTOCOL = {
+export const CALLBACK_DELIVERY_PROTOCOL = /* @__PURE__ */ (() => ({
     envelope: {
         /**
          * The frozen wire order, and `completion` sits inside it.
@@ -790,7 +790,7 @@ export const CALLBACK_DELIVERY_PROTOCOL = {
         signingInputUtf8: CALLBACK_DELIVERY_UNICODE_VECTOR_INPUT,
     },
     version: CALLBACK_DELIVERY_PROTOCOL_VERSION,
-};
+}))();
 /**
  * Every published vector, derived from the protocol rather than listed.
  *

package/dist/stored-http.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The headers a send carries: the endpoint's defaults with the schedule's own
+ * headers over them, matched case-insensitively, the later entry winning, and
+ * suppressed names removed — kept in the order they were written.
+ */
+export declare function mergeStoredHttpHeaders(defaults: readonly unknown[] | null | undefined, overrides: readonly unknown[] | null | undefined): unknown[];
+/**
+ * Whether stored headers fit their bounds: an array of at most 32, each name
+ * present, at most 128 bytes and distinct case-insensitively, and each value
+ * that is not suppressed at most 8,192 bytes, 16,384 bytes in all.
+ */
+export declare function validStoredHttpHeaders(headers: unknown): boolean;
+/**
+ * Whether a schedule's stored HTTP settings, sent through an endpoint with
+ * these default headers, are within bounds: the settings' own shape and
+ * headers, and the headers a send would carry after the merge.
+ */
+export declare function validScheduleHttp(request: unknown, endpointHeaders: readonly unknown[] | null | undefined): boolean;

package/dist/stored-http.js

@@ -0,0 +1,106 @@
+/**
+ * The stored custom-HTTP invariants, as pure functions (W9-73).
+ *
+ * Until W9-73 a schedule insert ran these inside PostgreSQL, in the
+ * `greatwait_schedule_http_bounds` trigger (migration 0050): a lock and read of
+ * the endpoint's default headers, `http_merge_headers_v1` and
+ * `http_validate_headers_v1`. They are the same rules here, over the same JSON,
+ * so the create can validate before it writes and spend no statement on it.
+ * Schedule edits keep the trigger; the endpoint's own trigger still guards an
+ * endpoint header change against every schedule using it.
+ */
+import { HTTP_HEADER_BOUNDS, HTTP_METHODS } from "./http-request.js";
+const encoder = new TextEncoder();
+const BODY_MODES = ["envelope", "json", "none"];
+function record(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+/** `value->>'suppressed' = 'true'`: the JSON `true`, or the string. */
+function suppressed(header) {
+    const flag = record(header)?.["suppressed"];
+    return flag === true || flag === "true";
+}
+function headerName(header) {
+    const name = record(header)?.["name"];
+    return typeof name === "string" ? name : undefined;
+}
+/**
+ * The headers a send carries: the endpoint's defaults with the schedule's own
+ * headers over them, matched case-insensitively, the later entry winning, and
+ * suppressed names removed — kept in the order they were written.
+ */
+export function mergeStoredHttpHeaders(defaults, overrides) {
+    // Positions as the SQL numbered them: defaults from 1, overrides from 101,
+    // so an override always outranks a default of the same name.
+    const winners = new Map();
+    const consider = (headers, offset) => {
+        headers.forEach((header, index) => {
+            const key = headerName(header)?.toLowerCase();
+            const position = offset + index + 1;
+            const prior = winners.get(key);
+            if (prior === undefined || position > prior[0])
+                winners.set(key, [position, header]);
+        });
+    };
+    consider(defaults ?? [], 0);
+    consider(overrides ?? [], 100);
+    return [...winners.values()]
+        .filter(([, header]) => !suppressed(header))
+        .sort(([left], [right]) => left - right)
+        .map(([, header]) => header);
+}
+/**
+ * Whether stored headers fit their bounds: an array of at most 32, each name
+ * present, at most 128 bytes and distinct case-insensitively, and each value
+ * that is not suppressed at most 8,192 bytes, 16,384 bytes in all.
+ */
+export function validStoredHttpHeaders(headers) {
+    if (!Array.isArray(headers) || headers.length > HTTP_HEADER_BOUNDS.count)
+        return false;
+    const names = new Set();
+    let total = 0;
+    for (const header of headers) {
+        const name = headerName(header);
+        if (name === undefined || name.length === 0)
+            return false;
+        const nameBytes = encoder.encode(name).byteLength;
+        if (nameBytes > HTTP_HEADER_BOUNDS.nameBytes)
+            return false;
+        if (names.has(name.toLowerCase()))
+            return false;
+        names.add(name.toLowerCase());
+        if (suppressed(header))
+            continue;
+        const size = record(header)?.["valueBytes"];
+        // The SQL read the number as text and required one to five digits.
+        if (typeof size !== "number" ||
+            !Number.isSafeInteger(size) ||
+            size < 0 ||
+            size > HTTP_HEADER_BOUNDS.valueBytes)
+            return false;
+        total += nameBytes + size;
+    }
+    return total <= HTTP_HEADER_BOUNDS.totalBytes;
+}
+/**
+ * Whether a schedule's stored HTTP settings, sent through an endpoint with
+ * these default headers, are within bounds: the settings' own shape and
+ * headers, and the headers a send would carry after the merge.
+ */
+export function validScheduleHttp(request, endpointHeaders) {
+    const settings = record(request);
+    if (request !== null && request !== undefined) {
+        const method = settings?.["method"];
+        const bodyMode = settings?.["bodyMode"];
+        if (settings === undefined ||
+            !HTTP_METHODS.includes(method) ||
+            !BODY_MODES.includes(bodyMode) ||
+            (method === "GET") !== (bodyMode === "none") ||
+            !validStoredHttpHeaders(settings["headers"]))
+            return false;
+    }
+    const overrides = settings?.["headers"];
+    return validStoredHttpHeaders(mergeStoredHttpHeaders(endpointHeaders, Array.isArray(overrides) ? overrides : undefined));
+}