@greatwait/contracts 0.1.0-alpha.1

package/dist/signatures.js

@@ -0,0 +1,867 @@
+import { z } from "zod";
+import { CALLBACK_COMPLETION_OUTCOMES, isCallbackRefusalStatus, } from "./delivery.js";
+import { attemptIdSchema, callbackSigningKeyIdSchema, deliveryIdSchema, occurrenceIdSchema, scheduleIdSchema, } from "./identifiers.js";
+import { timestampSchema } from "./time.js";
+/**
+ * Callback authenticity.
+ *
+ * The signature covers the timestamp, the delivery id, and the exact raw
+ * request-body bytes. A receiver verifies before parsing, in constant time.
+ *
+ * This is the most consequential break from the legacy scheduler, which signed
+ * `scheduleId.owner.tenant.timestampMs` and never touched the body: a signature
+ * that does not cover the body authenticates only the envelope, so an attacker
+ * who can replay a captured header set may substitute any payload. W6-03
+ * migrates the autoscaler onto this contract through a separate v2 endpoint so
+ * the old and new verifiers never weaken each other.
+ *
+ * The `Callback-*` header namespace is intentionally independent of the display
+ * brand. Renaming the product must not force receivers to change verification
+ * code.
+ */
+export const CALLBACK_HEADERS = {
+    deliveryId: "Callback-Delivery-Id",
+    keyId: "Callback-Key-Id",
+    occurrenceId: "Callback-Occurrence-Id",
+    signature: "Callback-Signature",
+    timestamp: "Callback-Timestamp",
+};
+/** Only `v1` exists. A new scheme is added alongside, never in place of. */
+export const SIGNATURE_SCHEME = "v1";
+/** How far a receiver's clock may differ before a signature is stale. */
+export const SIGNATURE_TOLERANCE_SECONDS = 300;
+/** Version of the complete delivery-authentication protocol artifact. */
+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
+    .string()
+    .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
+ * before signing or verifying is the classic way to break this.
+ *
+ * Both prefix fields are validated here rather than trusted, and that is a
+ * security property, not tidiness. The delimiter `.` also occurs inside every
+ * contract timestamp, so without validation the encoding is not injective:
+ * `("2026-07-28T15:00:00", "000Z.dlv_…", body)` produces the same bytes as
+ * `("2026-07-28T15:00:00.000Z", "dlv_…", body)`, and an attacker holding one
+ * legitimate signature could move bytes across the delimiter — shortening the
+ * body and lengthening the delivery-id header — and still verify.
+ *
+ * Validating makes both fields fixed-width, so the prefix is a constant 56
+ * bytes and the encoding is injective. A verifier that computes the MAC before
+ * validating its headers is the natural implementation and would be
+ * vulnerable; making that impossible here means no receiver has to know.
+ *
+ * **Throws** on a malformed timestamp or delivery id. That is right on the
+ * signing side — refusing to sign something we cannot encode unambiguously —
+ * but a receiver verifying attacker-controlled headers wants a boolean, not an
+ * exception: use `trySigningInput`, or an uncaught throw turns a
+ * malformed-header probe into a 500.
+ */
+export function signingInput(timestamp, deliveryId, rawBody) {
+    const checkedTimestamp = timestampSchema.parse(timestamp);
+    const checkedDeliveryId = deliveryIdSchema.parse(deliveryId);
+    const prefix = `${checkedTimestamp}.${checkedDeliveryId}.`;
+    // Both fields are ASCII by construction, now that both have been validated, so
+    // UTF-8 encoding is byte-for-byte their code points and the prefix stays the
+    // constant 56 bytes the injectivity argument above depends on.
+    const prefixBytes = new TextEncoder().encode(prefix);
+    const input = new Uint8Array(prefixBytes.length + rawBody.length);
+    input.set(prefixBytes, 0);
+    input.set(rawBody, prefixBytes.length);
+    return input;
+}
+/**
+ * `signingInput` for untrusted input: returns `undefined` instead of throwing
+ * when the prefix fields are malformed, which is what a receiver verifying
+ * headers off the wire needs.
+ */
+export function trySigningInput(timestamp, deliveryId, rawBody) {
+    try {
+        return signingInput(timestamp, deliveryId, rawBody);
+    }
+    catch (error) {
+        // Only a validation failure means "malformed headers". Anything else — an
+        // allocation failure on an oversized body, say — is a real fault and must
+        // not be reported to the caller as a bad signature.
+        if (error instanceof z.ZodError) {
+            return undefined;
+        }
+        throw error;
+    }
+}
+export function formatSignature(hexMac) {
+    return `${SIGNATURE_SCHEME}=${hexMac}`;
+}
+/**
+ * Whether a signed timestamp is close enough to now. Replay protection beyond
+ * this window is the receiver's, keyed on the delivery id.
+ */
+export function isTimestampFresh(timestamp, nowMs, toleranceSeconds = SIGNATURE_TOLERANCE_SECONDS) {
+    // Validated with the contract schema, not `Date.parse`. A timestamp this
+    // service would never emit — `2026-07-28T15:00:00Z`, say — must not be
+    // treated as fresh just because it happens to parse.
+    if (!timestampSchema.safeParse(timestamp).success) {
+        return false;
+    }
+    return Math.abs(nowMs - Date.parse(timestamp)) <= toleranceSeconds * 1000;
+}
+/**
+ * Why this delivery exists.
+ *
+ * `automatic` is everything the system decided for itself: a first attempt, and
+ * every retry after an ambiguous or failed one. Nobody asked for it, it may
+ * duplicate work already done, and a receiver must therefore treat it as at
+ * most one execution of the occurrence.
+ *
+ * `redelivery` is a person pressing the button, scoped by
+ * `occurrences:redeliver` and named against the retained attempt they chose to
+ * follow. It is a *request for the work to happen again*, and a receiver that
+ * suppresses it as a duplicate is answering a deliberate instruction with
+ * silence.
+ *
+ * The two were indistinguishable on the wire until this field existed, so the
+ * only rule safe against the first was applied to both. That is the defect
+ * W3-08 exists to remove, and the reason the field is inside the signed bytes
+ * rather than in a header: a receiver that would re-run work on the strength of
+ * an unauthenticated hint has handed anyone who can reach its endpoint a
+ * duplicate-execution button.
+ */
+export const callbackTriggerSchema = z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("automatic") }),
+    z.object({
+        kind: z.literal("redelivery"),
+        sourceAttemptId: attemptIdSchema,
+    }),
+]);
+/**
+ * The envelope version this service emits.
+ *
+ * Dated and independent of the contract version. It moved on 2026-08-08 because
+ * the envelope gained `trigger`, and again on 2026-08-23 because `completion`
+ * stopped being optional: every delivery now carries a completion URL, a
+ * per-dispatch credential and an absolute deadline, whatever the schedule asked
+ * for. `assess` classifies both moves as `breaking` — see
+ * `CALLBACK_ENVELOPE_VERSION_CHANGE`.
+ *
+ * **A required field is why this is a version rather than an addition.** Under
+ * `2026-08-08` an absent `completion` means "this schedule did not ask for
+ * one"; under `2026-08-23` it means the envelope is malformed. A receiver that
+ * could not tell those apart would have to treat "no completion material" as
+ * both a normal delivery and a broken one.
+ */
+export const CALLBACK_ENVELOPE_VERSION = "2026-08-23";
+/** The first published envelope version, which this service no longer emits. */
+export const CALLBACK_ENVELOPE_VERSION_2026_07_01 = "2026-07-01";
+/**
+ * The second published version, which this service no longer emits.
+ *
+ * Still accepted inbound, and its known-answer vectors are still published:
+ * a receiver deployed before the sender moved keeps verifying deliveries that
+ * were signed under it.
+ */
+export const CALLBACK_ENVELOPE_VERSION_2026_08_08 = "2026-08-08";
+/**
+ * Every envelope version a receiver may be handed, oldest first.
+ *
+ * All are accepted on the way in and only the newest is sent, which is what
+ * makes a receiver deployable ahead of the sender. A receiver upgraded first
+ * keeps verifying the deliveries already in flight; one upgraded afterwards
+ * answers `invalid_envelope` to everything, because a version literal it has
+ * never heard of is exactly the case the field exists to catch.
+ */
+export const CALLBACK_ENVELOPE_VERSIONS = [
+    CALLBACK_ENVELOPE_VERSION_2026_07_01,
+    CALLBACK_ENVELOPE_VERSION_2026_08_08,
+    CALLBACK_ENVELOPE_VERSION,
+];
+const callbackEnvelopeShape = {
+    attempt: z.number().int().positive(),
+    /**
+     * The customer's payload, delivered verbatim. Deliberately any JSON value:
+     * the legacy scheduler accepted arrays and scalars, and narrowing to an
+     * object here would make existing payloads undeliverable after migration.
+     */
+    data: z.unknown(),
+    occurrenceId: occurrenceIdSchema,
+    plannedFor: timestampSchema,
+    scheduleId: scheduleIdSchema,
+    type: z.literal("schedule.occurrence"),
+};
+/**
+ * Where a `callback` receiver reports that it finished, and with what.
+ *
+ * **Present only on a delivery whose schedule asked for `completion:
+ * "callback"`**, which is what makes adding it to an existing envelope version
+ * safe rather than a break. A receiver sees this field for the first time on a
+ * delivery its own customer deliberately reconfigured; no receiver that has not
+ * opted in can be handed one. That is a different situation from `trigger`,
+ * which appeared on *every* delivery and moved the version to `2026-08-08` in
+ * consequence.
+ *
+ * The token authenticates the report and nothing else. It is minted per dispatch
+ * and names one attempt at one dispatch epoch, so a report replayed against a
+ * later attempt is refused by the same fence that refuses a late executor
+ * result.
+ */
+export const callbackCompletionSchema = 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.
+ *
+ * The same URL and credential, plus the one thing a receiver could not
+ * previously know: **when Greatwait stops waiting.** Without it a receiver
+ * deciding whether to accept the work has to infer the deadline from the
+ * schedule's configured duration, which it cannot see, and a receiver that
+ * reports one second late looks identical to one that never reported at all.
+ *
+ * `deadline` is the schedule's own allowance measured from this attempt, in
+ * the wire's one timestamp representation. It is the maximum: a receiver may
+ * ask for an earlier instant in its acknowledgement and may not ask for a
+ * later one.
+ */
+export const callbackDeferredCompletionSchema = 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({
+    outcome: z.enum(CALLBACK_COMPLETION_OUTCOMES).default("succeeded"),
+});
+/**
+ * The versioned JSON envelope delivered to a customer endpoint.
+ *
+ * A union rather than one object with an optional field, and the difference is
+ * the whole point of a version: under `2026-07-01` a missing `trigger` means
+ * "this sender cannot tell you", and under `2026-08-08` it is a malformed
+ * 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", [
+    z.object({
+        ...callbackEnvelopeShape,
+        /** Envelope version, dated and independent of the contract version. */
+        version: z.literal(CALLBACK_ENVELOPE_VERSION_2026_07_01),
+    }),
+    z.object({
+        ...callbackEnvelopeShape,
+        /**
+         * Where to report completion. Present only in `callback` mode, absent in
+         * every `response` delivery, which is every delivery this service sent
+         * before 2026-08-13.
+         */
+        completion: callbackCompletionSchema.optional(),
+        /** Why this delivery exists. Required from `2026-08-08` onward. */
+        trigger: callbackTriggerSchema,
+        version: z.literal(CALLBACK_ENVELOPE_VERSION_2026_08_08),
+    }),
+    z.object({
+        ...callbackEnvelopeShape,
+        /**
+         * Where to report completion, its credential, and the deadline.
+         *
+         * **Required, on every delivery.** That is the whole of this version: a
+         * receiver no longer has to have been configured for deferral to be
+         * allowed to defer, so the material cannot be conditional on a setting the
+         * receiver cannot see.
+         */
+        completion: callbackDeferredCompletionSchema,
+        /** Why this delivery exists. Required from `2026-08-08` onward. */
+        trigger: callbackTriggerSchema,
+        version: z.literal(CALLBACK_ENVELOPE_VERSION),
+    }),
+]);
+/**
+ * What caused a delivery, for an envelope of any published version.
+ *
+ * A `2026-07-01` envelope carries no trigger and reads as `automatic`, which is
+ * the conservative answer rather than a neutral one: it keeps duplicate
+ * suppression in force for a sender that cannot say a redelivery was ordered.
+ * Every receiver-side decision goes through this function so that default lives
+ * in one place instead of being re-decided at each call site.
+ */
+export function callbackEnvelopeTrigger(envelope) {
+    return "trigger" in envelope ? envelope.trigger : { kind: "automatic" };
+}
+export function callbackRun(envelope) {
+    return callbackEnvelopeTrigger(envelope).kind === "redelivery"
+        ? { kind: "redelivery", ordinal: envelope.attempt }
+        : { kind: "automatic" };
+}
+const textEncoder = new TextEncoder();
+function isJsonValue(value, ancestors) {
+    if (value === null ||
+        typeof value === "string" ||
+        typeof value === "boolean") {
+        return true;
+    }
+    if (typeof value === "number") {
+        return Number.isFinite(value);
+    }
+    if (typeof value !== "object" || ancestors.has(value)) {
+        return false;
+    }
+    if (Array.isArray(value)) {
+        ancestors.add(value);
+        try {
+            return value.every((entry) => isJsonValue(entry, ancestors));
+        }
+        finally {
+            ancestors.delete(value);
+        }
+    }
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) {
+        return false;
+    }
+    ancestors.add(value);
+    try {
+        return Object.values(value).every((entry) => isJsonValue(entry, ancestors));
+    }
+    finally {
+        ancestors.delete(value);
+    }
+}
+/**
+ * Serialize one callback envelope exactly once in the frozen wire order.
+ *
+ * The returned bytes are both the bytes HMAC signs and the bytes `fetch`
+ * sends. `data` is checked as JSON before stringification so values such as
+ * `undefined`, `NaN`, `bigint`, a `Date`, or a cycle cannot be silently omitted
+ * or rewritten into a body different from the caller's input.
+ */
+export function serializeCallbackEnvelope(envelope) {
+    const checked = callbackEnvelopeSchema.parse(envelope);
+    if (!isJsonValue(checked.data, new Set())) {
+        throw new TypeError("callback envelope data must be a JSON value");
+    }
+    const head = {
+        version: checked.version,
+        type: checked.type,
+        scheduleId: checked.scheduleId,
+        occurrenceId: checked.occurrenceId,
+        plannedFor: checked.plannedFor,
+        attempt: checked.attempt,
+    };
+    if (!("trigger" in checked)) {
+        return textEncoder.encode(JSON.stringify({ ...head, data: checked.data }));
+    }
+    // Rebuilt member by member rather than spread, because these bytes are
+    // signed and a parsed object's key order is not a property anyone should
+    // have to reason about. `kind` first, `sourceAttemptId` second, and nothing
+    // else has a representation here.
+    const trigger = checked.trigger.kind === "redelivery"
+        ? {
+            kind: checked.trigger.kind,
+            sourceAttemptId: checked.trigger.sourceAttemptId,
+        }
+        : { kind: checked.trigger.kind };
+    // Before `trigger` in both versions that carry it. The wire order is frozen
+    // because these bytes are signed, so a field added later still has one fixed
+    // position rather than wherever an object literal put it — and `deadline` is
+    // appended inside `completion` for the same reason, so a receiver that
+    // already reconstructs the `2026-08-08` object only has to add a key rather
+    // than to re-derive an order.
+    const completion = checked.version === CALLBACK_ENVELOPE_VERSION
+        ? {
+            completion: {
+                token: checked.completion.token,
+                url: checked.completion.url,
+                deadline: checked.completion.deadline,
+            },
+        }
+        : checked.completion === undefined
+            ? {}
+            : {
+                completion: {
+                    token: checked.completion.token,
+                    url: checked.completion.url,
+                },
+            };
+    return textEncoder.encode(JSON.stringify({ ...head, ...completion, trigger, data: checked.data }));
+}
+/**
+ * The version is matched by *shape* rather than against the published list, and
+ * that is deliberate.
+ *
+ * This runs before the body is parsed, on bytes the MAC has already
+ * authenticated, and its one job is to find the two identifiers so the
+ * occurrence header can be compared without trusting attacker-controlled JSON.
+ * Whether the version is one we publish is a question the schema answers a
+ * moment later, and answering it *here* would collapse two different refusals
+ * into one: a receiver handed an envelope from a newer sender would report
+ * `invalid_headers`, sending an integrator to check their signing keys, when
+ * what actually happened is that the two ends disagree about the contract.
+ * Matching a dated literal keeps the prefix a fixed shape and lets
+ * `invalid_envelope` mean what it says.
+ */
+const CANONICAL_ENVELOPE_ID_PREFIX = /^\{"version":"\d{4}-\d{2}-\d{2}","type":"schedule\.occurrence","scheduleId":"(sch_[0-9abcdefghjkmnpqrstvwxyz]{26})","occurrenceId":"(occ_[0-9abcdefghjkmnpqrstvwxyz]{26})",/u;
+/**
+ * Read the two leading envelope identifiers without parsing attacker-controlled
+ * JSON. This lets receiver middleware reject a mutated occurrence header after
+ * authenticating the exact bytes but before `JSON.parse` or an application
+ * handler sees them.
+ */
+export function extractCanonicalEnvelopeIds(rawBody) {
+    let decoded;
+    try {
+        decoded = new TextDecoder("utf-8", {
+            fatal: true,
+            ignoreBOM: false,
+        }).decode(rawBody);
+    }
+    catch {
+        return undefined;
+    }
+    const match = CANONICAL_ENVELOPE_ID_PREFIX.exec(decoded);
+    if (match === null)
+        return undefined;
+    const scheduleId = scheduleIdSchema.safeParse(match[1]);
+    const occurrenceId = occurrenceIdSchema.safeParse(match[2]);
+    return scheduleId.success && occurrenceId.success
+        ? { occurrenceId: occurrenceId.data, scheduleId: scheduleId.data }
+        : undefined;
+}
+export const callbackHeadersSchema = 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_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_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}`;
+/**
+ * The `2026-08-08` body with no `completion`, byte for byte as published.
+ *
+ * Under `2026-08-08` an absent `completion` was the ordinary case and this is
+ * its known answer. It is the vector `testVector` used to be, **moved rather
+ * than recomputed**: the bytes and the MAC are the ones published on
+ * 2026-08-08, so a change to `signingInput` still has to break them. Deleting
+ * it instead would have retired the only published answer for the shape a
+ * 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_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}`;
+/**
+ * The `2026-07-01` body, byte for byte as it was published, with the MAC it was
+ * published with.
+ *
+ * It is here rather than deleted because these vectors exist to make a change to
+ * `signingInput` fail loudly, and recomputing them is exactly the move that
+ * would hide one. Keeping the retired envelope's known answer *unchanged* is
+ * what separates "the bytes we send are new" from "the algorithm moved": if this
+ * MAC ever has to be recomputed, something signed differently and every
+ * 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}`;
+/**
+ * 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 = {
+    envelope: {
+        /**
+         * The frozen wire order, and `completion` sits inside it.
+         *
+         * **This list is what a receiver outside JavaScript implements against**,
+         * so a field that reached the wire without reaching this array would make
+         * every callback delivery fail signature verification for exactly the
+         * integrators who cannot read the serializer. From `2026-08-23` every
+         * delivery carries `completion`; under `2026-08-08` it was optional, and
+         * the order was fixed anyway, because a position decided at emit time is a
+         * position nobody else can reproduce.
+         */
+        propertyOrder: [
+            "version",
+            "type",
+            "scheduleId",
+            "occurrenceId",
+            "plannedFor",
+            "attempt",
+            "completion",
+            "trigger",
+            "data",
+        ],
+        /**
+         * The order **inside** `completion`, which is frozen for the same reason.
+         *
+         * `deadline` is appended rather than inserted, so a receiver that already
+         * reconstructs the `2026-08-08` object adds a key instead of re-deriving
+         * an order. Under `2026-08-08` the same object is the first two entries
+         * and nothing else.
+         */
+        completionPropertyOrder: ["token", "url", "deadline"],
+        /**
+         * The order under `2026-08-08`, whose `completion` is optional and carries
+         * no `deadline`. The top-level list is the same; what differs is inside.
+         */
+        propertyOrder_2026_08_08: [
+            "version",
+            "type",
+            "scheduleId",
+            "occurrenceId",
+            "plannedFor",
+            "attempt",
+            "completion",
+            "trigger",
+            "data",
+        ],
+        /** The order under `2026-07-01`, which carries no trigger. */
+        propertyOrder_2026_07_01: [
+            "version",
+            "type",
+            "scheduleId",
+            "occurrenceId",
+            "plannedFor",
+            "attempt",
+            "data",
+        ],
+        serialization: "compact UTF-8 JSON with the stated top-level property order",
+        trigger: {
+            automatic: "A first attempt or a retry the system chose. Nobody asked for it, it may repeat work already done, and a receiver must run the occurrence at most once.",
+            default: "An envelope with no trigger field is automatic. Only 2026-07-01 can omit it.",
+            propertyOrder: ["kind", "sourceAttemptId"],
+            ordinal: "attempt. It only ever increases within an occurrence and every copy of one redelivery carries the same value, so a receiver recognises a repeat by keeping the highest it has run to completion rather than by keeping them all.",
+            redelivery: "A person ordered this delivery under the occurrences:redeliver scope. sourceAttemptId names the retained attempt they chose to follow and is there to show them, not to decide whether the work runs — attempt is what decides that. It is a request for the work to happen again, and a receiver that suppresses it as a duplicate answers a deliberate instruction with silence.",
+            requirement: "run the handler again for a redelivery whose attempt is above the highest this receiver has run to completion for the occurrence, keep suppressing every automatic delivery of a completed occurrence, and suppress every redelivery at or below that high-water mark",
+        },
+        version: CALLBACK_ENVELOPE_VERSION,
+        /**
+         * Every version a receiver may be handed. A sender emits only the last;
+         * accepting the whole list is what lets a receiver deploy first.
+         */
+        versions: CALLBACK_ENVELOPE_VERSIONS,
+    },
+    headers: {
+        contentType: CALLBACK_CONTENT_TYPE,
+        required: [
+            "Content-Type",
+            CALLBACK_HEADERS.deliveryId,
+            CALLBACK_HEADERS.occurrenceId,
+            CALLBACK_HEADERS.timestamp,
+            CALLBACK_HEADERS.keyId,
+            CALLBACK_HEADERS.signature,
+        ],
+    },
+    replay: {
+        identity: CALLBACK_HEADERS.deliveryId,
+        requirement: "atomically reject a previously accepted delivery id before parsing",
+    },
+    signature: {
+        algorithm: "HMAC-SHA-256",
+        format: "v1=<64 lowercase hexadecimal characters>",
+        input: "ASCII <Callback-Timestamp>.<Callback-Delivery-Id>. followed by the exact raw request body bytes",
+        scheme: SIGNATURE_SCHEME,
+        timestampToleranceSeconds: SIGNATURE_TOLERANCE_SECONDS,
+    },
+    /**
+     * The retired `2026-07-01` envelope, kept as a known answer.
+     *
+     * A receiver is still held to verifying it, because a sender mid-rollout may
+     * have signed it before the version moved. Its MAC is the one published on
+     * 2026-07-28 and is deliberately not recomputed.
+     */
+    legacyTestVector: {
+        envelope: {
+            attempt: 1,
+            data: {},
+            occurrenceId: "occ_0123456789abcdefghjkmnpqrs",
+            plannedFor: "2026-07-28T15:00:00.000Z",
+            scheduleId: "sch_0123456789abcdefghjkmnpqrs",
+            type: "schedule.occurrence",
+            version: CALLBACK_ENVELOPE_VERSION_2026_07_01,
+        },
+        exactBodyBase64: "eyJ2ZXJzaW9uIjoiMjAyNi0wNy0wMSIsInR5cGUiOiJzY2hlZHVsZS5vY2N1cnJlbmNlIiwic2NoZWR1bGVJZCI6InNjaF8wMTIzNDU2Nzg5YWJjZGVmZ2hqa21ucHFycyIsIm9jY3VycmVuY2VJZCI6Im9jY18wMTIzNDU2Nzg5YWJjZGVmZ2hqa21ucHFycyIsInBsYW5uZWRGb3IiOiIyMDI2LTA3LTI4VDE1OjAwOjAwLjAwMFoiLCJhdHRlbXB0IjoxLCJkYXRhIjp7fX0=",
+        exactBodyUtf8: CALLBACK_DELIVERY_LEGACY_VECTOR_BODY,
+        headers: {
+            "Callback-Delivery-Id": "dlv_0123456789abcdefghjkmnpqrs",
+            "Callback-Key-Id": "csk_0123456789abcdefghjkmnpqrs",
+            "Callback-Occurrence-Id": "occ_0123456789abcdefghjkmnpqrs",
+            "Callback-Signature": "v1=11135fdfc0bc5d49ebcc9d3a0d8df1116179097cefe961c6eca281339e5cfab3",
+            "Callback-Timestamp": "2026-07-28T15:00:00.000Z",
+            "Content-Type": CALLBACK_CONTENT_TYPE,
+        },
+        secret: "greatwait-signature-vector-key-not-a-credential",
+        signingInputBase64: "MjAyNi0wNy0yOFQxNTowMDowMC4wMDBaLmRsdl8wMTIzNDU2Nzg5YWJjZGVmZ2hqa21ucHFycy57InZlcnNpb24iOiIyMDI2LTA3LTAxIiwidHlwZSI6InNjaGVkdWxlLm9jY3VycmVuY2UiLCJzY2hlZHVsZUlkIjoic2NoXzAxMjM0NTY3ODlhYmNkZWZnaGprbW5wcXJzIiwib2NjdXJyZW5jZUlkIjoib2NjXzAxMjM0NTY3ODlhYmNkZWZnaGprbW5wcXJzIiwicGxhbm5lZEZvciI6IjIwMjYtMDctMjhUMTU6MDA6MDAuMDAwWiIsImF0dGVtcHQiOjEsImRhdGEiOnt9fQ==",
+        signingInputUtf8: CALLBACK_DELIVERY_LEGACY_VECTOR_INPUT,
+    },
+    /**
+     * The retired `2026-08-08` envelope **without** `completion`, kept as a known
+     * answer.
+     *
+     * It is the vector `testVector` was until 2026-08-23, moved here rather than
+     * recomputed. Under `2026-08-08` an absent `completion` was the ordinary
+     * case, so this is the shape most deliveries signed under that version had,
+     * and a receiver still verifying them needs its published answer to stay put.
+     */
+    triggerTestVector: {
+        envelope: {
+            attempt: 1,
+            data: {},
+            occurrenceId: "occ_0123456789abcdefghjkmnpqrs",
+            plannedFor: "2026-07-28T15:00:00.000Z",
+            scheduleId: "sch_0123456789abcdefghjkmnpqrs",
+            trigger: { kind: "automatic" },
+            type: "schedule.occurrence",
+            version: CALLBACK_ENVELOPE_VERSION_2026_08_08,
+        },
+        exactBodyBase64: "eyJ2ZXJzaW9uIjoiMjAyNi0wOC0wOCIsInR5cGUiOiJzY2hlZHVsZS5vY2N1cnJlbmNlIiwic2NoZWR1bGVJZCI6InNjaF8wMTIzNDU2Nzg5YWJjZGVmZ2hqa21ucHFycyIsIm9jY3VycmVuY2VJZCI6Im9jY18wMTIzNDU2Nzg5YWJjZGVmZ2hqa21ucHFycyIsInBsYW5uZWRGb3IiOiIyMDI2LTA3LTI4VDE1OjAwOjAwLjAwMFoiLCJhdHRlbXB0IjoxLCJ0cmlnZ2VyIjp7ImtpbmQiOiJhdXRvbWF0aWMifSwiZGF0YSI6e319",
+        exactBodyUtf8: CALLBACK_DELIVERY_TRIGGER_VECTOR_BODY,
+        headers: {
+            "Callback-Delivery-Id": "dlv_0123456789abcdefghjkmnpqrs",
+            "Callback-Key-Id": "csk_0123456789abcdefghjkmnpqrs",
+            "Callback-Occurrence-Id": "occ_0123456789abcdefghjkmnpqrs",
+            "Callback-Signature": "v1=bd96c6d68a5c0521c18600d92913ce4dcf32036f2c930d0f9db9de55da9280e7",
+            "Callback-Timestamp": "2026-07-28T15:00:00.000Z",
+            "Content-Type": CALLBACK_CONTENT_TYPE,
+        },
+        secret: "greatwait-signature-vector-key-not-a-credential",
+        signingInputBase64: "MjAyNi0wNy0yOFQxNTowMDowMC4wMDBaLmRsdl8wMTIzNDU2Nzg5YWJjZGVmZ2hqa21ucHFycy57InZlcnNpb24iOiIyMDI2LTA4LTA4IiwidHlwZSI6InNjaGVkdWxlLm9jY3VycmVuY2UiLCJzY2hlZHVsZUlkIjoic2NoXzAxMjM0NTY3ODlhYmNkZWZnaGprbW5wcXJzIiwib2NjdXJyZW5jZUlkIjoib2NjXzAxMjM0NTY3ODlhYmNkZWZnaGprbW5wcXJzIiwicGxhbm5lZEZvciI6IjIwMjYtMDctMjhUMTU6MDA6MDAuMDAwWiIsImF0dGVtcHQiOjEsInRyaWdnZXIiOnsia2luZCI6ImF1dG9tYXRpYyJ9LCJkYXRhIjp7fX0=",
+        signingInputUtf8: CALLBACK_DELIVERY_TRIGGER_VECTOR_INPUT,
+    },
+    /**
+     * The retired `2026-08-08` envelope **with** `completion`, kept as a known
+     * answer.
+     *
+     * Under that version the field was optional and appeared only on a schedule
+     * configured for `callback` completion, and it carried no `deadline`. This is
+     * the published answer for that shape, byte for byte and MAC unchanged: a
+     * receiver mid-rollout is still handed it, and recomputing this vector is
+     * exactly the move that would hide a change to `signingInput`.
+     *
+     * The token is synthetic and shaped like ours without being one. A real token
+     * names an attempt at a dispatch epoch and expires; this is a vector.
+     */
+    completionTestVector: {
+        envelope: {
+            attempt: 1,
+            completion: {
+                token: "v1.example-claim-not-a-real-token.example-mac",
+                url: "https://greatwait-scheduler.example/callbacks/completion",
+            },
+            data: {},
+            occurrenceId: "occ_0123456789abcdefghjkmnpqrs",
+            plannedFor: "2026-07-28T15:00:00.000Z",
+            scheduleId: "sch_0123456789abcdefghjkmnpqrs",
+            trigger: { kind: "automatic" },
+            type: "schedule.occurrence",
+            version: CALLBACK_ENVELOPE_VERSION_2026_08_08,
+        },
+        exactBodyBase64: "eyJ2ZXJzaW9uIjoiMjAyNi0wOC0wOCIsInR5cGUiOiJzY2hlZHVsZS5vY2N1cnJlbmNlIiwic2NoZWR1bGVJZCI6InNjaF8wMTIzNDU2Nzg5YWJjZGVmZ2hqa21ucHFycyIsIm9jY3VycmVuY2VJZCI6Im9jY18wMTIzNDU2Nzg5YWJjZGVmZ2hqa21ucHFycyIsInBsYW5uZWRGb3IiOiIyMDI2LTA3LTI4VDE1OjAwOjAwLjAwMFoiLCJhdHRlbXB0IjoxLCJjb21wbGV0aW9uIjp7InRva2VuIjoidjEuZXhhbXBsZS1jbGFpbS1ub3QtYS1yZWFsLXRva2VuLmV4YW1wbGUtbWFjIiwidXJsIjoiaHR0cHM6Ly9ncmVhdHdhaXQtc2NoZWR1bGVyLmV4YW1wbGUvY2FsbGJhY2tzL2NvbXBsZXRpb24ifSwidHJpZ2dlciI6eyJraW5kIjoiYXV0b21hdGljIn0sImRhdGEiOnt9fQ==",
+        exactBodyUtf8: CALLBACK_DELIVERY_COMPLETION_VECTOR_BODY,
+        headers: {
+            "Callback-Delivery-Id": "dlv_0123456789abcdefghjkmnpqrs",
+            "Callback-Key-Id": "csk_0123456789abcdefghjkmnpqrs",
+            "Callback-Occurrence-Id": "occ_0123456789abcdefghjkmnpqrs",
+            "Callback-Signature": "v1=38c6d854051087ed408a5f6252d90375859f305aeb0bca1c3f3a5bb63135e138",
+            "Callback-Timestamp": "2026-07-28T15:00:00.000Z",
+            "Content-Type": CALLBACK_CONTENT_TYPE,
+        },
+        secret: "greatwait-signature-vector-key-not-a-credential",
+        signingInputBase64: "MjAyNi0wNy0yOFQxNTowMDowMC4wMDBaLmRsdl8wMTIzNDU2Nzg5YWJjZGVmZ2hqa21ucHFycy57InZlcnNpb24iOiIyMDI2LTA4LTA4IiwidHlwZSI6InNjaGVkdWxlLm9jY3VycmVuY2UiLCJzY2hlZHVsZUlkIjoic2NoXzAxMjM0NTY3ODlhYmNkZWZnaGprbW5wcXJzIiwib2NjdXJyZW5jZUlkIjoib2NjXzAxMjM0NTY3ODlhYmNkZWZnaGprbW5wcXJzIiwicGxhbm5lZEZvciI6IjIwMjYtMDctMjhUMTU6MDA6MDAuMDAwWiIsImF0dGVtcHQiOjEsImNvbXBsZXRpb24iOnsidG9rZW4iOiJ2MS5leGFtcGxlLWNsYWltLW5vdC1hLXJlYWwtdG9rZW4uZXhhbXBsZS1tYWMiLCJ1cmwiOiJodHRwczovL2dyZWF0d2FpdC1zY2hlZHVsZXIuZXhhbXBsZS9jYWxsYmFja3MvY29tcGxldGlvbiJ9LCJ0cmlnZ2VyIjp7ImtpbmQiOiJhdXRvbWF0aWMifSwiZGF0YSI6e319",
+        signingInputUtf8: CALLBACK_DELIVERY_COMPLETION_VECTOR_INPUT,
+    },
+    /**
+     * A redelivery, which is the only vector that discriminates this change.
+     *
+     * The two automatic vectors would still pass an implementation that dropped
+     * `trigger` on the floor and hard-coded `{"kind":"automatic"}`; this one
+     * cannot, because both the kind and the source attempt are inside the signed
+     * bytes.
+     */
+    redeliveryTestVector: {
+        envelope: {
+            attempt: 2,
+            completion: {
+                deadline: "2026-07-28T15:00:05.000Z",
+                token: "v2.example-claim-not-a-real-token.example-mac",
+                url: "https://greatwait-scheduler.example/callbacks/completion",
+            },
+            data: {},
+            occurrenceId: "occ_0123456789abcdefghjkmnpqrs",
+            plannedFor: "2026-07-28T15:00:00.000Z",
+            scheduleId: "sch_0123456789abcdefghjkmnpqrs",
+            trigger: {
+                kind: "redelivery",
+                sourceAttemptId: "att_0123456789abcdefghjkmnpqrs",
+            },
+            type: "schedule.occurrence",
+            version: CALLBACK_ENVELOPE_VERSION,
+        },
+        exactBodyBase64: "eyJ2ZXJzaW9uIjoiMjAyNi0wOC0yMyIsInR5cGUiOiJzY2hlZHVsZS5vY2N1cnJlbmNlIiwic2NoZWR1bGVJZCI6InNjaF8wMTIzNDU2Nzg5YWJjZGVmZ2hqa21ucHFycyIsIm9jY3VycmVuY2VJZCI6Im9jY18wMTIzNDU2Nzg5YWJjZGVmZ2hqa21ucHFycyIsInBsYW5uZWRGb3IiOiIyMDI2LTA3LTI4VDE1OjAwOjAwLjAwMFoiLCJhdHRlbXB0IjoyLCJjb21wbGV0aW9uIjp7InRva2VuIjoidjIuZXhhbXBsZS1jbGFpbS1ub3QtYS1yZWFsLXRva2VuLmV4YW1wbGUtbWFjIiwidXJsIjoiaHR0cHM6Ly9ncmVhdHdhaXQtc2NoZWR1bGVyLmV4YW1wbGUvY2FsbGJhY2tzL2NvbXBsZXRpb24iLCJkZWFkbGluZSI6IjIwMjYtMDctMjhUMTU6MDA6MDUuMDAwWiJ9LCJ0cmlnZ2VyIjp7ImtpbmQiOiJyZWRlbGl2ZXJ5Iiwic291cmNlQXR0ZW1wdElkIjoiYXR0XzAxMjM0NTY3ODlhYmNkZWZnaGprbW5wcXJzIn0sImRhdGEiOnt9fQ==",
+        exactBodyUtf8: CALLBACK_DELIVERY_REDELIVERY_VECTOR_BODY,
+        headers: {
+            "Callback-Delivery-Id": "dlv_0123456789abcdefghjkmnpqrs",
+            "Callback-Key-Id": "csk_0123456789abcdefghjkmnpqrs",
+            "Callback-Occurrence-Id": "occ_0123456789abcdefghjkmnpqrs",
+            "Callback-Signature": "v1=9d698aed6d05dcd964f00d6e6796aab238f4f50e6f5cfeb61751fd7850778a04",
+            "Callback-Timestamp": "2026-07-28T15:00:00.000Z",
+            "Content-Type": CALLBACK_CONTENT_TYPE,
+        },
+        secret: "greatwait-signature-vector-key-not-a-credential",
+        signingInputBase64: "MjAyNi0wNy0yOFQxNTowMDowMC4wMDBaLmRsdl8wMTIzNDU2Nzg5YWJjZGVmZ2hqa21ucHFycy57InZlcnNpb24iOiIyMDI2LTA4LTIzIiwidHlwZSI6InNjaGVkdWxlLm9jY3VycmVuY2UiLCJzY2hlZHVsZUlkIjoic2NoXzAxMjM0NTY3ODlhYmNkZWZnaGprbW5wcXJzIiwib2NjdXJyZW5jZUlkIjoib2NjXzAxMjM0NTY3ODlhYmNkZWZnaGprbW5wcXJzIiwicGxhbm5lZEZvciI6IjIwMjYtMDctMjhUMTU6MDA6MDAuMDAwWiIsImF0dGVtcHQiOjIsImNvbXBsZXRpb24iOnsidG9rZW4iOiJ2Mi5leGFtcGxlLWNsYWltLW5vdC1hLXJlYWwtdG9rZW4uZXhhbXBsZS1tYWMiLCJ1cmwiOiJodHRwczovL2dyZWF0d2FpdC1zY2hlZHVsZXIuZXhhbXBsZS9jYWxsYmFja3MvY29tcGxldGlvbiIsImRlYWRsaW5lIjoiMjAyNi0wNy0yOFQxNTowMDowNS4wMDBaIn0sInRyaWdnZXIiOnsia2luZCI6InJlZGVsaXZlcnkiLCJzb3VyY2VBdHRlbXB0SWQiOiJhdHRfMDEyMzQ1Njc4OWFiY2RlZmdoamttbnBxcnMifSwiZGF0YSI6e319",
+        signingInputUtf8: CALLBACK_DELIVERY_REDELIVERY_VECTOR_INPUT,
+    },
+    /**
+     * The ordinary current-version delivery: automatic, and carrying completion
+     * material because every `2026-08-23` delivery does.
+     */
+    testVector: {
+        envelope: {
+            attempt: 1,
+            completion: {
+                deadline: "2026-07-28T15:00:05.000Z",
+                token: "v2.example-claim-not-a-real-token.example-mac",
+                url: "https://greatwait-scheduler.example/callbacks/completion",
+            },
+            data: {},
+            occurrenceId: "occ_0123456789abcdefghjkmnpqrs",
+            plannedFor: "2026-07-28T15:00:00.000Z",
+            scheduleId: "sch_0123456789abcdefghjkmnpqrs",
+            trigger: { kind: "automatic" },
+            type: "schedule.occurrence",
+            version: CALLBACK_ENVELOPE_VERSION,
+        },
+        exactBodyBase64: "eyJ2ZXJzaW9uIjoiMjAyNi0wOC0yMyIsInR5cGUiOiJzY2hlZHVsZS5vY2N1cnJlbmNlIiwic2NoZWR1bGVJZCI6InNjaF8wMTIzNDU2Nzg5YWJjZGVmZ2hqa21ucHFycyIsIm9jY3VycmVuY2VJZCI6Im9jY18wMTIzNDU2Nzg5YWJjZGVmZ2hqa21ucHFycyIsInBsYW5uZWRGb3IiOiIyMDI2LTA3LTI4VDE1OjAwOjAwLjAwMFoiLCJhdHRlbXB0IjoxLCJjb21wbGV0aW9uIjp7InRva2VuIjoidjIuZXhhbXBsZS1jbGFpbS1ub3QtYS1yZWFsLXRva2VuLmV4YW1wbGUtbWFjIiwidXJsIjoiaHR0cHM6Ly9ncmVhdHdhaXQtc2NoZWR1bGVyLmV4YW1wbGUvY2FsbGJhY2tzL2NvbXBsZXRpb24iLCJkZWFkbGluZSI6IjIwMjYtMDctMjhUMTU6MDA6MDUuMDAwWiJ9LCJ0cmlnZ2VyIjp7ImtpbmQiOiJhdXRvbWF0aWMifSwiZGF0YSI6e319",
+        exactBodyUtf8: CALLBACK_DELIVERY_VECTOR_BODY,
+        headers: {
+            "Callback-Delivery-Id": "dlv_0123456789abcdefghjkmnpqrs",
+            "Callback-Key-Id": "csk_0123456789abcdefghjkmnpqrs",
+            "Callback-Occurrence-Id": "occ_0123456789abcdefghjkmnpqrs",
+            "Callback-Signature": "v1=5bf68b786fbac1afa7e3474ae5039ad27900b0185bca43a3e45185d56315a312",
+            "Callback-Timestamp": "2026-07-28T15:00:00.000Z",
+            "Content-Type": CALLBACK_CONTENT_TYPE,
+        },
+        secret: "greatwait-signature-vector-key-not-a-credential",
+        signingInputBase64: "MjAyNi0wNy0yOFQxNTowMDowMC4wMDBaLmRsdl8wMTIzNDU2Nzg5YWJjZGVmZ2hqa21ucHFycy57InZlcnNpb24iOiIyMDI2LTA4LTIzIiwidHlwZSI6InNjaGVkdWxlLm9jY3VycmVuY2UiLCJzY2hlZHVsZUlkIjoic2NoXzAxMjM0NTY3ODlhYmNkZWZnaGprbW5wcXJzIiwib2NjdXJyZW5jZUlkIjoib2NjXzAxMjM0NTY3ODlhYmNkZWZnaGprbW5wcXJzIiwicGxhbm5lZEZvciI6IjIwMjYtMDctMjhUMTU6MDA6MDAuMDAwWiIsImF0dGVtcHQiOjEsImNvbXBsZXRpb24iOnsidG9rZW4iOiJ2Mi5leGFtcGxlLWNsYWltLW5vdC1hLXJlYWwtdG9rZW4uZXhhbXBsZS1tYWMiLCJ1cmwiOiJodHRwczovL2dyZWF0d2FpdC1zY2hlZHVsZXIuZXhhbXBsZS9jYWxsYmFja3MvY29tcGxldGlvbiIsImRlYWRsaW5lIjoiMjAyNi0wNy0yOFQxNTowMDowNS4wMDBaIn0sInRyaWdnZXIiOnsia2luZCI6ImF1dG9tYXRpYyJ9LCJkYXRhIjp7fX0=",
+        signingInputUtf8: CALLBACK_DELIVERY_VECTOR_INPUT,
+    },
+    unicodeTestVector: {
+        envelope: {
+            attempt: 1,
+            completion: {
+                deadline: "2026-07-28T15:00:05.000Z",
+                token: "v2.example-claim-not-a-real-token.example-mac",
+                url: "https://greatwait-scheduler.example/callbacks/completion",
+            },
+            data: { note: "café ☃" },
+            occurrenceId: "occ_0123456789abcdefghjkmnpqrs",
+            plannedFor: "2026-07-28T15:00:00.000Z",
+            scheduleId: "sch_0123456789abcdefghjkmnpqrs",
+            trigger: { kind: "automatic" },
+            type: "schedule.occurrence",
+            version: CALLBACK_ENVELOPE_VERSION,
+        },
+        exactBodyBase64: "eyJ2ZXJzaW9uIjoiMjAyNi0wOC0yMyIsInR5cGUiOiJzY2hlZHVsZS5vY2N1cnJlbmNlIiwic2NoZWR1bGVJZCI6InNjaF8wMTIzNDU2Nzg5YWJjZGVmZ2hqa21ucHFycyIsIm9jY3VycmVuY2VJZCI6Im9jY18wMTIzNDU2Nzg5YWJjZGVmZ2hqa21ucHFycyIsInBsYW5uZWRGb3IiOiIyMDI2LTA3LTI4VDE1OjAwOjAwLjAwMFoiLCJhdHRlbXB0IjoxLCJjb21wbGV0aW9uIjp7InRva2VuIjoidjIuZXhhbXBsZS1jbGFpbS1ub3QtYS1yZWFsLXRva2VuLmV4YW1wbGUtbWFjIiwidXJsIjoiaHR0cHM6Ly9ncmVhdHdhaXQtc2NoZWR1bGVyLmV4YW1wbGUvY2FsbGJhY2tzL2NvbXBsZXRpb24iLCJkZWFkbGluZSI6IjIwMjYtMDctMjhUMTU6MDA6MDUuMDAwWiJ9LCJ0cmlnZ2VyIjp7ImtpbmQiOiJhdXRvbWF0aWMifSwiZGF0YSI6eyJub3RlIjoiY2Fmw6kg4piDIn19",
+        exactBodyUtf8: CALLBACK_DELIVERY_UNICODE_VECTOR_BODY,
+        headers: {
+            "Callback-Delivery-Id": "dlv_0123456789abcdefghjkmnpqrs",
+            "Callback-Key-Id": "csk_0123456789abcdefghjkmnpqrs",
+            "Callback-Occurrence-Id": "occ_0123456789abcdefghjkmnpqrs",
+            "Callback-Signature": "v1=18a8d1c50ea54bd0a5ec27abe80d1c98e44a7f358ecf8f06615c174075100e72",
+            "Callback-Timestamp": "2026-07-28T15:00:00.000Z",
+            "Content-Type": CALLBACK_CONTENT_TYPE,
+        },
+        secret: "greatwait-signature-vector-key-not-a-credential",
+        signingInputBase64: "MjAyNi0wNy0yOFQxNTowMDowMC4wMDBaLmRsdl8wMTIzNDU2Nzg5YWJjZGVmZ2hqa21ucHFycy57InZlcnNpb24iOiIyMDI2LTA4LTIzIiwidHlwZSI6InNjaGVkdWxlLm9jY3VycmVuY2UiLCJzY2hlZHVsZUlkIjoic2NoXzAxMjM0NTY3ODlhYmNkZWZnaGprbW5wcXJzIiwib2NjdXJyZW5jZUlkIjoib2NjXzAxMjM0NTY3ODlhYmNkZWZnaGprbW5wcXJzIiwicGxhbm5lZEZvciI6IjIwMjYtMDctMjhUMTU6MDA6MDAuMDAwWiIsImF0dGVtcHQiOjEsImNvbXBsZXRpb24iOnsidG9rZW4iOiJ2Mi5leGFtcGxlLWNsYWltLW5vdC1hLXJlYWwtdG9rZW4uZXhhbXBsZS1tYWMiLCJ1cmwiOiJodHRwczovL2dyZWF0d2FpdC1zY2hlZHVsZXIuZXhhbXBsZS9jYWxsYmFja3MvY29tcGxldGlvbiIsImRlYWRsaW5lIjoiMjAyNi0wNy0yOFQxNTowMDowNS4wMDBaIn0sInRyaWdnZXIiOnsia2luZCI6ImF1dG9tYXRpYyJ9LCJkYXRhIjp7Im5vdGUiOiJjYWbDqSDimIMifX0=",
+        signingInputUtf8: CALLBACK_DELIVERY_UNICODE_VECTOR_INPUT,
+    },
+    version: CALLBACK_DELIVERY_PROTOCOL_VERSION,
+};
+/**
+ * Every published vector, derived from the protocol rather than listed.
+ *
+ * **A hand-written list is the failure this exists to prevent.** The duplicated
+ * serializer in `@greatwait/delivery` is held byte-for-byte against these, and
+ * the one time it drifted, it drifted on the field whose vector nobody had
+ * added to the list yet. Reading the protocol object means a vector added later
+ * is driven by every suite that already iterates this, with no second edit.
+ *
+ * **Matched by shape rather than by name**, which is not fastidiousness: the
+ * first version of this matched keys ending in `TestVector` and silently
+ * dropped `testVector`, whose lower-case first letter makes that suffix test
+ * false. A filter that quietly returns one fewer than it should is the same
+ * failure as the hand-written list, arrived at differently.
+ */
+export function callbackDeliveryTestVectors() {
+    return Object.entries(CALLBACK_DELIVERY_PROTOCOL)
+        .filter(([, value]) => typeof value === "object" &&
+        value !== null &&
+        typeof value.exactBodyUtf8 === "string")
+        .map(([name, vector]) => ({
+        ...vector,
+        name,
+    }));
+}
+/**
+ * What moving the envelope to `2026-08-08` is, in the vocabulary the
+ * compatibility module classifies.
+ *
+ * Recorded as data rather than asserted in prose because the verdict is an
+ * output: `assess(CALLBACK_ENVELOPE_VERSION_CHANGE)` returns
+ * `{ kind: "breaking", requiresNewContractVersion: true }`, and a fixture holds
+ * it there. "It only added a field, so it is additive" is the reading this
+ * exists to refuse — what a client parses is not the field, it is the version
+ * literal, and that literal *changed*.
+ *
+ * The contract version does not move with it. `CONTRACT_VERSION` versions the
+ * REST surface; the envelope carries its own dated version precisely so a break
+ * in the callback body does not force every API client to re-pin.
+ */
+export const CALLBACK_ENVELOPE_VERSION_CHANGE = {
+    operation: "changed",
+    subject: "response-field",
+};
+/**
+ * Classifies a status code alone. Use `classifyOutcome` where a request may not
+ * complete.
+ *
+ * **`isCallbackRefusalStatus` is consulted rather than duplicated here.** This
+ * function is the published statement of what a receiver's answer means and
+ * `performGreatwaitAttempt` is what acts on it; before FXO-1596 the two carried
+ * the same status boundary as two independent literals, kept equal by hand.
+ * They are now one list, so a status cannot be retried by the executor while
+ * this function tells the customer it was terminal.
+ */
+export function classifyStatus(status) {
+    if (status >= 200 && status < 300) {
+        return "success";
+    }
+    if (status === 408 || status === 429 || status >= 500) {
+        return "retryable";
+    }
+    // A refusal is retryable to a receiver author for the same reason it is to
+    // the executor: the cause is theirs to fix, and the delivery that follows the
+    // fix carries the identical bytes.
+    return isCallbackRefusalStatus(status) ? "retryable" : "terminal";
+}
+export function classifyOutcome(outcome) {
+    // A lost response is ambiguous, never terminal. Treating it as a customer
+    // refusal would drop the occurrence without ever retrying it.
+    return outcome.kind === "no-response"
+        ? "ambiguous"
+        : classifyStatus(outcome.status);
+}