@naswerks/periscope 1.0.0

package/dist/control/stream-routing.js

@@ -0,0 +1,167 @@
+import { discriminatorOf } from '../host/agent-process.js';
+export const MESSAGE_ROUTING = {
+    // --- delta: superseded, high-frequency, broadcast-only ---------------------
+    stream_event: {
+        lane: 'delta',
+        note: 'the incremental lane — text_delta, thinking_delta, input_json_delta, and the block start/stop markers around them. Every fragment is superseded by the assistant message that settles it, so a lost one costs a repaint. Exists at all only under includePartialMessages.',
+    },
+    'system/thinking_tokens': {
+        lane: 'delta',
+        note: 'a running thinking-token estimate, emitted per thinking delta. Its own docs call it approximate progress for spinners rather than the billed count, and the next one supersedes it.',
+    },
+    'system/status': {
+        lane: 'delta',
+        note: 'the requesting/compacting ticker. Each value supersedes the last and the transition it causes is the durable record; this lane exists so a view can show the spinner without waiting for one.',
+    },
+    tool_progress: {
+        lane: 'delta',
+        note: 'elapsed seconds for a running tool call, re-emitted while it runs. Superseded by the next tick and finally by the tool closing.',
+    },
+    'system/task_progress': {
+        lane: 'delta',
+        note: 'progress for a background task, re-emitted while it runs. Same shape as tool_progress and superseded the same way.',
+    },
+    'system/hook_progress': {
+        lane: 'delta',
+        note: 'progress while a hook handler runs — a ticker, superseded by the hook resolving.',
+    },
+    // --- update: facts of the turn that nothing later restates -----------------
+    'system/init': {
+        lane: 'update',
+        note: 'the per-spawn receipt — session id, CLI version, model, tool/skill/plugin inventory, apiKeySource. It arrives once and nothing restates it.',
+    },
+    assistant: {
+        lane: 'update',
+        note: 'the settled assistant message. The fact the deltas were fragments of; a consumer with no delta lane still renders a turn from these.',
+    },
+    user: {
+        lane: 'update',
+        note: "tool results — that is what this row carries in practice. Observed on a live session: the queued prompt does not come back on the output stream for this host's input lane, so no SDKUserMessageReplay arrives to deduplicate against. This host still synthesizes no user echo of its own, because the controller queued the prompt and already holds the operator's turn — a synthesized event would be a second name for it.",
+    },
+    result: {
+        lane: 'update',
+        note: "the turn's outcome, and the telemetry that arrives with it: total_cost_usd, modelUsage[].costUSD per model, permission_denials, ttft_ms, user_message_uuid and terminal_reason (19 values). Forwarded whole so the layer that owns cost consumes these rather than re-deriving them.",
+    },
+    rate_limit_event: {
+        lane: 'update',
+        note: 'rate-limit state with resetsAt and utilization, in-stream. Losing one loses a reset time nothing else carries.',
+    },
+    'system/compact_boundary': {
+        lane: 'update',
+        note: 'compaction happened and this is where. A durable fact about the transcript, and the boundary anything reading history has to know about.',
+    },
+    'system/api_retry': {
+        lane: 'update',
+        note: 'a request failed and is being retried. Nothing else carries it, and an unattended run that is quietly retrying looks identical to one that is thinking.',
+    },
+    'system/model_refusal_fallback': {
+        lane: 'update',
+        note: 'the model refused and a fallback ran. The counterpart of model_refusal_no_fallback, which moves the machine; this one does not, so forwarding is the only way the fact travels.',
+    },
+    'system/model_refusal_no_fallback': {
+        lane: 'update',
+        note: 'the model refused and nothing ran. It also causes a transition, but the message names the original model, which the transition does not.',
+    },
+    'system/local_command_output': {
+        lane: 'update',
+        note: 'output of a local command, which is content a consumer renders. Not restated anywhere.',
+    },
+    'system/session_state_changed': {
+        lane: 'declined',
+        note: 'its entire content is state: idle|running|requires_action, and the transition it causes carries exactly that in `to`. Forwarding it too would put two names for one fact on the wire — the reason session_started and session_ended were removed from the payload kinds.',
+    },
+    'system/task_started': {
+        lane: 'update',
+        note: 'the only message carrying task_id AND tool_use_id together — the join a consumer needs to attribute later task reports. The transition lane deliberately records nothing here.',
+    },
+    'system/task_updated': {
+        lane: 'update',
+        note: 'a task changed status or was backgrounded. It causes a transition, and it also carries the patch itself, which the transition does not.',
+    },
+    'system/task_notification': {
+        lane: 'update',
+        note: 'a background task finished and says how. Causes a transition; the message carries the status text.',
+    },
+    'system/background_tasks_changed': {
+        lane: 'update',
+        note: 'the set of background tasks changed. Nothing else enumerates them, and a session whose work moved to the background is the case this whole split exists for.',
+    },
+    'system/worker_shutting_down': {
+        lane: 'update',
+        note: 'the worker is going away, with its reason. Causes a transition; the reason is worth carrying verbatim.',
+    },
+    'system/permission_denied': {
+        lane: 'update',
+        note: "the SDK's own auto-deny short-circuit — a different path from this host's gate, which the SDK's docs say explicitly does not produce this message. Nothing this package emits restates it.",
+    },
+    'system/elicitation_complete': {
+        lane: 'update',
+        note: 'an MCP elicitation resolved, with what it resolved to. The transition records the exit; the answer rides here.',
+    },
+    'system/plugin_install': {
+        lane: 'update',
+        note: 'a plugin was installed mid-session, so the inventory init reported is now stale. Nothing else says so.',
+    },
+    'system/commands_changed': {
+        lane: 'update',
+        note: 'the available command set changed. init carries the opening inventory and this carries the change; a consumer showing commands has no other source.',
+    },
+    'system/notification': {
+        lane: 'update',
+        note: 'a notification aimed at whoever is watching. Withholding it would be this host deciding what a controller finds worth showing.',
+    },
+    'system/memory_recall': {
+        lane: 'update',
+        note: 'what the agent recalled and used. Content, and part of explaining a turn a reader is trying to understand.',
+    },
+    'system/mirror_error': {
+        lane: 'update',
+        note: 'a mirror write failed. A degrade is a named outcome and never a silent pass, so it goes on the wire even though this host takes no action on it.',
+    },
+    'system/informational': {
+        lane: 'update',
+        note: "an informational message from the agent. Forwarded for the same reason as notification: the judgement is the controller's.",
+    },
+    tool_use_summary: {
+        lane: 'update',
+        note: 'a settled summary of a tool call — what a cold reader sees instead of raw arguments.',
+    },
+    auth_status: {
+        lane: 'update',
+        note: 'the credential state changed under a running session. An unattended run whose auth lapsed must not look like one that went quiet.',
+    },
+    prompt_suggestion: {
+        lane: 'update',
+        note: "a suggested next turn. Product surface, and whether to show it is the controller's call rather than this host's.",
+    },
+    conversation_reset: {
+        lane: 'update',
+        note: 'the conversation was reset, so everything a consumer has accumulated for this session is now history rather than context.',
+    },
+    // --- declined: the fact reaches the wire another way, or it is the host's own ---
+    'system/control_request_progress': {
+        lane: 'declined',
+        note: "progress on the SDK's internal control protocol between this host and its own CLI subprocess. It describes the host's transport, not the session, and a controller can do nothing with it.",
+    },
+    'system/hook_started': {
+        lane: 'declined',
+        note: "reports one of this host's own hooks starting. Forwarding it would echo the observer and the gate back at the controller that configured them. The gate's outcomes are recorded as transitions in the machine, and forwardSession's machine subscription carries every recorded transition to the wire whatever caused it — so this message would arrive as a second copy of a fact the transition already states.",
+    },
+    'system/hook_response': {
+        lane: 'declined',
+        note: "the answer this host's own hook just returned. Same echo reason as hook_started — and the decision's transition already rides the wire via the machine subscription, so re-reporting the answer here would invite a consumer to count one decision twice.",
+    },
+    'system/files_persisted': {
+        lane: 'declined',
+        note: 'a checkpointing receipt. It belongs to the layer that owns the receipt read path, which reads local records rather than the live stream.',
+    },
+};
+/** The lane one message rides. Total by construction — every discriminator has a row. */
+export function laneFor(message) {
+    return MESSAGE_ROUTING[discriminatorOf(message)].lane;
+}
+/** Every discriminator on one lane, in declaration order. The subject of the routing pin. */
+export function discriminatorsOn(lane) {
+    return Object.keys(MESSAGE_ROUTING).filter((key) => MESSAGE_ROUTING[key].lane === lane);
+}
+//# sourceMappingURL=stream-routing.js.map

package/dist/control/stream.d.ts

@@ -0,0 +1,43 @@
+import type { HostedSession, Unsubscribe } from '../sessions/session.js';
+import type { SessionObserver } from '../state/observer.js';
+import type { Refusal } from '../core/refusal.js';
+import type { Result } from '../core/result.js';
+import type { SessionPayload } from './frames.js';
+/**
+ * Where frames go. Structural rather than `ControllerLink` so the forwarder can be exercised with
+ * no socket — and so this module pulls no WebSocket dependency into a path that does not need one.
+ */
+export interface FrameSink {
+    send(sessionId: string, payload: SessionPayload): Result<void>;
+}
+export interface ForwardSessionOptions {
+    /**
+     * The frame's routing key: the controller's handle for this session, not the agent's own id.
+     *
+     * See `SessionFrame` in frames.ts for the three ids and why they are not interchangeable. The
+     * short version: a session's first transitions are recorded before the agent has named itself,
+     * and a session that dies in start-up never names itself at all, so keying frames by the agent's
+     * id would make exactly the frames that explain a failure unsendable.
+     */
+    readonly sessionKey: string;
+    readonly session: HostedSession;
+    /** The session's own observer. Already attached to its machine; this does not create one. */
+    readonly observer: SessionObserver;
+    readonly sink: FrameSink;
+    /**
+     * Every refusal the sink returned, and every transition the machine would not record.
+     *
+     * Wired by callers that want to know; a refusal that nobody listens to is still a refusal and is
+     * never a silent success — `send` has already declined by the time this is called.
+     */
+    readonly onRefusal?: (refusal: Refusal) => void;
+}
+/**
+ * Start forwarding. Returns the unsubscribe, which is idempotent.
+ *
+ * The end transition is emitted from the session's own end listener rather than from the message
+ * stream, because a session can end without its stream ending (a start timeout, a stop request)
+ * and a trace whose last row is whatever happened to arrive last is not a trace of an ending.
+ */
+export declare function forwardSession(options: ForwardSessionOptions): Unsubscribe;
+//# sourceMappingURL=stream.d.ts.map

package/dist/control/stream.js

@@ -0,0 +1,64 @@
+import { agentMessageDelta, agentMessageUpdate, stateTransitionUpdate } from './frames.js';
+import { laneFor } from './stream-routing.js';
+/**
+ * Start forwarding. Returns the unsubscribe, which is idempotent.
+ *
+ * The end transition is emitted from the session's own end listener rather than from the message
+ * stream, because a session can end without its stream ending (a start timeout, a stop request)
+ * and a trace whose last row is whatever happened to arrive last is not a trace of an ending.
+ */
+export function forwardSession(options) {
+    const { sessionKey, session, observer, sink } = options;
+    const refused = (refusal) => options.onRefusal?.(refusal);
+    const emit = (payload) => {
+        const sent = sink.send(sessionKey, payload);
+        if (!sent.ok)
+            refused(sent.refusal);
+    };
+    // Every transition this session records, whichever lane produced it. See this file's header.
+    const dropTransitions = observer.machine.onTransition((transition) => emit(stateTransitionUpdate(transition)));
+    /**
+     * A transition the machine refused is not on the wire and never will be, so this is the only
+     * place it can be named. The recorded ones are already gone out through the subscription above,
+     * which is why nothing here emits.
+     */
+    const reportRejected = (recorded) => {
+        for (const result of recorded)
+            if (!result.ok)
+                refused(result.refusal);
+    };
+    const dropMessages = session.onMessage((message) => {
+        // The message first, then what it caused. See this file's header.
+        forwardMessage(message, emit);
+        reportRejected(observer.observeMessage(message));
+    });
+    const dropEnd = session.onEnd((ended) => {
+        reportRejected([observer.ended({ kind: 'process', event: ended.cause, detail: ended.detail })]);
+        dropMessages();
+    });
+    return () => {
+        dropMessages();
+        dropEnd();
+        dropTransitions();
+    };
+}
+/**
+ * One message onto its declared lane, or nowhere.
+ *
+ * A large message is refused, not truncated, and it will happen: a tool result carrying a big
+ * file exceeds the frame limit, `send` declines with `frame-too-large`, and the refusal names the
+ * bulk lane. That is the "commands only, never payloads" rule doing its job rather than a defect,
+ * but a consumer will see a turn whose largest tool result never arrived, so the refusal has to
+ * reach someone. It does, through `onRefusal`.
+ */
+function forwardMessage(message, emit) {
+    const lane = laneFor(message);
+    if (lane === 'declined')
+        return;
+    // Cast rather than copy: the message arrived as JSON and the codec is where bytes and types meet,
+    // so re-validating it here would be a second wire edge. A message that genuinely cannot serialize
+    // is refused by `encode` under its own name and reaches `onRefusal` like any other refusal.
+    const body = message;
+    emit(lane === 'delta' ? agentMessageDelta(body) : agentMessageUpdate(body));
+}
+//# sourceMappingURL=stream.js.map

package/dist/core/async-queue.d.ts

@@ -0,0 +1,26 @@
+/**
+ * A single-consumer async queue: push values in, iterate them out, close when there are no more.
+ *
+ * It exists because a session's input has to be an `AsyncIterable` before the first turn is known —
+ * the agent process is started with a stream it will read from later, and the control surface
+ * (interrupt, model change, permission mode) is only available to a session driven that way. A
+ * plain string prompt would ship a session that cannot be interrupted.
+ *
+ * Pure and generic on purpose: nothing here knows what a message is, so it is testable without a
+ * process and reusable by anything else that needs the same shape.
+ */
+export declare class AsyncQueue<T> implements AsyncIterable<T> {
+    #private;
+    /** Hand a value to the consumer, or hold it until one asks. Ignored after `end()`. */
+    push(item: T): void;
+    /**
+     * No more values. Idempotent, and it releases every waiting consumer rather than leaving them
+     * hanging — an iterator that never returns is indistinguishable from a session that never ends.
+     */
+    end(): void;
+    /** Values pushed but not yet taken. */
+    get depth(): number;
+    get ended(): boolean;
+    [Symbol.asyncIterator](): AsyncIterator<T>;
+}
+//# sourceMappingURL=async-queue.d.ts.map

package/dist/core/async-queue.js

@@ -0,0 +1,63 @@
+/**
+ * A single-consumer async queue: push values in, iterate them out, close when there are no more.
+ *
+ * It exists because a session's input has to be an `AsyncIterable` before the first turn is known —
+ * the agent process is started with a stream it will read from later, and the control surface
+ * (interrupt, model change, permission mode) is only available to a session driven that way. A
+ * plain string prompt would ship a session that cannot be interrupted.
+ *
+ * Pure and generic on purpose: nothing here knows what a message is, so it is testable without a
+ * process and reusable by anything else that needs the same shape.
+ */
+export class AsyncQueue {
+    #items = [];
+    #waiting = [];
+    #ended = false;
+    /** Hand a value to the consumer, or hold it until one asks. Ignored after `end()`. */
+    push(item) {
+        if (this.#ended)
+            return;
+        const waiter = this.#waiting.shift();
+        if (waiter !== undefined) {
+            waiter({ value: item, done: false });
+            return;
+        }
+        this.#items.push(item);
+    }
+    /**
+     * No more values. Idempotent, and it releases every waiting consumer rather than leaving them
+     * hanging — an iterator that never returns is indistinguishable from a session that never ends.
+     */
+    end() {
+        if (this.#ended)
+            return;
+        this.#ended = true;
+        while (this.#waiting.length > 0) {
+            this.#waiting.shift()?.({ value: undefined, done: true });
+        }
+    }
+    /** Values pushed but not yet taken. */
+    get depth() {
+        return this.#items.length;
+    }
+    get ended() {
+        return this.#ended;
+    }
+    [Symbol.asyncIterator]() {
+        return {
+            next: () => {
+                const item = this.#items.shift();
+                if (item !== undefined)
+                    return Promise.resolve({ value: item, done: false });
+                if (this.#ended)
+                    return Promise.resolve({ value: undefined, done: true });
+                return new Promise((resolve) => this.#waiting.push(resolve));
+            },
+            return: () => {
+                this.end();
+                return Promise.resolve({ value: undefined, done: true });
+            },
+        };
+    }
+}
+//# sourceMappingURL=async-queue.js.map

package/dist/core/failure.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Describing a thrown failure so the reader learns the cause, not the wrapper.
+ *
+ * Node's `fetch` throws `TypeError: fetch failed` and puts the reason on `error.cause`; a WebSocket
+ * carries a `code` such as `DEPTH_ZERO_SELF_SIGNED_CERT`. A message that stops at the wrapper reads
+ * "could not be reached" for a controller that answered the TCP dial and refused nothing but its own
+ * certificate. So the nested causes are walked, the innermost code is named, and a certificate refusal
+ * carries the remedy, because it is the failure a local controller meets first.
+ */
+/** Is this failure TLS refusing the peer's certificate? Read off every `code` met on the way down. */
+export declare function isCertificateRefusal(error: unknown): boolean;
+/**
+ * The failure in one line: the innermost message, prefixed by the innermost code when there is one.
+ * `fetch failed` becomes `DEPTH_ZERO_SELF_SIGNED_CERT: self-signed certificate`.
+ */
+export declare function describeFailure(error: unknown): string;
+/**
+ * What to do about a certificate refusal, in the operator's words. Stated once, here, so the pair
+ * verb, the decision transport and the link say the same thing.
+ */
+export declare function certificateRemedy(where: string): string;
+//# sourceMappingURL=failure.d.ts.map

package/dist/core/failure.js

@@ -0,0 +1,53 @@
+/**
+ * Describing a thrown failure so the reader learns the cause, not the wrapper.
+ *
+ * Node's `fetch` throws `TypeError: fetch failed` and puts the reason on `error.cause`; a WebSocket
+ * carries a `code` such as `DEPTH_ZERO_SELF_SIGNED_CERT`. A message that stops at the wrapper reads
+ * "could not be reached" for a controller that answered the TCP dial and refused nothing but its own
+ * certificate. So the nested causes are walked, the innermost code is named, and a certificate refusal
+ * carries the remedy, because it is the failure a local controller meets first.
+ */
+/** The `code` a Node error carries when TLS refused the peer's certificate. */
+const CERTIFICATE_CODES = /CERT|SELF_SIGNED|UNABLE_TO_VERIFY|CERTIFICATE/;
+/** The innermost error under nested `cause` members, and the codes met on the way down. */
+function unwrap(error) {
+    const codes = [];
+    let current = error;
+    for (let depth = 0; depth < 8; depth += 1) {
+        if (typeof current === 'object' &&
+            current !== null &&
+            typeof current.code === 'string') {
+            codes.push(current.code);
+        }
+        const next = typeof current === 'object' && current !== null ? current.cause : undefined;
+        if (next === undefined || next === null)
+            break;
+        current = next;
+    }
+    return { leaf: current, codes };
+}
+/** Is this failure TLS refusing the peer's certificate? Read off every `code` met on the way down. */
+export function isCertificateRefusal(error) {
+    return unwrap(error).codes.some((code) => CERTIFICATE_CODES.test(code));
+}
+/**
+ * The failure in one line: the innermost message, prefixed by the innermost code when there is one.
+ * `fetch failed` becomes `DEPTH_ZERO_SELF_SIGNED_CERT: self-signed certificate`.
+ */
+export function describeFailure(error) {
+    const { leaf, codes } = unwrap(error);
+    const message = leaf instanceof Error ? leaf.message : typeof leaf === 'string' ? leaf : String(leaf);
+    const code = codes.at(-1);
+    return code === undefined || message.includes(code) ? message : `${code}: ${message}`;
+}
+/**
+ * What to do about a certificate refusal, in the operator's words. Stated once, here, so the pair
+ * verb, the decision transport and the link say the same thing.
+ */
+export function certificateRemedy(where) {
+    return (`Node does not trust the certificate ${where} presents. For a controller on a development ` +
+        `certificate, export that certificate as PEM and point Node at it: set NODE_EXTRA_CA_CERTS to the ` +
+        `file's path, then run this command again in a new terminal. Disabling verification ` +
+        `(NODE_TLS_REJECT_UNAUTHORIZED=0) also works and trusts every certificate; prefer the file.`);
+}
+//# sourceMappingURL=failure.js.map

package/dist/core/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The pure core: no `node:` imports, no packages, no I/O.
+ *
+ * Pinned by src/pins/core-purity.test.ts. The point is that anything here runs anywhere — in the
+ * host, in a controller, in a browser — so the contract types can be shared without dragging a
+ * runtime along with them.
+ */
+export type { Refusal, RefusalReason } from './refusal.js';
+export { REFUSAL_REASONS, isRefusalReason, refusal } from './refusal.js';
+export type { Result } from './result.js';
+export { isOk, ok, refuse, valueOr } from './result.js';
+export type { HostNoun, SdkNoun } from './vocab.js';
+export { HOST_NOUNS, SDK_NOUNS, isDeclaredNoun, nounOf } from './vocab.js';
+export { isAbsolutePath, isContainedBy, normalizePath, requireAbsolute } from './paths.js';
+export { MAX_WORKSPACE_ID_LENGTH } from './workspace-id.js';
+export type { Clock, Ticker } from './time.js';
+export { fixedClock, fixedTicker, systemClock, systemTicker } from './time.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/core/index.js

@@ -0,0 +1,7 @@
+export { REFUSAL_REASONS, isRefusalReason, refusal } from './refusal.js';
+export { isOk, ok, refuse, valueOr } from './result.js';
+export { HOST_NOUNS, SDK_NOUNS, isDeclaredNoun, nounOf } from './vocab.js';
+export { isAbsolutePath, isContainedBy, normalizePath, requireAbsolute } from './paths.js';
+export { MAX_WORKSPACE_ID_LENGTH } from './workspace-id.js';
+export { fixedClock, fixedTicker, systemClock, systemTicker } from './time.js';
+//# sourceMappingURL=index.js.map

package/dist/core/keyed-turns.d.ts

@@ -0,0 +1,28 @@
+/**
+ * A per-key serial executor: work submitted under one key runs one piece at a time, in arrival
+ * order; work under different keys interleaves freely.
+ *
+ * It exists because the host's workspace verbs are fire-and-forget concurrent (`#dispatch` never
+ * awaits a handler) while the work they do takes seconds and is mutually destructive on one key:
+ * a `git worktree add` and a `git worktree remove --force` each take many seconds, and the
+ * reachable interleavings are real — a provision landing inside a removal, a removal landing inside
+ * a close's release. Serializing per key closes every one of those windows without making
+ * unrelated workspaces wait on each other.
+ *
+ * Pure and generic on purpose: nothing here knows what a workspace is, so it is testable without
+ * a provider and reusable by anything else that needs the same shape.
+ */
+export declare class KeyedTurns {
+    #private;
+    /**
+     * Run `work` after everything previously submitted under `key` has settled.
+     *
+     * The returned promise carries `work`'s own result or rejection. A rejection does not poison the
+     * key: the next submission runs regardless, because a failed removal must not wedge every future
+     * provision at that key behind an error nobody can clear.
+     */
+    run<T>(key: string, work: () => Promise<T>): Promise<T>;
+    /** Keys with unsettled work — an observability convenience, never a guard. */
+    get depth(): number;
+}
+//# sourceMappingURL=keyed-turns.d.ts.map

package/dist/core/keyed-turns.js

@@ -0,0 +1,44 @@
+/**
+ * A per-key serial executor: work submitted under one key runs one piece at a time, in arrival
+ * order; work under different keys interleaves freely.
+ *
+ * It exists because the host's workspace verbs are fire-and-forget concurrent (`#dispatch` never
+ * awaits a handler) while the work they do takes seconds and is mutually destructive on one key:
+ * a `git worktree add` and a `git worktree remove --force` each take many seconds, and the
+ * reachable interleavings are real — a provision landing inside a removal, a removal landing inside
+ * a close's release. Serializing per key closes every one of those windows without making
+ * unrelated workspaces wait on each other.
+ *
+ * Pure and generic on purpose: nothing here knows what a workspace is, so it is testable without
+ * a provider and reusable by anything else that needs the same shape.
+ */
+export class KeyedTurns {
+    /** The tail of each key's queue — the promise the next submission must wait behind. */
+    #tails = new Map();
+    /**
+     * Run `work` after everything previously submitted under `key` has settled.
+     *
+     * The returned promise carries `work`'s own result or rejection. A rejection does not poison the
+     * key: the next submission runs regardless, because a failed removal must not wedge every future
+     * provision at that key behind an error nobody can clear.
+     */
+    async run(key, work) {
+        const previous = this.#tails.get(key) ?? Promise.resolve();
+        const turn = previous.then(work, work);
+        // The tail entry is removed when this turn settles with nothing queued behind it. The map
+        // identity check is what makes the cleanup safe under concurrent submission: a newer tail
+        // means a later submission queued behind this one, and the entry is now that one's to clean up.
+        const tail = turn.then(() => undefined, () => undefined);
+        this.#tails.set(key, tail);
+        void tail.then(() => {
+            if (this.#tails.get(key) === tail)
+                this.#tails.delete(key);
+        });
+        return turn;
+    }
+    /** Keys with unsettled work — an observability convenience, never a guard. */
+    get depth() {
+        return this.#tails.size;
+    }
+}
+//# sourceMappingURL=keyed-turns.js.map

package/dist/core/paths.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Path handling, written without `node:path` because this module is import-free by contract.
+ *
+ * Absolute always, on the wire and at every boundary — a relative path means "relative to a cwd the
+ * other end cannot see", which is a bug waiting for a second machine.
+ */
+import type { Result } from './result.js';
+/** POSIX `/x`, Windows `C:\x`, or a UNC `\\server\share`. */
+export declare function isAbsolutePath(candidate: string): boolean;
+/**
+ * Separators to `/`, redundant separators collapsed, `.` dropped and `..` resolved textually.
+ *
+ * Textual resolution deliberately does NOT consult the filesystem, so it cannot follow a symlink.
+ * A caller enforcing a real jail must canonicalize through the filesystem first — see
+ * `host/`, which is the only module that can.
+ */
+export declare function normalizePath(input: string): string;
+/** Normalizes, and refuses anything not absolute. The shape every boundary should take. */
+export declare function requireAbsolute(candidate: string): Result<string>;
+/**
+ * Is `candidate` at or beneath `root`? Both are normalized first; the comparison is
+ * segment-wise, so `/a/bc` is NOT inside `/a/b`.
+ */
+export declare function isContainedBy(candidate: string, root: string): boolean;
+//# sourceMappingURL=paths.d.ts.map

package/dist/core/paths.js

@@ -0,0 +1,77 @@
+import { ok, refuse } from './result.js';
+const WINDOWS_DRIVE = /^[A-Za-z]:[\\/]/;
+/** POSIX `/x`, Windows `C:\x`, or a UNC `\\server\share`. */
+export function isAbsolutePath(candidate) {
+    if (candidate.startsWith('/'))
+        return true;
+    if (candidate.startsWith('\\\\'))
+        return true;
+    return WINDOWS_DRIVE.test(candidate);
+}
+/**
+ * Separators to `/`, redundant separators collapsed, `.` dropped and `..` resolved textually.
+ *
+ * Textual resolution deliberately does NOT consult the filesystem, so it cannot follow a symlink.
+ * A caller enforcing a real jail must canonicalize through the filesystem first — see
+ * `host/`, which is the only module that can.
+ */
+export function normalizePath(input) {
+    const isUnc = input.startsWith('\\\\');
+    const unified = input.replace(/\\/g, '/');
+    const hasDrive = WINDOWS_DRIVE.test(input);
+    const rooted = unified.startsWith('/') || hasDrive || isUnc;
+    const segments = [];
+    let prefix = '';
+    let body = unified;
+    if (hasDrive) {
+        prefix = `${unified.slice(0, 2)}/`;
+        body = unified.slice(3);
+    }
+    else if (isUnc) {
+        prefix = '//';
+        body = unified.slice(2);
+    }
+    else if (rooted) {
+        prefix = '/';
+        body = unified.slice(1);
+    }
+    for (const segment of body.split('/')) {
+        if (segment === '' || segment === '.')
+            continue;
+        if (segment === '..') {
+            if (segments.length > 0 && segments[segments.length - 1] !== '..') {
+                segments.pop();
+            }
+            else if (!rooted) {
+                segments.push('..');
+            }
+            // Rooted paths cannot climb above their root; `/..` is `/`.
+            continue;
+        }
+        segments.push(segment);
+    }
+    const joined = segments.join('/');
+    if (prefix === '')
+        return joined === '' ? '.' : joined;
+    return prefix + joined;
+}
+/** Normalizes, and refuses anything not absolute. The shape every boundary should take. */
+export function requireAbsolute(candidate) {
+    if (!isAbsolutePath(candidate)) {
+        return refuse('path-not-absolute', `not an absolute path: ${candidate}`);
+    }
+    return ok(normalizePath(candidate));
+}
+/**
+ * Is `candidate` at or beneath `root`? Both are normalized first; the comparison is
+ * segment-wise, so `/a/bc` is NOT inside `/a/b`.
+ */
+export function isContainedBy(candidate, root) {
+    const normalizedRoot = normalizePath(root);
+    const normalizedCandidate = normalizePath(candidate);
+    if (normalizedCandidate === normalizedRoot)
+        return true;
+    const boundary = normalizedRoot.endsWith('/') ? normalizedRoot : `${normalizedRoot}/`;
+    return normalizedCandidate.startsWith(boundary);
+}
+//# sourceMappingURL=paths.js.map