@greatwait/contracts 0.1.0-alpha.1

package/dist/compatibility.js

@@ -0,0 +1,115 @@
+import { z } from "zod";
+/**
+ * What may change, and what that costs.
+ *
+ * The contract version is dated and moves independently of any deployment. A
+ * release that ships twice a day must not imply the contract changed twice a
+ * day, and a contract change must be visible even when no code deployed.
+ */
+export const CONTRACT_VERSION = "2026-08-22";
+export const contractVersionSchema = z.literal(CONTRACT_VERSION);
+/**
+ * Three kinds of change, and only the first is free.
+ *
+ * - `additive`: existing clients keep working untouched. New optional request
+ *   field, new response field, new enum member a client may *send*, new
+ *   endpoint, new scope, new problem code, new member of a vocabulary the
+ *   artifact publishes open. A new member a client must *receive* from a closed
+ *   list is breaking — it can break exhaustive parsing.
+ * - `breaking`: some conforming client stops working. Removing or renaming a
+ *   field, making an optional request field required, narrowing a type,
+ *   removing an enum member a client may send, changing a problem code's
+ *   status or category, changing what is signed.
+ * - `deployment-only`: no wire effect at all. Internal refactor, added index,
+ *   new log field, prose in `title` or `detail`. Prose is `internal`: `title`
+ *   and `detail` are explicitly not part of the contract, so editing them is
+ *   not a change to a response field.
+ *
+ * The distinction is enforceable rather than advisory: `classifyChange` is
+ * exercised by fixtures, so "we thought it was additive" is a testable claim.
+ */
+export const CHANGE_KINDS = [
+    "additive",
+    "breaking",
+    "deployment-only",
+];
+export const changeKindSchema = z.enum(CHANGE_KINDS);
+/**
+ * Declared as runtime arrays, not bare type unions, so a test can iterate the
+ * product and prove every combination is classified.
+ *
+ * A hand-written table of cases cannot do that: a combination nobody thought
+ * of is untested, and a subject or operation added later is untested by
+ * default — in a function whose whole job is to tell a caller whether a change
+ * will break customers.
+ */
+export const CHANGE_SUBJECTS = [
+    "endpoint",
+    "enum-member",
+    "internal",
+    "problem-code",
+    "request-field",
+    "response-field",
+    "scope",
+    "signature-input",
+];
+export const CHANGE_OPERATIONS = [
+    /** The meaning, status, or category of something existing was altered. */
+    "changed",
+    "added",
+    "narrowed",
+    "removed",
+    "required",
+    "widened",
+];
+/**
+ * Classifies a proposed change. Deliberately conservative: anything not
+ * demonstrably safe is `breaking`, because the cost of wrongly calling a
+ * breaking change additive is borne by customers.
+ */
+export function classifyChange(change) {
+    if (change.subject === "internal") {
+        return "deployment-only";
+    }
+    if (change.subject === "signature-input") {
+        // Any change to what is signed invalidates every receiver's verifier.
+        return "breaking";
+    }
+    if (change.operation === "removed" || change.operation === "changed") {
+        // "changed" covers altering a problem code's status or category, which the
+        // conventions document names as breaking.
+        return "breaking";
+    }
+    if (change.operation === "narrowed") {
+        // Accepting less than before breaks senders; returning less breaks readers.
+        return "breaking";
+    }
+    if (change.operation === "required") {
+        // Making a request field required breaks clients that omit it. Marking a
+        // response field always-present is merely a promise we now keep.
+        return change.subject === "request-field" ? "breaking" : "additive";
+    }
+    if (change.operation === "added") {
+        if (change.subject === "request-field") {
+            // Safe only while optional; `required` is handled above.
+            return "additive";
+        }
+        if (change.subject === "enum-member") {
+            // A new member a client may *send* is additive; a new member a client
+            // must *handle* on the wire can break exhaustive parsing — unless the
+            // artifact never published a list for it to parse exhaustively against.
+            return change.clientSupplied === true || change.openVocabulary === true
+                ? "additive"
+                : "breaking";
+        }
+        return "additive";
+    }
+    // `widened`. Accepting more on the way in never breaks a sender. Returning
+    // more on the way out does: a client parsing `string` breaks the day it
+    // starts receiving `string | number`.
+    return change.subject === "response-field" ? "breaking" : "additive";
+}
+export function assess(change) {
+    const kind = classifyChange(change);
+    return { kind, requiresNewContractVersion: kind === "breaking" };
+}

package/dist/delivery.d.ts

@@ -0,0 +1,401 @@
+import type { Authority } from "./authority.js";
+import type { AttemptId, DeliveryId, EndpointId, OccurrenceId, ScheduleId } from "./identifiers.js";
+import type { CallbackTrigger as AttemptTrigger } from "./signatures.js";
+/**
+ * Versioned associated-data contract for encrypted schedule payloads.
+ *
+ * The value is persisted beside the envelope by the portable scheduling
+ * record contract. Changing it requires an explicit reader for the old value;
+ * silently trying another value would turn an authentication failure into a
+ * decryption oracle.
+ */
+export declare const SCHEDULE_PAYLOAD_AAD_VERSION: "greatwait.schedule-payload.v1";
+/**
+ * The encrypted customer data carried from its authoritative partition to the
+ * network boundary. This is an internal Durable Object RPC shape, not a public
+ * schema. Its application-encryption key is deliberately distinct from the key
+ * which wraps endpoint signing secrets.
+ */
+export interface EncryptedSchedulePayload {
+    readonly ciphertext: string;
+    readonly keyId: string;
+    readonly nonce: string;
+}
+/**
+ * One immutable delivery attempt, minted by the Scheduler Partition from its
+ * verified authority. No member of this tuple comes from callback request
+ * input. A logical retry mints a new attempt and delivery identity; duplicate
+ * dispatch/recovery of this same attempt keeps both identities stable.
+ */
+export interface CallbackAttemptDispatch {
+    readonly authority: Authority;
+    readonly attemptId: AttemptId;
+    readonly attemptNumber: number;
+    /**
+     * How this receiver says it is finished: by answering the POST, or by calling
+     * the completion URL afterwards.
+     *
+     * Carried for the same reason `maxDurationSeconds` is — the partition holds
+     * the schedule — and load-bearing twice over. It decides whether the delivery
+     * holds its socket open or is free to park on an acknowledgement, and
+     * together with the duration it decides whether this delivery occupies one of
+     * the partition's six in-flight slots at all.
+     */
+    readonly completion: "response" | "callback";
+    readonly deliveryId: DeliveryId;
+    /** Monotonic partition fence for duplicate/late dispatch and report RPCs. */
+    readonly dispatchEpoch: number;
+    readonly encryptedPayloadEnvelope: EncryptedSchedulePayload;
+    readonly endpointId: EndpointId;
+    readonly latencyClass: "realtime" | "bulk";
+    /**
+     * How long the executor may wait for this receiver, in seconds.
+     *
+     * **Carried on the dispatch rather than resolved by the executor**, which is
+     * the rule `trigger` follows a few fields down and for the same reason: the
+     * partition is what holds the schedule, and a value the executor looked up
+     * separately would be a second opinion about the customer's own setting. It is
+     * also what makes a recovery honest — a redispatch of an attempt admitted
+     * under a five-minute setting is still that attempt, even if the schedule has
+     * been replaced with a five-second one since.
+     */
+    readonly maxDurationSeconds: number;
+    /**
+     * Internal lost-result recovery policy. `recovery` may perform the original
+     * same-identity POST only when the executor has no ledger row;
+     * `recover_only` may read the ledger but must never perform network I/O.
+     */
+    readonly mode: "attempt" | "recovery" | "recover_only";
+    readonly occurrenceId: OccurrenceId;
+    readonly plannedForMs: number;
+    readonly routingUrl: string;
+    readonly scheduleId: ScheduleId;
+    /** The verified project/environment partition lane used for host fairness. */
+    readonly shard: string;
+    /**
+     * Why this attempt exists. Unlike `mode` and `dispatchEpoch`, this crosses
+     * the network: it is serialized into the signed callback envelope, and it is
+     * what lets a receiver run a customer-ordered redelivery again while still
+     * suppressing a retry nobody asked for.
+     */
+    readonly trigger: AttemptTrigger;
+}
+/**
+ * What a receiver says about work it acknowledged and then finished.
+ *
+ * Here rather than beside the envelope schema because the scheduler Worker's
+ * completion route reads it and that bundle deliberately carries no Zod — this
+ * module is the Zod-free subpath. `signatures.ts` builds its enum from this
+ * list, so the vocabulary exists once.
+ *
+ * `succeeded` is what an empty body means: the overwhelmingly common report is
+ * "done", and a receiver should not have to compose a document to say it.
+ * `failed` puts the occurrence back on the ordinary retry ladder — the same
+ * place a 500 puts it — so a receiver can distinguish "my job died" from "I
+ * vanished".
+ */
+export declare const CALLBACK_COMPLETION_OUTCOMES: readonly ["succeeded", "failed"];
+export type CallbackCompletionOutcome = (typeof CALLBACK_COMPLETION_OUTCOMES)[number];
+export type CallbackAttemptClassification = "succeeded" | "retryable_failure" | "terminal_failure" | "ambiguous";
+/**
+ * The one status that can mean "I have the work and I am not finished".
+ *
+ * Exactly `202`, and the narrowness is the point. Every other 2xx keeps the
+ * meaning it has had since the first delivery this product sent — success,
+ * now — so a receiver that has never heard of deferral cannot be parked by
+ * accident. A `200` carrying the marker is success, and so is a `204`, because
+ * the discriminator is not the whole rule: the status and the body have to
+ * agree, and only this pair opts in.
+ */
+export declare const CALLBACK_DEFERRAL_STATUS = 202;
+/**
+ * How much of an acknowledgement body is read before the answer is decided.
+ *
+ * One kibibyte. An acknowledgement is a fixed object of two or three short
+ * members, so the bound is roughly twenty times what a legitimate one needs
+ * and is not a limit a receiver can meet by accident. What it stops is a
+ * receiver — or something in front of one — answering `202` with a body that
+ * is expensive to read: the delivery path reads this many bytes, decides, and
+ * cancels the rest of the stream without buffering it.
+ *
+ * **Exceeding it is not pending.** A body over the bound cannot be shown to
+ * carry the discriminator, and the safe reading of "cannot be shown" is the
+ * one that settles the attempt now rather than the one that parks a customer's
+ * occurrence on a receiver whose answer we did not finish reading.
+ */
+export declare const CALLBACK_ACKNOWLEDGEMENT_MAX_BYTES = 1024;
+/**
+ * The media types an acknowledgement may be carried in.
+ *
+ * JSON, in the two spellings a receiver actually sends. A `202` whose body is
+ * HTML or plain text is an ordinary success, because whatever it says it is
+ * not this protocol.
+ */
+export declare const CALLBACK_ACKNOWLEDGEMENT_CONTENT_TYPES: readonly ["application/json", "application/problem+json"];
+/**
+ * What a receiver answers with to keep the work and report later.
+ *
+ * ```json
+ * { "greatwait": { "status": "pending", "completeBy": "2026-08-23T18:00:00Z" } }
+ * ```
+ *
+ * **Namespaced under one key on purpose.** A receiver's `202` body is its own
+ * document — a job id, a queue position, a status URL — and a bare
+ * `{"status":"pending"}` would collide with the most ordinary word in that
+ * vocabulary. Nesting it means an existing receiver has to have chosen the key
+ * `greatwait` for something else before this can misfire.
+ */
+export declare const CALLBACK_PENDING_DISCRIMINATOR: {
+    readonly key: "greatwait";
+    readonly status: "pending";
+};
+/**
+ * Whether an acknowledgement asked to defer, and until when if it named an
+ * instant.
+ *
+ * `completeByMs` is what the receiver *asked for*, before clamping. Turning it
+ * into the deadline that is stored is
+ * {@link effectiveCompletionDeadlineMs}'s job, and the two are separate
+ * because only one of them is allowed to be an opinion.
+ */
+export type CallbackAcknowledgement = {
+    readonly pending: false;
+} | {
+    readonly completeByMs?: number;
+    readonly pending: true;
+};
+/**
+ * Decide whether one receiver answer is the deferral acknowledgement.
+ *
+ * Every term is required and each one is refused on its own: the status is
+ * exactly {@link CALLBACK_DEFERRAL_STATUS}, the media type is JSON, the body
+ * fits {@link CALLBACK_ACKNOWLEDGEMENT_MAX_BYTES}, it parses, it is a JSON
+ * object rather than an array or a scalar, and it carries the discriminator.
+ * Anything that fails one of them is not pending, which for a 2xx means
+ * ordinary immediate success.
+ *
+ * **It never decides a non-2xx.** The caller classifies the response first and
+ * only asks this about a success; a `500` carrying a perfectly formed pending
+ * marker is a `500`, because a receiver that is failing does not get to park
+ * the occurrence it is failing to handle.
+ *
+ * **There is no `Array.isArray` guard, and there was one.** Mutation testing
+ * showed both — over the parsed body and over the marker — surviving deletion
+ * with every case green, and the reason is that they cannot decide anything: a
+ * JSON array has no named members, so reading the discriminator key off one is
+ * `undefined` and the very next check refuses it. A rule no input can reach
+ * reads like protection and is not, so it is gone and this paragraph is what
+ * it left behind. The array cases in the suite stay — they pin the outcome a
+ * receiver sees, which is unchanged — but they hold by construction rather
+ * than by a guard.
+ */
+export declare function readCallbackAcknowledgement(response: {
+    /** The decoded prefix that was read, at most the bound plus nothing. */
+    readonly body: string;
+    readonly contentType: string | null;
+    readonly status: number;
+    /** Whether the body had more bytes than the bound allowed reading. */
+    readonly truncated: boolean;
+}): CallbackAcknowledgement;
+/**
+ * The deadline this deferral actually gets, in epoch milliseconds.
+ *
+ * The receiver may bring it forward and may not push it out. `maximumMs` is
+ * the deadline already inside the signed envelope — the schedule's own
+ * duration allowance measured from the attempt — so a receiver asking for
+ * longer is asking to change what its customer bought, and a receiver asking
+ * for an instant that has already passed is asking for something no wait can
+ * satisfy.
+ *
+ * **All three refusals fall back to the maximum rather than to immediate
+ * success.** The acknowledgement itself is what took the work; a malformed
+ * hint about *when* does not unmake that, and settling such an attempt
+ * `succeeded` would record a result the receiver never reported.
+ */
+export declare function effectiveCompletionDeadlineMs(requestedMs: number | undefined, maximumMs: number, nowMs: number): number;
+/** Safe, bounded diagnostics. Never contains a URL, payload, or secret. */
+/**
+ * Safe delivery diagnostics shared by the executor result and the public
+ * attempt timeline.
+ *
+ * Values are deliberately short categories. A URL, response body, payload,
+ * exception message, signing key, or transport trace has no representation in
+ * this vocabulary, so the durable history cannot accidentally turn private
+ * callback material into a public diagnostic.
+ */
+export declare const CALLBACK_ATTEMPT_DIAGNOSTICS: readonly ["completion_timed_out", "delivered", "duplicate_inflight", "endpoint_unavailable", "endpoint_unsafe", "http_refused", "http_retryable", "http_terminal", "identity_conflict", "network_ambiguous", "payload_unavailable", "rate_limited"];
+export type CallbackAttemptDiagnostic = (typeof CALLBACK_ATTEMPT_DIAGNOSTICS)[number];
+/**
+ * Statuses where the receiver is refusing *this delivery, right now* rather
+ * than objecting to the message it carries.
+ *
+ * **The line is whether resending the identical bytes could ever get a
+ * different answer.** Every callback attempt re-sends the same signed envelope,
+ * so a receiver that rejects the message itself — malformed, too large, wrong
+ * media type, gone, refused for legal reasons — will reject it identically for
+ * as long as the occurrence lives, and retrying is pure cost on the population
+ * least likely to recover. A receiver that refuses *us* has a cause someone
+ * fixes: an expired or rotated credential, a WAF rule that started matching, a
+ * deploy window where the route is briefly absent.
+ *
+ * | Status | Why it is here |
+ * | ------ | -------------- |
+ * | 401    | credential expired, rotated, or not yet deployed |
+ * | 402    | receiver's own service suspended, restored on payment |
+ * | 403    | WAF or bot rule, revoked permission, IP block |
+ * | 404    | route absent during a deploy or a partial rollout |
+ * | 405    | method absent during a deploy or a partial rollout |
+ * | 407    | an egress proxy in front of the receiver wants credentials |
+ * | 421    | misdirected during a routing or certificate change |
+ * | 423    | the target resource is temporarily locked |
+ * | 424    | the receiver's own dependency failed |
+ * | 425    | the receiver asked us not to risk a replay yet — literally "retry later" |
+ *
+ * **409 is deliberately not here**, though it is a refusal in the plain
+ * reading. From a callback receiver a conflict overwhelmingly means "I already
+ * have this delivery", which the identical retry cannot resolve and which is
+ * the receiver's idempotency working rather than failing.
+ *
+ * **An unrecognised 4xx is not here either.** RFC 7231 says an unknown 4xx must
+ * be treated as a 400, so the default is terminal and this list is the whole of
+ * the exception. Adding to it is a product decision, not a lookup.
+ */
+export declare const CALLBACK_REFUSAL_STATUSES: readonly [401, 402, 403, 404, 405, 407, 421, 423, 424, 425];
+/** Whether a receiver refused this delivery in a way that may recover. */
+export declare function isCallbackRefusalStatus(status: number): boolean;
+/** Stable outcome of the one network attempt an executor invocation may run. */
+export interface CallbackAttemptResult {
+    readonly classification: CallbackAttemptClassification;
+    readonly diagnostic: CallbackAttemptDiagnostic;
+    /** Receiver status when a response was obtained. */
+    readonly status?: number;
+    /** Bounded receiver hint, in milliseconds, for a retryable 429. */
+    readonly retryAfterMs?: number;
+    /** `tenant` applies only to this verified partition lane; `global` to host. */
+    readonly rateLimitScope?: "tenant" | "global";
+    /**
+     * Bounded, non-secret evidence about the response itself.
+     *
+     * Present whenever a response was obtained at all, including a success —
+     * status, duration and classification are kept for every attempt. The
+     * customer-content half of it, {@link CallbackResponseEvidence.snippet}, is
+     * present only where the policy allows one.
+     */
+    readonly evidence?: CallbackResponseEvidence;
+}
+/**
+ * Response headers worth keeping, in the order one is chosen.
+ *
+ * **A closed list, and short on purpose.** A response header is receiver-
+ * controlled text that lands in durable history and on a support screen, so
+ * the question is not "is this one dangerous" but "does this one earn its
+ * place". Content type explains what the snippet is, `Retry-After` explains a
+ * pacing decision the customer can see, and one receiver-side identifier is
+ * what turns "your receiver refused this" into something an integrator can
+ * look up in their own logs.
+ *
+ * Everything else is absent by construction rather than by filtering: cookies,
+ * `Authorization`, `WWW-Authenticate`, `Set-Cookie` and every vendor header
+ * have no entry here, so no future edit can retain one by forgetting to add a
+ * denial.
+ */
+export declare const CALLBACK_RESPONSE_HEADER_ALLOWLIST: readonly ["content-type", "retry-after"];
+/**
+ * Receiver-side identifiers, most specific first. **At most one is kept.**
+ *
+ * The order is which name a receiver most likely means as "look this up in my
+ * logs". Keeping several would be keeping a header set rather than an
+ * identifier, which is the thing the allowlist above exists to refuse.
+ */
+export declare const CALLBACK_RESPONSE_REQUEST_ID_HEADERS: readonly ["x-request-id", "request-id", "x-correlation-id", "x-amzn-requestid", "cf-ray"];
+/** How much of any retained header value is kept, in bytes. */
+export declare const CALLBACK_RESPONSE_HEADER_MAX_BYTES = 256;
+/**
+ * How much of a failed response body may be retained, in bytes.
+ *
+ * Four kibibytes of the *start* of the body, read as a bounded prefix and with
+ * the rest of the stream cancelled rather than buffered. It is enough for a
+ * stack trace's first frames or a validation error list, which is what makes a
+ * failing receiver diagnosable without turning this product into a log store.
+ */
+export declare const CALLBACK_FAILURE_SNIPPET_MAX_BYTES = 4096;
+/**
+ * Media types whose body may be retained as a failure snippet.
+ *
+ * Text and JSON only. A binary body has nothing a person reads in its first
+ * four kibibytes, and retaining one would mean storing an arbitrary fragment
+ * of an arbitrary file because a receiver set a header.
+ */
+export declare const CALLBACK_FAILURE_SNIPPET_CONTENT_TYPES: readonly ["application/json", "application/problem+json", "application/xml", "text/"];
+/** One retained response header, already bounded and lowercased by name. */
+export interface CallbackResponseHeader {
+    readonly name: string;
+    readonly value: string;
+}
+/**
+ * What a failing receiver said, bounded and destined for encryption.
+ *
+ * `truncated` is carried rather than inferred from the length, because a body
+ * that is exactly the bound and a body that was cut at the bound are different
+ * facts and only one of them should show a customer an ellipsis.
+ */
+export interface CallbackFailureSnippet {
+    readonly contentType: string;
+    readonly text: string;
+    readonly truncated: boolean;
+}
+/**
+ * Bounded evidence about one HTTP response.
+ *
+ * Deliberately not "the response": there is no body for a success, no header
+ * outside the allowlist, and no representation at all for a transport failure
+ * that produced no response.
+ */
+export interface CallbackResponseEvidence {
+    readonly headers: readonly CallbackResponseHeader[];
+    /** Absent for a success, a pending acknowledgement, and a non-text body. */
+    readonly snippet?: CallbackFailureSnippet;
+}
+/**
+ * What one network attempt did, including the answer that is not an outcome.
+ *
+ * **`deferred` is a third thing beside success and failure**, and it is a
+ * union member rather than a flag on {@link CallbackAttemptResult} so that
+ * every caller has to say what it does about it. A boolean on the result would
+ * have let the existing carriers keep compiling while silently settling a
+ * deferred attempt `succeeded` — which is precisely the wrong answer, and the
+ * one nothing would have reported.
+ */
+export type CallbackAttemptOutcome = CallbackAttemptResult | {
+    /** The instant the receiver asked for, before clamping. */
+    readonly completeByMs?: number;
+    readonly deferred: true;
+    readonly evidence: CallbackResponseEvidence;
+    readonly status: number;
+};
+/** Whether one network attempt asked to finish later. */
+export declare function isDeferredAttempt(outcome: CallbackAttemptOutcome): outcome is Extract<CallbackAttemptOutcome, {
+    readonly deferred: true;
+}>;
+/**
+ * Host admission and delivery result. A reroute is not a delivery attempt: no
+ * request was sent and the partition may resolve the returned URL to the right
+ * host executor once, outside its transaction. Backpressure likewise consumes
+ * no receiver attempt.
+ */
+export type HostExecutorAttemptResult = {
+    readonly accepted: false;
+    readonly disposition: "backpressure";
+    readonly reason: "paused" | "max_connections" | "partition_cap" | "recovery_probe" | "shard_transition" | "tokens" | "realtime_share";
+    readonly retryAfterMs: number;
+} | {
+    readonly accepted: false;
+    readonly disposition: "reroute";
+    readonly routingUrl: string;
+} | {
+    readonly accepted: true;
+    readonly durationMs: number;
+    readonly result: CallbackAttemptResult;
+    readonly shard: number;
+    readonly shardCount: number;
+};