@greatwait/contracts 0.1.0-alpha.1

package/dist/problems.js

@@ -0,0 +1,104 @@
+import { z } from "zod";
+/**
+ * Refusals.
+ *
+ * Every non-2xx response is an RFC 9457 problem document. It carries a stable
+ * machine-readable `code`, a human `title`, and — where the caller can act on
+ * it — a `retry` hint and per-field `errors`. The legacy scheduler returned
+ * `{ "error": "invalid_cron" }` with no category, no correlation, and no way
+ * for a client to tell "retry this" from "never retry this"; every adapter and
+ * SDK invented its own interpretation.
+ *
+ * `code` is the contract. `title` and `detail` are prose and may change without
+ * being a breaking change; clients must never branch on them.
+ */
+export const PROBLEM_CATEGORIES = [
+    "authentication",
+    "authorization",
+    "conflict",
+    "invalid-request",
+    "not-found",
+    "rate-limited",
+    "unavailable",
+];
+export const problemCategorySchema = z.enum(PROBLEM_CATEGORIES);
+/**
+ * The stable refusal catalog. Adding a code is additive; removing one, or
+ * changing the category or status of an existing one, is breaking.
+ */
+export const PROBLEM_CODES = {
+    authentication_required: { category: "authentication", status: 401 },
+    // Separate from `credential_revoked` because the two mean different things to
+    // whoever is reading them. An expiry is the deadline a rotation already told
+    // you about; a revocation is somebody deciding this credential stops working
+    // now. One code for both would make a missed rotation window indistinguishable
+    // from a security event, and the client's remedy differs — rotate again
+    // versus find out who revoked it.
+    credential_expired: { category: "authentication", status: 401 },
+    credential_revoked: { category: "authentication", status: 401 },
+    endpoint_unverified: { category: "invalid-request", status: 422 },
+    idempotency_key_reused: { category: "conflict", status: 409 },
+    invalid_request: { category: "invalid-request", status: 400 },
+    not_found: { category: "not-found", status: 404 },
+    payload_too_large: { category: "invalid-request", status: 413 },
+    plan_limit_reached: { category: "conflict", status: 409 },
+    rate_limited: { category: "rate-limited", status: 429 },
+    scope_missing: { category: "authorization", status: 403 },
+    service_unavailable: { category: "unavailable", status: 503 },
+    // The resource is in a state that does not permit what was asked — resuming a
+    // cancelled schedule, archiving an active one. A conflict rather than an
+    // invalid request: the request is well formed and would succeed against the
+    // same resource in another state, so telling the caller to fix their request
+    // would send them looking in the wrong place. Distinct from `version_conflict`,
+    // which says somebody else got there first; this one says nobody did and the
+    // transition is still not available.
+    state_conflict: { category: "conflict", status: 409 },
+    test_to_live_escalation: { category: "authorization", status: 403 },
+    version_conflict: { category: "conflict", status: 409 },
+};
+export const problemCodeSchema = z.enum(Object.keys(PROBLEM_CODES));
+/** Whether repeating the identical request could succeed later. */
+export function isRetryable(code) {
+    const category = PROBLEM_CODES[code].category;
+    return category === "rate-limited" || category === "unavailable";
+}
+export const fieldErrorSchema = z.object({
+    /** JSON Pointer into the request body, e.g. `/schedule/expression`. */
+    pointer: z.string().startsWith("/"),
+    reason: z.string().min(1),
+});
+export const problemSchema = z.object({
+    code: problemCodeSchema,
+    /** Prose. Never branch on it. */
+    detail: z.string().min(1).optional(),
+    errors: z.array(fieldErrorSchema).optional(),
+    /** Seconds to wait before repeating the request; only on retryable codes. */
+    retryAfterSeconds: z.number().int().positive().optional(),
+    status: z.number().int().min(400).max(599),
+    /** Prose. Never branch on it. */
+    title: z.string().min(1),
+    /** Echoes the request correlation id so a report can be traced. */
+    traceId: z.string().min(1).optional(),
+    type: z.literal("about:blank"),
+});
+/**
+ * Builds a problem whose status and category cannot contradict its code, and
+ * which cannot carry a retry hint on a code that is not retryable.
+ */
+export function problem(code, options) {
+    if (options.retryAfterSeconds !== undefined && !isRetryable(code)) {
+        throw new RangeError(`${code} is not retryable, so it must not carry retryAfterSeconds`);
+    }
+    return problemSchema.parse({
+        code,
+        status: PROBLEM_CODES[code].status,
+        type: "about:blank",
+        ...(options.detail === undefined ? {} : { detail: options.detail }),
+        ...(options.errors === undefined ? {} : { errors: [...options.errors] }),
+        ...(options.retryAfterSeconds === undefined
+            ? {}
+            : { retryAfterSeconds: options.retryAfterSeconds }),
+        title: options.title,
+        ...(options.traceId === undefined ? {} : { traceId: options.traceId }),
+    });
+}

package/dist/protocol.d.ts

@@ -0,0 +1,308 @@
+import { z } from "zod";
+import type { Authority } from "./authority.js";
+import type { FieldError } from "./problems.js";
+/**
+ * Request and collection mechanics: paging, optimistic concurrency, and
+ * idempotent writes.
+ */
+/**
+ * Cursor paging only. Offsets drift when rows are inserted mid-scan, and a
+ * scheduling book changes constantly. The cursor is opaque: clients pass back
+ * exactly what they were given.
+ */
+export declare const PAGE_SIZE: {
+    readonly default: 25;
+    readonly max: 100;
+    readonly min: 1;
+};
+export declare const pageRequestSchema: z.ZodObject<{
+    cursor: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+export type PageRequest = z.infer<typeof pageRequestSchema>;
+/**
+ * A page of results.
+ *
+ * `freshness` is deliberately part of the contract rather than an
+ * implementation detail: cross-partition listings are served from a projection
+ * that may lag, and a client that cannot tell fresh from stale will present
+ * stale data as fact. `authoritative` means the answer came from the owning
+ * partition; `projected` means it may lag and carries the age.
+ */
+export declare const freshnessSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"authoritative">;
+}, z.core.$strip>, z.ZodObject<{
+    asOf: z.ZodString;
+    kind: z.ZodLiteral<"projected">;
+    lagSeconds: z.ZodNumber;
+}, z.core.$strip>], "kind">;
+export type Freshness = z.infer<typeof freshnessSchema>;
+/**
+ * The `projected` arm alone, for a response that is never authoritative.
+ *
+ * **A comment saying "always projected" is a claim; this is a check.** The
+ * forecast's own schema documented that arm as the only one it ever sends and
+ * then admitted both, so every reader had to handle a case the service cannot
+ * produce — and the two most useful fields, the age and the instant it was
+ * taken, were unreachable without narrowing that no consumer could justify.
+ * Naming the narrower shape moves the claim into the type.
+ */
+export declare const projectedFreshnessSchema: z.ZodObject<{
+    asOf: z.ZodString;
+    kind: z.ZodLiteral<"projected">;
+    lagSeconds: z.ZodNumber;
+}, z.core.$strip>;
+export type ProjectedFreshness = z.infer<typeof projectedFreshnessSchema>;
+export declare function pageSchema<TItem extends z.ZodTypeAny>(item: TItem): z.ZodObject<{
+    data: z.ZodArray<TItem>;
+    freshness: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"authoritative">;
+    }, z.core.$strip>, z.ZodObject<{
+        asOf: z.ZodString;
+        kind: z.ZodLiteral<"projected">;
+        lagSeconds: z.ZodNumber;
+    }, z.core.$strip>], "kind">;
+    nextCursor: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Where a page stopped.
+ *
+ * Every collection in this product is ordered by the instant a row was created
+ * and then by its identifier, so one position type serves all of them. The
+ * identifier is the tiebreak rather than decoration: two credentials issued in
+ * the same millisecond are ordinary, and an order that does not break the tie
+ * can show one of them twice and the other never.
+ */
+export interface PagePosition {
+    /** The creation instant of the last item on the page just served. */
+    readonly createdAtMs: number;
+    /** That item's identifier. */
+    readonly id: string;
+}
+/**
+ * The cursor a client is handed for the next page.
+ *
+ * Opaque by construction: it is a position and a tenancy fingerprint, and
+ * `docs/contracts/v1-conventions.md` says clients pass back exactly what they
+ * were given. It is deliberately *not* signed. A signature would imply the value
+ * carries authority, and it carries none — every listing is scoped by the
+ * principal before a cursor is even looked at.
+ */
+export declare function encodeCursor(authority: Authority, position: PagePosition): string;
+/**
+ * The position a cursor names, or nothing.
+ *
+ * Nothing covers every way a cursor can fail to be one this listing issued:
+ * not base64url, not JSON, the wrong shape, or minted under a different
+ * authority. They collapse into one answer on purpose — telling a caller *how*
+ * their cursor is wrong tells them what a valid one looks like, and the caller
+ * never constructs one anyway.
+ */
+export declare function decodeCursor(authority: Authority, cursor: string): PagePosition | undefined;
+export type PageRequestParse = {
+    readonly ok: true;
+    readonly page: PageRequest;
+} | {
+    readonly ok: false;
+    readonly errors: readonly FieldError[];
+};
+/**
+ * A page request, read from a URL's query string.
+ *
+ * Lives here rather than in a route so REST and MCP cannot disagree about what
+ * `limit=0`, `limit=abc` or a repeated parameter mean — the bounds and the
+ * default come from `pageRequestSchema` and are stated once.
+ *
+ * A **repeated** parameter is refused rather than resolved by taking the first
+ * or the last. `?limit=5&limit=500` is a caller who does not agree with
+ * themselves, and silently picking one makes their bug look like ours.
+ *
+ * Unknown parameters are ignored. A client written against a later version of
+ * this contract must not start failing against an earlier deployment, and that
+ * is the direction compatibility has to hold in.
+ */
+export declare function parsePageRequest(query: URLSearchParams): PageRequestParse;
+/**
+ * Every mutable resource carries a monotonically increasing `version`, surfaced
+ * as a strong ETag. A conditional write that loses the race is refused with
+ * `version_conflict` rather than silently overwriting — a cancel racing a
+ * replace must not resolve by luck.
+ */
+export declare const versionSchema: z.ZodNumber;
+export type Version = z.infer<typeof versionSchema>;
+export declare function toETag(version: Version): string;
+/** Parses a strong ETag, returning undefined for anything malformed or weak. */
+export declare function fromETag(etag: string): Version | undefined;
+/**
+ * The same rule as a schema, and deliberately the *same* rule: the refinement
+ * calls the parser rather than restating what it accepts, so a value the
+ * document says is valid cannot be one the service then refuses.
+ *
+ * The `regex` is kept beside the refinement because only the regex survives
+ * JSON Schema conversion — the published document carries the pattern, and the
+ * refinement is the extra strictness the OpenAPI preamble already discloses
+ * that a described schema does not capture.
+ */
+export declare const etagSchema: z.ZodString;
+/**
+ * Idempotency keys make an unsafe write safe to retry.
+ *
+ * The key is scoped to the authority tuple and the operation, so two projects
+ * may use the same key without colliding. A replay of the *same* request
+ * returns the original result with `replayed: true`. Reusing a key with a
+ * *different* request body is a `idempotency_key_reused` conflict, never a
+ * silent second write — that distinction is the whole point, and the legacy
+ * scheduler had no equivalent.
+ */
+export declare const idempotencyKeySchema: z.ZodString;
+export type IdempotencyKey = z.infer<typeof idempotencyKeySchema>;
+/**
+ * The scope a key was used in. Carried on the receipt rather than assumed,
+ * because an implementation that keys its receipt store on the idempotency key
+ * alone would return one tenant's result to another whenever both happened to
+ * send the same key. The scope is part of the record so that mistake cannot be
+ * made silently.
+ */
+export declare const idempotencyScopeSchema: z.ZodObject<{
+    environment: z.ZodString;
+    operation: z.ZodString;
+    organization: z.ZodString;
+    project: z.ZodString;
+}, z.core.$strip>;
+export type IdempotencyScope = z.infer<typeof idempotencyScopeSchema>;
+export declare const idempotencyReceiptSchema: z.ZodObject<{
+    requestFingerprint: z.ZodString;
+    replayed: z.ZodBoolean;
+    scope: z.ZodObject<{
+        environment: z.ZodString;
+        operation: z.ZodString;
+        organization: z.ZodString;
+        project: z.ZodString;
+    }, z.core.$strip>;
+    storedAt: z.ZodString;
+}, z.core.$strip>;
+export type IdempotencyReceipt = z.infer<typeof idempotencyReceiptSchema>;
+/**
+ * The canonical form of a request, as the receipt's `requestFingerprint`
+ * describes it: the operation name, then the body with object keys sorted and
+ * no insignificant whitespace.
+ *
+ * Here rather than in each adapter because the receipt schema says every
+ * adapter must compute it the same way, and a rule stated in a doc comment and
+ * implemented twice is a rule that holds until the second implementation. REST
+ * and MCP send the same create differently — one as a JSON body, one as tool
+ * arguments — and this is what makes "the same request" mean the same thing to
+ * both.
+ *
+ * Keys are ordered by UTF-16 code unit rather than by `localeCompare`, which is
+ * locale-dependent: a canonical form that depends on the machine's locale is
+ * not canonical. `undefined`-valued keys are dropped, because `JSON.stringify`
+ * drops them too and a caller who omitted a field and one who set it to
+ * `undefined` sent the same bytes.
+ */
+export declare function canonicalRequest(operation: string, body: unknown): string;
+/**
+ * The fingerprint stored on a receipt: SHA-256 of the canonical request, hex.
+ *
+ * Hashed rather than stored whole because a body may carry a payload up to
+ * `SCHEDULING_BOUNDS.payloadBytes`, and a receipt store that kept every request
+ * verbatim would cost the same as the schedules it protects. A cryptographic
+ * digest rather than the cheap hash `encodeCursor` uses: a collision there
+ * costs a confusing refusal, and a collision here would replay one request's
+ * result for a different request, which is the exact failure the receipt exists
+ * to prevent.
+ *
+ * Web Crypto, for the reason `identifiers.ts` gives for `getRandomValues`: it
+ * is a standard rather than a Cloudflare extension, so one implementation
+ * serves every runtime this package is read from.
+ */
+export declare function requestFingerprint(operation: string, body: unknown): Promise<string>;
+export type IdempotencyOutcome = {
+    readonly kind: "accepted";
+} | {
+    readonly kind: "replayed";
+} | {
+    readonly kind: "conflict";
+};
+/**
+ * Decides how a write carrying an idempotency key must be treated. Pure, so
+ * both the API and the MCP adapter reach the same answer.
+ *
+ * A receipt from a different scope is not this caller's key at all — it is
+ * accepted as a first use, never replayed and never a conflict.
+ */
+export declare function classifyIdempotency(incoming: {
+    readonly fingerprint: string;
+    readonly scope: IdempotencyScope;
+}, stored: IdempotencyReceipt | undefined): IdempotencyOutcome;
+/**
+ * The headers the mechanics above are carried in, as object schemas whose
+ * properties are the header names.
+ *
+ * The same shape `OperationDefinition.query` uses, for the same reason: a
+ * header a route reads and the published document does not carry is drift, and
+ * the way to prevent it is for both to derive from one schema. Names are
+ * standard where a standard exists — `If-Match` and `ETag` are RFC 9110's, and
+ * a conditional write invented a private spelling of them would be a
+ * conditional write no HTTP cache, proxy or client library understands.
+ *
+ * `Idempotency-Key` has no RFC yet; the name is the one the payments industry
+ * settled on and the one the IETF draft uses, which is what an integrator will
+ * already have a client for.
+ */
+export declare const CONCURRENCY_HEADERS: {
+    readonly etag: "ETag";
+    readonly idempotencyKey: "Idempotency-Key";
+    readonly ifMatch: "If-Match";
+    readonly replayed: "Idempotency-Replayed";
+};
+export declare const idempotencyRequestHeaderSchema: z.ZodObject<{
+    "Idempotency-Key": z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * A write for which idempotency is mandatory, rather than an optional
+ * protection a caller may opt into.
+ *
+ * Redelivery uses this shape because retrying an ambiguous redelivery request
+ * without the same key could send a second callback. Keeping it distinct from
+ * `idempotencyRequestHeaderSchema` lets schedule creation retain its published
+ * optional behavior without weakening the redelivery promise.
+ */
+export declare const requiredIdempotencyRequestHeaderSchema: z.ZodObject<{
+    "Idempotency-Key": z.ZodString;
+}, z.core.$strip>;
+export declare const conditionalRequestHeaderSchema: z.ZodObject<{
+    "If-Match": z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Required rather than optional, deliberately: an operation that declares this
+ * promises the header on every success, and a client that has to test for its
+ * presence before making a conditional write will write the untested branch
+ * wrong.
+ */
+export declare const versionResponseHeaderSchema: z.ZodObject<{
+    ETag: z.ZodString;
+}, z.core.$strip>;
+/**
+ * What a replayed write answers with, on top of the version.
+ *
+ * `replayed: true` is a promise `docs/contracts/v1-conventions.md` and
+ * `idempotencyReceiptSchema` have both made since W0-02 — the receipt's own
+ * field is documented as "true when **this response** replays an earlier
+ * identical request" — and until W2-02's review nothing carried it on the wire.
+ * A caller could not tell a replay from a first create, which makes the
+ * difference between "my retry worked" and "I created a second one" unanswerable
+ * from the response.
+ *
+ * Present only on a replay rather than `false` on every create: an absent
+ * header is the ordinary case, and a client that has to read a header to learn
+ * nothing happened is a client that will not read it.
+ */
+export declare const replayedResponseHeaderSchema: z.ZodObject<{
+    ETag: z.ZodString;
+    "Idempotency-Replayed": z.ZodOptional<z.ZodLiteral<"true">>;
+}, z.core.$strip>;
+/** Replay marker for an idempotent create whose result has no ETag. */
+export declare const idempotencyReplayResponseHeaderSchema: z.ZodObject<{
+    "Idempotency-Replayed": z.ZodOptional<z.ZodLiteral<"true">>;
+}, z.core.$strip>;