@orkestrel/scaffold 0.0.91 → 0.0.93

package/dist/host/guides/mcp.md

@@ -5374,11 +5374,11 @@ the exact statement:
 1. **doc ↔ source bijection.** Every `function` / `class` / `const` /
    `interface` / `type` row in the `## Surface` tables (the core dispatch
    tables and the `### HTTP transport` + `### WebSocket transport` + `### stdio
-transport` tables) is a real export of the mcp layer (`src/core` or
+   transport` tables) is a real export of the mcp layer (`src/core` or
    `src/server`), and every export of either appears as a Surface row —
    exhaustive, both directions.
 2. **JSON-RPC 2.0 envelope.** A `dispatch` response is always `{ jsonrpc:
-'2.0', … }` with exactly one of `result` / `error`. The success arm always
+   '2.0', … }` with exactly one of `result` / `error`. The success arm always
    carries an `id`, echoing the request's, because a result answers a request and
    a request always has one. The error arm is the only arm whose `id` may be
    missing, and it is then omitted — the member is absent from the envelope, never
@@ -5410,7 +5410,7 @@ transport` tables) is a real export of the mcp layer (`src/core` or
    metadata, run through the same dispatcher, and are projected back unstamped — so
    they inherit the modern engine's execution port, cancellation, bounds, and
    validation rather than running beside them. `initialize` → `{ protocolVersion,
-capabilities: { tools: {} }, serverInfo: { name, version } }`, the version negotiated over the
+   capabilities: { tools: {} }, serverInfo: { name, version } }`, the version negotiated over the
    legacy subset only: the client's `params.protocolVersion` is echoed when it is a
    supported legacy revision, and every other request — the modern `'2026-07-28'`,
    an unsupported revision, a non-string, or an absent one — falls back to the
@@ -5435,7 +5435,7 @@ capabilities: { tools: {} }, serverInfo: { name, version } }`, the version negot
    into a `success: false` result, the server adds no try/catch: that branch's
    `error` maps to `{ content: [{ type: 'text', text: <error> }], isError: true }`;
    a valued `success: true` branch maps to `{ content: [{ type: 'text', text:
-JSON.stringify(value) }], structuredContent: value }`, carrying the value unchanged
+   JSON.stringify(value) }], structuredContent: value }`, carrying the value unchanged
    alongside the backwards-compatible text. A value-less success retains the required
    empty text block and omits `structuredContent`.
 6. **One modern seam, subscriptions included, and `-32601` for anything off it.**
@@ -5469,7 +5469,7 @@ JSON.stringify(value) }], structuredContent: value }`, carrying the value unchan
    carries the same stamp. Ending the consumer's producer closes gracefully when the
    honoured filter omits `toolsListChanged`, with
    `{ resultType: 'complete', _meta: { 'io.modelcontextprotocol/subscriptionId': id,
-… } }`. A stream honouring the tools family stays open until failure or signal abort.
+   … } }`. A stream honouring the tools family stays open until failure or signal abort.
    The request id is only stream identity: a later request does not supersede
    an earlier one. The legacy method remains absent and answers `-32601`.
 7. **`handle` maps the boundary failures.** A `JSON.parse` throw (malformed
@@ -5520,7 +5520,7 @@ JSON.stringify(value) }], structuredContent: value }`, carrying the value unchan
     continuation, or principal — carrying the caught value the wire never sees; the
     emitter isolates a listener throw, routing it
     to its own `error` handler (the `error` option, surfaced as `(error,
-event)`, not a domain event) — so a buggy observer can never corrupt a
+    event)`, not a domain event) — so a buggy observer can never corrupt a
     dispatch, and a throwing `error` handler neither escapes nor recurses.
 11. **doc ↔ source method bijection.** The `## Methods` tables list exactly
     the public methods of each behavioral interface — `MCPServerInterface`,
@@ -5565,7 +5565,7 @@ event)`, not a domain event) — so a buggy observer can never corrupt a
     own JSON-parse `try`/`catch`) and draws a sharp line: a TRANSPORT-level
     failure — malformed JSON (`-32700`) or a parsed value that is not a
     JSON-RPC request (`-32600`, narrowed with `parseJSONRPCMessage` + `'method'
-in request`, no `as`) — is HTTP **400** with a JSON-RPC error body carrying no
+    in request`, no `as`) — is HTTP **400** with a JSON-RPC error body carrying no
     `id` member. A legacy dispatch result — success or in-band JSON-RPC error — is
     HTTP **200**. A modern result is **400** for `-32020` / `-32021` / `-32022`
     / `-32602`, **404** for `-32601`, and **200** otherwise; every notification
@@ -5620,7 +5620,7 @@ in request`, no `as`) — is HTTP **400** with a JSON-RPC error body carrying no
     consumer-provided list.
 13. **The client is the modern-only egress mirror (`src/core`).**
     `createMCPClient({ transport, identity?, capabilities?, version?, timeout?,
-on? })` drives a remote server over an injected `MCPMessageTransportInterface`
+    on? })` drives a remote server over an injected `MCPMessageTransportInterface`
     (transport-abstract, like the server). `connect()` issues a modern
     `server/discover` carrying `_meta` with the offered revision,
     client capabilities, and client identity. It intersects the peer's
@@ -5708,9 +5708,9 @@ on? })` drives a remote server over an injected `MCPMessageTransportInterface`
     `error` option, not a domain event). Consumers subscribe through `emitter.on`.
 15. **The HTTP client transport drives a remote server over `fetch`
     (`src/server`).** `createHTTPClientTransport({ url, headers?, fetch?,
-timeout? })` returns a `MCPMessageTransportInterface` whose `send` POSTs one
+    timeout? })` returns a `MCPMessageTransportInterface` whose `send` POSTs one
     JSON-serialized message to `url` with `content-type:
-application/json` and an `Accept` of both `application/json` and
+    application/json` and an `Accept` of both `application/json` and
     `text/event-stream` (plus any `headers`), then decodes the reply and
     emits each carried `JSONRPCMessage` on the `message` event: an
     `application/json` body is narrowed with `parseJSONRPCMessage`; a
@@ -5762,7 +5762,7 @@ application/json` and an `Accept` of both `application/json` and
     (`upgradeRequestPath`) is not `options.path` (default `DEFAULT_MCP_PATH`),
     the `Sec-WebSocket-Key` is absent, or the `Sec-WebSocket-Version` is not
     `13`. Otherwise it claims (returns `true`): `createNodeWebSocket({
-socket, key, head, protocol })` (server mode → writes the `101` handshake,
+    socket, key, head, protocol })` (server mode → writes the `101` handshake,
     selecting the configured subprotocol only when the client's offer contains it,
     and sends unmasked frames), wraps it in a `WebSocketServerTransport`, and
     pumps — each inbound `JSONRPCMessage` that `isJSONRPCRequest` runs
@@ -5831,7 +5831,7 @@ socket, key, head, protocol })` (server mode → writes the `101` handshake,
     (`src/server`).** `createMCPSession({ path?, ttl?, session?, clock?, origin?, keepalive? })`
     returns a `MiddlewareHandler<TState>` (`TState extends MCPSessionState`)
     that owns its own closure `Map<string, { session: MCPSession; touched:
-number; version: MCPVersion }>` — no dependency on `@orkestrel/middleware` and no shared
+    number; version: MCPVersion }>` — no dependency on `@orkestrel/middleware` and no shared
     session primitive; the store, mint, and validation are all native to
     this package. Compose it with `router.use(createMCPSession())` in front
     of a session-agnostic `createMCPRoutes(mcp)`; it owns its `path` (default
@@ -5875,7 +5875,7 @@ number; version: MCPVersion }>` — no dependency on `@orkestrel/middleware` and
     the log under a monotone base36 event id (returned), evicting the oldest
     past `capacity` + any entry older than the per-event TTL, and fans the
     message out to every `attach`ed open stream as `stream.write({ id, data:
-JSON.stringify(message) })`. `session.replay(afterId)` returns every
+    JSON.stringify(message) })`. `session.replay(afterId)` returns every
     retained log entry strictly after `afterId` in append order — an unknown
     / evicted cursor replays nothing. The `createMCPSession` middleware
     serves the resumable `GET {path}`: it validates the `mcp-session-id`
@@ -5999,7 +5999,7 @@ JSON.stringify(message) })`. `session.replay(afterId)` returns every
     contract over native host APIs (`src/browser`).**
     `createWebSocketClientTransport({ url, protocols? })` returns a
     `MCPMessageTransportInterface` whose `start()` opens `new WebSocket(url,
-protocols)` and awaits the native `'open'` event (the RFC 6455 handshake
+    protocols)` and awaits the native `'open'` event (the RFC 6455 handshake
     is the host's concern; a connection failure — the native `'error'` event
     while not yet `OPEN` — rejects `start()`); `send` writes each message as
     one text frame once `OPEN`, queuing (in order) any message sent before —
@@ -6051,7 +6051,7 @@ protocols)` and awaits the native `'open'` event (the RFC 6455 handshake
     (the implicit, portless channel — bound once, for the whole lifetime of
     the returned handle, so a dedicated worker's very first portless message
     needs no first-use setup), and registers one `scope.addEventListener(
-'message', …)` listener built by `createScopeMessageListener`. That one
+    'message', …)` listener built by `createScopeMessageListener`. That one
     listener handles every shape uniformly, per event, with no upfront
     detection flag: `event.ports.length > 0` spawns a fresh
     `createMessagePortTransport` + `bindServer` for that port (tracked for

package/dist/host/guides/pool.md

@@ -1,12 +1,13 @@
 # Pool
 
-> A typed resource pool with optional bounded capacity, unique ownership, FIFO settlement,
-> validated reuse, caller-owned cancellation, explicit cleanup failures, and a stable
-> event-driven teardown barrier.
+> A typed resource pool with optional bounded capacity, a warm floor, bounded loss recovery,
+> exclusive leases by default, FIFO settlement, validated idle reuse, caller-owned cancellation, and explicit cleanup.
 
-The pool has no warm floor, eviction timer, acquire timeout, or polling loop. Every wait parks
-on a promise or a signal listener and wakes when a settlement reaches it, and the lifecycle
-hooks are the caller's, so the engine itself performs no I/O.
+The pool supports lazy creation or a warm floor, with no eviction timer, acquire timeout,
+or polling loop. Waits park on promises or signal listeners. An acquire rejects with
+`cleanup` when a floor retains a record, owns `min` records, has nothing eligible, and has no
+refill or disposal pending, even with live leases. The lifecycle hooks are the caller's,
+so the engine itself performs no I/O.
 
 ## Surface
 
@@ -38,16 +39,16 @@ try {
 
 ### Factories
 
-| API          | Kind     | Summary                                                                                                                                  |
-| ------------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
-| `createPool` | function | Creates a distinct `PoolInterface` from resource lifecycle hooks, with optional bounded capacity, unique ownership, and FIFO settlement. |
+| API          | Kind     | Summary                                                                                                                                             |
+| ------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `createPool` | function | Creates a distinct `PoolInterface` from resource lifecycle hooks, with optional bounded capacity, exclusive leases by default, and FIFO settlement. |
 
 ### Classes
 
-| API         | Kind  | Summary                                                                                                                                                                                  |
-| ----------- | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `Pool`      | class | Represents a capacity-aware resource pool whose opaque ownership records preserve FIFO settlement, cancellation, exact lease release, and deterministic teardown under concurrent hooks. |
-| `PoolError` | class | Represents a stable, machine-readable pool failure that retains the original thrown value as its cause without unsafe coercion, alongside structured context.                            |
+| API         | Kind  | Summary                                                                                                                                                                                                                    |
+| ----------- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Pool`      | class | Represents a resource pool with optional bounded capacity and a warm floor, whose opaque ownership records preserve FIFO settlement, cancellation, exact lease release, and deterministic teardown under concurrent hooks. |
+| `PoolError` | class | Represents a stable, machine-readable pool failure that retains the original thrown value as its cause without unsafe coercion, alongside structured context.                                                              |
 
 ### Guards
 
@@ -56,27 +57,29 @@ In a guard table a `Shape` cell holds the type the guard narrows to.
 | API            | Kind     | Shape         | Summary                                                                                                          |
 | -------------- | -------- | ------------- | ---------------------------------------------------------------------------------------------------------------- |
 | `isPoolError`  | function | `PoolError`   | Tests whether an unknown value is a `PoolError`, returning `false` for hostile proxies.                          |
-| `isPoolMax`    | function | `number`      | Tests whether a value is a positive safe integer, the only valid explicit pool maximum.                          |
+| `isPoolLimit`  | function | `number`      | Tests whether a value is a positive safe integer for a pool record or lease limit.                               |
 | `isPoolSignal` | function | `AbortSignal` | Tests whether a value is a native `AbortSignal` for the acquire boundary, returning `false` for hostile proxies. |
 
 ### Types
 
 A `Shape` cell holds an interface's data members as bare names in braces, `?` marking an optional member and `plus` introducing its call-signature members, and a type alias's own type literal with a union's arms escaped as `\|`.
 
-| API                | Kind      | Shape                                                          | Summary                                                                                                                                                     |
-| ------------------ | --------- | -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `PoolCode`         | type      | `'invalid' \| 'destroyed' \| 'create' \| 'cleanup'`            | Names the machine-readable failure codes produced by `PoolError`.                                                                                           |
-| `PoolContext`      | interface | `{ value?, failures? }`                                        | Represents the structured context attached to a `PoolError`: the rejected input, or the distinct destroy-hook failures an aggregate cleanup collected.      |
-| `PoolErrorOptions` | interface | `{ code, cause?, context? }`                                   | Represents the construction options for `PoolError`: the stable code, an optional cause, and optional structured context.                                   |
-| `PoolEventMap`     | type      | `{ create, acquire, release, destroy }`                        | Represents the observable resource lifecycle events emitted by a `PoolInterface`.                                                                           |
-| `PoolToken`        | interface | `{ value } plus release`                                       | Represents a unique lease over one pool-owned resource record, exposing that record as a readonly `value` and returning it through an idempotent `release`. |
-| `PoolOptions`      | interface | `{ on?, error?, create, destroy?, validate?, max? }`           | Represents the resource lifecycle options for `Pool` and `createPool`: creation, destruction, validation, capacity, and observation.                        |
-| `PoolInterface`    | interface | `{ emitter, size, idle, active } plus acquire, clear, destroy` | Represents a FIFO resource pool with optional bounded capacity and deterministic teardown, exposing its record counts and a typed lifecycle emitter.        |
-
-`size` counts every owned record, including records being validated or destroyed. `idle`
-counts only immediately available records. `active` counts only leased records. An in-flight
-create reservation claims capacity but is not yet an owned record and therefore is not part
-of `size`.
+| API                | Kind      | Shape                                                                                    | Summary                                                                                                                                                                            |
+| ------------------ | --------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `PoolCode`         | type      | `'invalid' \| 'destroyed' \| 'create' \| 'cleanup'`                                      | Names the machine-readable failure codes produced by `PoolError`.                                                                                                                  |
+| `PoolContext`      | interface | `{ value?, failures? }`                                                                  | Represents the structured context attached to a `PoolError`: the rejected input, or the distinct destroy-hook failures an aggregate cleanup collected.                             |
+| `PoolErrorOptions` | interface | `{ code, cause?, context? }`                                                             | Represents the construction options for `PoolError`: the stable code, an optional cause, and optional structured context.                                                          |
+| `PoolEventMap`     | type      | `{ create, acquire, release, destroy }`                                                  | Represents the observable resource lifecycle events emitted by a `PoolInterface`.                                                                                                  |
+| `PoolToken`        | interface | `{ value } plus release, destroy`                                                        | Represents a unique lease over one pool-owned resource record, exposing that record as a readonly `value` and ending it through an idempotent `release` or `destroy`.              |
+| `PoolOptions`      | interface | `{ on?, error?, create, destroy?, validate?, watch?, capacity?, max?, min?, restarts? }` | Represents the resource lifecycle options for `Pool` and `createPool`: creation, destruction, validation, capacity, a bounded warm floor, and loss observation.                    |
+| `PoolInterface`    | interface | `{ emitter, size, idle, active } plus start, acquire, clear, destroy`                    | Represents a FIFO resource pool with optional bounded capacity, a warm floor, loss recovery, and deterministic teardown, exposing its record counts and a typed lifecycle emitter. |
+
+`size` counts every owned record, including records being validated, destroyed, or retained
+after failed cleanup under `min`. `idle` counts available records with no live lease or pending
+handout. `active` counts records with live leases, counting a shared record once. A partially
+occupied record is active and can accept another lease; it is not idle. A pending handout counts
+against `capacity` but becomes active only at its FIFO grant. An in-flight create reservation
+claims record capacity but is not yet an owned record and therefore is not part of `size`.
 
 ## Methods
 
@@ -85,24 +88,121 @@ The public call-signature members of `PoolInterface` and `PoolToken`; `Pool` imp
 
 #### `PoolInterface`
 
-| Method    | Returns                 | Summary                                                                                                                   |
-| --------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------- |
-| `acquire` | `Promise<PoolToken<T>>` | Queues the caller in FIFO order, validates an idle record or creates one, and settles queued acquires in that same order. |
-| `clear`   | `Promise<void>`         | Destroys the records that are idle at this call's synchronous snapshot.                                                   |
-| `destroy` | `Promise<void>`         | Tears down the pool permanently and returns its stable completion barrier.                                                |
+| Method    | Returns                 | Summary                                                                                                                                                    |
+| --------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `start`   | `Promise<void>`         | Fills the warm floor and resets the strikes of a spent floor; without a floor, resolves immediately.                                                       |
+| `acquire` | `Promise<PoolToken<T>>` | Queues the caller in FIFO order, shares an occupied record or validates an idle record, and waits for a floor refill or creates on demand without a floor. |
+| `clear`   | `Promise<void>`         | Destroys the records that are idle at this call's synchronous snapshot and restores a started floor.                                                       |
+| `destroy` | `Promise<void>`         | Tears down the pool permanently and returns its stable completion barrier.                                                                                 |
 
 #### `PoolToken`
 
-The lease returned by `acquire`, with the operation that returns its record.
+The lease returned by `acquire`, with operations that return or dispose its exact record.
 
-| Method    | Returns | Summary                                                                                                             |
-| --------- | ------- | ------------------------------------------------------------------------------------------------------------------- |
-| `release` | `void`  | Gives this exact record back to the pool once; a repeat call, and a call after teardown took ownership, are no-ops. |
+| Method    | Returns         | Summary                                                                                                                                          |
+| --------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `release` | `void`          | Ends this exact lease once; a repeat call, and a call after loss or teardown took ownership, are no-ops. Other leases on the record remain live. |
+| `destroy` | `Promise<void>` | Destroys this exact record for every co-holder and invalidates their leases; a repeat call, and a call after release, are no-ops.                |
 
 ## Contract
 
+### Warm floor and loss
+
+Construction creates nothing. Set `min` to a positive safe integer and `restarts` to a
+non-negative safe integer, then call `start()`. `max` defaults to `min`; explicit values
+must equal each other. A missing restart bound, a bound without `min`, and a non-callable
+`watch` are invalid. The restart bound has no default.
+
+`start()` resolves when the pool owns `min` live records. Concurrent calls share the pending
+promise. Without `min`, it resolves immediately. Under `min`, queued acquires never cause
+creation, including before `start()` and during failed refills. The pool refills missing
+capacity after startup and cleanup, one create attempt at a time.
+Bound your `create` and `destroy` hooks. A create hook that never settles blocks every later
+refill, including the attempt owed to a lost leased record. A destroy hook that never settles
+keeps its record counted against `max` and blocks replacement of that record.
+
+`watch(value, signal)` runs once for each created record. A fulfillment, rejection, or
+synchronous throw declares loss while the record is live. The pool removes the record from
+service, disposes it, and refills if the bound permits. Rejections and synchronous throws
+reach `error(error, 'watch')` only while the record is live; a throwing error handler is
+isolated. Disposal aborts the watch signal before the destroy hook runs, including disposal
+through validation, clear, pool teardown, and token destruction.
+The watch must release its listeners when that signal aborts. Any settlement after the signal
+aborts is ignored, including rejection. A late or repeated loss cannot
+dispose a record twice. A lost record cannot be handed out after validation or from a ready
+result waiting behind an earlier caller. The pool disposes a lost leased record while its
+holder still holds the token. The holder learns of that loss from its own `watch` or `destroy`
+hook. After disposal, the token's `release()` and `destroy()` calls do nothing. During disposal,
+the first `destroy()` call waits for that cleanup attempt and rejects with `cleanup` if it fails.
+
+A failed refill adds a strike. Losing a record with no live lease also adds a strike,
+including a previously used record and failed idle validation. Granting a lease resets the
+strikes only when the granted record was created after the last strike; successful creation
+alone does not. Granting an older healthy
+record leaves the strikes unchanged. Any idle record that dies, refills, and dies
+again without a grant between those losses can spend the floor.
+When strikes exceed `restarts`, the floor is spent. With `restarts: 1`, the first failed
+create permits another attempt, and the second refuses the next attempt. `start()` rejects
+with `create` and the last cause; another `start()` resets the strikes. While the floor is
+spent, an acquire without an eligible record rejects with `create` after pending refills and
+disposal settle. If the floor retains a record and owns `min` records, that acquire rejects
+with `cleanup` instead, even with live leases. A spent floor and a rejected `start()` still
+serve their live records. A loss without a thrown cause leaves that cause undefined.
+
+A record lost while leased earns one refill attempt even after the bound is spent.
+The credit becomes spendable only when successful disposal removes the record; failed disposal
+grants no credit. That attempt remains owed during a concurrent refill and never resets the strikes.
+Its failed create adds a strike; its success alone does not reset the strikes. Granting that
+replacement resets the strikes only if no strike occurred after its creation. A record that was leased
+and later lost after its last release adds a strike. Under sharing, loss or one lease's
+`destroy()` ends the record for every co-holder, invalidates their leases, and owes one refill
+regardless of the lease count. `token.destroy()` waits for an existing cleanup attempt and
+rejects with `cleanup` if disposal fails.
+A token ends once: after `release()` or `destroy()`, the other call does nothing. Repeating
+either call does nothing. A repeat `token.destroy()` after a `cleanup` rejection resolves
+while the record stays retained. Refills hold no lease before a caller's grant, so repeated idle
+losses spend the budget. A consumer that keeps a lease without a holder, or repeatedly acquires
+refilled records that fail during use, can keep earning refills and qualifying grant resets.
+The pool cannot distinguish such a lease from useful work; callers must acquire only for a holder.
+
+Under `min`, a failed destroy hook leaves its record counted against `max` and excluded from
+idle and active counts. The pool never replaces that retained record or retries its destroy
+hook. The pool can run short; `start()` rejects with `cleanup` if retained records prevent
+filling. An acquire rejects with `cleanup` when the floor retains a record, owns `min` records,
+has nothing eligible, and has no refill or disposal pending, even with live leases. The cause is
+the retained record's own cleanup failure. The terminal `destroy()` barrier
+reports the original cleanup failures. Without `min`, cleanup retains its lazy behavior and
+frees capacity after either hook outcome.
+
+This example warms an inert resource, explicitly loses its lease, and tears down the pool:
+
+```ts
+import { createPool } from '@orkestrel/pool'
+
+const pool = createPool({
+	create: () => new EventTarget(),
+	min: 1,
+	restarts: 1,
+	watch: (resource, signal) =>
+		new Promise<void>((resolve) => {
+			resource.addEventListener('loss', () => resolve(), { once: true, signal })
+			signal.addEventListener('abort', () => resolve(), { once: true })
+		}),
+})
+await pool.start()
+const token = await pool.acquire()
+await token.destroy()
+await pool.destroy()
+```
+
 ### Capacity and FIFO
 
+`capacity` is a positive safe integer limiting simultaneous leases on each record; it defaults
+to 1. `min` and `max` still bound records. Acquisition chooses the eligible record with the
+fewest live leases and reserved handouts. Idle ties follow release order; occupied ties follow
+record creation order. A validating record is unavailable until validation settles.
+Reservations count before any awaited hook.
+
 Every `acquire` receives its queue position before a create or validation hook starts. The
 reentrancy-safe pump may assign several hook operations concurrently, but a head commit
 barrier settles successes and failures in request order. A later fast create or validation
@@ -110,19 +210,32 @@ cannot overtake an earlier slow one. Capacity obeys:
 
 ```text
 owned records + create reservations <= max
+live leases + reserved handouts per record <= capacity
 ```
 
-`max` must be a positive safe integer. Omit it for an unbounded pool; `Infinity`, fractions,
-zero, negative values, and unsafe integers are invalid. Construction snapshots `max` once and
-validates it before retention, then snapshots `on` and `error` once each.
+`max` must be a positive safe integer. Omit `min` and `max` for an unbounded record count.
+`Infinity`, fractions, zero, negative values, and unsafe integers are invalid.
+Construction snapshots `max` and `capacity` once and validates them before retention, then
+snapshots `on` and `error` once each.
 
-Record phases are disjoint:
+Record ownership follows these transitions; an occupied record can carry several leases and
+reserved handouts, and returns to available after its last lease and reservation end:
 
 ```text
 create reservation -> ready -> leased -> available -> validating -> ready
                                       \-> destroying -> removed
+                                                     \-> retained (failed cleanup with min)
+floor refill --------------------------> available
 ```
 
+Validation runs only when reserving an idle record; handouts on an occupied record skip it.
+No caller receives a lease while idle validation is pending. This keeps a failed validation
+from silently disposing a record used by co-holders. After the last lease ends, the next idle
+reuse validates again. A freshly created lazy record keeps its direct handout behavior.
+With `capacity` greater than 1, an occupied record is never revalidated. Only `watch` detects
+its loss: without `watch`, a dead record can keep receiving leases until it becomes idle;
+with `watch`, that exposure lasts until the watch settles.
+
 Invalid validation, whether `false` or a thrown value, claims and cleans the record before a
 replacement capacity slot becomes available. Cleanup failure rejects that acquire with
 `PoolError` code `cleanup`; successful cleanup lets the same FIFO waiter seek a replacement.
@@ -145,19 +258,24 @@ eventual `destroy()` barrier.
 
 ### Release and cleanup
 
-A token captures its exact opaque record, so `release()` is correct even when multiple
-records contain the same value. Release is idempotent and removes the lease synchronously.
-With a waiter, the record is validated before handoff. Without an assignable waiter, it
-becomes idle and emits `release`. Release after teardown ownership transferred is a no-op.
+A token captures its exact lease and opaque record, so `release()` is correct even when multiple
+records contain the same value or several tokens share a record. Release is idempotent and
+removes only that lease synchronously. A remaining co-holder keeps the record active, and a
+waiter can share the freed place without validation. After the last release, idle reuse validates.
+A record that remains idle emits `release`. Release after loss or teardown took ownership does nothing.
+The pool disposes a lost lease while its holder still holds the token; the holder learns of
+the loss through its own `watch` or `destroy` hook. After disposal, both token methods do nothing.
 
 `clear()` synchronously snapshots idle records and installs one cleanup promise per record
 before invoking the hook. Concurrent clears therefore own disjoint snapshots, and a lease
-released after a snapshot is taken is not part of it. Every claimed record stays in `size` until its
-hook attempt completes. Distinct failures are aggregated in a code-`cleanup` `PoolError`
-whose `context.failures` retains the original thrown values.
-Each claimed record's cleanup settlement independently wakes queued acquires after the
-destroy ledger transition, whether its cleanup hook succeeded or failed; a failed `clear()`
-still rejects its own aggregate cleanup barrier.
+released after a snapshot is taken is not part of it. Every claimed record stays in `size` during
+its hook attempt; failed cleanup under `min` retains it afterward. Distinct failures are
+aggregated in a code-`cleanup` `PoolError` whose `context.failures` retains the original thrown
+values.
+Each claimed record's cleanup settlement wakes queued acquires after the destroy ledger
+transition. A failed `clear()` rejects its own aggregate cleanup barrier; under `min`,
+the pool keeps a record whose cleanup fails counted against `max`, and successful cleanup
+restores a started floor.
 
 ### Destruction
 
@@ -165,7 +283,8 @@ still rejects its own aggregate cleanup barrier.
 rejects waiters, emits events, or invokes cleanup. Reentrant and repeated calls return that
 same object. Teardown invalidates idle, leased, and ready records, waits for create,
 validation, existing clear cleanup, and new cleanup activity, and disposes every late
-resource. Unresolved hooks keep the barrier pending without polling.
+resource. A pending `start()` rejects with `destroyed`. Unresolved create, validation, and
+destroy hooks keep the barrier pending without polling; aborted watches do not delay it.
 
 Cleanup already owned by an overlapping `clear()` is shared; its failure is reported to both
 the clear call and the destroy aggregate. Create failures that produced no resource do not
@@ -176,12 +295,12 @@ hook attempt, then the stable barrier resolves or rejects.
 
 `PoolError.code` is stable and lowercase:
 
-| Code        | Owner                                                                    |
-| ----------- | ------------------------------------------------------------------------ |
-| `invalid`   | Invalid explicit `max`, invalid acquire signal, or an internal boundary. |
-| `destroyed` | Acquire or clear attempted after terminal teardown began.                |
-| `create`    | The create hook failed for its bound acquire.                            |
-| `cleanup`   | Invalid-handoff, clear, or destroy cleanup failed.                       |
+| Code        | Owner                                                                               |
+| ----------- | ----------------------------------------------------------------------------------- |
+| `invalid`   | Invalid capacity, restart bound, watch hook, acquire signal, or internal boundary.  |
+| `destroyed` | Start, acquire, or clear attempted during terminal teardown.                        |
+| `create`    | A lazy create failed, or a floor refill bound was spent.                            |
+| `cleanup`   | Record disposal failed, including retained records blocking startup or acquisition. |
 
 The original thrown value is retained as `cause`; aggregate cleanup values are also in
 `context.failures`. Message construction and `isPoolError` avoid unsafe string coercion and
@@ -194,12 +313,12 @@ invokes listeners synchronously at each emission point. The `destroy` emission i
 one microtask after cleanup settlement so bound outcomes precede observer reentry. Events
 follow their ledger transitions:
 
-| Event     | Emission point                                                                                                                                                      |
-| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `create`  | After a fresh resource is inserted into the ownership ledger.                                                                                                       |
-| `acquire` | After the waiter promise receives its token and the record is leased.                                                                                               |
-| `release` | Only when the released or orphaned-ready record remains idle.                                                                                                       |
-| `destroy` | After the hook attempt and resource-ledger removal, one microtask after private cleanup settlement, while destroying ownership remains installed through the event. |
+| Event     | Emission point                                                                                                                                                                   |
+| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `create`  | After a fresh resource is inserted into the ownership ledger.                                                                                                                    |
+| `acquire` | After the waiter promise receives its token and the record is leased.                                                                                                            |
+| `release` | Only when a released, orphaned, or refilled record remains idle.                                                                                                                 |
+| `destroy` | After the hook attempt and resource-ledger removal or retention, one microtask after private cleanup settlement, while destroying ownership remains installed through the event. |
 
 Because listeners may synchronously reenter or destroy the pool, the engine checks terminal
 and waiter state after every awaited hook and every emit.
@@ -224,10 +343,10 @@ const pool = createPool({
 Check a candidate value or error against the public boundary guards before acting on it:
 
 ```ts
-import { PoolError, isPoolError, isPoolMax, isPoolSignal } from '@orkestrel/pool'
+import { PoolError, isPoolError, isPoolLimit, isPoolSignal } from '@orkestrel/pool'
 
-isPoolMax(4) // true
-isPoolMax(Infinity) // false: omit max for unbounded capacity
+isPoolLimit(4) // true
+isPoolLimit(Infinity) // false: omit max for unbounded capacity
 isPoolSignal(new AbortController().signal) // true
 
 const failure = new PoolError({ code: 'destroyed' })
@@ -260,7 +379,8 @@ await pool.destroy()
   hooks, create continuation, abort boundaries, abort-listener detachment, exclusive
   invalid-cleanup waiter ownership, bounded and unbounded replacement, destroy-observer
   reentry ordering, concurrent clear, stable reentrant destruction, late resources,
-  aggregate failures, emitter ordering, and high contention.
+  aggregate failures, emitter ordering, high contention, warm floors, exact refill bounds,
+  retained cleanup failures, watch cancellation, lost-record handoff races, and owed lease refills.
 - [`tests/src/core/validators.test.ts`](../tests/src/core/validators.test.ts) — the public
   boundary guards alone: accepted and rejected maxima, and native versus hostile signals.
 - [`tests/src/core/factories.test.ts`](../tests/src/core/factories.test.ts) — factory
@@ -271,7 +391,8 @@ await pool.destroy()
   its declaration's description paragraph, the titled `Create a pool` fence against the
   `@example` block of that title (pinned so the titled pair cannot be retired silently), and the
   README pitch against this guide's tagline. It also runs the boundary-guard fence and asserts
-  the values its comments claim.
+  the values its comments claim. The floor fence is checked line for line in execution order
+  and runs with assertions for warming, token cleanup, and watch-listener removal.
 
 ## See also