@electron-stagewright/host-supervisor 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Electron Stagewright contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,144 @@
-# Temporary Holding Version
+# @electron-stagewright/host-supervisor
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Runs one stateful host (a database, a native engine, an embedded server) off the Electron main
+thread, behind a closed list of operations, and supervises its life: lazy start, drain on stop,
+per-call timeout and `AbortSignal`, a limit on pending calls, waiting for a killed host to exit
+before the next one starts, and a choice between fatal and bounded restart when it dies.
+
+## Worker thread or utility process
+
+Choose this first. A native crash (a segfault or abort in a `.node` addon) in a worker thread ends
+the **whole app**; in a `utilityProcess` it ends only the host.
+
+|                                   | `worker_threads` (`./worker`) | `utilityProcess` (`./utility`)        |
+| --------------------------------- | ----------------------------- | ------------------------------------- |
+| Native crash in the host          | Ends the app                  | Ends the host; the supervisor decides |
+| JavaScript exception, heap limit  | Ends the host                 | Ends the host                         |
+| Start to first answer             | 19 ms                         | 59 ms                                 |
+| Call round trip                   | 24 µs                         | 37 µs                                 |
+| Memory                            | Counted in the main process   | Its own process, 67 MB working set    |
+| Runs without Electron (tests, CI) | Yes                           | No                                    |
+
+Start, round trip and memory: medians of 7 rounds on one Apple M4 Max, Electron 42.11.10, with a
+host that loads nothing. They are indicative only. In one app that moved an embedded server off the
+main thread, the worker added about 21 MB and left 0.7 % of the main thread blocked under load;
+a utility process added 46 MB and 3.6 %.
+
+Use a worker when the host runs JavaScript or native code you trust not to crash. Use a utility
+process when it loads a native engine (DuckDB, a driver, a codec) whose crash must not take the
+window with it.
+
+## Use
+
+The contract is an interface shared by both sides:
+
+```ts
+export interface DbOps {
+  query(sql: string): Promise<unknown[]>
+  rows(sql: string): AsyncIterable<unknown[]>
+}
+```
+
+In the main process:
+
+```ts
+import { fileURLToPath } from 'node:url'
+
+import { createHost, restartPolicy } from '@electron-stagewright/host-supervisor'
+import { utilityProcessTransport } from '@electron-stagewright/host-supervisor/utility'
+
+const host = createHost<DbOps, { key: string }>({
+  operations: ['query'],
+  streams: ['rows'],
+  transport: utilityProcessTransport({
+    entry: fileURLToPath(new URL('./db-host.js', import.meta.url)),
+    serviceName: 'Database',
+  }),
+  start: { payload: () => ({ key: readKey() }) },
+  stop: { graceMs: 30_000, retireWaitMs: 5_000 },
+  limits: { maxPending: 64, callTimeoutMs: 30_000 },
+  onExit: restartPolicy({
+    isFatal: (exit) => (exit.error as { code?: string }).code === 'SQLITE_CORRUPT',
+  }),
+})
+
+await host.ops.query('select 1')
+await host.call('query', ['select 2'], { signal })
+for await (const chunk of host.ops.rows('select * from big')) render(chunk)
+await host.close()
+```
+
+In the host entry (`db-host.js`):
+
+```ts
+import { serveHost } from '@electron-stagewright/host-supervisor'
+
+let db: Db | null = null
+serveHost<DbOps, { key: string }>({
+  operations: ['query'],
+  streams: ['rows'],
+  start: async ({ key }) => {
+    db = await open(key)
+    return {
+      query: (sql, { signal }) => db!.all(sql, { signal }),
+      rows: (sql) => db!.iterate(sql),
+    }
+  },
+  stop: () => db?.close(),
+})
+```
+
+`serveHost` finds its port: Electron's `process.parentPort` in a utility process, the
+`worker_threads` parent port in a worker. The entry never imports Electron.
+
+## Behaviour
+
+- **Start.** The host starts on the first call, or on `host.start()`. The payload is the first
+  message; keep secrets there, not in env or argv. The utility transport passes
+  `minimalEnvironment(process.env)` unless you pass `env`.
+- **Calls.** Each call has `limits.callTimeoutMs` (or `timeoutMs`) and an optional `signal`. A
+  timeout or an abort rejects the call and aborts `context.signal` in the handler, which receives
+  it after the caller's arguments. Past `maxPending` calls and open streams, a call fails with
+  `HOST_QUEUE_FULL`.
+- **Streams.** One item per pull; nothing is produced ahead. Leaving a `for await` early closes the
+  producer in the host.
+- **Exits.** A call in flight when the host exits fails with `HOST_EXITED`; its `cause` is the
+  host's uncaught error when the host could report it. It is never resent. `onExit` then returns
+  `fatal` (the default), `on-demand` or `restart`. `restartPolicy()` restarts up to 3 times in 10
+  minutes with 0.5, 2 and 8 s of backoff, and a restart whose start fails counts.
+- **Stop.** `stop()` refuses new calls, lets accepted ones answer, runs the host's `stop`, and
+  terminates the host after `graceMs`. It rejects with `HOST_STOP_TIMEOUT` or
+  `HOST_STOP_INCOMPLETE` when the host did not close cleanly, so code that is about to touch its
+  files can stop. `kill()` terminates without draining. `close()` stops and refuses every later
+  call. After `stop()` or `kill()` the next call starts a new host, once the old one has exited or
+  `retireWaitMs` has passed.
+- **Memory.** Worker `resourceLimits` usually end only the worker, reported as `out-of-memory`;
+  one allocation far past the cap can still abort the whole process, so use `utilityProcess` when
+  the app must survive its host. A `utilityProcess` that runs out of heap is reported as a
+  `crash`: Electron gives no out-of-memory signal. Native memory sits outside any heap cap: pass
+  `statsIntervalMs` to `serveHost`, and `memoryWatch({ rssMb, onAlert })` as `onStats`. A worker
+  shares the process, so its `rssMb` is the whole app's. `heapLimitMb` is V8's limit, which adds
+  the young generation to `maxOldGenerationSizeMb`. An `onStats` that throws or rejects becomes a
+  process warning.
+
+Errors keep their message and a code matching `^[A-Z][A-Z0-9_]{1,80}$`; stacks and object graphs
+never cross. The supervisor's own failures are `HostError` with a code from `HOST_ERROR_CODES`.
+
+## Platform notes
+
+- `terminate()` cannot interrupt a synchronous native call: the grace period is honoured between
+  calls, not inside one.
+- Large results should stream. `postMessage` copies by structured clone, and Electron's V8 memory
+  cage rules out external ArrayBuffers, so a native addon must copy into V8 memory anyway.
+- Windows has no POSIX signals; a kill is abrupt and a file can stay locked until the process is
+  gone. That is what `retireWaitMs` waits for.
+- The package ships no binaries. Unpack each `.node` from the asar, sign every `.node` and `.dylib`
+  (the macOS hardened runtime refuses unsigned libraries), and load them in a packaged smoke test.
+- On Linux a utility process inherits the app's sandbox settings; test it packaged, not only with
+  `--no-sandbox`.
+
+Design record: [ADR-032](../../docs/adr/032-host-supervisor-library.md).
+
+## License
+
+MIT

package/dist/contract.d.ts

@@ -0,0 +1,50 @@
+import type { SupervisorMessage } from './protocol.js';
+/** What a handler receives after the caller's arguments. */
+export interface CallContext {
+    /** Aborted when the caller aborts, the call times out, or the stream is closed early. */
+    readonly signal: AbortSignal;
+}
+type FixedArity<A extends readonly unknown[]> = number extends A['length'] ? false : A extends Required<A> ? true : false;
+/**
+ * Every member is an operation that returns a promise or an async iterable. Parameters are fixed:
+ * the handler's context follows the caller's arguments, so optional and rest parameters would
+ * shift it. Declare an optional value as `T | undefined` instead.
+ */
+export type Contract<Ops> = {
+    [K in keyof Ops]: Ops[K] extends (...args: infer A) => infer R ? FixedArity<A> extends true ? R extends Promise<unknown> | AsyncIterable<unknown> ? Ops[K] : (...args: never[]) => Promise<unknown> | AsyncIterable<unknown> : (...args: never[]) => 'optional and rest parameters are not supported' : never;
+};
+export type ArgsOf<F> = F extends (...args: infer A) => unknown ? A : never;
+/** Operations that answer once. */
+export type CallOperation<Ops> = {
+    [K in keyof Ops]: Ops[K] extends (...args: never[]) => Promise<unknown> ? K : never;
+}[keyof Ops] & string;
+/** Operations that answer with a stream, pulled one item at a time. */
+export type StreamOperation<Ops> = {
+    [K in keyof Ops]: Ops[K] extends (...args: never[]) => AsyncIterable<unknown> ? K : never;
+}[keyof Ops] & string;
+/** The host-side implementation of a contract: same arguments, plus the call context. */
+export type Handlers<Ops> = {
+    [K in keyof Ops]: Ops[K] extends (...args: infer A) => Promise<infer R> ? (...args: [...A, CallContext]) => R | Promise<R> : Ops[K] extends (...args: infer A) => AsyncIterable<infer T> ? (...args: [...A, CallContext]) => AsyncIterable<T> | Iterable<T> : never;
+};
+/** How a channel ended, as the transport saw it. */
+export interface ChannelExit {
+    readonly code: number | null;
+    readonly error?: Error;
+    /** The runtime ended the host for exceeding its memory limit. */
+    readonly outOfMemory?: boolean;
+}
+/** One running host, as seen from the supervisor. */
+export interface HostChannel {
+    send(message: SupervisorMessage): void;
+    onMessage(listener: (message: unknown) => void): void;
+    /** Called once, when the thread or process has exited. */
+    onExit(listener: (exit: ChannelExit) => void): void;
+    /** Ends the host without waiting for it; `onExit` still fires. */
+    kill(): void;
+}
+/** Starts hosts. A worker thread, a utility process, or anything that speaks the protocol. */
+export interface HostTransport {
+    launch(): HostChannel;
+}
+export {};
+//# sourceMappingURL=contract.d.ts.map

package/dist/contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AAEtD,4DAA4D;AAC5D,MAAM,WAAW,WAAW;IAC1B,yFAAyF;IACzF,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;CAC7B;AAED,KAAK,UAAU,CAAC,CAAC,SAAS,SAAS,OAAO,EAAE,IAAI,MAAM,SAAS,CAAC,CAAC,QAAQ,CAAC,GACtE,KAAK,GACL,CAAC,SAAS,QAAQ,CAAC,CAAC,CAAC,GACnB,IAAI,GACJ,KAAK,CAAA;AAEX;;;;GAIG;AACH,MAAM,MAAM,QAAQ,CAAC,GAAG,IAAI;KACzB,CAAC,IAAI,MAAM,GAAG,GAAG,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,MAAM,CAAC,KAAK,MAAM,CAAC,GAC1D,UAAU,CAAC,CAAC,CAAC,SAAS,IAAI,GACxB,CAAC,SAAS,OAAO,CAAC,OAAO,CAAC,GAAG,aAAa,CAAC,OAAO,CAAC,GACjD,GAAG,CAAC,CAAC,CAAC,GACN,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,aAAa,CAAC,OAAO,CAAC,GACjE,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,gDAAgD,GACxE,KAAK;CACV,CAAA;AAED,MAAM,MAAM,MAAM,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,MAAM,CAAC,KAAK,OAAO,GAAG,CAAC,GAAG,KAAK,CAAA;AAE3E,mCAAmC;AACnC,MAAM,MAAM,aAAa,CAAC,GAAG,IAAI;KAC9B,CAAC,IAAI,MAAM,GAAG,GAAG,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,KAAK;CACpF,CAAC,MAAM,GAAG,CAAC,GACV,MAAM,CAAA;AAER,uEAAuE;AACvE,MAAM,MAAM,eAAe,CAAC,GAAG,IAAI;KAChC,CAAC,IAAI,MAAM,GAAG,GAAG,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,aAAa,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,KAAK;CAC1F,CAAC,MAAM,GAAG,CAAC,GACV,MAAM,CAAA;AAER,yFAAyF;AACzF,MAAM,MAAM,QAAQ,CAAC,GAAG,IAAI;KACzB,CAAC,IAAI,MAAM,GAAG,GAAG,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,MAAM,CAAC,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC,GACnE,CAAC,GAAG,IAAI,EAAE,CAAC,GAAG,CAAC,EAAE,WAAW,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAChD,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,MAAM,CAAC,KAAK,aAAa,CAAC,MAAM,CAAC,CAAC,GACzD,CAAC,GAAG,IAAI,EAAE,CAAC,GAAG,CAAC,EAAE,WAAW,CAAC,KAAK,aAAa,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,GAChE,KAAK;CACZ,CAAA;AAED,oDAAoD;AACpD,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAA;IACtB,iEAAiE;IACjE,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAA;CAC/B;AAED,qDAAqD;AACrD,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,OAAO,EAAE,iBAAiB,GAAG,IAAI,CAAA;IACtC,SAAS,CAAC,QAAQ,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,GAAG,IAAI,CAAA;IACrD,0DAA0D;IAC1D,MAAM,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,IAAI,GAAG,IAAI,CAAA;IACnD,kEAAkE;IAClE,IAAI,IAAI,IAAI,CAAA;CACb;AAED,8FAA8F;AAC9F,MAAM,WAAW,aAAa;IAC5B,MAAM,IAAI,WAAW,CAAA;CACtB"}

package/dist/contract.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=contract.js.map

package/dist/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":""}

package/dist/env.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Only what a runtime needs to start. Secrets go in the start payload, never in env or argv.
+ * `home` replaces HOME and USERPROFILE, so a library's `~/.config` defaults stay in the app's folder.
+ */
+export declare function minimalEnvironment(env: NodeJS.ProcessEnv, options?: {
+    readonly home?: string;
+    readonly passThrough?: readonly string[];
+}): Record<string, string>;
+//# sourceMappingURL=env.d.ts.map

package/dist/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAaA;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,MAAM,CAAC,UAAU,EACtB,OAAO,GAAE;IAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAO,GACjF,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAWxB"}

package/dist/env.js

@@ -0,0 +1,30 @@
+const PASSED_THROUGH = [
+    'PATH',
+    'TMPDIR',
+    'TMP',
+    'TEMP',
+    'LANG',
+    'LC_ALL',
+    'LC_CTYPE',
+    'TZ',
+    'SystemRoot',
+    'windir',
+];
+/**
+ * Only what a runtime needs to start. Secrets go in the start payload, never in env or argv.
+ * `home` replaces HOME and USERPROFILE, so a library's `~/.config` defaults stay in the app's folder.
+ */
+export function minimalEnvironment(env, options = {}) {
+    const out = {};
+    for (const name of [...PASSED_THROUGH, ...(options.passThrough ?? [])]) {
+        const value = env[name];
+        if (value !== undefined)
+            out[name] = value;
+    }
+    if (options.home !== undefined) {
+        out['HOME'] = options.home;
+        out['USERPROFILE'] = options.home;
+    }
+    return out;
+}
+//# sourceMappingURL=env.js.map

package/dist/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAAA,MAAM,cAAc,GAAG;IACrB,MAAM;IACN,QAAQ;IACR,KAAK;IACL,MAAM;IACN,MAAM;IACN,QAAQ;IACR,UAAU;IACV,IAAI;IACJ,YAAY;IACZ,QAAQ;CACA,CAAA;AAEV;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAChC,GAAsB,EACtB,UAAgF,EAAE;IAElF,MAAM,GAAG,GAA2B,EAAE,CAAA;IACtC,KAAK,MAAM,IAAI,IAAI,CAAC,GAAG,cAAc,EAAE,GAAG,CAAC,OAAO,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;QACvE,MAAM,KAAK,GAAG,GAAG,CAAC,IAAI,CAAC,CAAA;QACvB,IAAI,KAAK,KAAK,SAAS;YAAE,GAAG,CAAC,IAAI,CAAC,GAAG,KAAK,CAAA;IAC5C,CAAC;IACD,IAAI,OAAO,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC/B,GAAG,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,IAAI,CAAA;QAC1B,GAAG,CAAC,aAAa,CAAC,GAAG,OAAO,CAAC,IAAI,CAAA;IACnC,CAAC;IACD,OAAO,GAAG,CAAA;AACZ,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,11 @@
+/** The supervisor's own failures. Application errors keep their own code when it is well formed. */
+export declare const HOST_ERROR_CODES: readonly ["HOST_STOPPED", "HOST_EXITED", "HOST_START_FAILED", "HOST_FATAL", "HOST_CALL_TIMEOUT", "HOST_CALL_ABORTED", "HOST_QUEUE_FULL", "HOST_OPERATION_REJECTED", "HOST_STOP_TIMEOUT", "HOST_STOP_INCOMPLETE"];
+export type HostErrorCode = (typeof HOST_ERROR_CODES)[number];
+export declare class HostError extends Error {
+    readonly code: HostErrorCode;
+    constructor(code: HostErrorCode, message: string, options?: {
+        cause?: unknown;
+    });
+}
+export declare function isHostError(error: unknown, code?: HostErrorCode): error is HostError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,oGAAoG;AACpG,eAAO,MAAM,gBAAgB,kNAmBnB,CAAA;AAEV,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAA;AAE7D,qBAAa,SAAU,SAAQ,KAAK;IAClC,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAA;gBAEhB,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAKhF;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,aAAa,GAAG,KAAK,IAAI,SAAS,CAEpF"}

package/dist/errors.js

@@ -0,0 +1,33 @@
+/** The supervisor's own failures. Application errors keep their own code when it is well formed. */
+export const HOST_ERROR_CODES = [
+    /** `close()` was called, or the call was still waiting when the host stopped. */
+    'HOST_STOPPED',
+    /** The host exited while the call was in flight. Calls are never resent. */
+    'HOST_EXITED',
+    /** The host failed to start, or answered `start` with a failure. */
+    'HOST_START_FAILED',
+    /** `onExit` chose `fatal`; the host never starts again. */
+    'HOST_FATAL',
+    'HOST_CALL_TIMEOUT',
+    'HOST_CALL_ABORTED',
+    /** More than `maxPending` calls were waiting. */
+    'HOST_QUEUE_FULL',
+    /** The host refused an operation outside its closed list. */
+    'HOST_OPERATION_REJECTED',
+    /** The host did not finish closing within the grace period and was terminated. */
+    'HOST_STOP_TIMEOUT',
+    /** The host exited during `stop` without confirming that its cleanup finished. */
+    'HOST_STOP_INCOMPLETE',
+];
+export class HostError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.name = 'HostError';
+        this.code = code;
+    }
+}
+export function isHostError(error, code) {
+    return error instanceof HostError && (code === undefined || error.code === code);
+}
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,oGAAoG;AACpG,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,iFAAiF;IACjF,cAAc;IACd,4EAA4E;IAC5E,aAAa;IACb,oEAAoE;IACpE,mBAAmB;IACnB,2DAA2D;IAC3D,YAAY;IACZ,mBAAmB;IACnB,mBAAmB;IACnB,iDAAiD;IACjD,iBAAiB;IACjB,6DAA6D;IAC7D,yBAAyB;IACzB,kFAAkF;IAClF,mBAAmB;IACnB,kFAAkF;IAClF,sBAAsB;CACd,CAAA;AAIV,MAAM,OAAO,SAAU,SAAQ,KAAK;IACzB,IAAI,CAAe;IAE5B,YAAY,IAAmB,EAAE,OAAe,EAAE,OAA6B;QAC7E,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;QACvB,IAAI,CAAC,IAAI,GAAG,WAAW,CAAA;QACvB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;IAClB,CAAC;CACF;AAED,MAAM,UAAU,WAAW,CAAC,KAAc,EAAE,IAAoB;IAC9D,OAAO,KAAK,YAAY,SAAS,IAAI,CAAC,IAAI,KAAK,SAAS,IAAI,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,CAAA;AAClF,CAAC"}

package/dist/host.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Supervisor side: starts the host on demand, matches answers to calls, and decides what happens
+ * when the host exits on its own.
+ */
+import type { ArgsOf, CallOperation, Contract, HostTransport, StreamOperation } from './contract.js';
+import { type HostStats } from './protocol.js';
+export declare const DEFAULT_STOP_GRACE_MS = 10000;
+export declare const DEFAULT_RETIRE_WAIT_MS = 5000;
+export type HostState = 'idle' | 'starting' | 'running' | 'restarting' | 'stopping' | 'fatal' | 'closed';
+/** What the supervisor knows about a host that exited without being asked to. */
+export interface HostExit {
+    /** `start-failed` is a restart whose start failed; the first start rejects its callers instead. */
+    readonly kind: 'crash' | 'out-of-memory' | 'start-failed';
+    readonly error: Error;
+    readonly code: number | null;
+    /** Milliseconds between `started` and the exit; null when the host never started. */
+    readonly uptimeMs: number | null;
+    /** Calls the exit rejected with `HOST_EXITED`. */
+    readonly pendingCalls: number;
+    readonly lastStats: HostStats | null;
+}
+/**
+ * - `fatal`: refuse every call from now on.
+ * - `on-demand`: start a new host on the next call.
+ * - `restart`: start a new host now, after `delayMs`.
+ */
+export type ExitDecision = 'fatal' | 'on-demand' | 'restart' | {
+    readonly action: 'restart';
+    readonly delayMs: number;
+};
+export interface CallOptions {
+    readonly signal?: AbortSignal;
+    /** Overrides `limits.callTimeoutMs`; for a stream it bounds each item. */
+    readonly timeoutMs?: number;
+}
+export interface HostOptions<Ops extends Contract<Ops>, Payload = undefined> {
+    /** The closed list of operations that answer once. */
+    readonly operations: readonly CallOperation<Ops>[];
+    /** The closed list of operations that answer with a stream. */
+    readonly streams?: readonly StreamOperation<Ops>[];
+    readonly transport: HostTransport;
+    readonly start?: {
+        /** Sent with `start` on every launch. Keeps secrets out of env and argv. */
+        readonly payload?: () => Payload | Promise<Payload>;
+        readonly timeoutMs?: number;
+    };
+    readonly stop?: {
+        /** How long `stop()` lets the host drain and close before terminating it. */
+        readonly graceMs?: number;
+        /** How long a terminated host may take to exit before the next one starts anyway. */
+        readonly retireWaitMs?: number;
+    };
+    readonly limits?: {
+        /** Calls and open streams allowed at once; one more fails with `HOST_QUEUE_FULL`. */
+        readonly maxPending?: number;
+        readonly callTimeoutMs?: number;
+    };
+    /** Decides what follows an exit nobody asked for. Defaults to `fatal`. */
+    readonly onExit?: (exit: HostExit) => ExitDecision | Promise<ExitDecision>;
+    readonly onStats?: (stats: HostStats) => void;
+    readonly now?: () => number;
+}
+export interface Host<Ops extends Contract<Ops>> {
+    /** One method per operation, with the contract's own signature. */
+    readonly ops: Ops;
+    call<K extends CallOperation<Ops>>(op: K, args: ArgsOf<Ops[K]>, options?: CallOptions): ReturnType<Ops[K]>;
+    stream<K extends StreamOperation<Ops>>(op: K, args: ArgsOf<Ops[K]>, options?: CallOptions): ReturnType<Ops[K]>;
+    /** Starts the host now instead of on the first call. */
+    start(): Promise<void>;
+    /** Drains and stops the host. The next call starts a new one. */
+    stop(): Promise<void>;
+    /** Terminates the host without draining, and waits (bounded) for it to exit. Never throws. */
+    kill(): Promise<void>;
+    /** Stops the host and refuses every later call. */
+    close(): Promise<void>;
+    readonly state: HostState;
+}
+export declare function createHost<Ops extends Contract<Ops>, Payload = undefined>(options: HostOptions<Ops, Payload>): Host<Ops>;
+//# sourceMappingURL=host.d.ts.map

package/dist/host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../src/host.ts"],"names":[],"mappings":"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"}