@kedge/server 0.0.0-stage → 0.10.0

package/src/types.ts

@@ -0,0 +1,841 @@
+// What the HTTP layer needs from a runtime. @kedge/runtime-cf implements
+// CartGateway with one Durable Object per cart; tests can use fakes.
+import type {
+  AccessContext,
+  Clock,
+  CustomFields,
+  IdGenerator,
+  Json,
+  JsonRecord,
+  LineInput,
+  LinePatch,
+  OrderStore,
+  OrderView,
+  Overrides,
+  PricedCart,
+  StoreProof,
+  TaxContext,
+} from "@kedge/core";
+
+export interface CartView {
+  id: string;
+  status: "active" | "completing" | "completed";
+  currency_code: string;
+  email: string | null;
+  revision: number;
+  locale: string;
+  /** The cart's `order` custom fields, projected for the reader. */
+  custom: JsonRecord;
+  consents: Record<string, { revision_id: string }>;
+  /** "unavailable" when a plugin the cart needs can't price it now; totals are then null (§1.1). */
+  pricing: "ok" | "unavailable";
+  lines: {
+    id: string;
+    variant_id: string;
+    kind: string;
+    parent_line_id: string | null;
+    quantity_mode: "own" | "per_parent";
+    quantity_per_parent: number | null;
+    period_start: number | null;
+    period_end: number | null;
+    custom: JsonRecord;
+    sku: string;
+    title: string;
+    unit_amount: number | null;
+    quantity: number;
+    line_total: number | null;
+    charge_class: "revenue" | "deposit" | null;
+    breakdown: Json;
+  }[];
+  totals: PricedCart["totals"] | null;
+  /** What's still missing before complete can succeed (docs/05 §3). */
+  requirements: string[];
+  order_id: string | null;
+}
+
+/** Errors cross the Durable Object boundary as data, so codes and details survive. */
+export type Result<T> =
+  | {
+      ok: true;
+      value: T;
+      /** A customer session the cart's own read renewed (§2.3): the Worker refreshes its cookie. */
+      session?: { expiresAt: number };
+    }
+  | { ok: false; error: { code: string; message: string; status?: number; details?: Record<string, unknown> } };
+
+/** What a store write to the cart itself may change (§4, §5). */
+export interface CartPatch {
+  email?: string | null;
+  locale?: string;
+  custom?: JsonRecord;
+  consents?: Record<string, { revision_id: string; typed_name: string } | null>;
+}
+
+/**
+ * Every call after create carries the cart token, so the cart can check it
+ * again (a second layer), and the request's store proof, which the cart
+ * re-proves inside the batch it sends anyway (p0.5 §6.2).
+ */
+export interface CartGateway {
+  create(
+    cartId: string,
+    proof: StoreProof,
+    input: { currency: string; email: string | null; locale?: string },
+  ): Promise<Result<CartView>>;
+  get(cartId: string, token: string, proof: StoreProof): Promise<Result<CartView>>;
+  setLine(
+    cartId: string,
+    token: string,
+    proof: StoreProof,
+    variantId: string,
+    quantity: number,
+    mode: "add" | "set",
+  ): Promise<Result<CartView>>;
+  setEmail(cartId: string, token: string, proof: StoreProof, email: string | null): Promise<Result<CartView>>;
+  // P0.3: lines by id (§1.1) and the cart's own fields (§4, §5).
+  addLine(cartId: string, token: string, proof: StoreProof, input: LineInput): Promise<Result<CartView>>;
+  changeLine(
+    cartId: string,
+    token: string,
+    proof: StoreProof,
+    lineId: string,
+    patch: LinePatch,
+  ): Promise<Result<CartView>>;
+  removeLines(cartId: string, token: string, proof: StoreProof, lineIds: string[]): Promise<Result<CartView>>;
+  update(cartId: string, token: string, proof: StoreProof, patch: CartPatch): Promise<Result<CartView>>;
+  complete(
+    cartId: string,
+    token: string,
+    proof: StoreProof,
+    expectedTotal: number,
+  ): Promise<Result<{ order: OrderView }>>;
+}
+
+export interface ProductReader {
+  productByHandle(
+    handle: string,
+    currency: string,
+  ): Promise<{
+    id: string;
+    title: string;
+    handle: string;
+    variants: {
+      id: string;
+      sku: string;
+      title: string;
+      price: { amount: number; currency_code: string } | null;
+      available: number;
+    }[];
+  } | null>;
+  createProduct(
+    input: {
+      title: string;
+      handle: string;
+      variants: {
+        sku: string;
+        title: string;
+        prices: Record<string, number>;
+        stock: Record<string, number>;
+        allowedKinds?: string[];
+        inventory?: boolean;
+      }[];
+    },
+    who: CommandIdentity,
+  ): Promise<{ productId: string; variantIds: string[] }>;
+  setAllowedKinds(variantId: string, kinds: string[]): Promise<void>;
+}
+
+/** Staff-set store settings P0.3 adds (§3.2, §5.1). */
+export interface SettingsStore {
+  tax(): Promise<TaxContext>;
+  setTax(input: TaxContext): Promise<TaxContext>;
+  publishRevision(
+    policy: string,
+    input: { locale: string; body: string },
+    who: CommandIdentity,
+  ): Promise<{
+    id: string;
+    policy: string;
+    version: number;
+    locale: string;
+    body: string;
+    digest: string;
+    publishedAt: number;
+  }>;
+  currentRevision(
+    policy: string,
+    locale: string,
+  ): Promise<{
+    id: string;
+    policy: string;
+    version: number;
+    locale: string;
+    body: string;
+    digest: string;
+    publishedAt: number;
+  } | null>;
+  requiredPolicies(): Promise<string[]>;
+  setRequiredPolicies(policies: string[]): Promise<string[]>;
+}
+
+/**
+ * The line features' rollout mode (§1.6). `legacy`: only P0.2's routes and
+ * RPC methods, for the first deployment of an upgrade. `on`: everything.
+ * `frozen`: the rollback once `on` has run, refusing new feature state but
+ * keeping every operation existing carts need.
+ */
+export type LineFeatures = "legacy" | "on" | "frozen";
+
+export interface Secrets {
+  cartTokenSecret: string;
+  orderTokenSecret: string;
+}
+
+// ---- P0.5: access (p0.5-auth-and-access.md §2, §3) --------------------------------
+
+export type Pool = "staff" | "customer";
+
+/** A valid session, as the access read found it. */
+export interface AccessSession {
+  id: string;
+  pool: Pool;
+  principalId: string;
+  method: string;
+  authenticatedAt: number;
+  lastSeenAt: number;
+  expiresAt: number;
+  enrolUntil: number | null;
+  epoch: number;
+}
+
+/** A verified API key. */
+export interface AccessKey {
+  id: string;
+  type: "secret" | "publishable";
+  storefrontId: string | null;
+  lastUsedAt: number | null;
+  /** A publishable key's storefront's allowed browser origins (§6.2). */
+  origins: readonly string[];
+}
+
+export interface ResolvedAccess {
+  ctx: AccessContext;
+  session?: AccessSession;
+  key?: AccessKey;
+}
+
+/** The per-request access read (§3.3); @kedge/db's D1AccessStore. */
+export interface AccessStore {
+  session(pool: Pool, token: string, now: number): Promise<ResolvedAccess | null>;
+  maintenanceDue(session: AccessSession, now: number): boolean;
+  /** Staff activity or a customer renewal; the renewed expiry, if any. */
+  maintain(session: AccessSession, now: number): Promise<number | null>;
+  apiKey(presented: string, now: number): Promise<ResolvedAccess | null>;
+  /** A CLI session's principal (p0.10 §6.2), or null when the token names no unexpired one. */
+  cliSession(token: string, now: number): Promise<ResolvedAccess | null>;
+  keyTouchDue(key: { lastUsedAt: number | null }, now: number): boolean;
+  touchKey(keyId: string, now: number): Promise<void>;
+  /** Counts a failed key verification against the address; false once past the limit (§4.3). */
+  keyFailure(address: string | null, now: number): Promise<boolean>;
+  /**
+   * A publishable key's lookup id and its secret's digest under every pepper
+   * version this Worker holds, with no D1 read (§6.2); null if malformed.
+   */
+  keyProof(presented: string): Promise<{ lookup: string; digests: string[] } | null>;
+  /** Every origin a storefront with an unrevoked publishable key lists, for preflights (§6.2). */
+  storefrontOrigins(now: number): Promise<ReadonlySet<string>>;
+  csrf(sessionToken: string, token: string, now: number): Promise<"ok" | "expired" | "invalid">;
+  /** Consumes a session route's rate counters (§2.8); false once past a limit. */
+  limit(
+    policy: "session" | "session_read",
+    pool: Pool,
+    subjects: { session?: string; address?: string },
+    now: number,
+  ): Promise<boolean>;
+}
+
+export interface ClientInfo {
+  ip: string | null;
+  userAgent: string | null;
+}
+
+/** A session a ceremony made; its raw token goes to the client once. */
+export interface IssuedSession {
+  id: string;
+  token: string;
+  pool: Pool;
+  principalId: string;
+  method: string;
+  expiresAt: number;
+  csrfToken: string;
+}
+
+export interface Caller {
+  sessionId: string;
+  principalId: string;
+}
+
+/** Kedge's credential ceremonies (§2); @kedge/db's D1AuthStore. */
+export interface AuthCeremonies {
+  staffSignIn(
+    input: { email: string; password: string; deviceToken?: string | null },
+    client: ClientInfo,
+    now: number,
+  ): Promise<
+    | { kind: "session"; session: IssuedSession; deviceToken: string | null }
+    | { kind: "challenge"; challengeToken: string; expiresAt: number }
+  >;
+  staffTotpChallenge(
+    input: { challengeToken: string; code: string; deviceToken?: string | null },
+    client: ClientInfo,
+    now: number,
+  ): Promise<{ session: IssuedSession; deviceToken: string | null }>;
+  totpEnrolStart(caller: Caller, account: string, now: number): Promise<{ uri: string; expiresAt: number }>;
+  totpEnrolConfirm(caller: Caller, code: string, client: ClientInfo, now: number): Promise<void>;
+  staffChangePassword(caller: Caller, current: string, next: string, client: ClientInfo, now: number): Promise<void>;
+  signOut(pool: Pool, token: string, now: number, who: { principalId: string; ip: string | null }): Promise<void>;
+  signOutEverywhere(caller: Caller, pool: Pool, now: number, ip: string | null): Promise<void>;
+  acceptInvite(
+    input: { token: string; password: string; resumeNonce: string },
+    client: ClientInfo,
+    now: number,
+  ): Promise<IssuedSession>;
+  resumeInvite(
+    input: { token: string; password: string; resumeNonce: string },
+    client: ClientInfo,
+    now: number,
+  ): Promise<IssuedSession>;
+  requestCode(email: string, client: ClientInfo, now: number): Promise<void>;
+  verifyCode(email: string, code: string, client: ClientInfo, now: number): Promise<IssuedSession>;
+  refreshCsrf(sessionToken: string, now: number): Promise<{ csrfToken: string; expiresAt: number }>;
+  /** A signed-in customer's own record (`/store/customers/me`). */
+  customerProfile(customerId: string): Promise<{ id: string; email: string; createdAt: number } | null>;
+  /** A signed-in staff member's email, for the authenticator label. */
+  staffEmail(staffId: string): Promise<string | null>;
+  /** P0.9 (§4.4): a member's email and roles. */
+  staffProfile(
+    staffId: string,
+  ): Promise<{ email: string; roles: { id: string; name: string; strong: boolean }[] } | null>;
+  /** P0.9 (§4.2): whether the member has an enrolled TOTP factor. */
+  staffFactorEnrolled(staffId: string): Promise<boolean>;
+}
+
+/** What one admin request's batches record and re-prove (§7.1, §3.3). */
+export interface AdminScope {
+  access: ResolvedAccess;
+  /** The route's permission(s), held unscoped, re-proved in every batch. */
+  required: readonly string[];
+  action: string;
+  ip: string | null;
+  userAgent: string | null;
+  /** What the batch scope's audit row says the request was for (§7.2): its target and its input, made audit-safe. */
+  entity?: { type: string; id: string | null };
+  changes?: unknown;
+  /** The request as a command (§8) when its route's store keeps no envelope of its own. */
+  command?: { key: string; operation: string; targets: readonly string[]; input: unknown };
+}
+
+/** A scope-recorded command's stored outcome (§8): what happened and the ids it touched. */
+export interface ScopeOutcome {
+  outcome: string;
+  ids: readonly string[];
+}
+
+/** Runs a handler with every batch it sends audited and guarded (@kedge/db's adminScopeRunner). */
+export interface AdminScopeRunner {
+  /** A command already recorded under its key is `replayed` and `fn` doesn't run. */
+  run<T>(scope: AdminScope, fn: () => Promise<T>): Promise<{ replayed: ScopeOutcome | null }>;
+  /** After a refused request: the outcome of a concurrent send with the same key that won. */
+  replayed(scope: AdminScope): Promise<ScopeOutcome | null>;
+}
+
+export interface GrantInput {
+  permission: string;
+  rowScope: "all" | "self" | "location";
+}
+export interface RoleRef {
+  id: string;
+  version: number;
+}
+export interface AdminRequest {
+  idempotencyKey?: string | null;
+  ip?: string | null;
+  userAgent?: string | null;
+}
+export interface IssuedInvite {
+  id: string;
+  token: string;
+  expiresAt: number;
+}
+/** What a credential reference made, kept for ever (p0.10 §6.2). */
+export interface CredentialRefState {
+  ref: string;
+  kind: "secret" | "publishable" | "storefront";
+  state: "used" | "fenced" | "revoked";
+  storefrontId: string | null;
+  keyId: string | null;
+}
+
+export type CredentialRefCreate =
+  | { kind: "secret"; name: string; grants: readonly GrantInput[]; locationIds?: readonly string[] }
+  | { kind: "publishable"; name: string; storefrontId: string }
+  | { kind: "storefront"; name: string; allowedOrigins: readonly string[] };
+
+export interface IssuedKey {
+  id: string;
+  key: string;
+  tokenPrefix: string;
+}
+
+/** Staff, roles, invites, storefronts and keys (§3, §4); @kedge/db's D1AdminStore. */
+export interface AdminStore {
+  // P0.6b's webhook endpoints (p0.6b §2.1, §2.7, §2.9).
+  createWebhookEndpoint(
+    ctx: AccessContext,
+    input: { url: string; events: readonly string[]; grants: readonly string[]; description?: string | null },
+    req?: AdminRequest,
+  ): Promise<{ id: string; secret: string }>;
+  updateWebhookEndpoint(
+    ctx: AccessContext,
+    id: string,
+    input: { url?: string; events?: readonly string[]; grants?: readonly string[]; description?: string | null },
+    req?: AdminRequest,
+  ): Promise<{ id: string; generation: number }>;
+  setWebhookEndpointStatus(
+    ctx: AccessContext,
+    id: string,
+    action: "disable" | "enable" | "delete",
+    req?: AdminRequest,
+  ): Promise<void>;
+  rotateWebhookSecret(ctx: AccessContext, id: string, req?: AdminRequest): Promise<{ id: string; secret: string }>;
+  replayWebhookDelivery(ctx: AccessContext, deliveryId: string, req?: AdminRequest): Promise<{ id: string }>;
+  testWebhookEndpoint(ctx: AccessContext, id: string, req?: AdminRequest): Promise<{ id: string }>;
+  webhookEndpoints(
+    ctx: AccessContext,
+    q: { status: "active" | "disabled"; after: string | null; limit: number },
+  ): Promise<{ endpoints: unknown[]; next: string | null }>;
+  staffList(ctx: AccessContext): Promise<unknown[]>;
+  rolesList(ctx: AccessContext): Promise<unknown[]>;
+  keysList(ctx: AccessContext, opts?: { stalePepper?: boolean }): Promise<unknown[]>;
+  storefrontsList(ctx: AccessContext): Promise<unknown[]>;
+  createRole(
+    ctx: AccessContext,
+    input: { code: string; name: string; grants: readonly GrantInput[]; strongAuth?: boolean },
+    req?: AdminRequest,
+  ): Promise<{ id: string; version: number | null }>;
+  setRoleGrants(
+    ctx: AccessContext,
+    roleId: string,
+    input: { expectedVersion: number; grants: readonly GrantInput[] },
+    req?: AdminRequest,
+  ): Promise<{ id: string; version: number | null }>;
+  deleteRole(ctx: AccessContext, roleId: string, req?: AdminRequest): Promise<void>;
+  assignRoles(
+    ctx: AccessContext,
+    staffId: string,
+    input: { roleIds: readonly RoleRef[] },
+    req?: AdminRequest,
+  ): Promise<void>;
+  setLocations(
+    ctx: AccessContext,
+    principal: { staffId: string } | { apiKeyId: string },
+    locationIds: readonly string[],
+    req?: AdminRequest,
+  ): Promise<void>;
+  deactivateStaff(ctx: AccessContext, staffId: string, req?: AdminRequest): Promise<void>;
+  createInvite(
+    ctx: AccessContext,
+    input: { email: string; roleIds: readonly RoleRef[] },
+    req?: AdminRequest,
+  ): Promise<IssuedInvite>;
+  resetFactors(ctx: AccessContext, staffId: string, req?: AdminRequest): Promise<IssuedInvite>;
+  createStorefront(
+    ctx: AccessContext,
+    input: { name: string; allowedOrigins: readonly string[] },
+    req?: AdminRequest,
+  ): Promise<{ id: string }>;
+  setOrigins(
+    ctx: AccessContext,
+    storefrontId: string,
+    allowedOrigins: readonly string[],
+    req?: AdminRequest,
+    /** The list the caller read: the write is refused CONFLICT if it changed since. */
+    expected?: readonly string[],
+  ): Promise<void>;
+  createSecretKey(
+    ctx: AccessContext,
+    input: { name: string; grants: readonly GrantInput[]; locationIds?: readonly string[] },
+    req?: AdminRequest,
+  ): Promise<IssuedKey>;
+  createPublishableKey(
+    ctx: AccessContext,
+    input: { name: string; storefrontId: string },
+    req?: AdminRequest,
+  ): Promise<IssuedKey>;
+  revokeKey(
+    ctx: AccessContext,
+    keyId: string,
+    at?: number,
+    req?: AdminRequest,
+    storefrontId?: string,
+  ): Promise<{ id: string; revokedAt: number | null }>;
+  /** A key made under a caller-chosen ref: at most one, ever (p0.10 §6.2). */
+  createByRef(
+    ctx: AccessContext,
+    ref: string,
+    input: CredentialRefCreate,
+    req?: AdminRequest,
+  ): Promise<CredentialRefState & IssuedKey>;
+  /** Settles a ref for good: fenced when unused, its key revoked when used. */
+  voidRef(
+    ctx: AccessContext,
+    ref: string,
+    kind: CredentialRefState["kind"],
+    req?: AdminRequest,
+  ): Promise<CredentialRefState>;
+  rotateKey(
+    ctx: AccessContext,
+    keyId: string,
+    input: { overlapMs: number },
+    req?: AdminRequest,
+    storefrontId?: string,
+  ): Promise<IssuedKey & { previous: { id: string; revokedAt: number | null } }>;
+  auditLog(
+    ctx: AccessContext,
+    filter?: {
+      entityType?: string;
+      entityId?: string;
+      actor?: string;
+      before?: { createdAt: number; id: string };
+      limit?: number;
+    },
+  ): Promise<{ entries: unknown[]; next: { createdAt: number; id: string } | null }>;
+}
+
+export interface OrderFilter {
+  field: string;
+  op: "eq" | "in" | "gte" | "lt";
+  value: string | number | readonly (string | number)[];
+}
+export interface OrderPage {
+  data: Record<string, unknown>[];
+  next_cursor: string | null;
+  has_more: boolean;
+}
+/** Authorized order reads through the resource registry (§5.2); @kedge/db's D1OrderQuery. */
+export interface OrderQuery {
+  get(ctx: AccessContext, id: string): Promise<Record<string, unknown> | null>;
+  list(
+    ctx: AccessContext,
+    req: {
+      filters?: readonly OrderFilter[];
+      sort?: { field: string; direction: "asc" | "desc" };
+      expand?: readonly string[];
+      cursor?: string | null;
+      limit?: number;
+    },
+  ): Promise<OrderPage>;
+  search(
+    ctx: AccessContext,
+    req: {
+      filters?: readonly OrderFilter[];
+      sort?: { field: string; direction: "asc" | "desc" };
+      search?: { fields: readonly string[]; term: string };
+      expand?: readonly string[];
+      cursor?: string | null;
+      limit?: number;
+    },
+  ): Promise<OrderPage>;
+}
+
+export interface KeyringStateView {
+  family: "pepper" | "totp" | "auth";
+  active: number;
+  retiring: number | null;
+  activatedAt: number;
+  held: readonly number[];
+}
+/** The keyring protocol's steps (§4.1, §9); @kedge/db's D1KeyringStore. */
+export interface KeyringAdmin {
+  state(): Promise<KeyringStateView[]>;
+  activate(
+    family: KeyringStateView["family"],
+    version: number,
+    now: number,
+    who?: CommandIdentity,
+  ): Promise<KeyringStateView>;
+  complete(family: KeyringStateView["family"], now: number, who?: CommandIdentity): Promise<KeyringStateView>;
+  rollback(family: KeyringStateView["family"], now: number, who?: CommandIdentity): Promise<KeyringStateView>;
+}
+
+export interface AuthDeps {
+  access: AccessStore;
+  ceremonies: AuthCeremonies;
+  scoped: AdminScopeRunner;
+  /** `ADMIN_ORIGINS`: the admin's browser origins (§2.9, §9). The Worker's own origin is one too (p0.9 §4.1). */
+  adminOrigins: readonly string[];
+  /** P0.9 (§2.4): the admin build bundled with this Worker, `KEDGE_ADMIN_BUILD`; null when none is. */
+  adminBuild?: string | null;
+  /** P0.9 (§9): the deployment's resolved access contract, hashed once at boot; part of every authority fingerprint. */
+  accessContract?: string;
+}
+
+/** P0.4's capacity administration (p0.4-dated-capacity.md §6); @kedge/db's D1CapacityStore. */
+export interface CapacityAdmin {
+  createPool(
+    who: CommandIdentity,
+    input: {
+      kind: string;
+      inventoryItemId?: string | null;
+      locationId?: string | null;
+      bucketMinutes: number;
+      maxSpan: number;
+      initialBase: number;
+    },
+  ): Promise<{ id: string }>;
+  changeBase(
+    who: CommandIdentity,
+    poolId: string,
+    input: { delta: number; origin: "physical" | "scheduled"; date?: number; reason: string },
+  ): Promise<{ id: string; fromBucket: number }>;
+  cancelBaseChange(changeId: string): Promise<void>;
+  adjust(
+    who: CommandIdentity,
+    poolId: string,
+    input: { start: number; end: number; delta: number; reason: string },
+  ): Promise<{ id: string; firstBucket: number; lastBucket: number }>;
+  cancelAdjustment(adjustmentId: string): Promise<void>;
+  setCeiling(
+    who: CommandIdentity,
+    poolId: string,
+    input: { slotOfWeek: number; ceiling: number | null },
+  ): Promise<{ poolId: string; slotOfWeek: number; ceiling: number | null }>;
+  setBuffer(input: { kind: string; poolKind: string; before: number; after: number }): Promise<void>;
+  hold(
+    who: CommandIdentity,
+    poolId: string,
+    input: { kind: "block" | "maintenance" | "import"; start: number; end: number; qty: number },
+  ): Promise<{ id: string; firstBucket: number; lastBucket: number }>;
+  releaseHold(holdId: string): Promise<void>;
+  mapScope(
+    who: CommandIdentity,
+    input: { mapping: string; key: string; poolId: string },
+  ): Promise<{ mapping: string; key: string; poolId: string }>;
+  unmapScope(input: { mapping: string; key: string; poolId: string }): Promise<void>;
+  markNotReopenable(orderId: string): Promise<void>;
+  convert(
+    who: CommandIdentity,
+    itemId: string,
+    input: { to: "count" | "dated" | "none"; bucketMinutes?: number; maxSpan?: number; reason: string },
+  ): Promise<{ itemId: string; tracking: string; pools: string[] }>;
+  replacePool(
+    who: CommandIdentity,
+    poolId: string,
+    input: { bucketMinutes: number; maxSpan: number; reason: string },
+  ): Promise<{ id: string }>;
+  pools(filter?: { inventoryItemId?: string; kind?: string }): Promise<unknown[]>;
+  poolAvailability(poolId: string, first: number, last: number): Promise<unknown>;
+  holdsOn(poolId: string, first: number, last: number): Promise<unknown[]>;
+  shortages(): Promise<unknown>;
+  negativeBases(): Promise<unknown[]>;
+}
+
+/** The relay's delivery tables (p0.6a §2.3; p0.6b §2.3): subscriber, release, resolution and webhook deliveries. */
+export type DeliveryKind = "sub" | "rel" | "res" | "whk";
+
+/**
+ * P0.6a's staff surface (p0.6a §2.8, §4.9): failed, blocked and orphaned
+ * deliveries, the relay's health, and the unresolved effects across the
+ * journal's shards. @kedge/runtime-cf implements it over D1 and the journal.
+ */
+export interface DeliveryAdmin {
+  problems(q: {
+    state: "failed" | "blocked" | "orphaned";
+    plugin?: string;
+    /** The types whose webhook deliveries the reader may see (p0.6b §2.9); none listed without it. */
+    webhookTypes?: readonly string[];
+    cursor: string | null;
+    limit: number;
+  }): Promise<{ items: unknown[]; next: string | null }>;
+  /** A webhook delivery's event type, for the routes that name one (p0.6b §2.9). */
+  webhookEventType(seq: number): Promise<string | null>;
+  /** False when the delivery isn't `failed` (a second retry, or one racing a discard). */
+  /** `expected`: the row's `updated_at` the caller acted on, or null for any failed row. */
+  retry(kind: DeliveryKind, seq: number, expected?: number | null): Promise<boolean>;
+  discard(kind: DeliveryKind, seq: number, expected?: number | null): Promise<boolean>;
+  health(): Promise<unknown>;
+  effects(q: {
+    state: "unresolved" | "conflict" | "divergence";
+    cursor: string | null;
+    limit: number;
+    /** The webhook types the reader may see, for `conflict`: a webhook's key conflict is listed too (codex code r2). */
+    webhookTypes: readonly string[];
+  }): Promise<{ items: unknown[]; next: string | null }>;
+  /**
+   * Records a staff decision as a resolution delivery (§4.9), after checking
+   * it against the record as it is now and the operation this deployment
+   * declares; refused before anything is written when it lacks what its form needs.
+   */
+  resolve(input: {
+    key: string;
+    expectedRevision: number;
+    form: "observe" | "succeeded" | "failed_final";
+    result?: Record<string, unknown>;
+    code?: string;
+    staffId: string;
+    /** Required: the resolution is created under it, and its retry answers the same id (code r17). */
+    idempotencyKey: string | null;
+  }): Promise<{ resolutionId: string; replayed?: boolean }>;
+  resolution(id: string): Promise<unknown | null>;
+}
+
+/** P0.6b's delivery log (§2.9): bounded per readable type. @kedge/db's D1WebhookStore. */
+export interface WebhookLog {
+  log(q: {
+    types: readonly string[];
+    endpoint?: string;
+    state?: "pending" | "finalizing" | "done" | "failed";
+    after: number;
+    limit: number;
+  }): Promise<{ items: Record<string, unknown>[]; next: number | null }>;
+}
+
+/** P0.6b's preview capture log (§4.4); null outside a preview. */
+export interface PreviewCaptures {
+  list(q: { port?: string; after: number; limit: number }): Promise<Record<string, unknown>[] | null>;
+}
+
+/** P0.6b's business calendar (§3), over the store's zone, which the runtime holds. */
+export interface CalendarAdmin {
+  get(now: number): Promise<unknown>;
+  set(input: { workingDays: number; cutoffMinutes: number | null }): Promise<void>;
+  putHoliday(day: string, name: string): Promise<void>;
+  deleteHoliday(day: string): Promise<void>;
+}
+
+/** A command's caller and its Idempotency-Key (p0.4 §6). */
+export interface CommandIdentity {
+  principal: string;
+  key: string | null;
+}
+
+/** Store availability (dated-capacity.md §7); @kedge/db's D1AvailabilityStore. */
+export interface AvailabilityReader {
+  available(input: {
+    variantId: string;
+    kind?: string;
+    periods: { start: number; end: number }[];
+    locationId?: string;
+    now: number;
+  }): Promise<{ kind: string; periods: { start: number; end: number; available: number | null }[] }>;
+  days(from: number, days: number): { start: number; end: number }[];
+}
+
+/** P0.7 (§3.4, §3.8): track commands and reads; @kedge/db's D1TrackStore. */
+export interface TrackToken {
+  recovery_id: string;
+  version: number;
+}
+export interface TrackCommandInput {
+  plugin: string;
+  track: string;
+  aggregateId: string;
+  idempotencyKey: string | null;
+  ip?: string | null;
+  userAgent?: string | null;
+}
+export interface TrackAdmin {
+  read(ctx: AccessContext, plugin: string, track: string, aggregateId: string, after?: number): Promise<unknown>;
+  start(ctx: AccessContext, cmd: TrackCommandInput): Promise<unknown>;
+  transition(
+    ctx: AccessContext,
+    cmd: TrackCommandInput & { transition: string; expected: TrackToken; input?: unknown; comment?: string | null },
+  ): Promise<unknown>;
+}
+
+/** P0.7 (§4.4, §4.7): plugin entities; @kedge/db's D1EntityStore. */
+export interface EntityAdmin {
+  list(
+    ctx: AccessContext,
+    plugin: string,
+    entity: string,
+    req: { query: unknown; cursor?: string | null; limit?: number; state?: "live" | "archived" },
+  ): Promise<unknown>;
+  get(ctx: AccessContext, plugin: string, entity: string, id: string): Promise<Record<string, unknown> | null>;
+  create(
+    ctx: AccessContext,
+    cmd: {
+      plugin: string;
+      entity: string;
+      values: unknown;
+      orderId?: string | null;
+      idempotencyKey: string | null;
+      ip?: string | null;
+      userAgent?: string | null;
+    },
+  ): Promise<unknown>;
+  write(
+    ctx: AccessContext,
+    cmd: {
+      plugin: string;
+      entity: string;
+      id: string;
+      version: number;
+      set?: unknown;
+      archive?: boolean;
+      idempotencyKey: string | null;
+      ip?: string | null;
+      userAgent?: string | null;
+    },
+  ): Promise<unknown>;
+  metadata(ctx: AccessContext): unknown;
+}
+
+/** P0.7 (§5.1): installed plugins and their lifecycle; @kedge/db's D1PluginStore. */
+export interface PluginAdmin {
+  list(): Promise<unknown[]>;
+  set(plugin: string, to: "active" | "disabled"): Promise<unknown>;
+}
+
+export interface AppDeps {
+  secrets: Secrets;
+  /** P0.8 (§7): the store's ejected units, by id. */
+  overrides?: Overrides;
+  /** P0.5: who is asking (§3.3) and the credential ceremonies (§2). */
+  auth: AuthDeps;
+  /** P0.5: staff, roles, keys, storefronts, the audit log and authorized order reads; their routes exist only when given. */
+  admin?: AdminStore;
+  orderQuery?: OrderQuery;
+  keyring?: KeyringAdmin;
+  /** P0.4: capacity administration and store availability; their routes exist only when given. */
+  capacity?: CapacityAdmin;
+  availability?: AvailabilityReader;
+  /** P0.6a: deliveries and effects; their routes exist only when given. */
+  deliveries?: DeliveryAdmin;
+  /** P0.6b: the webhook delivery log and the business calendar; their routes exist only when given. */
+  webhooks?: WebhookLog;
+  calendar?: CalendarAdmin;
+  previewCaptures?: PreviewCaptures;
+  /** P0.7: the plugin lifecycle; its routes exist only when given. */
+  plugins?: PluginAdmin;
+  /** P0.7: tracks; their routes exist only when given. */
+  tracks?: TrackAdmin;
+  /** P0.9 (§5.1): plugin tracks on core resources, for the admin's metadata. */
+  adminMeta?: { tracksOn: (ctx: import("@kedge/core").AccessContext, on: "order" | "order_line") => unknown[] };
+  /** P0.7: plugin entities, with every declared entity's definition for its routes and schemas. */
+  entities?: {
+    store: EntityAdmin;
+    declared: readonly { plugin: string; entity: string; def: import("@kedge/core").EntityDefinition }[];
+  };
+  carts: CartGateway;
+  products: ProductReader;
+  settings: SettingsStore;
+  lineFeatures?: LineFeatures;
+  /** The merchant's custom fields, to project orders for each reader (§4.2). */
+  fields?: CustomFields;
+  /** `order_line` identity fields: setting one creates a new line identity, refused while frozen. */
+  identityKeys?: readonly string[];
+  orders: OrderStore;
+  ids: IdGenerator;
+  clock: Clock;
+}