@greatwait/contracts 0.1.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 FlowXO LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,77 @@
+# @greatwait/contracts
+
+The public contracts for [Greatwait](https://greatwait.dev): the schemas every
+response is parsed with, the stable refusal catalog, the operation registry, and
+the generated OpenAPI documents.
+
+> **Invited alpha.** This package publishes on the `alpha` dist-tag and has no
+> `latest`. Install it explicitly, and pin the exact version in anything you
+> care about.
+
+```bash
+npm install @greatwait/contracts@alpha
+```
+
+Most people arrive here through [`@greatwait/api-client`](https://www.npmjs.com/package/@greatwait/api-client),
+which depends on this package. Install it directly when you want the schemas
+without the client — to validate a callback body, to generate code, or to hold
+your own client against the published shapes.
+
+## Parsing a response
+
+```javascript
+import { responseSchemaFor } from "@greatwait/contracts";
+
+const schedule = responseSchemaFor("schedules.create").parse(body);
+```
+
+Schemas are [Zod](https://zod.dev) and are the same objects the service
+validates with, so a shape is stated once rather than mirrored. The JSON Schema
+form of each is shipped too, under `generated/v1/schemas/`, for consumers that
+are not JavaScript.
+
+## What ships
+
+| Path                                    | What it is                                                                                  |
+| --------------------------------------- | ------------------------------------------------------------------------------------------- |
+| `generated/v1/openapi.json`             | The public API, as OpenAPI                                                                  |
+| `generated/v1/openapi.mock.json`        | The contract mock's surface, labelled separately so it can never be read as the product API |
+| `generated/v1/schemas/`                 | JSON Schema per operation, request and response                                             |
+| `generated/v1/snippets/`                | curl, JavaScript and MCP examples per operation                                             |
+| `generated/v1/first-value-journey.json` | The canonical first-value sequence, as data                                                 |
+| `generated/v1/policy-matrix.json`       | Who may call what, derived from the registry                                                |
+| `generated/v1/manifest.json`            | The index of everything above, with the contract version                                    |
+
+All of it is generated from one registry, so a change to an operation changes
+every artifact at once. Nothing here is hand-maintained beside the code it
+describes.
+
+## The conventions the schemas encode
+
+- **Identifiers** are opaque, prefixed and server-assigned. Compare them for
+  equality and nothing else.
+- **Time** is RFC 3339, UTC, milliseconds, literal `Z`. Durations are whole
+  seconds. An IANA timezone appears only beside a `cron` recurrence.
+- **Collections** are cursor-paged, never offset-paged, and every page carries
+  `freshness` so a client can tell an authoritative answer from a projected one.
+- **Concurrency** is a monotonic `version` surfaced as a strong `ETag`; a
+  conditional write sends it back in `If-Match` and is refused
+  `version_conflict` rather than resolving by luck.
+- **Refusals** are RFC 9457 problem documents with a stable `code`. Adding a
+  code is additive; removing one, or changing its category or status, is
+  breaking.
+
+`CONTRACT_VERSION` is the dated version of all of this. It moves independently
+of any deployment, because a service that ships twice a day must not imply the
+contract changed twice a day.
+
+## The first-value journey
+
+`generated/v1/first-value-journey.json` is the one sequence that takes a
+developer from a credential to an observed callback — the same steps the curl
+quickstart, the JavaScript quickstart and the website walkthrough render. Read
+it rather than restating the steps: each entry carries the operation, the
+method, the path, the scopes it needs, the refusals it can produce and what to
+do about each of them.
+
+MIT licensed. Issues: <https://github.com/flowxo/greatwait/issues>.

package/dist/authority.d.ts

@@ -0,0 +1,217 @@
+import { z } from "zod";
+import type { ProblemCode } from "./problems.js";
+/**
+ * Who is asking, and what they may do.
+ *
+ * The authority tuple `(organization, project, environment)` comes from a
+ * verified principal — a Clerk session, an API credential, or an OAuth access
+ * token. It is never read from a request body, a query parameter, or a path
+ * segment. A client can no more select its own organization than it can select
+ * its own password.
+ *
+ * The legacy scheduler put `:owner` and `:partition` in the path and trusted
+ * them. Those segments are migration inputs for W6 and are never authorization
+ * here. See `docs/architecture/legacy-provenance.md`.
+ */
+/**
+ * Environments are immutable and hard-separated. A test principal cannot name,
+ * infer, mutate, or fire a live resource, and no operation escalates from test
+ * to live.
+ */
+/**
+ * Both kinds, in a fixed order.
+ *
+ * Exported so a caller that must handle every kind — provisioning a project,
+ * say — iterates the list rather than writing the two out and quietly missing a
+ * third if one is ever added.
+ */
+export declare const ENVIRONMENT_KINDS_IN_ORDER: readonly ["test", "live"];
+export declare const environmentKindSchema: z.ZodEnum<{
+    test: "test";
+    live: "live";
+}>;
+export type EnvironmentKind = z.infer<typeof environmentKindSchema>;
+export declare const authoritySchema: z.ZodObject<{
+    environment: z.ZodString;
+    environmentKind: z.ZodEnum<{
+        test: "test";
+        live: "live";
+    }>;
+    organization: z.ZodString;
+    project: z.ZodString;
+}, z.core.$strip>;
+export type Authority = z.infer<typeof authoritySchema>;
+/**
+ * The initial scope vocabulary. Scopes are `resource:action`, lower case, and
+ * additive — a new scope is a compatible change, removing or narrowing one is
+ * not.
+ *
+ * Granted scopes are always the intersection of what was requested, what the
+ * client is permitted, and what the granting member's current role allows.
+ * Nothing here can exceed a human's own access.
+ */
+export declare const SCOPES: readonly ["credentials:administer", "credentials:read", "credentials:write", "endpoints:read", "endpoints:write", "forecast:read", "grants:read", "grants:write", "occurrences:read", "occurrences:redeliver", "projects:read", "projects:write", "schedules:read", "schedules:write", "usage:read"];
+export declare const scopeSchema: z.ZodEnum<{
+    "credentials:administer": "credentials:administer";
+    "credentials:read": "credentials:read";
+    "credentials:write": "credentials:write";
+    "endpoints:read": "endpoints:read";
+    "endpoints:write": "endpoints:write";
+    "forecast:read": "forecast:read";
+    "grants:read": "grants:read";
+    "grants:write": "grants:write";
+    "occurrences:read": "occurrences:read";
+    "occurrences:redeliver": "occurrences:redeliver";
+    "projects:read": "projects:read";
+    "projects:write": "projects:write";
+    "schedules:read": "schedules:read";
+    "schedules:write": "schedules:write";
+    "usage:read": "usage:read";
+}>;
+export type Scope = z.infer<typeof scopeSchema>;
+/**
+ * Expands granted scopes with the reads their writes imply, so a caller that
+ * holds `schedules:write` need not also be granted `schedules:read`.
+ */
+export declare function effectiveScopes(granted: readonly Scope[]): Set<Scope>;
+/**
+ * The three ways a principal can be established.
+ *
+ * Hoisted out of `principalSchema` so the operation registry can say which of
+ * them an operation accepts. Before that, "who may call this" was carried
+ * nowhere: the published document derived its security requirement from
+ * `scopes` alone, so `credentials.create` advertised API-credential
+ * authentication for a route that refuses an API credential outright.
+ *
+ * - `api-credential` — a scoped key. Its authority tuple is fixed at issue.
+ * - `oauth` — a delegated grant, capped by the granting member's role. Its
+ *   authority tuple is fixed at consent.
+ * - `session` — a signed-in human, in a browser. **This is the only kind whose
+ *   authority tuple is not fixed in advance**: a member belongs to an
+ *   organization and may act in any project inside it, so the request names the
+ *   project and environment and the service resolves the tuple against that
+ *   member's own organization. Naming is not widening — `resolveAuthority`
+ *   refuses a project the organization does not own, with the same answer it
+ *   gives for one that does not exist.
+ */
+export declare const PRINCIPAL_KINDS: readonly ["api-credential", "oauth", "session"];
+export declare const principalKindSchema: z.ZodEnum<{
+    "api-credential": "api-credential";
+    oauth: "oauth";
+    session: "session";
+}>;
+export type PrincipalKind = z.infer<typeof principalKindSchema>;
+export declare const principalSchema: z.ZodObject<{
+    authority: z.ZodObject<{
+        environment: z.ZodString;
+        environmentKind: z.ZodEnum<{
+            test: "test";
+            live: "live";
+        }>;
+        organization: z.ZodString;
+        project: z.ZodString;
+    }, z.core.$strip>;
+    scopes: z.ZodArray<z.ZodEnum<{
+        "credentials:administer": "credentials:administer";
+        "credentials:read": "credentials:read";
+        "credentials:write": "credentials:write";
+        "endpoints:read": "endpoints:read";
+        "endpoints:write": "endpoints:write";
+        "forecast:read": "forecast:read";
+        "grants:read": "grants:read";
+        "grants:write": "grants:write";
+        "occurrences:read": "occurrences:read";
+        "occurrences:redeliver": "occurrences:redeliver";
+        "projects:read": "projects:read";
+        "projects:write": "projects:write";
+        "schedules:read": "schedules:read";
+        "schedules:write": "schedules:write";
+        "usage:read": "usage:read";
+    }>>;
+    via: z.ZodEnum<{
+        "api-credential": "api-credential";
+        oauth: "oauth";
+        session: "session";
+    }>;
+}, z.core.$strip>;
+export type Principal = z.infer<typeof principalSchema>;
+export interface AccessRequest {
+    readonly principal: Principal;
+    /** The authority the resource actually belongs to. */
+    readonly resource: Authority;
+    readonly scope: Scope;
+}
+export type AccessDecision = {
+    readonly allowed: true;
+} | {
+    readonly allowed: false;
+    readonly reason: AccessRefusal;
+};
+/**
+ * Why access was refused. `not-found` exists so a cross-tenant read is
+ * indistinguishable from a genuine miss: telling a caller that a resource
+ * exists but belongs to someone else is itself a disclosure.
+ */
+export type AccessRefusal = "not-found" | "scope-missing";
+/**
+ * Whether a principal may act on an already-resolved resource.
+ *
+ * Order matters. Any mismatch in the authority tuple — organization, project,
+ * or environment — is `not-found`, and that is deliberate: distinguishing
+ * "exists but is not yours" from "does not exist" is an existence oracle. A
+ * test-scoped credential holding a live identifier must not be able to learn
+ * that the identifier is real, and environment is part of the authority tuple
+ * exactly so it gets the same treatment as organization.
+ *
+ * Escalation is refused before this point, on *intent* rather than on a
+ * resolved resource — see `decideEnvironmentIntent`. Tenancy is checked before
+ * scope so a refusal can never be used to probe another tenant.
+ */
+export declare function decideAccess(request: AccessRequest): AccessDecision;
+export type EnvironmentIntentDecision = {
+    readonly allowed: true;
+} | {
+    readonly allowed: false;
+    readonly reason: "test-to-live-escalation";
+};
+/**
+ * Whether a principal may act in an environment it has *asked* for — creating
+ * a live schedule, say.
+ *
+ * This is the one place escalation is named, because here the caller stated
+ * the target rather than being told a resource exists. Keeping it separate
+ * from `decideAccess` means a distinct, actionable refusal without leaking
+ * whether any particular resource is real.
+ */
+export declare function decideEnvironmentIntent(principal: Principal, requested: EnvironmentKind): EnvironmentIntentDecision;
+/**
+ * The wire refusal for every possible decision, so no adapter invents one.
+ *
+ * Typed against `ProblemCode` rather than a hand-written union, so renaming a
+ * code in the catalog fails here instead of silently returning one that is no
+ * longer catalogued.
+ */
+export declare function problemCodeForRefusal(reason: AccessRefusal | "principal-kind" | "test-to-live-escalation"): ProblemCode;
+/**
+ * Where a session names the project and environment it is acting in.
+ *
+ * **Headers rather than query parameters, and that is an authentication
+ * decision rather than a stylistic one.** These two values are part of
+ * establishing *who is asking* — together with the Clerk session they produce
+ * the authority tuple that a key or a token carries intrinsically. Declaring
+ * them as request parameters would put them in the published parameter list of
+ * every operation a signed-in member can reach, which means the generated MCP
+ * tools would gain a `project` argument. A count stood here — "fourteen
+ * operations" — and was wrong by one before anybody read it twice; the number is
+ * derivable from the registry and nothing checks a number written in prose.
+ * `packages/mcp-tools/src/invoke.ts` already refuses that
+ * argument by name, on the grounds that an agent which sent it "believes it
+ * asked for another project", and offering it would read as consent.
+ *
+ * A cache keyed on the URL alone would serve one project's page to another, so
+ * every response that varies on these must say so in `Vary`.
+ */
+export declare const SESSION_AUTHORITY_HEADERS: {
+    readonly environment: "Greatwait-Environment";
+    readonly project: "Greatwait-Project";
+};

package/dist/authority.js

@@ -0,0 +1,261 @@
+import { z } from "zod";
+import { environmentIdSchema, organizationIdSchema, projectIdSchema, } from "./identifiers.js";
+/**
+ * Who is asking, and what they may do.
+ *
+ * The authority tuple `(organization, project, environment)` comes from a
+ * verified principal — a Clerk session, an API credential, or an OAuth access
+ * token. It is never read from a request body, a query parameter, or a path
+ * segment. A client can no more select its own organization than it can select
+ * its own password.
+ *
+ * The legacy scheduler put `:owner` and `:partition` in the path and trusted
+ * them. Those segments are migration inputs for W6 and are never authorization
+ * here. See `docs/architecture/legacy-provenance.md`.
+ */
+/**
+ * Environments are immutable and hard-separated. A test principal cannot name,
+ * infer, mutate, or fire a live resource, and no operation escalates from test
+ * to live.
+ */
+/**
+ * Both kinds, in a fixed order.
+ *
+ * Exported so a caller that must handle every kind — provisioning a project,
+ * say — iterates the list rather than writing the two out and quietly missing a
+ * third if one is ever added.
+ */
+export const ENVIRONMENT_KINDS_IN_ORDER = ["test", "live"];
+export const environmentKindSchema = z.enum(ENVIRONMENT_KINDS_IN_ORDER);
+export const authoritySchema = z.object({
+    environment: environmentIdSchema,
+    environmentKind: environmentKindSchema,
+    organization: organizationIdSchema,
+    project: projectIdSchema,
+});
+/**
+ * The initial scope vocabulary. Scopes are `resource:action`, lower case, and
+ * additive — a new scope is a compatible change, removing or narrowing one is
+ * not.
+ *
+ * Granted scopes are always the intersection of what was requested, what the
+ * client is permitted, and what the granting member's current role allows.
+ * Nothing here can exceed a human's own access.
+ */
+export const SCOPES = [
+    /**
+     * Act on a credential somebody else issued.
+     *
+     * **The one scope `member` does not hold, and the reason the role ceiling
+     * still distinguishes anything.** Every other scope is ordinary developer
+     * work; this one is the difference between managing your own access and
+     * managing everybody's. It gates rotation as well as revocation, because a
+     * rotation with a zero overlap retires the current key immediately —
+     * `credentialRotationRequestSchema` says so on the field — so gating one and
+     * leaving the other open would be a restriction with a door beside it.
+     *
+     * `credentials:write` still covers acting on your *own*, which is why this is
+     * a third scope rather than a narrowing of that one: an operation declares
+     * the scopes it always needs, and "whose credential is this" is a property of
+     * the row rather than of the route.
+     */
+    "credentials:administer",
+    "credentials:read",
+    "credentials:write",
+    "endpoints:read",
+    "endpoints:write",
+    "forecast:read",
+    /**
+     * See which applications a member has connected, and disconnect one.
+     *
+     * **Two scopes no delegated grant can ever carry, and that is the point.**
+     * `grantableScopes` derives what an OAuth client may ask for from the
+     * operations that accept an OAuth principal, and both grant operations accept
+     * only a signed-in member — so an application cannot request them. That is
+     * `oauth.ts`'s rule made structural: an application holding a grant must not
+     * be able to enumerate its rivals, still less disconnect them.
+     *
+     * They exist because W4-08 moved the grant surface onto `/v1`, where every
+     * operation declares what it needs. A published route that enforces nothing
+     * is a surface whose authorization story nobody can read.
+     */
+    "grants:read",
+    "grants:write",
+    "occurrences:read",
+    "occurrences:redeliver",
+    "projects:read",
+    /**
+     * Create a project, with its `test` and `live` environments.
+     *
+     * **Added by W4-08, and it is the scope that makes the product usable by
+     * somebody nobody has set up by hand.** Until then `provisionProject` was
+     * reachable from no deployed surface at all: an invited member with a Clerk
+     * organization and no project saw "No projects" and had no move, and the only
+     * way to give them one was SQL against the control plane — which is the
+     * hidden operator path that story's criterion 3 forbids.
+     *
+     * `member` holds it, like every scope but `credentials:administer`. A project
+     * is a container: creating one grants its creator nothing they did not
+     * already have, and the ceiling still bounds everything inside it. Making it
+     * admin-only would also have broken the sentence `policy.ts` states about
+     * what `admin` means — acting on somebody else's access, and nothing else.
+     */
+    "projects:write",
+    "schedules:read",
+    "schedules:write",
+    /**
+     * See what this project was charged for.
+     *
+     * A scope of its own rather than a corner of `schedules:read`, because the
+     * two answer to different people: a service account that lists schedules to
+     * keep them in step has no business reading a bill, and somebody
+     * reconciling one has no need to enumerate the book. Read-only by
+     * construction — there is no `usage:write`, because a usage fact is written
+     * by a settlement and by nothing a customer can ask for.
+     */
+    "usage:read",
+];
+export const scopeSchema = z.enum(SCOPES);
+/** Read scopes implied by the matching write scope. */
+const IMPLIED_BY_WRITE = {
+    "credentials:write": "credentials:read",
+    "endpoints:write": "endpoints:read",
+    "grants:write": "grants:read",
+    "projects:write": "projects:read",
+    "schedules:write": "schedules:read",
+};
+/**
+ * Expands granted scopes with the reads their writes imply, so a caller that
+ * holds `schedules:write` need not also be granted `schedules:read`.
+ */
+export function effectiveScopes(granted) {
+    const effective = new Set(granted);
+    for (const scope of granted) {
+        const implied = IMPLIED_BY_WRITE[scope];
+        if (implied) {
+            effective.add(implied);
+        }
+    }
+    return effective;
+}
+/**
+ * The three ways a principal can be established.
+ *
+ * Hoisted out of `principalSchema` so the operation registry can say which of
+ * them an operation accepts. Before that, "who may call this" was carried
+ * nowhere: the published document derived its security requirement from
+ * `scopes` alone, so `credentials.create` advertised API-credential
+ * authentication for a route that refuses an API credential outright.
+ *
+ * - `api-credential` — a scoped key. Its authority tuple is fixed at issue.
+ * - `oauth` — a delegated grant, capped by the granting member's role. Its
+ *   authority tuple is fixed at consent.
+ * - `session` — a signed-in human, in a browser. **This is the only kind whose
+ *   authority tuple is not fixed in advance**: a member belongs to an
+ *   organization and may act in any project inside it, so the request names the
+ *   project and environment and the service resolves the tuple against that
+ *   member's own organization. Naming is not widening — `resolveAuthority`
+ *   refuses a project the organization does not own, with the same answer it
+ *   gives for one that does not exist.
+ */
+export const PRINCIPAL_KINDS = ["api-credential", "oauth", "session"];
+export const principalKindSchema = z.enum(PRINCIPAL_KINDS);
+export const principalSchema = z.object({
+    authority: authoritySchema,
+    scopes: z.array(scopeSchema).min(1),
+    /** How the principal was established, for audit and refusal messages. */
+    via: principalKindSchema,
+});
+/**
+ * Whether a principal may act on an already-resolved resource.
+ *
+ * Order matters. Any mismatch in the authority tuple — organization, project,
+ * or environment — is `not-found`, and that is deliberate: distinguishing
+ * "exists but is not yours" from "does not exist" is an existence oracle. A
+ * test-scoped credential holding a live identifier must not be able to learn
+ * that the identifier is real, and environment is part of the authority tuple
+ * exactly so it gets the same treatment as organization.
+ *
+ * Escalation is refused before this point, on *intent* rather than on a
+ * resolved resource — see `decideEnvironmentIntent`. Tenancy is checked before
+ * scope so a refusal can never be used to probe another tenant.
+ */
+export function decideAccess(request) {
+    const { principal, resource, scope } = request;
+    const held = principal.authority;
+    if (held.organization !== resource.organization ||
+        held.project !== resource.project ||
+        held.environment !== resource.environment ||
+        // Kind is a property of the environment id, so this is belt-and-braces —
+        // but the rule says "any mismatch in the authority tuple", and the whole
+        // tuple is cheap to compare.
+        held.environmentKind !== resource.environmentKind) {
+        return { allowed: false, reason: "not-found" };
+    }
+    if (!effectiveScopes(principal.scopes).has(scope)) {
+        return { allowed: false, reason: "scope-missing" };
+    }
+    return { allowed: true };
+}
+/**
+ * Whether a principal may act in an environment it has *asked* for — creating
+ * a live schedule, say.
+ *
+ * This is the one place escalation is named, because here the caller stated
+ * the target rather than being told a resource exists. Keeping it separate
+ * from `decideAccess` means a distinct, actionable refusal without leaking
+ * whether any particular resource is real.
+ */
+export function decideEnvironmentIntent(principal, requested) {
+    return principal.authority.environmentKind === "test" && requested === "live"
+        ? { allowed: false, reason: "test-to-live-escalation" }
+        : { allowed: true };
+}
+/**
+ * The wire refusal for every possible decision, so no adapter invents one.
+ *
+ * Typed against `ProblemCode` rather than a hand-written union, so renaming a
+ * code in the catalog fails here instead of silently returning one that is no
+ * longer catalogued.
+ */
+export function problemCodeForRefusal(reason) {
+    switch (reason) {
+        case "not-found":
+            return "not_found";
+        // Not `scope_missing`, and the difference matters to whoever is holding the
+        // credential. A missing scope says "ask for more"; this says "that kind of
+        // credential is not accepted here at all" — an API key cannot acquire the
+        // scope that would let it list an organization's projects, because the
+        // refusal is about what it *is*. 401 is what sends a browser to sign in and
+        // stops a key holder retrying with a wider grant.
+        case "principal-kind":
+            return "authentication_required";
+        case "scope-missing":
+            return "scope_missing";
+        case "test-to-live-escalation":
+            return "test_to_live_escalation";
+    }
+}
+/**
+ * Where a session names the project and environment it is acting in.
+ *
+ * **Headers rather than query parameters, and that is an authentication
+ * decision rather than a stylistic one.** These two values are part of
+ * establishing *who is asking* — together with the Clerk session they produce
+ * the authority tuple that a key or a token carries intrinsically. Declaring
+ * them as request parameters would put them in the published parameter list of
+ * every operation a signed-in member can reach, which means the generated MCP
+ * tools would gain a `project` argument. A count stood here — "fourteen
+ * operations" — and was wrong by one before anybody read it twice; the number is
+ * derivable from the registry and nothing checks a number written in prose.
+ * `packages/mcp-tools/src/invoke.ts` already refuses that
+ * argument by name, on the grounds that an agent which sent it "believes it
+ * asked for another project", and offering it would read as consent.
+ *
+ * A cache keyed on the URL alone would serve one project's page to another, so
+ * every response that varies on these must say so in `Vary`.
+ */
+export const SESSION_AUTHORITY_HEADERS = {
+    environment: "Greatwait-Environment",
+    project: "Greatwait-Project",
+};

package/dist/callback-ownership.d.ts

@@ -0,0 +1,58 @@
+/**
+ * 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 declare const CALLBACK_OWNERSHIP_POLICIES: readonly ["not-required", "required"];
+export type CallbackOwnershipPolicy = (typeof CALLBACK_OWNERSHIP_POLICIES)[number];
+/**
+ * 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 declare const DEFAULT_CALLBACK_OWNERSHIP_POLICY: CallbackOwnershipPolicy;
+/**
+ * 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 declare function readCallbackOwnershipPolicy(value: string | undefined): CallbackOwnershipPolicy;
+/**
+ * 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 declare function sendableStatuses(policy: CallbackOwnershipPolicy): readonly string[];