@greatwait/contracts 0.1.0-alpha.1

package/dist/test-sink.d.ts

@@ -0,0 +1,986 @@
+import { z } from "zod";
+import { type CallbackCompletionOutcome } from "./delivery.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.
+ */
+/**
+ * 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 declare const TEST_SINK_BEHAVIORS: readonly ["client_error", "defer_abandon", "defer_fail", "defer_succeed", "delay", "disconnect", "duplicate", "invalid_signature", "rate_limited", "server_error", "success", "timeout"];
+export declare const testSinkBehaviorSchema: z.ZodEnum<{
+    rate_limited: "rate_limited";
+    success: "success";
+    server_error: "server_error";
+    client_error: "client_error";
+    defer_abandon: "defer_abandon";
+    defer_fail: "defer_fail";
+    defer_succeed: "defer_succeed";
+    delay: "delay";
+    disconnect: "disconnect";
+    duplicate: "duplicate";
+    invalid_signature: "invalid_signature";
+    timeout: "timeout";
+}>;
+export type TestSinkBehavior = z.infer<typeof testSinkBehaviorSchema>;
+/**
+ * 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 declare 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.
+     */
+    readonly maxCompletionDelayMs: 5000;
+    /** Longest `delay` a sink will honour before answering. */
+    readonly maxDelayMs: 10000;
+    /** Longest a `timeout` or `disconnect` holds a request open. */
+    readonly maxHoldMs: 45000;
+    /** Retained delivery receipts per sink; the oldest are evicted. */
+    readonly maxRetainedDeliveries: 50;
+    /** Sinks per project/environment. */
+    readonly maxSinksPerEnvironment: 10;
+    /** Largest request body a sink will read. Larger is refused unread. */
+    readonly maxRequestBodyBytes: 65536;
+    /** Captured body bytes retained on a receipt; beyond this it is truncated. */
+    readonly maxRetainedBodyBytes: 4096;
+};
+/**
+ * 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 declare const TEST_SINK_CLIENT_ERROR_STATUSES: readonly [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 declare const TEST_SINK_REFUSAL_STATUSES: readonly [401, 403, 404];
+/** Selected 5xx a sink may answer with. Each is retryable to the sender. */
+export declare const TEST_SINK_SERVER_ERROR_STATUSES: readonly [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 declare const testSinkProgramSchema: z.ZodObject<{
+    behavior: z.ZodEnum<{
+        rate_limited: "rate_limited";
+        success: "success";
+        server_error: "server_error";
+        client_error: "client_error";
+        defer_abandon: "defer_abandon";
+        defer_fail: "defer_fail";
+        defer_succeed: "defer_succeed";
+        delay: "delay";
+        disconnect: "disconnect";
+        duplicate: "duplicate";
+        invalid_signature: "invalid_signature";
+        timeout: "timeout";
+    }>;
+    completionDelayMs: z.ZodOptional<z.ZodNumber>;
+    delayMs: z.ZodOptional<z.ZodNumber>;
+    forDeliveries: z.ZodOptional<z.ZodNumber>;
+    retryAfterSeconds: z.ZodOptional<z.ZodNumber>;
+    status: z.ZodOptional<z.ZodNumber>;
+    then: z.ZodOptional<z.ZodEnum<{
+        rate_limited: "rate_limited";
+        success: "success";
+        server_error: "server_error";
+        client_error: "client_error";
+        defer_abandon: "defer_abandon";
+        defer_fail: "defer_fail";
+        defer_succeed: "defer_succeed";
+        delay: "delay";
+        disconnect: "disconnect";
+        duplicate: "duplicate";
+        invalid_signature: "invalid_signature";
+        timeout: "timeout";
+    }>>;
+}, z.core.$strip>;
+export type TestSinkProgram = z.infer<typeof testSinkProgramSchema>;
+/**
+ * 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 declare const TEST_SINK_BEHAVIOR_FACTS: {
+    readonly client_error: {
+        readonly defaultStatus: 422;
+        readonly deferredReport: undefined;
+        readonly receiverActed: false;
+        readonly senderOutcome: "terminal";
+        readonly 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.";
+    };
+    readonly defer_abandon: {
+        readonly defaultStatus: 202;
+        readonly deferredReport: "never";
+        readonly receiverActed: true;
+        readonly senderOutcome: "ambiguous";
+        readonly 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.";
+    };
+    readonly defer_fail: {
+        readonly defaultStatus: 202;
+        readonly deferredReport: "failed";
+        readonly receiverActed: true;
+        readonly senderOutcome: "retryable";
+        readonly 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.";
+    };
+    readonly defer_succeed: {
+        readonly defaultStatus: 202;
+        readonly deferredReport: "succeeded";
+        readonly receiverActed: true;
+        readonly senderOutcome: "success";
+        readonly 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.";
+    };
+    readonly delay: {
+        readonly defaultStatus: 200;
+        readonly deferredReport: undefined;
+        readonly receiverActed: true;
+        readonly senderOutcome: "success";
+        readonly summary: "Waits a bounded interval, then accepts. Exercises a slow receiver that still succeeds.";
+    };
+    readonly disconnect: {
+        readonly defaultStatus: undefined;
+        readonly deferredReport: undefined;
+        readonly receiverActed: false;
+        readonly senderOutcome: "ambiguous";
+        readonly 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.";
+    };
+    readonly duplicate: {
+        readonly defaultStatus: 200;
+        readonly deferredReport: undefined;
+        readonly receiverActed: false;
+        readonly senderOutcome: "success";
+        readonly summary: "Accepts and reports the occurrence as already handled, without processing it again. What occurrence idempotency looks like from the sender's side.";
+    };
+    readonly invalid_signature: {
+        readonly defaultStatus: 401;
+        readonly deferredReport: undefined;
+        readonly receiverActed: false;
+        readonly senderOutcome: "retryable";
+        readonly 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.";
+    };
+    readonly rate_limited: {
+        readonly defaultStatus: 429;
+        readonly deferredReport: undefined;
+        readonly receiverActed: false;
+        readonly senderOutcome: "retryable";
+        readonly summary: "Answers 429 with a bounded Retry-After. The sender honours the hint and does not spend its give-up budget.";
+    };
+    readonly server_error: {
+        readonly defaultStatus: 503;
+        readonly deferredReport: undefined;
+        readonly receiverActed: false;
+        readonly senderOutcome: "retryable";
+        readonly summary: "Answers a selected 5xx. The sender retries with backoff.";
+    };
+    readonly success: {
+        readonly defaultStatus: 200;
+        readonly deferredReport: undefined;
+        readonly receiverActed: true;
+        readonly senderOutcome: "success";
+        readonly summary: "Verifies, records, and accepts.";
+    };
+    readonly timeout: {
+        readonly defaultStatus: undefined;
+        readonly deferredReport: undefined;
+        readonly receiverActed: true;
+        readonly senderOutcome: "ambiguous";
+        readonly summary: "Verifies and records the delivery, then never answers. The receiver acted and the sender cannot know it.";
+    };
+};
+/**
+ * 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 declare const TEST_SINK_PENDING_ACKNOWLEDGEMENT: string;
+/**
+ * What the sink should do with one delivery.
+ *
+ * `hold` means no response is ever produced.
+ *
+ * `claims` says whether the receiver's idempotency ledgers are the durable
+ * ones. It is false only for `disconnect`, which models a connection that died
+ * before the receiver processed anything: the delivery is still authenticated —
+ * a sink that held an *unsigned* request open would be a way for anyone holding
+ * a sink url to pin the Worker's request budget, not a simulation of a customer
+ * receiver — but no occurrence is claimed and no work is recorded as done, so
+ * `receiverActed: false` stays true.
+ */
+export interface TestSinkAction {
+    /**
+     * The exact acknowledgement bytes a deferral answers with, present exactly
+     * when `defers` is true.
+     *
+     * Carried here rather than composed by the runtime because these bytes are
+     * the protocol: a sink that assembled its own marker could assemble one the
+     * sender does not recognise, and the failure would be a delivery quietly
+     * settled `succeeded` while the receiver was still working — the one thing
+     * the whole deferral protocol exists to prevent.
+     */
+    readonly acknowledgement?: string;
+    readonly behavior: TestSinkBehavior;
+    /** Whether the occurrence and delivery ledgers this delivery touches persist. */
+    readonly claims: boolean;
+    /**
+     * Milliseconds between the acknowledgement and the report. Zero when there
+     * is no report to send, the way `delayMs` is zero when there is no delay.
+     */
+    readonly completionDelayMs: number;
+    /**
+     * What to report, with the credential in the delivery's signed envelope.
+     *
+     * Absent means "report nothing", which is `defer_abandon` and every behavior
+     * that does not defer. The two are told apart by `defers`, never by this.
+     */
+    readonly completionOutcome?: CallbackCompletionOutcome;
+    /** Whether to acknowledge the work and answer later instead of now. */
+    readonly defers: boolean;
+    readonly delayMs: number;
+    readonly hold: boolean;
+    readonly retryAfterSeconds?: number;
+    readonly status?: number;
+}
+/**
+ * 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 declare function resolveTestSinkAction(program: TestSinkProgram, deliveryIndex: number): TestSinkAction;
+/**
+ * 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 declare const CALLBACK_RECEIVER_DISPOSITIONS: readonly ["body_too_large", "duplicate", "handler_failed", "in_flight", "invalid_envelope", "invalid_headers", "invalid_signature", "processed", "replay", "stale_timestamp"];
+export declare const callbackReceiverDispositionSchema: z.ZodEnum<{
+    duplicate: "duplicate";
+    invalid_signature: "invalid_signature";
+    body_too_large: "body_too_large";
+    handler_failed: "handler_failed";
+    in_flight: "in_flight";
+    invalid_envelope: "invalid_envelope";
+    invalid_headers: "invalid_headers";
+    processed: "processed";
+    replay: "replay";
+    stale_timestamp: "stale_timestamp";
+}>;
+export type CallbackReceiverDisposition = z.infer<typeof callbackReceiverDispositionSchema>;
+/**
+ * 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 declare const TEST_SINK_DISPOSITIONS: readonly ["body_too_large", "duplicate", "handler_failed", "in_flight", "invalid_envelope", "invalid_headers", "invalid_signature", "processed", "replay", "stale_timestamp", "connection_dropped"];
+export declare const testSinkDispositionSchema: z.ZodEnum<{
+    duplicate: "duplicate";
+    invalid_signature: "invalid_signature";
+    body_too_large: "body_too_large";
+    handler_failed: "handler_failed";
+    in_flight: "in_flight";
+    invalid_envelope: "invalid_envelope";
+    invalid_headers: "invalid_headers";
+    processed: "processed";
+    replay: "replay";
+    stale_timestamp: "stale_timestamp";
+    connection_dropped: "connection_dropped";
+}>;
+export type TestSinkDisposition = z.infer<typeof testSinkDispositionSchema>;
+/**
+ * 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 declare const CALLBACK_RECEIVER_STATUS: {
+    readonly body_too_large: 413;
+    readonly duplicate: 200;
+    readonly handler_failed: 500;
+    readonly in_flight: 503;
+    readonly invalid_envelope: 400;
+    readonly invalid_headers: 401;
+    readonly invalid_signature: 401;
+    readonly processed: 200;
+    readonly replay: 200;
+    readonly 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 declare const callbackReceiverAcknowledgementSchema: z.ZodObject<{
+    disposition: z.ZodEnum<{
+        duplicate: "duplicate";
+        invalid_signature: "invalid_signature";
+        body_too_large: "body_too_large";
+        handler_failed: "handler_failed";
+        in_flight: "in_flight";
+        invalid_envelope: "invalid_envelope";
+        invalid_headers: "invalid_headers";
+        processed: "processed";
+        replay: "replay";
+        stale_timestamp: "stale_timestamp";
+    }>;
+    occurrenceId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type CallbackReceiverAcknowledgement = z.infer<typeof callbackReceiverAcknowledgementSchema>;
+export declare const testSinkSchema: z.ZodObject<{
+    createdAt: z.ZodString;
+    deliveryCount: z.ZodNumber;
+    endpoint: z.ZodString;
+    environmentKind: z.ZodLiteral<"test">;
+    id: z.ZodString;
+    program: z.ZodObject<{
+        behavior: z.ZodEnum<{
+            rate_limited: "rate_limited";
+            success: "success";
+            server_error: "server_error";
+            client_error: "client_error";
+            defer_abandon: "defer_abandon";
+            defer_fail: "defer_fail";
+            defer_succeed: "defer_succeed";
+            delay: "delay";
+            disconnect: "disconnect";
+            duplicate: "duplicate";
+            invalid_signature: "invalid_signature";
+            timeout: "timeout";
+        }>;
+        completionDelayMs: z.ZodOptional<z.ZodNumber>;
+        delayMs: z.ZodOptional<z.ZodNumber>;
+        forDeliveries: z.ZodOptional<z.ZodNumber>;
+        retryAfterSeconds: z.ZodOptional<z.ZodNumber>;
+        status: z.ZodOptional<z.ZodNumber>;
+        then: z.ZodOptional<z.ZodEnum<{
+            rate_limited: "rate_limited";
+            success: "success";
+            server_error: "server_error";
+            client_error: "client_error";
+            defer_abandon: "defer_abandon";
+            defer_fail: "defer_fail";
+            defer_succeed: "defer_succeed";
+            delay: "delay";
+            disconnect: "disconnect";
+            duplicate: "duplicate";
+            invalid_signature: "invalid_signature";
+            timeout: "timeout";
+        }>>;
+    }, z.core.$strip>;
+    project: z.ZodString;
+    updatedAt: z.ZodString;
+    url: z.ZodURL;
+}, z.core.$strip>;
+export type TestSink = z.infer<typeof testSinkSchema>;
+export declare const testSinkPageSchema: z.ZodObject<{
+    data: z.ZodArray<z.ZodObject<{
+        createdAt: z.ZodString;
+        deliveryCount: z.ZodNumber;
+        endpoint: z.ZodString;
+        environmentKind: z.ZodLiteral<"test">;
+        id: z.ZodString;
+        program: z.ZodObject<{
+            behavior: z.ZodEnum<{
+                rate_limited: "rate_limited";
+                success: "success";
+                server_error: "server_error";
+                client_error: "client_error";
+                defer_abandon: "defer_abandon";
+                defer_fail: "defer_fail";
+                defer_succeed: "defer_succeed";
+                delay: "delay";
+                disconnect: "disconnect";
+                duplicate: "duplicate";
+                invalid_signature: "invalid_signature";
+                timeout: "timeout";
+            }>;
+            completionDelayMs: z.ZodOptional<z.ZodNumber>;
+            delayMs: z.ZodOptional<z.ZodNumber>;
+            forDeliveries: z.ZodOptional<z.ZodNumber>;
+            retryAfterSeconds: z.ZodOptional<z.ZodNumber>;
+            status: z.ZodOptional<z.ZodNumber>;
+            then: z.ZodOptional<z.ZodEnum<{
+                rate_limited: "rate_limited";
+                success: "success";
+                server_error: "server_error";
+                client_error: "client_error";
+                defer_abandon: "defer_abandon";
+                defer_fail: "defer_fail";
+                defer_succeed: "defer_succeed";
+                delay: "delay";
+                disconnect: "disconnect";
+                duplicate: "duplicate";
+                invalid_signature: "invalid_signature";
+                timeout: "timeout";
+            }>>;
+        }, z.core.$strip>;
+        project: z.ZodString;
+        updatedAt: z.ZodString;
+        url: z.ZodURL;
+    }, z.core.$strip>>;
+    freshness: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"authoritative">;
+    }, z.core.$strip>, z.ZodObject<{
+        asOf: z.ZodString;
+        kind: z.ZodLiteral<"projected">;
+        lagSeconds: z.ZodNumber;
+    }, z.core.$strip>], "kind">;
+    nextCursor: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type TestSinkPage = z.infer<typeof testSinkPageSchema>;
+export declare const testSinkCreateRequestSchema: z.ZodObject<{
+    endpoint: z.ZodString;
+    program: z.ZodOptional<z.ZodObject<{
+        behavior: z.ZodEnum<{
+            rate_limited: "rate_limited";
+            success: "success";
+            server_error: "server_error";
+            client_error: "client_error";
+            defer_abandon: "defer_abandon";
+            defer_fail: "defer_fail";
+            defer_succeed: "defer_succeed";
+            delay: "delay";
+            disconnect: "disconnect";
+            duplicate: "duplicate";
+            invalid_signature: "invalid_signature";
+            timeout: "timeout";
+        }>;
+        completionDelayMs: z.ZodOptional<z.ZodNumber>;
+        delayMs: z.ZodOptional<z.ZodNumber>;
+        forDeliveries: z.ZodOptional<z.ZodNumber>;
+        retryAfterSeconds: z.ZodOptional<z.ZodNumber>;
+        status: z.ZodOptional<z.ZodNumber>;
+        then: z.ZodOptional<z.ZodEnum<{
+            rate_limited: "rate_limited";
+            success: "success";
+            server_error: "server_error";
+            client_error: "client_error";
+            defer_abandon: "defer_abandon";
+            defer_fail: "defer_fail";
+            defer_succeed: "defer_succeed";
+            delay: "delay";
+            disconnect: "disconnect";
+            duplicate: "duplicate";
+            invalid_signature: "invalid_signature";
+            timeout: "timeout";
+        }>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type TestSinkCreateRequest = z.infer<typeof testSinkCreateRequestSchema>;
+/**
+ * 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 declare const testSinkDeliverySchema: z.ZodObject<{
+    behavior: z.ZodEnum<{
+        rate_limited: "rate_limited";
+        success: "success";
+        server_error: "server_error";
+        client_error: "client_error";
+        defer_abandon: "defer_abandon";
+        defer_fail: "defer_fail";
+        defer_succeed: "defer_succeed";
+        delay: "delay";
+        disconnect: "disconnect";
+        duplicate: "duplicate";
+        invalid_signature: "invalid_signature";
+        timeout: "timeout";
+    }>;
+    disposition: z.ZodEnum<{
+        duplicate: "duplicate";
+        invalid_signature: "invalid_signature";
+        body_too_large: "body_too_large";
+        handler_failed: "handler_failed";
+        in_flight: "in_flight";
+        invalid_envelope: "invalid_envelope";
+        invalid_headers: "invalid_headers";
+        processed: "processed";
+        replay: "replay";
+        stale_timestamp: "stale_timestamp";
+        connection_dropped: "connection_dropped";
+    }>;
+    delivery: z.ZodString;
+    id: z.ZodString;
+    keyId: z.ZodOptional<z.ZodString>;
+    occurrenceId: z.ZodOptional<z.ZodString>;
+    receivedAt: z.ZodString;
+    respondedWith: z.ZodOptional<z.ZodNumber>;
+    scheduleId: z.ZodOptional<z.ZodString>;
+    sink: z.ZodString;
+}, z.core.$strip>;
+export type TestSinkDelivery = z.infer<typeof testSinkDeliverySchema>;
+export declare const testSinkDeliveryPageSchema: z.ZodObject<{
+    data: z.ZodArray<z.ZodObject<{
+        behavior: z.ZodEnum<{
+            rate_limited: "rate_limited";
+            success: "success";
+            server_error: "server_error";
+            client_error: "client_error";
+            defer_abandon: "defer_abandon";
+            defer_fail: "defer_fail";
+            defer_succeed: "defer_succeed";
+            delay: "delay";
+            disconnect: "disconnect";
+            duplicate: "duplicate";
+            invalid_signature: "invalid_signature";
+            timeout: "timeout";
+        }>;
+        disposition: z.ZodEnum<{
+            duplicate: "duplicate";
+            invalid_signature: "invalid_signature";
+            body_too_large: "body_too_large";
+            handler_failed: "handler_failed";
+            in_flight: "in_flight";
+            invalid_envelope: "invalid_envelope";
+            invalid_headers: "invalid_headers";
+            processed: "processed";
+            replay: "replay";
+            stale_timestamp: "stale_timestamp";
+            connection_dropped: "connection_dropped";
+        }>;
+        delivery: z.ZodString;
+        id: z.ZodString;
+        keyId: z.ZodOptional<z.ZodString>;
+        occurrenceId: z.ZodOptional<z.ZodString>;
+        receivedAt: z.ZodString;
+        respondedWith: z.ZodOptional<z.ZodNumber>;
+        scheduleId: z.ZodOptional<z.ZodString>;
+        sink: z.ZodString;
+    }, z.core.$strip>>;
+    freshness: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"authoritative">;
+    }, z.core.$strip>, z.ZodObject<{
+        asOf: z.ZodString;
+        kind: z.ZodLiteral<"projected">;
+        lagSeconds: z.ZodNumber;
+    }, z.core.$strip>], "kind">;
+    nextCursor: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type TestSinkDeliveryPage = z.infer<typeof testSinkDeliveryPageSchema>;
+/**
+ * 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 declare const testSinkDeliveryBodySchema: z.ZodObject<{
+    behavior: z.ZodEnum<{
+        rate_limited: "rate_limited";
+        success: "success";
+        server_error: "server_error";
+        client_error: "client_error";
+        defer_abandon: "defer_abandon";
+        defer_fail: "defer_fail";
+        defer_succeed: "defer_succeed";
+        delay: "delay";
+        disconnect: "disconnect";
+        duplicate: "duplicate";
+        invalid_signature: "invalid_signature";
+        timeout: "timeout";
+    }>;
+    disposition: z.ZodEnum<{
+        duplicate: "duplicate";
+        invalid_signature: "invalid_signature";
+        body_too_large: "body_too_large";
+        handler_failed: "handler_failed";
+        in_flight: "in_flight";
+        invalid_envelope: "invalid_envelope";
+        invalid_headers: "invalid_headers";
+        processed: "processed";
+        replay: "replay";
+        stale_timestamp: "stale_timestamp";
+        connection_dropped: "connection_dropped";
+    }>;
+    delivery: z.ZodString;
+    id: z.ZodString;
+    keyId: z.ZodOptional<z.ZodString>;
+    occurrenceId: z.ZodOptional<z.ZodString>;
+    receivedAt: z.ZodString;
+    respondedWith: z.ZodOptional<z.ZodNumber>;
+    scheduleId: z.ZodOptional<z.ZodString>;
+    sink: z.ZodString;
+    body: z.ZodString;
+    bodyTruncated: z.ZodBoolean;
+    receivedBytes: z.ZodNumber;
+    signature: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type TestSinkDeliveryBody = z.infer<typeof testSinkDeliveryBodySchema>;
+/**
+ * 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 declare 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 declare const CALLBACK_RECEIVER_PROTOCOL: {
+    readonly 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.
+         */
+        readonly occurrence: {
+            readonly identity: "Callback-Occurrence-Id";
+            readonly 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.";
+            readonly 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*.
+         */
+        readonly redelivery: {
+            readonly identity: "Callback-Occurrence-Id together with the signed attempt number, which is the redelivery's ordinal";
+            readonly 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.";
+            readonly 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.";
+            readonly 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.";
+            readonly 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";
+            readonly 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.";
+            readonly 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.";
+        };
+        readonly replay: {
+            readonly identity: "Callback-Delivery-Id";
+            readonly 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.
+     */
+    readonly claimRules: readonly ["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"];
+    readonly order: readonly ["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", "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"];
+    readonly responses: {
+        readonly body_too_large: 413;
+        readonly duplicate: 200;
+        readonly handler_failed: 500;
+        readonly in_flight: 503;
+        readonly invalid_envelope: 400;
+        readonly invalid_headers: 401;
+        readonly invalid_signature: 401;
+        readonly processed: 200;
+        readonly replay: 200;
+        readonly stale_timestamp: 408;
+    };
+    readonly sink: {
+        readonly behaviors: {
+            readonly client_error: {
+                readonly defaultStatus: 422;
+                readonly deferredReport: undefined;
+                readonly receiverActed: false;
+                readonly senderOutcome: "terminal";
+                readonly 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.";
+            };
+            readonly defer_abandon: {
+                readonly defaultStatus: 202;
+                readonly deferredReport: "never";
+                readonly receiverActed: true;
+                readonly senderOutcome: "ambiguous";
+                readonly 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.";
+            };
+            readonly defer_fail: {
+                readonly defaultStatus: 202;
+                readonly deferredReport: "failed";
+                readonly receiverActed: true;
+                readonly senderOutcome: "retryable";
+                readonly 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.";
+            };
+            readonly defer_succeed: {
+                readonly defaultStatus: 202;
+                readonly deferredReport: "succeeded";
+                readonly receiverActed: true;
+                readonly senderOutcome: "success";
+                readonly 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.";
+            };
+            readonly delay: {
+                readonly defaultStatus: 200;
+                readonly deferredReport: undefined;
+                readonly receiverActed: true;
+                readonly senderOutcome: "success";
+                readonly summary: "Waits a bounded interval, then accepts. Exercises a slow receiver that still succeeds.";
+            };
+            readonly disconnect: {
+                readonly defaultStatus: undefined;
+                readonly deferredReport: undefined;
+                readonly receiverActed: false;
+                readonly senderOutcome: "ambiguous";
+                readonly 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.";
+            };
+            readonly duplicate: {
+                readonly defaultStatus: 200;
+                readonly deferredReport: undefined;
+                readonly receiverActed: false;
+                readonly senderOutcome: "success";
+                readonly summary: "Accepts and reports the occurrence as already handled, without processing it again. What occurrence idempotency looks like from the sender's side.";
+            };
+            readonly invalid_signature: {
+                readonly defaultStatus: 401;
+                readonly deferredReport: undefined;
+                readonly receiverActed: false;
+                readonly senderOutcome: "retryable";
+                readonly 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.";
+            };
+            readonly rate_limited: {
+                readonly defaultStatus: 429;
+                readonly deferredReport: undefined;
+                readonly receiverActed: false;
+                readonly senderOutcome: "retryable";
+                readonly summary: "Answers 429 with a bounded Retry-After. The sender honours the hint and does not spend its give-up budget.";
+            };
+            readonly server_error: {
+                readonly defaultStatus: 503;
+                readonly deferredReport: undefined;
+                readonly receiverActed: false;
+                readonly senderOutcome: "retryable";
+                readonly summary: "Answers a selected 5xx. The sender retries with backoff.";
+            };
+            readonly success: {
+                readonly defaultStatus: 200;
+                readonly deferredReport: undefined;
+                readonly receiverActed: true;
+                readonly senderOutcome: "success";
+                readonly summary: "Verifies, records, and accepts.";
+            };
+            readonly timeout: {
+                readonly defaultStatus: undefined;
+                readonly deferredReport: undefined;
+                readonly receiverActed: true;
+                readonly senderOutcome: "ambiguous";
+                readonly summary: "Verifies and records the delivery, then never answers. The receiver acted and the sender cannot know it.";
+            };
+        };
+        readonly 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.
+             */
+            readonly maxCompletionDelayMs: 5000;
+            /** Longest `delay` a sink will honour before answering. */
+            readonly maxDelayMs: 10000;
+            /** Longest a `timeout` or `disconnect` holds a request open. */
+            readonly maxHoldMs: 45000;
+            /** Retained delivery receipts per sink; the oldest are evicted. */
+            readonly maxRetainedDeliveries: 50;
+            /** Sinks per project/environment. */
+            readonly maxSinksPerEnvironment: 10;
+            /** Largest request body a sink will read. Larger is refused unread. */
+            readonly maxRequestBodyBytes: 65536;
+            /** Captured body bytes retained on a receipt; beyond this it is truncated. */
+            readonly maxRetainedBodyBytes: 4096;
+        };
+        readonly clientErrorStatuses: readonly [400, 401, 403, 404, 409, 410, 422];
+        readonly clientErrorStatusesRetried: readonly [401, 403, 404];
+        readonly deferral: {
+            readonly acknowledgement: string;
+            readonly 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.";
+            readonly status: 202;
+        };
+        readonly 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.";
+        readonly visibility: "Test environments only. Organization, project, environment, and credential kind come from the verified principal; no request may widen them.";
+    };
+    readonly version: "2026-08-23";
+};