@greatwait/contracts 0.1.0-alpha.1

package/dist/callback-ownership.js

@@ -0,0 +1,71 @@
+/**
+ * Whether a receiver has to prove it owns a destination before Greatwait
+ * delivers anything there.
+ *
+ * **Zod-free and dependency-free on purpose.** Both the API Worker and the
+ * Scheduler Worker enforce this, and `apps/scheduler/src/contract-runtime.ts`
+ * records what reaching the contract barrel costs a Durable Object cold start.
+ * This module is an enumeration and two pure functions, so the subpath export
+ * `@greatwait/contracts/callback-ownership` costs the scheduler nothing.
+ *
+ * **Why the rule is stated once rather than twice.** Two sites resolve a
+ * destination for sending — `apps/api` when a schedule is created, and
+ * `apps/scheduler` at the moment of delivery — and they live in different
+ * workspaces. If each wrote its own status predicate they would eventually
+ * disagree, and the shape of that disagreement is a schedule the product
+ * accepts and then silently never delivers. `sendableStatuses` is the single
+ * statement both build their query from.
+ */
+/**
+ * The answers this product understands, in the order a person would read them
+ * as increasing strictness.
+ *
+ * `not-required` does **not** mean verification is gone. A destination may
+ * still answer its ownership challenge, and doing so still records the instant
+ * it proved possession of the secret. It means nothing waits for that.
+ */
+export const CALLBACK_OWNERSHIP_POLICIES = [
+    "not-required",
+    "required",
+];
+/**
+ * What an unset variable means.
+ *
+ * Not required, decided on 2026-08-18 after the first invited customers walked
+ * the product: nobody writes an HMAC responder to try a scheduler, so requiring
+ * one before the first delivery cost the whole top of the funnel to buy a
+ * property that `evaluateCallbackUrl`, the delivery rate limits and the request
+ * signature already defend from other directions. See W4-09.
+ */
+export const DEFAULT_CALLBACK_OWNERSHIP_POLICY = "not-required";
+/**
+ * Read the policy a deployment declares, or refuse to run.
+ *
+ * **An unrecognised value throws rather than falling back.** The entire reason
+ * this is configuration is that turning the requirement on or off should be a
+ * visible decision; a typo, a rename, or a half-finished edit silently read as
+ * `not-required` would hand back exactly the off-switch the setting exists to
+ * make visible. Absent is a decision — it is the documented default — and
+ * `"requred"` is not.
+ */
+export function readCallbackOwnershipPolicy(value) {
+    if (value === undefined || value === "") {
+        return DEFAULT_CALLBACK_OWNERSHIP_POLICY;
+    }
+    const known = CALLBACK_OWNERSHIP_POLICIES.find((policy) => policy === value);
+    if (known === undefined) {
+        throw new Error(`GREATWAIT_CALLBACK_OWNERSHIP is ${JSON.stringify(value)}, which this service does not understand. Known values: ${CALLBACK_OWNERSHIP_POLICIES.join(", ")}. Leave it unset for ${DEFAULT_CALLBACK_OWNERSHIP_POLICY}.`);
+    }
+    return known;
+}
+/**
+ * The destination statuses a send may resolve under a policy, as a query
+ * builds its `IN` list from.
+ *
+ * `disabled` is absent from both and always will be: disabling is terminal and
+ * is the one refusal this setting does not reach. A caller that widened this to
+ * include it would be delivering to a destination somebody turned off.
+ */
+export function sendableStatuses(policy) {
+    return policy === "required" ? ["verified"] : ["pending", "verified"];
+}

package/dist/callback-safety.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Stable reasons a callback URL can fail the syntax/address policy.
+ *
+ * DNS is deliberately not represented here: names are resolved and every
+ * returned address is passed through `isPublicCallbackAddress` by the caller.
+ *
+ * **That caller is endpoint creation and verification, and since 2026-08-11 it
+ * is nowhere else.** This comment used to end "and immediately before a send",
+ * which FXO-1566 made false when it removed the send-time re-resolution. What
+ * runs at send time is `evaluateCallbackUrl` alone — a string check, which
+ * cannot see where a hostname points now. FXO-1575 measured what the platform
+ * does with the resulting window; see
+ * `docs/delivery/follow-ups/fxo-1575-what-global-fetch-strictly-public-blocks.md`.
+ */
+export declare const CALLBACK_URL_REJECTION_REASONS: readonly ["invalid_url", "https_required", "credentials_forbidden", "fragment_forbidden", "port_forbidden", "hostname_forbidden", "address_forbidden"];
+export type CallbackUrlRejectionReason = (typeof CALLBACK_URL_REJECTION_REASONS)[number];
+/** 32 random bytes encoded without padding, after this visible namespace. */
+export declare const CALLBACK_ENDPOINT_SECRET_PATTERN: RegExp;
+type CallbackUrlEvaluation = {
+    readonly hostname: string;
+    readonly ok: true;
+    /** The WHATWG-canonical URL, including its path/query. */
+    readonly url: string;
+} | {
+    readonly ok: false;
+    readonly reason: CallbackUrlRejectionReason;
+};
+/** Evaluate the URL-only half of the callback destination policy. */
+export declare function evaluateCallbackUrl(value: string): CallbackUrlEvaluation;
+/**
+ * Whether a literal address is globally reachable callback unicast space.
+ *
+ * The function accepts WHATWG IPv4 number forms because the URL parser accepts
+ * them. For example, `0x7f000001`, `0177.0.0.1`, and `2130706433` all classify
+ * as loopback rather than escaping the range checks through spelling alone.
+ */
+export declare function isPublicCallbackAddress(address: string): boolean;
+export {};

package/dist/callback-safety.js

@@ -0,0 +1,403 @@
+/**
+ * Stable reasons a callback URL can fail the syntax/address policy.
+ *
+ * DNS is deliberately not represented here: names are resolved and every
+ * returned address is passed through `isPublicCallbackAddress` by the caller.
+ *
+ * **That caller is endpoint creation and verification, and since 2026-08-11 it
+ * is nowhere else.** This comment used to end "and immediately before a send",
+ * which FXO-1566 made false when it removed the send-time re-resolution. What
+ * runs at send time is `evaluateCallbackUrl` alone — a string check, which
+ * cannot see where a hostname points now. FXO-1575 measured what the platform
+ * does with the resulting window; see
+ * `docs/delivery/follow-ups/fxo-1575-what-global-fetch-strictly-public-blocks.md`.
+ */
+export const CALLBACK_URL_REJECTION_REASONS = [
+    "invalid_url",
+    "https_required",
+    "credentials_forbidden",
+    "fragment_forbidden",
+    "port_forbidden",
+    "hostname_forbidden",
+    "address_forbidden",
+];
+/** 32 random bytes encoded without padding, after this visible namespace. */
+export const CALLBACK_ENDPOINT_SECRET_PATTERN = /^ptsk_(?:live|test)_[A-Za-z0-9_-]{43}$/u;
+/**
+ * IANA IPv4 Special-Purpose Address Space entries that are not globally
+ * reachable, last updated 2025-10-09, plus multicast and one cloud-platform
+ * virtual address. The two globally reachable exceptions in 192.0.0.0/24 are
+ * handled before this table.
+ */
+const FORBIDDEN_IPV4_CIDRS = [
+    ipv4Cidr("0.0.0.0", 8),
+    ipv4Cidr("10.0.0.0", 8),
+    ipv4Cidr("100.64.0.0", 10),
+    ipv4Cidr("127.0.0.0", 8),
+    ipv4Cidr("169.254.0.0", 16),
+    ipv4Cidr("172.16.0.0", 12),
+    ipv4Cidr("192.0.0.0", 24),
+    ipv4Cidr("192.0.2.0", 24),
+    ipv4Cidr("192.88.99.0", 24),
+    ipv4Cidr("192.168.0.0", 16),
+    ipv4Cidr("198.18.0.0", 15),
+    ipv4Cidr("198.51.100.0", 24),
+    ipv4Cidr("203.0.113.0", 24),
+    // IPv4 multicast is not unicast callback space.
+    ipv4Cidr("224.0.0.0", 4),
+    ipv4Cidr("240.0.0.0", 4),
+    // Azure's host virtual IP exposes platform services from inside a VM/VNet.
+    ipv4Cidr("168.63.129.16", 32),
+];
+const GLOBALLY_REACHABLE_IPV4_EXCEPTIONS = new Set([
+    ipv4Number([192, 0, 0, 9]),
+    ipv4Number([192, 0, 0, 10]),
+]);
+/**
+ * Fail-closed IPv6 public-unicast allowlist.
+ *
+ * This is the ALLOCATED portion of IANA's "IPv6 Global Unicast Address Space"
+ * registry, last updated 2025-10-10. The broad 2001::/23 IETF allocation is
+ * intentionally replaced by only its entries whose IANA special-purpose
+ * records say `Globally Reachable: True` (special registry last updated
+ * 2025-10-09). 2001:db8::/32 is subtracted below because it sits inside the
+ * allocated 2001:c00::/23 block. Unlisted and RESERVED space therefore fails
+ * closed when IANA changes the registry.
+ *
+ * Translation/mapping ranges (including 64:ff9b::/96, IPv4-compatible,
+ * IPv4-mapped, 6to4 and Teredo) are absent on purpose. That prevents an IPv4
+ * dotted or hexadecimal tail from smuggling a forbidden destination through
+ * a superficially IPv6 literal.
+ */
+const PUBLIC_IPV6_CIDRS = [
+    // Globally reachable exceptions inside IANA's otherwise non-global /23.
+    ipv6Cidr("2001:1::1", 128),
+    ipv6Cidr("2001:1::2", 128),
+    ipv6Cidr("2001:1::3", 128),
+    ipv6Cidr("2001:3::", 32),
+    ipv6Cidr("2001:4:112::", 48),
+    ipv6Cidr("2001:20::", 28),
+    ipv6Cidr("2001:30::", 28),
+    // RIR/IANA allocations from the global-unicast registry.
+    ipv6Cidr("2001:200::", 23),
+    ipv6Cidr("2001:400::", 23),
+    ipv6Cidr("2001:600::", 23),
+    ipv6Cidr("2001:800::", 22),
+    ipv6Cidr("2001:c00::", 23),
+    ipv6Cidr("2001:e00::", 23),
+    ipv6Cidr("2001:1200::", 23),
+    ipv6Cidr("2001:1400::", 22),
+    ipv6Cidr("2001:1800::", 23),
+    ipv6Cidr("2001:1a00::", 23),
+    ipv6Cidr("2001:1c00::", 22),
+    ipv6Cidr("2001:2000::", 19),
+    ipv6Cidr("2001:4000::", 23),
+    ipv6Cidr("2001:4200::", 23),
+    ipv6Cidr("2001:4400::", 23),
+    ipv6Cidr("2001:4600::", 23),
+    ipv6Cidr("2001:4800::", 23),
+    ipv6Cidr("2001:4a00::", 23),
+    ipv6Cidr("2001:4c00::", 23),
+    ipv6Cidr("2001:5000::", 20),
+    ipv6Cidr("2001:8000::", 19),
+    ipv6Cidr("2001:a000::", 20),
+    ipv6Cidr("2001:b000::", 20),
+    ipv6Cidr("2003::", 18),
+    ipv6Cidr("2400::", 12),
+    ipv6Cidr("2410::", 12),
+    ipv6Cidr("2600::", 12),
+    ipv6Cidr("2610::", 23),
+    ipv6Cidr("2620::", 23),
+    ipv6Cidr("2630::", 12),
+    ipv6Cidr("2800::", 12),
+    ipv6Cidr("2a00::", 12),
+    ipv6Cidr("2a10::", 12),
+    ipv6Cidr("2c00::", 12),
+];
+const FORBIDDEN_IPV6_CIDRS = [ipv6Cidr("2001:db8::", 32)];
+const FORBIDDEN_NAME_SUFFIXES = [
+    "localhost",
+    "local",
+    "localdomain",
+    "internal",
+    "home.arpa",
+];
+/**
+ * Runtime names are denied even when their DNS currently returns public IPs:
+ * allowing the product to call itself turns any future internal route into a
+ * customer-controlled reflection surface. Both custom-domain forms follow the
+ * deployable host vocabulary; workers.dev/pages.dev cover provider hostnames.
+ *
+ * **Two zones, because a rename does not retire a name.** W0-11 moved every
+ * address onto `greatwait.dev`, where a stage is `api.greatwait.dev` and
+ * `api-staging.greatwait.dev` — a shape the `flowxo.com` pattern does not
+ * match, so for as long as this recognised only the old form a customer could
+ * aim a callback at the product's own API and get exactly the reflection
+ * surface this rule exists to deny. The old form stays because the old names
+ * keep resolving until their custom domains are detached, and because a DNS
+ * record somebody forgets is precisely what this should still refuse.
+ */
+const GREATWAIT_RUNTIME_NAME = /^(?:greatwait-(?:api|app|scheduler|contract-mock|postgres-runtime)(?:-[a-z0-9-]+)?\.flowxo\.com|(?:api|app|scheduler|contract-mock|postgres-runtime)(?:-[a-z0-9-]+)?\.greatwait\.dev)$/u;
+const GREATWAIT_PROVIDER_NAME = /^greatwait-(?:api|app|scheduler|contract-mock|postgres-runtime)(?:-[a-z0-9-]+)?(?:\..+)?\.(?:workers|pages)\.dev$/u;
+const GREATWAIT_WORKER_NAME = /^greatwait-(?:api|app|scheduler|contract-mock|postgres-runtime)(?:-[a-z0-9-]+)?$/u;
+/** Evaluate the URL-only half of the callback destination policy. */
+export function evaluateCallbackUrl(value) {
+    if (value.trim() !== value) {
+        return reject("invalid_url");
+    }
+    let parsed;
+    try {
+        parsed = new URL(value);
+    }
+    catch {
+        return reject("invalid_url");
+    }
+    if (parsed.protocol !== "https:") {
+        return reject("https_required");
+    }
+    // URL.username cannot distinguish `https://@host` after canonicalization,
+    // so inspect the raw authority as well as the parsed credential fields.
+    if (parsed.username.length > 0 ||
+        parsed.password.length > 0 ||
+        rawAuthorityContainsUserinfo(value)) {
+        return reject("credentials_forbidden");
+    }
+    // Likewise, URL.hash is empty for a trailing `#`; policy forbids the
+    // delimiter, not merely a non-empty fragment value.
+    if (value.includes("#")) {
+        return reject("fragment_forbidden");
+    }
+    // WHATWG removes the canonical default `:443`, so an empty parsed port means
+    // the effective port is 443 whether the caller wrote it or omitted it.
+    if (parsed.port !== "") {
+        return reject("port_forbidden");
+    }
+    if (rawHostnameHasEmptyLabel(value)) {
+        return reject("hostname_forbidden");
+    }
+    const hostname = unbracket(parsed.hostname).toLowerCase();
+    if (hostname.length === 0) {
+        return reject("invalid_url");
+    }
+    if (isIpv6Text(hostname) || isCanonicalIpv4(hostname)) {
+        if (!isPublicCallbackAddress(hostname)) {
+            return reject("address_forbidden");
+        }
+    }
+    else if (!isAllowedRegisteredName(hostname)) {
+        return reject("hostname_forbidden");
+    }
+    return { hostname, ok: true, url: parsed.href };
+}
+/**
+ * Whether a literal address is globally reachable callback unicast space.
+ *
+ * The function accepts WHATWG IPv4 number forms because the URL parser accepts
+ * them. For example, `0x7f000001`, `0177.0.0.1`, and `2130706433` all classify
+ * as loopback rather than escaping the range checks through spelling alone.
+ */
+export function isPublicCallbackAddress(address) {
+    if (address.length === 0 || address.trim() !== address) {
+        return false;
+    }
+    const hasOpeningBracket = address.startsWith("[");
+    const hasClosingBracket = address.endsWith("]");
+    if (hasOpeningBracket !== hasClosingBracket) {
+        return false;
+    }
+    const bare = unbracket(address).toLowerCase();
+    if (hasOpeningBracket && !isIpv6Text(bare)) {
+        return false;
+    }
+    if (isIpv6Text(bare)) {
+        const parsed = parseIpv6(bare);
+        if (parsed === undefined) {
+            return false;
+        }
+        if (FORBIDDEN_IPV6_CIDRS.some((cidr) => ipv6InCidr(parsed, cidr))) {
+            return false;
+        }
+        return PUBLIC_IPV6_CIDRS.some((cidr) => ipv6InCidr(parsed, cidr));
+    }
+    const parsed = parseWhatwgIpv4(bare);
+    if (parsed === undefined) {
+        return false;
+    }
+    if (GLOBALLY_REACHABLE_IPV4_EXCEPTIONS.has(parsed)) {
+        return true;
+    }
+    return !FORBIDDEN_IPV4_CIDRS.some((cidr) => ipv4InCidr(parsed, cidr));
+}
+function reject(reason) {
+    return { ok: false, reason };
+}
+function rawAuthorityContainsUserinfo(value) {
+    return rawAuthority(value)?.includes("@") ?? false;
+}
+function rawHostnameHasEmptyLabel(value) {
+    const authority = rawAuthority(value);
+    if (authority === undefined) {
+        return false;
+    }
+    const withoutUserinfo = authority.slice(authority.lastIndexOf("@") + 1);
+    // Colons inside brackets are IPv6 separators, never DNS-label separators.
+    if (withoutUserinfo.startsWith("[")) {
+        return false;
+    }
+    const portStart = withoutUserinfo.lastIndexOf(":");
+    const rawHostname = portStart === -1 ? withoutUserinfo : withoutUserinfo.slice(0, portStart);
+    // WHATWG treats percent-encoded dots as label separators too.
+    const hostname = rawHostname.replace(/%2e/giu, ".");
+    return (hostname.startsWith(".") ||
+        hostname.endsWith(".") ||
+        hostname.includes(".."));
+}
+function rawAuthority(value) {
+    const schemeEnd = value.indexOf("://");
+    if (schemeEnd < 0) {
+        return undefined;
+    }
+    const authorityStart = schemeEnd + 3;
+    const possibleEnds = ["/", "?", "#"]
+        .map((delimiter) => value.indexOf(delimiter, authorityStart))
+        .filter((index) => index >= 0);
+    const authorityEnd = possibleEnds.length === 0 ? value.length : Math.min(...possibleEnds);
+    return value.slice(authorityStart, authorityEnd);
+}
+function isAllowedRegisteredName(hostname) {
+    if (hostname.startsWith(".") ||
+        hostname.endsWith(".") ||
+        hostname.includes("..") ||
+        hostname.length > 253) {
+        return false;
+    }
+    if (FORBIDDEN_NAME_SUFFIXES.some((suffix) => hostname === suffix || hostname.endsWith(`.${suffix}`))) {
+        return false;
+    }
+    if (GREATWAIT_RUNTIME_NAME.test(hostname) ||
+        GREATWAIT_PROVIDER_NAME.test(hostname) ||
+        GREATWAIT_WORKER_NAME.test(hostname)) {
+        return false;
+    }
+    return hostname
+        .split(".")
+        .every((label) => label.length > 0 &&
+        label.length <= 63 &&
+        /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/u.test(label));
+}
+function unbracket(value) {
+    return value.startsWith("[") && value.endsWith("]")
+        ? value.slice(1, -1)
+        : value;
+}
+function isIpv6Text(value) {
+    return value.includes(":");
+}
+function isCanonicalIpv4(value) {
+    return /^\d+\.\d+\.\d+\.\d+$/u.test(value);
+}
+function parseWhatwgIpv4(value) {
+    if (value.startsWith(".") ||
+        value.endsWith(".") ||
+        value.includes("..") ||
+        ["/", "@", "?", "#", "[", "]"].some((char) => value.includes(char))) {
+        return undefined;
+    }
+    let hostname;
+    try {
+        hostname = new URL(`http://${value}/`).hostname;
+    }
+    catch {
+        return undefined;
+    }
+    const parts = hostname.split(".");
+    if (parts.length !== 4 || parts.some((part) => !/^\d{1,3}$/u.test(part))) {
+        return undefined;
+    }
+    const octets = parts.map(Number);
+    if (octets.some((octet) => octet > 255)) {
+        return undefined;
+    }
+    return ipv4Number(octets);
+}
+function parseStrictIpv4(value) {
+    const parts = value.split(".");
+    if (parts.length !== 4 ||
+        parts.some((part) => !/^(?:0|[1-9]\d{0,2})$/u.test(part))) {
+        return undefined;
+    }
+    const octets = parts.map(Number);
+    return octets.some((octet) => octet > 255) ? undefined : octets;
+}
+function ipv4Number(octets) {
+    const [a = 0, b = 0, c = 0, d = 0] = octets;
+    return ((a * 256 + b) * 256 + c) * 256 + d;
+}
+function ipv4Cidr(address, prefix) {
+    const parsed = parseStrictIpv4(address);
+    if (parsed === undefined) {
+        throw new Error(`Invalid internal IPv4 CIDR address: ${address}`);
+    }
+    return { address: ipv4Number(parsed), prefix };
+}
+function ipv4InCidr(address, cidr) {
+    const blockSize = 2 ** (32 - cidr.prefix);
+    return (Math.floor(address / blockSize) === Math.floor(cidr.address / blockSize));
+}
+function parseIpv6(value) {
+    if (value.includes("%") || value.length === 0) {
+        return undefined;
+    }
+    let source = value;
+    if (source.includes(".")) {
+        const tailStart = source.lastIndexOf(":") + 1;
+        const ipv4 = parseStrictIpv4(source.slice(tailStart));
+        if (tailStart === 0 || ipv4 === undefined) {
+            return undefined;
+        }
+        const [a = 0, b = 0, c = 0, d = 0] = ipv4;
+        source = `${source.slice(0, tailStart)}${(a * 256 + b).toString(16)}:${(c * 256 +
+            d).toString(16)}`;
+    }
+    const compression = source.indexOf("::");
+    if (compression !== -1 && compression !== source.lastIndexOf("::")) {
+        return undefined;
+    }
+    let segments;
+    if (compression === -1) {
+        segments = source.split(":");
+        if (segments.length !== 8) {
+            return undefined;
+        }
+    }
+    else {
+        const left = source.slice(0, compression);
+        const right = source.slice(compression + 2);
+        const leftSegments = left.length === 0 ? [] : left.split(":");
+        const rightSegments = right.length === 0 ? [] : right.split(":");
+        const omitted = 8 - leftSegments.length - rightSegments.length;
+        if (omitted < 1) {
+            return undefined;
+        }
+        segments = [
+            ...leftSegments,
+            ...Array(omitted).fill("0"),
+            ...rightSegments,
+        ];
+    }
+    if (segments.some((segment) => !/^[0-9a-f]{1,4}$/u.test(segment))) {
+        return undefined;
+    }
+    return segments.reduce((result, segment) => (result << 16n) | BigInt(`0x${segment}`), 0n);
+}
+function ipv6Cidr(address, prefix) {
+    const parsed = parseIpv6(address);
+    if (parsed === undefined) {
+        throw new Error(`Invalid internal IPv6 CIDR address: ${address}`);
+    }
+    return { address: parsed, prefix };
+}
+function ipv6InCidr(address, cidr) {
+    const shift = BigInt(128 - cidr.prefix);
+    return address >> shift === cidr.address >> shift;
+}

package/dist/compatibility.d.ts

@@ -0,0 +1,82 @@
+import { z } from "zod";
+/**
+ * What may change, and what that costs.
+ *
+ * The contract version is dated and moves independently of any deployment. A
+ * release that ships twice a day must not imply the contract changed twice a
+ * day, and a contract change must be visible even when no code deployed.
+ */
+export declare const CONTRACT_VERSION: "2026-08-22";
+export declare const contractVersionSchema: z.ZodLiteral<"2026-08-22">;
+/**
+ * Three kinds of change, and only the first is free.
+ *
+ * - `additive`: existing clients keep working untouched. New optional request
+ *   field, new response field, new enum member a client may *send*, new
+ *   endpoint, new scope, new problem code, new member of a vocabulary the
+ *   artifact publishes open. A new member a client must *receive* from a closed
+ *   list is breaking — it can break exhaustive parsing.
+ * - `breaking`: some conforming client stops working. Removing or renaming a
+ *   field, making an optional request field required, narrowing a type,
+ *   removing an enum member a client may send, changing a problem code's
+ *   status or category, changing what is signed.
+ * - `deployment-only`: no wire effect at all. Internal refactor, added index,
+ *   new log field, prose in `title` or `detail`. Prose is `internal`: `title`
+ *   and `detail` are explicitly not part of the contract, so editing them is
+ *   not a change to a response field.
+ *
+ * The distinction is enforceable rather than advisory: `classifyChange` is
+ * exercised by fixtures, so "we thought it was additive" is a testable claim.
+ */
+export declare const CHANGE_KINDS: readonly ["additive", "breaking", "deployment-only"];
+export declare const changeKindSchema: z.ZodEnum<{
+    additive: "additive";
+    breaking: "breaking";
+    "deployment-only": "deployment-only";
+}>;
+export type ChangeKind = z.infer<typeof changeKindSchema>;
+/**
+ * Declared as runtime arrays, not bare type unions, so a test can iterate the
+ * product and prove every combination is classified.
+ *
+ * A hand-written table of cases cannot do that: a combination nobody thought
+ * of is untested, and a subject or operation added later is untested by
+ * default — in a function whose whole job is to tell a caller whether a change
+ * will break customers.
+ */
+export declare const CHANGE_SUBJECTS: readonly ["endpoint", "enum-member", "internal", "problem-code", "request-field", "response-field", "scope", "signature-input"];
+export type ChangeSubject = (typeof CHANGE_SUBJECTS)[number];
+export declare const CHANGE_OPERATIONS: readonly ["changed", "added", "narrowed", "removed", "required", "widened"];
+export type ChangeOperation = (typeof CHANGE_OPERATIONS)[number];
+export interface ContractChange {
+    readonly operation: ChangeOperation;
+    /** Whether a client may send this, as opposed to only receiving it. */
+    readonly clientSupplied?: boolean;
+    /**
+     * Whether the published artifact describes this vocabulary as open.
+     *
+     * A received enum member is breaking because a client that generated a
+     * validator from a closed list rejects the first value that postdates its
+     * code. That is a fact about the *artifact*, not about the vocabulary, and
+     * two of ours are deliberately published without an `enum` — problem codes,
+     * and callback attempt diagnostics — so that growing them is genuinely free.
+     * Without this flag the classifier answers `breaking` for those too, which
+     * reads as a rule while being an artifact detail nobody can check from here.
+     *
+     * Set it only where the projection really opens the list. Claiming it for a
+     * closed vocabulary is how a breaking change ships as additive.
+     */
+    readonly openVocabulary?: boolean;
+    readonly subject: ChangeSubject;
+}
+/**
+ * Classifies a proposed change. Deliberately conservative: anything not
+ * demonstrably safe is `breaking`, because the cost of wrongly calling a
+ * breaking change additive is borne by customers.
+ */
+export declare function classifyChange(change: ContractChange): ChangeKind;
+export interface CompatibilityVerdict {
+    readonly kind: ChangeKind;
+    readonly requiresNewContractVersion: boolean;
+}
+export declare function assess(change: ContractChange): CompatibilityVerdict;