@greatwait/contracts 0.1.0-alpha.1

package/dist/partition.d.ts

@@ -0,0 +1,771 @@
+import type { Authority } from "./authority.js";
+import type { Attempt, AttemptView, LatencyClass, Occurrence, OccurrenceView, Schedule, ScheduleView } from "./scheduling.js";
+/**
+ * The seam between the API Worker and a Scheduler Partition Durable Object.
+ *
+ * **This is not a public wire shape.** Nothing here is served to a customer,
+ * appears in OpenAPI, or is reachable from the internet — a Durable Object has
+ * no route, and only a Worker holding the namespace binding can address one.
+ * It lives in the contracts package for the single reason that two workspaces
+ * need to agree on it and this is the only package both `apps/api` and
+ * `apps/scheduler` may depend on. The alternative was each side writing the
+ * shape out separately, which is how `apps/scheduler/src/contract-runtime.ts`
+ * became a filed debt.
+ *
+ * It carries **no Zod and no runtime import of the contract barrel**. The
+ * addressing and routing functions below are a string join and a hash, and the
+ * rest is types, which are erased. That matters: `apps/scheduler` is the Worker
+ * every Durable Object cold start parses, and W2-08 measured the contract
+ * barrel's runtime exports at 3.4x its bundle (see
+ * `apps/scheduler/src/contract-runtime.ts`).
+ *
+ * **`@greatwait/contracts/partition` is a subpath export for that reason**,
+ * added by W2-05 when the scheduler needed the route function at runtime rather
+ * than only its types. Importing it through the barrel would have reached Zod
+ * and undone the whole of `contract-runtime.ts`. This is a narrow instance of
+ * what [FXO-1404](https://linear.app/flowxo/issue/FXO-1404) asks for in
+ * general — a Zod-free entry point — and it does not close that issue: the
+ * identifier, timestamp and problem helpers `contract-runtime.ts` copies still
+ * live in modules that do reach Zod.
+ */
+/**
+ * The shard every partition had until W2-05, and the only one an unsharded
+ * deployment ever uses.
+ *
+ * Named rather than written as `"0"` at two call sites, because the API Worker
+ * and the partition must derive the same Durable Object name and a literal
+ * repeated across a workspace boundary is a literal that will eventually
+ * disagree with itself. `partitionShardFor` returns exactly this when the shard
+ * count is one, so every Durable Object name a single-shard deployment produces
+ * is byte-identical to the ones it produced before sharding existed.
+ */
+export declare const SINGLE_SHARD = "0";
+/**
+ * Projection intents handed over in one call.
+ *
+ * **Declared here because both sides of the seam enforce it, and a bound
+ * enforced twice from two workspaces is a bound that will eventually disagree
+ * with itself.** The API Worker asks for this many; the partition clamps what it
+ * hands over to it and *refuses* a settle carrying more. If the asking number
+ * ever exceeded the refusing one, every settle would be refused, no intent would
+ * ever be retired, the outbox would grow to `PARTITION_LIMITS.outboxRows` and
+ * creates would then start failing for bookkeeping — a customer-visible outage
+ * produced by two constants drifting apart. The test-gap audit named exactly
+ * that, and the fix is one declaration rather than a test comparing two.
+ *
+ * Thirty-two is one D1 batch's worth of work and a few kilobytes of response.
+ * The caller comes back for the rest, and `RetainedProjections.pending` is how
+ * it knows to.
+ */
+export declare const PROJECTION_DRAIN_LIMIT = 32;
+/**
+ * The most shards one project/environment may be spread across.
+ *
+ * Eight, and the number is borrowed rather than invented:
+ * `apps/scheduler/src/routing.ts` clamps `HOST_EXECUTOR_SHARDS` at eight, and a
+ * repository carrying two different bounds on two knobs of the same shape is a
+ * repository where somebody eventually applies the wrong one. The costs differ
+ * but they point the same way — an executor shard divides a host budget, and a
+ * partition shard divides a project's schedules across Durable Objects.
+ *
+ * A listing had to fan out across all of them until W2-06 served listings from
+ * D1, which was the sharpest reason for a bound and is now gone. What is left is
+ * still a real fan-out: a listing whose projection is stale re-confirms every
+ * partition it covers, and a repair after an outage hands over from each in
+ * turn. Eight is where that stops being a request.
+ *
+ * A value above this is clamped rather than refused, which is upstream's
+ * judgement in `executorShardCount` and holds for the same reason: an operator
+ * asking for sixteen still wants sharding, just bounded.
+ */
+export declare const MAX_PARTITION_SHARDS = 8;
+/**
+ * How many shards a deployment spreads one project/environment across.
+ *
+ * Reads the raw environment string rather than an `Env`, so both Workers parse
+ * it the same way without either of them naming the other's bindings. Missing,
+ * unparseable, non-integer and below-one all resolve to one — the unsharded
+ * default — because a partition count is the thing a *routing* decision is made
+ * from, and a routing decision made from a garbage value is worse than one made
+ * from the default.
+ *
+ * **Changing it moves where existing identifiers resolve, so it is retunable
+ * only under a precondition, and that is the most important thing to know about
+ * it.** A schedule's shard is derived from its identifier. Before W2-06 that was
+ * the only answer, so raising the count stranded every schedule already stored.
+ * Now the shard a schedule was actually stored in is *recorded* in the D1
+ * directory, and `resolveSchedule` falls back to it whenever the derived
+ * partition has nothing — so a schedule created under an older count keeps
+ * working, because its route was written down rather than recomputed.
+ *
+ * The precondition is that every schedule **has** such a route, which is exactly
+ * what `greatwait_projection_checkpoint` reporting `pending: 0` for every
+ * partition means. A schedule whose projection never landed has no recorded
+ * route and no derivable one, and it is unreachable until its partition is
+ * drained. `docs/operations/cloudflare-environments.md` carries the procedure
+ * and the two costs it does not remove — a keyed create's idempotency receipt is
+ * stranded for its 24-hour life, and detail reads of pre-change schedules cost
+ * an extra round trip for as long as they exist.
+ *
+ * It is still not `HOST_EXECUTOR_SHARDS`, which rolls `1 → 4 → 8` under load
+ * because an executor holds no durable state. This one holds all of it, and
+ * moving it is a planned operation rather than a dial.
+ */
+export declare function partitionShardCount(raw: string | undefined): number;
+/**
+ * The shard a schedule identifier belongs to.
+ *
+ * Architecture section 4's route function: the stable opaque schedule ID hashed
+ * into a project/environment shard, with the count an operational configuration
+ * rather than a public contract. Nothing a *client* sends reaches this — the
+ * identifier is minted by the API Worker — so a caller can neither choose their
+ * shard nor learn how many there are.
+ */
+export declare function partitionShardFor(scheduleId: string, shardCount: number): string;
+/**
+ * The shard a create carrying an idempotency key routes to.
+ *
+ * **A create is the one operation that cannot route by schedule identifier,
+ * because it is the operation that mints one.** Every other operation is handed
+ * an identifier and derives the shard from it; a create has to pick a partition
+ * first and name the schedule afterwards. Picking randomly would break
+ * idempotency the moment there is more than one shard: the retry that carries
+ * the same key would mint a different identifier, land in a different Durable
+ * Object, find no receipt there, and create a second schedule — the exact
+ * failure the receipt exists to prevent.
+ *
+ * So a keyed create routes on the key, and the identifier is then minted *into*
+ * that shard (`mintScheduleIdIn`), which keeps `partitionShardFor` the single
+ * answer for every later read. A create with no key routes on the identifier it
+ * mints, because there is nothing to be idempotent about.
+ *
+ * The `idk:` prefix separates the two domains, so an identifier and a key that
+ * happen to be the same string cannot be conflated into the same hash input.
+ * The key is customer input and it selects a shard **inside the caller's own
+ * authority tuple**: it cannot reach another organization, project or
+ * environment, because those are the other components of the Durable Object
+ * name and none of them comes from the request.
+ */
+export declare function partitionShardForIdempotencyKey(key: string, shardCount: number): string;
+/**
+ * The Durable Object instance name for one authority tuple and shard.
+ *
+ * Deriving the name from the authority is what makes a cross-tenant read reach
+ * a *different object*, so tenancy is enforced by addressing before any code
+ * runs. The partition's own bound-identity check is then defence against a
+ * defect in this function rather than the only thing standing between two
+ * tenants.
+ *
+ * `:` is safe as a separator because every component is either a prefixed
+ * identifier drawn from Crockford base32 or the fixed literal `test`/`live`,
+ * and none of those can contain it. Callers must validate the tuple before
+ * calling: this function makes a name, it does not police one.
+ */
+export declare function partitionInstanceName(authority: Authority, shard: string): string;
+/**
+ * Why a partition refused.
+ *
+ * `not-found` covers both "no such schedule" and "this partition is bound to
+ * someone else", deliberately: the caller must not be able to tell those apart,
+ * and a refusal that named the bound authority would be a refusal that named
+ * another tenant.
+ *
+ * `version-conflict` and `state-conflict` are separate answers because they
+ * have separate remedies. The first says somebody else wrote first and the
+ * caller should re-read and decide again; the second says nobody did and this
+ * transition is simply not available from where the schedule is. Collapsing
+ * them would make a client retry a conditional write that can never succeed.
+ *
+ * `invalid-request` and `unavailable` are separate for a sharper reason: they
+ * differ in **whose fault it is**. `invalid-request` is something the caller
+ * sent — an instant that is not one. `unavailable` is something we did: an
+ * authority tuple built from a verified principal that this partition cannot
+ * read, or a partition bound to a tuple other than the one that addressed it.
+ * One refusal covered both until W2-02's review, and the cost was the same
+ * internal fault surfacing as a 400 that told the caller their own tuple was
+ * malformed on six routes and a 503 on the seventh — with that 400 unpublished
+ * on the read operation, because no caller can cause it.
+ */
+export type PartitionRefusal = "idempotency-probe-miss" | "invalid-request" | "not-found" | "state-conflict" | "unavailable" | "version-conflict";
+/**
+ * A refusal, and optionally what specifically could not be accepted.
+ *
+ * The detail exists because `invalid-request` stopped being a single answer the
+ * moment a schedule could be defined four ways. The adapter used to hard-code
+ * one sentence naming `at` and `delaySeconds`, which was true while those were
+ * the only arms and became a wrong answer for a cron expression that does not
+ * parse. It is a short, caller-facing phrase and never a stored value or an
+ * identifier: a refusal must not be able to carry another tenant's data out of
+ * a partition, which is why the refusals that could — `not-found` above — say
+ * nothing beyond themselves.
+ */
+export interface PartitionRefused {
+    readonly detail?: string;
+    readonly refusal: PartitionRefusal;
+}
+export type PartitionOutcome = PartitionRefused | {
+    readonly view: ScheduleView;
+};
+/**
+ * One retained projection intent, with the schedule it is about.
+ *
+ * **The partition reads the schedule at drain time rather than carrying a copy
+ * in the outbox row.** The stored `body` is `{schedule, version}` and W2-06
+ * deliberately left it that way: widening it would have been a format change
+ * across a deployment window for no gain, because superseding already keeps at
+ * most one pending intent per schedule and that intent always names the newest
+ * version. Reading the row at drain time is therefore the same answer, and it is
+ * the answer that stays right if the schedule moved on in between.
+ *
+ * **`schedule` absent is a tombstone.** The partition retained an intent for a
+ * schedule it no longer holds, so the directory must stop listing it rather than
+ * keep a summary nothing can repair.
+ *
+ * **`scheduleId` absent is an intent this build cannot route.** The outbox is a
+ * general event log — `event_type` carries no CHECK precisely so adding a type
+ * is not a partition migration — so an intent naming no schedule is one a later
+ * story enqueued and this drainer does not understand. It is acknowledged rather
+ * than retained, which is the kernel's unknown-kind rule and it has the same
+ * consequence: **rolling the API Worker back past a story that adds an event
+ * type discards that story's pending intents**, exactly as rolling the scheduler
+ * back past W2-04 discards its `advance-series` tasks. A story adding an event
+ * type teaches the drainer about it in the same change.
+ */
+export interface ProjectionIntent {
+    /**
+     * How many hand-overs of this intent have already failed.
+     *
+     * Carried so the caller can back a failing intent off without keeping state
+     * of its own — and, more importantly, so it can decline to back off the
+     * *first* failure. A blanket delay would lock a schedule out of listings for
+     * the length of it after one transient error, which is the common case; a
+     * poison intent that fails every time is the rare one, and it is the one the
+     * backoff exists for.
+     */
+    readonly attempts: number;
+    readonly eventId: string;
+    readonly eventType: string;
+    /** The schedule as the partition holds it now. Absent means it is gone. */
+    readonly schedule?: Schedule;
+    /** Absent on an intent that names no schedule. */
+    readonly scheduleId?: string;
+    /** The version the intent was enqueued for. Absent with `scheduleId`. */
+    readonly scheduleVersion?: number;
+}
+/**
+ * What a partition is still holding for the control plane.
+ *
+ * **`pending` is the whole retained count and `intents` is only what fits in one
+ * hand-over**, which is what lets a caller tell "you have everything" from "come
+ * back for more" without a second call. It also counts intents that are
+ * *deferred* — postponed after a failed send and therefore not offered yet — so
+ * a directory that reports itself caught up while a partition is sitting on a
+ * backlog is not a state this shape can express.
+ */
+export interface RetainedProjections {
+    readonly intents: readonly ProjectionIntent[];
+    /** Intents retained in total, counted no further than the outbox bound. */
+    readonly pending: number;
+}
+/**
+ * What a write answers.
+ *
+ * The same view a read answers, plus whatever the control plane still owes —
+ * which for a healthy partition is the one intent this write just enqueued, and
+ * after an outage is that one plus whatever else is waiting. Carried on the
+ * outcome rather than fetched by a second call, because the write and its intent
+ * were committed together and a round trip to ask "what did you just record" is
+ * a round trip to learn something the callee already knew.
+ *
+ * Carrying the *other* schedules' intents is what makes any write after an
+ * outage repair the schedules written during it, which is acceptance criterion 4
+ * on the cheapest path there is.
+ */
+export type ScheduleWriteOutcome = PartitionRefused | {
+    readonly projections: RetainedProjections;
+    readonly view: ScheduleView;
+};
+/** Read the intents a partition is still holding, oldest first. */
+export interface DrainProjectionsQuery {
+    readonly authority: Authority;
+    readonly limit: number;
+}
+/**
+ * What the partition is still holding.
+ *
+ * **Nothing is deleted here.** The intents stay until `settleProjections` says
+ * the control plane has them, which is acceptance criterion 1: an intent
+ * survives a drain whose D1 write never landed, and a partition that has never
+ * been initialized answers an empty drain rather than a refusal — a shard nobody
+ * has written to owes the directory nothing.
+ */
+export type DrainProjectionsOutcome = PartitionRefused | RetainedProjections;
+/**
+ * Retire the intents the control plane accepted, and postpone the rest.
+ *
+ * Both halves in one call rather than two, because a drain has exactly one of
+ * these outcomes and the failing half must not need a healthy D1 to be recorded:
+ * the deferral is what stops a control-plane outage from making every subsequent
+ * request pay a D1 timeout for the same intent.
+ */
+export interface SettleProjectionsCommand {
+    /** Intents the control plane has durably applied, or cannot route. */
+    readonly acknowledged: readonly string[];
+    readonly authority: Authority;
+    /** Intents whose apply failed, and the instant to offer them again. */
+    readonly deferred?: {
+        readonly eventIds: readonly string[];
+        readonly nextAttemptAtMs: number;
+    };
+}
+export type SettleProjectionsOutcome = PartitionRefused | {
+    readonly acknowledged: number;
+    readonly deferred: number;
+    /** Intents still retained after this call. */
+    readonly pending: number;
+};
+/**
+ * What the partition did with an idempotency key, and what it had on file.
+ *
+ * The partition reports rather than decides. `classifyIdempotency` is the
+ * decision and it is pure, so it runs once, in the adapter that also knows the
+ * caller's scope — and this carries back the only thing the adapter cannot
+ * know, which is whether a live receipt was already there and what request it
+ * was for. The partition's own contribution is atomicity: the receipt is
+ * written in the same transaction as the schedule, so a key can never be
+ * recorded for a create that did not happen, nor a create happen twice under
+ * one key.
+ */
+export interface IdempotencyDisposition {
+    /** The fingerprint on the receipt already on file, if there was one. */
+    readonly storedFingerprint?: string;
+    /** When that receipt was written, epoch milliseconds. */
+    readonly storedAtMs?: number;
+    /** False when a live receipt already existed, so nothing was written. */
+    readonly written: boolean;
+}
+export type CreateScheduleOutcome = PartitionRefused | {
+    readonly idempotency?: IdempotencyDisposition;
+    /** What the control plane still owes for this partition. */
+    readonly projections: RetainedProjections;
+    readonly view: ScheduleView;
+};
+/**
+ * How a schedule recurs, as the seam carries it and the partition stores it.
+ *
+ * Close to the published `Recurrence` and deliberately not the same type. This
+ * one's `at` arm carries the instant, because a create has to say *when*; the
+ * published one does not, because a client reads the instant off the
+ * occurrence and two copies of it would be two things to disagree after a
+ * replace. Everything else is identical, and the partition writes this shape
+ * into `greatwait_schedule.definition` verbatim — which for a one-shot is
+ * byte-identical to what W2-02 already wrote, so no stored row is rewritten.
+ *
+ * `timeZone` is required on the `cron` arm rather than optional: the adapter
+ * resolves the caller's omission to `UTC` once, at acceptance, so the stored
+ * definition always names the wall clock it is read against and no later reader
+ * has to know what the default was on the day it was created.
+ */
+export type ScheduleDefinition = {
+    readonly at: string;
+    readonly kind: "at";
+} | {
+    readonly everySeconds: number;
+    readonly kind: "every";
+} | {
+    readonly cron: string;
+    readonly kind: "cron";
+    readonly timeZone: string;
+};
+/**
+ * Create one schedule in the partition owning `authority`.
+ *
+ * **`definition` is the whole of when it happens**, and which side of the seam
+ * resolves each arm is a deliberate split rather than an inconsistency. The
+ * `at` arm carries an instant and never a delay, because converting a delay is
+ * the adapter's job, done once against the clock the request arrived on — the
+ * partition is reached again by every retry and every replay, and would convert
+ * a second time and land the schedule somewhere the caller never asked for. The
+ * `every` and `cron` arms carry the *definition* and not a first instant,
+ * because resolving those needs a cron parser and a timezone database and
+ * belongs to whoever will resolve every later occurrence too. Two engines
+ * answering "when does this cron next fire" is the drift that matters here, and
+ * `.architecture-boundaries.json` does not permit `apps/api` to depend on
+ * `packages/scheduling` anyway.
+ */
+export interface CreateScheduleCommand {
+    /**
+     * **Transitional, and the reason this seam has a safe deployment order.**
+     *
+     * `apps/api` and `apps/scheduler` are separate Workers, deployed by separate
+     * sequential commands, so between them one runs new code and the other runs
+     * old. Before W2-04 this command carried `at: string` and no `definition`;
+     * replacing one field with the other would have broken **both** orderings —
+     * an old API Worker's command would reach a new partition with no
+     * `definition` at all, and a new API Worker's command would reach an old
+     * partition with no `at`. W2-02 could say "deploy the scheduler first"
+     * because it only *added* methods, and W2-03 needed no order at all because
+     * it changed no method; this is the first story to change the shape of one,
+     * and a shape change with no safe order is an outage during a routine
+     * deploy.
+     *
+     * So a partition accepts either: `definition` when the caller sends it, and
+     * this instant when it does not. That makes **scheduler first** safe, which
+     * is the order recorded in the W2-04 evidence. Remove it once both Workers
+     * are past this story — [FXO-1438](https://linear.app/flowxo/issue/FXO-1438/remove-the-transitional-at-field-from-the-partition-create-and-replace).
+     *
+     * It is declared here rather than only read defensively in the partition so
+     * that the compatibility window is visible to a reader of the seam, and so
+     * deleting it is a contract change somebody has to make on purpose.
+     */
+    readonly at?: string;
+    readonly authority: Authority;
+    readonly definition: ScheduleDefinition;
+    /**
+     * The schedule's delivery settings, resolved by the adapter.
+     *
+     * Optional for the reason `at` above is: `apps/api` and `apps/scheduler` are
+     * deployed by separate commands, so an API Worker one release behind sends a
+     * command without it. The partition then stores the shipped defaults, which is
+     * exactly the behaviour every schedule had before this field existed — so
+     * either deployment order is safe and neither produces a schedule nobody
+     * asked for.
+     */
+    readonly delivery?: {
+        readonly completion: "response" | "callback";
+        readonly maxDurationSeconds: number;
+        readonly onOverlap: "skip" | "queue";
+    };
+    /** Verified callback endpoint selected under `authority`, when this delivers. */
+    readonly endpointId?: string;
+    /** Present only when the caller sent an idempotency key. */
+    readonly idempotency?: {
+        readonly fingerprint: string;
+        readonly key: string;
+        /**
+         * Receipt lookup only. A miss returns `idempotency-probe-miss` without
+         * binding a partition, creating a schedule, or writing any other state.
+         */
+        readonly probeOnly?: boolean;
+    };
+    /**
+     * How promptly the schedule's occurrences expect to be served.
+     *
+     * Resolved by the adapter, from the caller's `latencyClass` when they sent
+     * one and from the recurrence when they did not — the same derivation the
+     * copied `validate.ts` makes, and it is the adapter's because the alternative
+     * is the partition and the MCP surface each deriving it again. Optional here
+     * on the same terms as `at`: a partition addressed by an API Worker deployed
+     * before this story receives no class and defaults it, which is what makes
+     * **scheduler first** a safe deploy order.
+     */
+    readonly latencyClass?: LatencyClass;
+    /**
+     * The caller's fairness lane within their own partition, when they named one.
+     *
+     * It selects a pacing lane and a telemetry label and nothing else. It cannot
+     * change the authority tuple, and — unlike the shard — it is not part of the
+     * Durable Object name, so no value of it can reach another object.
+     */
+    readonly partitionKey?: string;
+    /**
+     * Authenticated encrypted customer JSON. The plaintext never crosses this
+     * seam and is never stored in a D1 projection.
+     */
+    readonly payloadEnvelope?: string;
+    /** UTF-8 byte length of the plaintext JSON, before encryption. */
+    readonly payloadBytes?: number;
+    /**
+     * The verified endpoint URL captured for durable host routing.
+     *
+     * This is internal metadata, not a public response field. The Host Executor
+     * re-reads the D1 endpoint row before signing and reroutes if the URL has
+     * changed. It does not resolve or revalidate the address: that boundary was
+     * removed by FXO-1566 and FXO-1581, and this comment claimed it afterwards.
+     */
+    readonly routingUrl?: string;
+    /**
+     * The identifier the schedule will have, minted by the adapter.
+     *
+     * **The partition stopped minting this because the route function needs it
+     * first.** A schedule's shard is `partitionShardFor(scheduleId)`, so the
+     * caller has to know the identifier before it knows which Durable Object to
+     * address; an identifier minted inside the partition would be one whose shard
+     * nothing had routed to. Optional for the deployment window's sake — a
+     * partition still mints one when an older API Worker sends none, and at one
+     * shard the two agree by construction because every identifier resolves to
+     * `SINGLE_SHARD`.
+     *
+     * Remove the fallback once both Workers are past this story, on the same
+     * terms as `at`.
+     */
+    readonly scheduleId?: string;
+    readonly shard: string;
+}
+/** Read one schedule from the partition owning `authority`. */
+export interface ReadScheduleQuery {
+    readonly authority: Authority;
+    readonly scheduleId: string;
+}
+/** List the partition's schedules, oldest first. */
+export interface ListSchedulesQuery {
+    readonly authority: Authority;
+    /** Where the previous page stopped. Absent for the first page. */
+    readonly after?: {
+        readonly createdAtMs: number;
+        readonly id: string;
+    };
+    /** Whether archived schedules are included. */
+    readonly includeArchived: boolean;
+    readonly limit: number;
+}
+export type ListSchedulesOutcome = PartitionRefused | {
+    readonly schedules: readonly Schedule[];
+    /**
+     * Whether a further page exists, decided from a row the partition
+     * scanned and did not serve. `schedules` is never longer than the limit
+     * asked for — an earlier version of this comment said it was, and a
+     * reader who believed it would trim the last item off every full page.
+     */
+    readonly hasMore: boolean;
+};
+/** Stable keyset position in one schedule's occurrence history. */
+export interface OccurrencePagePosition {
+    readonly createdAtMs: number;
+    readonly id: string;
+}
+/** List retained occurrences from their authoritative partition. */
+export interface ListOccurrencesQuery {
+    /** Where the previous page stopped, including the identifier tie-break. */
+    readonly after?: OccurrencePagePosition;
+    readonly authority: Authority;
+    readonly limit: number;
+    readonly scheduleId: string;
+}
+export type ListOccurrencesOutcome = PartitionRefused | {
+    readonly hasMore: boolean;
+    readonly next?: OccurrencePagePosition;
+    readonly occurrences: readonly Occurrence[];
+};
+/** Read one retained occurrence, scoped through its owning schedule. */
+export interface ReadOccurrenceQuery {
+    readonly authority: Authority;
+    readonly occurrenceId: string;
+    readonly scheduleId: string;
+}
+export type ReadOccurrenceOutcome = PartitionRefused | {
+    readonly view: OccurrenceView;
+};
+/** Stable keyset position in one occurrence's immutable attempt history. */
+export interface AttemptPagePosition {
+    readonly id: string;
+    readonly startedAtMs: number;
+}
+/** List retained attempts from their occurrence's authoritative partition. */
+export interface ListAttemptsQuery {
+    /** Where the previous page stopped, including the identifier tie-break. */
+    readonly after?: AttemptPagePosition;
+    readonly authority: Authority;
+    readonly limit: number;
+    readonly occurrenceId: string;
+    readonly scheduleId: string;
+}
+export type ListAttemptsOutcome = PartitionRefused | {
+    readonly attempts: readonly Attempt[];
+    readonly hasMore: boolean;
+    readonly next?: AttemptPagePosition;
+};
+/** Read one attempt, scoped through both its occurrence and schedule. */
+export interface ReadAttemptQuery {
+    readonly attemptId: string;
+    readonly authority: Authority;
+    readonly occurrenceId: string;
+    readonly scheduleId: string;
+}
+export type ReadAttemptOutcome = PartitionRefused | {
+    readonly view: AttemptView;
+};
+/**
+ * Create one manual attempt under a retained occurrence.
+ *
+ * The body contributes no authority and no mutable attempt fields. The
+ * adapter fingerprints the fixed path action and the partition serializes the
+ * receipt with the new attempt, so a same-key race has one durable answer.
+ */
+export interface RedeliverOccurrenceCommand {
+    readonly authority: Authority;
+    readonly idempotency: {
+        readonly fingerprint: string;
+        readonly key: string;
+    };
+    readonly occurrenceId: string;
+    readonly scheduleId: string;
+}
+export type RedeliverOccurrenceOutcome = PartitionRefused | {
+    readonly idempotency: IdempotencyDisposition;
+    readonly view: AttemptView;
+};
+/**
+ * A write against an existing schedule.
+ *
+ * `expectedVersion` is the caller's precondition and is absent when they sent
+ * none. Absent means an unconditional write, not "whatever the current version
+ * is": the partition reads the row inside the same transaction it writes it, so
+ * an unconditional write is atomic without inventing a precondition nobody
+ * stated.
+ */
+export interface ScheduleWriteCommand {
+    readonly authority: Authority;
+    readonly expectedVersion?: number;
+    readonly scheduleId: string;
+}
+/** Replace a schedule's definition, starting a new generation. */
+export interface ReplaceScheduleCommand extends ScheduleWriteCommand {
+    /**
+     * The replacement's delivery settings.
+     *
+     * Optional for the same deployment reason `CreateScheduleCommand.delivery`
+     * is: an API Worker one release behind sends nothing, and the partition then
+     * leaves the stored settings alone rather than resetting a paying customer's
+     * twelve-hour schedule to five seconds during a rolling deploy.
+     */
+    readonly delivery?: {
+        readonly completion: "response" | "callback";
+        readonly maxDurationSeconds: number;
+        readonly onOverlap: "skip" | "queue";
+    };
+    /** Transitional, for the reason `CreateScheduleCommand.at` gives. */
+    readonly at?: string;
+    /** The replacement definition, on the same terms as a create's. */
+    readonly definition: ScheduleDefinition;
+    /** Replacement endpoint; absent preserves the stored endpoint. */
+    readonly endpointId?: string;
+    /**
+     * The class the replacement runs under, resolved the way a create's is.
+     *
+     * A replace carries this rather than inheriting it because the class is
+     * derived from the recurrence when the caller does not state one, and a
+     * replace is precisely the operation that changes the recurrence: a one-shot
+     * thirty seconds out that becomes a nightly cron is `realtime` becoming
+     * `bulk`, and keeping the old answer would pace a campaign in the lane a
+     * human is waiting in. Absent leaves the stored class alone, which is what an
+     * API Worker deployed before this story sends.
+     */
+    readonly latencyClass?: LatencyClass;
+    /** Replacement encrypted payload; absent preserves the stored payload. */
+    readonly payloadEnvelope?: string;
+    /** Plaintext byte length paired with `payloadEnvelope`. */
+    readonly payloadBytes?: number;
+    /** Replacement routing URL paired with `endpointId`. */
+    readonly routingUrl?: string;
+    /**
+     * The fairness lane the schedule already runs in, echoed back unchanged.
+     *
+     * **Immutable after create, since FXO-1451.** W2-05 shipped it settable on
+     * replace and clearable by omission; `classifyChange` is what reversed that.
+     * Widening an accepted behaviour later is additive and narrowing it is
+     * breaking, so shipping immutable keeps both doors open and shipping mutable
+     * shuts one — and nobody has asked to move a schedule between fairness lanes.
+     *
+     * Not "reject any replace that carries it": the natural client flow is read,
+     * modify, write, and that body carries back the key it just read. So a value
+     * **equal** to the stored one is accepted, and a value that would change or
+     * set one is refused `invalid-request` naming the field.
+     *
+     * Omission means "leave it alone". An explicit `null` is a clear attempt and
+     * is refused like any other value that does not equal the stored key. The
+     * rolling Scheduler Durable Object compatibility rule that once treated
+     * `null` as omission ended when W8-10 retired that runtime.
+     */
+    readonly partitionKey?: string;
+}
+/**
+ * Ask one partition what it expects to fire.
+ *
+ * The window is half-open — `fromMs <= instant < toMs` — and `bucketMs` must be
+ * a whole number of the partition's internal minute buckets, which the public
+ * request bound already guarantees. Sending anything else would make the
+ * re-aggregation approximate, and an approximate capacity number is one nobody
+ * can reconcile against a bill.
+ */
+export interface ForecastQuery {
+    readonly authority: Authority;
+    readonly bucketMs: number;
+    readonly fromMs: number;
+    readonly toMs: number;
+}
+/** One bucket, as one partition sees it. */
+export interface ForecastPartitionBucket {
+    readonly bucketStartMs: number;
+    readonly byLatencyClass: Readonly<Record<LatencyClass, number>>;
+    readonly count: number;
+    /** Occurrences here that are the next firing of their schedule. */
+    readonly nextFireCount: number;
+    /**
+     * Named customer keys and their counts, ascending by key.
+     *
+     * **Pairs rather than an object**, because a null-prototype map is what stops
+     * a key called `__proto__` being swallowed by a prototype setter and
+     * structured clone refuses to serialize one — which arrives as an unreachable
+     * partition rather than as a type error. The caller rebuilds a
+     * null-prototype map where the answer is rendered.
+     *
+     * Named keys only: a schedule that chose none is in `unkeyedCount`.
+     */
+    readonly partitionKeys: readonly {
+        readonly key: string;
+        readonly n: number;
+    }[];
+    readonly unkeyedCount: number;
+}
+/**
+ * What one partition expects, and how old the answer is.
+ *
+ * `truncated` is a refusal in waiting rather than a caveat a caller may ignore.
+ * A partition that hit a projection bound is reporting a floor, and the one
+ * consumer this shape exists for reads a low number as a quiet book and scales
+ * *down* — so the API Worker turns it into `service_unavailable` rather than
+ * publishing a number that reads as smaller than the truth.
+ */
+export type ForecastOutcome = PartitionRefused | {
+    /**
+     * When this partition's snapshot was built.
+     *
+     * **Absent when it has none** — a partition nobody has written to holds
+     * nothing, so it has nothing to be stale about and must not vouch for
+     * freshness one way or the other. Reporting the read's own instant
+     * instead made the published `asOf` jitter between reads of the same
+     * unchanged book, because a project spans several shards and most of them
+     * are usually empty.
+     */
+    readonly asOfMs?: number;
+    readonly buckets: readonly ForecastPartitionBucket[];
+    readonly truncated: boolean;
+};
+/**
+ * What a Scheduler Partition Durable Object answers.
+ *
+ * `SchedulerPartitionDO` declares `implements PartitionRpc`, so the two sides
+ * of this seam cannot drift without failing to compile. The API Worker brands
+ * its namespace binding with a `Rpc.DurableObjectBranded` extension of this
+ * interface; the branding is a Cloudflare type and stays in the adapter, which
+ * is the layer allowed to name one.
+ */
+export interface PartitionRpc {
+    archiveSchedule(command: ScheduleWriteCommand): Promise<ScheduleWriteOutcome>;
+    forecastOccurrences(query: ForecastQuery): Promise<ForecastOutcome>;
+    cancelSchedule(command: ScheduleWriteCommand): Promise<ScheduleWriteOutcome>;
+    createSchedule(command: CreateScheduleCommand): Promise<CreateScheduleOutcome>;
+    drainProjections(query: DrainProjectionsQuery): Promise<DrainProjectionsOutcome>;
+    listAttempts(query: ListAttemptsQuery): Promise<ListAttemptsOutcome>;
+    listOccurrences(query: ListOccurrencesQuery): Promise<ListOccurrencesOutcome>;
+    listSchedules(query: ListSchedulesQuery): Promise<ListSchedulesOutcome>;
+    pauseSchedule(command: ScheduleWriteCommand): Promise<ScheduleWriteOutcome>;
+    readAttempt(query: ReadAttemptQuery): Promise<ReadAttemptOutcome>;
+    readOccurrence(query: ReadOccurrenceQuery): Promise<ReadOccurrenceOutcome>;
+    readSchedule(query: ReadScheduleQuery): Promise<PartitionOutcome>;
+    redeliverOccurrence(command: RedeliverOccurrenceCommand): Promise<RedeliverOccurrenceOutcome>;
+    replaceSchedule(command: ReplaceScheduleCommand): Promise<ScheduleWriteOutcome>;
+    resumeSchedule(command: ScheduleWriteCommand): Promise<ScheduleWriteOutcome>;
+    settleProjections(command: SettleProjectionsCommand): Promise<SettleProjectionsOutcome>;
+}