@polygonlabs/staker-pool-allocations-schemas 0.1.0

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@polygonlabs/staker-pool-allocations-schemas",
+  "version": "0.1.0",
+  "description": "Zod request/response schemas and OpenAPI registry for the PIP-85 staker pool API + management surfaces.",
+  "type": "module",
+  "files": [
+    "src",
+    "dist",
+    "openapi.json",
+    "MIGRATION.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./codegen": {
+      "types": "./dist/codegen.d.ts",
+      "import": "./dist/codegen.js"
+    },
+    "./openapi.json": "./openapi.json"
+  },
+  "dependencies": {
+    "@asteasolutions/zod-to-openapi": "^8.0.0",
+    "@polygonlabs/openapi-registry": "^2.1.1",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@tsconfig/node-ts": "^23.0.0",
+    "@tsconfig/node24": "^24.0.0",
+    "@types/node": "^24.0.0",
+    "typescript": "^5.5.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/0xPolygon/staker-pool-allocations.git",
+    "directory": "packages/schemas"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "pnpm run typecheck && tsc -b tsconfig.lib.json && node --conditions=@polygonlabs/source scripts/generate-spec.ts",
+    "build:clean": "pnpm run typecheck && rm -rf dist out-tsc *.tsbuildinfo && tsc -b tsconfig.lib.json && node --conditions=@polygonlabs/source scripts/generate-spec.ts",
+    "typecheck": "tsc -b",
+    "clean": "rm -rf dist out-tsc node_modules *.tsbuildinfo",
+    "codegen-drift-check": "pnpm run build && git diff --exit-code -- openapi.json"
+  }
+}

package/src/allocation-history.ts

@@ -0,0 +1,35 @@
+import { AddressSchema, DistributionIdSchema, Hex32Schema, WeiSchema } from './common.ts';
+import { z } from './zod.ts';
+
+// One row in the per-address cross-distribution allocation history.
+// Distinct from `AllocationRowSchema` because the history view carries
+// distribution-scoped fields (id, merkleRoot, completedAt) and the
+// claim status derived live from the `pos-staker-pool-claims`
+// subgraph (spec §3.6, D10).
+export const AllocationHistoryRowSchema = z
+  .object({
+    distributionId: DistributionIdSchema,
+    address: AddressSchema,
+    amount: WeiSchema,
+    // null for excluded addresses: stored allocation, excluded from the
+    // merkle tree (settled off-chain), not claimable on-chain.
+    leafIndex: z.number().int().nonnegative().nullable(),
+    merkleRoot: Hex32Schema,
+    completedAt: z.iso.datetime(),
+    status: z.enum(['claimed', 'unclaimed']).openapi({
+      description:
+        "Derived live at request time by diffing the address's allocations against the " +
+        'pos-staker-pool-claims subgraph. Never persisted (spec D10).'
+    })
+  })
+  .openapi('AllocationHistoryRow');
+
+export type AllocationHistoryRow = z.infer<typeof AllocationHistoryRowSchema>;
+
+export const AllocationHistoryResponseSchema = z
+  .object({
+    items: z.array(AllocationHistoryRowSchema)
+  })
+  .openapi('AllocationHistoryResponse');
+
+export type AllocationHistoryResponse = z.infer<typeof AllocationHistoryResponseSchema>;

package/src/allocation.ts

@@ -0,0 +1,51 @@
+import { AddressSchema, WeiSchema } from './common.ts';
+import { z } from './zod.ts';
+
+export const AllocationRowSchema = z
+  .object({
+    address: AddressSchema,
+    amount: WeiSchema,
+    // null for excluded addresses: they have a stored allocation but are
+    // excluded from the merkle tree (settled off-chain) and cannot claim.
+    leafIndex: z.number().int().nonnegative().nullable()
+  })
+  .openapi('AllocationRow');
+
+export type AllocationRow = z.infer<typeof AllocationRowSchema>;
+
+export const AllocationListResponseSchema = z
+  .object({
+    items: z.array(AllocationRowSchema),
+    nextCursor: z.string().nullable()
+  })
+  .openapi('AllocationListResponse');
+
+export type AllocationListResponse = z.infer<typeof AllocationListResponseSchema>;
+
+// A single off-chain (excluded-from-merkle) allocation. These addresses
+// (excluded addresses) receive a stored allocation but no merkle leaf — they
+// cannot claim on-chain and are settled manually. No `leafIndex` (always
+// null), so it's omitted from this shape entirely.
+export const ExcludedAllocationRowSchema = z
+  .object({
+    address: AddressSchema,
+    amount: WeiSchema
+  })
+  .openapi('ExcludedAllocationRow');
+
+export type ExcludedAllocationRow = z.infer<typeof ExcludedAllocationRowSchema>;
+
+// The full set of off-chain allocations for a distribution — the manual
+// settlement list. Not paginated: the excluded set is the configured list (e.g. LST contracts)
+// contracts (a small, bounded set), returned in one response. `totalAmount`
+// is the sum to settle off-chain and equals the distribution's
+// `total_allocated - claimable_total`.
+export const ExcludedAllocationsResponseSchema = z
+  .object({
+    items: z.array(ExcludedAllocationRowSchema),
+    total: z.number().int().nonnegative(),
+    totalAmount: WeiSchema
+  })
+  .openapi('ExcludedAllocationsResponse');
+
+export type ExcludedAllocationsResponse = z.infer<typeof ExcludedAllocationsResponseSchema>;

package/src/codegen.ts

@@ -0,0 +1,50 @@
+// Codegen-facing surface: registered name === exported binding name.
+//
+// The @polygonlabs/zod-to-openapi-heyapi plugin emits
+// `import { <RegisteredName> } from '<schemasFrom>'` for every schema a
+// public-registry route response `$ref`s, and its codegen-time audit fails
+// the client build when a registered name has no matching named export of
+// the `schemasFrom` module. The generated client's response transformer
+// then calls `<RegisteredName>.parseAsync(data)` at runtime against these
+// exact values.
+//
+// This lives on its own `./codegen` subpath (the plugin README's
+// "schemas exposed under a subpath export" case) rather than the main
+// barrel: the barrel star-exports `z.infer` *types* under these same
+// names (`AllocationRow`, `DistributionSummary`, …), and TypeScript
+// rejects a re-exported value alias alongside a re-exported type of the
+// same name (TS2300). A dedicated module sidesteps the collision without
+// renaming anything the worker and rest-api already import.
+//
+// Response slots in the public registry reference the wire variants (see
+// `routes-public/wire.ts` for why `z.encode` can't take the canonical
+// address-bearing schemas), so those names bind the wire values — the
+// client validates exactly the shape the service emits. Schemas that are
+// already encode-safe bind their canonical definition.
+export {
+  AllocationHistoryResponseWireSchema as AllocationHistoryResponse,
+  AllocationHistoryRowWireSchema as AllocationHistoryRow,
+  AllocationListResponseWireSchema as AllocationListResponse,
+  AllocationRowWireSchema as AllocationRow,
+  ExcludedAllocationRowWireSchema as ExcludedAllocationRow,
+  ExcludedAllocationsResponseWireSchema as ExcludedAllocationsResponse,
+  ProofResponseWireSchema as ProofResponse
+} from './routes-public/wire.ts';
+export { OperationalStatusSchema as OperationalStatus } from './routes-public/operational.ts';
+export {
+  DistributionDetailSchema as DistributionDetail,
+  DistributionListResponseSchema as DistributionListResponse,
+  DistributionSummarySchema as DistributionSummary
+} from './distribution.ts';
+export {
+  UnclaimedProofBatchSchema as UnclaimedProofBatch,
+  UnclaimedProofsResponseSchema as UnclaimedProofsResponse
+} from './unclaimed-proofs.ts';
+
+// Canonical error response schemas, renamed to drop the `Schema` suffix so
+// the binding matches the OpenAPI registered name — the TypedRegistry
+// auto-injects these into every route's 400/500 response slots.
+export {
+  ErrorResponseSchema as ErrorResponse,
+  ValidationErrorResponseSchema as ValidationErrorResponse
+} from '@polygonlabs/openapi-registry/error-schemas';

package/src/common.ts

@@ -0,0 +1,76 @@
+import { z } from './zod.ts';
+
+// Network discriminator surfaced as a path parameter (`/v1/:network/...`)
+// and persisted on every domain row. The set is closed — adding a third
+// network is a schema + migration change, not a config flip.
+export const NetworkSchema = z.enum(['mainnet', 'amoy']).openapi({
+  description:
+    'Polygon network the distribution covers. `mainnet` is PoS mainnet, `amoy` is the PoS testnet.',
+  example: 'mainnet'
+});
+
+export type Network = z.infer<typeof NetworkSchema>;
+
+// Lowercased 0x-prefixed 40-hex EVM address. Transform normalises so
+// downstream code never has to think about case.
+export const AddressSchema = z
+  .string()
+  .regex(/^0x[0-9a-fA-F]{40}$/)
+  .transform((s) => s.toLowerCase())
+  .openapi({ example: '0xabc0000000000000000000000000000000000001' });
+
+// Distributions are named by the month they cover, e.g. "2026-04". The
+// spec deliberately picks a human-readable scheme rather than UUIDs so
+// the URL path is meaningful to operators.
+export const DistributionIdSchema = z
+  .string()
+  .regex(/^[0-9]{4}-[0-9]{2}$/)
+  .openapi({ example: '2026-04' });
+
+// All POL amounts cross the API boundary as decimal strings — uint256
+// can't fit in a JS number, and JSON has no native bigint. Callers cast
+// to BigInt at the seam.
+export const WeiSchema = z
+  .string()
+  .regex(/^[0-9]+$/)
+  .openapi({ example: '1234567890000000000' });
+
+// 32-byte hex with the 0x prefix — used for merkle roots, inputs
+// hashes, and subgraph block hashes.
+export const Hex32Schema = z
+  .string()
+  .regex(/^0x[0-9a-fA-F]{64}$/)
+  .openapi({ example: '0x' + 'a'.repeat(64) });
+
+// POL/USD price as a decimal string with up to 6 fractional digits (the
+// micro-USD precision the worker and storage use). String, not number, so
+// it round-trips through the API and the inputs hash without float drift —
+// `0.42` always means `0.420000`. Used both for the trigger override and the
+// stored price on the distribution detail.
+export const PolUsdPriceSchema = z
+  .string()
+  .regex(/^[0-9]+(\.[0-9]{1,6})?$/)
+  .openapi({ example: '0.423100' });
+
+// Cursor-based pagination. The cursor is an opaque base64-encoded
+// JSON object — decoded server-side only. The shape inside differs
+// per endpoint (e.g. `{ id }` for distributions, `{ leafIndex }` for
+// allocations); the encoder/decoder lives next to each route.
+export const PaginationQuerySchema = z.object({
+  cursor: z.string().min(1).optional(),
+  limit: z.coerce.number().int().min(1).max(100).default(50)
+});
+
+export type PaginationQuery = z.infer<typeof PaginationQuerySchema>;
+
+// Opaque cursor encode/decode pair. Forces every endpoint to round-trip
+// the same way so the cursor format is consistent across the API.
+export function encodeCursor<T>(payload: T): string {
+  return Buffer.from(JSON.stringify(payload), 'utf8').toString('base64url');
+}
+
+export function decodeCursor<T>(cursor: string): T {
+  // Throws SyntaxError on malformed JSON / base64; route handlers wrap
+  // this in a typed 400 via the error envelope.
+  return JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8')) as T;
+}

package/src/distribution.ts

@@ -0,0 +1,52 @@
+import { DistributionIdSchema, Hex32Schema, PolUsdPriceSchema, WeiSchema } from './common.ts';
+import { z } from './zod.ts';
+
+const DistributionStatusSchema = z
+  .enum(['pending', 'running', 'completed', 'failed'])
+  .openapi({ example: 'completed' });
+
+// List-view shape. Drops the full subgraph-pin block hashes (visible in
+// the detail endpoint only) and the error blob.
+export const DistributionSummarySchema = z
+  .object({
+    distributionId: DistributionIdSchema,
+    status: DistributionStatusSchema,
+    startPoSBlock: WeiSchema,
+    endPoSBlock: WeiSchema,
+    merkleRoot: Hex32Schema.nullable(),
+    totalAllocated: WeiSchema.nullable(),
+    completedAt: z.iso.datetime().nullable()
+  })
+  .openapi('DistributionSummary');
+
+export type DistributionSummary = z.infer<typeof DistributionSummarySchema>;
+
+// Detail view extends the summary with subgraph pins + checkpoint
+// count + the inputs hash. Used by `GET /v1/distributions/:id` and
+// (with the `error` field) by the management variant.
+export const DistributionDetailSchema = DistributionSummarySchema.extend({
+  checkpointCount: z.number().int().nonnegative(),
+  // POL/USD price applied this run and the USD claim ceiling (decimal
+  // strings, up to 6 dp). `maxClaimableUsdThreshold` is null when the
+  // threshold was inert for the run. Both null until completion.
+  polUsdPrice: PolUsdPriceSchema.nullable(),
+  maxClaimableUsdThreshold: PolUsdPriceSchema.nullable(),
+  inputsHash: Hex32Schema.nullable(),
+  posStakingSubgraphBlock: WeiSchema.nullable(),
+  posStakingSubgraphHash: Hex32Schema.nullable(),
+  posCheckpointsSubgraphBlock: WeiSchema.nullable(),
+  posCheckpointsSubgraphHash: Hex32Schema.nullable(),
+  posPriorityFeesSubgraphBlock: WeiSchema.nullable(),
+  posPriorityFeesSubgraphHash: Hex32Schema.nullable()
+}).openapi('DistributionDetail');
+
+export type DistributionDetail = z.infer<typeof DistributionDetailSchema>;
+
+export const DistributionListResponseSchema = z
+  .object({
+    items: z.array(DistributionSummarySchema),
+    nextCursor: z.string().nullable()
+  })
+  .openapi('DistributionListResponse');
+
+export type DistributionListResponse = z.infer<typeof DistributionListResponseSchema>;

package/src/error.ts

@@ -0,0 +1,17 @@
+import { z } from './zod.ts';
+
+// Canonical error envelope every 4xx and 5xx response uses. Per spec
+// §7.1: 4xx responses populate `details` from VError.info; 5xx wipe
+// both `details` and the stack to avoid leaking internal state to
+// untrusted callers.
+export const ErrorEnvelopeSchema = z
+  .object({
+    error: z.object({
+      code: z.string().openapi({ example: 'DISTRIBUTION_NOT_FOUND' }),
+      message: z.string().openapi({ example: 'Distribution not found.' }),
+      details: z.record(z.string(), z.unknown()).optional()
+    })
+  })
+  .openapi('ErrorEnvelope');
+
+export type ErrorEnvelope = z.infer<typeof ErrorEnvelopeSchema>;

package/src/index.ts

@@ -0,0 +1,16 @@
+// Package barrel: the extended Zod instance (with the OpenAPI registry) plus
+// every request/response schema. Consumers (the api + worker apps) import the
+// schemas they need from here; internal files still reference `./common.ts`
+// and `./zod.ts` by relative path.
+export * from './zod.ts';
+export * from './common.ts';
+export * from './error.ts';
+export * from './distribution.ts';
+export * from './allocation.ts';
+export * from './allocation-history.ts';
+export * from './unclaimed-proofs.ts';
+export * from './proof.ts';
+export * from './management.ts';
+export * from './registry-public.ts';
+export * from './registry-management.ts';
+export * from './routes-management/operational.ts';

package/src/management.ts

@@ -0,0 +1,158 @@
+import {
+  AddressSchema,
+  DistributionIdSchema,
+  NetworkSchema,
+  PolUsdPriceSchema,
+  WeiSchema
+} from './common.ts';
+import { z } from './zod.ts';
+
+// Body shape for `POST /v1/:network/management/distributions`.
+// `distributionId` is optional — when omitted, the handler derives the
+// monthly id (`YYYY-MM`) from the current date in UTC. Providing it
+// makes the call idempotent: re-POSTing with an existing id returns
+// 202 with the existing status rather than enqueueing a duplicate.
+//
+// `force` is the escape hatch for re-running a completed distribution
+// — operator confirms the inputs really changed, the prior completed
+// row + its allocations get hard-deleted, and the worker reruns. The
+// audit trail relies on the surrounding ops log + the persisted
+// `inputsHash`; no soft-delete or version history here in Phase 1.
+export const DistributionTriggerRequestSchema = z
+  .object({
+    startPoSBlock: WeiSchema.openapi({
+      description: 'Inclusive lower bound of the PoS block range to allocate over.'
+    }),
+    endPoSBlock: WeiSchema.openapi({
+      description: 'Exclusive upper bound of the PoS block range to allocate over.'
+    }),
+    distributionId: DistributionIdSchema.optional().openapi({
+      description:
+        'Optional. When omitted, derived as the current `YYYY-MM` (UTC). ' +
+        'Providing it makes the call idempotent — repeat POSTs with the ' +
+        'same id return the existing status.'
+    }),
+    force: z
+      .boolean()
+      .optional()
+      .openapi({
+        description:
+          'Re-run a previously completed distribution covering the same range. ' +
+          'Hard-deletes the prior completed row + allocations before the worker ' +
+          'starts. Use only after operator-confirmed input drift.'
+      }),
+    polUsdPrice: PolUsdPriceSchema.optional().openapi({
+      description:
+        'Optional POL/USD price override (decimal string, up to 6 dp). When ' +
+        'omitted, the worker fetches the spot price from CoinGecko at run ' +
+        "start. Pass a prior run's stored `polUsdPrice` to reproduce its " +
+        'merkle root and leaves on a `force` re-run — the price feeds the ' +
+        'USD-threshold exclusion that decides which allocations stay on-chain.'
+    })
+  })
+  .openapi('DistributionTriggerRequest');
+
+export type DistributionTriggerRequest = z.infer<typeof DistributionTriggerRequestSchema>;
+
+// 202 response — the worker runs out-of-band on the same pod after
+// the handler returns. Operators poll the public distributions
+// endpoint (or the management `:id` view, Phase 1 follow-up) to
+// observe the terminal status.
+export const DistributionTriggerResponseSchema = z
+  .object({
+    network: NetworkSchema,
+    distributionId: DistributionIdSchema,
+    status: z.enum(['pending', 'running', 'completed', 'failed']).openapi({
+      description:
+        'Status snapshot at the moment the trigger returned. A freshly ' +
+        'enqueued run starts at `pending`; an idempotent hit on an ' +
+        'existing id returns whatever the current row says.'
+    })
+  })
+  .openapi('DistributionTriggerResponse');
+
+export type DistributionTriggerResponse = z.infer<typeof DistributionTriggerResponseSchema>;
+
+// 200 response for `DELETE /v1/:network/management/distributions/:id`.
+// `priorStatus` is the state the row was in before removal — never
+// `completed`, which the handler refuses (those are published roots).
+export const DistributionDeleteResponseSchema = z
+  .object({
+    network: NetworkSchema,
+    distributionId: DistributionIdSchema,
+    removed: z.boolean(),
+    priorStatus: z.enum(['pending', 'running', 'failed']),
+    deletedAllocations: z
+      .number()
+      .int()
+      .nonnegative()
+      .openapi({
+        description:
+          'Number of allocation rows removed alongside the distribution. Normally 0 — ' +
+          'allocations are only persisted at completion, and completed rows cannot be deleted.'
+      })
+  })
+  .openapi('DistributionDeleteResponse');
+
+export type DistributionDeleteResponse = z.infer<typeof DistributionDeleteResponseSchema>;
+
+// Body for `POST /v1/:network/management/excluded-addresses`. Adds (or
+// re-labels, on conflict) an address that receives an allocation but is
+// excluded from the merkle tree and settled off-chain (LST contracts and
+// other manually-handled addresses).
+export const AddExcludedAddressRequestSchema = z
+  .object({
+    address: AddressSchema.openapi({
+      description: 'Address to exclude from the merkle tree (settled off-chain).'
+    }),
+    label: z.string().min(1).max(256).openapi({
+      description: 'Human-readable note for the entry, e.g. the LST protocol name.'
+    }),
+    createdBy: z
+      .string()
+      .min(1)
+      .max(128)
+      .optional()
+      .openapi({
+        description:
+          'Actor id recorded on the row (who added it). Defaults to "management-api" ' +
+          'when omitted — the x-api-key gate carries no operator identity.'
+      })
+  })
+  .openapi('AddExcludedAddressRequest');
+
+export type AddExcludedAddressRequest = z.infer<typeof AddExcludedAddressRequestSchema>;
+
+// A single excluded-address row as returned by the management API.
+export const ManagedExcludedAddressSchema = z
+  .object({
+    network: NetworkSchema,
+    address: AddressSchema,
+    label: z.string(),
+    createdBy: z.string(),
+    createdAt: z.iso.datetime(),
+    updatedAt: z.iso.datetime()
+  })
+  .openapi('ManagedExcludedAddress');
+
+export type ManagedExcludedAddress = z.infer<typeof ManagedExcludedAddressSchema>;
+
+export const ExcludedAddressListResponseSchema = z
+  .object({
+    items: z.array(ManagedExcludedAddressSchema)
+  })
+  .openapi('ExcludedAddressListResponse');
+
+export type ExcludedAddressListResponse = z.infer<typeof ExcludedAddressListResponseSchema>;
+
+// `DELETE` is idempotent: `removed` is false when the address wasn't in
+// the list (no 404), so re-running a delete is safe.
+export const RemoveExcludedAddressResponseSchema = z
+  .object({
+    network: NetworkSchema,
+    address: AddressSchema,
+    removed: z.boolean()
+  })
+  .openapi('RemoveExcludedAddressResponse');
+
+export type RemoveExcludedAddressResponse = z.infer<typeof RemoveExcludedAddressResponseSchema>;

package/src/proof.ts

@@ -0,0 +1,27 @@
+import { AddressSchema, Hex32Schema, WeiSchema } from './common.ts';
+import { z } from './zod.ts';
+
+// Response for `GET /v1/:network/distributions/:id/allocations/:addr/proof`.
+// `proof` is the array of 32-byte hex sibling hashes the on-chain
+// `MultiRootDistributor` needs to reconstruct the merkle root from the leaf
+// `keccak256(abi.encodePacked(leafIndex, address, amount))`. Generated on
+// demand from the persisted allocations table — no proof is stored at
+// distribution time (spec D9). Pass `leafIndex`, `address`, `amount`, and
+// `proof` straight to `claim(root, index, account, amount, proof)`.
+export const ProofResponseSchema = z
+  .object({
+    merkleRoot: Hex32Schema.openapi({
+      description: 'Distribution merkle root — same value as `DistributionDetail.merkleRoot`.'
+    }),
+    address: AddressSchema,
+    amount: WeiSchema,
+    leafIndex: z.number().int().nonnegative().openapi({
+      description: 'Index of this leaf in the canonical (lowercased-address-sorted) tree.'
+    }),
+    proof: z.array(Hex32Schema).openapi({
+      description: 'Sibling-hash array. Pass straight to the claimer contract.'
+    })
+  })
+  .openapi('ProofResponse');
+
+export type ProofResponse = z.infer<typeof ProofResponseSchema>;

package/src/registry-management.ts

@@ -0,0 +1,36 @@
+import { TypedRegistry } from '@polygonlabs/openapi-registry';
+
+import { addManagementDistributionRoutes } from './routes-management/distributions.ts';
+import { addExcludedAddressRoutes } from './routes-management/excluded-addresses.ts';
+import { addOperationalRoutes } from './routes-management/operational.ts';
+
+// Registry composition for the WORKER service's management surface (the
+// public read API has its own registry). `TypedRegistry` accumulates the
+// registered operations and security schemes into its *type* via chained
+// method returns — the chain's final value is what `buildManagementRegistry`
+// returns, and the worker derives the registry-driven router, the typed
+// handler binding (`HandlerMapFor<typeof buildManagementRegistry, ...>`),
+// and the served OpenAPI document from that one inferred type.
+//
+// One chained expression on purpose: discarding any link's return drops the
+// type-level narrow even though the runtime registration still happens (see
+// @polygonlabs/openapi-registry's "The one rule"). To add a route, append a
+// `.registerPath({...})` inside the relevant helper under
+// `./routes-management/`, or add a new domain helper and `.with(...)` here.
+export const buildManagementRegistry = () =>
+  new TypedRegistry()
+    // Operations opt in via `security: [{ ApiKeyAuth: [] }]`; the
+    // registry-driven router then requires an `ApiKeyAuth` handler at
+    // compile time and runs it before request validation. The operational
+    // probes declare no security and stay unauthenticated.
+    .registerSecurityScheme('ApiKeyAuth', {
+      type: 'apiKey',
+      in: 'header',
+      name: 'x-api-key',
+      description:
+        'Management API key (`MANAGEMENT_API_KEY`, Secret-Manager-backed). ' +
+        'Required on every management operation.'
+    })
+    .with(addOperationalRoutes)
+    .with(addManagementDistributionRoutes)
+    .with(addExcludedAddressRoutes);

package/src/registry-public.ts

@@ -0,0 +1,33 @@
+// Registry composition for the public REST API (`packages/rest-api`).
+//
+// `TypedRegistry` accumulates registered operations into its type via
+// chained method returns — `registerPath` and `with(fn)` each return a
+// `TypedRegistry` narrowed with what was just registered. The chain's
+// final value is what `buildPublicRegistry` returns; the rest-api service
+// derives its typed handler map from it via
+// `HandlerMapFor<typeof buildPublicRegistry>` and the OpenAPI document is
+// generated from the same registry's `definitions`, so the served spec
+// and the mounted routes cannot drift.
+//
+// To add a route: append a `.registerPath({...})` call inside the relevant
+// per-domain helper under `./routes-public/`, or add a new domain helper
+// and `.with(addNewDomainRoutes)` here. Always chain or capture every
+// registration — see `@polygonlabs/openapi-registry`'s "The one rule".
+//
+// The worker's management surface composes its own registry; this one
+// carries only the read-only public endpoints.
+import { TypedRegistry } from '@polygonlabs/openapi-registry';
+
+import { addAddressRoutes } from './routes-public/addresses.ts';
+import { addAllocationRoutes } from './routes-public/allocations.ts';
+import { addDistributionRoutes } from './routes-public/distributions.ts';
+import { addOperationalRoutes } from './routes-public/operational.ts';
+import { addProofRoutes } from './routes-public/proofs.ts';
+
+export const buildPublicRegistry = () =>
+  new TypedRegistry()
+    .with(addOperationalRoutes)
+    .with(addDistributionRoutes)
+    .with(addAllocationRoutes)
+    .with(addAddressRoutes)
+    .with(addProofRoutes);