@greatwait/contracts 0.1.0-alpha.1

package/dist/partition.js

@@ -0,0 +1,206 @@
+/**
+ * The seam between the API Worker and a Scheduler Partition Durable Object.
+ *
+ * **This is not a public wire shape.** Nothing here is served to a customer,
+ * appears in OpenAPI, or is reachable from the internet — a Durable Object has
+ * no route, and only a Worker holding the namespace binding can address one.
+ * It lives in the contracts package for the single reason that two workspaces
+ * need to agree on it and this is the only package both `apps/api` and
+ * `apps/scheduler` may depend on. The alternative was each side writing the
+ * shape out separately, which is how `apps/scheduler/src/contract-runtime.ts`
+ * became a filed debt.
+ *
+ * It carries **no Zod and no runtime import of the contract barrel**. The
+ * addressing and routing functions below are a string join and a hash, and the
+ * rest is types, which are erased. That matters: `apps/scheduler` is the Worker
+ * every Durable Object cold start parses, and W2-08 measured the contract
+ * barrel's runtime exports at 3.4x its bundle (see
+ * `apps/scheduler/src/contract-runtime.ts`).
+ *
+ * **`@greatwait/contracts/partition` is a subpath export for that reason**,
+ * added by W2-05 when the scheduler needed the route function at runtime rather
+ * than only its types. Importing it through the barrel would have reached Zod
+ * and undone the whole of `contract-runtime.ts`. This is a narrow instance of
+ * what [FXO-1404](https://linear.app/flowxo/issue/FXO-1404) asks for in
+ * general — a Zod-free entry point — and it does not close that issue: the
+ * identifier, timestamp and problem helpers `contract-runtime.ts` copies still
+ * live in modules that do reach Zod.
+ */
+/**
+ * The shard every partition had until W2-05, and the only one an unsharded
+ * deployment ever uses.
+ *
+ * Named rather than written as `"0"` at two call sites, because the API Worker
+ * and the partition must derive the same Durable Object name and a literal
+ * repeated across a workspace boundary is a literal that will eventually
+ * disagree with itself. `partitionShardFor` returns exactly this when the shard
+ * count is one, so every Durable Object name a single-shard deployment produces
+ * is byte-identical to the ones it produced before sharding existed.
+ */
+export const SINGLE_SHARD = "0";
+/**
+ * Projection intents handed over in one call.
+ *
+ * **Declared here because both sides of the seam enforce it, and a bound
+ * enforced twice from two workspaces is a bound that will eventually disagree
+ * with itself.** The API Worker asks for this many; the partition clamps what it
+ * hands over to it and *refuses* a settle carrying more. If the asking number
+ * ever exceeded the refusing one, every settle would be refused, no intent would
+ * ever be retired, the outbox would grow to `PARTITION_LIMITS.outboxRows` and
+ * creates would then start failing for bookkeeping — a customer-visible outage
+ * produced by two constants drifting apart. The test-gap audit named exactly
+ * that, and the fix is one declaration rather than a test comparing two.
+ *
+ * Thirty-two is one D1 batch's worth of work and a few kilobytes of response.
+ * The caller comes back for the rest, and `RetainedProjections.pending` is how
+ * it knows to.
+ */
+export const PROJECTION_DRAIN_LIMIT = 32;
+/**
+ * The most shards one project/environment may be spread across.
+ *
+ * Eight, and the number is borrowed rather than invented:
+ * `apps/scheduler/src/routing.ts` clamps `HOST_EXECUTOR_SHARDS` at eight, and a
+ * repository carrying two different bounds on two knobs of the same shape is a
+ * repository where somebody eventually applies the wrong one. The costs differ
+ * but they point the same way — an executor shard divides a host budget, and a
+ * partition shard divides a project's schedules across Durable Objects.
+ *
+ * A listing had to fan out across all of them until W2-06 served listings from
+ * D1, which was the sharpest reason for a bound and is now gone. What is left is
+ * still a real fan-out: a listing whose projection is stale re-confirms every
+ * partition it covers, and a repair after an outage hands over from each in
+ * turn. Eight is where that stops being a request.
+ *
+ * A value above this is clamped rather than refused, which is upstream's
+ * judgement in `executorShardCount` and holds for the same reason: an operator
+ * asking for sixteen still wants sharding, just bounded.
+ */
+export const MAX_PARTITION_SHARDS = 8;
+/**
+ * FNV-1a, 32-bit, with the standard constants.
+ *
+ * A second copy of `apps/scheduler/src/routing.ts`'s `fnv1a32`, and the
+ * duplication is deliberate rather than overlooked. That file is copied
+ * upstream source which W3-03 retenants, and this package may not depend on an
+ * application workspace in either direction. `partition.test.ts` holds the two
+ * equal over a vector set, which is the same arrangement
+ * `partition-contract-parity.test.ts` uses for the state vocabularies: the
+ * duplication is safe because a divergence fails a test rather than shipping.
+ */
+function fnv1a32(input) {
+    let hash = 0x811c9dc5;
+    for (let index = 0; index < input.length; index++) {
+        hash ^= input.charCodeAt(index);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return hash >>> 0;
+}
+/**
+ * How many shards a deployment spreads one project/environment across.
+ *
+ * Reads the raw environment string rather than an `Env`, so both Workers parse
+ * it the same way without either of them naming the other's bindings. Missing,
+ * unparseable, non-integer and below-one all resolve to one — the unsharded
+ * default — because a partition count is the thing a *routing* decision is made
+ * from, and a routing decision made from a garbage value is worse than one made
+ * from the default.
+ *
+ * **Changing it moves where existing identifiers resolve, so it is retunable
+ * only under a precondition, and that is the most important thing to know about
+ * it.** A schedule's shard is derived from its identifier. Before W2-06 that was
+ * the only answer, so raising the count stranded every schedule already stored.
+ * Now the shard a schedule was actually stored in is *recorded* in the D1
+ * directory, and `resolveSchedule` falls back to it whenever the derived
+ * partition has nothing — so a schedule created under an older count keeps
+ * working, because its route was written down rather than recomputed.
+ *
+ * The precondition is that every schedule **has** such a route, which is exactly
+ * what `greatwait_projection_checkpoint` reporting `pending: 0` for every
+ * partition means. A schedule whose projection never landed has no recorded
+ * route and no derivable one, and it is unreachable until its partition is
+ * drained. `docs/operations/cloudflare-environments.md` carries the procedure
+ * and the two costs it does not remove — a keyed create's idempotency receipt is
+ * stranded for its 24-hour life, and detail reads of pre-change schedules cost
+ * an extra round trip for as long as they exist.
+ *
+ * It is still not `HOST_EXECUTOR_SHARDS`, which rolls `1 → 4 → 8` under load
+ * because an executor holds no durable state. This one holds all of it, and
+ * moving it is a planned operation rather than a dial.
+ */
+export function partitionShardCount(raw) {
+    if (raw === undefined) {
+        return 1;
+    }
+    const count = Number(raw);
+    if (!Number.isInteger(count) || count < 1) {
+        return 1;
+    }
+    return Math.min(count, MAX_PARTITION_SHARDS);
+}
+/**
+ * The shard a schedule identifier belongs to.
+ *
+ * Architecture section 4's route function: the stable opaque schedule ID hashed
+ * into a project/environment shard, with the count an operational configuration
+ * rather than a public contract. Nothing a *client* sends reaches this — the
+ * identifier is minted by the API Worker — so a caller can neither choose their
+ * shard nor learn how many there are.
+ */
+export function partitionShardFor(scheduleId, shardCount) {
+    return shardOf(`sch:${scheduleId}`, shardCount);
+}
+/**
+ * The shard a create carrying an idempotency key routes to.
+ *
+ * **A create is the one operation that cannot route by schedule identifier,
+ * because it is the operation that mints one.** Every other operation is handed
+ * an identifier and derives the shard from it; a create has to pick a partition
+ * first and name the schedule afterwards. Picking randomly would break
+ * idempotency the moment there is more than one shard: the retry that carries
+ * the same key would mint a different identifier, land in a different Durable
+ * Object, find no receipt there, and create a second schedule — the exact
+ * failure the receipt exists to prevent.
+ *
+ * So a keyed create routes on the key, and the identifier is then minted *into*
+ * that shard (`mintScheduleIdIn`), which keeps `partitionShardFor` the single
+ * answer for every later read. A create with no key routes on the identifier it
+ * mints, because there is nothing to be idempotent about.
+ *
+ * The `idk:` prefix separates the two domains, so an identifier and a key that
+ * happen to be the same string cannot be conflated into the same hash input.
+ * The key is customer input and it selects a shard **inside the caller's own
+ * authority tuple**: it cannot reach another organization, project or
+ * environment, because those are the other components of the Durable Object
+ * name and none of them comes from the request.
+ */
+export function partitionShardForIdempotencyKey(key, shardCount) {
+    return shardOf(`idk:${key}`, shardCount);
+}
+function shardOf(input, shardCount) {
+    return shardCount <= 1 ? SINGLE_SHARD : String(fnv1a32(input) % shardCount);
+}
+/**
+ * The Durable Object instance name for one authority tuple and shard.
+ *
+ * Deriving the name from the authority is what makes a cross-tenant read reach
+ * a *different object*, so tenancy is enforced by addressing before any code
+ * runs. The partition's own bound-identity check is then defence against a
+ * defect in this function rather than the only thing standing between two
+ * tenants.
+ *
+ * `:` is safe as a separator because every component is either a prefixed
+ * identifier drawn from Crockford base32 or the fixed literal `test`/`live`,
+ * and none of those can contain it. Callers must validate the tuple before
+ * calling: this function makes a name, it does not police one.
+ */
+export function partitionInstanceName(authority, shard) {
+    return [
+        authority.organization,
+        authority.project,
+        authority.environment,
+        authority.environmentKind,
+        "s",
+        shard,
+    ].join(":");
+}

package/dist/policy.d.ts

@@ -0,0 +1,93 @@
+import { type PrincipalKind, type Scope } from "./authority.js";
+import { type MembershipRole } from "./identity.js";
+import { type OperationDefinition } from "./operations.js";
+export declare const ROLE_SCOPE_CEILINGS: Readonly<Record<MembershipRole, readonly Scope[]>>;
+/** Everything a role may hold, expanded so a write implies its read. */
+export declare function ceilingForRole(role: MembershipRole): Set<Scope>;
+/** Whether a role may ever hold a scope. */
+export declare function roleAllows(role: MembershipRole, scope: Scope): boolean;
+/**
+ * Narrow requested scopes to what a role may actually hold.
+ *
+ * The rule the project specification states as "OAuth scopes cannot exceed the
+ * granting member's current role". Expressed as an intersection rather than a
+ * validation, deliberately: a grant request naming a scope above the ceiling is
+ * *reduced*, not refused. Refusing would tell the caller which scopes exist above
+ * their role, and a partial grant is what the OAuth consent screen has to show
+ * anyway.
+ *
+ * Order follows `SCOPES`, so the result is stable regardless of how the request
+ * was ordered — a granted-scope list that reorders between requests looks like a
+ * change to anything comparing them.
+ */
+export declare function capScopesToRole(requested: readonly Scope[], role: MembershipRole): readonly Scope[];
+/**
+ * The scopes an OAuth client may ask a member to grant.
+ *
+ * **Derived from what the operations actually accept, not from `SCOPES`.** The
+ * authorization server advertises a `scopes_supported` list and the consent
+ * screen offers it; without this, a client could request — and a member could
+ * approve — a scope whose only operation refuses OAuth principals outright. The
+ * grant would look granted and buy nothing, which is the worst kind of consent:
+ * one that misrepresents what was agreed to.
+ *
+ * `projects:read` is the first scope this excludes. Listing an organization's
+ * projects is a signed-in member's question, and a token's authority already is
+ * one project.
+ */
+export declare function grantableScopes(): readonly Scope[];
+/**
+ * The scopes an API credential can actually use.
+ *
+ * **`grantableScopes`'s sibling, and it exists for the same reason.** That one
+ * stops a consent screen offering a scope whose only operation refuses OAuth
+ * principals — "a grant that looks granted and buys nothing, which is the worst
+ * kind of consent". A credential-issuing surface has the identical exposure: a
+ * key issued with a scope no credential-callable operation declares is a key
+ * that will be refused `authentication_required` on the only route it names,
+ * for ever, and nothing about the key says so.
+ *
+ * `projects:read` was the first such scope and `projects:write` is the second —
+ * both belong to operations that accept only a signed-in member, because a
+ * key's authority already *is* one project. Deriving the list rather than
+ * naming them is what keeps a third from arriving unnoticed.
+ */
+export declare function credentialScopes(): readonly Scope[];
+/** One row of the generated policy matrix. */
+export interface PolicyMatrixRow {
+    /**
+     * Scopes only some calls to this operation need.
+     *
+     * Present on the row rather than folded into `scopes`, because folding them
+     * would say every caller needs them — and `roles` below would then report
+     * that a member cannot rotate a credential at all, which is false.
+     */
+    readonly conditionalScopes?: readonly Scope[];
+    readonly mutates: boolean;
+    readonly operation: string;
+    /** Which kinds of principal may perform it. Empty means none is needed. */
+    readonly principals: readonly PrincipalKind[];
+    /** Roles that may perform it, in `MEMBERSHIP_ROLES` order. */
+    readonly roles: readonly MembershipRole[];
+    /** Scopes the operation requires. Empty means no principal is needed. */
+    readonly scopes: readonly Scope[];
+}
+/**
+ * Whether a role can perform an operation.
+ *
+ * An operation requiring no scopes needs no principal at all, so every role can
+ * reach it — and so can an unauthenticated caller. That is stated here rather
+ * than left implicit because "requires no scope" and "is public" are the same
+ * sentence, and a reader should not have to infer it.
+ */
+export declare function roleCanPerform(role: MembershipRole, operation: OperationDefinition): boolean;
+/**
+ * The policy matrix, derived from the operation registry.
+ *
+ * Generated rather than written down. A hand-maintained matrix is a second
+ * statement of the same policy, and the two drift — which is precisely what the
+ * artifact pipeline exists to prevent. Adding an operation to `OPERATIONS`
+ * changes this output, and `check:contracts` fails until the committed artifact
+ * matches.
+ */
+export declare function policyMatrix(): readonly PolicyMatrixRow[];

package/dist/policy.js

@@ -0,0 +1,180 @@
+import { SCOPES, effectiveScopes, } from "./authority.js";
+import { MEMBERSHIP_ROLES } from "./identity.js";
+import { OPERATIONS } from "./operations.js";
+/** The registry as its declared interface. See `grantableScopes` for why. */
+function allOperations() {
+    return OPERATIONS;
+}
+/**
+ * One policy for every way in.
+ *
+ * A Clerk session, an API credential, and an OAuth grant all resolve to the same
+ * `Principal`, and every one of them is authorized by the rules here. That is the
+ * point of W1-03: the legacy scheduler let each entry point decide for itself, so
+ * whichever one was least careful became the effective policy.
+ *
+ * **Scope names are public.** Renaming one is a contract change, not a
+ * refactor — an API credential issued yesterday carries the old name, and a
+ * customer's code names it too. `SCOPES` is the frozen list; this module says who
+ * may hold which.
+ */
+/**
+ * The most a human role may ever hold.
+ *
+ * A ceiling, not a grant. An API credential or OAuth grant is issued *within* a
+ * member's ceiling and is usually narrower; nothing anywhere may exceed it. That
+ * asymmetry is what stops a member minting a credential more powerful than
+ * themselves, which is the standard privilege-escalation route in a system with
+ * delegated credentials.
+ *
+ * `admin` holds everything, and is written as `SCOPES` rather than a copied list
+ * so a new scope cannot be introduced that admins silently lack.
+ *
+ * `member` is everything except `credentials:administer` — acting on a
+ * credential somebody else issued.
+ *
+ * **It was everything except credential management entirely, and the operator
+ * changed that on 2026-08-15.** The reason it changed is that the argument for
+ * the old line did not support it: the comment above justifies the *ceiling
+ * mechanism*, which stops a credential exceeding its issuer, and that holds
+ * whatever the ceiling contains. What withholding `credentials:write` actually
+ * bought was a developer who could already create live schedules and live
+ * destinations from the browser, and had to ask somebody else for the key that
+ * does the same thing by another route. This is a developer tool and a `member`
+ * is a developer.
+ *
+ * **What is left is the distinction that survives being asked "who does this
+ * protect".** Your own access is yours; somebody else's is not, and taking a
+ * colleague's key away — or rotating it, which retires it on a delay — belongs
+ * with the role that manages the organization. Inviting and removing people is
+ * Clerk's and this product does not do it, so this is the whole of what `admin`
+ * means here.
+ */
+const MEMBER_SCOPES = SCOPES.filter((scope) => scope !== "credentials:administer");
+export const ROLE_SCOPE_CEILINGS = {
+    admin: SCOPES,
+    member: MEMBER_SCOPES,
+};
+/** Everything a role may hold, expanded so a write implies its read. */
+export function ceilingForRole(role) {
+    return effectiveScopes(ROLE_SCOPE_CEILINGS[role]);
+}
+/** Whether a role may ever hold a scope. */
+export function roleAllows(role, scope) {
+    return ceilingForRole(role).has(scope);
+}
+/**
+ * Narrow requested scopes to what a role may actually hold.
+ *
+ * The rule the project specification states as "OAuth scopes cannot exceed the
+ * granting member's current role". Expressed as an intersection rather than a
+ * validation, deliberately: a grant request naming a scope above the ceiling is
+ * *reduced*, not refused. Refusing would tell the caller which scopes exist above
+ * their role, and a partial grant is what the OAuth consent screen has to show
+ * anyway.
+ *
+ * Order follows `SCOPES`, so the result is stable regardless of how the request
+ * was ordered — a granted-scope list that reorders between requests looks like a
+ * change to anything comparing them.
+ */
+export function capScopesToRole(requested, role) {
+    const ceiling = ceilingForRole(role);
+    const asked = new Set(requested);
+    return SCOPES.filter((scope) => asked.has(scope) && ceiling.has(scope));
+}
+/**
+ * The scopes an OAuth client may ask a member to grant.
+ *
+ * **Derived from what the operations actually accept, not from `SCOPES`.** The
+ * authorization server advertises a `scopes_supported` list and the consent
+ * screen offers it; without this, a client could request — and a member could
+ * approve — a scope whose only operation refuses OAuth principals outright. The
+ * grant would look granted and buy nothing, which is the worst kind of consent:
+ * one that misrepresents what was agreed to.
+ *
+ * `projects:read` is the first scope this excludes. Listing an organization's
+ * projects is a signed-in member's question, and a token's authority already is
+ * one project.
+ */
+export function grantableScopes() {
+    // `.some` rather than `.includes`: `OPERATIONS` is a literal array, so each
+    // entry's `principals` is its own tuple type and `includes` narrows its
+    // argument to that tuple's members — which is `never` across the union.
+    // **`operationsFor` rather than `OPERATIONS`**: the registry is a
+    // const-asserted tuple, so each entry is its own literal type and an optional
+    // field absent from one entry is absent from the union. Reading it as the
+    // declared interface is what lets an optional field be read at all.
+    const grantable = new Set(allOperations()
+        .filter((operation) => operation.principals.some((kind) => kind === "oauth"))
+        .flatMap((operation) => [
+        ...operation.scopes,
+        // **And the ones only some calls need.** A scope an operation can refuse
+        // for but never declares is a scope no grant can carry, so the refusal
+        // would be unreachable through OAuth — and `credentials:administer` is
+        // the only scope a member does not hold, which would have left every
+        // role-narrowing rule on the consent path with nothing to narrow.
+        ...(operation.conditionalScopes ?? []),
+    ]));
+    // `SCOPES` order, so the advertised list is stable regardless of registry order.
+    return SCOPES.filter((scope) => grantable.has(scope));
+}
+/**
+ * The scopes an API credential can actually use.
+ *
+ * **`grantableScopes`'s sibling, and it exists for the same reason.** That one
+ * stops a consent screen offering a scope whose only operation refuses OAuth
+ * principals — "a grant that looks granted and buys nothing, which is the worst
+ * kind of consent". A credential-issuing surface has the identical exposure: a
+ * key issued with a scope no credential-callable operation declares is a key
+ * that will be refused `authentication_required` on the only route it names,
+ * for ever, and nothing about the key says so.
+ *
+ * `projects:read` was the first such scope and `projects:write` is the second —
+ * both belong to operations that accept only a signed-in member, because a
+ * key's authority already *is* one project. Deriving the list rather than
+ * naming them is what keeps a third from arriving unnoticed.
+ */
+export function credentialScopes() {
+    const usable = new Set(allOperations()
+        .filter((operation) => operation.principals.some((kind) => kind === "api-credential"))
+        .flatMap((operation) => [
+        ...operation.scopes,
+        ...(operation.conditionalScopes ?? []),
+    ]));
+    return SCOPES.filter((scope) => usable.has(scope));
+}
+/**
+ * Whether a role can perform an operation.
+ *
+ * An operation requiring no scopes needs no principal at all, so every role can
+ * reach it — and so can an unauthenticated caller. That is stated here rather
+ * than left implicit because "requires no scope" and "is public" are the same
+ * sentence, and a reader should not have to infer it.
+ */
+export function roleCanPerform(role, operation) {
+    const ceiling = ceilingForRole(role);
+    return operation.scopes.every((scope) => ceiling.has(scope));
+}
+/**
+ * The policy matrix, derived from the operation registry.
+ *
+ * Generated rather than written down. A hand-maintained matrix is a second
+ * statement of the same policy, and the two drift — which is precisely what the
+ * artifact pipeline exists to prevent. Adding an operation to `OPERATIONS`
+ * changes this output, and `check:contracts` fails until the committed artifact
+ * matches.
+ */
+export function policyMatrix() {
+    return [...allOperations()]
+        .sort((left, right) => left.id.localeCompare(right.id))
+        .map((operation) => ({
+        mutates: operation.mutates,
+        operation: operation.id,
+        ...(operation.conditionalScopes === undefined
+            ? {}
+            : { conditionalScopes: [...operation.conditionalScopes] }),
+        principals: [...operation.principals],
+        roles: MEMBERSHIP_ROLES.filter((role) => roleCanPerform(role, operation)),
+        scopes: [...operation.scopes],
+    }));
+}

package/dist/problems.d.ts

@@ -0,0 +1,158 @@
+import { z } from "zod";
+/**
+ * Refusals.
+ *
+ * Every non-2xx response is an RFC 9457 problem document. It carries a stable
+ * machine-readable `code`, a human `title`, and — where the caller can act on
+ * it — a `retry` hint and per-field `errors`. The legacy scheduler returned
+ * `{ "error": "invalid_cron" }` with no category, no correlation, and no way
+ * for a client to tell "retry this" from "never retry this"; every adapter and
+ * SDK invented its own interpretation.
+ *
+ * `code` is the contract. `title` and `detail` are prose and may change without
+ * being a breaking change; clients must never branch on them.
+ */
+export declare const PROBLEM_CATEGORIES: readonly ["authentication", "authorization", "conflict", "invalid-request", "not-found", "rate-limited", "unavailable"];
+export declare const problemCategorySchema: z.ZodEnum<{
+    authentication: "authentication";
+    authorization: "authorization";
+    conflict: "conflict";
+    "invalid-request": "invalid-request";
+    "not-found": "not-found";
+    "rate-limited": "rate-limited";
+    unavailable: "unavailable";
+}>;
+export type ProblemCategory = z.infer<typeof problemCategorySchema>;
+/**
+ * The stable refusal catalog. Adding a code is additive; removing one, or
+ * changing the category or status of an existing one, is breaking.
+ */
+export declare const PROBLEM_CODES: {
+    readonly authentication_required: {
+        readonly category: "authentication";
+        readonly status: 401;
+    };
+    readonly credential_expired: {
+        readonly category: "authentication";
+        readonly status: 401;
+    };
+    readonly credential_revoked: {
+        readonly category: "authentication";
+        readonly status: 401;
+    };
+    readonly endpoint_unverified: {
+        readonly category: "invalid-request";
+        readonly status: 422;
+    };
+    readonly idempotency_key_reused: {
+        readonly category: "conflict";
+        readonly status: 409;
+    };
+    readonly invalid_request: {
+        readonly category: "invalid-request";
+        readonly status: 400;
+    };
+    readonly not_found: {
+        readonly category: "not-found";
+        readonly status: 404;
+    };
+    readonly payload_too_large: {
+        readonly category: "invalid-request";
+        readonly status: 413;
+    };
+    readonly plan_limit_reached: {
+        readonly category: "conflict";
+        readonly status: 409;
+    };
+    readonly rate_limited: {
+        readonly category: "rate-limited";
+        readonly status: 429;
+    };
+    readonly scope_missing: {
+        readonly category: "authorization";
+        readonly status: 403;
+    };
+    readonly service_unavailable: {
+        readonly category: "unavailable";
+        readonly status: 503;
+    };
+    readonly state_conflict: {
+        readonly category: "conflict";
+        readonly status: 409;
+    };
+    readonly test_to_live_escalation: {
+        readonly category: "authorization";
+        readonly status: 403;
+    };
+    readonly version_conflict: {
+        readonly category: "conflict";
+        readonly status: 409;
+    };
+};
+export type ProblemCode = keyof typeof PROBLEM_CODES;
+export declare const problemCodeSchema: z.ZodEnum<{
+    authentication_required: "authentication_required";
+    credential_expired: "credential_expired";
+    credential_revoked: "credential_revoked";
+    endpoint_unverified: "endpoint_unverified";
+    idempotency_key_reused: "idempotency_key_reused";
+    invalid_request: "invalid_request";
+    not_found: "not_found";
+    payload_too_large: "payload_too_large";
+    plan_limit_reached: "plan_limit_reached";
+    rate_limited: "rate_limited";
+    scope_missing: "scope_missing";
+    service_unavailable: "service_unavailable";
+    state_conflict: "state_conflict";
+    test_to_live_escalation: "test_to_live_escalation";
+    version_conflict: "version_conflict";
+}>;
+/** Whether repeating the identical request could succeed later. */
+export declare function isRetryable(code: ProblemCode): boolean;
+export declare const fieldErrorSchema: z.ZodObject<{
+    pointer: z.ZodString;
+    reason: z.ZodString;
+}, z.core.$strip>;
+export type FieldError = z.infer<typeof fieldErrorSchema>;
+export declare const problemSchema: z.ZodObject<{
+    code: z.ZodEnum<{
+        authentication_required: "authentication_required";
+        credential_expired: "credential_expired";
+        credential_revoked: "credential_revoked";
+        endpoint_unverified: "endpoint_unverified";
+        idempotency_key_reused: "idempotency_key_reused";
+        invalid_request: "invalid_request";
+        not_found: "not_found";
+        payload_too_large: "payload_too_large";
+        plan_limit_reached: "plan_limit_reached";
+        rate_limited: "rate_limited";
+        scope_missing: "scope_missing";
+        service_unavailable: "service_unavailable";
+        state_conflict: "state_conflict";
+        test_to_live_escalation: "test_to_live_escalation";
+        version_conflict: "version_conflict";
+    }>;
+    detail: z.ZodOptional<z.ZodString>;
+    errors: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        pointer: z.ZodString;
+        reason: z.ZodString;
+    }, z.core.$strip>>>;
+    retryAfterSeconds: z.ZodOptional<z.ZodNumber>;
+    status: z.ZodNumber;
+    title: z.ZodString;
+    traceId: z.ZodOptional<z.ZodString>;
+    type: z.ZodLiteral<"about:blank">;
+}, z.core.$strip>;
+export type Problem = z.infer<typeof problemSchema>;
+export interface ProblemOptions {
+    readonly detail?: string;
+    readonly errors?: readonly FieldError[];
+    readonly retryAfterSeconds?: number;
+    readonly title: string;
+    readonly traceId?: string;
+}
+/**
+ * Builds a problem whose status and category cannot contradict its code, and
+ * which cannot carry a retry hint on a code that is not retryable.
+ */
+export declare function problem(code: ProblemCode, options: ProblemOptions): Problem;