first commit

docs/api-stack/api/api-2pc/src/options/options.md

@@ -0,0 +1,96 @@
+# `options/`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Defines the boundary-validated option shape consumed by
+`createTwoPcCoordinator`. Every tunable that affects coordinator
+behaviour (host instance id, outstanding-prepared cap, default phase-1
+timeout) lives here, with Zod validation at the seam and explicit
+defaults pinned to the design doc §9.2 numbers.
+
+Centralising option resolution in one module keeps the coordinator
+free of conditional fallback logic — by the time it sees the resolved
+shape every field is concrete, so subsequent code never has to
+re-check `undefined`.
+
+## Features
+
+- `DEFAULT_TIMEOUT_MS = 5000` — phase-1 deadline default per design
+  doc §9.2.
+- `TIMEOUT_CEILING_MS = 30000` — hard ceiling enforced at call time
+  (the coordinator's `limits/timeout-ceiling` module imports this).
+- `DEFAULT_OUTSTANDING_PREPARED_CAP = 256` — admission-control default
+  per design doc §14.
+- `twoPcCoordinatorOptionsSchema` — Zod schema, `strict()` so typos
+  surface as Zod errors instead of being silently ignored.
+- `resolveTwoPcCoordinatorOptions(raw)` — validates and fills in
+  defaults; returns the fully-populated `ResolvedTwoPcCoordinatorOptions`
+  shape the coordinator consumes.
+
+## Usage: Basic
+
+```ts
+import {
+    DEFAULT_TIMEOUT_MS,
+    resolveTwoPcCoordinatorOptions,
+} from "@suaveplan/api-2pc/options";
+
+const resolved = resolveTwoPcCoordinatorOptions({
+    hostInstanceId: "host-01",
+});
+
+console.log(resolved.defaultTimeoutMs === DEFAULT_TIMEOUT_MS); // true
+```
+
+## Usage: Advanced
+
+Override every default — useful for canary hosts where operators want
+a tighter admission cap and a longer prepare window:
+
+```ts
+import { resolveTwoPcCoordinatorOptions } from "@suaveplan/api-2pc/options";
+
+const resolved = resolveTwoPcCoordinatorOptions({
+    hostInstanceId: "canary-eu-west-1",
+    outstandingPreparedCap: 64,
+    defaultTimeoutMs: 15_000,
+});
+```
+
+Calls supplying `defaultTimeoutMs` above `TIMEOUT_CEILING_MS` raise a
+Zod error at this boundary — the coordinator's runtime ceiling check
+in `limits/timeout-ceiling.ts` then surfaces the misuse on per-call
+overrides as well.
+
+## API Reference
+
+- `const DEFAULT_TIMEOUT_MS: number` — 5000.
+- `const TIMEOUT_CEILING_MS: number` — 30000.
+- `const DEFAULT_OUTSTANDING_PREPARED_CAP: number` — 256.
+- `interface TwoPcCoordinatorOptions` — caller-supplied input shape.
+- `interface ResolvedTwoPcCoordinatorOptions` — internal shape after
+  defaults.
+- `const twoPcCoordinatorOptionsSchema: z.ZodType` — strict-shape
+  Zod schema.
+- `function resolveTwoPcCoordinatorOptions(raw): ResolvedTwoPcCoordinatorOptions`
+  — validates and resolves defaults.
+
+## Implementation Notes
+
+The schema uses `.strict()` so unknown keys fail validation rather than
+silently being dropped. The default for `defaultTimeoutMs` is applied
+post-parse with `?? DEFAULT_TIMEOUT_MS` rather than via
+`z.default(...)` so the schema continues to reject above-ceiling
+values regardless of whether the caller supplied the field — Zod's
+`default` would short-circuit `.max()` checks when the field is
+omitted, which is the wrong shape for a ceiling-enforced option.
+
+The module deliberately does NOT re-throw Zod failures as
+`TwoPcError` — that's the responsibility of the coordinator's
+public entry points. Keeping this module pure of cross-package error
+mapping makes it reusable from tests that want a raw Zod surface for
+property-based shape testing.