@greatwait/contracts 0.1.0-alpha.1

package/dist/protocol.js

@@ -0,0 +1,515 @@
+import { z } from "zod";
+import { environmentIdSchema, organizationIdSchema, projectIdSchema, } from "./identifiers.js";
+import { timestampSchema } from "./time.js";
+/**
+ * Request and collection mechanics: paging, optimistic concurrency, and
+ * idempotent writes.
+ */
+/* -------------------------------------------------------------------------- */
+/* Pagination                                                                 */
+/* -------------------------------------------------------------------------- */
+/**
+ * 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 const PAGE_SIZE = { default: 25, max: 100, min: 1 };
+export const pageRequestSchema = z.object({
+    cursor: z.string().min(1).optional(),
+    limit: z
+        .number()
+        .int()
+        .min(PAGE_SIZE.min)
+        .max(PAGE_SIZE.max)
+        .default(PAGE_SIZE.default),
+});
+/**
+ * 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 const freshnessSchema = z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("authoritative") }),
+    z.object({
+        asOf: timestampSchema,
+        kind: z.literal("projected"),
+        lagSeconds: z.number().int().nonnegative(),
+    }),
+]);
+/**
+ * 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 const projectedFreshnessSchema = z.object({
+    asOf: timestampSchema,
+    kind: z.literal("projected"),
+    lagSeconds: z.number().int().nonnegative(),
+});
+export function pageSchema(item) {
+    return z.object({
+        data: z.array(item),
+        freshness: freshnessSchema,
+        /** Absent when there is no further page. */
+        nextCursor: z.string().min(1).optional(),
+    });
+}
+/**
+ * A 32-bit FNV-1a hash of the authority tuple, hex encoded.
+ *
+ * This is **not** an authorization control and must never be read as one. The
+ * listing a cursor is presented to is scoped by the verified principal, so a
+ * forged or stolen cursor can at most reposition a walk inside the thief's own
+ * project — it cannot name another one. What the fingerprint buys is a clear
+ * refusal instead of a confusing empty page when a cursor is carried across
+ * projects or environments, which is why a non-cryptographic hash is enough and
+ * why a collision costs nothing.
+ */
+function authorityFingerprint(authority) {
+    const material = [
+        authority.organization,
+        authority.project,
+        authority.environment,
+        authority.environmentKind,
+    ].join("\u0000");
+    let hash = 0x811c9dc5;
+    for (let index = 0; index < material.length; index += 1) {
+        hash ^= material.charCodeAt(index);
+        // The FNV prime 0x01000193, applied as shifts so the arithmetic stays
+        // inside 32 bits: 2^24 + 2^8 + 2^7 + 2^4 + 2^1 + 2^0. The 2^24 term is easy
+        // to leave out and hard to notice — without it this multiplies by 403, and
+        // a hash that disperses acceptably on this input shape looks fine while no
+        // longer being the algorithm its own name promises.
+        hash =
+            (hash +
+                (hash << 1) +
+                (hash << 4) +
+                (hash << 7) +
+                (hash << 8) +
+                (hash << 24)) >>>
+                0;
+    }
+    return hash.toString(16).padStart(8, "0");
+}
+function base64UrlEncode(value) {
+    return btoa(value)
+        .replace(/\+/gu, "-")
+        .replace(/\//gu, "_")
+        .replace(/=+$/u, "");
+}
+/** Undefined for anything that is not base64url at all. */
+function base64UrlDecode(value) {
+    if (!/^[A-Za-z0-9_-]+$/u.test(value)) {
+        return undefined;
+    }
+    // The padding is restored for readers rather than for `atob`, which
+    // implements WHATWG forgiving-base64 and accepts an unpadded value already.
+    // Stated so nobody later reads this line as load-bearing: what actually
+    // rejects a malformed cursor is the character check above and the throw
+    // below, which fires for a length that cannot be base64 at all.
+    const padded = value
+        .replace(/-/gu, "+")
+        .replace(/_/gu, "/")
+        .padEnd(Math.ceil(value.length / 4) * 4, "=");
+    try {
+        return atob(padded);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * 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 function encodeCursor(authority, position) {
+    return base64UrlEncode(JSON.stringify({
+        a: position.createdAtMs,
+        i: position.id,
+        k: authorityFingerprint(authority),
+    }));
+}
+/**
+ * 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 function decodeCursor(authority, cursor) {
+    const decoded = base64UrlDecode(cursor);
+    if (decoded === undefined) {
+        return undefined;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(decoded);
+    }
+    catch {
+        return undefined;
+    }
+    const shape = z
+        .object({
+        a: z.number().int().nonnegative(),
+        i: z.string().min(1),
+        k: z.string(),
+    })
+        .safeParse(parsed);
+    if (!shape.success || shape.data.k !== authorityFingerprint(authority)) {
+        return undefined;
+    }
+    return { createdAtMs: shape.data.a, id: shape.data.i };
+}
+/** Query values arrive as strings; only a whole number may become one. */
+function asNumberIfInteger(value) {
+    return /^-?\d+$/u.test(value) ? Number(value) : value;
+}
+/**
+ * The page parameters, and which of them are numeric — derived from
+ * `pageRequestSchema` rather than written out again.
+ *
+ * Every projection reads the parameter list out of this same schema's JSON
+ * Schema. A hand-written list here agrees with it exactly until somebody adds a
+ * field: the document would publish it and the generated client would send it,
+ * while the service silently ignored it. That is the drift the operation
+ * registry exists to prevent, one line below the schema it prevents it for.
+ *
+ * Numeric-ness has to be derived too rather than assumed from the name. Coercing
+ * every all-digit value would turn a cursor that happened to be digits into a
+ * number, and a cursor is opaque precisely so its encoding can change.
+ *
+ * **Only numeric coercion is derived.** A future page parameter that is neither
+ * a string nor a number — a boolean, say — would arrive here as the text
+ * `"true"` and be refused by its own schema. That is the safe direction and it
+ * is still a trap, so whoever adds one adds its coercion beside this list.
+ *
+ * Computed once: `toJSONSchema` is not cheap enough to run per request.
+ */
+const PAGE_PARAMETERS = Object.entries(z.toJSONSchema(pageRequestSchema, {
+    io: "input",
+    unrepresentable: "any",
+}).properties ?? {}).map(([name, schema]) => [
+    name,
+    schema.type === "integer" || schema.type === "number",
+]);
+/**
+ * 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 function parsePageRequest(query) {
+    const errors = [];
+    const raw = {};
+    for (const [field, numeric] of PAGE_PARAMETERS) {
+        const values = query.getAll(field);
+        if (values.length > 1) {
+            errors.push({
+                pointer: `/${field}`,
+                reason: "must be given at most once",
+            });
+            continue;
+        }
+        const value = values[0];
+        if (value === undefined) {
+            continue;
+        }
+        raw[field] = numeric ? asNumberIfInteger(value) : value;
+    }
+    if (errors.length > 0) {
+        return { errors, ok: false };
+    }
+    const parsed = pageRequestSchema.safeParse(raw);
+    if (parsed.success) {
+        return { ok: true, page: parsed.data };
+    }
+    return {
+        errors: parsed.error.issues.map((issue) => ({
+            pointer: `/${issue.path.join("/")}`,
+            reason: issue.message,
+        })),
+        ok: false,
+    };
+}
+/* -------------------------------------------------------------------------- */
+/* Optimistic concurrency                                                     */
+/* -------------------------------------------------------------------------- */
+/**
+ * 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 const versionSchema = z.number().int().positive();
+/**
+ * A strong entity tag over a version: a quoted decimal, and nothing else.
+ *
+ * Written once and read by both `fromETag` and `etagSchema`, so what the
+ * document publishes as an `If-Match` value and what a route will actually
+ * accept cannot disagree. Weak tags (`W/"3"`) and the wildcard (`*`) are
+ * deliberately not matched — a weak comparison is defined to ignore exactly the
+ * differences a lost update consists of, and `*` asks a question about
+ * existence rather than about version.
+ *
+ * **No leading zero.** RFC 9110 defines strong comparison as byte-for-byte, so
+ * `"01"` is simply not the tag `"1"` — and this pattern read `\d+` until
+ * W2-02's tests found that `fromETag('"01"')` answered `1`, honouring a
+ * precondition against a version whose tag the service never issued. `toETag`
+ * cannot produce that spelling, so every one that arrives was hand-made.
+ *
+ * The digit ceiling only keeps the input bounded; `fromETag` below applies the
+ * rule that matters, which is that the value survives being a `Number`. Past
+ * 2^53 it does not: `"9007199254740993"` parses to 9007199254740992 and would
+ * match a *different* version, which is worse than being refused.
+ */
+const ETAG_PATTERN = /^"([1-9][0-9]{0,18})"$/u;
+const ETAG_MESSAGE = 'must be a strong entity tag, as returned by ETag: "7"';
+export function toETag(version) {
+    return `"${version}"`;
+}
+/** Parses a strong ETag, returning undefined for anything malformed or weak. */
+export function fromETag(etag) {
+    const match = ETAG_PATTERN.exec(etag.trim());
+    if (match === null) {
+        return undefined;
+    }
+    const parsed = Number(match[1]);
+    return Number.isSafeInteger(parsed) ? parsed : 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 const etagSchema = z
+    .string()
+    .regex(ETAG_PATTERN, ETAG_MESSAGE)
+    .refine((value) => fromETag(value) !== undefined, ETAG_MESSAGE);
+/* -------------------------------------------------------------------------- */
+/* Idempotency                                                                */
+/* -------------------------------------------------------------------------- */
+/**
+ * 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 const idempotencyKeySchema = z
+    .string()
+    .min(16, "must be at least 16 characters so keys do not collide by accident")
+    .max(255)
+    .regex(/^[\x20-\x7e]+$/u, "must be printable ASCII");
+/**
+ * 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 const idempotencyScopeSchema = z.object({
+    environment: environmentIdSchema,
+    operation: z.string().min(1),
+    organization: organizationIdSchema,
+    project: projectIdSchema,
+});
+export const idempotencyReceiptSchema = z.object({
+    /**
+     * Hash of the canonical request the key was first used with. Canonical
+     * means: the operation name, then the request body serialized with object
+     * keys sorted lexicographically and no insignificant whitespace. Every
+     * adapter must compute it the same way or REST and MCP will disagree about
+     * whether two requests are the same.
+     */
+    requestFingerprint: z.string().min(1),
+    /** True when this response replays an earlier identical request. */
+    replayed: z.boolean(),
+    scope: idempotencyScopeSchema,
+    storedAt: timestampSchema,
+});
+/**
+ * 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 function canonicalRequest(operation, body) {
+    return `${operation}\n${canonicalJson(body)}`;
+}
+function canonicalJson(value) {
+    if (value === null || typeof value !== "object") {
+        // `undefined` at the root serializes to nothing, which would make an absent
+        // body and an empty one the same fingerprint. They are the same request, so
+        // that is correct — but stated, because it looks like an oversight.
+        return JSON.stringify(value) ?? "null";
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map((item) => canonicalJson(item)).join(",")}]`;
+    }
+    const fields = Object.entries(value)
+        .filter(([, field]) => field !== undefined)
+        .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
+        .map(([name, field]) => `${JSON.stringify(name)}:${canonicalJson(field)}`);
+    return `{${fields.join(",")}}`;
+}
+/**
+ * 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 async function requestFingerprint(operation, body) {
+    const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(canonicalRequest(operation, body)));
+    return [...new Uint8Array(digest)]
+        .map((byte) => byte.toString(16).padStart(2, "0"))
+        .join("");
+}
+function sameScope(a, b) {
+    return (a.environment === b.environment &&
+        a.operation === b.operation &&
+        a.organization === b.organization &&
+        a.project === b.project);
+}
+/**
+ * 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 function classifyIdempotency(incoming, stored) {
+    if (stored === undefined || !sameScope(stored.scope, incoming.scope)) {
+        return { kind: "accepted" };
+    }
+    return stored.requestFingerprint === incoming.fingerprint
+        ? { kind: "replayed" }
+        : { kind: "conflict" };
+}
+/* -------------------------------------------------------------------------- */
+/* Headers on the wire                                                        */
+/* -------------------------------------------------------------------------- */
+/**
+ * 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 const CONCURRENCY_HEADERS = {
+    etag: "ETag",
+    idempotencyKey: "Idempotency-Key",
+    ifMatch: "If-Match",
+    replayed: "Idempotency-Replayed",
+};
+export const idempotencyRequestHeaderSchema = z.object({
+    [CONCURRENCY_HEADERS.idempotencyKey]: idempotencyKeySchema.optional(),
+});
+/**
+ * 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 const requiredIdempotencyRequestHeaderSchema = z.object({
+    [CONCURRENCY_HEADERS.idempotencyKey]: idempotencyKeySchema,
+});
+export const conditionalRequestHeaderSchema = z.object({
+    [CONCURRENCY_HEADERS.ifMatch]: etagSchema.optional(),
+});
+/**
+ * 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 const versionResponseHeaderSchema = z.object({
+    [CONCURRENCY_HEADERS.etag]: etagSchema,
+});
+/**
+ * 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 const replayedResponseHeaderSchema = z.object({
+    [CONCURRENCY_HEADERS.etag]: etagSchema,
+    [CONCURRENCY_HEADERS.replayed]: z.literal("true").optional(),
+});
+/** Replay marker for an idempotent create whose result has no ETag. */
+export const idempotencyReplayResponseHeaderSchema = z.object({
+    [CONCURRENCY_HEADERS.replayed]: z.literal("true").optional(),
+});