footprintjs 4.16.0 → 4.17.2

package/dist/types/detach.d.ts

@@ -0,0 +1,59 @@
+/**
+ * footprintjs/detach — Fire-and-forget child flowchart execution.
+ *
+ * A library of scheduling drivers that lets you detach work from the
+ * parent stage's hot path. The parent stage returns immediately; the
+ * child runs on whichever driver you pick (microtask, immediate, plus
+ * setImmediate / setTimeout / sendBeacon / worker-thread in v4.17.1+).
+ *
+ * Two shapes:
+ *
+ *   - `detachAndJoinLater(driver, child, input)` — returns a `DetachHandle`
+ *     you can `wait()` on (Promise) or read `.status` from (sync).
+ *   - `detachAndForget(driver, child, input)` — discards the handle.
+ *     Use for fire-and-forget telemetry where the caller never needs to
+ *     know how the child finished.
+ *
+ * Two entry points:
+ *
+ *   - `scope.$detachAndJoinLater(driver, child, input)` — from inside a
+ *     stage. refIds are minted from the calling stage's runtimeStageId
+ *     for diagnostic correlation.
+ *   - `executor.detachAndJoinLater(driver, child, input)` — from outside
+ *     any chart (consumer code). refIds use the synthetic `__executor__`
+ *     prefix.
+ *
+ * @example
+ * ```typescript
+ * import { microtaskBatchDriver } from 'footprintjs/detach';
+ * import { flowChart, FlowChartExecutor } from 'footprintjs';
+ *
+ * const telemetry = flowChart('telemetry', async (scope) => {
+ *   await fetch('/log', { method: 'POST', body: JSON.stringify(scope.$getArgs()) });
+ * }, 'telemetry').build();
+ *
+ * const main = flowChart('process', async (scope) => {
+ *   scope.result = await heavyWork();
+ *   // Fire telemetry without blocking the parent.
+ *   scope.$detachAndForget(microtaskBatchDriver, telemetry, { event: 'processed' });
+ * }, 'process').build();
+ *
+ * await new FlowChartExecutor(main).run();
+ * ```
+ */
+export type { DetachDriver, DetachHandle, DetachPollResult, DetachWaitResult, DriverCapabilities, } from './lib/detach/types.js';
+export { createImmediateDriver, immediateDriver } from './lib/detach/drivers/immediate.js';
+export { createMicrotaskBatchDriver, microtaskBatchDriver } from './lib/detach/drivers/microtaskBatch.js';
+export type { SendBeaconDriverOptions } from './lib/detach/drivers/sendBeacon.js';
+export { createSendBeaconDriver } from './lib/detach/drivers/sendBeacon.js';
+export { createSetImmediateDriver, setImmediateDriver } from './lib/detach/drivers/setImmediate.js';
+export type { SetTimeoutDriverOptions } from './lib/detach/drivers/setTimeout.js';
+export { createSetTimeoutDriver, setTimeoutDriver } from './lib/detach/drivers/setTimeout.js';
+export type { WorkerThreadDriverOptions } from './lib/detach/drivers/workerThread.js';
+export { createWorkerThreadDriver } from './lib/detach/drivers/workerThread.js';
+export { asImpl, createHandle, HandleImpl } from './lib/detach/handle.js';
+export type { ChildRunner } from './lib/detach/runChild.js';
+export { defaultRunChild } from './lib/detach/runChild.js';
+export { size as detachedCount, ids as listDetachedIds, lookup as lookupDetachedHandle, } from './lib/detach/registry.js';
+export type { FlushOptions, FlushResult } from './lib/detach/flush.js';
+export { flushAllDetached } from './lib/detach/flush.js';

package/dist/types/lib/builder/FlowChartBuilder.d.ts

@@ -146,6 +146,87 @@ export declare class FlowChartBuilder<TOut = any, TScope = any> {
      * ```
      */
     addPausableFunction(name: string, handler: PausableHandler<TScope>, id: string, description?: string): this;
+    /**
+     * Add a stage that fires a child flowchart on the given driver and
+     * DISCARDS the handle. Pure fire-and-forget — useful for telemetry
+     * exports, audit log shipping, cache warm-up.
+     *
+     * @param id Stable id for this stage (also the stageMap key).
+     * @param child The child flowchart to detach.
+     * @param options.driver The driver to schedule on (e.g. `microtaskBatchDriver`).
+     * @param options.inputMapper Maps the parent's scope to the child's input.
+     *   Defaults to passing `undefined`.
+     * @param options.mountName Display name; defaults to `id`.
+     * @param options.description Stage description for narrative + tools.
+     *
+     * @example
+     * ```ts
+     * import { microtaskBatchDriver } from 'footprintjs/detach';
+     *
+     * flowChart('process', processFn, 'process')
+     *   .addDetachAndForget('telemetry', telemetryChart, {
+     *     driver: microtaskBatchDriver,
+     *     inputMapper: (scope) => ({ event: 'processed', orderId: scope.orderId }),
+     *   })
+     *   .addFunction('next', nextFn, 'next')
+     *   .build();
+     * ```
+     */
+    addDetachAndForget(id: string, child: import('./types.js').FlowChart<any, any>, options: {
+        driver: import('../detach/types.js').DetachDriver;
+        inputMapper?: (scope: TScope) => unknown;
+        mountName?: string;
+        description?: string;
+    }): this;
+    /**
+     * Add a stage that fires a child flowchart on the given driver and
+     * delivers the resulting `DetachHandle` to a consumer-supplied
+     * `onHandle` callback. The handle CANNOT be stored in shared state
+     * — `StageContext.setValue` calls `structuredClone` which drops
+     * class prototypes (and therefore the handle's `.wait()` method).
+     *
+     * The callback pattern is the explicit alternative: keep handles in
+     * a closure-local array (or whatever shape suits) and have a
+     * downstream stage `await Promise.all(...)` over them.
+     *
+     * @example
+     * ```ts
+     * import { microtaskBatchDriver } from 'footprintjs/detach';
+     * import type { DetachHandle } from 'footprintjs/detach';
+     *
+     * const handles: DetachHandle[] = [];
+     *
+     * const chart = flowChart('seed', seedFn, 'seed')
+     *   .addDetachAndJoinLater('eval-a', evalChart, {
+     *     driver: microtaskBatchDriver,
+     *     inputMapper: (scope) => scope.configA,
+     *     onHandle: (h) => handles.push(h),
+     *   })
+     *   .addDetachAndJoinLater('eval-b', evalChart, {
+     *     driver: microtaskBatchDriver,
+     *     inputMapper: (scope) => scope.configB,
+     *     onHandle: (h) => handles.push(h),
+     *   })
+     *   .addFunction('join', async (scope) => {
+     *     const settled = await Promise.all(handles.map((h) => h.wait()));
+     *     scope.results = settled;
+     *   }, 'join')
+     *   .build();
+     * ```
+     *
+     * Note: putting `handles` in a module-level closure is fine for
+     * single-run scripts. For server code that runs the same chart
+     * concurrently across requests, allocate a new closure per run
+     * (e.g., wrap chart construction in a factory function) so handles
+     * from different runs don't bleed into each other.
+     */
+    addDetachAndJoinLater(id: string, child: import('./types.js').FlowChart<any, any>, options: {
+        driver: import('../detach/types.js').DetachDriver;
+        onHandle: (handle: import('../detach/types.js').DetachHandle) => void;
+        inputMapper?: (scope: TScope) => unknown;
+        mountName?: string;
+        description?: string;
+    }): this;
     addDeciderFunction(name: string, fn: StageFunction<any, TScope>, id: string, description?: string): DeciderList<TOut, TScope>;
     addSelectorFunction(name: string, fn: StageFunction<any, TScope>, id: string, description?: string): SelectorFnList<TOut, TScope>;
     addListOfFunction(children: SimplifiedParallelSpec<TOut, TScope>[], options?: {

package/dist/types/lib/detach/drivers/immediate.d.ts

@@ -0,0 +1,39 @@
+/**
+ * detach/drivers/immediate.ts — Run detached work synchronously inside `schedule()`.
+ *
+ * Pattern:  Null-object driver for the "no actual deferral" case. Same
+ *           intent as a `setTimeout(fn, 0)` shim that just calls `fn()`
+ *           — keeps the API surface uniform so consumers can swap drivers
+ *           without changing call sites.
+ * Role:     Test fixture + opt-in for consumers who want fire-and-forget
+ *           ergonomics (the handle API) without actually deferring. Useful
+ *           for:
+ *
+ *             - unit tests where deterministic, synchronous completion
+ *               beats microtask gymnastics
+ *             - very small detach payloads where the overhead of a
+ *               microtask roundtrip exceeds the work itself
+ *             - debugging — easier to step through with breakpoints
+ *
+ * Performance:
+ *   - Sync runChild → handle becomes terminal before `schedule()` returns
+ *   - Async runChild → handle marks running sync, terminal at runChild's
+ *     resolution. The `wait()` Promise is the same one consumers use for
+ *     any other driver; behaviour is uniform.
+ *
+ * Caveat — this is NOT a passive-recorder by default:
+ *   When runChild is sync, the parent stage observes the work's side
+ *   effects WITHIN its own slice. That's intentional for the test/debug
+ *   use case but means consumers should NOT use `immediateDriver` for
+ *   long-running work in production hot paths — pick `microtaskBatchDriver`
+ *   for that.
+ */
+import { type ChildRunner } from '../runChild.js';
+import type { DetachDriver } from '../types.js';
+/**
+ * Build an immediate driver wired to a custom child runner. Most
+ * consumers want the default singleton `immediateDriver`.
+ */
+export declare function createImmediateDriver(runChild?: ChildRunner): DetachDriver;
+/** Default singleton — most consumers use this. */
+export declare const immediateDriver: DetachDriver;

package/dist/types/lib/detach/drivers/microtaskBatch.d.ts

@@ -0,0 +1,57 @@
+/**
+ * detach/drivers/microtaskBatch.ts — Batch detached work into ONE microtask.
+ *
+ * Pattern:  Producer-consumer with batched flush. Same shape as
+ *           agentfootprint's `EventDispatcher` flush queue and the React
+ *           reconciler's microtask scheduling — accumulate during the
+ *           current sync slice, drain at the next microtask boundary.
+ * Role:     Default driver for in-process detach. Cheapest scheduling
+ *           primitive on V8/JSC: one `queueMicrotask` per batch
+ *           regardless of how many work items, so the perf budget
+ *           amortizes. Suitable for browser AND node AND edge runtimes
+ *           (queueMicrotask is universal since 2018).
+ *
+ * Lifecycle:
+ *
+ *   schedule(child, input, refId)            ← driver entry
+ *     └─ create handle (queued)
+ *     └─ register in detachRegistry
+ *     └─ push work item onto local queue
+ *     └─ if no microtask scheduled yet → queueMicrotask(flush)
+ *     └─ return handle (sync — passive recorder rule)
+ *
+ *   flush() (microtask)                       ← deferred
+ *     └─ swap out queue (drain races safely)
+ *     └─ for each item: _markRunning, await runChild, _markDone/_markFailed
+ *     └─ unregister handle from detachRegistry
+ *
+ * Why microtask (and not setImmediate / setTimeout):
+ *   - Microtasks run BEFORE returning to the event loop — guarantees
+ *     the work finishes within the current "tick" if the runtime allows
+ *   - Lowest possible deferral cost (~50ns on modern V8)
+ *   - Works in EVERY JS runtime (browser, node, deno, bun, edge)
+ *   - Doesn't require any timer infrastructure → no GC pressure
+ *
+ * Re-entrancy:
+ *   - If `runChild` calls `schedule()` for nested detach, the new item
+ *     lands on the SAME queue. Because `scheduled` flips back to false
+ *     at the start of `flush`, the new item triggers a fresh microtask.
+ *   - Worst-case: O(n) microtasks for n nested levels. Acceptable —
+ *     real-world detach trees are shallow.
+ */
+import { type ChildRunner } from '../runChild.js';
+import type { DetachDriver } from '../types.js';
+/**
+ * Build a microtask-batch driver wired to a custom child runner. Most
+ * consumers want the default singleton `microtaskBatchDriver` instead;
+ * this factory exists for tests and for advanced consumers who want to
+ * inject their own runner (e.g., a runner that wraps the child in a
+ * tracing context).
+ */
+export declare function createMicrotaskBatchDriver(runChild?: ChildRunner): DetachDriver;
+/**
+ * Default singleton. Most consumers import this and pass it to
+ * `executor.detachAndJoinLater(child, input, { driver: microtaskBatchDriver })`
+ * (or rely on it being the executor's default driver, set in T5b).
+ */
+export declare const microtaskBatchDriver: DetachDriver;

package/dist/types/lib/detach/drivers/sendBeacon.d.ts

@@ -0,0 +1,38 @@
+/**
+ * detach/drivers/sendBeacon.ts — Browser-only driver that ships work
+ *                                via `navigator.sendBeacon` so it
+ *                                survives page-unload.
+ *
+ * Pattern:  Strategy / Adapter — translates the consumer's child
+ *           flowchart into a sendBeacon POST. The "child" is expected
+ *           to produce a JSON-serializable payload via its
+ *           `inputMapper`; the URL endpoint is set at driver creation.
+ * Role:     The narrow but high-value driver for analytics / error
+ *           reporting / page-leave telemetry — the one case where
+ *           "fire-and-forget" must really mean "ships even if the
+ *           user closes the tab right after."
+ *
+ * `navigator.sendBeacon` semantics:
+ *   - Browser queues the POST in the OS network stack BEFORE returning
+ *     control. Survives page-unload, navigation, refresh.
+ *   - Limited to ~64 KB per call (per HTML5 spec).
+ *   - Fire-and-forget — no response observable.
+ *
+ * Caveats:
+ *   - Browser-only (`browserSafe: true, survivesUnload: true`).
+ *     `validate()` throws helpfully if `navigator.sendBeacon` isn't a
+ *     function (e.g., when imported in Node).
+ *   - The driver does NOT run the child flowchart through a
+ *     `FlowChartExecutor` — it serializes the input and POSTs. This
+ *     is an intentional simplification: sendBeacon's semantics
+ *     wouldn't survive an executor's async stages anyway.
+ */
+import type { DetachDriver } from '../types.js';
+export interface SendBeaconDriverOptions {
+    /** Endpoint URL — required. e.g., `'https://telemetry.example.com/ingest'`. */
+    readonly url: string;
+    /** Custom serializer. Defaults to `JSON.stringify(input)` with
+     *  `application/json` content type. */
+    readonly serialize?: (input: unknown) => Blob | string | FormData;
+}
+export declare function createSendBeaconDriver(opts: SendBeaconDriverOptions): DetachDriver;

package/dist/types/lib/detach/drivers/setImmediate.d.ts

@@ -0,0 +1,32 @@
+/**
+ * detach/drivers/setImmediate.ts — Defer detached work to a Node.js
+ *                                  `setImmediate` boundary.
+ *
+ * Pattern:  Same producer-consumer batch flush as `microtaskBatch`,
+ *           but the deferral is `setImmediate` instead of
+ *           `queueMicrotask`. Yields control back to the event loop
+ *           BEFORE running — allows pending I/O callbacks to drain
+ *           first, which microtasks would block.
+ * Role:     Node-specific driver for "fire-and-forget after the
+ *           current I/O tick." Use when the parent stage handles
+ *           latency-sensitive work and you don't want detached work
+ *           to compete for the synchronous slice.
+ *
+ * When to pick this over microtaskBatch:
+ *   - You're shipping logs / metrics in a hot HTTP path and don't
+ *     want them blocking the response from being flushed
+ *   - The detached work itself is CPU-heavy enough that running it on
+ *     the same microtask cycle would delay other microtasks
+ *   - You explicitly want "next event-loop tick" semantics — useful
+ *     when interacting with third-party libraries that expect at
+ *     least one I/O tick between schedule and execution
+ *
+ * Capability:
+ *   - `nodeSafe: true` — relies on Node's `setImmediate`, NOT
+ *     available in browsers / Deno / Cloudflare Workers (use
+ *     `setTimeoutDriver` for cross-runtime alternative)
+ */
+import { type ChildRunner } from '../runChild.js';
+import type { DetachDriver } from '../types.js';
+export declare function createSetImmediateDriver(runChild?: ChildRunner): DetachDriver;
+export declare const setImmediateDriver: DetachDriver;

package/dist/types/lib/detach/drivers/setTimeout.d.ts

@@ -0,0 +1,34 @@
+/**
+ * detach/drivers/setTimeout.ts — Defer detached work via `setTimeout(..., delayMs)`.
+ *
+ * Pattern:  Producer-consumer batch flush; deferral mechanism is
+ *           `setTimeout` with a configurable delay (default `0`).
+ * Role:     Cross-runtime "next macrotask" driver. Works in browsers,
+ *           Node.js, Deno, Cloudflare Workers, Bun, etc.
+ *
+ * When to pick this:
+ *   - Consumer wants a SPECIFIC delay (e.g. "ship telemetry in 5
+ *     seconds, batched") — pass `createSetTimeoutDriver({ delayMs: 5000 })`
+ *   - Cross-runtime detach where `setImmediate` isn't available
+ *   - Coalescing high-frequency events into a low-frequency flush
+ *
+ * Caveats:
+ *   - Not for low-latency hot paths — minimum delay is ~4ms in
+ *     browsers per the HTML5 spec, ~1ms in Node. Use
+ *     `microtaskBatchDriver` for sub-ms scheduling.
+ *   - Browser tab freezing / throttling can extend the delay
+ *     significantly. Don't rely on precise timing.
+ */
+import { type ChildRunner } from '../runChild.js';
+import type { DetachDriver } from '../types.js';
+export interface SetTimeoutDriverOptions {
+    /** Milliseconds to wait before flushing the batch. Default 0
+     *  (next macrotask). */
+    readonly delayMs?: number;
+    /** Custom `runChild`. Defaults to spawning a `FlowChartExecutor`. */
+    readonly runChild?: ChildRunner;
+}
+export declare function createSetTimeoutDriver(opts?: SetTimeoutDriverOptions): DetachDriver;
+/** Default singleton — zero-delay (next macrotask). For configurable
+ *  delays, use `createSetTimeoutDriver({ delayMs })`. */
+export declare const setTimeoutDriver: DetachDriver;

package/dist/types/lib/detach/drivers/workerThread.d.ts

@@ -0,0 +1,50 @@
+/**
+ * detach/drivers/workerThread.ts — Run detached work in a Node.js
+ *                                  Worker Thread (or browser Web Worker).
+ *
+ * Pattern:  Adapter — translates the consumer's child flowchart into
+ *           a worker message + lifecycle handoff. The worker is owned
+ *           by the driver instance; restarted on crash.
+ * Role:     CPU-isolation driver — when detached work is genuinely
+ *           expensive (heavy parsing, hashing, image processing) and
+ *           you don't want it blocking the main thread's event loop
+ *           even for a microtask burst.
+ *
+ * Caveats / IMPORTANT v1 limitations:
+ *   - The worker entry point is a CONSUMER-PROVIDED file path / URL —
+ *     this driver does NOT auto-spawn FlowChartExecutor in a worker.
+ *     Workers can't `import('footprintjs')` portably without setup,
+ *     and the worker file's lifecycle differs by runtime
+ *     (Node Worker vs Web Worker vs Bun). Consumer writes the worker
+ *     code; this driver just hands them a uniform `(input, handle)`
+ *     API.
+ *   - The "child flowchart" parameter is IGNORED in v1 (we only ship
+ *     the input). The chart shape doesn't survive structuredClone +
+ *     postMessage anyway. v2 may add a serialization protocol.
+ *
+ * Two ways to consume:
+ *
+ *   1. Node.js: pass a file path
+ *      `createWorkerThreadDriver({ workerScript: '/path/to/worker.js' })`
+ *
+ *   2. Browser: pass a URL or pre-built Worker instance
+ *      `createWorkerThreadDriver({ worker: new Worker(url) })`
+ */
+import type { DetachDriver } from '../types.js';
+interface WorkerLike {
+    postMessage(message: unknown, transfer?: Transferable[]): void;
+    terminate?(): unknown;
+    on?(event: string, listener: (msg: unknown) => void): void;
+    addEventListener?(event: string, listener: (msg: unknown) => void): void;
+}
+export interface WorkerThreadDriverOptions {
+    /** Pre-constructed Worker instance. Pass either this OR
+     *  `workerScript` — not both. */
+    readonly worker?: WorkerLike;
+    /** Path / URL to the worker script. Used only when `worker` is
+     *  not provided; the driver constructs a Worker from this on demand
+     *  (Node `worker_threads` API). */
+    readonly workerScript?: string;
+}
+export declare function createWorkerThreadDriver(opts: WorkerThreadDriverOptions): DetachDriver;
+export {};

package/dist/types/lib/detach/flush.d.ts

@@ -0,0 +1,62 @@
+/**
+ * detach/flush.ts — Drain every in-flight detached handle to terminal.
+ *
+ * Pattern:  Drain-loop with deadline. Same shape as a graceful HTTP
+ *           server shutdown: snapshot the queue, await everything in
+ *           flight, repeat until empty or deadline.
+ * Role:     Graceful-shutdown hook for consumers who launched
+ *           fire-and-forget work and want to make sure it actually
+ *           flushed before exiting (server stop, test cleanup, etc.).
+ *
+ * Why iterate (not single Promise.all over a snapshot):
+ *   - A child stage can itself call `detachAndForget` while running —
+ *     new handles arrive WHILE we're flushing. A single snapshot would
+ *     miss them. Looping until `size() === 0` drains transitively.
+ *
+ * Why dedupe via `seen` Set:
+ *   - Handles already terminal (but not yet `unregister`ed by their
+ *     driver's finally-block) can re-appear in subsequent snapshots.
+ *     Without dedupe, the `done` counter would double-count them.
+ *
+ * Why `Promise.allSettled` (not `Promise.all`):
+ *   - One handle's rejection must NOT abort the rest. A failed child
+ *     is normal (it's why `wait()` rejects); we still want to drain
+ *     the siblings.
+ */
+export interface FlushResult {
+    /** Handles whose `wait()` we EXPLICITLY awaited and saw fulfilled.
+     *  Best-effort count — a child that completes inside another's
+     *  `wait()` may finish (and unregister) before we get a chance to
+     *  await it directly. The DRAIN is still guaranteed (registry empty
+     *  on return); only the COUNT is approximate. */
+    readonly done: number;
+    /** Handles whose `wait()` rejected. Same best-effort semantics. */
+    readonly failed: number;
+    /** Handles still in-flight when the deadline expired. `0` indicates
+     *  a successful (complete) drain — registry was empty on return. */
+    readonly pending: number;
+}
+export interface FlushOptions {
+    /** Max wall-clock to spend draining, in milliseconds. Default 30s. */
+    readonly timeoutMs?: number;
+}
+/**
+ * Wait for every in-flight detached handle to reach a terminal state.
+ * Returns counts for diagnostics. PROCESS-WIDE — drains every driver
+ * across every executor. For per-executor scoping, consumers should
+ * collect their own handles from `executor.detachAndJoinLater(...)`
+ * calls and await `Promise.allSettled([...].map(h => h.wait()))`
+ * themselves.
+ *
+ * @example Graceful server shutdown
+ * ```typescript
+ * import { flushAllDetached } from 'footprintjs/detach';
+ *
+ * process.on('SIGTERM', async () => {
+ *   const stats = await flushAllDetached({ timeoutMs: 10_000 });
+ *   console.log(`Drained ${stats.done} done, ${stats.failed} failed, ${stats.pending} pending.`);
+ *   process.exit(stats.pending === 0 ? 0 : 1);
+ * });
+ * ```
+ */
+export declare function flushAllDetached(opts?: FlushOptions): Promise<FlushResult>;

package/dist/types/lib/detach/handle.d.ts

@@ -0,0 +1,83 @@
+/**
+ * detach/handle.ts — DetachHandle implementation.
+ *
+ * Pattern:  Object-as-state-machine. Mutable status field; transitions
+ *           are one-way and irreversible (queued → running → done/failed).
+ * Role:     Backs the consumer-facing `DetachHandle` interface. The
+ *           public surface is the interface (defined in `types.ts`);
+ *           this class is the runtime impl.
+ *
+ * Internal vs public split:
+ *   - PUBLIC (in `types.ts`)   — read-only properties + `wait()`
+ *   - INTERNAL (this file)     — `_markRunning` / `_markDone` /
+ *                                `_markFailed` mutators called by drivers
+ *
+ * The class implements `DetachHandle` (which has only readonly fields
+ * exposed). Drivers cast to `HandleImpl` via the `asImpl()` helper to
+ * call the mutators — a controlled escape from readonly. Consumers
+ * cannot do this (they only see the interface).
+ *
+ * Promise caching contract:
+ *   - First `wait()` call:
+ *       - if status terminal → returns IMMEDIATELY-resolved Promise
+ *       - if not terminal    → returns NEW Promise; resolvers stored
+ *                              for use by `_markDone` / `_markFailed`
+ *   - Subsequent `wait()` calls → returns the SAME cached Promise
+ *   - The resolved/rejected value is the SAME on every call (no
+ *     re-running, no duplicated work)
+ *
+ * Concurrency notes:
+ *   - All transitions are sync. JavaScript is single-threaded so no
+ *     atomics or locks needed.
+ *   - State transitions out of terminal states are forbidden — calling
+ *     `_markDone` after `_markFailed` (or vice-versa) is a no-op
+ *     (defensive: prevents driver bugs from corrupting state).
+ */
+import type { DetachHandle, DetachWaitResult } from './types.js';
+/**
+ * Internal handle implementation. Drivers call the `_mark*` methods
+ * to drive state transitions; consumers see only the readonly
+ * `DetachHandle` interface.
+ */
+export declare class HandleImpl implements DetachHandle {
+    readonly id: string;
+    status: DetachHandle['status'];
+    result: unknown;
+    error: Error | undefined;
+    private waitPromise;
+    private resolveWait;
+    private rejectWait;
+    constructor(id: string);
+    /**
+     * Public — opt-in async join. Returns a cached Promise.
+     * See `DetachHandle.wait()` docstring for contract.
+     */
+    wait(): Promise<DetachWaitResult>;
+    /** Transition queued → running. No-op if already past 'queued'. */
+    _markRunning(): void;
+    /**
+     * Transition to terminal 'done' with the given result. No-op if
+     * already terminal (defensive: prevents driver bugs from corrupting
+     * state).
+     */
+    _markDone(result: unknown): void;
+    /**
+     * Transition to terminal 'failed' with the given error. No-op if
+     * already terminal.
+     */
+    _markFailed(error: Error): void;
+}
+/**
+ * Type-narrowing helper — cast a public `DetachHandle` to its
+ * implementation. Drivers (only) use this to call internal mutators.
+ *
+ * Throws if the handle isn't actually a `HandleImpl` — defends
+ * against consumers passing a hand-rolled object that satisfies the
+ * interface shape but lacks the mutators.
+ */
+export declare function asImpl(handle: DetachHandle): HandleImpl;
+/**
+ * Driver-facing factory. Drivers MUST use this to create handles
+ * (NOT construct `HandleImpl` directly — keeps the impl type private).
+ */
+export declare function createHandle(id: string): DetachHandle;

package/dist/types/lib/detach/registry.d.ts

@@ -0,0 +1,82 @@
+/**
+ * detach/registry.ts — Process-singleton handle registry.
+ *
+ * Pattern:  Registry (GoF). Same shape as the cache strategy registry
+ *           in agentfootprint v2.6 — a Map keyed by stable string id.
+ * Role:     Glue between drivers and executors. When a driver schedules
+ *           work it `register`s the handle here; later (during executor
+ *           disposal, or for diagnostics) consumers `lookup` by refId.
+ *
+ * Why a singleton?
+ *   - refIds are minted per detach call and are unique across the
+ *     process lifetime (driver name + monotonic counter)
+ *   - handles need to be cleanable from MULTIPLE call sites (executor
+ *     disposal, driver-internal flush, test cleanup) without each one
+ *     having to thread a Registry instance through ten layers
+ *   - one-source-of-truth simplifies "is this handle still alive?"
+ *     queries during debugging
+ *
+ * Why NOT a class instance per executor?
+ *   - drivers (e.g., `microtaskBatchDriver`) are PROCESS-wide (one queue
+ *     per driver, shared by every executor). Tying registry to executor
+ *     would force per-executor driver instances, multiplying the queue
+ *     count and breaking the batch-amortization the drivers exist for.
+ *
+ * Cleanup contract:
+ *   - Drivers call `register(handle)` synchronously inside `schedule()`
+ *   - Drivers (or executor disposal) call `unregister(refId)` once the
+ *     handle is terminal AND the consumer has had a chance to observe it
+ *   - `_resetForTests()` clears every entry — tests only
+ *
+ * Capacity:
+ *   - No upper bound. The handle objects are tiny (~6 fields). A long-
+ *     running process that detaches a million units WITHOUT cleanup
+ *     would leak ~50 MB — acceptable for v1, since drivers ARE the
+ *     cleanup site. If real-world programs hit the limit, add a
+ *     sliding-window cap with telemetry hook (mirrors
+ *     `LIVE_STATUS_LOG_CAP` in agentfootprint).
+ */
+import type { DetachHandle } from './types.js';
+/**
+ * Register a freshly-minted handle. Drivers MUST call this synchronously
+ * inside `schedule()` so the handle is observable from the moment it
+ * exists.
+ *
+ * Replacing an existing registration is treated as a programming error
+ * (refIds are supposed to be unique). We don't throw — silent overwrite
+ * could mask a bug, but throwing inside a driver's hot path could cascade
+ * into the parent stage. Compromise: warn in dev mode, overwrite always.
+ */
+export declare function register(handle: DetachHandle): void;
+/**
+ * Look up a handle by refId. Returns `undefined` for unknown ids — the
+ * caller decides whether that's an error or just a stale reference.
+ *
+ * Used by:
+ *   - Executor disposal (find handles to mark cancelled / drain)
+ *   - Driver-internal flush (correlate work-queue entries → handles)
+ *   - Diagnostic tooling (dump handle state for a refId in a log line)
+ */
+export declare function lookup(refId: string): DetachHandle | undefined;
+/**
+ * Drop a handle from the registry. Idempotent — calling on an already-
+ * removed refId is a no-op (matches `Map.delete` semantics; useful when
+ * cleanup may race between executor disposal and the driver's own
+ * post-terminal cleanup).
+ */
+export declare function unregister(refId: string): void;
+/**
+ * Diagnostic — total live handles. Use sparingly; calling this on hot
+ * paths defeats the registry's "cheap insert/lookup" goal.
+ */
+export declare function size(): number;
+/**
+ * Diagnostic — every live refId. Use for "what's still in flight?"
+ * dumps during executor disposal or oncall debugging.
+ */
+export declare function ids(): readonly string[];
+/**
+ * Test-only — wipe every entry. NEVER call from production code; that
+ * would orphan in-flight work without a chance to drain.
+ */
+export declare function _resetForTests(): void;