# `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.