@start9labs/start-sdk 0.4.0-beta.50 → 0.4.0-beta.52

package/base/lib/s9pk/index.js

@@ -10,6 +10,11 @@ const mime_1 = __importDefault(require("mime"));
 const directoryContents_1 = require("./merkleArchive/directoryContents");
 const fileContents_1 = require("./merkleArchive/fileContents");
 const magicAndVersion = new Uint8Array([59, 59, 2]);
+/**
+ * Compares two `Uint8Array` instances byte-by-byte for equality.
+ *
+ * @returns `true` if both arrays have the same length and identical bytes
+ */
 function compare(a, b) {
     if (a.length !== b.length)
         return false;
@@ -19,12 +24,44 @@ function compare(a, b) {
     }
     return true;
 }
+/**
+ * Represents a parsed `.s9pk` package archive — the binary distribution format for StartOS services.
+ *
+ * An `S9pk` wraps a verified {@link Manifest}, a {@link MerkleArchive} containing the package's
+ * assets (icon, license, dependency metadata), and the total archive size in bytes.
+ *
+ * @example
+ * ```ts
+ * const s9pk = await S9pk.deserialize(file, null)
+ * console.log(s9pk.manifest.id)    // e.g. "bitcoind"
+ * console.log(s9pk.size)           // archive size in bytes
+ * const icon = await s9pk.icon()   // base64 data URL
+ * const license = await s9pk.license()
+ * ```
+ */
 class S9pk {
-    constructor(manifest, archive, size) {
+    constructor(
+    /** The parsed package manifest containing metadata, dependencies, and interface definitions. */
+    manifest, 
+    /** The Merkle-verified archive containing the package's files. */
+    archive, 
+    /** The total size of the archive in bytes. */
+    size) {
         this.manifest = manifest;
         this.archive = archive;
         this.size = size;
     }
+    /**
+     * Deserializes an `S9pk` from a `Blob` (e.g. a `File` from a browser file input).
+     *
+     * Validates the magic bytes and version header, then parses the Merkle archive structure.
+     * If a `commitment` is provided, the archive is cryptographically verified against it.
+     *
+     * @param source - The raw `.s9pk` file as a `Blob`
+     * @param commitment - An optional Merkle commitment to verify the archive against, or `null` to skip verification
+     * @returns A fully parsed `S9pk` instance
+     * @throws If the magic bytes are invalid or the archive fails verification
+     */
     static async deserialize(source, commitment) {
         const header = new merkleArchive_1.ArrayBufferReader(await source
             .slice(0, magicAndVersion.length + merkleArchive_1.MerkleArchive.headerSize)
@@ -39,6 +76,14 @@ class S9pk {
             ?.verifiedFileContents()));
         return new S9pk(manifest, archive, source.size);
     }
+    /**
+     * Extracts the package icon from the archive and returns it as a base64-encoded data URL.
+     *
+     * Looks for a file named `icon.*` with an image MIME type (e.g. `icon.png`, `icon.svg`).
+     *
+     * @returns A data URL string like `"data:image/png;base64,..."` suitable for use in `<img src>`.
+     * @throws If no icon file is found in the archive
+     */
     async icon() {
         const iconName = Object.keys(this.archive.contents.contents).find((name) => name.startsWith('icon.') && mime_1.default.getType(name)?.startsWith('image/'));
         if (!iconName) {
@@ -47,6 +92,12 @@ class S9pk {
         return (`data:${mime_1.default.getType(iconName)};base64,` +
             Buffer.from(await this.archive.contents.getPath([iconName]).verifiedFileContents()).toString('base64'));
     }
+    /**
+     * Returns the metadata (e.g. `{ title }`) for a specific dependency by its package ID.
+     *
+     * @param id - The dependency's package identifier (e.g. `"bitcoind"`)
+     * @returns The dependency metadata object, or `null` if the dependency is not present in the archive
+     */
     async dependencyMetadataFor(id) {
         const entry = this.archive.contents.getPath([
             'dependencies',
@@ -57,6 +108,12 @@ class S9pk {
             return null;
         return JSON.parse(new TextDecoder().decode(await entry.verifiedFileContents()));
     }
+    /**
+     * Returns the icon for a specific dependency as a base64 data URL.
+     *
+     * @param id - The dependency's package identifier
+     * @returns A data URL string, or `null` if the dependency or its icon is not present
+     */
     async dependencyIconFor(id) {
         const dir = this.archive.contents.getPath(['dependencies', id]);
         if (!dir || !(dir.contents instanceof directoryContents_1.DirectoryContents))
@@ -67,6 +124,12 @@ class S9pk {
         return (`data:${mime_1.default.getType(iconName)};base64,` +
             Buffer.from(await dir.contents.getPath([iconName]).verifiedFileContents()).toString('base64'));
     }
+    /**
+     * Returns a merged record of all dependency metadata (title, icon, description, optional flag)
+     * for every dependency declared in the manifest.
+     *
+     * @returns A record keyed by package ID, each containing `{ title, icon, description, optional }`
+     */
     async dependencyMetadata() {
         return Object.fromEntries(await Promise.all(Object.entries(this.manifest.dependencies)
             .filter(([_, info]) => !!info)
@@ -80,6 +143,12 @@ class S9pk {
             },
         ])));
     }
+    /**
+     * Reads and returns the `LICENSE.md` file from the archive as a UTF-8 string.
+     *
+     * @returns The full license text
+     * @throws If `LICENSE.md` is not found in the archive
+     */
     async license() {
         const file = this.archive.contents.getPath(['LICENSE.md']);
         if (!file || !(file.contents instanceof fileContents_1.FileContents))

package/base/lib/s9pk/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../base/lib/s9pk/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../base/lib/s9pk/index.ts"],"names":[],"mappings":";;;;;;AAmBA,0BAMC;AAlBD,mDAAkE;AAClE,gDAAuB;AACvB,yEAAqE;AACrE,+DAA2D;AAE3D,MAAM,eAAe,GAAG,IAAI,UAAU,CAAC,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,CAAA;AAEnD;;;;GAIG;AACH,SAAgB,OAAO,CAAC,CAAa,EAAE,CAAa;IAClD,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM;QAAE,OAAO,KAAK,CAAA;IACvC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAClC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YAAE,OAAO,KAAK,CAAA;IACjC,CAAC;IACD,OAAO,IAAI,CAAA;AACb,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAa,IAAI;IACf;IACE,gGAAgG;IACvF,QAAkB;IAC3B,kEAAkE;IACzD,OAAsB;IAC/B,8CAA8C;IACrC,IAAY;QAJZ,aAAQ,GAAR,QAAQ,CAAU;QAElB,YAAO,GAAP,OAAO,CAAe;QAEtB,SAAI,GAAJ,IAAI,CAAQ;IACpB,CAAC;IACJ;;;;;;;;;;OAUG;IACH,MAAM,CAAC,KAAK,CAAC,WAAW,CACtB,MAAY,EACZ,UAA0C;QAE1C,MAAM,MAAM,GAAG,IAAI,iCAAiB,CAClC,MAAM,MAAM;aACT,KAAK,CAAC,CAAC,EAAE,eAAe,CAAC,MAAM,GAAG,6BAAa,CAAC,UAAU,CAAC;aAC3D,WAAW,EAAE,CACjB,CAAA;QACD,MAAM,YAAY,GAAG,IAAI,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC,CAAA;QACxE,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE,eAAe,CAAC,EAAE,CAAC;YAC5C,MAAM,IAAI,KAAK,CAAC,qCAAqC,CAAC,CAAA;QACxD,CAAC;QAED,MAAM,OAAO,GAAG,MAAM,6BAAa,CAAC,WAAW,CAC7C,MAAM,EACN,MAAM,EACN,MAAM,EACN,UAAU,CACX,CAAA;QAED,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CACzB,IAAI,WAAW,EAAE,CAAC,MAAM,CACtB,MAAM,OAAO,CAAC,QAAQ;aACnB,OAAO,CAAC,CAAC,eAAe,CAAC,CAAC;YAC3B,EAAE,oBAAoB,EAAE,CAC3B,CACF,CAAA;QAED,OAAO,IAAI,IAAI,CAAC,QAAQ,EAAE,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,CAAA;IACjD,CAAC;IACD;;;;;;;OAOG;IACH,KAAK,CAAC,IAAI;QACR,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,IAAI,CAC/D,CAAC,IAAI,EAAE,EAAE,CACP,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,cAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,UAAU,CAAC,QAAQ,CAAC,CACvE,CAAA;QACD,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,MAAM,IAAI,KAAK,CAAC,0BAA0B,CAAC,CAAA;QAC7C,CAAC;QACD,OAAO,CACL,QAAQ,cAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,UAAU;YACxC,MAAM,CAAC,IAAI,CACT,MAAM,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,QAAQ,CAAC,CAAE,CAAC,oBAAoB,EAAE,CACxE,CAAC,QAAQ,CAAC,QAAQ,CAAC,CACrB,CAAA;IACH,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,qBAAqB,CAAC,EAAa;QACvC,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC;YAC1C,cAAc;YACd,EAAE;YACF,eAAe;SAChB,CAAC,CAAA;QACF,IAAI,CAAC,KAAK;YAAE,OAAO,IAAI,CAAA;QACvB,OAAO,IAAI,CAAC,KAAK,CACf,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,oBAAoB,EAAE,CAAC,CACxC,CAAA;IACxB,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,iBAAiB,CAAC,EAAa;QACnC,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,cAAc,EAAE,EAAE,CAAC,CAAC,CAAA;QAC/D,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC,GAAG,CAAC,QAAQ,YAAY,qCAAiB,CAAC;YAAE,OAAO,IAAI,CAAA;QACrE,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,IAAI,CACtD,CAAC,IAAI,EAAE,EAAE,CACP,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,cAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,UAAU,CAAC,QAAQ,CAAC,CACvE,CAAA;QACD,IAAI,CAAC,QAAQ;YAAE,OAAO,IAAI,CAAA;QAC1B,OAAO,CACL,QAAQ,cAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,UAAU;YACxC,MAAM,CAAC,IAAI,CACT,MAAM,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,QAAQ,CAAC,CAAE,CAAC,oBAAoB,EAAE,CAC/D,CAAC,QAAQ,CAAC,QAAQ,CAAC,CACrB,CAAA;IACH,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,kBAAkB;QACtB,OAAO,MAAM,CAAC,WAAW,CACvB,MAAM,OAAO,CAAC,GAAG,CACf,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,YAAY,CAAC;aACvC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;aAC7B,GAAG,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC;YACzB,EAAE;YACF;gBACE,GAAG,CAAC,MAAM,IAAI,CAAC,qBAAqB,CAAC,EAAE,CAAC,CAAC;gBACzC,IAAI,EAAE,MAAM,IAAI,CAAC,iBAAiB,CAAC,EAAE,CAAC;gBACtC,WAAW,EAAE,IAAK,CAAC,WAAW;gBAC9B,QAAQ,EAAE,IAAK,CAAC,QAAQ;aACzB;SACF,CAAC,CACL,CACF,CAAA;IACH,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,OAAO;QACX,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,YAAY,CAAC,CAAC,CAAA;QAC1D,IAAI,CAAC,IAAI,IAAI,CAAC,CAAC,IAAI,CAAC,QAAQ,YAAY,2BAAY,CAAC;YACnD,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAA;QACpD,OAAO,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,MAAM,IAAI,CAAC,oBAAoB,EAAE,CAAC,CAAA;IACpE,CAAC;CACF;AAvJD,oBAuJC"}

package/base/lib/types.d.ts

@@ -1,4 +1,5 @@
 export * as inputSpecTypes from './actions/input/inputSpecTypes';
+import { InputSpec as InputSpecClass } from './actions/input/builder/inputSpec';
 import { DependencyRequirement, NamedHealthCheckResult, Manifest, ServiceInterface, ActionId } from './osBindings';
 import { StringObject, ToKebab } from './util';
 import { Action, Actions } from './actions/setupActions';
@@ -8,21 +9,33 @@ export { Effects };
 export * from './osBindings';
 export { SDKManifest } from './types/ManifestTypes';
 export { RequiredDependenciesOf as RequiredDependencies, OptionalDependenciesOf as OptionalDependencies, CurrentDependenciesResult, } from './dependencies/setupDependencies';
+/** An object that can be built into a terminable daemon process. */
 export type DaemonBuildable = {
     build(): Promise<{
         term(): Promise<void>;
     }>;
 };
+/** The three categories of service network interfaces. */
 export type ServiceInterfaceType = 'ui' | 'p2p' | 'api';
+/** A Node.js signal name (e.g. `"SIGTERM"`, `"SIGKILL"`). */
 export type Signals = NodeJS.Signals;
+/** The SIGTERM signal — used for graceful daemon termination. */
 export declare const SIGTERM: Signals;
+/** The SIGKILL signal — used for forceful daemon termination. */
 export declare const SIGKILL: Signals;
+/** Sentinel value (`-1`) indicating that no timeout should be applied. */
 export declare const NO_TIMEOUT = -1;
+/** A function that builds an absolute file path from a volume name and relative path. */
 export type PathMaker = (options: {
     volume: string;
     path: string;
 }) => string;
+/** A value that may or may not be wrapped in a `Promise`. */
 export type MaybePromise<A> = Promise<A> | A;
+/**
+ * Namespace defining the required exports for a StartOS service package.
+ * Every package must export implementations matching these types.
+ */
 export declare namespace ExpectedExports {
     /** For backing up service data though the startOS UI */
     type createBackup = (options: {
@@ -50,9 +63,15 @@ export declare namespace ExpectedExports {
         effects: Effects;
         target: ExtendedVersion | VersionRange | null;
     }) => Promise<unknown>;
+    /** The package manifest describing the service's metadata, dependencies, and interfaces. */
     type manifest = Manifest;
+    /** The map of user-invocable actions defined by this service. */
     type actions = Actions<Record<ActionId, Action<ActionId, any>>>;
 }
+/**
+ * The complete ABI (Application Binary Interface) for a StartOS service package.
+ * Maps all required exports to their expected types.
+ */
 export type ABI = {
     createBackup: ExpectedExports.createBackup;
     main: ExpectedExports.main;
@@ -61,48 +80,75 @@ export type ABI = {
     manifest: ExpectedExports.manifest;
     actions: ExpectedExports.actions;
 };
+/** A time value in milliseconds. */
 export type TimeMs = number;
+/** A version string in string form. */
 export type VersionString = string;
 declare const DaemonProof: unique symbol;
+/** Opaque branded type proving that a daemon was started. Cannot be constructed directly. */
 export type DaemonReceipt = {
     [DaemonProof]: never;
 };
+/** A running daemon with methods to wait for completion or terminate it. */
 export type Daemon = {
+    /** Waits for the daemon to exit and returns its exit message. */
     wait(): Promise<string>;
+    /** Terminates the daemon. */
     term(): Promise<null>;
     [DaemonProof]: never;
 };
+/** The result status of a health check (extracted from `NamedHealthCheckResult`). */
 export type HealthStatus = NamedHealthCheckResult['result'];
+/** SMTP mail server configuration values. */
 export type SmtpValue = {
-    server: string;
+    host: string;
     port: number;
     from: string;
-    login: string;
+    username: string;
     password: string | null | undefined;
+    security: 'starttls' | 'tls';
 };
+/**
+ * Marker class indicating that a container should use its own built-in entrypoint
+ * rather than a custom command. Optionally accepts an override command array.
+ */
 export declare class UseEntrypoint {
     readonly overridCmd?: string[] | undefined;
     readonly USE_ENTRYPOINT = "USE_ENTRYPOINT";
     constructor(overridCmd?: string[] | undefined);
 }
+/** Type guard that checks if a {@link CommandType} is a {@link UseEntrypoint} instance. */
 export declare function isUseEntrypoint(command: CommandType): command is UseEntrypoint;
+/**
+ * The ways to specify a command to run in a container:
+ * - A shell string (run via `sh -c`)
+ * - An explicit argv array
+ * - A {@link UseEntrypoint} to use the container's built-in entrypoint
+ */
 export type CommandType = string | [string, ...string[]] | UseEntrypoint;
+/** The return type from starting a daemon — provides `wait()` and `term()` controls. */
 export type DaemonReturned = {
+    /** Waits for the daemon process to exit. */
     wait(): Promise<unknown>;
+    /** Sends a signal to terminate the daemon. If it doesn't exit within `timeout` ms, sends SIGKILL. */
     term(options?: {
         signal?: Signals;
         timeout?: number;
     }): Promise<null>;
 };
 export declare const hostName: unique symbol;
+/** A branded string type for hostnames (e.g. `.onion` addresses or IP addresses). */
 export type Hostname = string & {
     [hostName]: never;
 };
+/** A string identifier for a service network interface. */
 export type ServiceInterfaceId = string;
 export { ServiceInterface };
+/** Maps effect method names to their kebab-case RPC equivalents. */
 export type EffectMethod<T extends StringObject = Effects> = {
     [K in keyof T]-?: K extends string ? T[K] extends Function ? ToKebab<K> : T[K] extends StringObject ? `${ToKebab<K>}.${EffectMethod<T[K]>}` : never : never;
 }[keyof T];
+/** Options for rsync-based file synchronization (used in backup/restore). */
 export type SyncOptions = {
     /** delete files that exist in the target directory, but not in the source directory */
     delete: boolean;
@@ -126,33 +172,53 @@ export type Metadata = {
     gid: number;
     mode: number;
 };
+/** Result type for setting a service's dependency configuration and restart signal. */
 export type SetResult = {
     dependsOn: DependsOn;
     signal: Signals;
 };
+/** A string identifier for a StartOS package (e.g. `"bitcoind"`). */
 export type PackageId = string;
+/** A user-facing message string. */
 export type Message = string;
+/** Whether a dependency needs to be actively running or merely installed. */
 export type DependencyKind = 'running' | 'exists';
+/**
+ * Maps package IDs to the health check IDs that must pass before this service considers
+ * the dependency satisfied.
+ */
 export type DependsOn = {
     [packageId: string]: string[] | readonly string[];
 };
+/**
+ * A typed error that can be displayed to the user.
+ * Either a plain error message string, or a structured error code with description.
+ */
 export type KnownError = {
     error: string;
 } | {
     errorCode: [number, string] | readonly [number, string];
 };
+/** An array of dependency requirements for a service. */
 export type Dependencies = Array<DependencyRequirement>;
+/** Recursively makes all properties of `T` optional. */
 export type DeepPartial<T> = T extends [infer A, ...infer Rest] ? [DeepPartial<A>, ...DeepPartial<Rest>] : T extends {} ? {
     [P in keyof T]?: DeepPartial<T[P]>;
 } : T;
+/** Recursively removes all `readonly` modifiers from `T`. */
 export type DeepWritable<T> = {
     -readonly [K in keyof T]: T[K];
 };
+/** Casts a value to {@link DeepWritable} (identity at runtime, removes `readonly` at the type level). */
 export declare function writable<T>(value: T): DeepWritable<T>;
+/** Recursively makes all properties of `T` readonly. */
 export type DeepReadonly<T> = {
     readonly [P in keyof T]: DeepReadonly<T[P]>;
 };
+/** Casts a value to {@link DeepReadonly} (identity at runtime, adds `readonly` at the type level). */
 export declare function readonly<T>(value: T): DeepReadonly<T>;
+/** Accepts either a mutable or deeply-readonly version of `T`. */
 export type AllowReadonly<T> = T | {
     readonly [P in keyof T]: AllowReadonly<T[P]>;
 };
+export type InputSpec<Type extends StaticValidatedAs, StaticValidatedAs extends Record<string, unknown> = Type> = InputSpecClass<Type, StaticValidatedAs>;

package/base/lib/types.js

@@ -42,13 +42,24 @@ exports.writable = writable;
 exports.readonly = readonly;
 exports.inputSpecTypes = __importStar(require("./actions/input/inputSpecTypes"));
 __exportStar(require("./osBindings"), exports);
+/** The SIGTERM signal — used for graceful daemon termination. */
 exports.SIGTERM = 'SIGTERM';
+/** The SIGKILL signal — used for forceful daemon termination. */
 exports.SIGKILL = 'SIGKILL';
+/** Sentinel value (`-1`) indicating that no timeout should be applied. */
 exports.NO_TIMEOUT = -1;
+/**
+ * Namespace defining the required exports for a StartOS service package.
+ * Every package must export implementations matching these types.
+ */
 var ExpectedExports;
 (function (ExpectedExports) {
     version: 1;
 })(ExpectedExports || (exports.ExpectedExports = ExpectedExports = {}));
+/**
+ * Marker class indicating that a container should use its own built-in entrypoint
+ * rather than a custom command. Optionally accepts an override command array.
+ */
 class UseEntrypoint {
     constructor(overridCmd) {
         this.overridCmd = overridCmd;
@@ -56,12 +67,15 @@ class UseEntrypoint {
     }
 }
 exports.UseEntrypoint = UseEntrypoint;
+/** Type guard that checks if a {@link CommandType} is a {@link UseEntrypoint} instance. */
 function isUseEntrypoint(command) {
     return typeof command === 'object' && 'USE_ENTRYPOINT' in command;
 }
+/** Casts a value to {@link DeepWritable} (identity at runtime, removes `readonly` at the type level). */
 function writable(value) {
     return value;
 }
+/** Casts a value to {@link DeepReadonly} (identity at runtime, adds `readonly` at the type level). */
 function readonly(value) {
     return value;
 }

package/base/lib/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../base/lib/types.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsGA,0CAIC;AAmFD,4BAEC;AAMD,4BAEC;AAvMD,iFAAgE;AAchE,+CAA4B;AAgBf,QAAA,OAAO,GAAY,SAAS,CAAA;AAC5B,QAAA,OAAO,GAAY,SAAS,CAAA;AAC5B,QAAA,UAAU,GAAG,CAAC,CAAC,CAAA;AAI5B,IAAiB,eAAe,CA+B/B;AA/BD,WAAiB,eAAe;IAC9B,OAAO,EAAE,CAAC,CAAA;AA8BZ,CAAC,EA/BgB,eAAe,+BAAf,eAAe,QA+B/B;AA+BD,MAAa,aAAa;IAExB,YAAqB,UAAqB;QAArB,eAAU,GAAV,UAAU,CAAW;QADjC,mBAAc,GAAG,gBAAgB,CAAA;IACG,CAAC;CAC/C;AAHD,sCAGC;AACD,SAAgB,eAAe,CAC7B,OAAoB;IAEpB,OAAO,OAAO,OAAO,KAAK,QAAQ,IAAI,gBAAgB,IAAI,OAAO,CAAA;AACnE,CAAC;AAmFD,SAAgB,QAAQ,CAAI,KAAQ;IAClC,OAAO,KAAK,CAAA;AACd,CAAC;AAMD,SAAgB,QAAQ,CAAI,KAAQ;IAClC,OAAO,KAAK,CAAA;AACd,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../base/lib/types.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuIA,0CAIC;AA+GD,4BAEC;AAQD,4BAEC;AAtQD,iFAAgE;AAehE,+CAA4B;AAmB5B,iEAAiE;AACpD,QAAA,OAAO,GAAY,SAAS,CAAA;AACzC,iEAAiE;AACpD,QAAA,OAAO,GAAY,SAAS,CAAA;AACzC,0EAA0E;AAC7D,QAAA,UAAU,GAAG,CAAC,CAAC,CAAA;AAM5B;;;GAGG;AACH,IAAiB,eAAe,CAiC/B;AAjCD,WAAiB,eAAe;IAC9B,OAAO,EAAE,CAAC,CAAA;AAgCZ,CAAC,EAjCgB,eAAe,+BAAf,eAAe,QAiC/B;AA4CD;;;GAGG;AACH,MAAa,aAAa;IAExB,YAAqB,UAAqB;QAArB,eAAU,GAAV,UAAU,CAAW;QADjC,mBAAc,GAAG,gBAAgB,CAAA;IACG,CAAC;CAC/C;AAHD,sCAGC;AACD,2FAA2F;AAC3F,SAAgB,eAAe,CAC7B,OAAoB;IAEpB,OAAO,OAAO,OAAO,KAAK,QAAQ,IAAI,gBAAgB,IAAI,OAAO,CAAA;AACnE,CAAC;AA8GD,yGAAyG;AACzG,SAAgB,QAAQ,CAAI,KAAQ;IAClC,OAAO,KAAK,CAAA;AACd,CAAC;AAOD,sGAAsG;AACtG,SAAgB,QAAQ,CAAI,KAAQ;IAClC,OAAO,KAAK,CAAA;AACd,CAAC"}

package/base/lib/util/GetOutboundGateway.d.ts

@@ -0,0 +1,30 @@
+import { Effects } from '../Effects';
+export declare class GetOutboundGateway {
+    readonly effects: Effects;
+    constructor(effects: Effects);
+    /**
+     * Returns the effective outbound gateway. Reruns the context from which it has been called if the underlying value changes
+     */
+    const(): Promise<string>;
+    /**
+     * Returns the effective outbound gateway. Does nothing if the value changes
+     */
+    once(): Promise<string>;
+    private watchGen;
+    /**
+     * Watches the effective outbound gateway. Returns an async iterator that yields whenever the value changes
+     */
+    watch(abort?: AbortSignal): AsyncGenerator<string, never, unknown>;
+    /**
+     * Watches the effective outbound gateway. Takes a custom callback function to run whenever the value changes
+     */
+    onChange(callback: (value: string, error?: Error) => {
+        cancel: boolean;
+    } | Promise<{
+        cancel: boolean;
+    }>): void;
+    /**
+     * Watches the effective outbound gateway. Returns when the predicate is true
+     */
+    waitFor(pred: (value: string) => boolean): Promise<string>;
+}

package/base/lib/util/GetOutboundGateway.js

@@ -0,0 +1,90 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GetOutboundGateway = void 0;
+const Drop_1 = require("./Drop");
+class GetOutboundGateway {
+    constructor(effects) {
+        this.effects = effects;
+    }
+    /**
+     * Returns the effective outbound gateway. Reruns the context from which it has been called if the underlying value changes
+     */
+    const() {
+        return this.effects.getOutboundGateway({
+            callback: this.effects.constRetry &&
+                (() => this.effects.constRetry && this.effects.constRetry()),
+        });
+    }
+    /**
+     * Returns the effective outbound gateway. Does nothing if the value changes
+     */
+    once() {
+        return this.effects.getOutboundGateway({});
+    }
+    async *watchGen(abort) {
+        const resolveCell = { resolve: () => { } };
+        this.effects.onLeaveContext(() => {
+            resolveCell.resolve();
+        });
+        abort?.addEventListener('abort', () => resolveCell.resolve());
+        while (this.effects.isInContext && !abort?.aborted) {
+            let callback = () => { };
+            const waitForNext = new Promise((resolve) => {
+                callback = resolve;
+                resolveCell.resolve = resolve;
+            });
+            yield await this.effects.getOutboundGateway({
+                callback: () => callback(),
+            });
+            await waitForNext;
+        }
+        return new Promise((_, rej) => rej(new Error('aborted')));
+    }
+    /**
+     * Watches the effective outbound gateway. Returns an async iterator that yields whenever the value changes
+     */
+    watch(abort) {
+        const ctrl = new AbortController();
+        abort?.addEventListener('abort', () => ctrl.abort());
+        return Drop_1.DropGenerator.of(this.watchGen(ctrl.signal), () => ctrl.abort());
+    }
+    /**
+     * Watches the effective outbound gateway. Takes a custom callback function to run whenever the value changes
+     */
+    onChange(callback) {
+        ;
+        (async () => {
+            const ctrl = new AbortController();
+            for await (const value of this.watch(ctrl.signal)) {
+                try {
+                    const res = await callback(value);
+                    if (res.cancel) {
+                        ctrl.abort();
+                        break;
+                    }
+                }
+                catch (e) {
+                    console.error('callback function threw an error @ GetOutboundGateway.onChange', e);
+                }
+            }
+        })()
+            .catch((e) => callback('', e))
+            .catch((e) => console.error('callback function threw an error @ GetOutboundGateway.onChange', e));
+    }
+    /**
+     * Watches the effective outbound gateway. Returns when the predicate is true
+     */
+    waitFor(pred) {
+        const ctrl = new AbortController();
+        return Drop_1.DropPromise.of(Promise.resolve().then(async () => {
+            for await (const next of this.watchGen(ctrl.signal)) {
+                if (pred(next)) {
+                    return next;
+                }
+            }
+            return '';
+        }), () => ctrl.abort());
+    }
+}
+exports.GetOutboundGateway = GetOutboundGateway;
+//# sourceMappingURL=GetOutboundGateway.js.map

package/base/lib/util/GetOutboundGateway.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GetOutboundGateway.js","sourceRoot":"","sources":["../../../../base/lib/util/GetOutboundGateway.ts"],"names":[],"mappings":"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"}

package/base/lib/util/asError.d.ts

@@ -1 +1,9 @@
+/**
+ * Converts an unknown thrown value into an Error instance.
+ * If `e` is already an Error, wraps it; if a string, uses it as the message;
+ * otherwise JSON-serializes it as the error message.
+ *
+ * @param e - The unknown value to convert
+ * @returns An Error instance
+ */
 export declare const asError: (e: unknown) => Error;

package/base/lib/util/asError.js

@@ -1,6 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.asError = void 0;
+/**
+ * Converts an unknown thrown value into an Error instance.
+ * If `e` is already an Error, wraps it; if a string, uses it as the message;
+ * otherwise JSON-serializes it as the error message.
+ *
+ * @param e - The unknown value to convert
+ * @returns An Error instance
+ */
 const asError = (e) => {
     if (e instanceof Error) {
         return new Error(e);

package/base/lib/util/asError.js.map

@@ -1 +1 @@
-{"version":3,"file":"asError.js","sourceRoot":"","sources":["../../../../base/lib/util/asError.ts"],"names":[],"mappings":";;;AAAO,MAAM,OAAO,GAAG,CAAC,CAAU,EAAE,EAAE;IACpC,IAAI,CAAC,YAAY,KAAK,EAAE,CAAC;QACvB,OAAO,IAAI,KAAK,CAAC,CAAQ,CAAC,CAAA;IAC5B,CAAC;IACD,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;QAC1B,OAAO,IAAI,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,CAAA;IAC1B,CAAC;IACD,OAAO,IAAI,KAAK,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAA;AAC1C,CAAC,CAAA;AARY,QAAA,OAAO,WAQnB"}
+{"version":3,"file":"asError.js","sourceRoot":"","sources":["../../../../base/lib/util/asError.ts"],"names":[],"mappings":";;;AAAA;;;;;;;GAOG;AACI,MAAM,OAAO,GAAG,CAAC,CAAU,EAAE,EAAE;IACpC,IAAI,CAAC,YAAY,KAAK,EAAE,CAAC;QACvB,OAAO,IAAI,KAAK,CAAC,CAAQ,CAAC,CAAA;IAC5B,CAAC;IACD,IAAI,OAAO,CAAC,KAAK,QAAQ,EAAE,CAAC;QAC1B,OAAO,IAAI,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,CAAA;IAC1B,CAAC;IACD,OAAO,IAAI,KAAK,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAA;AAC1C,CAAC,CAAA;AARY,QAAA,OAAO,WAQnB"}

package/base/lib/util/deepEqual.d.ts

@@ -1 +1,16 @@
+/**
+ * Performs a deep structural equality check across all provided arguments.
+ * Returns true only if every argument is deeply equal to every other argument.
+ * Handles primitives, arrays, and plain objects recursively.
+ *
+ * @param args - Two or more values to compare for deep equality
+ * @returns True if all arguments are deeply equal
+ *
+ * @example
+ * ```ts
+ * deepEqual({ a: 1 }, { a: 1 })           // true
+ * deepEqual([1, 2], [1, 2], [1, 2])       // true
+ * deepEqual({ a: 1 }, { a: 2 })           // false
+ * ```
+ */
 export declare function deepEqual(...args: unknown[]): boolean;

package/base/lib/util/deepEqual.js

@@ -1,9 +1,23 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.deepEqual = deepEqual;
-const ts_matches_1 = require("ts-matches");
+/**
+ * Performs a deep structural equality check across all provided arguments.
+ * Returns true only if every argument is deeply equal to every other argument.
+ * Handles primitives, arrays, and plain objects recursively.
+ *
+ * @param args - Two or more values to compare for deep equality
+ * @returns True if all arguments are deeply equal
+ *
+ * @example
+ * ```ts
+ * deepEqual({ a: 1 }, { a: 1 })           // true
+ * deepEqual([1, 2], [1, 2], [1, 2])       // true
+ * deepEqual({ a: 1 }, { a: 2 })           // false
+ * ```
+ */
 function deepEqual(...args) {
-    const objects = args.filter(ts_matches_1.object.test);
+    const objects = args.filter((x) => typeof x === 'object' && x !== null);
     if (objects.length === 0) {
         for (const x of args)
             if (x !== args[0])

package/base/lib/util/deepEqual.js.map

@@ -1 +1 @@
-{"version":3,"file":"deepEqual.js","sourceRoot":"","sources":["../../../../base/lib/util/deepEqual.ts"],"names":[],"mappings":";;AAEA,8BAgBC;AAlBD,2CAAmC;AAEnC,SAAgB,SAAS,CAAC,GAAG,IAAe;IAC1C,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,mBAAM,CAAC,IAAI,CAAC,CAAA;IACxC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,KAAK,MAAM,CAAC,IAAI,IAAI;YAAE,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC;gBAAE,OAAO,KAAK,CAAA;QACrD,OAAO,IAAI,CAAA;IACb,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,KAAK,IAAI,CAAC,MAAM;QAAE,OAAO,KAAK,CAAA;IAChD,IAAI,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC;QAAE,OAAO,KAAK,CAAA;IAC9E,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;IAC/D,KAAK,MAAM,GAAG,IAAI,OAAO,EAAE,CAAC;QAC1B,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;YACxB,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;gBAAE,OAAO,KAAK,CAAA;YAC7B,IAAI,CAAC,SAAS,CAAE,OAAO,CAAC,CAAC,CAAS,CAAC,GAAG,CAAC,EAAG,CAAS,CAAC,GAAG,CAAC,CAAC;gBAAE,OAAO,KAAK,CAAA;QACzE,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAA;AACb,CAAC"}
+{"version":3,"file":"deepEqual.js","sourceRoot":"","sources":["../../../../base/lib/util/deepEqual.ts"],"names":[],"mappings":";;AAeA,8BAkBC;AAjCD;;;;;;;;;;;;;;GAcG;AACH,SAAgB,SAAS,CAAC,GAAG,IAAe;IAC1C,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CACzB,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,CACxD,CAAA;IACD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,KAAK,MAAM,CAAC,IAAI,IAAI;YAAE,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC;gBAAE,OAAO,KAAK,CAAA;QACrD,OAAO,IAAI,CAAA;IACb,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,KAAK,IAAI,CAAC,MAAM;QAAE,OAAO,KAAK,CAAA;IAChD,IAAI,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC;QAAE,OAAO,KAAK,CAAA;IAC9E,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAA;IAC/D,KAAK,MAAM,GAAG,IAAI,OAAO,EAAE,CAAC;QAC1B,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;YACxB,IAAI,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;gBAAE,OAAO,KAAK,CAAA;YAC7B,IAAI,CAAC,SAAS,CAAE,OAAO,CAAC,CAAC,CAAS,CAAC,GAAG,CAAC,EAAG,CAAS,CAAC,GAAG,CAAC,CAAC;gBAAE,OAAO,KAAK,CAAA;QACzE,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAA;AACb,CAAC"}

package/base/lib/util/deepMerge.d.ts

@@ -1,4 +1,22 @@
+/**
+ * Computes the partial difference between two values.
+ * Returns `undefined` if the values are equal, or `{ diff }` containing only the changed parts.
+ * For arrays, the diff contains only items in `next` that have no deep-equal counterpart in `prev`.
+ * For objects, the diff contains only keys whose values changed.
+ *
+ * @param prev - The original value
+ * @param next - The updated value
+ * @returns An object containing the diff, or `undefined` if the values are equal
+ */
 export declare function partialDiff<T>(prev: T, next: T): {
     diff: Partial<T>;
 } | undefined;
+/**
+ * Deeply merges multiple values together. Objects are merged key-by-key recursively.
+ * Arrays are merged by appending items that are not already present (by deep equality).
+ * Primitives are resolved by taking the last argument.
+ *
+ * @param args - The values to merge, applied left to right
+ * @returns The merged result
+ */
 export declare function deepMerge(...args: unknown[]): unknown;

package/base/lib/util/deepMerge.js

@@ -2,6 +2,16 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.partialDiff = partialDiff;
 exports.deepMerge = deepMerge;
+/**
+ * Computes the partial difference between two values.
+ * Returns `undefined` if the values are equal, or `{ diff }` containing only the changed parts.
+ * For arrays, the diff contains only items in `next` that have no deep-equal counterpart in `prev`.
+ * For objects, the diff contains only keys whose values changed.
+ *
+ * @param prev - The original value
+ * @param next - The updated value
+ * @returns An object containing the diff, or `undefined` if the values are equal
+ */
 function partialDiff(prev, next) {
     if (prev === next) {
         return;
@@ -53,6 +63,14 @@ function partialDiff(prev, next) {
         return { diff: next };
     }
 }
+/**
+ * Deeply merges multiple values together. Objects are merged key-by-key recursively.
+ * Arrays are merged by appending items that are not already present (by deep equality).
+ * Primitives are resolved by taking the last argument.
+ *
+ * @param args - The values to merge, applied left to right
+ * @returns The merged result
+ */
 function deepMerge(...args) {
     const lastItem = args[args.length - 1];
     if (typeof lastItem !== 'object' || !lastItem)