@greatwait/contracts 0.1.0-alpha.1

package/dist/test-sink.js

@@ -0,0 +1,755 @@
+import { z } from "zod";
+import { CALLBACK_DEFERRAL_STATUS, CALLBACK_PENDING_DISCRIMINATOR, } from "./delivery.js";
+import { callbackSigningKeyIdSchema, deliveryIdSchema, endpointIdSchema, occurrenceIdSchema, projectIdSchema, scheduleIdSchema, testSinkDeliveryIdSchema, testSinkIdSchema, } from "./identifiers.js";
+import { pageSchema } from "./protocol.js";
+import { CALLBACK_HEADERS, signatureHeaderSchema } from "./signatures.js";
+import { timestampSchema } from "./time.js";
+/**
+ * The deterministic test sink and the receiver contract it and the shipped
+ * middleware both implement.
+ *
+ * An integrator cannot rehearse a delivery failure against their own receiver
+ * without first building one that fails on demand, and the failures that matter
+ * — a dropped connection, a receiver that answers three minutes late, a 429
+ * carrying a delay hint — are exactly the ones hardest to produce by hand. The
+ * sink produces them on request, in test environments only.
+ *
+ * Two properties are load-bearing and are the reason this vocabulary lives in
+ * the contract package rather than inside the API Worker.
+ *
+ * **The sink and the SDK middleware must agree.** The sink is a reference
+ * receiver built on the middleware this story ships, so an integrator who
+ * compares the two is comparing one implementation against itself. That is only
+ * worth anything if the status a receiver returns for each outcome is published
+ * rather than chosen twice — hence `CALLBACK_RECEIVER_STATUS` below.
+ *
+ * **A sink is a receiver, and the only thing it ever sends is a report about a
+ * delivery it has already received.** That sentence used to read "never a
+ * sender", and the deferring behaviors added on 2026-08-23 are why it does not:
+ * a receiver that defers is one that answers `202` now and reports later, and a
+ * sink that could not report later could rehearse the first half of that
+ * exchange and none of the half where it goes wrong.
+ *
+ * What has not changed is that **there is deliberately no field anywhere in
+ * this file that names a place to send to.** A completion report goes to the
+ * credential inside the signed envelope of the delivery in hand, sent to the
+ * one address the stage is configured with, and
+ * nowhere else: no program, no control operation and no request header names a
+ * destination, so a sink still cannot be asked to forward, redirect or fetch,
+ * and still cannot be configured into an egress proxy. A delivery whose
+ * envelope carries no completion material cannot defer at all.
+ */
+/* -------------------------------------------------------------------------- */
+/* Failure simulation                                                          */
+/* -------------------------------------------------------------------------- */
+/**
+ * What a sink does with a delivery. Exhaustive, and each entry corresponds to a
+ * distinct sender-visible outcome class rather than to a distinct status code.
+ *
+ * `timeout` and `disconnect` are both ambiguous to the sender, and that is the
+ * point rather than a defect in the simulation: a sender genuinely cannot tell
+ * them apart, which is why the architecture records ambiguity honestly instead
+ * of guessing. They differ in what the *receiver* did — see
+ * `TEST_SINK_BEHAVIOR_FACTS`.
+ *
+ * **The three `defer_*` behaviors are three entries rather than one entry with
+ * an option**, for exactly the reason stated above: they produce three
+ * different sender-visible outcomes. All three answer the same `202` and the
+ * same pending marker, so a list that collapsed them would be a list keyed on
+ * the status a receiver returns — which is the thing this list is deliberately
+ * not keyed on. What separates them happens *after* the acknowledgement, and it
+ * is the whole of what an integrator rehearsing deferral needs to see.
+ */
+export const TEST_SINK_BEHAVIORS = [
+    "client_error",
+    "defer_abandon",
+    "defer_fail",
+    "defer_succeed",
+    "delay",
+    "disconnect",
+    "duplicate",
+    "invalid_signature",
+    "rate_limited",
+    "server_error",
+    "success",
+    "timeout",
+];
+export const testSinkBehaviorSchema = z.enum(TEST_SINK_BEHAVIORS);
+/**
+ * Bounds on what a sink may be asked to do.
+ *
+ * Every one of these exists because the sink runs inside the API Worker's
+ * request budget on the product's own account. A test facility that can be
+ * asked to hold a request open indefinitely, or to accumulate history without
+ * limit, is a denial-of-service surface wearing a test badge.
+ */
+export const TEST_SINK_BOUNDS = {
+    /**
+     * Longest a sink will wait between acknowledging a deferral and reporting
+     * completion.
+     *
+     * Bounded for the same reason `maxDelayMs` is, and the reason survives the
+     * response having already been sent: the report is performed on the same
+     * invocation, so a sink asked to report an hour later would be asking the API
+     * Worker to stay alive for an hour on the product's own account. Smaller than
+     * `maxDelayMs` because nothing is waiting on this wait — a rehearsal of
+     * deferral is a rehearsal of the *shape* of the exchange, and any integrator
+     * who needs to watch a real deadline expire has `defer_abandon`, which costs
+     * nothing at all.
+     */
+    maxCompletionDelayMs: 5_000,
+    /** Longest `delay` a sink will honour before answering. */
+    maxDelayMs: 10_000,
+    /** Longest a `timeout` or `disconnect` holds a request open. */
+    maxHoldMs: 45_000,
+    /** Retained delivery receipts per sink; the oldest are evicted. */
+    maxRetainedDeliveries: 50,
+    /** Sinks per project/environment. */
+    maxSinksPerEnvironment: 10,
+    /** Largest request body a sink will read. Larger is refused unread. */
+    maxRequestBodyBytes: 65_536,
+    /** Captured body bytes retained on a receipt; beyond this it is truncated. */
+    maxRetainedBodyBytes: 4_096,
+};
+/**
+ * Selected 4xx a sink may answer with.
+ *
+ * **They are no longer all terminal to the sender, and which are is not this
+ * file's decision.** FXO-1596 moved the refusals — a receiver declining *this
+ * delivery now* rather than objecting to the message — onto the receiver's
+ * ordinary five-failure budget. `TEST_SINK_REFUSAL_STATUSES` below is the
+ * subset of this list that the sender will retry, and `test-sink.test.ts`
+ * holds it equal to what `classifyStatus` actually says, so a status moved in
+ * `CALLBACK_REFUSAL_STATUSES` and not here fails a test rather than teaching an
+ * integrator the wrong lesson.
+ *
+ * Nothing is removed from what a caller may request: every status here was
+ * accepted before and still is.
+ */
+export const TEST_SINK_CLIENT_ERROR_STATUSES = [
+    400, 401, 403, 404, 409, 410, 422,
+];
+/**
+ * The statuses above that the sender retries rather than settling on.
+ *
+ * Exists so an integrator simulating a rotated credential (401) or a WAF rule
+ * (403) can see five attempts arrive, and one simulating a malformed body (400)
+ * or a duplicate (409) can see exactly one.
+ */
+export const TEST_SINK_REFUSAL_STATUSES = [401, 403, 404];
+/** Selected 5xx a sink may answer with. Each is retryable to the sender. */
+export const TEST_SINK_SERVER_ERROR_STATUSES = [500, 502, 503, 504];
+/**
+ * A deterministic behavior program.
+ *
+ * `behavior` applies to the first `forDeliveries` deliveries and `then` to
+ * every one after that, so "fail twice, then succeed" is one declaration rather
+ * than a sequence of control calls racing the schedule that is firing. Leaving
+ * `forDeliveries` out makes `behavior` permanent, which is what a single
+ * failure mode under test wants.
+ *
+ * The count is over deliveries this sink has *received*, not over a particular
+ * occurrence's attempts: a sink is a destination and does not get to know which
+ * occurrence the sender considers current.
+ */
+export const testSinkProgramSchema = z
+    .object({
+    behavior: testSinkBehaviorSchema,
+    /**
+     * Milliseconds between acknowledging a deferral and reporting completion.
+     * Only meaningful for a behavior that reports one.
+     */
+    completionDelayMs: z
+        .number()
+        .int()
+        .positive()
+        .max(TEST_SINK_BOUNDS.maxCompletionDelayMs)
+        .optional(),
+    /** Milliseconds to wait before answering. Only meaningful for `delay`. */
+    delayMs: z
+        .number()
+        .int()
+        .positive()
+        .max(TEST_SINK_BOUNDS.maxDelayMs)
+        .optional(),
+    /**
+     * How many deliveries `behavior` applies to before `then` takes over.
+     * Absent means "every delivery".
+     */
+    forDeliveries: z.number().int().positive().max(100).optional(),
+    /** `Retry-After` seconds sent with `rate_limited`. */
+    retryAfterSeconds: z.number().int().positive().max(300).optional(),
+    /** Which 4xx or 5xx to answer with. Defaults per behavior. */
+    status: z.number().int().min(400).max(599).optional(),
+    /** Behavior after `forDeliveries` is exhausted. Defaults to `success`. */
+    then: testSinkBehaviorSchema.optional(),
+})
+    .superRefine((program, context) => {
+    if (program.status !== undefined) {
+        const allowed = program.behavior === "client_error"
+            ? TEST_SINK_CLIENT_ERROR_STATUSES
+            : program.behavior === "server_error"
+                ? TEST_SINK_SERVER_ERROR_STATUSES
+                : [];
+        if (!allowed.includes(program.status)) {
+            context.addIssue({
+                code: "custom",
+                message: "status is only accepted with client_error or server_error, and only from the published list",
+                path: ["status"],
+            });
+        }
+    }
+    if (program.delayMs !== undefined && program.behavior !== "delay") {
+        context.addIssue({
+            code: "custom",
+            message: "delayMs is only accepted with the delay behavior",
+            path: ["delayMs"],
+        });
+    }
+    // The gap before a *report*, so it is only meaningful for a behavior that
+    // sends one. `defer_abandon` deliberately sends none, and accepting a delay
+    // there would read as configured while nothing would ever honour it —
+    // the same reason `then` without `forDeliveries` is refused below.
+    //
+    // Read off the facts rather than off a list of behavior names: the facts
+    // are what the runtime resolves against, so a behavior that stopped
+    // reporting would stop accepting the modifier in the same edit.
+    if (program.completionDelayMs !== undefined &&
+        !reportsCompletion(program.behavior)) {
+        context.addIssue({
+            code: "custom",
+            message: "completionDelayMs is only accepted with a behavior that reports completion",
+            path: ["completionDelayMs"],
+        });
+    }
+    if (program.retryAfterSeconds !== undefined &&
+        program.behavior !== "rate_limited") {
+        context.addIssue({
+            code: "custom",
+            message: "retryAfterSeconds is only accepted with the rate_limited behavior",
+            path: ["retryAfterSeconds"],
+        });
+    }
+    // `then` exists to end a bounded run of failures. Without `forDeliveries`
+    // it is unreachable, and a program with an unreachable half reads as
+    // configured when it is not.
+    if (program.then !== undefined && program.forDeliveries === undefined) {
+        context.addIssue({
+            code: "custom",
+            message: "then requires forDeliveries",
+            path: ["then"],
+        });
+    }
+});
+/**
+ * What each behavior does, as data rather than prose, so the published artifact
+ * and the implementation cannot drift and a receiver author can read the whole
+ * simulation without running it.
+ *
+ * `senderOutcome` is stated in the vocabulary of `classifyOutcome`, which is
+ * what the delivery path actually applies. `receiverActed` is the honest answer
+ * to "may the receiver have processed this?" — the question a sender cannot
+ * answer for itself and must therefore record as ambiguity.
+ *
+ * `deferredReport` is present on the behaviors that acknowledge now and report
+ * later, and it is the reason `senderOutcome` cannot be derived from
+ * `defaultStatus` for those three: all three answer the same `202`, which
+ * `classifyStatus` reads as an ordinary success, and what the sender finally
+ * records comes from the report — or, for `never`, from the deadline passing
+ * with no report at all.
+ */
+export const TEST_SINK_BEHAVIOR_FACTS = {
+    client_error: {
+        defaultStatus: 422,
+        deferredReport: undefined,
+        receiverActed: false,
+        senderOutcome: "terminal",
+        summary: "Answers a selected 4xx. The sender records a customer refusal, and retries it only when the status is one the receiver may recover from — 401, 403 and 404, listed as `clientErrorStatusesRetried`. The default, 422, is not one of those, so it settles on the first attempt.",
+    },
+    defer_abandon: {
+        defaultStatus: CALLBACK_DEFERRAL_STATUS,
+        deferredReport: "never",
+        // It answered 202, which is the receiver taking the work. That is what
+        // makes this the ambiguity the deadline exists for rather than a failure:
+        // the work may well have run, and nothing anyone can observe says whether
+        // it did.
+        receiverActed: true,
+        senderOutcome: "ambiguous",
+        summary: "Acknowledges the delivery and then never reports at all. The sender waits until the deadline in the envelope and records ambiguity, because a receiver that took the work and went quiet may well have done it. This is the case the completion deadline exists to bound.",
+    },
+    defer_fail: {
+        defaultStatus: CALLBACK_DEFERRAL_STATUS,
+        deferredReport: "failed",
+        receiverActed: true,
+        senderOutcome: "retryable",
+        summary: "Acknowledges the delivery, then reports `failed` with the credential in its signed envelope. The occurrence goes back on the ordinary retry ladder — the same place a 500 puts it — which is how a receiver says its job died rather than that it vanished.",
+    },
+    defer_succeed: {
+        defaultStatus: CALLBACK_DEFERRAL_STATUS,
+        deferredReport: "succeeded",
+        receiverActed: true,
+        senderOutcome: "success",
+        summary: "Acknowledges the delivery with 202 and the pending marker, keeps the work, then reports `succeeded` with the credential in its signed envelope. The whole deferred exchange, without writing a receiver.",
+    },
+    delay: {
+        defaultStatus: 200,
+        deferredReport: undefined,
+        receiverActed: true,
+        senderOutcome: "success",
+        summary: "Waits a bounded interval, then accepts. Exercises a slow receiver that still succeeds.",
+    },
+    disconnect: {
+        defaultStatus: undefined,
+        deferredReport: undefined,
+        receiverActed: false,
+        senderOutcome: "ambiguous",
+        summary: "Authenticates the delivery and then drops the connection without processing it, holding until the sender gives up. Nothing was claimed and nothing ran, but the sender cannot know that.",
+    },
+    duplicate: {
+        defaultStatus: 200,
+        deferredReport: undefined,
+        receiverActed: false,
+        senderOutcome: "success",
+        summary: "Accepts and reports the occurrence as already handled, without processing it again. What occurrence idempotency looks like from the sender's side.",
+    },
+    invalid_signature: {
+        defaultStatus: 401,
+        deferredReport: undefined,
+        receiverActed: false,
+        // Retryable since FXO-1596, and the reversal is deliberate. The reasoning
+        // it replaces was that a key mismatch cannot self-heal the way a stale
+        // timestamp does — true of a mismatch caused by our own signing, and wrong
+        // about the population that actually occurs, which is a receiver holding a
+        // credential it has rotated or not yet deployed. That fixes itself on their
+        // next release, and the delivery that follows carries a fresh signature.
+        senderOutcome: "retryable",
+        summary: "Rejects the delivery as unauthenticated regardless of whether the signature verified. Exercises the key-mismatch path without forging a signature. The sender retries on the receiver's ordinary budget, because the usual cause is a credential the receiver is about to redeploy.",
+    },
+    rate_limited: {
+        defaultStatus: 429,
+        deferredReport: undefined,
+        receiverActed: false,
+        senderOutcome: "retryable",
+        summary: "Answers 429 with a bounded Retry-After. The sender honours the hint and does not spend its give-up budget.",
+    },
+    server_error: {
+        defaultStatus: 503,
+        deferredReport: undefined,
+        receiverActed: false,
+        senderOutcome: "retryable",
+        summary: "Answers a selected 5xx. The sender retries with backoff.",
+    },
+    success: {
+        defaultStatus: 200,
+        deferredReport: undefined,
+        receiverActed: true,
+        senderOutcome: "success",
+        summary: "Verifies, records, and accepts.",
+    },
+    timeout: {
+        defaultStatus: undefined,
+        deferredReport: undefined,
+        receiverActed: true,
+        senderOutcome: "ambiguous",
+        summary: "Verifies and records the delivery, then never answers. The receiver acted and the sender cannot know it.",
+    },
+};
+/**
+ * Whether this behavior acknowledges now and reports later.
+ *
+ * `defer_abandon` defers and does *not* report, so the two questions are
+ * separate ones and a caller asking "does it defer" must not be answered with
+ * "does it report".
+ */
+function defersCompletion(behavior) {
+    return TEST_SINK_BEHAVIOR_FACTS[behavior].deferredReport !== undefined;
+}
+/** The outcome this behavior reports, or `undefined` if it reports nothing. */
+function completionReportFor(behavior) {
+    const report = TEST_SINK_BEHAVIOR_FACTS[behavior].deferredReport;
+    return report === undefined || report === "never" ? undefined : report;
+}
+/** Whether this behavior sends a completion report at all. */
+function reportsCompletion(behavior) {
+    return completionReportFor(behavior) !== undefined;
+}
+/**
+ * The exact body a deferring sink answers with.
+ *
+ * Built from the published discriminator rather than written out, so a sink
+ * cannot emit a marker the sender does not recognise. Deliberately without
+ * `completeBy`: the sink's report follows within `completionDelayMs`, and an
+ * acknowledgement that named an instant that close would be asking the sender
+ * to stop waiting at roughly the moment the report arrives — a race the
+ * rehearsal would lose intermittently and blame on the protocol. A receiver
+ * that wants to bring its deadline forward is exercising
+ * `effectiveCompletionDeadlineMs`, which is the delivery path's own test rather
+ * than this simulation's.
+ */
+export const TEST_SINK_PENDING_ACKNOWLEDGEMENT = JSON.stringify({
+    [CALLBACK_PENDING_DISCRIMINATOR.key]: {
+        status: CALLBACK_PENDING_DISCRIMINATOR.status,
+    },
+});
+/**
+ * Resolve a program against how many deliveries this sink has already taken.
+ *
+ * Pure and total: the same `(program, deliveryIndex)` always produces the same
+ * action, which is what "deterministic" means here and what lets the same
+ * engine drive both the hosted sink and an offline conformance run.
+ *
+ * `deliveryIndex` is zero-based and counts every delivery the sink accepted for
+ * processing, including refused ones — a receiver that answers 401 has still
+ * received a request, and a program that said "fail the first two" must not be
+ * satisfiable by failing the same delivery twice.
+ */
+export function resolveTestSinkAction(program, deliveryIndex) {
+    const inFirstPhase = program.forDeliveries === undefined ||
+        deliveryIndex < program.forDeliveries;
+    const behavior = inFirstPhase
+        ? program.behavior
+        : (program.then ?? "success");
+    const facts = TEST_SINK_BEHAVIOR_FACTS[behavior];
+    const status = inFirstPhase
+        ? (program.status ?? facts.defaultStatus)
+        : facts.defaultStatus;
+    const retryAfterSeconds = behavior === "rate_limited"
+        ? ((inFirstPhase ? program.retryAfterSeconds : undefined) ?? 5)
+        : undefined;
+    const defers = defersCompletion(behavior);
+    const completionOutcome = completionReportFor(behavior);
+    return {
+        ...(defers ? { acknowledgement: TEST_SINK_PENDING_ACKNOWLEDGEMENT } : {}),
+        behavior,
+        claims: behavior !== "disconnect",
+        // Defaulted the way `delayMs` is, and for the same reason: the wait is the
+        // only thing separating a report that arrives after the response from one
+        // that races it, so a default of zero would make the rehearsal prove less
+        // than it appears to.
+        completionDelayMs: completionOutcome === undefined
+            ? 0
+            : ((inFirstPhase ? program.completionDelayMs : undefined) ?? 250),
+        ...(completionOutcome === undefined ? {} : { completionOutcome }),
+        defers,
+        delayMs: behavior === "delay"
+            ? ((inFirstPhase ? program.delayMs : undefined) ?? 250)
+            : 0,
+        hold: behavior === "timeout" || behavior === "disconnect",
+        ...(retryAfterSeconds === undefined ? {} : { retryAfterSeconds }),
+        ...(status === undefined ? {} : { status }),
+    };
+}
+/* -------------------------------------------------------------------------- */
+/* The receiver contract                                                       */
+/* -------------------------------------------------------------------------- */
+/**
+ * Every way a receiver can dispose of one delivery.
+ *
+ * `duplicate` and `replay` are both "already handled" and both succeed, and
+ * separating them is what makes an integrator's logs legible: `replay` is the
+ * same delivery identity arriving twice — a duplicated request — while
+ * `duplicate` is a *different* delivery for an occurrence already processed,
+ * which is what a retry after an ambiguous attempt, and what a customer-ordered
+ * redelivery, both look like on the wire.
+ *
+ * `in_flight` is the concurrent case: another worker holds the occurrence and
+ * has not finished. Answering success there would claim an outcome nobody has
+ * yet produced.
+ */
+export const CALLBACK_RECEIVER_DISPOSITIONS = [
+    "body_too_large",
+    "duplicate",
+    "handler_failed",
+    "in_flight",
+    "invalid_envelope",
+    "invalid_headers",
+    "invalid_signature",
+    "processed",
+    "replay",
+    "stale_timestamp",
+];
+export const callbackReceiverDispositionSchema = z.enum(CALLBACK_RECEIVER_DISPOSITIONS);
+/**
+ * What a sink recorded, which is one value wider than what a receiver can
+ * answer with.
+ *
+ * `connection_dropped` has no status because the point of it is that there was
+ * none: the sink modelled a connection that died before the receiver read
+ * anything, so nothing was authenticated and nothing ran. Widening
+ * `CALLBACK_RECEIVER_DISPOSITIONS` to hold it would break the property that
+ * makes that list useful — every member maps to exactly one status.
+ */
+export const TEST_SINK_DISPOSITIONS = [
+    ...CALLBACK_RECEIVER_DISPOSITIONS,
+    "connection_dropped",
+];
+export const testSinkDispositionSchema = z.enum(TEST_SINK_DISPOSITIONS);
+/**
+ * The HTTP status a conforming receiver returns for each disposition.
+ *
+ * Published, and published *here*, because the sender classifies on the status
+ * and the classification decides whether an occurrence retries, settles, or is
+ * abandoned. A receiver that picks its own numbers can be perfectly correct
+ * about what it did and still tell the sender the opposite.
+ *
+ * Each choice is answerable against `classifyStatus`:
+ *
+ * - `processed`, `duplicate`, `replay` — 200. All three mean the occurrence is
+ *   handled. A replayed or duplicated delivery answering 4xx would make the
+ *   sender record a terminal failure for work that succeeded, which is the
+ *   single most damaging thing a receiver can do.
+ * - `stale_timestamp` — 408, which is retryable. A clock skew wide enough to
+ *   fail tolerance is an operator problem no retry fixes, but a request held on
+ *   the network for six minutes is not, and every attempt re-signs with a fresh
+ *   timestamp, so the transient case self-heals and the permanent case exhausts
+ *   the attempt bound honestly.
+ * - `invalid_signature`, `invalid_headers` — 401, **retryable since
+ *   FXO-1596**, and this entry used to say the opposite. The reasoning it
+ *   replaces was that retrying with the same key cannot succeed and a retryable
+ *   answer would spend the give-up budget hiding a misconfiguration. That is
+ *   true of a mismatch in *our* signing and false of the population that
+ *   actually reaches a 401: a receiver holding a credential it has rotated,
+ *   expired, or not yet deployed. Those recover on the receiver's next release,
+ *   and the delivery after it carries a fresh signature. The misconfiguration
+ *   is not hidden either — five identical 401s settle the occurrence 82 seconds
+ *   later with the same `inspect_receiver` advice, five rows instead of one.
+ * - `invalid_envelope` — 400, terminal. The bytes authenticated and did not
+ *   parse, so the sender and receiver disagree about the contract.
+ * - `body_too_large` — 413, terminal, and matched to the `payload_too_large`
+ *   problem code the API surface already publishes.
+ * - `in_flight` — 503, retryable. Honest: someone else holds the occurrence.
+ * - `handler_failed` — 500, retryable. The receiver's own fault and worth
+ *   another attempt.
+ */
+export const CALLBACK_RECEIVER_STATUS = {
+    body_too_large: 413,
+    duplicate: 200,
+    handler_failed: 500,
+    in_flight: 503,
+    invalid_envelope: 400,
+    invalid_headers: 401,
+    invalid_signature: 401,
+    processed: 200,
+    replay: 200,
+    stale_timestamp: 408,
+};
+/**
+ * The response body a conforming receiver returns.
+ *
+ * Deliberately tiny and deliberately free of prose: a receiver's response is
+ * read by a machine, and a body that carries an exception message is how a
+ * receiver leaks its internals to whoever can provoke an error.
+ */
+export const callbackReceiverAcknowledgementSchema = z.object({
+    disposition: callbackReceiverDispositionSchema,
+    /** Present only when the delivery authenticated. */
+    occurrenceId: occurrenceIdSchema.optional(),
+});
+/* -------------------------------------------------------------------------- */
+/* The sink resource                                                           */
+/* -------------------------------------------------------------------------- */
+export const testSinkSchema = z.object({
+    createdAt: timestampSchema,
+    /** Deliveries this sink has received, across its whole retained lifetime. */
+    deliveryCount: z.number().int().nonnegative(),
+    /** The callback endpoint whose signing keys this sink verifies against. */
+    endpoint: endpointIdSchema,
+    /** Always `test`. Published so a reader never has to infer it. */
+    environmentKind: z.literal("test"),
+    id: testSinkIdSchema,
+    program: testSinkProgramSchema,
+    project: projectIdSchema,
+    updatedAt: timestampSchema,
+    /**
+     * Where to point the endpoint. Absolute and server-assigned.
+     *
+     * The scheme is the stage's own public origin rather than a fixed `https://`,
+     * which is not a weakening: every hosted stage is HTTPS, and a callback
+     * endpoint's URL policy refuses anything else outright, so a sink served over
+     * plain HTTP is one no endpoint can be pointed at. Asserting `https` here
+     * would only make the local development origin — `http://127.0.0.1` — fail
+     * schema validation instead of failing endpoint validation, which moves the
+     * refusal somewhere less informative.
+     */
+    url: z.url(),
+});
+export const testSinkPageSchema = pageSchema(testSinkSchema);
+export const testSinkCreateRequestSchema = z.object({
+    endpoint: endpointIdSchema,
+    /** Initial behavior. Defaults to plain acceptance. */
+    program: testSinkProgramSchema.optional(),
+});
+/* -------------------------------------------------------------------------- */
+/* Delivery receipts                                                           */
+/* -------------------------------------------------------------------------- */
+/**
+ * One received delivery, as the sink recorded it.
+ *
+ * The identifiers, the key that signed it, and the disposition are the whole of
+ * what a *list* returns. The exact body is available only from the single-record
+ * read, capped, and only in a test environment — see `testSinkDeliveryBodySchema`.
+ */
+export const testSinkDeliverySchema = z.object({
+    /** Which of the sink's behaviors produced the response. */
+    behavior: testSinkBehaviorSchema,
+    disposition: testSinkDispositionSchema,
+    /** The sender's delivery identity, from the signed header. */
+    delivery: deliveryIdSchema,
+    id: testSinkDeliveryIdSchema,
+    /** Absent when the delivery failed authentication. */
+    keyId: callbackSigningKeyIdSchema.optional(),
+    occurrenceId: occurrenceIdSchema.optional(),
+    receivedAt: timestampSchema,
+    /** Absent when the sink held the connection instead of answering. */
+    respondedWith: z.number().int().min(100).max(599).optional(),
+    scheduleId: scheduleIdSchema.optional(),
+    sink: testSinkIdSchema,
+});
+export const testSinkDeliveryPageSchema = pageSchema(testSinkDeliverySchema);
+/**
+ * One received delivery including the bytes that arrived.
+ *
+ * **The one deliberate exception to "callback bodies never leave the delivery
+ * path".** The rule exists because a payload is customer content and a log,
+ * metric, or support index is the wrong place for it. A test sink is none of
+ * those: it is a destination the customer created, in their own test
+ * environment, to look at what their receiver would have been sent, and
+ * withholding it would leave the sink unable to answer the first question
+ * anybody asks it.
+ *
+ * The exception is kept narrow rather than assumed safe. The body is available
+ * only from the single-delivery read and never from a listing, only under the
+ * creating authority, only in test, capped at
+ * `TEST_SINK_BOUNDS.maxRetainedBodyBytes` with the truncation stated, and never
+ * written to a log. `signature` is included because a MAC is not secret and
+ * comparing it against a locally computed one is how a receiver author finds a
+ * body-mutation bug; no signing key has a field anywhere in this file.
+ */
+export const testSinkDeliveryBodySchema = testSinkDeliverySchema.extend({
+    /** The exact bytes as received, UTF-8 decoded, possibly truncated. */
+    body: z.string(),
+    /** True when the body exceeded the retained cap and was cut. */
+    bodyTruncated: z.boolean(),
+    /** Exactly the bytes that arrived, before truncation. */
+    receivedBytes: z.number().int().nonnegative(),
+    /** The offered MAC. Public by construction; never a key. */
+    signature: signatureHeaderSchema.optional(),
+});
+/* -------------------------------------------------------------------------- */
+/* The published artifact                                                      */
+/* -------------------------------------------------------------------------- */
+/**
+ * Dated, and moved on 2026-08-23 because the sink gained the three deferring
+ * behaviors and the bound on how long one may wait before reporting. A reader
+ * holding the older artifact has a complete and correct description of a sink
+ * that could not defer.
+ */
+export const TEST_SINK_PROTOCOL_VERSION = "2026-08-23";
+/**
+ * The language-neutral receiver contract.
+ *
+ * A receiver written in any stack can be held to this: verify these bytes,
+ * answer these statuses, dedupe on this identity. It is generated beside
+ * OpenAPI so an integrator does not have to read TypeScript to write a Go
+ * receiver.
+ */
+export const CALLBACK_RECEIVER_PROTOCOL = {
+    idempotency: {
+        /**
+         * Stated plainly because it is the property most often got wrong, and the
+         * one the contract vocabulary already implies without saying so anywhere a
+         * receiver author would look.
+         */
+        occurrence: {
+            identity: CALLBACK_HEADERS.occurrenceId,
+            note: "Every automatic delivery of one occurrence — the first attempt and every retry the system chose — is at most one execution. A receiver claims the occurrence atomically and answers 200 for every later automatic delivery of it. This is what makes at-least-once delivery safe; a receiver that needs a second execution asks for a second occurrence, or a person orders a redelivery.",
+            requirement: "claim the occurrence atomically before running the handler; release the claim if the handler fails so a later attempt can retry it",
+        },
+        /**
+         * The one case where an occurrence runs twice, and the reason it is safe.
+         *
+         * Until the envelope carried `trigger` this could not be expressed: a retry
+         * nobody asked for and a redelivery a person ordered arrived identically, so
+         * the rule safe against the first was applied to both and pressing
+         * "redeliver" changed nothing. The unit of idempotency is therefore not the
+         * occurrence alone but the occurrence *and what asked for it*.
+         */
+        redelivery: {
+            identity: `${CALLBACK_HEADERS.occurrenceId} together with the signed attempt number, which is the redelivery's ordinal`,
+            note: "A redelivery is a deliberate, authorized instruction to do the work again. Suppressing it as a duplicate answers a person with silence, which is what a customer pressing redeliver after fixing their endpoint experiences as the attempt succeeding while nothing happens.",
+            optOut: "A receiver that genuinely requires strict once-only per occurrence chooses it explicitly and keeps answering duplicate. It is an opt-out, not the default, because a default of suppression makes the product lie to the person who pressed the button.",
+            ordering: "attempt only ever increases within an occurrence and every copy of one redelivery carries the same value, so a receiver keeps the highest redelivery it has run to completion and refuses anything at or below it. That is what recognises a copy delayed in a proxy, a queue or an abandoned connection, however late it arrives and however many redeliveries have completed since. Remembering only the most recent instruction cannot do this and will run a customer's work twice; remembering every instruction can, at the cost of a store that grows without bound. sourceAttemptId names the attempt the person chose to follow and is there to show them, not to decide whether the work runs.",
+            requirement: "run the handler again for a redelivery whose attempt is above the highest this receiver has run to completion for the occurrence, and suppress every redelivery at or below that high-water mark",
+            strictness: "A receiver that chose strict once-only suppresses every delivery for an occurrence once anything has finished, whatever caused it. Reading strictness as a rule about redeliveries alone leaves a hole: a strict receiver that processed a redelivery first would then admit a delayed automatic delivery and run a payment twice.",
+            warranty: "Each accepted redelivery is one logical run. Repeats are suppressed once the receiver has durably completed that run — not from the moment it starts one. A handler that performs its external effect and then dies before its claim is settled will be run again when the lease expires, which is the honest limit of what any at-least-once receiver can promise. A customer whose effect must happen exactly once commits the occurrence and ordinal alongside their own state, or passes them downstream as an idempotency key.",
+        },
+        replay: {
+            identity: CALLBACK_HEADERS.deliveryId,
+            requirement: "reject a previously accepted delivery identity before parsing, and answer 200 — a duplicated request is not a failure",
+        },
+    },
+    /**
+     * How a receiver's occurrence store answers one claim, in order.
+     *
+     * Published as data because a receiver author outside JavaScript had nowhere
+     * to read it: `order` covers authenticating a request, and the prose guide is
+     * TypeScript-shaped and not machine-readable. It drifted from the code three
+     * times during W3-08 — and the third time it published a rule that would have
+     * had a customer take a payment twice — so the ordered list now lives beside
+     * the rules it describes and the guide is checked against it.
+     *
+     * Rule 2 is deliberately about what has *finished* rather than what *arrived*.
+     * Splitting it — suppress an automatic delivery when the automatic run
+     * finished, apply strictness only to redeliveries — is the hole: a strict
+     * receiver that legitimately saw an ordered redelivery first would then admit
+     * a delayed automatic copy and run the work again.
+     */
+    claimRules: [
+        "another delivery holds an unexpired lease, whatever the run, so an ordered redelivery never runs alongside the attempt it follows -> in_flight",
+        "the delivery may not retake a settled occurrence and anything at all has finished for it -> settled. This covers every automatic delivery and every delivery at a receiver that chose strict once-only",
+        "the delivery is a redelivery whose ordinal is at or below the highest this receiver has run to completion -> settled",
+        "otherwise take it, recording the holder and the run -> claimed",
+    ],
+    order: [
+        "read the exact request bytes before any body parser sees them",
+        "reject a body over the receiver's byte bound without buffering it",
+        "validate the five Callback-* headers and the content type",
+        "reject a timestamp outside tolerance",
+        "select the signing key by Callback-Key-Id within the receiver's own endpoint, project, and environment",
+        "compare the HMAC in constant time over <timestamp>.<delivery-id>. plus the exact bytes",
+        "compare the canonical envelope identifiers with the occurrence header",
+        "claim the delivery identity atomically",
+        // Parsing moved ahead of the occurrence claim on 2026-08-08, and it is a
+        // correction as much as a change: the shipped verifier already parsed here,
+        // because nothing downstream can use an envelope it has not decoded. What
+        // is new is that the step now *matters* — the trigger deciding which run is
+        // being claimed lives in the body, so it must come from bytes the MAC has
+        // already authenticated rather than from a header anyone could set.
+        "only now parse the body, and read the trigger that says why this delivery exists",
+        "claim the occurrence identity atomically, for the run the signed body names — the occurrence for an automatic delivery, and the occurrence with the redelivery's attempt ordinal for one a person ordered",
+        "run the application handler",
+    ],
+    responses: CALLBACK_RECEIVER_STATUS,
+    sink: {
+        behaviors: TEST_SINK_BEHAVIOR_FACTS,
+        bounds: TEST_SINK_BOUNDS,
+        clientErrorStatuses: TEST_SINK_CLIENT_ERROR_STATUSES,
+        // Published as data rather than described in a summary, because a receiver
+        // author reading this artifact writes their integration test against it and
+        // has no way to read a TypeScript constant. Which of the 4xx above are
+        // retried is the one fact about the sink that changed at FXO-1596.
+        clientErrorStatusesRetried: TEST_SINK_REFUSAL_STATUSES,
+        // The `defer_*` behaviors made "never sends" false, and stating the
+        // narrower property is worth more than restating the old one: what keeps a
+        // sink from being an egress surface was never that it made no request, but
+        // that nothing anyone can set names a place for it to send to.
+        deferral: {
+            acknowledgement: TEST_SINK_PENDING_ACKNOWLEDGEMENT,
+            note: "A deferring behavior answers this exact body with this status, then reports with the bearer credential from the delivery's own signed envelope — to the one completion address the stage is configured with, which the envelope's own URL must match. A delivery whose envelope carries no completion material, or names a different address, cannot defer, and the sink answers it as an ordinary success instead.",
+            status: CALLBACK_DEFERRAL_STATUS,
+        },
+        egress: "A test sink has no destination field: no program, no control operation and no request header names anywhere for it to send. The one request it performs is a deferred-completion report for a delivery it has already received and authenticated, to the URL and credential carried inside that delivery's signed envelope. It cannot forward or redirect a delivery.",
+        visibility: "Test environments only. Organization, project, environment, and credential kind come from the verified principal; no request may widen them.",
+    },
+    version: TEST_SINK_PROTOCOL_VERSION,
+};