@greatwait/contracts 0.1.0-alpha.3 → 0.1.0-alpha.5

package/dist/organization-lifecycle.d.ts

@@ -0,0 +1,34 @@
+import { z } from "./zod.js";
+export declare const organizationLifecycleSchema: import("zod").ZodObject<{
+    organizationId: import("zod").ZodString;
+    generation: import("zod").ZodNumber;
+    phase: import("zod").ZodEnum<{
+        active: "active";
+        closing: "closing";
+        closed: "closed";
+        restoring: "restoring";
+        purging: "purging";
+        erased: "erased";
+    }>;
+    requestedAt: import("zod").ZodNullable<import("zod").ZodString>;
+    reversibleUntil: import("zod").ZodNullable<import("zod").ZodString>;
+    purgeDeadline: import("zod").ZodNullable<import("zod").ZodString>;
+    immediate: import("zod").ZodBoolean;
+    converged: import("zod").ZodBoolean;
+}, import("zod/v4/core").$strict>;
+export declare const organizationClosureRequestSchema: import("zod").ZodObject<{
+    expectedGeneration: import("zod").ZodNumber;
+    immediate: import("zod").ZodBoolean;
+    confirmation: import("zod").ZodLiteral<"delete organization">;
+}, import("zod/v4/core").$strict>;
+export declare const organizationRestoreRequestSchema: import("zod").ZodObject<{
+    expectedGeneration: import("zod").ZodNumber;
+}, import("zod/v4/core").$strict>;
+export type OrganizationLifecycle = z.infer<typeof organizationLifecycleSchema>;
+export declare const ORGANIZATION_LIFECYCLE_OPERATIONS: readonly [import("./operations.js").OperationDefinition & {
+    readonly id: "organizations.lifecycle";
+}, import("./operations.js").OperationDefinition & {
+    readonly id: "organizations.close";
+}, import("./operations.js").OperationDefinition & {
+    readonly id: "organizations.restore";
+}];

package/dist/organization-lifecycle.js

@@ -0,0 +1,122 @@
+import { organizationIdSchema } from "./identifiers.js";
+import { API_UNUSED_RESPONSE_SCHEMA, defineOperations, } from "./operation-definitions.js";
+import { timestampSchema } from "./time.js";
+import { z } from "./zod.js";
+export const organizationLifecycleSchema = z.strictObject({
+    organizationId: organizationIdSchema,
+    generation: z.number().int().nonnegative(),
+    phase: z.enum([
+        "active",
+        "closing",
+        "closed",
+        "restoring",
+        "purging",
+        "erased",
+    ]),
+    requestedAt: timestampSchema.nullable(),
+    reversibleUntil: timestampSchema.nullable(),
+    purgeDeadline: timestampSchema.nullable(),
+    immediate: z.boolean(),
+    converged: z.boolean(),
+});
+export const organizationClosureRequestSchema = z.strictObject({
+    expectedGeneration: z.number().int().nonnegative(),
+    immediate: z.boolean(),
+    confirmation: z.literal("delete organization"),
+});
+export const organizationRestoreRequestSchema = z.strictObject({
+    expectedGeneration: z.number().int().positive(),
+});
+const example = {
+    organizationId: "org_01h8xyz9k2m4n6p8r0t2v4w6y8",
+    generation: 1,
+    phase: "closed",
+    requestedAt: "2026-09-12T12:00:00.000Z",
+    reversibleUntil: "2026-09-19T12:00:00.000Z",
+    purgeDeadline: "2026-10-12T12:00:00.000Z",
+    immediate: false,
+    converged: true,
+};
+const common = {
+    creates: false,
+    idempotent: true,
+    mcp: {
+        kind: "unavailable",
+        reason: "Organization closure and recovery require a signed-in administrator; delegated credentials cannot acquire organization-wide authority.",
+    },
+    principals: ["session"],
+    problems: [
+        "invalid_request",
+        "not_found",
+        "state_conflict",
+        "version_conflict",
+    ],
+    response: globalThis.GREATWAIT_API_REQUEST_REGISTRY
+        ? API_UNUSED_RESPONSE_SCHEMA
+        : organizationLifecycleSchema,
+    scopes: ["projects:administer"],
+    sessionAuthority: "organization",
+    surfaces: ["api", "mock"],
+    example: globalThis.GREATWAIT_RUNTIME_WITHOUT_EXAMPLES
+        ? {}
+        : example,
+};
+export const ORGANIZATION_LIFECYCLE_OPERATIONS = defineOperations([
+    {
+        ...common,
+        id: "organizations.lifecycle",
+        problems: ["not_found", "service_unavailable"],
+        method: "GET",
+        mutates: false,
+        path: "/v1/organization/lifecycle",
+        summary: globalThis.GREATWAIT_API_REQUEST_REGISTRY
+            ? ""
+            : "Read organization closure progress",
+        description: globalThis.GREATWAIT_RUNTIME_CONTRACTS_ONLY
+            ? ""
+            : "Reads the signed-in administrator's organization closure generation and progress, including the reversible window. It remains available during closure so the administrator can request recovery.",
+    },
+    {
+        ...common,
+        id: "organizations.close",
+        method: "POST",
+        mutates: true,
+        path: "/v1/organization/close",
+        summary: globalThis.GREATWAIT_API_REQUEST_REGISTRY
+            ? ""
+            : "Close the organization and request erasure",
+        description: globalThis.GREATWAIT_RUNTIME_CONTRACTS_ONLY
+            ? ""
+            : "Stops customer access, execution and new purchases across the organization. Ordinary closure can be reversed for seven days; immediate erasure skips that window. Non-financial erasure completes within thirty days unless suspended by an operator legal hold. Financial records remain under the configured retention policy. An interrupted request resumes under the same generation; closure is acknowledged only after every configured scheduling shard is fenced.",
+        request: organizationClosureRequestSchema,
+        requestExample: globalThis
+            .GREATWAIT_RUNTIME_WITHOUT_EXAMPLES
+            ? {}
+            : {
+                expectedGeneration: 0,
+                immediate: false,
+                confirmation: "delete organization",
+            },
+    },
+    {
+        ...common,
+        id: "organizations.restore",
+        method: "POST",
+        mutates: true,
+        path: "/v1/organization/restore",
+        summary: globalThis.GREATWAIT_API_REQUEST_REGISTRY
+            ? ""
+            : "Cancel organization erasure during its reversible window",
+        description: globalThis.GREATWAIT_RUNTIME_CONTRACTS_ONLY
+            ? ""
+            : "Restores access after every configured scheduling shard acknowledges the new generation. Immediate erasure and expired reversible windows cannot be restored. Recovery preserves each schedule's pause and lateness policy and does not reauthorize automatic top-up.",
+        request: organizationRestoreRequestSchema,
+        requestExample: globalThis
+            .GREATWAIT_RUNTIME_WITHOUT_EXAMPLES
+            ? {}
+            : { expectedGeneration: 1 },
+        example: globalThis.GREATWAIT_RUNTIME_WITHOUT_EXAMPLES
+            ? {}
+            : { ...example, generation: 2, phase: "active" },
+    },
+]);

package/dist/partition.d.ts

@@ -53,7 +53,7 @@ export declare const SINGLE_SHARD = "0";
  * 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.
+ * Thirty-two is one control-plane 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.
  */
@@ -93,8 +93,8 @@ export declare const MAX_PARTITION_SHARDS = 8;
  * 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
+ * Now the shard a schedule was actually stored in is *recorded* in the
+ * control-plane 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.
  *
@@ -295,7 +295,7 @@ export interface DrainProjectionsQuery {
  *
  * **Nothing is deleted here.** The intents stay until `settleProjections` says
  * the control plane has them, which is acceptance criterion 1: an intent
- * survives a drain whose D1 write never landed, and a partition that has never
+ * survives a drain whose control-plane write never landed, and a partition that has never
  * been initialized answers an empty drain rather than a refusal — a shard nobody
  * has written to owes the directory nothing.
  */
@@ -304,9 +304,10 @@ export type DrainProjectionsOutcome = PartitionRefused | RetainedProjections;
  * Retire the intents the control plane accepted, and postpone the rest.
  *
  * Both halves in one call rather than two, because a drain has exactly one of
- * these outcomes and the failing half must not need a healthy D1 to be recorded:
- * the deferral is what stops a control-plane outage from making every subsequent
- * request pay a D1 timeout for the same intent.
+ * these outcomes and the failing half must not need a healthy control plane
+ * to be recorded: the deferral is what stops a control-plane outage from
+ * making every subsequent request pay a control-plane timeout for the same
+ * intent.
  */
 export interface SettleProjectionsCommand {
     /** Intents the control plane has durably applied, or cannot route. */
@@ -470,7 +471,7 @@ export interface CreateScheduleCommand {
     readonly partitionKey?: string;
     /**
      * Authenticated encrypted customer JSON. The plaintext never crosses this
-     * seam and is never stored in a D1 projection.
+     * seam and is never stored in a control-plane projection.
      */
     readonly payloadEnvelope?: string;
     /** UTF-8 byte length of the plaintext JSON, before encryption. */
@@ -479,7 +480,7 @@ export interface CreateScheduleCommand {
      * The verified endpoint URL captured for durable host routing.
      *
      * This is internal metadata, not a public response field. The Host Executor
-     * re-reads the D1 endpoint row before signing and reroutes if the URL has
+     * re-reads the control-plane endpoint row before signing and reroutes if the URL has
      * changed. It does not resolve or revalidate the address: that boundary was
      * removed by FXO-1566 and FXO-1581, and this comment claimed it afterwards.
      */
@@ -540,6 +541,12 @@ export interface ListOccurrencesQuery {
     readonly after?: OccurrencePagePosition;
     readonly authority: Authority;
     readonly limit: number;
+    /**
+     * Which end to walk from; oldest when absent. A cursor belongs to the order
+     * it was issued under. Spelled out rather than imported so this module keeps
+     * carrying no runtime import of the contract barrel.
+     */
+    readonly order?: "newest" | "oldest";
     readonly scheduleId: string;
 }
 export type ListOccurrencesOutcome = PartitionRefused | {
@@ -621,6 +628,8 @@ export interface ScheduleWriteCommand {
 }
 /** Replace a schedule's definition, starting a new generation. */
 export interface ReplaceScheduleCommand extends ScheduleWriteCommand {
+    /** A new name; absent keeps the stored one (W4-14). */
+    readonly name?: string;
     /**
      * The replacement's delivery settings.
      *
@@ -692,6 +701,8 @@ export interface ForecastQuery {
     readonly authority: Authority;
     readonly bucketMs: number;
     readonly fromMs: number;
+    /** Omit named-key cells when the public caller only needs totals/classes. */
+    readonly includePartitionKeys?: boolean;
     readonly toMs: number;
 }
 /** One bucket, as one partition sees it. */
@@ -701,6 +712,8 @@ export interface ForecastPartitionBucket {
     readonly count: number;
     /** Occurrences here that are the next firing of their schedule. */
     readonly nextFireCount: number;
+    /** Named-key counts folded into the public remainder after exact ranking. */
+    readonly omittedPartitionKeyCount?: number;
     /**
      * Named customer keys and their counts, ascending by key.
      *
@@ -740,6 +753,27 @@ export type ForecastOutcome = PartitionRefused | {
      */
     readonly asOfMs?: number;
     readonly buckets: readonly ForecastPartitionBucket[];
+    /** Operator work budget that prevented a complete answer, never a count. */
+    readonly exhaustedBudget?: string;
+    readonly coverage?: import("./forecast.js").ForecastCoverage;
+    /**
+     * The instant this answer actually reached, when it is not the one asked
+     * for.
+     *
+     * **A plan horizon shortens a forecast rather than refusing it**, which
+     * is the right trade — a plan that buys six hours is telling a customer
+     * how far it can see, and answering "no forecast at all" because they
+     * asked for a day would be a worse reading of the same purchase. What
+     * was missing is the other half: the published window said twenty-four
+     * hours and the last eighteen of them were empty, so a caller sizing
+     * capacity read "nothing planned" where the truth was "not projected",
+     * and under-read by three quarters. The dashboard drew it as eighteen
+     * hours of zero bars.
+     *
+     * Absent when the answer covered the whole window, which is every source
+     * with no horizon over it.
+     */
+    readonly coveredToMs?: number;
     readonly truncated: boolean;
 };
 /**

package/dist/partition.js

@@ -51,7 +51,7 @@ export const SINGLE_SHARD = "0";
  * 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.
+ * Thirty-two is one control-plane 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.
  */
@@ -110,8 +110,8 @@ function fnv1a32(input) {
  * 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
+ * Now the shard a schedule was actually stored in is *recorded* in the
+ * control-plane 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.
  *

package/dist/policy.d.ts

@@ -47,10 +47,10 @@ export declare function grantableScopes(): readonly Scope[];
  * 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.
+ * `projects:read` remains excluded because enumerating an organization is a
+ * signed-in member's question. Project writes are different: a key's authority
+ * already names exactly the project that rename/archive/delete may affect, so
+ * those scopes become usable when their operations do.
  */
 export declare function credentialScopes(): readonly Scope[];
 /** One row of the generated policy matrix. */

package/dist/policy.js

@@ -50,9 +50,13 @@ function allOperations() {
  * 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");
+const MEMBER_SCOPES = SCOPES.filter((scope) => scope !== "billing:write" &&
+    scope !== "credentials:administer" &&
+    scope !== "projects:administer");
+const BILLING_SCOPES = SCOPES.filter((scope) => scope !== "credentials:administer" && scope !== "projects:administer");
 export const ROLE_SCOPE_CEILINGS = {
     admin: SCOPES,
+    billing: BILLING_SCOPES,
     member: MEMBER_SCOPES,
 };
 /** Everything a role may hold, expanded so a write implies its read. */
@@ -129,10 +133,10 @@ export function grantableScopes() {
  * 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.
+ * `projects:read` remains excluded because enumerating an organization is a
+ * signed-in member's question. Project writes are different: a key's authority
+ * already names exactly the project that rename/archive/delete may affect, so
+ * those scopes become usable when their operations do.
  */
 export function credentialScopes() {
     const usable = new Set(allOperations()

package/dist/problems.d.ts

@@ -1,4 +1,4 @@
-import { z } from "zod";
+import { z } from "./zod.js";
 /**
  * Refusals.
  *
@@ -12,12 +12,13 @@ import { z } from "zod";
  * `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<{
+export declare const PROBLEM_CATEGORIES: readonly ["authentication", "authorization", "conflict", "invalid-request", "not-configured", "not-found", "rate-limited", "unavailable"];
+export declare const problemCategorySchema: import("zod").ZodEnum<{
     authentication: "authentication";
     authorization: "authorization";
     conflict: "conflict";
     "invalid-request": "invalid-request";
+    "not-configured": "not-configured";
     "not-found": "not-found";
     "rate-limited": "rate-limited";
     unavailable: "unavailable";
@@ -32,6 +33,14 @@ export declare const PROBLEM_CODES: {
         readonly category: "authentication";
         readonly status: 401;
     };
+    readonly billing_not_ready: {
+        readonly category: "unavailable";
+        readonly status: 503;
+    };
+    readonly capability_not_configured: {
+        readonly category: "not-configured";
+        readonly status: 503;
+    };
     readonly credential_expired: {
         readonly category: "authentication";
         readonly status: 401;
@@ -40,10 +49,6 @@ export declare const PROBLEM_CODES: {
         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;
@@ -64,10 +69,18 @@ export declare const PROBLEM_CODES: {
         readonly category: "conflict";
         readonly status: 409;
     };
+    readonly project_archived: {
+        readonly category: "conflict";
+        readonly status: 409;
+    };
     readonly rate_limited: {
         readonly category: "rate-limited";
         readonly status: 429;
     };
+    readonly revision_conflict: {
+        readonly category: "conflict";
+        readonly status: 409;
+    };
     readonly scope_missing: {
         readonly category: "authorization";
         readonly status: 403;
@@ -90,59 +103,75 @@ export declare const PROBLEM_CODES: {
     };
 };
 export type ProblemCode = keyof typeof PROBLEM_CODES;
-export declare const problemCodeSchema: z.ZodEnum<{
+export declare const problemCodeSchema: import("zod").ZodEnum<{
     authentication_required: "authentication_required";
+    billing_not_ready: "billing_not_ready";
+    capability_not_configured: "capability_not_configured";
     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";
+    project_archived: "project_archived";
     rate_limited: "rate_limited";
+    revision_conflict: "revision_conflict";
     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. */
+/**
+ * Whether repeating the identical request could succeed later.
+ *
+ * **Two 5xx categories, opposite answers, and that is the point.**
+ * `unavailable` is something that has gone wrong and will come back;
+ * `not-configured` is something that was never turned on and will not turn
+ * itself on. Reading the status alone cannot tell them apart, which is how a
+ * permanent refusal came to be published to customers as retryable — in the
+ * SDK's `retryable`, in the CLI's exit class, and as a "Try again" control the
+ * dashboard offered for a condition no amount of trying clears.
+ */
 export declare function isRetryable(code: ProblemCode): boolean;
-export declare const fieldErrorSchema: z.ZodObject<{
-    pointer: z.ZodString;
-    reason: z.ZodString;
-}, z.core.$strip>;
+export declare const fieldErrorSchema: import("zod").ZodObject<{
+    pointer: import("zod").ZodString;
+    reason: import("zod").ZodString;
+}, import("zod/v4/core").$strip>;
 export type FieldError = z.infer<typeof fieldErrorSchema>;
-export declare const problemSchema: z.ZodObject<{
-    code: z.ZodEnum<{
+export declare const problemSchema: import("zod").ZodObject<{
+    code: import("zod").ZodEnum<{
         authentication_required: "authentication_required";
+        billing_not_ready: "billing_not_ready";
+        capability_not_configured: "capability_not_configured";
         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";
+        project_archived: "project_archived";
         rate_limited: "rate_limited";
+        revision_conflict: "revision_conflict";
         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>;
+    detail: import("zod").ZodOptional<import("zod").ZodString>;
+    errors: import("zod").ZodOptional<import("zod").ZodArray<import("zod").ZodObject<{
+        pointer: import("zod").ZodString;
+        reason: import("zod").ZodString;
+    }, import("zod/v4/core").$strip>>>;
+    retryAfterSeconds: import("zod").ZodOptional<import("zod").ZodNumber>;
+    status: import("zod").ZodNumber;
+    title: import("zod").ZodString;
+    traceId: import("zod").ZodOptional<import("zod").ZodString>;
+    type: import("zod").ZodLiteral<"about:blank">;
+}, import("zod/v4/core").$strip>;
 export type Problem = z.infer<typeof problemSchema>;
 export interface ProblemOptions {
     readonly detail?: string;

package/dist/problems.js

@@ -1,4 +1,4 @@
-import { z } from "zod";
+import { z } from "./zod.js";
 /**
  * Refusals.
  *
@@ -17,6 +17,14 @@ export const PROBLEM_CATEGORIES = [
     "authorization",
     "conflict",
     "invalid-request",
+    // **A capability this deployment was never given, which is not an outage.**
+    // Separate from `unavailable` for one reason: `isRetryable` is a function of
+    // the category, and these two answer the retry question oppositely. An
+    // outage clears by itself and repeating is the right move; an unconfigured
+    // capability clears when somebody changes configuration and never otherwise,
+    // so telling a client "the identical request is safe to repeat" is false and
+    // it is false forever. Both are 5xx because the caller's request was fine.
+    "not-configured",
     "not-found",
     "rate-limited",
     "unavailable",
@@ -34,15 +42,49 @@ export const PROBLEM_CODES = {
     // now. One code for both would make a missed rotation window indistinguishable
     // from a security event, and the client's remedy differs — rotate again
     // versus find out who revoked it.
+    // **"Still being set up" is not "broken", and a first screen should not say
+    // the second when it means the first.** An organization's billing account row
+    // is written by a projection that runs every minute rather than synchronously
+    // at sign-up, so a member who creates their project immediately can read
+    // billing before the row exists. That used to answer `service_unavailable`,
+    // which the dashboard renders as "The service is not answering right now" —
+    // the sentence W9-06 blocked the invited cohort over, and the one a new member
+    // met on first contact.
+    //
+    // Deliberately still `unavailable`, and therefore still retryable: repeating
+    // the request is exactly the right move, and it succeeds within about a
+    // minute. What changes is what the reader is told, not what a client does.
+    billing_not_ready: { category: "unavailable", status: 503 },
+    // **The environment was never given this capability.** A configuration fact,
+    // not a fault and not a fluctuation: the Worker holds no provider, no secret
+    // or no binding for the thing being asked about, and it will hold none until
+    // somebody deploys different configuration.
+    //
+    // It exists because `service_unavailable` was carrying both meanings, and
+    // the retry answer differs between them. W9-06 blocked the invited cohort
+    // over billing panels that said "The service is not answering right now" for
+    // capabilities production had deliberately not turned on; W9-08 found the
+    // other half still live — the same refusal reaching a customer as
+    // `retryable`, and the CLI printing "The identical request is safe to
+    // repeat" about a condition no repetition can clear.
+    //
+    // Deliberately **not** `billing_not_ready`, which is the opposite case: that
+    // one is provisioning already in flight, finishes on its own within a
+    // minute, and is correctly retryable.
+    capability_not_configured: { category: "not-configured", status: 503 },
     credential_expired: { category: "authentication", status: 401 },
     credential_revoked: { category: "authentication", status: 401 },
-    endpoint_unverified: { category: "invalid-request", status: 422 },
     idempotency_key_reused: { category: "conflict", status: 409 },
     invalid_request: { category: "invalid-request", status: 400 },
     not_found: { category: "not-found", status: 404 },
     payload_too_large: { category: "invalid-request", status: 413 },
     plan_limit_reached: { category: "conflict", status: 409 },
+    // The target belongs to the caller, but its whole project is parked. This is
+    // deliberately distinct from `not_found`: foreign projects still receive
+    // that opaque answer, while an owner needs the move that restores their own.
+    project_archived: { category: "conflict", status: 409 },
     rate_limited: { category: "rate-limited", status: 429 },
+    revision_conflict: { category: "conflict", status: 409 },
     scope_missing: { category: "authorization", status: 403 },
     service_unavailable: { category: "unavailable", status: 503 },
     // The resource is in a state that does not permit what was asked — resuming a
@@ -57,7 +99,17 @@ export const PROBLEM_CODES = {
     version_conflict: { category: "conflict", status: 409 },
 };
 export const problemCodeSchema = z.enum(Object.keys(PROBLEM_CODES));
-/** Whether repeating the identical request could succeed later. */
+/**
+ * Whether repeating the identical request could succeed later.
+ *
+ * **Two 5xx categories, opposite answers, and that is the point.**
+ * `unavailable` is something that has gone wrong and will come back;
+ * `not-configured` is something that was never turned on and will not turn
+ * itself on. Reading the status alone cannot tell them apart, which is how a
+ * permanent refusal came to be published to customers as retryable — in the
+ * SDK's `retryable`, in the CLI's exit class, and as a "Try again" control the
+ * dashboard offered for a condition no amount of trying clears.
+ */
 export function isRetryable(code) {
     const category = PROBLEM_CODES[code].category;
     return category === "rate-limited" || category === "unavailable";