@orkestrel/terminal 0.0.14 → 0.0.16

package/README.md

@@ -1,14 +1,13 @@
 # @orkestrel/terminal
 
-The terminal side of a form, for the `@orkestrel` line. `@orkestrel/form` owns
-the document — the schema, the controls, the rules, the values, and the
-settle-once `answer` promise. This package owns what form has no opinion about:
-a key decoder, a theme, pure per-field reducers, and the surfaces one form
-can be answered on. The server `Terminal` implements the one driving contract
-against a real TTY (raw-mode stdin, live in-place re-render, a `node:readline`
-fallback when piped). The headless `Prompt` broker PARKS a live form until
-somebody elsewhere answers it. The `PromptClient` bridge carries a form parked
-elsewhere to this machine's keyboard over SSE. Built beside
+> The terminal side of a form: a key decoder, a presentation theme, the pure per-field reducers,
+> the headless broker that parks a live form until somebody elsewhere answers it, the SSE bridge
+> that carries a parked form to a machine with a keyboard, and the manager that routes parked
+> forms between named endpoints.
+
+`@orkestrel/form` owns the document — the schema, the controls, the rules,
+the values, and the settle-once `answer` promise — and this package declares
+none of it a second time. Part of the `@orkestrel` line, built beside
 `@orkestrel/console` (the shared style engine), `@orkestrel/contract`,
 `@orkestrel/emitter`, `@orkestrel/database`, and `@orkestrel/sse`.
 
@@ -42,7 +41,7 @@ const values = await terminal.ask(
 )
 ```
 
-A bare return binds ABSENCE, not the empty string, so `required` refuses it and
+A bare return binds absence, not the empty string, so `required` refuses it and
 the walk asks again.
 
 Park a live form and answer it from anywhere else:
@@ -56,7 +55,7 @@ prompt.emitter.on('pending', (form) => send(form)) // the wire-safe record
 
 const form = createForm({ fields: [{ control: 'text', name: 'name' }] })
 const id = prompt.park(form) // the id; you await the form's own `answer`
-prompt.answer(id, { name: 'Ada' }) // fills and submits the AUTHORITATIVE form
+prompt.answer(id, { name: 'Ada' }) // fills and submits the authoritative form
 const values = await form.answer // { name: 'Ada' }
 ```
 

package/dist/src/core/index.cjs

@@ -36,10 +36,11 @@ var CTRL_E = String.fromCharCode(5);
 */
 var KEY_SS3 = `${_orkestrel_console.ESC}O`;
 /**
-* Holds the exact escape SEQUENCE → canonical key NAME table {@link import('./helpers.js').parseKey}
-* consults for the navigation / editing keys. Covers BOTH the CSI form (`ESC[A`…) and the SS3
-* form (`ESCOA`…) of the arrows, plus the `home` / `end` / `delete` CSI sequences (with
-* their numeric-tilde variants). The source of truth for the multi-byte key decode; frozen.
+* Holds the exact escape sequence to canonical key name table
+* {@link import('./helpers.js').parseKey} consults for the navigation and editing keys. Covers the
+* CSI form (`ESC[A`…) and the SS3 form (`ESCOA`…) of the arrows, plus the `home` / `end` / `delete`
+* CSI sequences with their numeric-tilde variants. The source of truth for the multi-byte key
+* decode; frozen.
 *
 * @remarks
 * Terminals disagree on these: a cursor key is `ESC[A` (normal) or `ESCOA` (application mode),
@@ -65,10 +66,10 @@ var SEQUENCE_NAMES = Object.freeze({
 	[`${_orkestrel_console.CSI}8~`]: "end"
 });
 /**
-* Holds the control BYTE (or CRLF pair) → key descriptor table {@link import('./helpers.js').parseKey}
-* consults for the one-byte keys and the two-byte CRLF Enter chunk. Each entry carries the
-* canonical `name` and whether it is a `ctrl` combination. The source of truth for that decode;
-* frozen.
+* Holds the control byte (or CRLF pair) to key descriptor table
+* {@link import('./helpers.js').parseKey} consults for the one-byte keys and the two-byte CRLF
+* Enter chunk. Each entry carries the canonical `name` and whether it is a `ctrl` combination. The
+* source of truth for that decode; frozen.
 *
 * @remarks
 * `return` / `newline` / `return + newline` all map to `return` (one canonical Enter name) — a
@@ -135,8 +136,9 @@ var CONTROL_NAMES = Object.freeze({
 /** Names the default mask glyph {@link import('./helpers.js').createPasswordState} uses — `*`. */
 var DEFAULT_MASK = "*";
 /**
-* Holds the default glyphs {@link DEFAULT_PROMPT_THEME} assembles its `icons` from. Read only when
-* the default theme is assembled; a view reads its resolved theme and never this constant. Frozen.
+* Holds the terminal-owned glyphs {@link DEFAULT_PROMPT_THEME} assembles its `icons` from, beside
+* the console module's own success and error marks. Read only when the default theme is assembled;
+* a view reads its resolved theme and never this constant. Frozen.
 *
 * @remarks
 * - `question` — the leading mark on a prompt's message line.
@@ -225,17 +227,18 @@ var DEFAULT_PROMPT_THEME = Object.freeze({
 		description: (0, _orkestrel_console.freezeStyle)({ attributes: ["dim"] })
 	})
 });
-/** Holds how long (ms) the {@link import('./types.js').PromptInterface} broker parks an unanswered prompt before it expires — 5 minutes. */
+/** Holds how long (ms) the {@link import('./types.js').PromptInterface} broker parks an unanswered form before it expires — 5 minutes. */
 var DEFAULT_PROMPT_TIMEOUT_MS = 3e5;
 /** Holds how long (ms) the {@link import('./types.js').PromptClientInterface} waits before each reconnect attempt — 2 seconds. */
 var DEFAULT_RECONNECT_DELAY_MS = 2e3;
 /**
-* Holds the SSE `event:` names the broker emits and the {@link import('./types.js').PromptClientInterface}
-* dispatches on. Frozen; the source of truth for the wire event vocabulary.
+* Holds the SSE `event:` names the broker emits and the
+* {@link import('./types.js').PromptClientInterface} dispatches on — `pending`, `expire`, and
+* `destroy`. Frozen; the source of truth for the wire event vocabulary.
 *
 * @remarks
 * - `pending` — a serialized {@link import('./types.js').PendingForm} to dispatch and answer.
-* - `expire` — an `{ id }` payload: the broker expired or released a parked prompt (the client drops it).
+* - `expire` — an `{ id }` payload: the broker expired or released a parked form (the client drops it).
 * - `destroy` — the broker is going away; the client disconnects (no auto-reconnect) but stays reusable.
 */
 var SSE_EVENTS = Object.freeze({
@@ -243,9 +246,12 @@ var SSE_EVENTS = Object.freeze({
 	expire: "expire",
 	destroy: "destroy"
 });
-/** Names the auth-token request header the {@link import('./types.js').PromptClientInterface} sends. */
+/**
+* Names the auth-token request header the {@link import('./types.js').PromptClientInterface} sends
+* when a `token` is configured — `x-orkestrel-token`.
+*/
 var HEADER_TOKEN = "x-orkestrel-token";
-/** Names the `Accept` header value that opens the broker's SSE stream. */
+/** Names the `Accept` header value that opens the broker's SSE stream — `text/event-stream`. */
 var ACCEPT_EVENT_STREAM = "text/event-stream";
 /**
 * Sets the maximum number of characters the {@link import('./types.js').PromptClientInterface} lets its
@@ -287,7 +293,7 @@ var TerminalError = class extends Error {
 	}
 };
 /**
-* Narrows an unknown caught value to a {@link TerminalError}.
+* Narrows an unknown caught value to a {@link TerminalError}, so a caller can branch on its `code`.
 *
 * @param value - The value to test (typically a `catch` binding or a rejected prompt call)
 * @returns True if `value` is a {@link TerminalError}; false otherwise
@@ -304,7 +310,7 @@ var TerminalError = class extends Error {
 * ```
 */
 function isTerminalError(value) {
-	return value instanceof TerminalError;
+	return (0, _orkestrel_contract.isInstance)(value, TerminalError);
 }
 //#endregion
 //#region src/core/validators.ts
@@ -316,7 +322,8 @@ function isTerminalError(value) {
 */
 var isPendingFormStatus = (0, _orkestrel_contract.literalOf)("pending", "answered", "expired");
 /**
-* Narrows an unknown wire value to a {@link PendingForm} envelope.
+* Narrows an unknown wire value to a {@link PendingForm} envelope — the envelope alone, because the
+* form package's `parseForm` owns the schema payload.
 *
 * @remarks
 * This guard checks the transport record and proves only that `schema` is a record. The Form
@@ -336,7 +343,8 @@ function isPendingForm(value) {
 	}, ["from", "to"])(value);
 }
 /**
-* Narrows an unknown value to a transport-neutral {@link WireEvent}.
+* Narrows an unknown value to a transport-neutral {@link WireEvent} — the guard a consumer's own
+* transport applies to an inbound frame.
 *
 * @param value - The candidate wire event
 * @returns True if the value carries an event name, serialized data, and an optional id; false otherwise
@@ -347,8 +355,8 @@ var isWireEvent = (0, _orkestrel_contract.recordOf)({
 	id: _orkestrel_contract.isString
 }, ["id"]);
 /**
-* Narrows an unknown value to a {@link TerminalSnapshot} — the read boundary a store applies to an
-* untrusted persisted row.
+* Narrows an unknown value to a {@link TerminalSnapshot} — a non-empty `id` and an optional numeric
+* `timeout`, the read boundary a store applies to an untrusted persisted row.
 *
 * @param value - The candidate snapshot read back from storage
 * @returns True if the value carries a non-empty `id` and an optional numeric `timeout`; false otherwise
@@ -361,16 +369,16 @@ var isTerminalSnapshot = (0, _orkestrel_contract.recordOf)({
 //#region src/core/helpers.ts
 /**
 * Decodes one keypress's bytes into a {@link KeyEvent} — total, never throws. A `Uint8Array` is
-* read as UTF-8; the resulting string is matched against the known control bytes and the CRLF
-* pair ({@link CONTROL_NAMES}) and escape sequences ({@link SEQUENCE_NAMES}), falling back to a
-* single printable character. An unrecognized sequence carries NO `name`, with the raw `sequence`
+* read as UTF-8; the resulting string is matched against the known control bytes and the CRLF pair
+* ({@link CONTROL_NAMES}) and escape sequences ({@link SEQUENCE_NAMES}), falling back to a single
+* printable character. An unrecognized sequence carries no `name`, with the raw `sequence`
 * preserved.
 *
 * @remarks
 * - **Single control byte.** A one-character control input (`return` / `backspace` / `tab` /
 *   `escape` / `space`, or a Ctrl combo `c` / `d` / `u` / `a` / `e`), or the two-byte `\r\n`
 *   CRLF pair, is looked up in {@link CONTROL_NAMES}, carrying its `ctrl` flag.
-* - **Escape sequence.** A multi-byte ESC sequence (`up` / `down` / `left` / `right` in BOTH the
+* - **Escape sequence.** A multi-byte ESC sequence (`up` / `down` / `left` / `right` in both the
 *   `ESC[A` and `ESCOA` forms, plus `home` / `end` / `delete`) is looked up in
 *   {@link SEQUENCE_NAMES} and flagged `meta`.
 * - **Printable character.** A single printable character becomes `name` = that character, with
@@ -425,8 +433,8 @@ function parseKey(input) {
 	};
 }
 /**
-* Checks whether a single character is a printable (non-control) character — used by
-* {@link parseKey}'s char fallback.
+* Checks whether a single character is printable — the fallback test {@link parseKey} applies after
+* the control bytes and the escape sequences, so the C0 controls and DEL are excluded.
 *
 * @param character - The single character to test
 * @returns True if the character is at or above space and is not DEL; false otherwise
@@ -488,7 +496,8 @@ function sanitizeDisplayText(text) {
 	return (0, _orkestrel_console.stripControls)((0, _orkestrel_console.strip)(text)).replaceAll("	", "").replaceAll("\n", "").replaceAll("\r", "");
 }
 /**
-* Sanitizes every terminal-readable string in a parsed form schema.
+* Sanitizes every terminal-readable string in a parsed form schema, keeping every identity and
+* answer string verbatim and dropping field metadata.
 *
 * @remarks
 * Display strings pass through {@link sanitizeDisplayText}: labels, help, placeholders, masks,
@@ -639,7 +648,8 @@ function renderSubmitHeader(styler, theme, message) {
 	return `${styler.render(theme.roles.success, theme.icons.success)} ${styler.render(theme.roles.message, message)}`;
 }
 /**
-* Renders the styled failure line (`✖ message`) a form driver appends for a refused field.
+* Renders the styled failure line (`✖ message`) a form driver writes for each refused field before
+* it asks that field again.
 *
 * @param styler - The console styler that renders each role
 * @param theme - The resolved prompt theme
@@ -650,7 +660,8 @@ function renderErrorLine(styler, theme, message) {
 	return `${styler.render(theme.roles.error, theme.icons.error)} ${styler.render(theme.roles.error, message)}`;
 }
 /**
-* Builds the initial text-field key state.
+* Builds the initial text-field reducer state — the sanitized label, the declared default, the
+* styler, and the resolved theme.
 *
 * @param field - The text field to render
 * @param styler - The styler used to render the view
@@ -667,7 +678,8 @@ function createInputState(field, styler = (0, _orkestrel_console.createStyler)()
 	};
 }
 /**
-* Renders a text-field key state as a styled view.
+* Renders a text-field reducer state as a styled view — the header, the pointer, and the typed
+* value, or the default shown as a hint while nothing is typed.
 *
 * @param state - The text field's current reducer state
 * @returns The rendered single-line view — header, pointer, and the typed value or the default
@@ -722,7 +734,8 @@ function reduceInput(state, key) {
 	};
 }
 /**
-* Builds the initial password-field key state.
+* Builds the initial password-field reducer state — the text-field state, plus the mask glyph each
+* typed character renders as.
 *
 * @param field - The password field to render
 * @param styler - The styler used to render the view
@@ -739,7 +752,8 @@ function createPasswordState(field, styler = (0, _orkestrel_console.createStyler
 	};
 }
 /**
-* Renders a password-field key state as a styled view.
+* Renders a password-field reducer state as a styled view, with the value replaced by the mask
+* repeated so the secret is never echoed.
 *
 * @param state - The password field's current reducer state
 * @returns The rendered view, with the mask repeated in place of the typed value
@@ -786,7 +800,8 @@ function reducePassword(state, key) {
 	};
 }
 /**
-* Builds the initial confirm-field key state.
+* Builds the initial confirm-field reducer state — the sanitized label and the declared default
+* answer.
 *
 * @param field - The confirm field to render
 * @param styler - The styler used to render the view
@@ -802,7 +817,8 @@ function createConfirmState(field, styler = (0, _orkestrel_console.createStyler)
 	};
 }
 /**
-* Renders a confirm-field key state as a styled view. The selected role paints the default letter.
+* Renders a confirm-field reducer state as a styled view — the header and the yes/no group, with
+* the default letter capitalized and painted by the `selected` role.
 *
 * @param state - The confirm field's current reducer state
 * @returns The rendered view — the header and the yes/no group with the default capitalized
@@ -845,7 +861,8 @@ function reduceConfirm(state, key) {
 	};
 }
 /**
-* Builds the initial select-field key state.
+* Builds the initial select-field reducer state — the offered choices, with the focus pre-placed on
+* the declared default.
 *
 * @param field - The select field to render
 * @param styler - The styler used to render the view
@@ -864,7 +881,8 @@ function createSelectState(field, styler = (0, _orkestrel_console.createStyler)(
 	};
 }
 /**
-* Renders a select-field key state as a multi-line styled view.
+* Renders a select-field reducer state as a multi-line styled view — one row per choice, with the
+* focused row marked and its help shown.
 *
 * @param state - The select field's current reducer state
 * @returns The rendered view — the header, then one row per choice with the focused row marked
@@ -878,7 +896,7 @@ function renderSelectView(state) {
 }
 /**
 * Advances a select prompt by one {@link KeyEvent} — the pure `(state, key) → PromptStep<string>`
-* reducer. `up` / `down` (and `k` / `j`) move the focus, WRAPPING at the ends; return submits the
+* reducer. `up` / `down` (and `k` / `j`) move the focus, wrapping at the ends; return submits the
 * focused choice's `value`; ctrl-c cancels. An empty choice list can never submit (a higher layer
 * guards against it); any other key is ignored.
 *
@@ -937,7 +955,8 @@ function reduceSelect(state, key) {
 	};
 }
 /**
-* Builds the initial checkbox-field key state.
+* Builds the initial checkbox-field reducer state — the offered choices, with every value in the
+* field's `default` list pre-checked.
 *
 * @param field - The checkbox field to render
 * @param styler - The styler used to render the view
@@ -960,7 +979,8 @@ function createCheckboxState(field, styler = (0, _orkestrel_console.createStyler
 	};
 }
 /**
-* Renders a checkbox-field key state as a multi-line styled view.
+* Renders a checkbox-field reducer state as a multi-line styled view — one box per choice, and the
+* selected count beneath them.
 *
 * @param state - The checkbox field's current reducer state
 * @returns The rendered view — the header, one box per choice, and the selected count
@@ -1048,7 +1068,7 @@ function reduceCheckbox(state, key) {
 }
 /**
 * Toggles `index` in a readonly index list — copy-on-write, returning the new sorted-by-insertion
-* list.
+* list; the primitive {@link reduceCheckbox} calls.
 *
 * @param indices - The ticked indices, in tick order
 * @param index - The index to add when absent, or drop when present
@@ -1058,7 +1078,8 @@ function toggleIndex(indices, index) {
 	return indices.includes(index) ? indices.filter((i) => i !== index) : [...indices, index];
 }
 /**
-* Builds the initial editor-field key state.
+* Builds the initial editor-field reducer state — the committed lines empty, and the declared
+* default held for a finish with nothing typed.
 *
 * @param field - The editor field to render
 * @param styler - The styler used to render the view
@@ -1076,7 +1097,8 @@ function createEditorState(field, styler = (0, _orkestrel_console.createStyler)(
 	};
 }
 /**
-* Renders an editor-field key state as a multi-line styled view with its finish hint.
+* Renders an editor-field reducer state as a multi-line styled view — the finish hint, the
+* committed lines, and the line in progress.
 *
 * @param state - The editor field's current reducer state
 * @returns The rendered view — the hinted header, the committed lines, and the line in progress
@@ -1089,8 +1111,8 @@ function renderEditorView(state) {
 /**
 * Advances an editor prompt by one {@link KeyEvent} — the pure `(state, key) → PromptStep<string>`
 * reducer. Printable characters extend the current line; backspace shrinks it; return commits the
-* current line and starts a fresh one; ctrl-d FINISHES (joining all lines, falling back to the
-* default when empty); ctrl-c cancels. The form validates the candidate after the driver fills it.
+* current line and starts a fresh one; ctrl-d finishes, joining every line and falling back to the
+* default when empty; ctrl-c cancels. The form validates the candidate after the driver fills it.
 *
 * @param state - The editor field's current reducer state
 * @param key - The decoded keypress to apply
@@ -1142,9 +1164,10 @@ function reduceEditor(state, key) {
 	};
 }
 /**
-* Applies a single line-editing {@link KeyEvent} to a text buffer — the editing shared by input /
-* password / editor. A printable key appends its character; `backspace` drops the last character;
-* `space` appends a space; ctrl-u clears the line.
+* Applies a single line-editing {@link KeyEvent} to a text buffer — the editing shared by input,
+* password, and editor. A printable key appends its character; `backspace` drops the last
+* character; `space` appends a space; ctrl-u clears the line; a key that edits nothing returns
+* `undefined`.
 *
 * @param value - The buffer the field holds so far
 * @param key - The decoded keypress to apply
@@ -1192,11 +1215,13 @@ function globalFetch(input, init) {
 * @returns True if the value is a host `Error` or `DOMException` named `AbortError`; false otherwise
 */
 function isAbortError(error) {
-	return (error instanceof DOMException || error instanceof Error) && error.name === "AbortError";
+	return (0, _orkestrel_contract.isError)(error) && error.name === "AbortError";
 }
 /**
-* Checks whether `url` is an INSECURE remote endpoint — a plain `http://` URL whose host is NOT a
-* loopback address. Pure string parsing (no `URL` global), so it stays total on malformed input.
+* Checks whether `url` is an insecure remote endpoint — a plain `http://` URL whose host is not a
+* loopback address. Pure string parsing (no `URL` global), so it stays total on malformed input;
+* the {@link import('./PromptClient.js').PromptClient} warns once when a `token` would cross such
+* an endpoint in cleartext.
 *
 * @remarks
 * A loopback host (`localhost`, `127.0.0.1`, `[::1]`) over `http://` is exempt (local
@@ -1223,7 +1248,8 @@ function isInsecureRemote(url) {
 	return hostname !== "localhost" && hostname !== "127.0.0.1" && hostname !== "[::1]";
 }
 /**
-* Serializes a parked {@link PendingForm} into a {@link WireEvent}.
+* Serializes a parked {@link PendingForm} into a `pending` {@link WireEvent}, whose frame `id` is
+* the form's own id.
 *
 * @param form - The parked form's wire-safe record
 * @returns The `pending` frame — the JSON-stringified record as `data`, and the form's own `id`
@@ -1236,7 +1262,8 @@ function serializePending(form) {
 	};
 }
 /**
-* Serializes a parked prompt's expiry or release into a {@link WireEvent}.
+* Serializes a parked form's expiry or release into an `expire` {@link WireEvent}, whose `data` is
+* the JSON `{ id }` payload.
 *
 * @param id - The id of the parked form that expired or was released
 * @returns The `expire` frame, carrying the JSON-stringified `{ id }` payload as `data`
@@ -1248,7 +1275,8 @@ function serializeExpire(id) {
 	};
 }
 /**
-* Serializes the {@link WireEvent} a broker or manager sends when it is going away.
+* Serializes the `destroy` {@link WireEvent} a broker or manager sends when it is going away, which
+* carries no payload.
 *
 * @returns The `destroy` frame, whose `data` is empty because the signal carries no payload
 */
@@ -1261,8 +1289,9 @@ function serializeDestroy() {
 //#endregion
 //#region src/core/Prompt.ts
 /**
-* Implements the headless form broker. It parks live forms, exposes their serialized schemas, and applies
-* remote answers to the authoritative form.
+* Implements the headless form broker. It parks live forms, exposes their serialized schemas,
+* applies remote answers to the authoritative form, and abandons a parked form on timeout, release,
+* or teardown.
 *
 * @remarks
 * A parked record carries one call to `serializeForm`. A failed fill or submit leaves the record
@@ -1419,7 +1448,7 @@ var Prompt = class {
 			if ((0, _orkestrel_form.isFieldError)(error.context)) return [error.context];
 			const named = error.context?.field;
 			return [{
-				field: typeof named === "string" ? named : this.#field(form, field),
+				field: (0, _orkestrel_contract.isString)(named) ? named : this.#field(form, field),
 				message: error.message
 			}];
 		}
@@ -1452,8 +1481,9 @@ var Prompt = class {
 //#endregion
 //#region src/core/PromptClient.ts
 /**
-* Implements the SSE form bridge. It ingests serialized forms from a remote broker, renders them through a
-* local terminal, and posts answers back without blocking the event stream.
+* Implements the SSE form bridge. It ingests serialized forms from a remote broker without waiting
+* on a render, drives one form at a time through a local terminal, posts each answer back, and asks
+* again when the authoritative form refuses one.
 *
 * @remarks
 * - **Connect + reconnect.** {@link connect} opens the SSE stream and reconnects after a transport
@@ -1465,8 +1495,9 @@ var Prompt = class {
 * - **Safe local form.** The rendering copy omits every wire `pattern`, because Form compiles a
 *   pattern during local evaluation. The broker's parked form retains it and remains authoritative.
 * - **Refusal retry.** A structured `rejected` response seeds a new rendering form with the values
-*   just submitted, applies every {@link FieldError} through `invalidate`, and asks again. No retry
-*   counter truncates the loop; acceptance, expiry, and the broker's own teardown are its bounds.
+*   the refused attempt submitted, applies every {@link FieldError} through `invalidate`, and asks
+*   again. No retry counter truncates the loop; acceptance, expiry, and the broker's own teardown
+*   are its bounds.
 * - **Replay safety.** A replayed id is skipped while it is queued, rendering, or posting. Once an
 *   attempt ends, a later delivery of that id may be rendered again.
 *
@@ -1757,24 +1788,24 @@ var PromptClient = class {
 //#endregion
 //#region src/core/TerminalManager.ts
 /**
-* Registers named {@link PromptInterface} brokers (one per endpoint), so several parties can
-* `ask` forms of each other by NAME with a `from` → `to` attribution edge on every parked form,
-* and a transitive DEADLOCK check across all in-flight asks.
+* Registers named {@link PromptInterface} brokers, one per endpoint, so several parties can `ask`
+* forms of each other by name with a `from` → `to` attribution edge on every parked form, and
+* refuses `DEADLOCK` on a transitive cycle across every in-flight ask.
 *
 * @remarks
 * - **Registry.** `add(name, options?)` mints (or, if `name` is already mounted, returns the
-*   EXISTING broker UNCHANGED — idempotent, never clobbers a live/parked endpoint). Every mounted
+*   existing broker unchanged — idempotent, never clobbers a live/parked endpoint). Every mounted
 *   broker's `pending` / `answer` / `expire` events are re-emitted on the manager, attributed by
 *   `name`.
-* - **`ask`.** The target must already be mounted via {@link add} — `ask` never auto-adds it;
+* - **`ask`.** The target must already be mounted through {@link add} — `ask` never auto-adds it;
 *   rejects `TARGET` for an unknown `to` (listing the known names). Rejects `DEADLOCK` when parking
-*   `from → to` would close a cycle over the CURRENT in-flight edge set (walked transitively);
+*   `from → to` would close a cycle over the current in-flight edge set (walked transitively);
 *   otherwise parks the caller's live form through the target's broker and returns that form's own
 *   `answer` promise. Edge cleanup never alters the value or rejection the caller observes.
 * - **Durable open / save.** `open(name)` restores an EMPTY broker from the `store` (parked
 *   Promises are process-bound and never resurrected); `save(name)` persists the endpoint's
 *   configured `timeout`.
-* - **Removal.** `remove` drops one endpoint, a batch (the array overload declared FIRST), or every
+* - **Removal.** `remove` drops one endpoint, a batch (the array overload declared first), or every
 *   endpoint when called without an argument. It destroys each broker, which expires every form
 *   still parked on it. `destroy` is idempotent.
 *
@@ -2001,9 +2032,10 @@ var TerminalManager = class {
 //#region src/core/stores/MemoryTerminalStore.ts
 /**
 * Implements the in-memory {@link TerminalStoreInterface} — a process-lifetime `Map` of
-* {@link TerminalSnapshot}s keyed by endpoint id, the DEFAULT store
-* {@link import('../factories.js').createMemoryTerminalStore} builds. The EXACT twin of
-* {@link import('./DatabaseTerminalStore.js').DatabaseTerminalStore}.
+* {@link TerminalSnapshot} records keyed by endpoint id, the default store
+* {@link import('../factories.js').createMemoryTerminalStore} builds and the exact twin of
+* {@link import('./DatabaseTerminalStore.js').DatabaseTerminalStore}. It carries no idle expiry and
+* no eviction.
 *
 * @remarks
 * A plain `Map<string, TerminalSnapshot>` — the snapshot is already pure, self-contained CONFIG-only
@@ -2066,10 +2098,11 @@ var MemoryTerminalStore = class {
 //#endregion
 //#region src/core/stores/DatabaseTerminalStore.ts
 /**
-* Implements a {@link TerminalStoreInterface} backed by one table of the `databases` layer — an endpoint's
-* durable CONFIG state IS a row, so persistence reduces to keyed point-access (`get` / `set` /
-* `delete`) over a {@link TableInterface}, the driver-pluggable twin of the plain-`Map`
-* {@link import('./MemoryTerminalStore.js').MemoryTerminalStore}.
+* Implements a {@link TerminalStoreInterface} backed by one table of the `databases` layer — an
+* endpoint's durable config state is a row, so persistence reduces to keyed point-access (`get` /
+* `set` / `delete`) over a {@link TableInterface}, the driver-pluggable twin of the plain-`Map`
+* {@link import('./MemoryTerminalStore.js').MemoryTerminalStore}. A stored `snapshot` is narrowed
+* with {@link import('../validators.js').isTerminalSnapshot} on read.
 *
 * @remarks
 * The store is driver-agnostic: it holds a single {@link TableInterface} whose backend (memory,
@@ -2183,9 +2216,10 @@ function createPrompt(options) {
 	return new Prompt(options);
 }
 /**
-* Creates the SSE prompt {@link PromptClientInterface} BRIDGE — it connects to a remote broker's SSE
-* endpoint, dispatches each received form to a local {@link import('./types.js').TerminalInterface},
-* and POSTs the answer back. Universal — `fetch` / SSE are web-standard.
+* Creates the SSE prompt {@link PromptClientInterface} bridge — it connects to a remote broker's
+* SSE endpoint, dispatches each received form to a local
+* {@link import('./types.js').TerminalInterface}, and POSTs the answer back. Universal — `fetch`
+* and SSE are web standards.
 *
 * @param options - See {@link PromptClientOptions} (`url` + `terminal` required)
 * @returns A {@link PromptClientInterface}
@@ -2209,9 +2243,9 @@ function createPromptClient(options) {
 	return new PromptClient(options);
 }
 /**
-* Creates the multi-endpoint {@link TerminalManager} — a named registry of
-* {@link PromptInterface} brokers so several parties can `ask` prompts of each other by name,
-* with a transitive DEADLOCK check across every in-flight ask.
+* Creates the multi-endpoint {@link TerminalManager} — a named registry of {@link PromptInterface}
+* brokers so several parties can `ask` forms of each other by name, with a transitive cycle check
+* that refuses `DEADLOCK` across every in-flight ask.
 *
 * @param options - See {@link TerminalManagerOptions}
 * @returns A {@link TerminalManager}
@@ -2246,7 +2280,8 @@ function createMemoryTerminalStore() {
 /**
 * Creates a {@link TerminalStoreInterface} backed by one table of the `databases` layer — the
 * driver-pluggable twin of {@link createMemoryTerminalStore}, storing each endpoint's config
-* snapshot as one opaque JSON column.
+* snapshot as one opaque JSON column. The default driver is an in-memory `@orkestrel/database`
+* driver.
 *
 * @param driver - The {@link DriverInterface} backing the table (default an in-memory driver)
 * @returns A {@link TerminalStoreInterface}