@greatwait/contracts 0.1.0-alpha.1

package/dist/operations.js

@@ -0,0 +1,1837 @@
+import { z } from "zod";
+import { callbackEndpointCreatedSchema, callbackEndpointPageSchema, callbackEndpointRequestSchema, callbackEndpointRotatedSchema, callbackEndpointSchema, callbackSigningKeyRotationRequestSchema, } from "./endpoints.js";
+import { FORECAST_WINDOW_VERSION, forecastRequestSchema, forecastSchema, forecastWindowsSchema, } from "./forecast.js";
+import { usageRequestSchema, usageSchema } from "./usage.js";
+import { conditionalRequestHeaderSchema, idempotencyReplayResponseHeaderSchema, idempotencyRequestHeaderSchema, pageRequestSchema, replayedResponseHeaderSchema, requiredIdempotencyRequestHeaderSchema, versionResponseHeaderSchema, } from "./protocol.js";
+import { oauthGrantListSchema, oauthGrantRevokedSchema } from "./oauth.js";
+import { credentialCreatedSchema, credentialPageSchema, credentialRequestSchema, credentialRevokedSchema, credentialRotatedSchema, credentialRotationRequestSchema, } from "./secrets.js";
+import { attemptPageSchema, attemptViewSchema, occurrencePageSchema, occurrenceViewSchema, schedulePageSchema, scheduleRequestSchema, scheduleViewSchema, } from "./scheduling.js";
+import { testSinkCreateRequestSchema, testSinkDeliveryBodySchema, testSinkDeliveryPageSchema, testSinkPageSchema, testSinkProgramSchema, testSinkSchema, } from "./test-sink.js";
+import { projectCreateRequestSchema, projectListSchema, projectSummarySchema, } from "./tenancy.js";
+import { scaffoldVersionSchema, workspaceScaffoldSchema } from "./workspace.js";
+import { timestampSchema } from "./time.js";
+/**
+ * Deterministic behaviors the contract mock can be asked to produce.
+ *
+ * These are the failure modes an integrator must be able to rehearse before
+ * going live, and they are part of the contract rather than mock trivia: a
+ * customer tunes their receiver against exactly these categories.
+ */
+export const MOCK_BEHAVIORS = [
+    "ambiguous",
+    "redelivery",
+    "refusal",
+    "retry",
+    "success",
+    "timeout",
+];
+export const mockBehaviorSchema = z.enum(MOCK_BEHAVIORS);
+/**
+ * A mock scenario. `now` pins the clock so a test that depends on time is
+ * reproducible: without it, "what does a stale signature look like" is a test
+ * that passes until it doesn't.
+ */
+export const mockScenarioRequestSchema = z.object({
+    behavior: mockBehaviorSchema,
+    /** Fixed instant the mock reports as the current time. */
+    now: timestampSchema.optional(),
+    /** How many attempts fail before `retry` succeeds. */
+    failuresBeforeSuccess: z.number().int().min(0).max(10).optional(),
+});
+export const mockScenarioResponseSchema = z.object({
+    behavior: mockBehaviorSchema,
+    /** The instant the mock will report for the duration of this scenario. */
+    now: timestampSchema,
+    scenarioId: z.string().min(1),
+});
+export const fixtureListSchema = z.object({
+    fixtures: z.array(z.object({ id: z.string().min(1), description: z.string().min(1) })),
+});
+export const OPERATIONS = [
+    {
+        creates: false,
+        description: "Reports the service, environment, and build the request reached. Unauthenticated: it carries no customer data and is used by canaries and deployment smoke checks.",
+        example: {
+            buildSha: "9f2c1ab",
+            environment: "development",
+            service: "@greatwait/api",
+        },
+        id: "meta.version",
+        idempotent: true,
+        // A resource, not a tool. It takes no arguments and reports a fact about
+        // the deployment; publishing it as a tool would put a build sha in an
+        // agent's tool list beside the operations that actually administer
+        // schedules, and an agent picking tools reads that list.
+        mcp: { kind: "resource", uri: "greatwait://meta/version" },
+        method: "GET",
+        mutates: false,
+        path: "/__greatwait/version",
+        principals: [],
+        problems: [],
+        response: scaffoldVersionSchema,
+        scopes: [],
+        summary: "Read the deployed version",
+        surfaces: ["api", "mock"],
+    },
+    {
+        creates: false,
+        description: "Reports the workspace layer this service occupies and the layers it may depend on. Exists so the architecture boundary is observable at runtime, not only at build time.",
+        example: {
+            dependsOn: ["application", "contract", "platform"],
+            layer: "adapter",
+            service: "@greatwait/api",
+        },
+        id: "meta.scaffold",
+        idempotent: true,
+        mcp: { kind: "resource", uri: "greatwait://meta/scaffold" },
+        method: "GET",
+        mutates: false,
+        path: "/_scaffold",
+        principals: [],
+        problems: [],
+        response: workspaceScaffoldSchema,
+        scopes: [],
+        summary: "Read the workspace scaffold",
+        surfaces: ["api", "mock"],
+    },
+    {
+        creates: false,
+        description: "Lists the committed contract fixtures the mock can serve. Mock-only: the API has no fixtures.",
+        example: {
+            fixtures: [
+                {
+                    description: "The workspace scaffold every service reports.",
+                    id: "workspace-scaffold",
+                },
+            ],
+        },
+        id: "mock.listFixtures",
+        idempotent: true,
+        mcp: {
+            kind: "unavailable",
+            reason: "The contract mock's control plane. An agent handed this would call it against the real service.",
+        },
+        method: "GET",
+        mutates: false,
+        path: "/_contract/fixtures",
+        principals: [],
+        problems: [],
+        response: fixtureListSchema,
+        scopes: [],
+        summary: "List contract fixtures",
+        surfaces: ["mock"],
+    },
+    {
+        creates: false,
+        description: "Serves one committed fixture, byte-identical on every call. Returns a not_found problem for an unknown identifier.",
+        example: {
+            dependsOn: ["application", "contract", "platform"],
+            layer: "adapter",
+            service: "@greatwait/contract-mock",
+        },
+        id: "mock.getFixture",
+        idempotent: true,
+        mcp: {
+            kind: "unavailable",
+            reason: "The contract mock's control plane. An agent handed this would call it against the real service.",
+        },
+        method: "GET",
+        mutates: false,
+        path: "/_contract/fixtures/{fixtureId}",
+        principals: [],
+        problems: ["not_found"],
+        response: workspaceScaffoldSchema,
+        scopes: [],
+        summary: "Read a contract fixture",
+        surfaces: ["mock"],
+    },
+    {
+        creates: true,
+        description: "Creates a reusable callback endpoint in the caller's project and environment. The destination must be HTTPS on effective port 443, contain no URL credentials or fragment, and resolve only to public unicast addresses. The endpoint begins pending. Whether delivery waits for its secret-bound ownership challenge is a deployment policy: where the challenge is not required, which is the default, a pending endpoint is delivered to and answering the challenge only records the instant it proved possession; where it is required, attaching a pending endpoint to a schedule is refused endpoint_unverified until the challenge succeeds. A disabled endpoint is never delivered to under either policy, and a schedule write naming one answers not_found, because disabling is terminal rather than a state to recover from. The per-endpoint secret is returned in this response and nowhere else. The 50-record safety ceiling includes disabled endpoints because they remain readable for audit.",
+        example: {
+            createdAt: "2026-08-05T15:00:00.000Z",
+            environmentKind: "test",
+            id: "ep_01h8xyz9k2m4n6p8r0t2v4w6y8",
+            keyId: "csk_01h8xyz9k2m4n6p8r0t2v4w6y8",
+            project: "proj_01h8xyz9k2m4n6p8r0t2v4w6y8",
+            secret: "ptsk_test_<the-one-time-endpoint-secret-here>",
+            shownOnce: true,
+            signingKeys: { current: "csk_01h8xyz9k2m4n6p8r0t2v4w6y8" },
+            status: "pending",
+            updatedAt: "2026-08-05T15:00:00.000Z",
+            url: "https://hooks.example.com/greatwait",
+            version: 1,
+        },
+        id: "endpoints.create",
+        idempotent: false,
+        mcp: {
+            kind: "unavailable",
+            reason: "Creation returns a one-time endpoint signing secret, and MCP has no negotiated secure-result channel that can keep it out of ordinary tool history.",
+        },
+        method: "POST",
+        mutates: true,
+        path: "/v1/endpoints",
+        principals: ["api-credential", "oauth", "session"],
+        problems: ["invalid_request", "plan_limit_reached", "rate_limited"],
+        request: callbackEndpointRequestSchema,
+        requestExample: { url: "https://hooks.example.com/greatwait" },
+        response: callbackEndpointCreatedSchema,
+        scopes: ["endpoints:write"],
+        sessionAuthority: "headers",
+        summary: "Create a callback endpoint",
+        surfaces: ["api", "mock"],
+    },
+    {
+        creates: false,
+        description: "Lists the caller's callback endpoints for exactly its own project and environment. The result is authoritative and metadata-only: no signing secret or sealed key material has a field in this shape.",
+        example: {
+            data: [
+                {
+                    createdAt: "2026-08-05T15:00:00.000Z",
+                    environmentKind: "test",
+                    id: "ep_01h8xyz9k2m4n6p8r0t2v4w6y8",
+                    project: "proj_01h8xyz9k2m4n6p8r0t2v4w6y8",
+                    signingKeys: { current: "csk_01h8xyz9k2m4n6p8r0t2v4w6y8" },
+                    status: "verified",
+                    updatedAt: "2026-08-05T15:01:00.000Z",
+                    url: "https://hooks.example.com/greatwait",
+                    verifiedAt: "2026-08-05T15:01:00.000Z",
+                    version: 2,
+                },
+            ],
+            freshness: { kind: "authoritative" },
+        },
+        id: "endpoints.list",
+        idempotent: true,
+        mcp: { destructive: false, kind: "tool", openWorld: false },
+        method: "GET",
+        mutates: false,
+        path: "/v1/endpoints",
+        principals: ["api-credential", "oauth", "session"],
+        problems: ["invalid_request"],
+        query: pageRequestSchema,
+        response: callbackEndpointPageSchema,
+        scopes: ["endpoints:read"],
+        sessionAuthority: "headers",
+        summary: "List callback endpoints",
+        surfaces: ["api", "mock"],
+    },
+    {
+        creates: false,
+        description: "Reads one callback endpoint from the caller's own project and environment. A well-formed identifier belonging to another authority is indistinguishable from an absent endpoint, and the response never contains secret material.",
+        example: {
+            createdAt: "2026-08-05T15:00:00.000Z",
+            environmentKind: "test",
+            id: "ep_01h8xyz9k2m4n6p8r0t2v4w6y8",
+            project: "proj_01h8xyz9k2m4n6p8r0t2v4w6y8",
+            signingKeys: { current: "csk_01h8xyz9k2m4n6p8r0t2v4w6y8" },
+            status: "verified",
+            updatedAt: "2026-08-05T15:01:00.000Z",
+            url: "https://hooks.example.com/greatwait",
+            verifiedAt: "2026-08-05T15:01:00.000Z",
+            version: 2,
+        },
+        id: "endpoints.read",
+        idempotent: true,
+        mcp: { destructive: false, kind: "tool", openWorld: false },
+        method: "GET",
+        mutates: false,
+        path: "/v1/endpoints/{endpointId}",
+        principals: ["api-credential", "oauth", "session"],
+        problems: ["invalid_request", "not_found"],
+        response: callbackEndpointSchema,
+        // The version a conditional update or verification must send back. Published
+        // because a caller expected to put a value in `If-Match` needs the operation
+        // that hands it out to say so — the same reason `schedules.read` carries it.
+        responseHeaders: versionResponseHeaderSchema,
+        scopes: ["endpoints:read"],
+        sessionAuthority: "headers",
+        summary: "Read a callback endpoint",
+        surfaces: ["api", "mock"],
+    },
+    {
+        creates: false,
+        description: "Replaces an endpoint's destination after applying the complete URL and DNS policy. A changed destination resets verification to pending; the endpoint cannot be used again until ownership of the new URL is proved. Disabled endpoints cannot be updated. Send If-Match with the version the endpoint was read at to be refused rather than overwrite a destination somebody else changed in the meantime.",
+        example: {
+            createdAt: "2026-08-05T15:00:00.000Z",
+            environmentKind: "test",
+            id: "ep_01h8xyz9k2m4n6p8r0t2v4w6y8",
+            project: "proj_01h8xyz9k2m4n6p8r0t2v4w6y8",
+            signingKeys: { current: "csk_01h8xyz9k2m4n6p8r0t2v4w6y8" },
+            status: "pending",
+            updatedAt: "2026-08-05T16:00:00.000Z",
+            url: "https://hooks.example.com/replacement",
+            version: 3,
+        },
+        id: "endpoints.update",
+        idempotent: true,
+        mcp: { destructive: true, kind: "tool", openWorld: true },
+        method: "PUT",
+        mutates: true,
+        path: "/v1/endpoints/{endpointId}",
+        principals: ["api-credential", "oauth", "session"],
+        problems: [
+            "invalid_request",
+            "not_found",
+            "rate_limited",
+            "state_conflict",
+            "version_conflict",
+        ],
+        request: callbackEndpointRequestSchema,
+        requestExample: { url: "https://hooks.example.com/replacement" },
+        requestHeaders: conditionalRequestHeaderSchema,
+        response: callbackEndpointSchema,
+        responseHeaders: versionResponseHeaderSchema,
+        scopes: ["endpoints:write"],
+        sessionAuthority: "headers",
+        summary: "Update a callback endpoint",
+        surfaces: ["api", "mock"],
+    },
+    {
+        creates: false,
+        description: "Re-resolves the endpoint immediately before sending one bounded ownership challenge with redirects disabled. The receiver proves possession of the one-time endpoint secret in its response. A successful challenge marks the endpoint verified; a failed challenge records only a safe failure category. Send If-Match with the version the endpoint was read at to be refused rather than challenge a destination somebody else has since changed.",
+        example: {
+            createdAt: "2026-08-05T15:00:00.000Z",
+            environmentKind: "test",
+            id: "ep_01h8xyz9k2m4n6p8r0t2v4w6y8",
+            lastVerificationAttemptAt: "2026-08-05T15:01:00.000Z",
+            project: "proj_01h8xyz9k2m4n6p8r0t2v4w6y8",
+            signingKeys: { current: "csk_01h8xyz9k2m4n6p8r0t2v4w6y8" },
+            status: "verified",
+            updatedAt: "2026-08-05T15:01:00.000Z",
+            url: "https://hooks.example.com/greatwait",
+            verifiedAt: "2026-08-05T15:01:00.000Z",
+            version: 2,
+        },
+        id: "endpoints.verify",
+        idempotent: false,
+        mcp: { destructive: false, kind: "tool", openWorld: true },
+        method: "POST",
+        mutates: true,
+        path: "/v1/endpoints/{endpointId}/verify",
+        principals: ["api-credential", "oauth", "session"],
+        problems: [
+            "invalid_request",
+            "not_found",
+            "rate_limited",
+            "state_conflict",
+            "version_conflict",
+        ],
+        requestHeaders: conditionalRequestHeaderSchema,
+        response: callbackEndpointSchema,
+        responseHeaders: versionResponseHeaderSchema,
+        scopes: ["endpoints:write"],
+        sessionAuthority: "headers",
+        summary: "Verify callback endpoint ownership",
+        surfaces: ["api", "mock"],
+    },
+    {
+        creates: true,
+        description: "Creates the next endpoint signing key and selects it immediately for new deliveries while retaining the current key in the receiver acceptance set for a bounded overlap. The overlap defaults to and cannot exceed 24 hours. A second rotation is refused until the current overlap ends. The new secret is returned once and has no recovery operation, so a call whose answer was never read may have rotated a key nobody holds: read the endpoint and compare its signing keys before repeating one. Send If-Match with the version the endpoint was read at to be refused rather than rotate an endpoint that has changed since.",
+        example: {
+            endpoint: {
+                createdAt: "2026-08-05T15:00:00.000Z",
+                environmentKind: "test",
+                id: "ep_01h8xyz9k2m4n6p8r0t2v4w6y8",
+                project: "proj_01h8xyz9k2m4n6p8r0t2v4w6y8",
+                signingKeys: {
+                    current: "csk_01h8xyz9k2m4n6p8r0t2v4w6y8",
+                    next: {
+                        id: "csk_11h8xyz9k2m4n6p8r0t2v4w6y8",
+                        overlapEndsAt: "2026-08-06T15:05:00.000Z",
+                    },
+                },
+                status: "verified",
+                updatedAt: "2026-08-05T15:05:00.000Z",
+                url: "https://hooks.example.com/greatwait",
+                verifiedAt: "2026-08-05T15:01:00.000Z",
+                version: 3,
+            },
+            keyId: "csk_11h8xyz9k2m4n6p8r0t2v4w6y8",
+            secret: "ptsk_test_<the-next-one-time-endpoint-secret-here>",
+            shownOnce: true,
+        },
+        id: "endpoints.rotateSigningKey",
+        idempotent: false,
+        mcp: {
+            kind: "unavailable",
+            reason: "Rotation returns a one-time endpoint signing secret, and MCP has no negotiated secure-result channel that can keep it out of ordinary tool history.",
+        },
+        method: "POST",
+        mutates: true,
+        path: "/v1/endpoints/{endpointId}/signing-keys/rotate",
+        principals: ["api-credential", "oauth", "session"],
+        problems: [
+            "invalid_request",
+            "not_found",
+            "state_conflict",
+            "version_conflict",
+        ],
+        request: callbackSigningKeyRotationRequestSchema,
+        requestExample: { overlapSeconds: 3600 },
+        requestHeaders: conditionalRequestHeaderSchema,
+        response: callbackEndpointRotatedSchema,
+        // The endpoint's version after the rotation, so the next conditional write
+        // from the same page has something to send.
+        responseHeaders: versionResponseHeaderSchema,
+        scopes: ["endpoints:write"],
+        sessionAuthority: "headers",
+        summary: "Rotate a callback endpoint signing key",
+        surfaces: ["api", "mock"],
+    },
+    {
+        creates: false,
+        description: "Disables an endpoint immediately and permanently: there is no operation that re-enables one. It stays readable for audit but is no longer eligible for update, verification or callback send admission, and schedules pointed at it deliver nothing. Repeating the disable is idempotent and does not write a second audit event, which is why it takes no precondition — the outcome does not depend on what else has changed.",
+        example: {
+            createdAt: "2026-08-05T15:00:00.000Z",
+            disabledAt: "2026-08-05T17:00:00.000Z",
+            environmentKind: "test",
+            id: "ep_01h8xyz9k2m4n6p8r0t2v4w6y8",
+            project: "proj_01h8xyz9k2m4n6p8r0t2v4w6y8",
+            signingKeys: { current: "csk_01h8xyz9k2m4n6p8r0t2v4w6y8" },
+            status: "disabled",
+            updatedAt: "2026-08-05T17:00:00.000Z",
+            url: "https://hooks.example.com/greatwait",
+            verifiedAt: "2026-08-05T15:01:00.000Z",
+            version: 3,
+        },
+        id: "endpoints.disable",
+        idempotent: true,
+        mcp: { destructive: true, kind: "tool", openWorld: false },
+        method: "DELETE",
+        mutates: true,
+        path: "/v1/endpoints/{endpointId}",
+        principals: ["api-credential", "oauth", "session"],
+        problems: ["invalid_request", "not_found"],
+        response: callbackEndpointSchema,
+        responseHeaders: versionResponseHeaderSchema,
+        scopes: ["endpoints:write"],
+        sessionAuthority: "headers",
+        summary: "Disable a callback endpoint",
+        surfaces: ["api", "mock"],
+    },
+    {
+        creates: true,
+        description: "Creates a deterministic receiver for one callback endpoint so failures can be rehearsed before they happen in production. Test environments only: a live principal has no such operation, and there is no request field that could widen the organization, project, or environment the sink belongs to. The sink verifies deliveries with the bound endpoint's own signing keys, so key rotation and a wrong key behave here exactly as they would at the customer's receiver. It receives and never sends: no field names a destination and no configuration makes it forward a delivery. Point the endpoint at the returned url and verify it, and every attempt lands here.",
+        example: {
+            createdAt: "2026-08-07T15:00:00.000Z",
+            deliveryCount: 0,
+            endpoint: "ep_01h8xyz9k2m4n6p8r0t2v4w6y8",
+            environmentKind: "test",
+            id: "tsk_01h8xyz9k2m4n6p8r0t2v4w6y8",
+            program: { behavior: "success" },
+            project: "proj_01h8xyz9k2m4n6p8r0t2v4w6y8",
+            updatedAt: "2026-08-07T15:00:00.000Z",
+            url: "https://sink.greatwait.dev/__greatwait/test-sinks/tsk_01h8xyz9k2m4n6p8r0t2v4w6y8",
+        },
+        id: "testsinks.create",
+        idempotent: false,
+        mcp: { destructive: false, kind: "tool", openWorld: false },
+        method: "POST",
+        mutates: true,
+        path: "/v1/test-sinks",
+        // **A session, from W4-02's third merge, and this is the last of the
+        // moratorium.** The story's first acceptance criterion says a member
+        // reaches an observed test callback "without holding an API credential",
+        // and a sink is the only receiver this product hosts — so leaving this
+        // refused would mean onboarding that ends where it always ended, at a
+        // terminal. The three sink writes move together because a surface that can
+        // make one and neither reprogram nor remove it is a surface that leaves a
+        // hosted receiver bound to somebody's destination with no way back.
+        principals: ["api-credential", "oauth", "session"],
+        problems: [
+            "invalid_request",
+            "not_found",
+            "plan_limit_reached",
+            "state_conflict",
+        ],
+        request: testSinkCreateRequestSchema,
+        requestExample: {
+            endpoint: "ep_01h8xyz9k2m4n6p8r0t2v4w6y8",
+            program: { behavior: "server_error", forDeliveries: 2, then: "success" },
+        },
+        response: testSinkSchema,
+        scopes: ["endpoints:write"],
+        sessionAuthority: "headers",
+        summary: "Create a test sink",
+        surfaces: ["api", "mock"],
+    },
+    {
+        creates: false,
+        description: "Lists the caller's test sinks for exactly its own project and test environment. A live principal receives an empty-handed refusal rather than another environment's sinks.",
+        example: {
+            data: [
+                {
+                    createdAt: "2026-08-07T15:00:00.000Z",
+                    deliveryCount: 3,
+                    endpoint: "ep_01h8xyz9k2m4n6p8r0t2v4w6y8",
+                    environmentKind: "test",
+                    id: "tsk_01h8xyz9k2m4n6p8r0t2v4w6y8",
+                    program: { behavior: "success" },
+                    project: "proj_01h8xyz9k2m4n6p8r0t2v4w6y8",
+                    updatedAt: "2026-08-07T15:02:00.000Z",
+                    url: "https://sink.greatwait.dev/__greatwait/test-sinks/tsk_01h8xyz9k2m4n6p8r0t2v4w6y8",
+                },
+            ],
+            freshness: { kind: "authoritative" },
+        },
+        id: "testsinks.list",
+        idempotent: true,
+        mcp: { destructive: false, kind: "tool", openWorld: false },
+        method: "GET",
+        mutates: false,
+        path: "/v1/test-sinks",
+        principals: ["api-credential", "oauth", "session"],
+        problems: ["invalid_request", "state_conflict"],
+        query: pageRequestSchema,
+        response: testSinkPageSchema,
+        scopes: ["endpoints:read"],
+        sessionAuthority: "headers",
+        summary: "List test sinks",
+        surfaces: ["api", "mock"],
+    },
+    {
+        creates: false,
+        description: "Reads one test sink from the caller's own project and test environment, including how many deliveries it has taken. A well-formed identifier belonging to another authority is indistinguishable from an absent sink.",
+        example: {
+            createdAt: "2026-08-07T15:00:00.000Z",
+            deliveryCount: 3,
+            endpoint: "ep_01h8xyz9k2m4n6p8r0t2v4w6y8",
+            environmentKind: "test",
+            id: "tsk_01h8xyz9k2m4n6p8r0t2v4w6y8",
+            program: { behavior: "rate_limited", retryAfterSeconds: 5 },
+            project: "proj_01h8xyz9k2m4n6p8r0t2v4w6y8",
+            updatedAt: "2026-08-07T15:02:00.000Z",
+            url: "https://sink.greatwait.dev/__greatwait/test-sinks/tsk_01h8xyz9k2m4n6p8r0t2v4w6y8",
+        },
+        id: "testsinks.read",
+        idempotent: true,
+        mcp: { destructive: false, kind: "tool", openWorld: false },
+        method: "GET",
+        mutates: false,
+        path: "/v1/test-sinks/{sinkId}",
+        principals: ["api-credential", "oauth", "session"],
+        problems: ["invalid_request", "not_found", "state_conflict"],
+        response: testSinkSchema,
+        scopes: ["endpoints:read"],
+        sessionAuthority: "headers",
+        summary: "Read a test sink",
+        surfaces: ["api", "mock"],
+    },
+    {
+        creates: false,
+        description: "Replaces a sink's behavior program. The program is resolved against the number of deliveries the sink has already taken, so `forDeliveries` counts from the next delivery rather than from the sink's creation. Repeating the identical program is idempotent and changes nothing an integrator can observe.",
+        example: {
+            createdAt: "2026-08-07T15:00:00.000Z",
+            deliveryCount: 3,
+            endpoint: "ep_01h8xyz9k2m4n6p8r0t2v4w6y8",
+            environmentKind: "test",
+            id: "tsk_01h8xyz9k2m4n6p8r0t2v4w6y8",
+            program: { behavior: "timeout" },
+            project: "proj_01h8xyz9k2m4n6p8r0t2v4w6y8",
+            updatedAt: "2026-08-07T15:03:00.000Z",
+            url: "https://sink.greatwait.dev/__greatwait/test-sinks/tsk_01h8xyz9k2m4n6p8r0t2v4w6y8",
+        },
+        id: "testsinks.configure",
+        idempotent: true,
+        mcp: { destructive: false, kind: "tool", openWorld: false },
+        method: "PUT",
+        mutates: true,
+        path: "/v1/test-sinks/{sinkId}/program",
+        principals: ["api-credential", "oauth", "session"],
+        problems: ["invalid_request", "not_found", "state_conflict"],
+        request: testSinkProgramSchema,
+        requestExample: { behavior: "timeout" },
+        response: testSinkSchema,
+        scopes: ["endpoints:write"],
+        sessionAuthority: "headers",
+        summary: "Set a test sink behavior program",
+        surfaces: ["api", "mock"],
+    },
+    {
+        creates: false,
+        description: "Lists what the sink received, most recent first with the record identifier breaking a tie, bounded by the retained-delivery ceiling. Metadata only: the identifiers, the signing key that authenticated the delivery, how the receiver disposed of it, and what it answered. The delivered body is not in this shape.",
+        example: {
+            data: [
+                {
+                    behavior: "success",
+                    delivery: "dlv_01h8xyz9k2m4n6p8r0t2v4w6y8",
+                    disposition: "processed",
+                    id: "tsd_01h8xyz9k2m4n6p8r0t2v4w6y8",
+                    keyId: "csk_01h8xyz9k2m4n6p8r0t2v4w6y8",
+                    occurrenceId: "occ_01h8xyz9k2m4n6p8r0t2v4w6y8",
+                    receivedAt: "2026-08-07T15:02:00.000Z",
+                    respondedWith: 200,
+                    scheduleId: "sch_01h8xyz9k2m4n6p8r0t2v4w6y8",
+                    sink: "tsk_01h8xyz9k2m4n6p8r0t2v4w6y8",
+                },
+            ],
+            freshness: { kind: "authoritative" },
+        },
+        id: "sinkdeliveries.list",
+        idempotent: true,
+        mcp: { destructive: false, kind: "tool", openWorld: false },
+        method: "GET",
+        mutates: false,
+        path: "/v1/test-sinks/{sinkId}/deliveries",
+        principals: ["api-credential", "oauth", "session"],
+        problems: ["invalid_request", "not_found", "state_conflict"],
+        query: pageRequestSchema,
+        response: testSinkDeliveryPageSchema,
+        scopes: ["endpoints:read"],
+        sessionAuthority: "headers",
+        summary: "List test sink deliveries",
+        surfaces: ["api", "mock"],
+    },
+    {
+        creates: false,
+        description: "Reads one recorded delivery including the exact bytes that arrived, truncated at the published cap with the original length stated. This is the one place a callback body is readable, and it is narrow on purpose: a test environment only, the creating authority only, a single record rather than a listing, and never a log. The signature is included because a MAC is not secret and comparing it against a locally computed one is how a body-mutation bug is found; no signing key appears in this shape.",
+        example: {
+            behavior: "success",
+            body: '{"version":"2026-08-08","type":"schedule.occurrence","scheduleId":"sch_01h8xyz9k2m4n6p8r0t2v4w6y8","occurrenceId":"occ_01h8xyz9k2m4n6p8r0t2v4w6y8","plannedFor":"2026-08-07T15:00:00.000Z","attempt":1,"trigger":{"kind":"automatic"},"data":{}}',
+            bodyTruncated: false,
+            delivery: "dlv_01h8xyz9k2m4n6p8r0t2v4w6y8",
+            disposition: "processed",
+            id: "tsd_01h8xyz9k2m4n6p8r0t2v4w6y8",
+            keyId: "csk_01h8xyz9k2m4n6p8r0t2v4w6y8",
+            occurrenceId: "occ_01h8xyz9k2m4n6p8r0t2v4w6y8",
+            receivedAt: "2026-08-07T15:02:00.000Z",
+            receivedBytes: 240,
+            respondedWith: 200,
+            scheduleId: "sch_01h8xyz9k2m4n6p8r0t2v4w6y8",
+            signature: "v1=11135fdfc0bc5d49ebcc9d3a0d8df1116179097cefe961c6eca281339e5cfab3",
+            sink: "tsk_01h8xyz9k2m4n6p8r0t2v4w6y8",
+        },
+        id: "sinkdeliveries.read",
+        idempotent: true,
+        mcp: {
+            kind: "unavailable",
+            reason: "The only operation that returns a delivered callback body. An agent handed it would put customer payload into ordinary tool history, which is the disclosure the narrow exception was written to avoid.",
+        },
+        method: "GET",
+        mutates: false,
+        path: "/v1/test-sinks/{sinkId}/deliveries/{deliveryRecordId}",
+        principals: ["api-credential", "oauth", "session"],
+        problems: ["invalid_request", "not_found", "state_conflict"],
+        response: testSinkDeliveryBodySchema,
+        scopes: ["endpoints:read"],
+        sessionAuthority: "headers",
+        summary: "Read a test sink delivery",
+        surfaces: ["api", "mock"],
+    },
+    {
+        creates: false,
+        description: "Deletes a sink and every delivery it recorded. The bound callback endpoint is untouched and keeps its signing keys; deliveries sent afterwards find nothing at the url and fail the way an unreachable receiver does.",
+        example: {
+            createdAt: "2026-08-07T15:00:00.000Z",
+            deliveryCount: 3,
+            endpoint: "ep_01h8xyz9k2m4n6p8r0t2v4w6y8",
+            environmentKind: "test",
+            id: "tsk_01h8xyz9k2m4n6p8r0t2v4w6y8",
+            program: { behavior: "success" },
+            project: "proj_01h8xyz9k2m4n6p8r0t2v4w6y8",
+            updatedAt: "2026-08-07T15:04:00.000Z",
+            url: "https://sink.greatwait.dev/__greatwait/test-sinks/tsk_01h8xyz9k2m4n6p8r0t2v4w6y8",
+        },
+        id: "testsinks.delete",
+        idempotent: true,
+        mcp: { destructive: true, kind: "tool", openWorld: false },
+        method: "DELETE",
+        mutates: true,
+        path: "/v1/test-sinks/{sinkId}",
+        principals: ["api-credential", "oauth", "session"],
+        problems: ["invalid_request", "not_found", "state_conflict"],
+        response: testSinkSchema,
+        scopes: ["endpoints:write"],
+        sessionAuthority: "headers",
+        summary: "Delete a test sink",
+        surfaces: ["api", "mock"],
+    },
+    {
+        creates: true,
+        description: "Pins the mock's behavior and clock so an integrator can rehearse success, refusal, retry, timeout, ambiguity, and redelivery deterministically. Mock-only, and never evidence that the real runtime behaves this way.",
+        example: {
+            behavior: "retry",
+            now: "2026-01-01T00:00:00.000Z",
+            scenarioId: "scenario-1",
+        },
+        id: "mock.setScenario",
+        idempotent: false,
+        mcp: {
+            kind: "unavailable",
+            reason: "The contract mock's control plane. An agent handed this would call it against the real service.",
+        },
+        method: "POST",
+        mutates: true,
+        path: "/_contract/scenarios",
+        principals: [],
+        problems: ["invalid_request"],
+        request: mockScenarioRequestSchema,
+        requestExample: { behavior: "retry", failuresBeforeSuccess: 2 },
+        response: mockScenarioResponseSchema,
+        scopes: [],
+        summary: "Set the mock scenario",
+        surfaces: ["mock"],
+    },
+    {
+        creates: true,
+        description: "Issues an API credential bound to one project and environment, with scopes capped by the issuing member's current role. The full secret is in this response and in no other, is not recoverable afterwards, and there is deliberately no reveal endpoint. The value is the sixteen-character display prefix followed immediately by thirty-two more characters; the example below is a visible placeholder rather than that shape, because a realistic credential in a committed file is one the repository's own secret scanner refuses.",
+        example: {
+            createdAt: "2026-07-28T15:00:00.000Z",
+            displayPrefix: "pt_test_a1b2c3d4",
+            environmentKind: "test",
+            id: "ak_01h8xyz9k2m4n6p8r0t2v4w6y8",
+            project: "proj_01h8xyz9k2m4n6p8r0t2v4w6y8",
+            scopes: ["schedules:write"],
+            secret: "pt_test_a1b2c3d4<the-32-character-secret-half-here>",
+            shownOnce: true,
+        },
+        id: "credentials.create",
+        idempotent: false,
+        // The one API-surface operation an agent cannot reach, and the reason is
+        // the route's own: issuance is authenticated by a Clerk session and refuses
+        // an API credential outright, because a key that can mint keys turns one
+        // disclosure into permanent access. MCP carries API credentials and OAuth
+        // tokens and never a session, so a tool here would be a tool that answers
+        // `authentication_required` to every caller. Publishing the exclusion is
+        // the honest version of that, and it is not MCP-only behaviour: it is what
+        // `POST /v1/credentials` already does to the same principals.
+        mcp: {
+            kind: "unavailable",
+            reason: "Issuance is authenticated by a signed-in member. MCP carries API credentials and OAuth tokens, and `POST /v1/credentials` refuses both.",
+        },
+        method: "POST",
+        mutates: true,
+        path: "/v1/credentials",
+        principals: ["session"],
+        // No `test_to_live_escalation`. It was declared here and is structurally
+        // unreachable: the issuer is a human session, whose authority tuple is
+        // *derived from* the environment it asked for, so the held kind and the
+        // requested kind are always equal and `decideEnvironmentIntent` has nothing
+        // to compare. An admin issuing a live credential is ordinary work, not an
+        // escalation. Publishing a refusal the implementation cannot produce is a
+        // contract that overstates what it enforces, which is worse than one that
+        // says less: a client writes a branch that never runs and believes it is
+        // protected. Escalation stays a real refusal wherever a *request* names an
+        // environment. This said "which is W2-02's create-in-live" until W2-02 was
+        // built and found no such thing: a schedule create takes its environment
+        // from the principal too, so no operation on this surface can yet have a
+        // held kind and a requested kind that differ. Whichever story first accepts
+        // an environment as *input* — a migration import is the likely one — is
+        // where the refusal becomes reachable and declarable.
+        problems: ["invalid_request", "not_found"],
+        request: credentialRequestSchema,
+        requestExample: {
+            environmentKind: "test",
+            project: "proj_01h8xyz9k2m4n6p8r0t2v4w6y8",
+            scopes: ["schedules:write"],
+        },
+        response: credentialCreatedSchema,
+        scopes: ["credentials:write"],
+        sessionAuthority: "request-body",
+        summary: "Issue an API credential",
+        surfaces: ["api", "mock"],
+    },
+    {
+        creates: false,
+        description: "Lists the credentials issued for the caller's own project and environment, oldest first, one page at a time. The authority tuple comes from the verified principal, so there is no parameter that could name another project — a listing is the caller's own book or nothing. Revoked and rotated credentials stay in the listing and carry the fields that say so; a credential nobody can see is a credential nobody can audit. `limit` is bounded by the contract and `cursor` is the opaque value the previous page returned. No page carries a secret: the item is the read shape, which has no field one could be put in.",
+        example: {
+            data: [
+                {
+                    createdAt: "2026-07-28T15:00:00.000Z",
+                    displayPrefix: "pt_test_a1b2c3d4",
+                    environmentKind: "test",
+                    id: "ak_01h8xyz9k2m4n6p8r0t2v4w6y8",
+                    lastUsedAt: "2026-07-28T15:04:00.000Z",
+                    project: "proj_01h8xyz9k2m4n6p8r0t2v4w6y8",
+                    scopes: ["schedules:write"],
+                },
+            ],
+            // Authoritative rather than projected: credentials are read from the row
+            // that owns them, not from a cross-partition projection. The
+            // discriminator is on every page so a client never has to know which
+            // collections lag.
+            freshness: { kind: "authoritative" },
+            // Opaque. Clients pass back exactly what they were given, which is why
+            // this is the whole value rather than an elided one — a truncated example
+            // teaches a reader that a cursor has readable parts.
+            nextCursor: "eyJhIjoxNzg1MjUwODAwMDAwLCJpIjoiYWtfMDFoOHh5ejlrMm00bjZwOHIwdDJ2NHc2eTgiLCJrIjoiOTUxMzU0NmYifQ",
+        },
+        id: "credentials.list",
+        idempotent: true,
+        mcp: { destructive: false, kind: "tool", openWorld: false },
+        method: "GET",
+        mutates: false,
+        path: "/v1/credentials",
+        principals: ["api-credential", "oauth", "session"],
+        // `invalid_request` covers a limit outside the contract's bounds and a
+        // cursor this listing did not issue. There is no `not_found`: the
+        // collection is addressed by the principal, so it always exists and is
+        // sometimes empty.
+        problems: ["invalid_request"],
+        query: pageRequestSchema,
+        response: credentialPageSchema,
+        scopes: ["credentials:read"],
+        sessionAuthority: "headers",
+        summary: "List API credentials",
+        surfaces: ["api", "mock"],
+    },
+    {
+        creates: false,
+        description: "Lists the projects in the signed-in member's organization that they may act in, with the environment kinds each one has. This is what a browser asks before it can address anything else: an API credential and an OAuth token each carry one project intrinsically, but a member belongs to an organization and chooses. Archived and deleted projects are omitted, because a member cannot act in one. The result is a display aid rather than an authorization control — naming a project on a later request re-resolves it against the member's own organization, and a project that is not theirs answers exactly as one that does not exist.",
+        example: {
+            data: [
+                {
+                    environmentKinds: ["test", "live"],
+                    id: "proj_01h8xyz9k2m4n6p8r0t2v4w6y8",
+                    name: "Billing reminders",
+                },
+            ],
+        },
+        id: "projects.list",
+        idempotent: true,
+        mcp: {
+            kind: "unavailable",
+            reason: "Enumerating an organization's projects is a signed-in member's question. MCP carries API credentials and OAuth tokens, whose authority already is one project, and this operation accepts neither.",
+        },
+        method: "GET",
+        mutates: false,
+        path: "/v1/projects",
+        principals: ["session"],
+        // No `not_found`: the collection is the member's own organization, so it
+        // always exists and is sometimes empty. No paging, so no `invalid_request`.
+        problems: [],
+        response: projectListSchema,
+        scopes: ["projects:read"],
+        sessionAuthority: "organization",
+        summary: "List the member's projects",
+        surfaces: ["api", "mock"],
+    },
+    {
+        creates: true,
+        description: "Creates a project in the signed-in member's organization, with both of its environments. This is the first call a new customer makes: an organization has no project until somebody makes one, and every other operation on this surface acts inside one. The `test` and `live` environments are provisioned with it in a single transaction rather than asked for, so a project is never observable in a half-provisioned state. The organization comes from the verified session and is never read from the request — a member who belongs to one organization cannot create a project in another. `PROJECT_LIST_LIMIT` bounds how many an organization may hold, and it is the same ceiling the listing publishes: a create that would take an organization past a list it can no longer return is refused rather than silently truncating a later read.",
+        example: {
+            environmentKinds: ["test", "live"],
+            id: "proj_01h8xyz9k2m4n6p8r0t2v4w6y8",
+            name: "Billing reminders",
+        },
+        id: "projects.create",
+        // Not idempotent, and it cannot be made so here: repeating this makes a
+        // second project with the same name, because a name is a label rather than
+        // an identifier — `projectNameSchema` says so, and non-uniqueness is what
+        // lets somebody rename one without breaking a caller's URLs. No route on
+        // this Worker reads an idempotency key for it, so declaring `true` would
+        // publish a promise nothing keeps.
+        idempotent: false,
+        // Withheld from MCP for `projects.list`'s reason and one of its own. The
+        // shared half: this operation accepts only a signed-in member, and MCP
+        // carries API credentials and OAuth tokens. The half that is this
+        // operation's alone: a credential's authority *is* one project, so an agent
+        // that could create a second could not then act in it — the tool would
+        // succeed and leave the caller holding an identifier nothing they carry can
+        // address.
+        mcp: {
+            kind: "unavailable",
+            reason: "Creating a project is a signed-in member's act. MCP carries API credentials and OAuth tokens, whose authority already is one project — so this operation accepts neither, and an agent that somehow created one could not act in it.",
+        },
+        method: "POST",
+        mutates: true,
+        path: "/v1/projects",
+        principals: ["session"],
+        // `invalid_request` covers a blank or over-long name. `plan_limit_reached`
+        // is the organization ceiling, the same code `endpoints.create` uses for
+        // the same shape of refusal. There is no `not_found`: the organization is
+        // the member's own and is created on first use, so it always exists by the
+        // time the project is written.
+        problems: ["invalid_request", "plan_limit_reached"],
+        request: projectCreateRequestSchema,
+        requestExample: { name: "Billing reminders" },
+        response: projectSummarySchema,
+        scopes: ["projects:write"],
+        sessionAuthority: "organization",
+        summary: "Create a project",
+        surfaces: ["api", "mock"],
+    },
+    {
+        creates: false,
+        description: "Lists the applications this member has connected to their own account, newest first, across every project in their organization — because a person connects an application, not a project. Revoked connections stay in the listing with the instant and the reason they ended: a connection nobody can see is one nobody can audit. This is a signed-in member's view of their own delegations. An application holding a grant cannot read it, which is why the operation accepts no API credential and no access token, and why it is on no agent's tool list.",
+        example: {
+            data: [
+                {
+                    client: { id: "oc_01h8xyz9k2m4n6p8r0t2v4w6y8", name: "Flow XO" },
+                    createdAt: "2026-08-14T11:00:00.000Z",
+                    environmentKind: "test",
+                    id: "og_01h8xyz9k2m4n6p8r0t2v4w6y8",
+                    lastUsedAt: "2026-08-15T09:12:00.000Z",
+                    project: "proj_01h8xyz9k2m4n6p8r0t2v4w6y8",
+                    scopes: ["schedules:read", "schedules:write"],
+                    status: "active",
+                },
+            ],
+        },
+        id: "grants.list",
+        idempotent: true,
+        // **Withheld, and the reason is what the surface is for.** An application
+        // authenticates to MCP with the very grant this operation enumerates. A
+        // tool here would let one connected application read every other
+        // application the member has connected, and the revoke beside it would let
+        // it disconnect them. That is not a narrower scope's problem — it is why
+        // the operation accepts only a session.
+        mcp: {
+            kind: "unavailable",
+            reason: "A member's own connected applications. MCP carries API credentials and OAuth tokens, and an application holding a grant must not be able to enumerate its rivals — still less disconnect them — so this operation accepts neither.",
+        },
+        method: "GET",
+        mutates: false,
+        path: "/v1/grants",
+        principals: ["session"],
+        // No paging and no `not_found`: the collection is the member's own and is
+        // sometimes empty. Its size is how many applications one person has
+        // connected, which is not a number a cursor helps with.
+        problems: [],
+        response: oauthGrantListSchema,
+        scopes: ["grants:read"],
+        sessionAuthority: "member",
+        summary: "List the member's connected applications",
+        surfaces: ["api", "mock"],
+    },
+    {
+        creates: false,
+        description: "Disconnects one application, ending every token that grant ever issued — the access tokens and the refresh token together. The grant stays readable afterwards with the instant and the reason it ended. Only the member who granted it can disconnect it, and a grant belonging to somebody else answers exactly as one that does not exist.",
+        example: {
+            grant: {
+                client: { id: "oc_01h8xyz9k2m4n6p8r0t2v4w6y8", name: "Flow XO" },
+                createdAt: "2026-08-14T11:00:00.000Z",
+                environmentKind: "test",
+                id: "og_01h8xyz9k2m4n6p8r0t2v4w6y8",
+                project: "proj_01h8xyz9k2m4n6p8r0t2v4w6y8",
+                revocationReason: "member-revoked",
+                revokedAt: "2026-08-15T10:00:00.000Z",
+                scopes: ["schedules:read", "schedules:write"],
+                status: "revoked",
+            },
+        },
+        id: "grants.revoke",
+        // Repeating it is safe: the grant is already revoked, and the second call
+        // reports the first one's instant rather than moving it. That is
+        // `credentials.revoke`'s shape, for the same reason.
+        idempotent: true,
+        mcp: {
+            kind: "unavailable",
+            reason: "Disconnecting an application is the member's own act. MCP carries API credentials and OAuth tokens, and an application able to disconnect a grant could disconnect the ones belonging to every other application the member has connected.",
+        },
+        method: "DELETE",
+        mutates: true,
+        path: "/v1/grants/{grantId}",
+        principals: ["session"],
+        problems: ["not_found"],
+        response: oauthGrantRevokedSchema,
+        scopes: ["grants:write"],
+        sessionAuthority: "member",
+        summary: "Disconnect an application",
+        surfaces: ["api", "mock"],
+    },
+    {
+        creates: true,
+        description: "Replaces a credential with a new one and gives the original a deadline, so consumers can pick up the new secret before the old stops working. The replacement is a new credential with its own identifier and the same authority and scopes; the original keeps working until it expires, then refuses with `credential_expired` rather than `credential_revoked`. `overlapSeconds` may only shorten the window — the default is also the maximum — and zero retires the original immediately. The new secret is in this response and in no other.",
+        example: {
+            credential: {
+                createdAt: "2026-07-28T15:00:00.000Z",
+                displayPrefix: "pt_test_e5f6g7h8",
+                environmentKind: "test",
+                id: "ak_01h8xyz9k2m4n6p8r0t2v4w6y9",
+                project: "proj_01h8xyz9k2m4n6p8r0t2v4w6y8",
+                scopes: ["schedules:write"],
+                secret: "pt_test_e5f6g7h8<the-32-character-secret-half-here>",
+                shownOnce: true,
+            },
+            retired: {
+                createdAt: "2026-07-28T15:00:00.000Z",
+                displayPrefix: "pt_test_a1b2c3d4",
+                environmentKind: "test",
+                expiresAt: "2026-07-29T15:00:00.000Z",
+                id: "ak_01h8xyz9k2m4n6p8r0t2v4w6y8",
+                project: "proj_01h8xyz9k2m4n6p8r0t2v4w6y8",
+                scopes: ["schedules:write"],
+                supersededBy: "ak_01h8xyz9k2m4n6p8r0t2v4w6y9",
+            },
+        },
+        id: "credentials.rotate",
+        // Destructive: the original credential is given a deadline it did not have,
+        // and whatever is still using it stops working when that deadline passes.
+        // The new secret is in the result, which is architecture section 9's "secrets
+        // are one-time results" — it is in this response and in no other, and no MCP
+        // read can recover it afterwards.
+        mcp: { destructive: true, kind: "tool", openWorld: false },
+        // Not idempotent, and it cannot be made so here: repeating this mints a
+        // second replacement and retires the first. `operations.ts` says a write
+        // qualifies only by carrying an idempotency key, and no route on this
+        // Worker reads one yet — declaring `true` would publish a promise nothing
+        // keeps.
+        idempotent: false,
+        method: "POST",
+        mutates: true,
+        path: "/v1/credentials/{credentialId}/rotate",
+        conditionalScopes: ["credentials:administer"],
+        principals: ["api-credential", "oauth", "session"],
+        problems: ["invalid_request", "not_found", "scope_missing"],
+        request: credentialRotationRequestSchema,
+        requestExample: { overlapSeconds: 3600 },
+        response: credentialRotatedSchema,
+        scopes: ["credentials:write"],
+        sessionAuthority: "headers",
+        summary: "Rotate an API credential",
+        surfaces: ["api", "mock"],
+    },
+    {
+        creates: false,
+        description: "Revokes a credential immediately, with no overlap. The credential stops verifying on the next request and refuses with `credential_revoked`. The row survives its revocation so the credential's history remains answerable, and revoking a credential that is already revoked reports the original revocation rather than moving it. A credential belonging to another project is indistinguishable from one that does not exist.",
+        example: {
+            credential: {
+                createdAt: "2026-07-28T15:00:00.000Z",
+                displayPrefix: "pt_test_a1b2c3d4",
+                environmentKind: "test",
+                id: "ak_01h8xyz9k2m4n6p8r0t2v4w6y8",
+                project: "proj_01h8xyz9k2m4n6p8r0t2v4w6y8",
+                revokedAt: "2026-07-28T16:00:00.000Z",
+                scopes: ["schedules:write"],
+            },
+        },
+        id: "credentials.revoke",
+        mcp: { destructive: true, kind: "tool", openWorld: false },
+        // Repeating this leaves the same credential revoked at the same instant, so
+        // it is idempotent in the sense the field means — no key required, because
+        // there is no second effect to suppress.
+        idempotent: true,
+        method: "DELETE",
+        mutates: true,
+        path: "/v1/credentials/{credentialId}",
+        conditionalScopes: ["credentials:administer"],
+        principals: ["api-credential", "oauth", "session"],
+        problems: ["invalid_request", "not_found", "scope_missing"],
+        response: credentialRevokedSchema,
+        scopes: ["credentials:write"],
+        sessionAuthority: "headers",
+        summary: "Revoke an API credential",
+        surfaces: ["api", "mock"],
+    },
+    {
+        creates: true,
+        description: "Creates a schedule and returns it together with its first planned occurrence. Give exactly one of `at`, `delaySeconds`, `everySeconds` and `cron`. An optional `partitionKey` selects a fairness lane inside this project and environment; it is fixed after create. Add a verified `endpoint` to deliver each occurrence there; optional JSON `data` is encrypted before PostgreSQL persistence and is placed in the signed callback, never returned by schedule reads. `at` and `delaySeconds` fire once; a delay is converted to an absolute instant when the request is accepted, so a schedule created either way reads back the same afterwards. `everySeconds` is a fixed duration and its first occurrence falls one interval after acceptance — it stays the same length across a daylight-saving change, and takes no timezone for that reason. `cron` is a wall clock: it is read against the IANA `timeZone` sent with it, `UTC` when none is, and the first occurrence is the first instant the expression names after acceptance. Where the clocks go forward and the wall time named does not exist that day, the occurrence falls at the first instant after the gap; where they go back and it happens twice, it falls once, at the earlier of the two. A recurring schedule is materialized one occurrence at a time: the next one is planned once the current one is due, so a read always shows one occurrence still to come. The organization, project and environment come from the verified principal; a body cannot name them, and the endpoint must belong to the same tuple, so a credential issued for one project can only ever create schedules in that project. Send an `Idempotency-Key` to make a retry safe: the identical request returns the schedule that key already created, marked `Idempotency-Replayed: true`, and creates nothing further; the same key with a different request is refused `idempotency_key_reused`. A replay reports the schedule **as it stands now**, not a frozen copy of the first response — if it was paused in between, the replay says so.",
+        example: {
+            occurrence: {
+                attemptCount: 0,
+                generation: 1,
+                id: "occ_01h8xyz9k2m4n6p8r0t2v4w6y8",
+                plannedFor: "2026-07-28T15:00:00.000Z",
+                schedule: "sch_01h8xyz9k2m4n6p8r0t2v4w6y8",
+                sequence: 1,
+                state: "planned",
+            },
+            schedule: {
+                createdAt: "2026-07-28T14:59:00.000Z",
+                endpoint: "ep_01h8xyz9k2m4n6p8r0t2v4w6y8",
+                generation: 1,
+                id: "sch_01h8xyz9k2m4n6p8r0t2v4w6y8",
+                latencyClass: "realtime",
+                partitionKey: "campaign.spring",
+                recurrence: { kind: "at" },
+                status: "active",
+                updatedAt: "2026-07-28T14:59:00.000Z",
+                version: 1,
+            },
+        },
+        id: "schedules.create",
+        // Additive: it brings a schedule into existence and takes nothing away.
+        // A callback schedule causes a future request to the verified external
+        // endpoint. It does not destructively modify that system, but it does act
+        // beyond Greatwait, so MCP clients must receive the open-world hint.
+        mcp: { destructive: false, kind: "tool", openWorld: true },
+        // False even though this operation reads `Idempotency-Key`, because the
+        // header is optional and this flag is what a client reads before deciding
+        // whether a blind retry is safe. It is not: a retry without the key creates
+        // a second schedule. What says the protection is available is
+        // `requestHeaders`, which publishes the key rather than promising it was
+        // used.
+        idempotent: false,
+        method: "POST",
+        mutates: true,
+        path: "/v1/schedules",
+        principals: ["api-credential", "oauth", "session"],
+        problems: [
+            // **Reachable in every deployment, and undeclared until W9-03.** The
+            // route refuses here when the endpoint's status is not one this
+            // deployment will send to — under the default `not-required` ownership
+            // policy that still covers a `disabled` destination, and under
+            // `required` it covers a `pending` one as well. An operation that can
+            // refuse for a code it never mentions is a document that lies, and a
+            // published quickstart could not tell a reader what to do about a
+            // refusal the contract said was impossible.
+            "endpoint_unverified",
+            "idempotency_key_reused",
+            "invalid_request",
+            "not_found",
+            // The organization ceiling, the same code and the same shape
+            // `projects.create` and `endpoints.create` use. A plan may bound the
+            // live schedules an organization holds, the distinct partition keys it
+            // has live, and how large a `data` body it may carry; all three refuse
+            // here rather than truncating, because a schedule created without the
+            // body the caller sent is not the schedule they asked for.
+            "plan_limit_reached",
+            "service_unavailable",
+        ],
+        request: scheduleRequestSchema,
+        requestExample: {
+            cron: "0 9 * * 1-5",
+            data: { report: "daily" },
+            endpoint: "ep_01h8xyz9k2m4n6p8r0t2v4w6y8",
+            partitionKey: "campaign.spring",
+            timeZone: "Europe/London",
+        },
+        requestHeaders: idempotencyRequestHeaderSchema,
+        response: scheduleViewSchema,
+        responseHeaders: replayedResponseHeaderSchema,
+        scopes: ["schedules:write"],
+        sessionAuthority: "headers",
+        summary: "Create a schedule",
+        surfaces: ["api", "mock"],
+    },
+    {
+        creates: false,
+        description: "Reads one schedule and its next occurrence from the partition that owns it. A schedule belonging to another organization, project or environment answers not_found rather than a refusal that would confirm it exists. The response carries the schedule's version as a strong ETag; send it back in `If-Match` to make a later write conditional on nothing having changed in between.",
+        example: {
+            occurrence: {
+                attemptCount: 0,
+                generation: 1,
+                id: "occ_01h8xyz9k2m4n6p8r0t2v4w6y8",
+                plannedFor: "2026-07-28T15:00:00.000Z",
+                schedule: "sch_01h8xyz9k2m4n6p8r0t2v4w6y8",
+                sequence: 1,
+                state: "planned",
+            },
+            schedule: {
+                createdAt: "2026-07-28T14:59:00.000Z",
+                endpoint: "ep_01h8xyz9k2m4n6p8r0t2v4w6y8",
+                generation: 1,
+                id: "sch_01h8xyz9k2m4n6p8r0t2v4w6y8",
+                latencyClass: "realtime",
+                partitionKey: "campaign.spring",
+                recurrence: { kind: "at" },
+                status: "active",
+                updatedAt: "2026-07-28T14:59:00.000Z",
+                version: 1,
+            },
+        },
+        id: "schedules.read",
+        idempotent: true,
+        mcp: { destructive: false, kind: "tool", openWorld: false },
+        method: "GET",
+        mutates: false,
+        path: "/v1/schedules/{scheduleId}",
+        principals: ["api-credential", "oauth", "session"],
+        problems: ["invalid_request", "not_found"],
+        response: scheduleViewSchema,
+        responseHeaders: versionResponseHeaderSchema,
+        scopes: ["schedules:read"],
+        sessionAuthority: "headers",
+        summary: "Read a schedule",
+        surfaces: ["api", "mock"],
+    },
+    {
+        creates: false,
+        description: "Lists the caller's own schedules, oldest first, one page at a time. Archived schedules are left out: archiving is how a schedule leaves the working set, and a listing that still carried them would make the operation pointless. Items are schedules rather than schedules-with-occurrences, because a cross-partition listing is served from a projection that holds a summary; read a schedule to get its authoritative next occurrence. Every page states whether it is authoritative or projected.",
+        example: {
+            data: [
+                {
+                    createdAt: "2026-07-28T14:59:00.000Z",
+                    endpoint: "ep_01h8xyz9k2m4n6p8r0t2v4w6y8",
+                    generation: 1,
+                    id: "sch_01h8xyz9k2m4n6p8r0t2v4w6y8",
+                    latencyClass: "realtime",
+                    recurrence: { kind: "at" },
+                    status: "active",
+                    updatedAt: "2026-07-28T14:59:00.000Z",
+                    version: 1,
+                },
+            ],
+            // `projected` since W2-06 served this listing from the control-plane
+            // directory. `asOf` is the instant the projection was last known to hold
+            // everything every partition had handed over, and `lagSeconds` is how long
+            // ago that was — so a page states how far behind it may be rather than
+            // implying it is current.
+            freshness: {
+                asOf: "2026-07-28T15:00:00.000Z",
+                kind: "projected",
+                lagSeconds: 0,
+            },
+            nextCursor: "eyJhIjoxNzg1MjUwODAwMDAwLCJpIjoic2NoXzAxaDh4eXo5azJtNG42cDhyMHQydjR3Nnk4IiwiayI6Ijk1MTM1NDZmIn0",
+        },
+        id: "schedules.list",
+        idempotent: true,
+        mcp: { destructive: false, kind: "tool", openWorld: false },
+        method: "GET",
+        mutates: false,
+        path: "/v1/schedules",
+        principals: ["api-credential", "oauth", "session"],
+        problems: ["invalid_request"],
+        query: pageRequestSchema,
+        response: schedulePageSchema,
+        scopes: ["schedules:read"],
+        sessionAuthority: "headers",
+        summary: "List schedules",
+        surfaces: ["api", "mock"],
+    },
+    {
+        creates: false,
+        description: "Counts the occurrences this project and environment expect to fire, in epoch-aligned time buckets, with a latency-class split on every bucket and an optional customer partition-key breakdown. A recurring series contributes every instant it fires inside the window rather than only its next one, and `nextFireCount` reports how many of a bucket's occurrences are a schedule's next firing. The answer states its own freshness and is refused rather than shortened when a partition cannot complete it. It carries counts only: no schedule identifier, callback destination, payload or endpoint detail has a field in the response.",
+        example: {
+            buckets: [
+                {
+                    byLatencyClass: { bulk: 12, realtime: 3 },
+                    byPartitionKey: { "campaign.spring": 9, "campaign.winter": 4 },
+                    count: 15,
+                    nextFireCount: 4,
+                    otherPartitionKeyCount: 2,
+                    start: "2026-07-28T15:00:00.000Z",
+                },
+            ],
+            freshness: {
+                asOf: "2026-07-28T14:58:30.000Z",
+                kind: "projected",
+                lagSeconds: 90,
+            },
+            window: {
+                bucketSeconds: 1800,
+                from: "2026-07-28T15:00:00.000Z",
+                to: "2026-07-29T15:00:00.000Z",
+            },
+        },
+        id: "forecast.read",
+        idempotent: true,
+        mcp: { destructive: false, kind: "tool", openWorld: false },
+        method: "GET",
+        mutates: false,
+        path: "/v1/forecast",
+        principals: ["api-credential", "oauth", "session"],
+        problems: ["invalid_request"],
+        query: forecastRequestSchema,
+        response: forecastSchema,
+        scopes: ["forecast:read"],
+        sessionAuthority: "headers",
+        summary: "Forecast upcoming occurrences",
+        surfaces: ["api", "mock"],
+    },
+    {
+        creates: false,
+        description: "What this project was charged for, by UTC day, from the authoritative scheduling model. One terminal occurrence is one billable unit however many attempts it took, so a schedule that failed four times and succeeded on the fifth appears here once; the attempts it cost are on that occurrence's own attempt history. Days with no billable occurrence are absent rather than zero, and the window states which days the answer covers. `from` and `to` are snapped outward to UTC midnight, so an answer always covers whole days.",
+        example: {
+            days: [
+                {
+                    billableOccurrences: 42,
+                    byTerminalState: { succeeded: 40, terminal_failed: 2 },
+                    start: "2026-07-28T00:00:00.000Z",
+                },
+            ],
+            freshness: { kind: "authoritative" },
+            totalBillableOccurrences: 42,
+            window: {
+                from: "2026-07-28T00:00:00.000Z",
+                to: "2026-07-29T00:00:00.000Z",
+            },
+        },
+        id: "usage.read",
+        idempotent: true,
+        mcp: { destructive: false, kind: "tool", openWorld: false },
+        method: "GET",
+        mutates: false,
+        path: "/v1/usage",
+        principals: ["api-credential", "oauth", "session"],
+        problems: ["invalid_request"],
+        query: usageRequestSchema,
+        response: usageSchema,
+        scopes: ["usage:read"],
+        sessionAuthority: "headers",
+        summary: "Read billable usage by day",
+        surfaces: ["api", "mock"],
+    },
+    {
+        creates: false,
+        description: "The same forecast in the window shape the legacy scheduler's autoscaler already parses, published under a dated version so a consumer can pin it. It exists for one migration and is expected to be withdrawn once that migration completes; `forecast.read` is the shape this product publishes. `byTenant` is the customer partition-key breakdown under its legacy name, and `count` is always the bucket total rather than the named subtotal.",
+        example: {
+            bucketSeconds: 600,
+            buckets: [
+                {
+                    byTenant: { "campaign.spring": 9, "campaign.winter": 4 },
+                    count: 15,
+                    nextFireCount: 4,
+                    otherCount: 2,
+                    start: "2026-07-28T15:00:00.000Z",
+                },
+            ],
+            freshness: {
+                asOf: "2026-07-28T14:58:30.000Z",
+                kind: "projected",
+                lagSeconds: 90,
+            },
+            version: FORECAST_WINDOW_VERSION,
+        },
+        id: "forecast.windows",
+        idempotent: true,
+        // Withheld from MCP rather than published as a tool. It is a compatibility
+        // projection for one migrating consumer, and `forecast.read` is the same
+        // data in the shape this product intends to keep — so putting it in an
+        // agent's tool list would invite an agent to build against a shape that is
+        // scheduled for removal, which is the opposite of what a tool list is for.
+        mcp: {
+            kind: "unavailable",
+            reason: "A transitional shape for the autoscaler migration, scheduled for withdrawal once W6-02 has cut over. forecast.read is the same data in the shape this product publishes, and it is the tool an agent should reach for.",
+        },
+        method: "GET",
+        mutates: false,
+        path: "/v1/forecast/windows",
+        principals: ["api-credential", "oauth", "session"],
+        problems: ["invalid_request"],
+        query: forecastRequestSchema,
+        response: forecastWindowsSchema,
+        scopes: ["forecast:read"],
+        sessionAuthority: "headers",
+        summary: "Forecast in the transitional window shape",
+        surfaces: ["api", "mock"],
+    },
+    {
+        creates: false,
+        description: "Lists the retained occurrences of one schedule from its authoritative Scheduler Partition, ordered by durable creation instant and occurrence identifier so tied timestamps never duplicate or omit a row. The cursor is opaque and scoped to the verified principal's organization, project and environment. Each item is metadata only: callback payloads, destinations, response bodies and signing material have no field in the response.",
+        example: {
+            data: [
+                {
+                    attemptCount: 1,
+                    generation: 1,
+                    id: "occ_01h8xyz9k2m4n6p8r0t2v4w6y8",
+                    plannedFor: "2026-07-28T15:00:00.000Z",
+                    schedule: "sch_01h8xyz9k2m4n6p8r0t2v4w6y8",
+                    sequence: 1,
+                    state: "retry_wait",
+                },
+            ],
+            freshness: { kind: "authoritative" },
+            nextCursor: "eyJhIjoxNzg1MjUwODAwMDAwLCJpIjoib2NjXzAxaDh4eXo5azJtNG42cDhyMHQydjR3Nnk4IiwiayI6Ijk1MTM1NDZmIn0",
+        },
+        id: "occurrences.list",
+        idempotent: true,
+        mcp: { destructive: false, kind: "tool", openWorld: false },
+        method: "GET",
+        mutates: false,
+        path: "/v1/schedules/{scheduleId}/occurrences",
+        principals: ["api-credential", "oauth", "session"],
+        problems: ["invalid_request", "not_found"],
+        query: pageRequestSchema,
+        response: occurrencePageSchema,
+        scopes: ["occurrences:read"],
+        sessionAuthority: "headers",
+        summary: "List retained occurrences",
+        surfaces: ["api", "mock"],
+    },
+    {
+        creates: false,
+        description: "Reads one retained occurrence from the Scheduler Partition that owns its schedule. The response explicitly states that it is authoritative; a stale D1 directory or schedule projection is used only to find the partition and never as occurrence truth. An identifier outside the verified principal's organization, project or environment is indistinguishable from an absent occurrence.",
+        example: {
+            freshness: { kind: "authoritative" },
+            occurrence: {
+                attemptCount: 2,
+                generation: 1,
+                id: "occ_01h8xyz9k2m4n6p8r0t2v4w6y8",
+                plannedFor: "2026-07-28T15:00:00.000Z",
+                schedule: "sch_01h8xyz9k2m4n6p8r0t2v4w6y8",
+                sequence: 1,
+                settledAt: "2026-07-28T15:02:00.000Z",
+                state: "terminal_failed",
+            },
+        },
+        id: "occurrences.read",
+        idempotent: true,
+        mcp: { destructive: false, kind: "tool", openWorld: false },
+        method: "GET",
+        mutates: false,
+        path: "/v1/schedules/{scheduleId}/occurrences/{occurrenceId}",
+        principals: ["api-credential", "oauth", "session"],
+        problems: ["invalid_request", "not_found"],
+        response: occurrenceViewSchema,
+        scopes: ["occurrences:read"],
+        sessionAuthority: "headers",
+        summary: "Read an occurrence",
+        surfaces: ["api", "mock"],
+    },
+    {
+        creates: false,
+        description: "Lists the immutable attempts retained under one occurrence, ordered by start instant and attempt identifier so equal timestamps have a stable position. The owning Scheduler Partition is authoritative and every page says so. Results expose only bounded outcome, response-status, duration, diagnostic, remediation and redelivery-cause metadata; callback payloads, response bodies, destinations, signing material, secrets and transport traces are structurally absent.",
+        example: {
+            data: [
+                {
+                    attemptNumber: 1,
+                    classifiedAt: "2026-07-28T15:00:00.071Z",
+                    delivery: "dlv_01h8xyz9k2m4n6p8r0t2v4w6y8",
+                    diagnostic: "http_retryable",
+                    durationMs: 71,
+                    id: "att_01h8xyz9k2m4n6p8r0t2v4w6y8",
+                    occurrence: "occ_01h8xyz9k2m4n6p8r0t2v4w6y8",
+                    remediation: "review_retry_policy",
+                    responseStatus: 503,
+                    startedAt: "2026-07-28T15:00:00.000Z",
+                    state: "retryable_failure",
+                    trigger: { kind: "automatic" },
+                },
+            ],
+            freshness: { kind: "authoritative" },
+            nextCursor: "eyJhIjoxNzg1MjUwODAwMDAwLCJpIjoiYXR0XzAxaDh4eXo5azJtNG42cDhyMHQydjR3Nnk4IiwiayI6Ijk1MTM1NDZmIn0",
+        },
+        id: "attempts.list",
+        idempotent: true,
+        mcp: { destructive: false, kind: "tool", openWorld: false },
+        method: "GET",
+        mutates: false,
+        path: "/v1/schedules/{scheduleId}/occurrences/{occurrenceId}/attempts",
+        principals: ["api-credential", "oauth", "session"],
+        problems: ["invalid_request", "not_found"],
+        query: pageRequestSchema,
+        response: attemptPageSchema,
+        scopes: ["occurrences:read"],
+        sessionAuthority: "headers",
+        summary: "List delivery attempts",
+        surfaces: ["api", "mock"],
+    },
+    {
+        creates: false,
+        description: "Reads one immutable delivery attempt from its occurrence's authoritative Scheduler Partition. Ambiguous means the receiver may have acted and is never rewritten into certainty without durable result evidence. The bounded response omits callback payloads, response bodies, destinations, signing material, secrets and raw transport failures by construction.",
+        example: {
+            attempt: {
+                attemptNumber: 2,
+                classifiedAt: "2026-07-28T15:02:00.000Z",
+                delivery: "dlv_11h8xyz9k2m4n6p8r0t2v4w6y8",
+                diagnostic: "network_ambiguous",
+                durationMs: 10_000,
+                id: "att_11h8xyz9k2m4n6p8r0t2v4w6y8",
+                occurrence: "occ_01h8xyz9k2m4n6p8r0t2v4w6y8",
+                remediation: "review_before_redelivery",
+                startedAt: "2026-07-28T15:01:50.000Z",
+                state: "ambiguous",
+                trigger: { kind: "automatic" },
+            },
+            freshness: { kind: "authoritative" },
+        },
+        id: "attempts.read",
+        idempotent: true,
+        mcp: { destructive: false, kind: "tool", openWorld: false },
+        method: "GET",
+        mutates: false,
+        path: "/v1/schedules/{scheduleId}/occurrences/{occurrenceId}/attempts/{attemptId}",
+        principals: ["api-credential", "oauth", "session"],
+        problems: ["invalid_request", "not_found"],
+        response: attemptViewSchema,
+        scopes: ["occurrences:read"],
+        sessionAuthority: "headers",
+        summary: "Read a delivery attempt",
+        surfaces: ["api", "mock"],
+    },
+    {
+        creates: true,
+        description: "Creates one new immutable attempt under the same retained terminal occurrence and dispatches it through the ordinary delivery boundary. The required Idempotency-Key makes an identical replay converge on the same attempt and conflicting reuse is refused. The new attempt names the retained attempt that caused the redelivery; no earlier identity or outcome is changed. MCP marks this outbound mutation for explicit approval even though it is non-destructive.",
+        example: {
+            attempt: {
+                attemptNumber: 3,
+                delivery: "dlv_21h8xyz9k2m4n6p8r0t2v4w6y8",
+                id: "att_21h8xyz9k2m4n6p8r0t2v4w6y8",
+                occurrence: "occ_01h8xyz9k2m4n6p8r0t2v4w6y8",
+                startedAt: "2026-07-28T15:05:00.000Z",
+                trigger: {
+                    kind: "redelivery",
+                    sourceAttemptId: "att_11h8xyz9k2m4n6p8r0t2v4w6y8",
+                },
+            },
+            freshness: { kind: "authoritative" },
+        },
+        id: "occurrences.redeliver",
+        idempotent: true,
+        mcp: { destructive: false, kind: "tool", openWorld: true },
+        method: "POST",
+        mutates: true,
+        path: "/v1/schedules/{scheduleId}/occurrences/{occurrenceId}/redeliver",
+        principals: ["api-credential", "oauth", "session"],
+        problems: [
+            "idempotency_key_reused",
+            "invalid_request",
+            "not_found",
+            "service_unavailable",
+            "state_conflict",
+        ],
+        requestHeaders: requiredIdempotencyRequestHeaderSchema,
+        response: attemptViewSchema,
+        responseHeaders: idempotencyReplayResponseHeaderSchema,
+        scopes: ["occurrences:redeliver"],
+        sessionAuthority: "headers",
+        summary: "Redeliver an occurrence",
+        surfaces: ["api", "mock"],
+    },
+    {
+        creates: false,
+        description: "Replaces a schedule's definition, starting a new generation. Takes the same four ways of saying when as a create, so a one-shot can be replaced by a recurring definition and the other way round. An omitted callback endpoint/data pair preserves the stored callback; sending `data` alone replaces the encrypted data for the current endpoint, and sending `endpoint` selects a verified endpoint in the same authority tuple. The occurrence planned under the old definition is settled `skipped_stale` and can never fire unless it was already in flight, in which case its immutable attempt is allowed to settle honestly; a fresh occurrence is planned under the new definition, and the old definition's series stops advancing. Send `If-Match` with the version you read to make this conditional; without it the replace is unconditional and the last writer wins. A cancelled or completed schedule cannot be replaced. `partitionKey` is fixed when the schedule is created: omit it to preserve the stored value or echo that exact value in a GET → modify → PUT flow. Adding, changing, or clearing it is refused as `invalid_request` with `/partitionKey` identified. `latencyClass` remains derived from the replacement recurrence when the caller omits it.",
+        example: {
+            occurrence: {
+                attemptCount: 0,
+                generation: 2,
+                id: "occ_01h8xyz9k2m4n6p8r0t2v4w6y9",
+                plannedFor: "2026-07-28T16:00:00.000Z",
+                schedule: "sch_01h8xyz9k2m4n6p8r0t2v4w6y8",
+                sequence: 1,
+                state: "planned",
+            },
+            schedule: {
+                createdAt: "2026-07-28T14:59:00.000Z",
+                endpoint: "ep_01h8xyz9k2m4n6p8r0t2v4w6y8",
+                generation: 2,
+                id: "sch_01h8xyz9k2m4n6p8r0t2v4w6y8",
+                latencyClass: "realtime",
+                partitionKey: "campaign.spring",
+                recurrence: { kind: "at" },
+                status: "active",
+                updatedAt: "2026-07-28T15:10:00.000Z",
+                version: 2,
+            },
+        },
+        id: "schedules.replace",
+        idempotent: true,
+        // Destructive: the occurrence planned under the old definition is settled
+        // `skipped_stale` and can never fire. A caller who meant to adjust a
+        // schedule has discarded the work it was about to do.
+        mcp: { destructive: true, kind: "tool", openWorld: true },
+        method: "PUT",
+        mutates: true,
+        path: "/v1/schedules/{scheduleId}",
+        principals: ["api-credential", "oauth", "session"],
+        problems: [
+            // The same undeclared refusal `schedules.create` carried, for the same
+            // reason: a replacement may attach a different endpoint and resolves it
+            // through the same status rule.
+            "endpoint_unverified",
+            "invalid_request",
+            "not_found",
+            // Only the payload ceiling can produce this here. A replacement adds no
+            // schedule and cannot change `partitionKey`, so neither counted ceiling
+            // can move; what it can do is carry a larger body than the plan admits.
+            "plan_limit_reached",
+            "service_unavailable",
+            "state_conflict",
+            "version_conflict",
+        ],
+        request: scheduleRequestSchema,
+        // The other arm of the same schema, deliberately: the create example shows
+        // `at` and this one shows `delaySeconds`, so a reader of the published
+        // document meets both ways of naming an instant.
+        requestExample: {
+            data: { report: "weekly" },
+            everySeconds: 86_400,
+            endpoint: "ep_01h8xyz9k2m4n6p8r0t2v4w6y8",
+            partitionKey: "campaign.spring",
+        },
+        requestHeaders: conditionalRequestHeaderSchema,
+        response: scheduleViewSchema,
+        responseHeaders: versionResponseHeaderSchema,
+        scopes: ["schedules:write"],
+        sessionAuthority: "headers",
+        summary: "Replace a schedule",
+        surfaces: ["api", "mock"],
+    },
+    {
+        creates: false,
+        description: "Suspends a schedule without discarding it: its occurrence stays planned, its timer is released, and resume re-arms the original planned instant so elapsed work becomes due rather than being silently moved. A schedule with a dispatching or ambiguous callback is refused until that attempt settles, because pausing cannot strand its watchdog or turn a proven success into an unreachable completed state. Pausing an already paused schedule changes nothing and returns the same version, so a retry is free. A cancelled or completed schedule cannot be paused.",
+        example: {
+            occurrence: {
+                attemptCount: 0,
+                generation: 1,
+                id: "occ_01h8xyz9k2m4n6p8r0t2v4w6y8",
+                plannedFor: "2026-07-28T15:00:00.000Z",
+                schedule: "sch_01h8xyz9k2m4n6p8r0t2v4w6y8",
+                sequence: 1,
+                state: "planned",
+            },
+            schedule: {
+                createdAt: "2026-07-28T14:59:00.000Z",
+                generation: 1,
+                id: "sch_01h8xyz9k2m4n6p8r0t2v4w6y8",
+                latencyClass: "realtime",
+                recurrence: { kind: "at" },
+                status: "paused",
+                updatedAt: "2026-07-28T15:10:00.000Z",
+                version: 2,
+            },
+        },
+        id: "schedules.pause",
+        idempotent: true,
+        // Not destructive: the occurrence stays planned and the timer stays armed.
+        // A pause defers work; resuming delivers it.
+        mcp: { destructive: false, kind: "tool", openWorld: false },
+        method: "POST",
+        mutates: true,
+        path: "/v1/schedules/{scheduleId}/pause",
+        principals: ["api-credential", "oauth", "session"],
+        problems: [
+            "invalid_request",
+            "not_found",
+            "state_conflict",
+            "version_conflict",
+        ],
+        requestHeaders: conditionalRequestHeaderSchema,
+        response: scheduleViewSchema,
+        responseHeaders: versionResponseHeaderSchema,
+        scopes: ["schedules:write"],
+        sessionAuthority: "headers",
+        summary: "Pause a schedule",
+        surfaces: ["api", "mock"],
+    },
+    {
+        creates: false,
+        description: "Returns a paused schedule to active. An occurrence whose instant passed while the schedule was paused becomes due at once rather than being skipped — a pause defers work, it does not discard it. Resuming an already active schedule changes nothing and returns the same version.",
+        example: {
+            occurrence: {
+                attemptCount: 0,
+                generation: 1,
+                id: "occ_01h8xyz9k2m4n6p8r0t2v4w6y8",
+                plannedFor: "2026-07-28T15:00:00.000Z",
+                schedule: "sch_01h8xyz9k2m4n6p8r0t2v4w6y8",
+                sequence: 1,
+                state: "planned",
+            },
+            schedule: {
+                createdAt: "2026-07-28T14:59:00.000Z",
+                generation: 1,
+                id: "sch_01h8xyz9k2m4n6p8r0t2v4w6y8",
+                latencyClass: "realtime",
+                recurrence: { kind: "at" },
+                status: "active",
+                updatedAt: "2026-07-28T15:20:00.000Z",
+                version: 3,
+            },
+        },
+        id: "schedules.resume",
+        idempotent: true,
+        mcp: { destructive: false, kind: "tool", openWorld: false },
+        method: "POST",
+        mutates: true,
+        path: "/v1/schedules/{scheduleId}/resume",
+        principals: ["api-credential", "oauth", "session"],
+        problems: [
+            "invalid_request",
+            "not_found",
+            "state_conflict",
+            "version_conflict",
+        ],
+        requestHeaders: conditionalRequestHeaderSchema,
+        response: scheduleViewSchema,
+        responseHeaders: versionResponseHeaderSchema,
+        scopes: ["schedules:write"],
+        sessionAuthority: "headers",
+        summary: "Resume a schedule",
+        surfaces: ["api", "mock"],
+    },
+    {
+        creates: false,
+        description: "Cancels a schedule and settles its occurrence `cancelled`, releasing the timer. Terminal: a cancelled schedule cannot be resumed or replaced, and cancelling one that is already cancelled changes nothing and returns the same version. A cancel that races its own occurrence becoming due still wins — the occurrence settles cancelled and no work is delivered — which is why this is a refusal-free retry rather than a race a client has to reason about. The schedule stays readable; archive it to take it out of the listing.",
+        example: {
+            occurrence: {
+                attemptCount: 0,
+                generation: 1,
+                id: "occ_01h8xyz9k2m4n6p8r0t2v4w6y8",
+                plannedFor: "2026-07-28T15:00:00.000Z",
+                schedule: "sch_01h8xyz9k2m4n6p8r0t2v4w6y8",
+                sequence: 1,
+                settledAt: "2026-07-28T15:10:00.000Z",
+                state: "cancelled",
+            },
+            schedule: {
+                createdAt: "2026-07-28T14:59:00.000Z",
+                generation: 1,
+                id: "sch_01h8xyz9k2m4n6p8r0t2v4w6y8",
+                latencyClass: "realtime",
+                recurrence: { kind: "at" },
+                status: "cancelled",
+                updatedAt: "2026-07-28T15:10:00.000Z",
+                version: 2,
+            },
+        },
+        id: "schedules.cancel",
+        idempotent: true,
+        // Destructive and terminal: the occurrence settles `cancelled`, no work is
+        // delivered, and nothing resumes or replaces it afterwards.
+        mcp: { destructive: true, kind: "tool", openWorld: false },
+        method: "DELETE",
+        mutates: true,
+        path: "/v1/schedules/{scheduleId}",
+        principals: ["api-credential", "oauth", "session"],
+        problems: [
+            "invalid_request",
+            "not_found",
+            "state_conflict",
+            "version_conflict",
+        ],
+        requestHeaders: conditionalRequestHeaderSchema,
+        response: scheduleViewSchema,
+        responseHeaders: versionResponseHeaderSchema,
+        scopes: ["schedules:write"],
+        sessionAuthority: "headers",
+        summary: "Cancel a schedule",
+        surfaces: ["api", "mock"],
+    },
+    {
+        creates: false,
+        description: "Files a finished schedule away: it leaves the default listing and stays readable by identifier, carrying the instant it was archived. Only a cancelled or completed schedule can be archived — archiving is filing, not stopping, so cancel it first. Archiving an already archived schedule changes nothing and returns the same version.",
+        example: {
+            occurrence: {
+                attemptCount: 0,
+                generation: 1,
+                id: "occ_01h8xyz9k2m4n6p8r0t2v4w6y8",
+                plannedFor: "2026-07-28T15:00:00.000Z",
+                schedule: "sch_01h8xyz9k2m4n6p8r0t2v4w6y8",
+                sequence: 1,
+                settledAt: "2026-07-28T15:10:00.000Z",
+                state: "cancelled",
+            },
+            schedule: {
+                archivedAt: "2026-07-28T15:30:00.000Z",
+                createdAt: "2026-07-28T14:59:00.000Z",
+                generation: 1,
+                id: "sch_01h8xyz9k2m4n6p8r0t2v4w6y8",
+                latencyClass: "realtime",
+                recurrence: { kind: "at" },
+                status: "cancelled",
+                updatedAt: "2026-07-28T15:30:00.000Z",
+                version: 3,
+            },
+        },
+        id: "schedules.archive",
+        idempotent: true,
+        // Not destructive: archiving is filing. The schedule stays readable by
+        // identifier and only leaves the default listing, and it is refused unless
+        // the schedule has already stopped.
+        mcp: { destructive: false, kind: "tool", openWorld: false },
+        method: "POST",
+        mutates: true,
+        path: "/v1/schedules/{scheduleId}/archive",
+        principals: ["api-credential", "oauth", "session"],
+        problems: [
+            "invalid_request",
+            "not_found",
+            "state_conflict",
+            "version_conflict",
+        ],
+        requestHeaders: conditionalRequestHeaderSchema,
+        response: scheduleViewSchema,
+        responseHeaders: versionResponseHeaderSchema,
+        scopes: ["schedules:write"],
+        sessionAuthority: "headers",
+        summary: "Archive a schedule",
+        surfaces: ["api", "mock"],
+    },
+];
+/**
+ * Headers the contract mock uses to expose state a body cannot carry.
+ *
+ * Declared here rather than written into the adapter for the same reason every
+ * other wire detail is: a header invented at the edge is a wire shape that
+ * drifts.
+ */
+export const MOCK_HEADERS = {
+    /** The instant the mock's pinned clock reports. */
+    now: "X-Greatwait-Now",
+    /** Present when this response is an at-least-once duplicate. */
+    replayed: "X-Greatwait-Replayed",
+};
+/** The registry, widened. `as const` narrows `surfaces` to per-operation
+ *  literal tuples, which is what makes `OperationId` precise but makes the
+ *  registry awkward to iterate generically. */
+const ALL = OPERATIONS;
+export function operationsFor(surface) {
+    return ALL.filter((operation) => operation.surfaces.includes(surface));
+}
+export function findOperation(id) {
+    return ALL.find((operation) => operation.id === id);
+}
+/**
+ * The schema an operation's success body is parsed with, by operation id.
+ *
+ * **Exists so a consumer can parse without naming a schema export.** The typed
+ * client returns `unknown` and tells callers to parse with "that operation's
+ * contract schema", which until W9-03 meant every caller had to map an
+ * operation id onto a symbol by hand — a mapping that is a second statement of
+ * the registry, and one a renamed export breaks silently. The published
+ * quickstarts and anything W10 generates resolve it here instead, so the
+ * operation id is the only name a consumer has to know.
+ *
+ * `undefined` for an id the registry does not carry, rather than a throw: the
+ * caller usually has a better message than this function could write.
+ */
+export function responseSchemaFor(id) {
+    return findOperation(id)?.response;
+}
+/** The schema an operation's request body is validated with, by id. */
+export function requestSchemaFor(id) {
+    return findOperation(id)?.request;
+}
+/**
+ * The status a successful call returns.
+ *
+ * Computed in one place, so the OpenAPI document, the contract mock and the API
+ * adapter cannot disagree about it — which they did for exactly one commit,
+ * when a route returned 201 and the published document said 200. An operation
+ * that **creates** something, **on the product surface**, answers 201;
+ * everything else answers 200.
+ *
+ * The first clause read `method === "POST" && mutates` until W2-02, which added
+ * the first mutating POST that creates nothing — pausing a schedule — and would
+ * have had "201 Created" published for it. `creates` is declared rather than
+ * inferred because no combination of method, path and schema distinguishes
+ * "changed something" from "brought something into being".
+ *
+ * The surface clause is not a per-operation exception, and it is not
+ * cosmetic. Without it the rule reaches `mock.setScenario`, whose 200 is
+ * already published in `openapi.mock.json` and already served from a deployed
+ * host — and `classifyChange` in `compatibility.ts` classifies a changed status
+ * as **breaking**, requiring a new contract version. Tidying the mock's control
+ * plane is not worth a contract version, and shipping the change without one
+ * would make the compatibility module a thing this repository consults and then
+ * ignores. The mock's control plane is not a product operation; that is the
+ * distinction, and it is structural rather than a judgement about any one
+ * operation.
+ */
+export function successStatusFor(operation) {
+    return operation.creates && operation.surfaces.includes("api") ? 201 : 200;
+}
+/**
+ * Problems any operation may return regardless of what it does. Kept separate
+ * so an operation's own `problems` list stays about that operation.
+ */
+export const UNIVERSAL_PROBLEMS = [
+    "rate_limited",
+    "service_unavailable",
+];
+/**
+ * Problems an operation returns once authentication applies to it.
+ *
+ * `credential_expired` is here rather than on the operations that rotate,
+ * because expiry is a property of the credential being *presented*, not of what
+ * the caller asked to do. Any authenticated operation can meet a credential
+ * whose rotation window has closed.
+ */
+export const AUTHENTICATED_PROBLEMS = [
+    "authentication_required",
+    "credential_expired",
+    "credential_revoked",
+    "scope_missing",
+];
+export function problemsFor(operation) {
+    return [
+        ...new Set([
+            ...operation.problems,
+            ...UNIVERSAL_PROBLEMS,
+            ...(operation.scopes.length > 0 ? AUTHENTICATED_PROBLEMS : []),
+        ]),
+    ].sort();
+}