@greatwait/contracts 0.1.0-alpha.1 → 0.1.0-alpha.2

package/dist/callback-receiver.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Bounds a receiver applies to the deliveries this service sends it.
+ *
+ * **A receiver's bounds are not the sender's, and the shipped SDK used the
+ * sender's.** `createNodeCallbackMiddleware` and the receiver conformance suite
+ * both defaulted their body limit to `TEST_SINK_BOUNDS.maxRequestBodyBytes` —
+ * a number whose every neighbour is justified by the test sink running *inside
+ * the API Worker's request budget, on the product's own account*. None of that
+ * reasoning is about a customer's own server, and the value it produced was
+ * wrong for one.
+ */
+/**
+ * Headroom for the envelope wrapped around a payload.
+ *
+ * A receiver is sent an envelope, not a payload: version, type, schedule and
+ * occurrence identifiers, the planned time, the attempt ordinal, the trigger
+ * that says why the delivery exists, and in `callback` mode a completion URL,
+ * bearer token and deadline. All of that is additive to `payloadBytes`.
+ *
+ * **Measured, not chosen.** Serializing every published delivery test vector
+ * around a payload at exactly `SCHEDULING_BOUNDS.payloadBytes`, with a 180-
+ * character completion host and a 512-character token — both far past anything
+ * the service mints — the largest envelope exceeded the payload maximum by
+ * 1,097 bytes. `callback-receiver.test.ts` re-derives that rather than trusting
+ * this sentence, so an envelope that grows past the headroom fails a test
+ * instead of silently costing a customer their largest deliveries.
+ *
+ * Four kibibytes is roughly four times the measured worst case, which is slack
+ * enough to absorb a new envelope field and tight enough that this is still a
+ * bound rather than a shrug.
+ */
+export declare const CALLBACK_ENVELOPE_HEADROOM_BYTES = 4096;
+/**
+ * The largest callback body a conforming receiver reads before refusing.
+ *
+ * Derived rather than written down, because the thing that must stay true is
+ * the *relationship*: a receiver has to accept the largest payload this service
+ * will accept, plus whatever the envelope adds. A literal here would be a
+ * second statement of `payloadBytes` and would go stale the first time that
+ * moved.
+ *
+ * **The defect this replaces was live in `0.1.0-alpha.1`.** The old default was
+ * 65,536 — exactly `payloadBytes`, and therefore below every envelope carrying
+ * a maximum payload. A customer scheduling their largest legal payload against
+ * a receiver built with the SDK's defaults got `413 body_too_large`, which the
+ * sender classifies as terminal: the occurrence fails and is not retried. The
+ * bound was reachable by anyone using both the documented maximum and the
+ * documented defaults.
+ */
+export declare const CALLBACK_RECEIVER_MAX_BODY_BYTES: number;

package/dist/callback-receiver.js

@@ -0,0 +1,51 @@
+import { SCHEDULING_BOUNDS } from "./scheduling.js";
+/**
+ * Bounds a receiver applies to the deliveries this service sends it.
+ *
+ * **A receiver's bounds are not the sender's, and the shipped SDK used the
+ * sender's.** `createNodeCallbackMiddleware` and the receiver conformance suite
+ * both defaulted their body limit to `TEST_SINK_BOUNDS.maxRequestBodyBytes` —
+ * a number whose every neighbour is justified by the test sink running *inside
+ * the API Worker's request budget, on the product's own account*. None of that
+ * reasoning is about a customer's own server, and the value it produced was
+ * wrong for one.
+ */
+/**
+ * Headroom for the envelope wrapped around a payload.
+ *
+ * A receiver is sent an envelope, not a payload: version, type, schedule and
+ * occurrence identifiers, the planned time, the attempt ordinal, the trigger
+ * that says why the delivery exists, and in `callback` mode a completion URL,
+ * bearer token and deadline. All of that is additive to `payloadBytes`.
+ *
+ * **Measured, not chosen.** Serializing every published delivery test vector
+ * around a payload at exactly `SCHEDULING_BOUNDS.payloadBytes`, with a 180-
+ * character completion host and a 512-character token — both far past anything
+ * the service mints — the largest envelope exceeded the payload maximum by
+ * 1,097 bytes. `callback-receiver.test.ts` re-derives that rather than trusting
+ * this sentence, so an envelope that grows past the headroom fails a test
+ * instead of silently costing a customer their largest deliveries.
+ *
+ * Four kibibytes is roughly four times the measured worst case, which is slack
+ * enough to absorb a new envelope field and tight enough that this is still a
+ * bound rather than a shrug.
+ */
+export const CALLBACK_ENVELOPE_HEADROOM_BYTES = 4_096;
+/**
+ * The largest callback body a conforming receiver reads before refusing.
+ *
+ * Derived rather than written down, because the thing that must stay true is
+ * the *relationship*: a receiver has to accept the largest payload this service
+ * will accept, plus whatever the envelope adds. A literal here would be a
+ * second statement of `payloadBytes` and would go stale the first time that
+ * moved.
+ *
+ * **The defect this replaces was live in `0.1.0-alpha.1`.** The old default was
+ * 65,536 — exactly `payloadBytes`, and therefore below every envelope carrying
+ * a maximum payload. A customer scheduling their largest legal payload against
+ * a receiver built with the SDK's defaults got `413 body_too_large`, which the
+ * sender classifies as terminal: the occurrence fails and is not retried. The
+ * bound was reachable by anyone using both the documented maximum and the
+ * documented defaults.
+ */
+export const CALLBACK_RECEIVER_MAX_BODY_BYTES = SCHEDULING_BOUNDS.payloadBytes + CALLBACK_ENVELOPE_HEADROOM_BYTES;

package/dist/index.d.ts

@@ -8,7 +8,6 @@ export { CREDENTIAL_PREFIX_LENGTH, CREDENTIAL_PREFIX_PATTERN, CREDENTIAL_ROTATIO
 export { MAX_PARTITION_SHARDS, PROJECTION_DRAIN_LIMIT, SINGLE_SHARD, partitionInstanceName, partitionShardCount, partitionShardFor, partitionShardForIdempotencyKey, type CreateScheduleCommand, type CreateScheduleOutcome, type AttemptPagePosition, type DrainProjectionsOutcome, type DrainProjectionsQuery, type ForecastOutcome, type ForecastPartitionBucket, type ForecastQuery, type IdempotencyDisposition, type ListSchedulesOutcome, type ListSchedulesQuery, type ListAttemptsOutcome, type ListAttemptsQuery, type ListOccurrencesOutcome, type ListOccurrencesQuery, type OccurrencePagePosition, type PartitionOutcome, type PartitionRefusal, type PartitionRefused, type PartitionRpc, type ProjectionIntent, type ReadScheduleQuery, type ReadAttemptOutcome, type ReadAttemptQuery, type ReadOccurrenceOutcome, type ReadOccurrenceQuery, type RedeliverOccurrenceCommand, type RedeliverOccurrenceOutcome, type ReplaceScheduleCommand, type RetainedProjections, type ScheduleDefinition, type ScheduleWriteCommand, type ScheduleWriteOutcome, type SettleProjectionsCommand, type SettleProjectionsOutcome, } from "./partition.js";
 export { EVENT_TYPES, eventEnvelopeSchema, eventTypeSchema, genericEventSchema, type EventType, type GenericEvent, } from "./events.js";
 export { MEMBERSHIP_ROLES, MEMBERSHIP_STATUSES, externalMembershipIdSchema, externalOrganizationIdSchema, externalUserIdSchema, grantsAccess, leastRole, leastStatus, membershipChangeSchema, membershipRoleSchema, membershipSchema, membershipStatusSchema, organizationTombstoneSchema, sessionMembershipSchema, type ExternalMembershipId, type ExternalOrganizationId, type ExternalUserId, type Membership, type MembershipChange, type MembershipRole, type MembershipStatus, type OrganizationTombstone, type SessionMembership, } from "./identity.js";
-export { CLERK_WEBHOOK_PATH, SVIX_HEADERS, WEBHOOK_SIGNATURE_SCHEME, WEBHOOK_TOLERANCE_SECONDS, isWebhookTimestampFresh, svixHeadersSchema, svixIdSchema, svixSignatureHeaderSchema, svixTimestampSchema, tryWebhookSigningInput, webhookSignatureCandidates, webhookSigningInput, } from "./webhooks.js";
 export { CHANGE_KINDS, CHANGE_OPERATIONS, CHANGE_SUBJECTS, CONTRACT_VERSION, assess, changeKindSchema, classifyChange, contractVersionSchema, type ChangeKind, type ChangeOperation, type ChangeSubject, type CompatibilityVerdict, type ContractChange, } from "./compatibility.js";
 export { WORKSPACE_LAYERS, scaffoldProblemSchema, scaffoldVersionSchema, toolDescriptorSchema, toolListSchema, workspaceIdentitySchema, workspaceLayerSchema, workspaceScaffoldSchema, type ScaffoldProblem, type ScaffoldVersion, type ToolDescriptor, type ToolList, type WorkspaceIdentity, type WorkspaceLayer, type WorkspaceScaffold, } from "./workspace.js";
 export { MOCK_BEHAVIORS, MOCK_HEADERS, OPERATIONS, UNIVERSAL_PROBLEMS, AUTHENTICATED_PROBLEMS, findOperation, fixtureListSchema, mockBehaviorSchema, mockScenarioRequestSchema, mockScenarioResponseSchema, operationsFor, problemsFor, requestSchemaFor, responseSchemaFor, successStatusFor, type FixtureList, type McpDisposition, type MockBehavior, type MockScenarioRequest, type MockScenarioResponse, type OperationDefinition, type OperationId, type OperationSurface, } from "./operations.js";
@@ -17,7 +16,7 @@ export { ATTEMPT_DURATION_MAX_MS, ATTEMPT_FAILURE_SNIPPET_MAX_LENGTH, ATTEMPT_RE
 export { portableAttemptRecordSchema, portableEncryptedPayloadRecordSchema, portableOccurrenceRecordSchema, portableReceiptRecordSchema, portableScheduleRecordSchema, portableSchedulingRecordSetSchema, type PortableAttemptRecord, type PortableEncryptedPayloadRecord, type PortableOccurrenceRecord, type PortableReceiptRecord, type PortableScheduleRecord, type PortableSchedulingRecordSet, } from "./scheduling-records.js";
 export { ROLE_SCOPE_CEILINGS, capScopesToRole, ceilingForRole, credentialScopes, grantableScopes, policyMatrix, roleAllows, roleCanPerform, type PolicyMatrixRow, } from "./policy.js";
 export { ACCESS_TOKEN_PATTERN, ACCESS_TOKEN_TTL_SECONDS, AUTHORIZATION_CODE_PATTERN, AUTHORIZATION_CODE_TTL_SECONDS, AUTHORIZATION_REQUEST_TTL_SECONDS, MAX_REDIRECT_URIS, OAUTH_ERRORS, OAUTH_ERROR_STATUS, OAUTH_GRANT_STATUSES, OAUTH_GRANT_TYPES, OAUTH_RESPONSE_TYPES, OAUTH_REVOCATION_REASONS, OAUTH_ROUTES, OAUTH_SECRET_PATTERN, OAUTH_TOKEN_NAMESPACE_LENGTH, OAUTH_TOKEN_SECRET_LENGTH, PKCE_CHALLENGE_PATTERN, PKCE_METHODS, PKCE_VERIFIER_PATTERN, REFRESH_TOKEN_PATTERN, REFRESH_TOKEN_TTL_SECONDS, TOKEN_ENDPOINT_AUTH_METHODS, authorizationParametersSchema, authorizationServerMetadataSchema, bearerChallenge, clientRegistrationRequestSchema, clientRegistrationSchema, consentDecisionSchema, consentOutcomeSchema, consentPromptSchema, formatScopeString, isLoopbackRedirect, oauthError, oauthErrorCodeSchema, oauthErrorSchema, oauthGrantListSchema, oauthGrantRevokedSchema, oauthGrantSchema, oauthGrantStatusSchema, oauthGrantTypeSchema, oauthRevocationReasonSchema, parseScopeString, pkceMethodSchema, protectedResourceMetadataSchema, redirectUriSchema, revocationRequestSchema, tokenRequestSchema, tokenResponseSchema, type AuthorizationParameters, type AuthorizationServerMetadata, type ClientRegistration, type ClientRegistrationRequest, type ConsentDecision, type ConsentOutcome, type ConsentPrompt, type OAuthErrorBody, type OAuthErrorCode, type OAuthGrant, type OAuthGrantList, type OAuthGrantRevoked, type OAuthGrantStatus, type OAuthGrantType, type OAuthRevocationReason, type ProtectedResourceMetadata, type RevocationRequest, type TokenRequest, type TokenResponse, } from "./oauth.js";
-export { MCP_INSTRUCTIONS, MCP_ROUTES } from "./mcp.js";
+export { CALLBACK_ENVELOPE_HEADROOM_BYTES, CALLBACK_RECEIVER_MAX_BODY_BYTES, } from "./callback-receiver.js";
 export { CALLBACK_OWNERSHIP_POLICIES, DEFAULT_CALLBACK_OWNERSHIP_POLICY, readCallbackOwnershipPolicy, sendableStatuses, type CallbackOwnershipPolicy, } from "./callback-ownership.js";
 export { CALLBACK_ENDPOINT_SECRET_PATTERN, CALLBACK_URL_REJECTION_REASONS, evaluateCallbackUrl, isPublicCallbackAddress, type CallbackUrlRejectionReason, } from "./callback-safety.js";
 export { CALLBACK_ENDPOINT_LIMIT_PER_ENVIRONMENT, CALLBACK_ENDPOINT_STATUSES, CALLBACK_SIGNING_KEY_ROTATION_OVERLAP_SECONDS, CALLBACK_VERIFICATION_FAILURES, CALLBACK_VERIFICATION_HEADERS, CALLBACK_VERIFICATION_PROTOCOL, CALLBACK_VERIFICATION_PROTOCOL_VERSION, CALLBACK_VERIFICATION_RATE_LIMITS, CALLBACK_VERIFICATION_RESPONSE_BYTES, CALLBACK_VERIFICATION_TIMEOUT_MILLISECONDS, CALLBACK_VERIFICATION_TYPE, callbackEndpointCreatedSchema, callbackEndpointPageSchema, callbackEndpointRequestSchema, callbackEndpointRotatedSchema, callbackEndpointSchema, callbackEndpointStatusSchema, callbackSigningKeyRotationRequestSchema, callbackSigningKeysSchema, callbackVerificationChallengeSchema, callbackVerificationFailureSchema, type CallbackEndpoint, type CallbackEndpointCreated, type CallbackEndpointPage, type CallbackEndpointRequest, type CallbackEndpointRotated, type CallbackEndpointStatus, type CallbackSigningKeyRotationRequest, type CallbackSigningKeys, type CallbackVerificationChallenge, type CallbackVerificationFailure, } from "./endpoints.js";

package/dist/index.js

@@ -8,7 +8,6 @@ export { CREDENTIAL_PREFIX_LENGTH, CREDENTIAL_PREFIX_PATTERN, CREDENTIAL_ROTATIO
 export { MAX_PARTITION_SHARDS, PROJECTION_DRAIN_LIMIT, SINGLE_SHARD, partitionInstanceName, partitionShardCount, partitionShardFor, partitionShardForIdempotencyKey, } from "./partition.js";
 export { EVENT_TYPES, eventEnvelopeSchema, eventTypeSchema, genericEventSchema, } from "./events.js";
 export { MEMBERSHIP_ROLES, MEMBERSHIP_STATUSES, externalMembershipIdSchema, externalOrganizationIdSchema, externalUserIdSchema, grantsAccess, leastRole, leastStatus, membershipChangeSchema, membershipRoleSchema, membershipSchema, membershipStatusSchema, organizationTombstoneSchema, sessionMembershipSchema, } from "./identity.js";
-export { CLERK_WEBHOOK_PATH, SVIX_HEADERS, WEBHOOK_SIGNATURE_SCHEME, WEBHOOK_TOLERANCE_SECONDS, isWebhookTimestampFresh, svixHeadersSchema, svixIdSchema, svixSignatureHeaderSchema, svixTimestampSchema, tryWebhookSigningInput, webhookSignatureCandidates, webhookSigningInput, } from "./webhooks.js";
 export { CHANGE_KINDS, CHANGE_OPERATIONS, CHANGE_SUBJECTS, CONTRACT_VERSION, assess, changeKindSchema, classifyChange, contractVersionSchema, } from "./compatibility.js";
 export { WORKSPACE_LAYERS, scaffoldProblemSchema, scaffoldVersionSchema, toolDescriptorSchema, toolListSchema, workspaceIdentitySchema, workspaceLayerSchema, workspaceScaffoldSchema, } from "./workspace.js";
 export { MOCK_BEHAVIORS, MOCK_HEADERS, OPERATIONS, UNIVERSAL_PROBLEMS, AUTHENTICATED_PROBLEMS, findOperation, fixtureListSchema, mockBehaviorSchema, mockScenarioRequestSchema, mockScenarioResponseSchema, operationsFor, problemsFor, requestSchemaFor, responseSchemaFor, successStatusFor, } from "./operations.js";
@@ -17,7 +16,7 @@ export { ATTEMPT_DURATION_MAX_MS, ATTEMPT_FAILURE_SNIPPET_MAX_LENGTH, ATTEMPT_RE
 export { portableAttemptRecordSchema, portableEncryptedPayloadRecordSchema, portableOccurrenceRecordSchema, portableReceiptRecordSchema, portableScheduleRecordSchema, portableSchedulingRecordSetSchema, } from "./scheduling-records.js";
 export { ROLE_SCOPE_CEILINGS, capScopesToRole, ceilingForRole, credentialScopes, grantableScopes, policyMatrix, roleAllows, roleCanPerform, } from "./policy.js";
 export { ACCESS_TOKEN_PATTERN, ACCESS_TOKEN_TTL_SECONDS, AUTHORIZATION_CODE_PATTERN, AUTHORIZATION_CODE_TTL_SECONDS, AUTHORIZATION_REQUEST_TTL_SECONDS, MAX_REDIRECT_URIS, OAUTH_ERRORS, OAUTH_ERROR_STATUS, OAUTH_GRANT_STATUSES, OAUTH_GRANT_TYPES, OAUTH_RESPONSE_TYPES, OAUTH_REVOCATION_REASONS, OAUTH_ROUTES, OAUTH_SECRET_PATTERN, OAUTH_TOKEN_NAMESPACE_LENGTH, OAUTH_TOKEN_SECRET_LENGTH, PKCE_CHALLENGE_PATTERN, PKCE_METHODS, PKCE_VERIFIER_PATTERN, REFRESH_TOKEN_PATTERN, REFRESH_TOKEN_TTL_SECONDS, TOKEN_ENDPOINT_AUTH_METHODS, authorizationParametersSchema, authorizationServerMetadataSchema, bearerChallenge, clientRegistrationRequestSchema, clientRegistrationSchema, consentDecisionSchema, consentOutcomeSchema, consentPromptSchema, formatScopeString, isLoopbackRedirect, oauthError, oauthErrorCodeSchema, oauthErrorSchema, oauthGrantListSchema, oauthGrantRevokedSchema, oauthGrantSchema, oauthGrantStatusSchema, oauthGrantTypeSchema, oauthRevocationReasonSchema, parseScopeString, pkceMethodSchema, protectedResourceMetadataSchema, redirectUriSchema, revocationRequestSchema, tokenRequestSchema, tokenResponseSchema, } from "./oauth.js";
-export { MCP_INSTRUCTIONS, MCP_ROUTES } from "./mcp.js";
+export { CALLBACK_ENVELOPE_HEADROOM_BYTES, CALLBACK_RECEIVER_MAX_BODY_BYTES, } from "./callback-receiver.js";
 export { CALLBACK_OWNERSHIP_POLICIES, DEFAULT_CALLBACK_OWNERSHIP_POLICY, readCallbackOwnershipPolicy, sendableStatuses, } from "./callback-ownership.js";
 export { CALLBACK_ENDPOINT_SECRET_PATTERN, CALLBACK_URL_REJECTION_REASONS, evaluateCallbackUrl, isPublicCallbackAddress, } from "./callback-safety.js";
 export { CALLBACK_ENDPOINT_LIMIT_PER_ENVIRONMENT, CALLBACK_ENDPOINT_STATUSES, CALLBACK_SIGNING_KEY_ROTATION_OVERLAP_SECONDS, CALLBACK_VERIFICATION_FAILURES, CALLBACK_VERIFICATION_HEADERS, CALLBACK_VERIFICATION_PROTOCOL, CALLBACK_VERIFICATION_PROTOCOL_VERSION, CALLBACK_VERIFICATION_RATE_LIMITS, CALLBACK_VERIFICATION_RESPONSE_BYTES, CALLBACK_VERIFICATION_TIMEOUT_MILLISECONDS, CALLBACK_VERIFICATION_TYPE, callbackEndpointCreatedSchema, callbackEndpointPageSchema, callbackEndpointRequestSchema, callbackEndpointRotatedSchema, callbackEndpointSchema, callbackEndpointStatusSchema, callbackSigningKeyRotationRequestSchema, callbackSigningKeysSchema, callbackVerificationChallengeSchema, callbackVerificationFailureSchema, } from "./endpoints.js";

package/dist/operations.d.ts

@@ -2379,7 +2379,7 @@ export declare const OPERATIONS: readonly [{
                 response: "response";
                 callback: "callback";
             }>>;
-            maxDurationSeconds: z.ZodOptional<z.ZodLiteral<5 | 300 | 86400 | 30 | 900 | 1800 | 3600 | 43200>>;
+            maxDurationSeconds: z.ZodOptional<z.ZodLiteral<300 | 5 | 30 | 900 | 1800 | 3600 | 43200 | 86400>>;
         }, z.core.$strict>>;
         everySeconds: z.ZodOptional<z.ZodNumber>;
         endpoint: z.ZodOptional<z.ZodString>;
@@ -3360,7 +3360,7 @@ export declare const OPERATIONS: readonly [{
                 response: "response";
                 callback: "callback";
             }>>;
-            maxDurationSeconds: z.ZodOptional<z.ZodLiteral<5 | 300 | 86400 | 30 | 900 | 1800 | 3600 | 43200>>;
+            maxDurationSeconds: z.ZodOptional<z.ZodLiteral<300 | 5 | 30 | 900 | 1800 | 3600 | 43200 | 86400>>;
         }, z.core.$strict>>;
         everySeconds: z.ZodOptional<z.ZodNumber>;
         endpoint: z.ZodOptional<z.ZodString>;

package/dist/scheduling.d.ts

@@ -127,7 +127,7 @@ export declare const FREE_DELIVERY_DURATION_SECONDS = 30;
  * than thirty minutes has to do is answer immediately and call us back.
  */
 export declare const RESPONSE_DELIVERY_MAX_DURATION_SECONDS = 1800;
-export declare const deliveryDurationSecondsSchema: z.ZodLiteral<5 | 300 | 86400 | 30 | 900 | 1800 | 3600 | 43200>;
+export declare const deliveryDurationSecondsSchema: z.ZodLiteral<300 | 5 | 30 | 900 | 1800 | 3600 | 43200 | 86400>;
 export type DeliveryDurationSeconds = z.infer<typeof deliveryDurationSecondsSchema>;
 /** Whether a duration is past the point where it needs a plan that allows it. */
 export declare function isLongRunningDuration(seconds: number): boolean;
@@ -1041,7 +1041,7 @@ export declare const scheduleRequestSchema: z.ZodObject<{
             response: "response";
             callback: "callback";
         }>>;
-        maxDurationSeconds: z.ZodOptional<z.ZodLiteral<5 | 300 | 86400 | 30 | 900 | 1800 | 3600 | 43200>>;
+        maxDurationSeconds: z.ZodOptional<z.ZodLiteral<300 | 5 | 30 | 900 | 1800 | 3600 | 43200 | 86400>>;
     }, z.core.$strict>>;
     everySeconds: z.ZodOptional<z.ZodNumber>;
     endpoint: z.ZodOptional<z.ZodString>;

package/dist/test-sink.d.ts

@@ -100,8 +100,18 @@ export declare const TEST_SINK_BOUNDS: {
     readonly maxRetainedDeliveries: 50;
     /** Sinks per project/environment. */
     readonly maxSinksPerEnvironment: 10;
-    /** Largest request body a sink will read. Larger is refused unread. */
-    readonly maxRequestBodyBytes: 65536;
+    /**
+     * Largest request body a sink will read. Larger is refused unread.
+     *
+     * **A sink is a receiver, so this is the receiver's bound rather than one of
+     * its own.** It used to be a literal 65,536, which is exactly
+     * `SCHEDULING_BOUNDS.payloadBytes` — and therefore below every envelope
+     * carrying a maximum payload, so a customer rehearsing their largest legal
+     * delivery against a sink got the 413 they were rehearsing to avoid. The
+     * neighbours here are all justified by the sink running inside the API
+     * Worker's budget; this one never was.
+     */
+    readonly maxRequestBodyBytes: number;
     /** Captured body bytes retained on a receipt; beyond this it is truncated. */
     readonly maxRetainedBodyBytes: 4096;
 };
@@ -967,8 +977,18 @@ export declare const CALLBACK_RECEIVER_PROTOCOL: {
             readonly maxRetainedDeliveries: 50;
             /** Sinks per project/environment. */
             readonly maxSinksPerEnvironment: 10;
-            /** Largest request body a sink will read. Larger is refused unread. */
-            readonly maxRequestBodyBytes: 65536;
+            /**
+             * Largest request body a sink will read. Larger is refused unread.
+             *
+             * **A sink is a receiver, so this is the receiver's bound rather than one of
+             * its own.** It used to be a literal 65,536, which is exactly
+             * `SCHEDULING_BOUNDS.payloadBytes` — and therefore below every envelope
+             * carrying a maximum payload, so a customer rehearsing their largest legal
+             * delivery against a sink got the 413 they were rehearsing to avoid. The
+             * neighbours here are all justified by the sink running inside the API
+             * Worker's budget; this one never was.
+             */
+            readonly maxRequestBodyBytes: number;
             /** Captured body bytes retained on a receipt; beyond this it is truncated. */
             readonly maxRetainedBodyBytes: 4096;
         };

package/dist/test-sink.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { CALLBACK_DEFERRAL_STATUS, CALLBACK_PENDING_DISCRIMINATOR, } from "./delivery.js";
 import { callbackSigningKeyIdSchema, deliveryIdSchema, endpointIdSchema, occurrenceIdSchema, projectIdSchema, scheduleIdSchema, testSinkDeliveryIdSchema, testSinkIdSchema, } from "./identifiers.js";
+import { CALLBACK_RECEIVER_MAX_BODY_BYTES } from "./callback-receiver.js";
 import { pageSchema } from "./protocol.js";
 import { CALLBACK_HEADERS, signatureHeaderSchema } from "./signatures.js";
 import { timestampSchema } from "./time.js";
@@ -106,8 +107,18 @@ export const TEST_SINK_BOUNDS = {
     maxRetainedDeliveries: 50,
     /** Sinks per project/environment. */
     maxSinksPerEnvironment: 10,
-    /** Largest request body a sink will read. Larger is refused unread. */
-    maxRequestBodyBytes: 65_536,
+    /**
+     * Largest request body a sink will read. Larger is refused unread.
+     *
+     * **A sink is a receiver, so this is the receiver's bound rather than one of
+     * its own.** It used to be a literal 65,536, which is exactly
+     * `SCHEDULING_BOUNDS.payloadBytes` — and therefore below every envelope
+     * carrying a maximum payload, so a customer rehearsing their largest legal
+     * delivery against a sink got the 413 they were rehearsing to avoid. The
+     * neighbours here are all justified by the sink running inside the API
+     * Worker's budget; this one never was.
+     */
+    maxRequestBodyBytes: CALLBACK_RECEIVER_MAX_BODY_BYTES,
     /** Captured body bytes retained on a receipt; beyond this it is truncated. */
     maxRetainedBodyBytes: 4_096,
 };

package/generated/v1/callback-receiver.json

@@ -132,7 +132,7 @@
       "maxHoldMs": 45000,
       "maxRetainedDeliveries": 50,
       "maxSinksPerEnvironment": 10,
-      "maxRequestBodyBytes": 65536,
+      "maxRequestBodyBytes": 69632,
       "maxRetainedBodyBytes": 4096
     },
     "clientErrorStatuses": [400, 401, 403, 404, 409, 410, 422],

package/generated/v1/openapi.json

@@ -23555,7 +23555,7 @@
         "maxHoldMs": 45000,
         "maxRetainedDeliveries": 50,
         "maxSinksPerEnvironment": 10,
-        "maxRequestBodyBytes": 65536,
+        "maxRequestBodyBytes": 69632,
         "maxRetainedBodyBytes": 4096
       },
       "clientErrorStatuses": [400, 401, 403, 404, 409, 410, 422],

package/package.json

@@ -25,6 +25,11 @@
       "import": "./dist/callback-ownership.js",
       "default": "./dist/callback-ownership.js"
     },
+    "./callback-receiver": {
+      "types": "./dist/callback-receiver.d.ts",
+      "import": "./dist/callback-receiver.js",
+      "default": "./dist/callback-receiver.js"
+    },
     "./callback-safety": {
       "types": "./dist/callback-safety.d.ts",
       "import": "./dist/callback-safety.js",
@@ -149,5 +154,5 @@
   },
   "sideEffects": false,
   "type": "module",
-  "version": "0.1.0-alpha.1"
+  "version": "0.1.0-alpha.2"
 }

package/dist/mcp.d.ts

@@ -1,51 +0,0 @@
-/**
- * Where the remote MCP surface lives, and what it tells an agent about itself.
- *
- * Stated once for the same reason `OAUTH_ROUTES` is: two readers must agree.
- * The router serves these paths and the protected-resource metadata document
- * advertises them, and a path that drifts from its advertisement is not a 404 —
- * it is a client that cannot authenticate and cannot say why.
- *
- * Outside `/v1`, following the convention `CLERK_WEBHOOK_PATH` and
- * `OAUTH_ROUTES` set. The `/v1` surface is the operation registry, every entry
- * of which is projected into OpenAPI, the SDK, an MCP tool and the contract
- * mock; the MCP endpoint is the transport those tools are served over, and a
- * transport that appeared in its own tool list would be a tool an agent could
- * point at itself.
- */
-export declare const MCP_ROUTES: {
-    /**
-     * The single Streamable HTTP endpoint. POST only; `GET` and `DELETE` answer
-     * `405`, because this endpoint opens no standalone event stream and mints no
-     * session to terminate.
-     *
-     * Served at this path **and** at the same path with a trailing slash, without
-     * a redirect between them. A `301`/`302` on a POST is rewritten by the fetch
-     * standard into a GET with the body dropped, so a client configured with the
-     * other spelling would have its opening request silently become the GET this
-     * endpoint refuses — and read that as "no MCP server here".
-     */
-    readonly endpoint: "/mcp";
-    /**
-     * RFC 9728 metadata for the MCP endpoint specifically.
-     *
-     * Served *beside* the origin's own document rather than instead of it. RFC
-     * 9728 §3.1 places the metadata for a resource with a path component at
-     * `/.well-known/oauth-protected-resource` followed by that path, so a client
-     * that treats `https://host/mcp` as the resource it is authorizing for
-     * constructs exactly this URL — and one that follows the `resource_metadata`
-     * link out of the `401` is sent here too. Both arrive at a document naming
-     * the same authorization server.
-     */
-    readonly protectedResourceMetadata: "/.well-known/oauth-protected-resource/mcp";
-};
-/**
- * What the server tells a model about itself, once, before any tool call.
- *
- * MCP calls this `instructions` and hands it to the model as context. It is
- * kept short and factual: an agent that has read the tool descriptions knows
- * what each one does, and what it cannot work out from them is the shape of the
- * authority it is acting under — which is the one thing that decides whether an
- * instruction like "create this in production" is even expressible.
- */
-export declare const MCP_INSTRUCTIONS: string;

package/dist/mcp.js

@@ -1,56 +0,0 @@
-/**
- * Where the remote MCP surface lives, and what it tells an agent about itself.
- *
- * Stated once for the same reason `OAUTH_ROUTES` is: two readers must agree.
- * The router serves these paths and the protected-resource metadata document
- * advertises them, and a path that drifts from its advertisement is not a 404 —
- * it is a client that cannot authenticate and cannot say why.
- *
- * Outside `/v1`, following the convention `CLERK_WEBHOOK_PATH` and
- * `OAUTH_ROUTES` set. The `/v1` surface is the operation registry, every entry
- * of which is projected into OpenAPI, the SDK, an MCP tool and the contract
- * mock; the MCP endpoint is the transport those tools are served over, and a
- * transport that appeared in its own tool list would be a tool an agent could
- * point at itself.
- */
-export const MCP_ROUTES = {
-    /**
-     * The single Streamable HTTP endpoint. POST only; `GET` and `DELETE` answer
-     * `405`, because this endpoint opens no standalone event stream and mints no
-     * session to terminate.
-     *
-     * Served at this path **and** at the same path with a trailing slash, without
-     * a redirect between them. A `301`/`302` on a POST is rewritten by the fetch
-     * standard into a GET with the body dropped, so a client configured with the
-     * other spelling would have its opening request silently become the GET this
-     * endpoint refuses — and read that as "no MCP server here".
-     */
-    endpoint: "/mcp",
-    /**
-     * RFC 9728 metadata for the MCP endpoint specifically.
-     *
-     * Served *beside* the origin's own document rather than instead of it. RFC
-     * 9728 §3.1 places the metadata for a resource with a path component at
-     * `/.well-known/oauth-protected-resource` followed by that path, so a client
-     * that treats `https://host/mcp` as the resource it is authorizing for
-     * constructs exactly this URL — and one that follows the `resource_metadata`
-     * link out of the `401` is sent here too. Both arrive at a document naming
-     * the same authorization server.
-     */
-    protectedResourceMetadata: "/.well-known/oauth-protected-resource/mcp",
-};
-/**
- * What the server tells a model about itself, once, before any tool call.
- *
- * MCP calls this `instructions` and hands it to the model as context. It is
- * kept short and factual: an agent that has read the tool descriptions knows
- * what each one does, and what it cannot work out from them is the shape of the
- * authority it is acting under — which is the one thing that decides whether an
- * instruction like "create this in production" is even expressible.
- */
-export const MCP_INSTRUCTIONS = [
-    "Greatwait schedules work and delivers it to an endpoint at the time asked for.",
-    "Every tool acts inside one organization, project and environment, fixed by the credential this connection was authorized with; no argument can name another, and there is no tool that moves between them.",
-    "Reads are safe to repeat. Writes are annotated, and the ones marked destructive settle or discard an occurrence that would otherwise have fired.",
-    "A refusal comes back as a problem document with a stable `code`: act on the code, not on the wording.",
-].join(" ");

package/dist/webhooks.d.ts

@@ -1,116 +0,0 @@
-import { z } from "zod";
-/**
- * Inbound webhook authenticity.
- *
- * Clerk delivers organization and membership changes through Svix, which signs
- * `<svix-id>.<svix-timestamp>.<raw body>` with HMAC-SHA256 under a secret minted
- * per endpoint. This module owns the encoding and the header vocabulary; the
- * adapter owns the key material and the constant-time comparison, exactly as
- * `signatures.ts` splits outbound callback signing.
- *
- * The split matters. Keeping the signed-byte construction in the contract layer
- * means every verifier — the Worker, a test, a future replay tool — signs the
- * same bytes, and the reasoning below is stated once instead of being
- * rediscovered by whoever writes the second one.
- */
-export declare const SVIX_HEADERS: {
-    readonly id: "svix-id";
-    readonly signature: "svix-signature";
-    readonly timestamp: "svix-timestamp";
-};
-/**
- * Where Clerk delivers organization and membership changes.
- *
- * Deliberately outside `/v1`. W1-07 enforces REST/MCP parity over every public
- * `/v1` operation, and a webhook ingress is not a customer-facing operation —
- * putting it there would either break that check or require an exception to it.
- * Follows the internal-route convention set by `/__greatwait/version`.
- *
- * **Here rather than in the Worker that serves it, since W4-08.** The smoke
- * asks a hosted stage whether this route is configured to accept a delivery,
- * and a script cannot import the API application. A second spelling of an
- * address Clerk is pointed at is one that can drift while both read as
- * correct.
- */
-export declare const CLERK_WEBHOOK_PATH = "/__greatwait/webhooks/clerk";
-/** Only `v1` exists. A new scheme is added alongside, never in place of. */
-export declare const WEBHOOK_SIGNATURE_SCHEME: "v1";
-/**
- * How far Clerk's clock may differ from ours before a delivery is stale.
- *
- * Svix's own guidance is five minutes, and matching it is deliberate: a tighter
- * window would reject legitimate deliveries during a retry burst, and a wider
- * one lengthens the replay window for a captured request.
- */
-export declare const WEBHOOK_TOLERANCE_SECONDS = 300;
-/**
- * A Svix message id. Deliberately a restricted charset rather than
- * `z.string().min(1)` — see `webhookSigningInput` for why the absence of `.`
- * here is a security property and not a formatting preference.
- */
-export declare const svixIdSchema: z.ZodString;
-/**
- * Seconds since the Unix epoch, as digits. No sign, no decimal point, no
- * exponent — `Number.parseInt` would happily accept `+1e9` and `12.5`, and both
- * would reach the signed bytes in a form we did not intend.
- */
-export declare const svixTimestampSchema: z.ZodString;
-/**
- * One `v1,<base64>` pair. Svix sends a space-delimited list so an endpoint can
- * be verified under both keys during rotation, which is why the verifier must
- * accept a match against *any* entry rather than parsing a single value.
- */
-export declare const svixSignatureEntryPattern: RegExp;
-export declare const svixSignatureHeaderSchema: z.ZodString;
-export declare const svixHeadersSchema: z.ZodObject<{
-    "svix-id": z.ZodString;
-    "svix-signature": z.ZodString;
-    "svix-timestamp": z.ZodString;
-}, z.core.$strip>;
-/**
- * Every `v1` signature offered in the header, base64 still encoded.
- *
- * Entries in other schemes are dropped rather than rejected: Svix may add a
- * scheme before we support it, and a delivery that carries both `v1` and a
- * future `v2` must still verify under `v1` instead of failing closed on the
- * presence of something newer.
- */
-export declare function webhookSignatureCandidates(header: string): readonly string[];
-/**
- * The exact bytes Svix signs: `<id>.<timestamp>.` followed by the raw body,
- * with no re-serialization anywhere in the path.
- *
- * Both prefix fields are validated rather than trusted, and — as with
- * `signingInput` for outbound callbacks — that is a security property. The
- * delimiter is `.`, so if either field could itself contain a `.` the encoding
- * would not be injective: an attacker holding one legitimate signature could
- * shift bytes across a delimiter, lengthening the id header while shortening
- * the body, and still verify.
- *
- * The argument here is slightly different from the outbound one, which relies
- * on both fields being fixed-width. `svixIdSchema` and `svixTimestampSchema`
- * admit no `.` at all, so splitting the signed content on its first two dots
- * recovers the id and the timestamp uniquely whatever their lengths. Variable
- * width is fine; a dot would not be.
- *
- * **Throws** on malformed input. Use `tryWebhookSigningInput` when verifying
- * headers off the wire, or a malformed-header probe becomes a 500.
- */
-export declare function webhookSigningInput(svixId: string, svixTimestamp: string, rawBody: Uint8Array): Uint8Array;
-/**
- * `webhookSigningInput` for untrusted input: `undefined` instead of a throw when
- * the headers are malformed.
- */
-export declare function tryWebhookSigningInput(svixId: string, svixTimestamp: string, rawBody: Uint8Array): Uint8Array | undefined;
-/**
- * Whether a delivery's timestamp is close enough to now.
- *
- * Rejects the future as firmly as the past. A signature dated an hour ahead is
- * not a clock-skew inconvenience — accepting it would hand an attacker who
- * captures one request an hour of replay window, so the comparison is on
- * absolute difference.
- *
- * Replay protection beyond this window belongs to the receiver, keyed on the
- * Svix message id; freshness alone does not make a delivery unique.
- */
-export declare function isWebhookTimestampFresh(svixTimestamp: string, nowMs: number, toleranceSeconds?: number): boolean;

package/dist/webhooks.js

@@ -1,161 +0,0 @@
-import { z } from "zod";
-/**
- * Inbound webhook authenticity.
- *
- * Clerk delivers organization and membership changes through Svix, which signs
- * `<svix-id>.<svix-timestamp>.<raw body>` with HMAC-SHA256 under a secret minted
- * per endpoint. This module owns the encoding and the header vocabulary; the
- * adapter owns the key material and the constant-time comparison, exactly as
- * `signatures.ts` splits outbound callback signing.
- *
- * The split matters. Keeping the signed-byte construction in the contract layer
- * means every verifier — the Worker, a test, a future replay tool — signs the
- * same bytes, and the reasoning below is stated once instead of being
- * rediscovered by whoever writes the second one.
- */
-export const SVIX_HEADERS = {
-    id: "svix-id",
-    signature: "svix-signature",
-    timestamp: "svix-timestamp",
-};
-/**
- * Where Clerk delivers organization and membership changes.
- *
- * Deliberately outside `/v1`. W1-07 enforces REST/MCP parity over every public
- * `/v1` operation, and a webhook ingress is not a customer-facing operation —
- * putting it there would either break that check or require an exception to it.
- * Follows the internal-route convention set by `/__greatwait/version`.
- *
- * **Here rather than in the Worker that serves it, since W4-08.** The smoke
- * asks a hosted stage whether this route is configured to accept a delivery,
- * and a script cannot import the API application. A second spelling of an
- * address Clerk is pointed at is one that can drift while both read as
- * correct.
- */
-export const CLERK_WEBHOOK_PATH = "/__greatwait/webhooks/clerk";
-/** Only `v1` exists. A new scheme is added alongside, never in place of. */
-export const WEBHOOK_SIGNATURE_SCHEME = "v1";
-/**
- * How far Clerk's clock may differ from ours before a delivery is stale.
- *
- * Svix's own guidance is five minutes, and matching it is deliberate: a tighter
- * window would reject legitimate deliveries during a retry burst, and a wider
- * one lengthens the replay window for a captured request.
- */
-export const WEBHOOK_TOLERANCE_SECONDS = 300;
-/**
- * A Svix message id. Deliberately a restricted charset rather than
- * `z.string().min(1)` — see `webhookSigningInput` for why the absence of `.`
- * here is a security property and not a formatting preference.
- */
-export const svixIdSchema = z
-    .string()
-    .regex(/^msg_[A-Za-z0-9]{1,64}$/u, 'must be "msg_" followed by up to 64 alphanumeric characters');
-/**
- * Seconds since the Unix epoch, as digits. No sign, no decimal point, no
- * exponent — `Number.parseInt` would happily accept `+1e9` and `12.5`, and both
- * would reach the signed bytes in a form we did not intend.
- */
-export const svixTimestampSchema = z
-    .string()
-    .regex(/^[0-9]{1,15}$/u, "must be a whole number of seconds since the epoch");
-/**
- * One `v1,<base64>` pair. Svix sends a space-delimited list so an endpoint can
- * be verified under both keys during rotation, which is why the verifier must
- * accept a match against *any* entry rather than parsing a single value.
- */
-export const svixSignatureEntryPattern = /^v1,[A-Za-z0-9+/]+={0,2}$/u;
-export const svixSignatureHeaderSchema = z
-    .string()
-    .min(1)
-    .refine((header) => header
-    .split(" ")
-    .filter((entry) => entry.length > 0)
-    .some((entry) => svixSignatureEntryPattern.test(entry)), "must contain at least one v1,<base64> signature");
-export const svixHeadersSchema = z.object({
-    [SVIX_HEADERS.id]: svixIdSchema,
-    [SVIX_HEADERS.signature]: svixSignatureHeaderSchema,
-    [SVIX_HEADERS.timestamp]: svixTimestampSchema,
-});
-/**
- * Every `v1` signature offered in the header, base64 still encoded.
- *
- * Entries in other schemes are dropped rather than rejected: Svix may add a
- * scheme before we support it, and a delivery that carries both `v1` and a
- * future `v2` must still verify under `v1` instead of failing closed on the
- * presence of something newer.
- */
-export function webhookSignatureCandidates(header) {
-    return header
-        .split(" ")
-        .filter((entry) => svixSignatureEntryPattern.test(entry))
-        .map((entry) => entry.slice(`${WEBHOOK_SIGNATURE_SCHEME},`.length));
-}
-/**
- * The exact bytes Svix signs: `<id>.<timestamp>.` followed by the raw body,
- * with no re-serialization anywhere in the path.
- *
- * Both prefix fields are validated rather than trusted, and — as with
- * `signingInput` for outbound callbacks — that is a security property. The
- * delimiter is `.`, so if either field could itself contain a `.` the encoding
- * would not be injective: an attacker holding one legitimate signature could
- * shift bytes across a delimiter, lengthening the id header while shortening
- * the body, and still verify.
- *
- * The argument here is slightly different from the outbound one, which relies
- * on both fields being fixed-width. `svixIdSchema` and `svixTimestampSchema`
- * admit no `.` at all, so splitting the signed content on its first two dots
- * recovers the id and the timestamp uniquely whatever their lengths. Variable
- * width is fine; a dot would not be.
- *
- * **Throws** on malformed input. Use `tryWebhookSigningInput` when verifying
- * headers off the wire, or a malformed-header probe becomes a 500.
- */
-export function webhookSigningInput(svixId, svixTimestamp, rawBody) {
-    const checkedId = svixIdSchema.parse(svixId);
-    const checkedTimestamp = svixTimestampSchema.parse(svixTimestamp);
-    const prefix = `${checkedId}.${checkedTimestamp}.`;
-    // Both fields are ASCII by construction, now that both have been validated, so
-    // UTF-8 encoding them is byte-identical to their code points.
-    const prefixBytes = new TextEncoder().encode(prefix);
-    const input = new Uint8Array(prefixBytes.length + rawBody.length);
-    input.set(prefixBytes, 0);
-    input.set(rawBody, prefixBytes.length);
-    return input;
-}
-/**
- * `webhookSigningInput` for untrusted input: `undefined` instead of a throw when
- * the headers are malformed.
- */
-export function tryWebhookSigningInput(svixId, svixTimestamp, rawBody) {
-    try {
-        return webhookSigningInput(svixId, svixTimestamp, rawBody);
-    }
-    catch (error) {
-        // Only a validation failure means "malformed headers". Anything else — an
-        // allocation failure on an oversized body, say — is a real fault and must
-        // not be reported to the caller as a bad signature.
-        if (error instanceof z.ZodError) {
-            return undefined;
-        }
-        throw error;
-    }
-}
-/**
- * Whether a delivery's timestamp is close enough to now.
- *
- * Rejects the future as firmly as the past. A signature dated an hour ahead is
- * not a clock-skew inconvenience — accepting it would hand an attacker who
- * captures one request an hour of replay window, so the comparison is on
- * absolute difference.
- *
- * Replay protection beyond this window belongs to the receiver, keyed on the
- * Svix message id; freshness alone does not make a delivery unique.
- */
-export function isWebhookTimestampFresh(svixTimestamp, nowMs, toleranceSeconds = WEBHOOK_TOLERANCE_SECONDS) {
-    if (!svixTimestampSchema.safeParse(svixTimestamp).success) {
-        return false;
-    }
-    const signedMs = Number(svixTimestamp) * 1000;
-    return Math.abs(nowMs - signedMs) <= toleranceSeconds * 1000;
-}