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

package/dist/protocol.d.ts

@@ -1,4 +1,4 @@
-import { z } from "zod";
+import { z } from "./zod.js";
 import type { Authority } from "./authority.js";
 import type { FieldError } from "./problems.js";
 /**
@@ -15,11 +15,74 @@ export declare const PAGE_SIZE: {
     readonly max: 100;
     readonly min: 1;
 };
-export declare const pageRequestSchema: z.ZodObject<{
-    cursor: z.ZodOptional<z.ZodString>;
-    limit: z.ZodDefault<z.ZodNumber>;
-}, z.core.$strip>;
+export declare const pageRequestSchema: import("zod").ZodObject<{
+    cursor: import("zod").ZodOptional<import("zod").ZodString>;
+    limit: import("zod").ZodDefault<import("zod").ZodNumber>;
+}, import("zod/v4/core").$strip>;
 export type PageRequest = z.infer<typeof pageRequestSchema>;
+/**
+ * A schedules listing: the page, and optionally one endpoint to keep to.
+ *
+ * The way back from a destination to everything pointed at it. Somebody who
+ * disabled an endpoint by mistake, or is about to move one, has to be able to
+ * see the schedules that deliver to it without reading the whole project.
+ */
+/**
+ * How a schedules listing may be ordered.
+ *
+ * `created` is the order this listing has always had and keeps by default, so a
+ * client that never heard of this parameter sees nothing change. `due` is what
+ * somebody looking at a list of schedules wants (FXO-2283) — what fires next,
+ * first — and it is a different index rather than a sort of the page, because
+ * sorting a page would order a hundred rows the cursor had already chosen by
+ * creation instant.
+ */
+export declare const SCHEDULE_ORDERS: readonly ["created", "due"];
+export type ScheduleOrder = (typeof SCHEDULE_ORDERS)[number];
+/**
+ * A schedules listing: the page, optionally one endpoint, and how to order it.
+ *
+ * The way back from a destination to everything pointed at it. Somebody who
+ * disabled an endpoint by mistake, or is about to move one, has to be able to
+ * see the schedules that deliver to it without reading the whole project.
+ *
+ * `dueBefore` filters on the earliest unsettled occurrence. It is served by the
+ * same index `order=due` walks, so filtering and ordering cost the same probe;
+ * a schedule with nothing on the books matches no `dueBefore`, because it has
+ * no instant to compare and inventing one either way would be a guess.
+ */
+export declare const scheduleListRequestSchema: import("zod").ZodObject<{
+    cursor: import("zod").ZodOptional<import("zod").ZodString>;
+    limit: import("zod").ZodDefault<import("zod").ZodNumber>;
+    dueBefore: import("zod").ZodOptional<import("zod").ZodString>;
+    endpoint: import("zod").ZodOptional<import("zod").ZodString>;
+    order: import("zod").ZodDefault<import("zod").ZodEnum<{
+        created: "created";
+        due: "due";
+    }>>;
+}, import("zod/v4/core").$strip>;
+export type ScheduleListRequest = z.infer<typeof scheduleListRequestSchema>;
+/**
+ * Which end of a history a page walks from.
+ *
+ * `oldest` is the order every listing has always had and keeps by default; a
+ * client that never heard of this parameter sees nothing change. `newest` is
+ * what a person looking at a schedule wants (FXO-2259): what happened most
+ * recently, first — and on a schedule firing every five minutes for thirty
+ * days that is eight thousand rows away from the other end.
+ */
+export declare const HISTORY_ORDERS: readonly ["oldest", "newest"];
+export type HistoryOrder = (typeof HISTORY_ORDERS)[number];
+/** A page request over a history, which may be walked from either end. */
+export declare const historyPageRequestSchema: import("zod").ZodObject<{
+    cursor: import("zod").ZodOptional<import("zod").ZodString>;
+    limit: import("zod").ZodDefault<import("zod").ZodNumber>;
+    order: import("zod").ZodDefault<import("zod").ZodEnum<{
+        oldest: "oldest";
+        newest: "newest";
+    }>>;
+}, import("zod/v4/core").$strip>;
+export type HistoryPageRequest = z.infer<typeof historyPageRequestSchema>;
 /**
  * A page of results.
  *
@@ -29,13 +92,13 @@ export type PageRequest = z.infer<typeof pageRequestSchema>;
  * stale data as fact. `authoritative` means the answer came from the owning
  * partition; `projected` means it may lag and carries the age.
  */
-export declare const freshnessSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
-    kind: z.ZodLiteral<"authoritative">;
-}, z.core.$strip>, z.ZodObject<{
-    asOf: z.ZodString;
-    kind: z.ZodLiteral<"projected">;
-    lagSeconds: z.ZodNumber;
-}, z.core.$strip>], "kind">;
+export declare const freshnessSchema: import("zod").ZodDiscriminatedUnion<[import("zod").ZodObject<{
+    kind: import("zod").ZodLiteral<"authoritative">;
+}, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+    asOf: import("zod").ZodString;
+    kind: import("zod").ZodLiteral<"projected">;
+    lagSeconds: import("zod").ZodNumber;
+}, import("zod/v4/core").$strip>], "kind">;
 export type Freshness = z.infer<typeof freshnessSchema>;
 /**
  * The `projected` arm alone, for a response that is never authoritative.
@@ -47,37 +110,74 @@ export type Freshness = z.infer<typeof freshnessSchema>;
  * taken, were unreachable without narrowing that no consumer could justify.
  * Naming the narrower shape moves the claim into the type.
  */
-export declare const projectedFreshnessSchema: z.ZodObject<{
-    asOf: z.ZodString;
-    kind: z.ZodLiteral<"projected">;
-    lagSeconds: z.ZodNumber;
-}, z.core.$strip>;
+export declare const projectedFreshnessSchema: import("zod").ZodObject<{
+    asOf: import("zod").ZodString;
+    kind: import("zod").ZodLiteral<"projected">;
+    lagSeconds: import("zod").ZodNumber;
+}, import("zod/v4/core").$strip>;
 export type ProjectedFreshness = z.infer<typeof projectedFreshnessSchema>;
-export declare function pageSchema<TItem extends z.ZodTypeAny>(item: TItem): z.ZodObject<{
-    data: z.ZodArray<TItem>;
-    freshness: z.ZodDiscriminatedUnion<[z.ZodObject<{
-        kind: z.ZodLiteral<"authoritative">;
-    }, z.core.$strip>, z.ZodObject<{
-        asOf: z.ZodString;
-        kind: z.ZodLiteral<"projected">;
-        lagSeconds: z.ZodNumber;
-    }, z.core.$strip>], "kind">;
-    nextCursor: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
+export declare function pageSchema<TItem extends z.ZodTypeAny>(item: TItem): import("zod").ZodObject<{
+    data: import("zod").ZodArray<TItem>;
+    freshness: import("zod").ZodDiscriminatedUnion<[import("zod").ZodObject<{
+        kind: import("zod").ZodLiteral<"authoritative">;
+    }, import("zod/v4/core").$strip>, import("zod").ZodObject<{
+        asOf: import("zod").ZodString;
+        kind: import("zod").ZodLiteral<"projected">;
+        lagSeconds: import("zod").ZodNumber;
+    }, import("zod/v4/core").$strip>], "kind">;
+    nextCursor: import("zod").ZodOptional<import("zod").ZodString>;
+}, import("zod/v4/core").$strip>;
 /**
  * Where a page stopped.
  *
- * Every collection in this product is ordered by the instant a row was created
- * and then by its identifier, so one position type serves all of them. The
- * identifier is the tiebreak rather than decoration: two credentials issued in
- * the same millisecond are ordinary, and an order that does not break the tie
- * can show one of them twice and the other never.
+ * Every collection in this product is ordered by one timestamp and then by its
+ * identifier, so one position type serves all of them. Most use creation time;
+ * schedules ordered by next due use that due instant, and the project execution
+ * index uses the occurrence's planned instant. The identifier is the tiebreak
+ * rather than decoration: two occurrences planned for the same millisecond are
+ * ordinary, and an order that does not break the tie can show one of them twice
+ * and the other never.
  */
 export interface PagePosition {
-    /** The creation instant of the last item on the page just served. */
+    /**
+     * The ordering instant of the last item served. The historical property name
+     * remains for wire and adapter compatibility; see the type comment above.
+     */
     readonly createdAtMs: number;
     /** That item's identifier. */
     readonly id: string;
+    /**
+     * The order the page was walked in, for a listing that has more than one
+     * (FXO-2259, FXO-2283). A position is only a position in the order that
+     * issued it: presented under another, it is refused rather than resumed from
+     * the middle of the book in the wrong direction. Absent on the listings that
+     * have one order, and on cursors issued before this field.
+     *
+     * **Two vocabularies, deliberately, because they are two different
+     * questions.** A history is walked from an end — `oldest` or `newest` — and a
+     * schedules listing is ordered by a *field*: `created` or `due`. Collapsing
+     * them into one enum would let a history cursor and a schedules cursor
+     * compare equal, which is the comparison this field exists to make impossible.
+     * A cursor carries whichever its listing issued, and the two listings never
+     * read each other's.
+     */
+    readonly order?: "created" | "due" | "newest" | "oldest";
+}
+/**
+ * The collection and filters under which a cursor was issued.
+ *
+ * A position is meaningful only inside the exact listing that produced it.
+ * Authority already keeps it inside one tenant; this binding keeps a cursor
+ * from one collection, or from one filtered view of a collection, from being
+ * replayed into another and silently resuming at an unrelated position.
+ *
+ * Parameters are a record rather than an encoded string so normalization has
+ * one home here. Their names are sorted before encoding; callers may build the
+ * object in any order and still mint the same binding.
+ */
+export interface CursorBinding {
+    readonly operation: string;
+    readonly parameters?: Readonly<Record<string, string>>;
 }
 /**
  * The cursor a client is handed for the next page.
@@ -88,7 +188,7 @@ export interface PagePosition {
  * carries authority, and it carries none — every listing is scoped by the
  * principal before a cursor is even looked at.
  */
-export declare function encodeCursor(authority: Authority, position: PagePosition): string;
+export declare function encodeCursor(authority: Authority, position: PagePosition, binding?: CursorBinding): string;
 /**
  * The position a cursor names, or nothing.
  *
@@ -98,7 +198,7 @@ export declare function encodeCursor(authority: Authority, position: PagePositio
  * their cursor is wrong tells them what a valid one looks like, and the caller
  * never constructs one anyway.
  */
-export declare function decodeCursor(authority: Authority, cursor: string): PagePosition | undefined;
+export declare function decodeCursor(authority: Authority, cursor: string, binding?: CursorBinding): PagePosition | undefined;
 export type PageRequestParse = {
     readonly ok: true;
     readonly page: PageRequest;
@@ -122,13 +222,31 @@ export type PageRequestParse = {
  * is the direction compatibility has to hold in.
  */
 export declare function parsePageRequest(query: URLSearchParams): PageRequestParse;
+export type ScheduleListRequestParse = {
+    readonly ok: true;
+    readonly page: ScheduleListRequest;
+} | {
+    readonly ok: false;
+    readonly errors: readonly FieldError[];
+};
+/** A schedules listing request: the page, and the endpoint filter if given. */
+export declare function parseScheduleListRequest(query: URLSearchParams): ScheduleListRequestParse;
+export type HistoryPageRequestParse = {
+    readonly ok: true;
+    readonly page: HistoryPageRequest;
+} | {
+    readonly ok: false;
+    readonly errors: readonly FieldError[];
+};
+/** A history page request: the page, and which end it walks from. */
+export declare function parseHistoryPageRequest(query: URLSearchParams): HistoryPageRequestParse;
 /**
  * Every mutable resource carries a monotonically increasing `version`, surfaced
  * as a strong ETag. A conditional write that loses the race is refused with
  * `version_conflict` rather than silently overwriting — a cancel racing a
  * replace must not resolve by luck.
  */
-export declare const versionSchema: z.ZodNumber;
+export declare const versionSchema: import("zod").ZodNumber;
 export type Version = z.infer<typeof versionSchema>;
 export declare function toETag(version: Version): string;
 /** Parses a strong ETag, returning undefined for anything malformed or weak. */
@@ -143,7 +261,7 @@ export declare function fromETag(etag: string): Version | undefined;
  * refinement is the extra strictness the OpenAPI preamble already discloses
  * that a described schema does not capture.
  */
-export declare const etagSchema: z.ZodString;
+export declare const etagSchema: import("zod").ZodString;
 /**
  * Idempotency keys make an unsafe write safe to retry.
  *
@@ -154,7 +272,7 @@ export declare const etagSchema: z.ZodString;
  * silent second write — that distinction is the whole point, and the legacy
  * scheduler had no equivalent.
  */
-export declare const idempotencyKeySchema: z.ZodString;
+export declare const idempotencyKeySchema: import("zod").ZodString;
 export type IdempotencyKey = z.infer<typeof idempotencyKeySchema>;
 /**
  * The scope a key was used in. Carried on the receipt rather than assumed,
@@ -163,24 +281,24 @@ export type IdempotencyKey = z.infer<typeof idempotencyKeySchema>;
  * send the same key. The scope is part of the record so that mistake cannot be
  * made silently.
  */
-export declare const idempotencyScopeSchema: z.ZodObject<{
-    environment: z.ZodString;
-    operation: z.ZodString;
-    organization: z.ZodString;
-    project: z.ZodString;
-}, z.core.$strip>;
+export declare const idempotencyScopeSchema: import("zod").ZodObject<{
+    environment: import("zod").ZodString;
+    operation: import("zod").ZodString;
+    organization: import("zod").ZodString;
+    project: import("zod").ZodString;
+}, import("zod/v4/core").$strip>;
 export type IdempotencyScope = z.infer<typeof idempotencyScopeSchema>;
-export declare const idempotencyReceiptSchema: z.ZodObject<{
-    requestFingerprint: z.ZodString;
-    replayed: z.ZodBoolean;
-    scope: z.ZodObject<{
-        environment: z.ZodString;
-        operation: z.ZodString;
-        organization: z.ZodString;
-        project: z.ZodString;
-    }, z.core.$strip>;
-    storedAt: z.ZodString;
-}, z.core.$strip>;
+export declare const idempotencyReceiptSchema: import("zod").ZodObject<{
+    requestFingerprint: import("zod").ZodString;
+    replayed: import("zod").ZodBoolean;
+    scope: import("zod").ZodObject<{
+        environment: import("zod").ZodString;
+        operation: import("zod").ZodString;
+        organization: import("zod").ZodString;
+        project: import("zod").ZodString;
+    }, import("zod/v4/core").$strip>;
+    storedAt: import("zod").ZodString;
+}, import("zod/v4/core").$strip>;
 export type IdempotencyReceipt = z.infer<typeof idempotencyReceiptSchema>;
 /**
  * The canonical form of a request, as the receipt's `requestFingerprint`
@@ -256,9 +374,9 @@ export declare const CONCURRENCY_HEADERS: {
     readonly ifMatch: "If-Match";
     readonly replayed: "Idempotency-Replayed";
 };
-export declare const idempotencyRequestHeaderSchema: z.ZodObject<{
-    "Idempotency-Key": z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
+export declare const idempotencyRequestHeaderSchema: import("zod").ZodObject<{
+    "Idempotency-Key": import("zod").ZodOptional<import("zod").ZodString>;
+}, import("zod/v4/core").$strip>;
 /**
  * A write for which idempotency is mandatory, rather than an optional
  * protection a caller may opt into.
@@ -268,21 +386,32 @@ export declare const idempotencyRequestHeaderSchema: z.ZodObject<{
  * `idempotencyRequestHeaderSchema` lets schedule creation retain its published
  * optional behavior without weakening the redelivery promise.
  */
-export declare const requiredIdempotencyRequestHeaderSchema: z.ZodObject<{
-    "Idempotency-Key": z.ZodString;
-}, z.core.$strip>;
-export declare const conditionalRequestHeaderSchema: z.ZodObject<{
-    "If-Match": z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
+export declare const requiredIdempotencyRequestHeaderSchema: import("zod").ZodObject<{
+    "Idempotency-Key": import("zod").ZodString;
+}, import("zod/v4/core").$strip>;
+export declare const conditionalRequestHeaderSchema: import("zod").ZodObject<{
+    "If-Match": import("zod").ZodOptional<import("zod").ZodString>;
+}, import("zod/v4/core").$strip>;
+/**
+ * A conditional write that refuses an unversioned request.
+ *
+ * Project lifecycle changes use this stricter shape because rename, archive,
+ * restore and permanent deletion are management actions over one shared row:
+ * silently accepting a missing precondition would let a stale General page
+ * overwrite a newer decision.
+ */
+export declare const requiredConditionalRequestHeaderSchema: import("zod").ZodObject<{
+    "If-Match": import("zod").ZodString;
+}, import("zod/v4/core").$strip>;
 /**
  * Required rather than optional, deliberately: an operation that declares this
  * promises the header on every success, and a client that has to test for its
  * presence before making a conditional write will write the untested branch
  * wrong.
  */
-export declare const versionResponseHeaderSchema: z.ZodObject<{
-    ETag: z.ZodString;
-}, z.core.$strip>;
+export declare const versionResponseHeaderSchema: import("zod").ZodObject<{
+    ETag: import("zod").ZodString;
+}, import("zod/v4/core").$strip>;
 /**
  * What a replayed write answers with, on top of the version.
  *
@@ -298,11 +427,11 @@ export declare const versionResponseHeaderSchema: z.ZodObject<{
  * header is the ordinary case, and a client that has to read a header to learn
  * nothing happened is a client that will not read it.
  */
-export declare const replayedResponseHeaderSchema: z.ZodObject<{
-    ETag: z.ZodString;
-    "Idempotency-Replayed": z.ZodOptional<z.ZodLiteral<"true">>;
-}, z.core.$strip>;
+export declare const replayedResponseHeaderSchema: import("zod").ZodObject<{
+    ETag: import("zod").ZodString;
+    "Idempotency-Replayed": import("zod").ZodOptional<import("zod").ZodLiteral<"true">>;
+}, import("zod/v4/core").$strip>;
 /** Replay marker for an idempotent create whose result has no ETag. */
-export declare const idempotencyReplayResponseHeaderSchema: z.ZodObject<{
-    "Idempotency-Replayed": z.ZodOptional<z.ZodLiteral<"true">>;
-}, z.core.$strip>;
+export declare const idempotencyReplayResponseHeaderSchema: import("zod").ZodObject<{
+    "Idempotency-Replayed": import("zod").ZodOptional<import("zod").ZodLiteral<"true">>;
+}, import("zod/v4/core").$strip>;

package/dist/protocol.js

@@ -1,5 +1,5 @@
-import { z } from "zod";
-import { environmentIdSchema, organizationIdSchema, projectIdSchema, } from "./identifiers.js";
+import { z } from "./zod.js";
+import { endpointIdSchema, environmentIdSchema, organizationIdSchema, projectIdSchema, } from "./identifiers.js";
 import { timestampSchema } from "./time.js";
 /**
  * Request and collection mechanics: paging, optimistic concurrency, and
@@ -23,6 +23,55 @@ export const pageRequestSchema = z.object({
         .max(PAGE_SIZE.max)
         .default(PAGE_SIZE.default),
 });
+/**
+ * A schedules listing: the page, and optionally one endpoint to keep to.
+ *
+ * The way back from a destination to everything pointed at it. Somebody who
+ * disabled an endpoint by mistake, or is about to move one, has to be able to
+ * see the schedules that deliver to it without reading the whole project.
+ */
+/**
+ * How a schedules listing may be ordered.
+ *
+ * `created` is the order this listing has always had and keeps by default, so a
+ * client that never heard of this parameter sees nothing change. `due` is what
+ * somebody looking at a list of schedules wants (FXO-2283) — what fires next,
+ * first — and it is a different index rather than a sort of the page, because
+ * sorting a page would order a hundred rows the cursor had already chosen by
+ * creation instant.
+ */
+export const SCHEDULE_ORDERS = ["created", "due"];
+/**
+ * A schedules listing: the page, optionally one endpoint, and how to order it.
+ *
+ * The way back from a destination to everything pointed at it. Somebody who
+ * disabled an endpoint by mistake, or is about to move one, has to be able to
+ * see the schedules that deliver to it without reading the whole project.
+ *
+ * `dueBefore` filters on the earliest unsettled occurrence. It is served by the
+ * same index `order=due` walks, so filtering and ordering cost the same probe;
+ * a schedule with nothing on the books matches no `dueBefore`, because it has
+ * no instant to compare and inventing one either way would be a guess.
+ */
+export const scheduleListRequestSchema = pageRequestSchema.extend({
+    dueBefore: timestampSchema.optional(),
+    endpoint: endpointIdSchema.optional(),
+    order: z.enum(SCHEDULE_ORDERS).default("created"),
+});
+/**
+ * Which end of a history a page walks from.
+ *
+ * `oldest` is the order every listing has always had and keeps by default; a
+ * client that never heard of this parameter sees nothing change. `newest` is
+ * what a person looking at a schedule wants (FXO-2259): what happened most
+ * recently, first — and on a schedule firing every five minutes for thirty
+ * days that is eight thousand rows away from the other end.
+ */
+export const HISTORY_ORDERS = ["oldest", "newest"];
+/** A page request over a history, which may be walked from either end. */
+export const historyPageRequestSchema = pageRequestSchema.extend({
+    order: z.enum(HISTORY_ORDERS).default("oldest"),
+});
 /**
  * A page of results.
  *
@@ -63,6 +112,12 @@ export function pageSchema(item) {
         nextCursor: z.string().min(1).optional(),
     });
 }
+function normalizedCursorBinding(binding) {
+    return JSON.stringify({
+        operation: binding.operation,
+        parameters: Object.entries(binding.parameters ?? {}).sort(([left], [right]) => left.localeCompare(right)),
+    });
+}
 /**
  * A 32-bit FNV-1a hash of the authority tuple, hex encoded.
  *
@@ -136,11 +191,13 @@ function base64UrlDecode(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) {
+export function encodeCursor(authority, position, binding) {
     return base64UrlEncode(JSON.stringify({
         a: position.createdAtMs,
+        ...(binding === undefined ? {} : { b: normalizedCursorBinding(binding) }),
         i: position.id,
         k: authorityFingerprint(authority),
+        ...(position.order === undefined ? {} : { o: position.order }),
     }));
 }
 /**
@@ -152,7 +209,7 @@ export function encodeCursor(authority, position) {
  * their cursor is wrong tells them what a valid one looks like, and the caller
  * never constructs one anyway.
  */
-export function decodeCursor(authority, cursor) {
+export function decodeCursor(authority, cursor, binding) {
     const decoded = base64UrlDecode(cursor);
     if (decoded === undefined) {
         return undefined;
@@ -167,47 +224,40 @@ export function decodeCursor(authority, cursor) {
     const shape = z
         .object({
         a: z.number().int().nonnegative(),
+        b: z.string().min(1).optional(),
         i: z.string().min(1),
         k: z.string(),
+        o: z.enum(["created", "due", "newest", "oldest"]).optional(),
     })
         .safeParse(parsed);
-    if (!shape.success || shape.data.k !== authorityFingerprint(authority)) {
+    const expectedBinding = binding === undefined ? undefined : normalizedCursorBinding(binding);
+    if (!shape.success ||
+        shape.data.k !== authorityFingerprint(authority) ||
+        shape.data.b !== expectedBinding) {
         return undefined;
     }
-    return { createdAtMs: shape.data.a, id: shape.data.i };
+    return {
+        createdAtMs: shape.data.a,
+        id: shape.data.i,
+        ...(shape.data.o === undefined ? {} : { order: shape.data.o }),
+    };
 }
 /** 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",
-]);
+const PARAMETERS = new Map();
+function parametersOf(schema) {
+    const cached = PARAMETERS.get(schema);
+    if (cached !== undefined)
+        return cached;
+    const derived = Object.entries(z.toJSONSchema(schema, {
+        io: "input",
+        unrepresentable: "any",
+    }).properties ?? {}).map(([name, field]) => [name, field.type === "integer" || field.type === "number"]);
+    PARAMETERS.set(schema, derived);
+    return derived;
+}
 /**
  * A page request, read from a URL's query string.
  *
@@ -224,9 +274,20 @@ const PAGE_PARAMETERS = Object.entries(z.toJSONSchema(pageRequestSchema, {
  * is the direction compatibility has to hold in.
  */
 export function parsePageRequest(query) {
+    return parseListing(query, pageRequestSchema);
+}
+/** A schedules listing request: the page, and the endpoint filter if given. */
+export function parseScheduleListRequest(query) {
+    return parseListing(query, scheduleListRequestSchema);
+}
+/** A history page request: the page, and which end it walks from. */
+export function parseHistoryPageRequest(query) {
+    return parseListing(query, historyPageRequestSchema);
+}
+function parseListing(query, schema) {
     const errors = [];
     const raw = {};
-    for (const [field, numeric] of PAGE_PARAMETERS) {
+    for (const [field, numeric] of parametersOf(schema)) {
         const values = query.getAll(field);
         if (values.length > 1) {
             errors.push({
@@ -244,7 +305,7 @@ export function parsePageRequest(query) {
     if (errors.length > 0) {
         return { errors, ok: false };
     }
-    const parsed = pageRequestSchema.safeParse(raw);
+    const parsed = schema.safeParse(raw);
     if (parsed.success) {
         return { ok: true, page: parsed.data };
     }
@@ -481,6 +542,17 @@ export const requiredIdempotencyRequestHeaderSchema = z.object({
 export const conditionalRequestHeaderSchema = z.object({
     [CONCURRENCY_HEADERS.ifMatch]: etagSchema.optional(),
 });
+/**
+ * A conditional write that refuses an unversioned request.
+ *
+ * Project lifecycle changes use this stricter shape because rename, archive,
+ * restore and permanent deletion are management actions over one shared row:
+ * silently accepting a missing precondition would let a stale General page
+ * overwrite a newer decision.
+ */
+export const requiredConditionalRequestHeaderSchema = z.object({
+    [CONCURRENCY_HEADERS.ifMatch]: etagSchema,
+});
 /**
  * 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