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

package/dist/authority.d.ts

@@ -215,3 +215,60 @@ export declare const SESSION_AUTHORITY_HEADERS: {
     readonly environment: "Greatwait-Environment";
     readonly project: "Greatwait-Project";
 };
+/**
+ * The authority a presented credential carries, answered back to its holder.
+ *
+ * **Why this exists at all.** The authority tuple is fixed at issue for a key
+ * and at consent for a grant — and until W10-01 nothing published it. A holder
+ * could act, and could not ask what it was acting *on*. The gap is invisible
+ * to a browser, which resolves its own project from a session it can see, and
+ * invisible to a documentation page, which tells a reader to substitute values
+ * they already know. It is not invisible to a command-line client: after
+ * `login` it holds a working token and cannot tell the person in front of it
+ * which project it is in, or whether the schedule they are about to create is
+ * a `test` one or a `live` one. Both were observable only by listing something
+ * the project already owned, which a new project does not have.
+ *
+ * **No organization, following every other `/v1` response.** Tenancy above the
+ * project is not a name this surface publishes, and a caller that cannot name
+ * an organization anywhere has no use for one here.
+ *
+ * **`scopes` is what was granted, not what was asked for and not what it
+ * implies.** A grant is capped by the consenting member's role and a key by
+ * what the issuer chose, so this is narrower than any request; it is also the
+ * *raw* list rather than `effectiveScopes`, which expands a write into its
+ * read. Publishing the expansion would make this answer disagree with the
+ * credential's own row in `credentials.list` and with what the consent screen
+ * showed the member — three places, two answers — and a caller that needs to
+ * know whether a scope is implied can apply the same published expansion the
+ * service does.
+ */
+export declare const credentialContextSchema: z.ZodObject<{
+    environmentKind: z.ZodEnum<{
+        test: "test";
+        live: "live";
+    }>;
+    principal: z.ZodEnum<{
+        "api-credential": "api-credential";
+        oauth: "oauth";
+    }>;
+    project: z.ZodString;
+    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";
+    }>>;
+}, z.core.$strip>;
+export type CredentialContext = z.infer<typeof credentialContextSchema>;

package/dist/authority.js

@@ -259,3 +259,38 @@ export const SESSION_AUTHORITY_HEADERS = {
     environment: "Greatwait-Environment",
     project: "Greatwait-Project",
 };
+/**
+ * The authority a presented credential carries, answered back to its holder.
+ *
+ * **Why this exists at all.** The authority tuple is fixed at issue for a key
+ * and at consent for a grant — and until W10-01 nothing published it. A holder
+ * could act, and could not ask what it was acting *on*. The gap is invisible
+ * to a browser, which resolves its own project from a session it can see, and
+ * invisible to a documentation page, which tells a reader to substitute values
+ * they already know. It is not invisible to a command-line client: after
+ * `login` it holds a working token and cannot tell the person in front of it
+ * which project it is in, or whether the schedule they are about to create is
+ * a `test` one or a `live` one. Both were observable only by listing something
+ * the project already owned, which a new project does not have.
+ *
+ * **No organization, following every other `/v1` response.** Tenancy above the
+ * project is not a name this surface publishes, and a caller that cannot name
+ * an organization anywhere has no use for one here.
+ *
+ * **`scopes` is what was granted, not what was asked for and not what it
+ * implies.** A grant is capped by the consenting member's role and a key by
+ * what the issuer chose, so this is narrower than any request; it is also the
+ * *raw* list rather than `effectiveScopes`, which expands a write into its
+ * read. Publishing the expansion would make this answer disagree with the
+ * credential's own row in `credentials.list` and with what the consent screen
+ * showed the member — three places, two answers — and a caller that needs to
+ * know whether a scope is implied can apply the same published expansion the
+ * service does.
+ */
+export const credentialContextSchema = z.object({
+    environmentKind: environmentKindSchema,
+    /** How this credential authenticated. Never `session`: see the operation. */
+    principal: z.enum(["api-credential", "oauth"]),
+    project: projectIdSchema,
+    scopes: z.array(scopeSchema).min(1),
+});

package/dist/callback-receiver.d.ts

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

package/dist/callback-receiver.js

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

package/dist/first-value-journey.d.ts

@@ -303,3 +303,159 @@ export declare function resolveJourneyReferences<T>(value: T, resolve: (name: st
  * value the reader supplies from one an earlier call handed them.
  */
 export declare function journeyCapturedVariables(): readonly string[];
+/**
+ * The website's rendering of the same journey.
+ *
+ * **Declared here rather than in the dashboard, because it is the *binding*
+ * between two things that already exist and neither of them may own it.** The
+ * dashboard has a four-step onboarding flow derived from what a member's
+ * project contains; this file has a nine-step sequence derived from the
+ * operation registry. Left unrelated they answered the same question with
+ * different words and different examples, and the website's answer was the one
+ * that went stale: its "Schedule a one-shot" step rendered the registry's
+ * `schedules.create` example, which is a **recurring cron** — a live dashboard
+ * action showing a reader the one thing the step promises it is not.
+ *
+ * So a website step names journey steps, and never a body, a title or a
+ * sentence of its own. What the browser prints is what the curl page prints,
+ * because it is the same declaration rendered twice.
+ *
+ * **`verified` maps to nothing, deliberately.** The ownership challenge is
+ * optional and off by default since W4-09, so the journey does not perform it;
+ * a deployment that turns it on gets the step from
+ * `endpoints.verify`'s own snippet. Mapping it to a journey step that does not
+ * exist would be worse than mapping it to none.
+ */
+export declare const WEBSITE_JOURNEY_STEP_KEYS: Readonly<Record<string, readonly string[]>>;
+/** The journey steps a website step renders, resolved against the sequence. */
+export declare function websiteJourneySteps(step: string): readonly JourneyStep[];
+/**
+ * The bounded wait the website inherits, rather than one it chose.
+ *
+ * W9-01's fourth criterion asks the browser to bound outcome polling and to
+ * leave a recovery action on timeout. The journey already declares both numbers
+ * on `await-occurrence`, and the curl and JavaScript quickstarts already wait
+ * exactly that long — so a browser that picked its own interval would be a
+ * third answer to a question with one published answer, and the reader who
+ * followed both would be told two different things about how long to wait.
+ */
+export declare function journeyPoll(key: string): JourneyPoll;
+/**
+ * What the reader has to bring, in the words the quickstarts already use.
+ *
+ * The website used to write its own: "anything that can take an HTTP POST. A
+ * webhook playground is fine for a first look." That sentence steered a new
+ * customer to paste their first callback into a third-party inspection service,
+ * which is the thing this project's receiver decision exists to refuse, and it
+ * disagreed with the curl page on the same screenful of product.
+ *
+ * The operator's decision on W9-01 was that the *invitation* says none of this
+ * — a prerequisite stated before somebody has any context is noise they cannot
+ * act on. It is said here instead, at the step that needs it.
+ */
+export declare function journeyPrerequisite(id: string): JourneyPrerequisite;
+/**
+ * How long a website step took, as a bucket and never as a number.
+ *
+ * Coarser than `MCP_ACTIVATION_DURATIONS`, because these measure different
+ * things: a connection test is a handshake and finishes in seconds, and a
+ * person adding a destination and scheduling a callback is doing minutes of
+ * work. Reusing the millisecond buckets would put every website step in
+ * `over_30s` and record nothing.
+ */
+export declare const JOURNEY_ACTIVATION_DURATIONS: readonly ["under_1m", "under_5m", "under_15m", "over_15m"];
+export type JourneyActivationDuration = (typeof JOURNEY_ACTIVATION_DURATIONS)[number];
+export declare function journeyActivationDuration(elapsedMs: number): JourneyActivationDuration;
+/** Every way a website step can end, drawn from a closed list. */
+export declare const JOURNEY_ACTIVATION_OUTCOMES: readonly ["reached", "refused", "timed_out", "failed"];
+export type JourneyActivationOutcome = (typeof JOURNEY_ACTIVATION_OUTCOMES)[number];
+/** The website steps an activation fact may name. */
+export declare const WEBSITE_JOURNEY_STEPS: readonly ["destination", "verified", "scheduled", "delivered"];
+/**
+ * What is recorded when somebody moves through the website journey, and the
+ * only thing that is.
+ *
+ * **Modelled on `mcpActivationEventSchema` down to the `strictObject`, and for
+ * the same reason.** Every field is drawn from a closed set: there is no
+ * free-text field, no identifier, no address, no URL and no measurement finer
+ * than a bucket, so an event of this shape cannot carry an account, an
+ * organization, a project, an invitation link, a token, a destination or a
+ * payload however carelessly it is constructed.
+ *
+ * Strict rather than merely typed. An ordinary object schema *strips* what it
+ * does not know, so an emitter that added `project` would look like it was
+ * recording one while the field silently vanished — safe and dishonest at once.
+ * The MCP schema learned that from a test and this one inherits the lesson
+ * rather than rediscovering it.
+ */
+export declare const websiteActivationEventSchema: z.ZodObject<{
+    duration: z.ZodEnum<{
+        under_1m: "under_1m";
+        under_5m: "under_5m";
+        under_15m: "under_15m";
+        over_15m: "over_15m";
+    }>;
+    outcome: z.ZodEnum<{
+        failed: "failed";
+        timed_out: "timed_out";
+        refused: "refused";
+        reached: "reached";
+    }>;
+    step: z.ZodEnum<{
+        verified: "verified";
+        delivered: "delivered";
+        destination: "destination";
+        scheduled: "scheduled";
+    }>;
+    type: z.ZodLiteral<"website.journey_step">;
+}, z.core.$strict>;
+export type WebsiteActivationEvent = z.infer<typeof websiteActivationEventSchema>;
+/**
+ * Parses an activation fact before it leaves the browser.
+ *
+ * The parse is the control, exactly as it is on the MCP side: a caller hands
+ * this an object and the schema refuses anything the closed sets do not admit,
+ * so the mistake surfaces where it was made rather than as a field that quietly
+ * disappeared.
+ */
+export declare function parseWebsiteActivationEvent(value: unknown): WebsiteActivationEvent;
+/**
+ * A path parameter's name, as the journey's variables spell it.
+ *
+ * **Published because a machine consumer cannot run the journey without it.**
+ * A step names its operation and the variables it needs — `read-schedule` says
+ * `/v1/schedules/{scheduleId}` and, separately, `GREATWAIT_SCHEDULEID` — and
+ * the rule joining the two lived in `scripts/first-value-projection.ts`, which
+ * is not published. A documentation page never notices: it renders both halves
+ * as text and a human joins them by eye. A command-line client has to *fill*
+ * the parameter, and had to re-derive the convention by guessing at it.
+ *
+ * The transformation is deliberately total and lossy in the safe direction:
+ * every non-alphanumeric character becomes `_`, so a parameter that differs
+ * from another only in punctuation would collide. `journeyPathVariables` is
+ * where that would surface, and `first-value-journey.test.ts` holds the
+ * journey's own parameters to distinct names.
+ */
+export declare function journeyVariableName(parameter: string): string;
+/** Every `{parameter}` in a path, in the order the path names them. */
+export declare function pathParameterNames(path: string): readonly string[];
+/**
+ * The variables a step's path parameters are filled from, in path order.
+ *
+ * Order is the contract: a client filling positional arguments — which is what
+ * the generated client takes — needs them in the order the path names them,
+ * and `attempts.list` has two.
+ */
+export declare function journeyPathVariables(step: JourneyStep): readonly string[];
+/**
+ * Everything a step must be given before it can be performed.
+ *
+ * **Published because it is a join, and a join is where a second consumer
+ * invents its own copy.** A step's inputs come from three places — the
+ * operation's path parameters, the `{{…}}` references in its body, query and
+ * headers — and stitching them is the kind of two-line rule every consumer gets
+ * *nearly* right. The machine-readable artifact's own `variables` field is this
+ * function, so a client reading the artifact and a client reading this module
+ * cannot disagree about what a step needs.
+ */
+export declare function journeyStepVariables(step: JourneyStep): readonly string[];

package/dist/first-value-journey.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { findOperation } from "./operations.js";
 /**
  * One thing that can go wrong at a step, and the next move.
  *
@@ -464,3 +465,215 @@ export function resolveJourneyReferences(value, resolve) {
 export function journeyCapturedVariables() {
     return FIRST_VALUE_STEPS.flatMap((step) => (step.capture ?? []).map((capture) => capture.variable));
 }
+/**
+ * The website's rendering of the same journey.
+ *
+ * **Declared here rather than in the dashboard, because it is the *binding*
+ * between two things that already exist and neither of them may own it.** The
+ * dashboard has a four-step onboarding flow derived from what a member's
+ * project contains; this file has a nine-step sequence derived from the
+ * operation registry. Left unrelated they answered the same question with
+ * different words and different examples, and the website's answer was the one
+ * that went stale: its "Schedule a one-shot" step rendered the registry's
+ * `schedules.create` example, which is a **recurring cron** — a live dashboard
+ * action showing a reader the one thing the step promises it is not.
+ *
+ * So a website step names journey steps, and never a body, a title or a
+ * sentence of its own. What the browser prints is what the curl page prints,
+ * because it is the same declaration rendered twice.
+ *
+ * **`verified` maps to nothing, deliberately.** The ownership challenge is
+ * optional and off by default since W4-09, so the journey does not perform it;
+ * a deployment that turns it on gets the step from
+ * `endpoints.verify`'s own snippet. Mapping it to a journey step that does not
+ * exist would be worse than mapping it to none.
+ */
+export const WEBSITE_JOURNEY_STEP_KEYS = {
+    delivered: ["await-occurrence", "read-attempt"],
+    destination: ["create-destination"],
+    scheduled: ["create-one-shot"],
+    verified: [],
+};
+/** The journey steps a website step renders, resolved against the sequence. */
+export function websiteJourneySteps(step) {
+    const keys = WEBSITE_JOURNEY_STEP_KEYS[step] ?? [];
+    return keys.map((key) => {
+        const found = FIRST_VALUE_STEPS.find((entry) => entry.key === key);
+        if (found === undefined) {
+            // Not reachable from the constant above, and that is exactly why it
+            // throws: the map is hand-written and the sequence is not, so a step
+            // renamed in `FIRST_VALUE_STEPS` must fail loudly here rather than
+            // silently render one fewer call than the page promises.
+            throw new Error(`website journey names unknown step ${key}`);
+        }
+        return found;
+    });
+}
+/**
+ * The bounded wait the website inherits, rather than one it chose.
+ *
+ * W9-01's fourth criterion asks the browser to bound outcome polling and to
+ * leave a recovery action on timeout. The journey already declares both numbers
+ * on `await-occurrence`, and the curl and JavaScript quickstarts already wait
+ * exactly that long — so a browser that picked its own interval would be a
+ * third answer to a question with one published answer, and the reader who
+ * followed both would be told two different things about how long to wait.
+ */
+export function journeyPoll(key) {
+    const step = FIRST_VALUE_STEPS.find((entry) => entry.key === key);
+    if (step?.poll === undefined) {
+        throw new Error(`journey step ${key} declares no bounded wait`);
+    }
+    return step.poll;
+}
+/**
+ * What the reader has to bring, in the words the quickstarts already use.
+ *
+ * The website used to write its own: "anything that can take an HTTP POST. A
+ * webhook playground is fine for a first look." That sentence steered a new
+ * customer to paste their first callback into a third-party inspection service,
+ * which is the thing this project's receiver decision exists to refuse, and it
+ * disagreed with the curl page on the same screenful of product.
+ *
+ * The operator's decision on W9-01 was that the *invitation* says none of this
+ * — a prerequisite stated before somebody has any context is noise they cannot
+ * act on. It is said here instead, at the step that needs it.
+ */
+export function journeyPrerequisite(id) {
+    const found = FIRST_VALUE_PREREQUISITES.find((entry) => entry.id === id);
+    if (found === undefined) {
+        throw new Error(`journey declares no prerequisite ${id}`);
+    }
+    return found;
+}
+/**
+ * How long a website step took, as a bucket and never as a number.
+ *
+ * Coarser than `MCP_ACTIVATION_DURATIONS`, because these measure different
+ * things: a connection test is a handshake and finishes in seconds, and a
+ * person adding a destination and scheduling a callback is doing minutes of
+ * work. Reusing the millisecond buckets would put every website step in
+ * `over_30s` and record nothing.
+ */
+export const JOURNEY_ACTIVATION_DURATIONS = [
+    "under_1m",
+    "under_5m",
+    "under_15m",
+    "over_15m",
+];
+export function journeyActivationDuration(elapsedMs) {
+    if (elapsedMs < 60_000)
+        return "under_1m";
+    if (elapsedMs < 300_000)
+        return "under_5m";
+    if (elapsedMs < 900_000)
+        return "under_15m";
+    return "over_15m";
+}
+/** Every way a website step can end, drawn from a closed list. */
+export const JOURNEY_ACTIVATION_OUTCOMES = [
+    "reached",
+    "refused",
+    "timed_out",
+    "failed",
+];
+/** The website steps an activation fact may name. */
+export const WEBSITE_JOURNEY_STEPS = [
+    "destination",
+    "verified",
+    "scheduled",
+    "delivered",
+];
+/**
+ * What is recorded when somebody moves through the website journey, and the
+ * only thing that is.
+ *
+ * **Modelled on `mcpActivationEventSchema` down to the `strictObject`, and for
+ * the same reason.** Every field is drawn from a closed set: there is no
+ * free-text field, no identifier, no address, no URL and no measurement finer
+ * than a bucket, so an event of this shape cannot carry an account, an
+ * organization, a project, an invitation link, a token, a destination or a
+ * payload however carelessly it is constructed.
+ *
+ * Strict rather than merely typed. An ordinary object schema *strips* what it
+ * does not know, so an emitter that added `project` would look like it was
+ * recording one while the field silently vanished — safe and dishonest at once.
+ * The MCP schema learned that from a test and this one inherits the lesson
+ * rather than rediscovering it.
+ */
+export const websiteActivationEventSchema = z.strictObject({
+    duration: z.enum(JOURNEY_ACTIVATION_DURATIONS),
+    outcome: z.enum(JOURNEY_ACTIVATION_OUTCOMES),
+    step: z.enum(WEBSITE_JOURNEY_STEPS),
+    type: z.literal("website.journey_step"),
+});
+/**
+ * Parses an activation fact before it leaves the browser.
+ *
+ * The parse is the control, exactly as it is on the MCP side: a caller hands
+ * this an object and the schema refuses anything the closed sets do not admit,
+ * so the mistake surfaces where it was made rather than as a field that quietly
+ * disappeared.
+ */
+export function parseWebsiteActivationEvent(value) {
+    return websiteActivationEventSchema.parse(value);
+}
+/**
+ * A path parameter's name, as the journey's variables spell it.
+ *
+ * **Published because a machine consumer cannot run the journey without it.**
+ * A step names its operation and the variables it needs — `read-schedule` says
+ * `/v1/schedules/{scheduleId}` and, separately, `GREATWAIT_SCHEDULEID` — and
+ * the rule joining the two lived in `scripts/first-value-projection.ts`, which
+ * is not published. A documentation page never notices: it renders both halves
+ * as text and a human joins them by eye. A command-line client has to *fill*
+ * the parameter, and had to re-derive the convention by guessing at it.
+ *
+ * The transformation is deliberately total and lossy in the safe direction:
+ * every non-alphanumeric character becomes `_`, so a parameter that differs
+ * from another only in punctuation would collide. `journeyPathVariables` is
+ * where that would surface, and `first-value-journey.test.ts` holds the
+ * journey's own parameters to distinct names.
+ */
+export function journeyVariableName(parameter) {
+    return `GREATWAIT_${parameter.toUpperCase().replace(/[^A-Z0-9]/gu, "_")}`;
+}
+/** Every `{parameter}` in a path, in the order the path names them. */
+export function pathParameterNames(path) {
+    return [...path.matchAll(/\{([^}]+)\}/gu)].map((match) => match[1]);
+}
+/**
+ * The variables a step's path parameters are filled from, in path order.
+ *
+ * Order is the contract: a client filling positional arguments — which is what
+ * the generated client takes — needs them in the order the path names them,
+ * and `attempts.list` has two.
+ */
+export function journeyPathVariables(step) {
+    const operation = findOperation(step.operationId);
+    if (operation === undefined) {
+        throw new Error(`the first-value journey names ${step.operationId}, which is not an operation`);
+    }
+    return pathParameterNames(operation.path).map(journeyVariableName);
+}
+/**
+ * Everything a step must be given before it can be performed.
+ *
+ * **Published because it is a join, and a join is where a second consumer
+ * invents its own copy.** A step's inputs come from three places — the
+ * operation's path parameters, the `{{…}}` references in its body, query and
+ * headers — and stitching them is the kind of two-line rule every consumer gets
+ * *nearly* right. The machine-readable artifact's own `variables` field is this
+ * function, so a client reading the artifact and a client reading this module
+ * cannot disagree about what a step needs.
+ */
+export function journeyStepVariables(step) {
+    return [
+        ...new Set([
+            ...journeyPathVariables(step),
+            ...journeyReferences(step.request),
+            ...journeyReferences(step.query),
+            ...journeyReferences(step.requestHeaders),
+        ]),
+    ];
+}

package/dist/identity.d.ts

@@ -57,8 +57,8 @@ export type ExternalMembershipId = z.infer<typeof externalMembershipIdSchema>;
  */
 export declare const MEMBERSHIP_ROLES: readonly ["admin", "member"];
 export declare const membershipRoleSchema: z.ZodEnum<{
-    admin: "admin";
     member: "member";
+    admin: "admin";
 }>;
 export type MembershipRole = z.infer<typeof membershipRoleSchema>;
 /**
@@ -99,8 +99,8 @@ export declare const membershipSchema: z.ZodObject<{
     id: z.ZodString;
     organization: z.ZodString;
     role: z.ZodEnum<{
-        admin: "admin";
         member: "member";
+        admin: "admin";
     }>;
     status: z.ZodEnum<{
         removed: "removed";
@@ -140,8 +140,8 @@ export declare const membershipChangeSchema: z.ZodObject<{
     id: z.ZodString;
     organization: z.ZodString;
     role: z.ZodEnum<{
-        admin: "admin";
         member: "member";
+        admin: "admin";
     }>;
     status: z.ZodEnum<{
         removed: "removed";
@@ -164,8 +164,8 @@ export declare const sessionMembershipSchema: z.ZodObject<{
     assertedAt: z.ZodNumber;
     organization: z.ZodString;
     role: z.ZodEnum<{
-        admin: "admin";
         member: "member";
+        admin: "admin";
     }>;
     user: z.ZodString;
 }, z.core.$strip>;