@nhtio/adk 1.20260609.0 → 1.20260610.0

package/batteries/media/engines/audio_decode.mjs

@@ -0,0 +1,90 @@
+import { o as isError } from "../../../tool_registry-791Vrjtf.mjs";
+import "../../../guards.mjs";
+import { PCM_MIME, pcmToBytes } from "../contracts.mjs";
+import { t as E_INVALID_MEDIA_PIPELINE_CONFIG } from "../../../exceptions-C7FSHEnV.mjs";
+//#region src/batteries/media/engines/audio_decode.ts
+/**
+* A cross-environment audio-decoding {@link @nhtio/adk/batteries/media/contracts!MediaEngine}
+* backed by the `audio-decode` package (pure JS/WASM codecs — no ffmpeg, no native bindings;
+* works in Node and browsers).
+*
+* @module @nhtio/adk/batteries/media/engines/audio_decode
+*
+* @remarks
+* Declares one convert capability: audio containers to the virtual `pcm` token (mp3 /
+* m4a-aac / ogg-vorbis / opus / flac / wav), downmixed to mono. The PCM output reports the
+* SOURCE sample rate in `meta.sampleRate` — the pipeline's transcribe step resamples to the
+* 16 kHz transcription engines expect. For exotic containers, compose an ffmpeg-backed
+* engine instead; the capability declaration is the seam.
+*
+* `audio-decode` is an optional peer dependency, lazily imported on first actual use.
+*/
+var channelsOf = (buffer) => {
+	if (Array.isArray(buffer.channelData)) return buffer.channelData;
+	if (typeof buffer.getChannelData === "function") {
+		const count = buffer.numberOfChannels ?? 1;
+		return Array.from({ length: count }, (_, c) => buffer.getChannelData(c));
+	}
+	throw new Error("audio-decode returned an unrecognized buffer shape");
+};
+/**
+* Construct the audio-decode-backed engine.
+*
+* @param options - Optional module resolver override.
+* @returns The engine.
+*/
+var audioDecodeEngine = (options = {}) => {
+	let fnPromise;
+	const getDecode = () => {
+		fnPromise ??= Promise.resolve(options.audioDecode ? options.audioDecode() : import("audio-decode")).then((mod) => {
+			const fn = typeof mod === "function" ? mod : mod.default;
+			if (typeof fn !== "function") throw new Error("audio-decode did not resolve to a decode function");
+			return fn;
+		}).catch((err) => {
+			throw new E_INVALID_MEDIA_PIPELINE_CONFIG([`the audio-decode engine could not load its peer dependency "audio-decode": ${isError(err) ? err.message : String(err)} — install it (pnpm add audio-decode)`]);
+		});
+		return fnPromise;
+	};
+	const convert = async (request) => {
+		const buffer = await (await getDecode())(request.bytes);
+		const channels = channelsOf(buffer);
+		let pcm;
+		if (channels.length <= 1) pcm = channels[0];
+		else {
+			const length = channels[0].length;
+			const mono = new Float32Array(length);
+			for (const data of channels) for (let i = 0; i < length; i++) mono[i] += data[i] / channels.length;
+			pcm = mono;
+		}
+		return { outputs: [{
+			bytes: pcmToBytes(pcm),
+			mimeType: PCM_MIME,
+			meta: { sampleRate: buffer.sampleRate }
+		}] };
+	};
+	return {
+		id: "audio-decode",
+		converts: [{
+			from: [
+				"audio/mpeg",
+				"audio/mp3",
+				"audio/mp4",
+				"audio/aac",
+				"audio/x-m4a",
+				"audio/ogg",
+				"audio/opus",
+				"audio/flac",
+				"audio/x-flac",
+				"audio/wav",
+				"audio/x-wav",
+				"audio/wave"
+			],
+			to: ["pcm"],
+			convert
+		}]
+	};
+};
+//#endregion
+export { audioDecodeEngine };
+
+//# sourceMappingURL=audio_decode.mjs.map

package/batteries/media/engines/audio_decode.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"audio_decode.mjs","names":[],"sources":["../../../../src/batteries/media/engines/audio_decode.ts"],"sourcesContent":["/**\n * A cross-environment audio-decoding {@link @nhtio/adk/batteries/media/contracts!MediaEngine}\n * backed by the `audio-decode` package (pure JS/WASM codecs — no ffmpeg, no native bindings;\n * works in Node and browsers).\n *\n * @module @nhtio/adk/batteries/media/engines/audio_decode\n *\n * @remarks\n * Declares one convert capability: audio containers to the virtual `pcm` token (mp3 /\n * m4a-aac / ogg-vorbis / opus / flac / wav), downmixed to mono. The PCM output reports the\n * SOURCE sample rate in `meta.sampleRate` — the pipeline's transcribe step resamples to the\n * 16 kHz transcription engines expect. For exotic containers, compose an ffmpeg-backed\n * engine instead; the capability declaration is the seam.\n *\n * `audio-decode` is an optional peer dependency, lazily imported on first actual use.\n */\n\nimport { isError } from '@nhtio/adk/guards'\nimport { pcmToBytes, PCM_MIME } from '../contracts'\nimport { E_INVALID_MEDIA_PIPELINE_CONFIG } from '../exceptions'\nimport type { MediaEngine, ConvertRequest, ConvertResult } from '../contracts'\n\n/**\n * The decoded shapes audio-decode resolves to. Some codecs return an AudioBuffer-compatible\n * object (`numberOfChannels` + `getChannelData`); others (e.g. the wav path in Node) return a\n * plain `{ channelData: Float32Array[], sampleRate }` record. The engine normalizes both.\n */\ninterface AudioBufferLike {\n  numberOfChannels?: number\n  sampleRate: number\n  getChannelData?(channel: number): Float32Array\n  channelData?: Float32Array[]\n}\n\ntype AudioDecodeFn = (bytes: Uint8Array | ArrayBuffer) => Promise<AudioBufferLike>\n\nconst channelsOf = (buffer: AudioBufferLike): Float32Array[] => {\n  if (Array.isArray(buffer.channelData)) return buffer.channelData\n  if (typeof buffer.getChannelData === 'function') {\n    const count = buffer.numberOfChannels ?? 1\n    return Array.from({ length: count }, (_, c) => buffer.getChannelData!(c))\n  }\n  throw new Error('audio-decode returned an unrecognized buffer shape')\n}\n\n/** Options for {@link audioDecodeEngine}. */\nexport interface AudioDecodeEngineOptions {\n  /** Override the module resolution. Default: `import('audio-decode')`. */\n  audioDecode?: () =>\n    | AudioDecodeFn\n    | { default: AudioDecodeFn }\n    | Promise<AudioDecodeFn | { default: AudioDecodeFn }>\n}\n\n/**\n * Construct the audio-decode-backed engine.\n *\n * @param options - Optional module resolver override.\n * @returns The engine.\n */\nexport const audioDecodeEngine = (options: AudioDecodeEngineOptions = {}): MediaEngine => {\n  let fnPromise: Promise<AudioDecodeFn> | undefined\n  const getDecode = (): Promise<AudioDecodeFn> => {\n    fnPromise ??= Promise.resolve(\n      options.audioDecode ? options.audioDecode() : import('audio-decode')\n    )\n      .then((mod) => {\n        const fn = typeof mod === 'function' ? mod : (mod as { default: AudioDecodeFn }).default\n        if (typeof fn !== 'function') {\n          throw new Error('audio-decode did not resolve to a decode function')\n        }\n        return fn\n      })\n      .catch((err) => {\n        const detail = isError(err) ? err.message : String(err)\n        throw new E_INVALID_MEDIA_PIPELINE_CONFIG([\n          `the audio-decode engine could not load its peer dependency \"audio-decode\": ${detail} — install it (pnpm add audio-decode)`,\n        ])\n      })\n    return fnPromise\n  }\n\n  const convert = async (request: ConvertRequest): Promise<ConvertResult> => {\n    const decode = await getDecode()\n    const buffer = await decode(request.bytes)\n    const channels = channelsOf(buffer)\n    let pcm: Float32Array\n    if (channels.length <= 1) {\n      pcm = channels[0]\n    } else {\n      // Downmix to mono by averaging channels.\n      const length = channels[0].length\n      const mono = new Float32Array(length)\n      for (const data of channels) {\n        for (let i = 0; i < length; i++) mono[i] += data[i] / channels.length\n      }\n      pcm = mono\n    }\n    return {\n      outputs: [\n        { bytes: pcmToBytes(pcm), mimeType: PCM_MIME, meta: { sampleRate: buffer.sampleRate } },\n      ],\n    }\n  }\n\n  return {\n    id: 'audio-decode',\n    converts: [\n      {\n        from: [\n          'audio/mpeg',\n          'audio/mp3',\n          'audio/mp4',\n          'audio/aac',\n          'audio/x-m4a',\n          'audio/ogg',\n          'audio/opus',\n          'audio/flac',\n          'audio/x-flac',\n          'audio/wav',\n          'audio/x-wav',\n          'audio/wave',\n        ],\n        to: ['pcm'],\n        convert,\n      },\n    ],\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAoCA,IAAM,cAAc,WAA4C;CAC9D,IAAI,MAAM,QAAQ,OAAO,WAAW,GAAG,OAAO,OAAO;CACrD,IAAI,OAAO,OAAO,mBAAmB,YAAY;EAC/C,MAAM,QAAQ,OAAO,oBAAoB;EACzC,OAAO,MAAM,KAAK,EAAE,QAAQ,MAAM,IAAI,GAAG,MAAM,OAAO,eAAgB,CAAC,CAAC;CAC1E;CACA,MAAM,IAAI,MAAM,oDAAoD;AACtE;;;;;;;AAiBA,IAAa,qBAAqB,UAAoC,CAAC,MAAmB;CACxF,IAAI;CACJ,MAAM,kBAA0C;EAC9C,cAAc,QAAQ,QACpB,QAAQ,cAAc,QAAQ,YAAY,IAAI,OAAO,eACvD,EACG,MAAM,QAAQ;GACb,MAAM,KAAK,OAAO,QAAQ,aAAa,MAAO,IAAmC;GACjF,IAAI,OAAO,OAAO,YAChB,MAAM,IAAI,MAAM,mDAAmD;GAErE,OAAO;EACT,CAAC,EACA,OAAO,QAAQ;GAEd,MAAM,IAAI,gCAAgC,CACxC,8EAFa,QAAQ,GAAG,IAAI,IAAI,UAAU,OAAO,GAAG,EAEiC,sCACvF,CAAC;EACH,CAAC;EACH,OAAO;CACT;CAEA,MAAM,UAAU,OAAO,YAAoD;EAEzE,MAAM,SAAS,OAAM,MADA,UAAU,GACH,QAAQ,KAAK;EACzC,MAAM,WAAW,WAAW,MAAM;EAClC,IAAI;EACJ,IAAI,SAAS,UAAU,GACrB,MAAM,SAAS;OACV;GAEL,MAAM,SAAS,SAAS,GAAG;GAC3B,MAAM,OAAO,IAAI,aAAa,MAAM;GACpC,KAAK,MAAM,QAAQ,UACjB,KAAK,IAAI,IAAI,GAAG,IAAI,QAAQ,KAAK,KAAK,MAAM,KAAK,KAAK,SAAS;GAEjE,MAAM;EACR;EACA,OAAO,EACL,SAAS,CACP;GAAE,OAAO,WAAW,GAAG;GAAG,UAAU;GAAU,MAAM,EAAE,YAAY,OAAO,WAAW;EAAE,CACxF,EACF;CACF;CAEA,OAAO;EACL,IAAI;EACJ,UAAU,CACR;GACE,MAAM;IACJ;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;IACA;GACF;GACA,IAAI,CAAC,KAAK;GACV;EACF,CACF;CACF;AACF"}

package/batteries/media/engines/execa_executor.cjs

@@ -0,0 +1,64 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+require("../../../chunk-Ble4zEEl.js");
+const require_tool_registry = require("../../../tool_registry-CKJPze3j.js");
+require("../../../guards.cjs");
+const require_exceptions = require("../../../exceptions-CQi_lNs1.js");
+//#region src/batteries/media/engines/execa_executor.ts
+/**
+* A {@link @nhtio/adk/batteries/media/contracts!BinaryExecutor} implementation that runs
+* invocations as local child processes via execa.
+*
+* @module @nhtio/adk/batteries/media/engines/execa_executor
+*
+* @remarks
+* The bundled local-process executor. `execa` is an optional peer dependency acquired through
+* an async resolver (default: a lazy dynamic import) — importing this module pulls nothing;
+* constructing the executor is what resolves the peer, and only on first `exec`.
+*
+* Process execution is a movable seam: anything implementing the `BinaryExecutor` contract —
+* a remote runner, a sandbox, a container shim — composes into binary engines exactly like
+* this one. The paired `ScratchWorkspace` must produce paths this executor can open; for the
+* local-process case, the bundled `fs_workspace` is the natural pair.
+*/
+var resolveExeca = async (supplied) => {
+	let value = supplied ?? (() => import("execa"));
+	if (typeof value === "function" && !("exec" in value)) try {
+		value = await value();
+	} catch (err) {
+		throw new require_exceptions.E_INVALID_MEDIA_PIPELINE_CONFIG([`execa resolver failed: ${require_tool_registry.isError(err) ? err.message : String(err)} — install the optional peer dependency "execa" or supply your own`]);
+	}
+	if (require_tool_registry.isObject(value) && "execa" in value) value = value.execa;
+	if (typeof value !== "function") throw new require_exceptions.E_INVALID_MEDIA_PIPELINE_CONFIG(["execa resolver did not resolve to a function"]);
+	return value;
+};
+/**
+* Construct the bundled local-process {@link BinaryExecutor}.
+*
+* @param options - The execa resolver and defaults.
+* @returns A `BinaryExecutor` running invocations as local child processes.
+*/
+var execaExecutor = (options = {}) => {
+	let execaPromise;
+	const getExeca = () => {
+		execaPromise ??= resolveExeca(options.execa);
+		return execaPromise;
+	};
+	return { async exec(invocation) {
+		const result = await (await getExeca())(invocation.cmd, invocation.args, {
+			timeout: invocation.timeoutMs ?? options.defaultTimeoutMs ?? 12e4,
+			cancelSignal: invocation.signal,
+			reject: false,
+			stripFinalNewline: true
+		});
+		return {
+			exitCode: result.exitCode ?? -1,
+			stdout: typeof result.stdout === "string" ? result.stdout : "",
+			stderr: typeof result.stderr === "string" ? result.stderr : "",
+			failed: result.failed
+		};
+	} };
+};
+//#endregion
+exports.execaExecutor = execaExecutor;
+
+//# sourceMappingURL=execa_executor.cjs.map

package/batteries/media/engines/execa_executor.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"execa_executor.cjs","names":[],"sources":["../../../../src/batteries/media/engines/execa_executor.ts"],"sourcesContent":["/**\n * A {@link @nhtio/adk/batteries/media/contracts!BinaryExecutor} implementation that runs\n * invocations as local child processes via execa.\n *\n * @module @nhtio/adk/batteries/media/engines/execa_executor\n *\n * @remarks\n * The bundled local-process executor. `execa` is an optional peer dependency acquired through\n * an async resolver (default: a lazy dynamic import) — importing this module pulls nothing;\n * constructing the executor is what resolves the peer, and only on first `exec`.\n *\n * Process execution is a movable seam: anything implementing the `BinaryExecutor` contract —\n * a remote runner, a sandbox, a container shim — composes into binary engines exactly like\n * this one. The paired `ScratchWorkspace` must produce paths this executor can open; for the\n * local-process case, the bundled `fs_workspace` is the natural pair.\n */\n\nimport { isError, isObject } from '@nhtio/adk/guards'\nimport { E_INVALID_MEDIA_PIPELINE_CONFIG } from '../exceptions'\nimport type { BinaryExecutor, BinaryInvocation, BinaryExecResult } from '../contracts'\n\n/** The slice of execa this executor uses (kept minimal for BYO substitution in tests). */\nexport interface ExecaLike {\n  (\n    cmd: string,\n    args: readonly string[],\n    options: {\n      timeout?: number\n      cancelSignal?: AbortSignal\n      reject: false\n      stripFinalNewline?: boolean\n    }\n  ): Promise<{\n    exitCode?: number\n    stdout?: unknown\n    stderr?: unknown\n    failed: boolean\n  }>\n}\n\n/** Resolver forms accepted for the execa module. */\nexport type ExecaResolver =\n  | ExecaLike\n  | (() => ExecaLike | { execa: ExecaLike } | Promise<ExecaLike | { execa: ExecaLike }>)\n\n/** Options for {@link execaExecutor}. */\nexport interface ExecaExecutorOptions {\n  /**\n   * The execa function or an async resolver for it. Defaults to a lazy dynamic import of the\n   * `execa` package (optional peer).\n   */\n  execa?: ExecaResolver\n  /** Default timeout applied when an invocation does not specify one. */\n  defaultTimeoutMs?: number\n}\n\nconst resolveExeca = async (supplied: ExecaResolver | undefined): Promise<ExecaLike> => {\n  let value: unknown = supplied ?? ((): Promise<{ execa: ExecaLike }> => import('execa'))\n  if (typeof value === 'function' && !('exec' in (value as object))) {\n    try {\n      value = await (value as () => unknown)()\n    } catch (err) {\n      const detail = isError(err) ? err.message : String(err)\n      throw new E_INVALID_MEDIA_PIPELINE_CONFIG([\n        `execa resolver failed: ${detail} — install the optional peer dependency \"execa\" or supply your own`,\n      ])\n    }\n  }\n  if (isObject(value) && 'execa' in value) {\n    value = (value as { execa: unknown }).execa\n  }\n  if (typeof value !== 'function') {\n    throw new E_INVALID_MEDIA_PIPELINE_CONFIG(['execa resolver did not resolve to a function'])\n  }\n  return value as ExecaLike\n}\n\n/**\n * Construct the bundled local-process {@link BinaryExecutor}.\n *\n * @param options - The execa resolver and defaults.\n * @returns A `BinaryExecutor` running invocations as local child processes.\n */\nexport const execaExecutor = (options: ExecaExecutorOptions = {}): BinaryExecutor => {\n  let execaPromise: Promise<ExecaLike> | undefined\n  const getExeca = (): Promise<ExecaLike> => {\n    execaPromise ??= resolveExeca(options.execa)\n    return execaPromise\n  }\n  return {\n    async exec(invocation: BinaryInvocation): Promise<BinaryExecResult> {\n      const execa = await getExeca()\n      const result = await execa(invocation.cmd, invocation.args, {\n        timeout: invocation.timeoutMs ?? options.defaultTimeoutMs ?? 120_000,\n        cancelSignal: invocation.signal,\n        reject: false,\n        stripFinalNewline: true,\n      })\n      return {\n        exitCode: result.exitCode ?? -1,\n        stdout: typeof result.stdout === 'string' ? result.stdout : '',\n        stderr: typeof result.stderr === 'string' ? result.stderr : '',\n        failed: result.failed,\n      }\n    },\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AAwDA,IAAM,eAAe,OAAO,aAA4D;CACtF,IAAI,QAAiB,mBAAkD,OAAO;CAC9E,IAAI,OAAO,UAAU,cAAc,EAAE,UAAW,QAC9C,IAAI;EACF,QAAQ,MAAO,MAAwB;CACzC,SAAS,KAAK;EAEZ,MAAM,IAAI,mBAAA,gCAAgC,CACxC,0BAFa,sBAAA,QAAQ,GAAG,IAAI,IAAI,UAAU,OAAO,GAAG,EAEnB,mEACnC,CAAC;CACH;CAEF,IAAI,sBAAA,SAAS,KAAK,KAAK,WAAW,OAChC,QAAS,MAA6B;CAExC,IAAI,OAAO,UAAU,YACnB,MAAM,IAAI,mBAAA,gCAAgC,CAAC,8CAA8C,CAAC;CAE5F,OAAO;AACT;;;;;;;AAQA,IAAa,iBAAiB,UAAgC,CAAC,MAAsB;CACnF,IAAI;CACJ,MAAM,iBAAqC;EACzC,iBAAiB,aAAa,QAAQ,KAAK;EAC3C,OAAO;CACT;CACA,OAAO,EACL,MAAM,KAAK,YAAyD;EAElE,MAAM,SAAS,OAAM,MADD,SAAS,GACF,WAAW,KAAK,WAAW,MAAM;GAC1D,SAAS,WAAW,aAAa,QAAQ,oBAAoB;GAC7D,cAAc,WAAW;GACzB,QAAQ;GACR,mBAAmB;EACrB,CAAC;EACD,OAAO;GACL,UAAU,OAAO,YAAY;GAC7B,QAAQ,OAAO,OAAO,WAAW,WAAW,OAAO,SAAS;GAC5D,QAAQ,OAAO,OAAO,WAAW,WAAW,OAAO,SAAS;GAC5D,QAAQ,OAAO;EACjB;CACF,EACF;AACF"}

package/batteries/media/engines/execa_executor.d.ts

@@ -0,0 +1,54 @@
+/**
+ * A {@link @nhtio/adk/batteries/media/contracts!BinaryExecutor} implementation that runs
+ * invocations as local child processes via execa.
+ *
+ * @module @nhtio/adk/batteries/media/engines/execa_executor
+ *
+ * @remarks
+ * The bundled local-process executor. `execa` is an optional peer dependency acquired through
+ * an async resolver (default: a lazy dynamic import) — importing this module pulls nothing;
+ * constructing the executor is what resolves the peer, and only on first `exec`.
+ *
+ * Process execution is a movable seam: anything implementing the `BinaryExecutor` contract —
+ * a remote runner, a sandbox, a container shim — composes into binary engines exactly like
+ * this one. The paired `ScratchWorkspace` must produce paths this executor can open; for the
+ * local-process case, the bundled `fs_workspace` is the natural pair.
+ */
+import type { BinaryExecutor } from "../contracts";
+/** The slice of execa this executor uses (kept minimal for BYO substitution in tests). */
+export interface ExecaLike {
+    (cmd: string, args: readonly string[], options: {
+        timeout?: number;
+        cancelSignal?: AbortSignal;
+        reject: false;
+        stripFinalNewline?: boolean;
+    }): Promise<{
+        exitCode?: number;
+        stdout?: unknown;
+        stderr?: unknown;
+        failed: boolean;
+    }>;
+}
+/** Resolver forms accepted for the execa module. */
+export type ExecaResolver = ExecaLike | (() => ExecaLike | {
+    execa: ExecaLike;
+} | Promise<ExecaLike | {
+    execa: ExecaLike;
+}>);
+/** Options for {@link execaExecutor}. */
+export interface ExecaExecutorOptions {
+    /**
+     * The execa function or an async resolver for it. Defaults to a lazy dynamic import of the
+     * `execa` package (optional peer).
+     */
+    execa?: ExecaResolver;
+    /** Default timeout applied when an invocation does not specify one. */
+    defaultTimeoutMs?: number;
+}
+/**
+ * Construct the bundled local-process {@link BinaryExecutor}.
+ *
+ * @param options - The execa resolver and defaults.
+ * @returns A `BinaryExecutor` running invocations as local child processes.
+ */
+export declare const execaExecutor: (options?: ExecaExecutorOptions) => BinaryExecutor;

package/batteries/media/engines/execa_executor.mjs

@@ -0,0 +1,62 @@
+import { c as isObject, o as isError } from "../../../tool_registry-791Vrjtf.mjs";
+import "../../../guards.mjs";
+import { t as E_INVALID_MEDIA_PIPELINE_CONFIG } from "../../../exceptions-C7FSHEnV.mjs";
+//#region src/batteries/media/engines/execa_executor.ts
+/**
+* A {@link @nhtio/adk/batteries/media/contracts!BinaryExecutor} implementation that runs
+* invocations as local child processes via execa.
+*
+* @module @nhtio/adk/batteries/media/engines/execa_executor
+*
+* @remarks
+* The bundled local-process executor. `execa` is an optional peer dependency acquired through
+* an async resolver (default: a lazy dynamic import) — importing this module pulls nothing;
+* constructing the executor is what resolves the peer, and only on first `exec`.
+*
+* Process execution is a movable seam: anything implementing the `BinaryExecutor` contract —
+* a remote runner, a sandbox, a container shim — composes into binary engines exactly like
+* this one. The paired `ScratchWorkspace` must produce paths this executor can open; for the
+* local-process case, the bundled `fs_workspace` is the natural pair.
+*/
+var resolveExeca = async (supplied) => {
+	let value = supplied ?? (() => import("execa"));
+	if (typeof value === "function" && !("exec" in value)) try {
+		value = await value();
+	} catch (err) {
+		throw new E_INVALID_MEDIA_PIPELINE_CONFIG([`execa resolver failed: ${isError(err) ? err.message : String(err)} — install the optional peer dependency "execa" or supply your own`]);
+	}
+	if (isObject(value) && "execa" in value) value = value.execa;
+	if (typeof value !== "function") throw new E_INVALID_MEDIA_PIPELINE_CONFIG(["execa resolver did not resolve to a function"]);
+	return value;
+};
+/**
+* Construct the bundled local-process {@link BinaryExecutor}.
+*
+* @param options - The execa resolver and defaults.
+* @returns A `BinaryExecutor` running invocations as local child processes.
+*/
+var execaExecutor = (options = {}) => {
+	let execaPromise;
+	const getExeca = () => {
+		execaPromise ??= resolveExeca(options.execa);
+		return execaPromise;
+	};
+	return { async exec(invocation) {
+		const result = await (await getExeca())(invocation.cmd, invocation.args, {
+			timeout: invocation.timeoutMs ?? options.defaultTimeoutMs ?? 12e4,
+			cancelSignal: invocation.signal,
+			reject: false,
+			stripFinalNewline: true
+		});
+		return {
+			exitCode: result.exitCode ?? -1,
+			stdout: typeof result.stdout === "string" ? result.stdout : "",
+			stderr: typeof result.stderr === "string" ? result.stderr : "",
+			failed: result.failed
+		};
+	} };
+};
+//#endregion
+export { execaExecutor };
+
+//# sourceMappingURL=execa_executor.mjs.map

package/batteries/media/engines/execa_executor.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"execa_executor.mjs","names":[],"sources":["../../../../src/batteries/media/engines/execa_executor.ts"],"sourcesContent":["/**\n * A {@link @nhtio/adk/batteries/media/contracts!BinaryExecutor} implementation that runs\n * invocations as local child processes via execa.\n *\n * @module @nhtio/adk/batteries/media/engines/execa_executor\n *\n * @remarks\n * The bundled local-process executor. `execa` is an optional peer dependency acquired through\n * an async resolver (default: a lazy dynamic import) — importing this module pulls nothing;\n * constructing the executor is what resolves the peer, and only on first `exec`.\n *\n * Process execution is a movable seam: anything implementing the `BinaryExecutor` contract —\n * a remote runner, a sandbox, a container shim — composes into binary engines exactly like\n * this one. The paired `ScratchWorkspace` must produce paths this executor can open; for the\n * local-process case, the bundled `fs_workspace` is the natural pair.\n */\n\nimport { isError, isObject } from '@nhtio/adk/guards'\nimport { E_INVALID_MEDIA_PIPELINE_CONFIG } from '../exceptions'\nimport type { BinaryExecutor, BinaryInvocation, BinaryExecResult } from '../contracts'\n\n/** The slice of execa this executor uses (kept minimal for BYO substitution in tests). */\nexport interface ExecaLike {\n  (\n    cmd: string,\n    args: readonly string[],\n    options: {\n      timeout?: number\n      cancelSignal?: AbortSignal\n      reject: false\n      stripFinalNewline?: boolean\n    }\n  ): Promise<{\n    exitCode?: number\n    stdout?: unknown\n    stderr?: unknown\n    failed: boolean\n  }>\n}\n\n/** Resolver forms accepted for the execa module. */\nexport type ExecaResolver =\n  | ExecaLike\n  | (() => ExecaLike | { execa: ExecaLike } | Promise<ExecaLike | { execa: ExecaLike }>)\n\n/** Options for {@link execaExecutor}. */\nexport interface ExecaExecutorOptions {\n  /**\n   * The execa function or an async resolver for it. Defaults to a lazy dynamic import of the\n   * `execa` package (optional peer).\n   */\n  execa?: ExecaResolver\n  /** Default timeout applied when an invocation does not specify one. */\n  defaultTimeoutMs?: number\n}\n\nconst resolveExeca = async (supplied: ExecaResolver | undefined): Promise<ExecaLike> => {\n  let value: unknown = supplied ?? ((): Promise<{ execa: ExecaLike }> => import('execa'))\n  if (typeof value === 'function' && !('exec' in (value as object))) {\n    try {\n      value = await (value as () => unknown)()\n    } catch (err) {\n      const detail = isError(err) ? err.message : String(err)\n      throw new E_INVALID_MEDIA_PIPELINE_CONFIG([\n        `execa resolver failed: ${detail} — install the optional peer dependency \"execa\" or supply your own`,\n      ])\n    }\n  }\n  if (isObject(value) && 'execa' in value) {\n    value = (value as { execa: unknown }).execa\n  }\n  if (typeof value !== 'function') {\n    throw new E_INVALID_MEDIA_PIPELINE_CONFIG(['execa resolver did not resolve to a function'])\n  }\n  return value as ExecaLike\n}\n\n/**\n * Construct the bundled local-process {@link BinaryExecutor}.\n *\n * @param options - The execa resolver and defaults.\n * @returns A `BinaryExecutor` running invocations as local child processes.\n */\nexport const execaExecutor = (options: ExecaExecutorOptions = {}): BinaryExecutor => {\n  let execaPromise: Promise<ExecaLike> | undefined\n  const getExeca = (): Promise<ExecaLike> => {\n    execaPromise ??= resolveExeca(options.execa)\n    return execaPromise\n  }\n  return {\n    async exec(invocation: BinaryInvocation): Promise<BinaryExecResult> {\n      const execa = await getExeca()\n      const result = await execa(invocation.cmd, invocation.args, {\n        timeout: invocation.timeoutMs ?? options.defaultTimeoutMs ?? 120_000,\n        cancelSignal: invocation.signal,\n        reject: false,\n        stripFinalNewline: true,\n      })\n      return {\n        exitCode: result.exitCode ?? -1,\n        stdout: typeof result.stdout === 'string' ? result.stdout : '',\n        stderr: typeof result.stderr === 'string' ? result.stderr : '',\n        failed: result.failed,\n      }\n    },\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAwDA,IAAM,eAAe,OAAO,aAA4D;CACtF,IAAI,QAAiB,mBAAkD,OAAO;CAC9E,IAAI,OAAO,UAAU,cAAc,EAAE,UAAW,QAC9C,IAAI;EACF,QAAQ,MAAO,MAAwB;CACzC,SAAS,KAAK;EAEZ,MAAM,IAAI,gCAAgC,CACxC,0BAFa,QAAQ,GAAG,IAAI,IAAI,UAAU,OAAO,GAAG,EAEnB,mEACnC,CAAC;CACH;CAEF,IAAI,SAAS,KAAK,KAAK,WAAW,OAChC,QAAS,MAA6B;CAExC,IAAI,OAAO,UAAU,YACnB,MAAM,IAAI,gCAAgC,CAAC,8CAA8C,CAAC;CAE5F,OAAO;AACT;;;;;;;AAQA,IAAa,iBAAiB,UAAgC,CAAC,MAAsB;CACnF,IAAI;CACJ,MAAM,iBAAqC;EACzC,iBAAiB,aAAa,QAAQ,KAAK;EAC3C,OAAO;CACT;CACA,OAAO,EACL,MAAM,KAAK,YAAyD;EAElE,MAAM,SAAS,OAAM,MADD,SAAS,GACF,WAAW,KAAK,WAAW,MAAM;GAC1D,SAAS,WAAW,aAAa,QAAQ,oBAAoB;GAC7D,cAAc,WAAW;GACzB,QAAQ;GACR,mBAAmB;EACrB,CAAC;EACD,OAAO;GACL,UAAU,OAAO,YAAY;GAC7B,QAAQ,OAAO,OAAO,WAAW,WAAW,OAAO,SAAS;GAC5D,QAAQ,OAAO,OAAO,WAAW,WAAW,OAAO,SAAS;GAC5D,QAAQ,OAAO;EACjB;CACF,EACF;AACF"}

package/batteries/media/engines/fs_workspace.cjs

@@ -0,0 +1,84 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+require("../../../chunk-Ble4zEEl.js");
+const require_tool_registry = require("../../../tool_registry-CKJPze3j.js");
+require("../../../guards.cjs");
+const require_exceptions = require("../../../exceptions-CQi_lNs1.js");
+//#region src/batteries/media/engines/fs_workspace.ts
+/**
+* A {@link @nhtio/adk/batteries/media/contracts!ScratchWorkspace} implementation backed by the
+* local filesystem via `node:fs/promises`.
+*
+* @module @nhtio/adk/batteries/media/engines/fs_workspace
+*
+* @remarks
+* The bundled filesystem workspace. `node:fs/promises` is acquired through an async resolver
+* (default: a lazy dynamic import) so this module carries no static `node:*` import and the
+* builtin loads only when a workspace is actually minted.
+*
+* The factory requires an explicit `root` directory — there is no `os.tmpdir()` silent
+* default. Each minted workspace is a fresh unique subdirectory of `root`, removed on
+* `dispose()`. Any BYO implementation whose paths the paired `BinaryExecutor` can open
+* satisfies the same contract (tmpfs mounts, container volumes, sandbox dirs…).
+*/
+var resolveFs = async (supplied) => {
+	let value = supplied ?? (() => import("node:fs/promises"));
+	if (typeof value === "function") try {
+		value = await value();
+	} catch (err) {
+		throw new require_exceptions.E_INVALID_MEDIA_PIPELINE_CONFIG([`fs resolver failed: ${require_tool_registry.isError(err) ? err.message : String(err)}`]);
+	}
+	if (value === null || typeof value !== "object" || typeof value.writeFile !== "function") throw new require_exceptions.E_INVALID_MEDIA_PIPELINE_CONFIG(["fs resolver did not resolve to a node:fs/promises-compatible module"]);
+	return value;
+};
+var counter = 0;
+var uniqueName = () => {
+	counter = (counter + 1) % Number.MAX_SAFE_INTEGER;
+	return `media-${Array.from(crypto.getRandomValues(new Uint8Array(6))).map((b) => b.toString(16).padStart(2, "0")).join("")}-${counter}`;
+};
+var joinPath = (...parts) => parts.join("/").replace(/\/{2,}/g, "/");
+/**
+* Construct a {@link ScratchWorkspaceFactory} minting per-invocation directories under `root`.
+*
+* @param options - The root directory and fs resolver.
+* @returns A factory binary engines call once per invocation.
+*/
+var fsScratchWorkspace = (options) => {
+	if (typeof options?.root !== "string" || options.root.length === 0) throw new require_exceptions.E_INVALID_MEDIA_PIPELINE_CONFIG(["fsScratchWorkspace requires an explicit root directory (no platform default)"]);
+	let fsPromise;
+	const getFs = () => {
+		fsPromise ??= resolveFs(options.fs);
+		return fsPromise;
+	};
+	return async () => {
+		const fs = await getFs();
+		const dir = joinPath(options.root, uniqueName());
+		await fs.mkdir(dir, { recursive: true });
+		return {
+			async materialize(bytes, filename) {
+				const path = joinPath(dir, filename.replace(/[/\\]/g, "_"));
+				await fs.writeFile(path, bytes);
+				return path;
+			},
+			async read(path) {
+				const bytes = await fs.readFile(path);
+				return require_tool_registry.isInstanceOf(bytes, "Uint8Array", Uint8Array) ? bytes : new Uint8Array(bytes);
+			},
+			dir() {
+				return dir;
+			},
+			async list() {
+				return fs.readdir(dir);
+			},
+			async dispose() {
+				await fs.rm(dir, {
+					recursive: true,
+					force: true
+				});
+			}
+		};
+	};
+};
+//#endregion
+exports.fsScratchWorkspace = fsScratchWorkspace;
+
+//# sourceMappingURL=fs_workspace.cjs.map

package/batteries/media/engines/fs_workspace.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs_workspace.cjs","names":[],"sources":["../../../../src/batteries/media/engines/fs_workspace.ts"],"sourcesContent":["/**\n * A {@link @nhtio/adk/batteries/media/contracts!ScratchWorkspace} implementation backed by the\n * local filesystem via `node:fs/promises`.\n *\n * @module @nhtio/adk/batteries/media/engines/fs_workspace\n *\n * @remarks\n * The bundled filesystem workspace. `node:fs/promises` is acquired through an async resolver\n * (default: a lazy dynamic import) so this module carries no static `node:*` import and the\n * builtin loads only when a workspace is actually minted.\n *\n * The factory requires an explicit `root` directory — there is no `os.tmpdir()` silent\n * default. Each minted workspace is a fresh unique subdirectory of `root`, removed on\n * `dispose()`. Any BYO implementation whose paths the paired `BinaryExecutor` can open\n * satisfies the same contract (tmpfs mounts, container volumes, sandbox dirs…).\n */\n\nimport { isError, isInstanceOf } from '@nhtio/adk/guards'\nimport { E_INVALID_MEDIA_PIPELINE_CONFIG } from '../exceptions'\nimport type { ScratchWorkspace, ScratchWorkspaceFactory } from '../contracts'\n\n/** The slice of `node:fs/promises` the workspace uses. */\nexport interface FsLike {\n  /** Create a directory (recursively). */\n  mkdir(path: string, options: { recursive: true }): Promise<unknown>\n  /** Write bytes to a path. */\n  writeFile(path: string, data: Uint8Array): Promise<void>\n  /** Read a file's bytes. */\n  readFile(path: string): Promise<Uint8Array>\n  /** List directory entries (basenames). */\n  readdir(path: string): Promise<string[]>\n  /** Remove a path recursively, ignoring absence. */\n  rm(path: string, options: { recursive: true; force: true }): Promise<void>\n}\n\n/** Resolver forms accepted for the fs module. */\nexport type FsResolver = FsLike | (() => FsLike | Promise<FsLike>)\n\n/** Options for {@link fsScratchWorkspace}. */\nexport interface FsScratchWorkspaceOptions {\n  /** The directory all workspaces are minted under. Required — no platform default. */\n  root: string\n  /** The fs module or a resolver for it. Defaults to a lazy `import('node:fs/promises')`. */\n  fs?: FsResolver\n}\n\nconst resolveFs = async (supplied: FsResolver | undefined): Promise<FsLike> => {\n  let value: unknown = supplied ?? ((): Promise<FsLike> => import('node:fs/promises'))\n  if (typeof value === 'function') {\n    try {\n      value = await (value as () => unknown)()\n    } catch (err) {\n      const detail = isError(err) ? err.message : String(err)\n      throw new E_INVALID_MEDIA_PIPELINE_CONFIG([`fs resolver failed: ${detail}`])\n    }\n  }\n  if (\n    value === null ||\n    typeof value !== 'object' ||\n    typeof (value as FsLike).writeFile !== 'function'\n  ) {\n    throw new E_INVALID_MEDIA_PIPELINE_CONFIG([\n      'fs resolver did not resolve to a node:fs/promises-compatible module',\n    ])\n  }\n  return value as FsLike\n}\n\nlet counter = 0\nconst uniqueName = (): string => {\n  counter = (counter + 1) % Number.MAX_SAFE_INTEGER\n  const rand = Array.from(crypto.getRandomValues(new Uint8Array(6)))\n    .map((b) => b.toString(16).padStart(2, '0'))\n    .join('')\n  return `media-${rand}-${counter}`\n}\n\nconst joinPath = (...parts: string[]): string => parts.join('/').replace(/\\/{2,}/g, '/')\n\n/**\n * Construct a {@link ScratchWorkspaceFactory} minting per-invocation directories under `root`.\n *\n * @param options - The root directory and fs resolver.\n * @returns A factory binary engines call once per invocation.\n */\nexport const fsScratchWorkspace = (options: FsScratchWorkspaceOptions): ScratchWorkspaceFactory => {\n  if (typeof options?.root !== 'string' || options.root.length === 0) {\n    throw new E_INVALID_MEDIA_PIPELINE_CONFIG([\n      'fsScratchWorkspace requires an explicit root directory (no platform default)',\n    ])\n  }\n  let fsPromise: Promise<FsLike> | undefined\n  const getFs = (): Promise<FsLike> => {\n    fsPromise ??= resolveFs(options.fs)\n    return fsPromise\n  }\n\n  return async (): Promise<ScratchWorkspace> => {\n    const fs = await getFs()\n    const dir = joinPath(options.root, uniqueName())\n    await fs.mkdir(dir, { recursive: true })\n    return {\n      async materialize(bytes: Uint8Array, filename: string): Promise<string> {\n        const safe = filename.replace(/[/\\\\]/g, '_')\n        const path = joinPath(dir, safe)\n        await fs.writeFile(path, bytes)\n        return path\n      },\n      async read(path: string): Promise<Uint8Array> {\n        const bytes = await fs.readFile(path)\n        return isInstanceOf(bytes, 'Uint8Array', Uint8Array) ? bytes : new Uint8Array(bytes)\n      },\n      dir(): string {\n        return dir\n      },\n      async list(): Promise<string[]> {\n        return fs.readdir(dir)\n      },\n      async dispose(): Promise<void> {\n        await fs.rm(dir, { recursive: true, force: true })\n      },\n    }\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AA8CA,IAAM,YAAY,OAAO,aAAsD;CAC7E,IAAI,QAAiB,mBAAoC,OAAO;CAChE,IAAI,OAAO,UAAU,YACnB,IAAI;EACF,QAAQ,MAAO,MAAwB;CACzC,SAAS,KAAK;EAEZ,MAAM,IAAI,mBAAA,gCAAgC,CAAC,uBAD5B,sBAAA,QAAQ,GAAG,IAAI,IAAI,UAAU,OAAO,GAAG,GACoB,CAAC;CAC7E;CAEF,IACE,UAAU,QACV,OAAO,UAAU,YACjB,OAAQ,MAAiB,cAAc,YAEvC,MAAM,IAAI,mBAAA,gCAAgC,CACxC,qEACF,CAAC;CAEH,OAAO;AACT;AAEA,IAAI,UAAU;AACd,IAAM,mBAA2B;CAC/B,WAAW,UAAU,KAAK,OAAO;CAIjC,OAAO,SAHM,MAAM,KAAK,OAAO,gBAAgB,IAAI,WAAW,CAAC,CAAC,CAAC,EAC9D,KAAK,MAAM,EAAE,SAAS,EAAE,EAAE,SAAS,GAAG,GAAG,CAAC,EAC1C,KAAK,EACQ,EAAK,GAAG;AAC1B;AAEA,IAAM,YAAY,GAAG,UAA4B,MAAM,KAAK,GAAG,EAAE,QAAQ,WAAW,GAAG;;;;;;;AAQvF,IAAa,sBAAsB,YAAgE;CACjG,IAAI,OAAO,SAAS,SAAS,YAAY,QAAQ,KAAK,WAAW,GAC/D,MAAM,IAAI,mBAAA,gCAAgC,CACxC,8EACF,CAAC;CAEH,IAAI;CACJ,MAAM,cAA+B;EACnC,cAAc,UAAU,QAAQ,EAAE;EAClC,OAAO;CACT;CAEA,OAAO,YAAuC;EAC5C,MAAM,KAAK,MAAM,MAAM;EACvB,MAAM,MAAM,SAAS,QAAQ,MAAM,WAAW,CAAC;EAC/C,MAAM,GAAG,MAAM,KAAK,EAAE,WAAW,KAAK,CAAC;EACvC,OAAO;GACL,MAAM,YAAY,OAAmB,UAAmC;IAEtE,MAAM,OAAO,SAAS,KADT,SAAS,QAAQ,UAAU,GACb,CAAI;IAC/B,MAAM,GAAG,UAAU,MAAM,KAAK;IAC9B,OAAO;GACT;GACA,MAAM,KAAK,MAAmC;IAC5C,MAAM,QAAQ,MAAM,GAAG,SAAS,IAAI;IACpC,OAAO,sBAAA,aAAa,OAAO,cAAc,UAAU,IAAI,QAAQ,IAAI,WAAW,KAAK;GACrF;GACA,MAAc;IACZ,OAAO;GACT;GACA,MAAM,OAA0B;IAC9B,OAAO,GAAG,QAAQ,GAAG;GACvB;GACA,MAAM,UAAyB;IAC7B,MAAM,GAAG,GAAG,KAAK;KAAE,WAAW;KAAM,OAAO;IAAK,CAAC;GACnD;EACF;CACF;AACF"}

package/batteries/media/engines/fs_workspace.d.ts

@@ -0,0 +1,51 @@
+/**
+ * A {@link @nhtio/adk/batteries/media/contracts!ScratchWorkspace} implementation backed by the
+ * local filesystem via `node:fs/promises`.
+ *
+ * @module @nhtio/adk/batteries/media/engines/fs_workspace
+ *
+ * @remarks
+ * The bundled filesystem workspace. `node:fs/promises` is acquired through an async resolver
+ * (default: a lazy dynamic import) so this module carries no static `node:*` import and the
+ * builtin loads only when a workspace is actually minted.
+ *
+ * The factory requires an explicit `root` directory — there is no `os.tmpdir()` silent
+ * default. Each minted workspace is a fresh unique subdirectory of `root`, removed on
+ * `dispose()`. Any BYO implementation whose paths the paired `BinaryExecutor` can open
+ * satisfies the same contract (tmpfs mounts, container volumes, sandbox dirs…).
+ */
+import type { ScratchWorkspaceFactory } from "../contracts";
+/** The slice of `node:fs/promises` the workspace uses. */
+export interface FsLike {
+    /** Create a directory (recursively). */
+    mkdir(path: string, options: {
+        recursive: true;
+    }): Promise<unknown>;
+    /** Write bytes to a path. */
+    writeFile(path: string, data: Uint8Array): Promise<void>;
+    /** Read a file's bytes. */
+    readFile(path: string): Promise<Uint8Array>;
+    /** List directory entries (basenames). */
+    readdir(path: string): Promise<string[]>;
+    /** Remove a path recursively, ignoring absence. */
+    rm(path: string, options: {
+        recursive: true;
+        force: true;
+    }): Promise<void>;
+}
+/** Resolver forms accepted for the fs module. */
+export type FsResolver = FsLike | (() => FsLike | Promise<FsLike>);
+/** Options for {@link fsScratchWorkspace}. */
+export interface FsScratchWorkspaceOptions {
+    /** The directory all workspaces are minted under. Required — no platform default. */
+    root: string;
+    /** The fs module or a resolver for it. Defaults to a lazy `import('node:fs/promises')`. */
+    fs?: FsResolver;
+}
+/**
+ * Construct a {@link ScratchWorkspaceFactory} minting per-invocation directories under `root`.
+ *
+ * @param options - The root directory and fs resolver.
+ * @returns A factory binary engines call once per invocation.
+ */
+export declare const fsScratchWorkspace: (options: FsScratchWorkspaceOptions) => ScratchWorkspaceFactory;

package/batteries/media/engines/fs_workspace.mjs

@@ -0,0 +1,82 @@
+import { o as isError, s as isInstanceOf } from "../../../tool_registry-791Vrjtf.mjs";
+import "../../../guards.mjs";
+import { t as E_INVALID_MEDIA_PIPELINE_CONFIG } from "../../../exceptions-C7FSHEnV.mjs";
+//#region src/batteries/media/engines/fs_workspace.ts
+/**
+* A {@link @nhtio/adk/batteries/media/contracts!ScratchWorkspace} implementation backed by the
+* local filesystem via `node:fs/promises`.
+*
+* @module @nhtio/adk/batteries/media/engines/fs_workspace
+*
+* @remarks
+* The bundled filesystem workspace. `node:fs/promises` is acquired through an async resolver
+* (default: a lazy dynamic import) so this module carries no static `node:*` import and the
+* builtin loads only when a workspace is actually minted.
+*
+* The factory requires an explicit `root` directory — there is no `os.tmpdir()` silent
+* default. Each minted workspace is a fresh unique subdirectory of `root`, removed on
+* `dispose()`. Any BYO implementation whose paths the paired `BinaryExecutor` can open
+* satisfies the same contract (tmpfs mounts, container volumes, sandbox dirs…).
+*/
+var resolveFs = async (supplied) => {
+	let value = supplied ?? (() => import("node:fs/promises"));
+	if (typeof value === "function") try {
+		value = await value();
+	} catch (err) {
+		throw new E_INVALID_MEDIA_PIPELINE_CONFIG([`fs resolver failed: ${isError(err) ? err.message : String(err)}`]);
+	}
+	if (value === null || typeof value !== "object" || typeof value.writeFile !== "function") throw new E_INVALID_MEDIA_PIPELINE_CONFIG(["fs resolver did not resolve to a node:fs/promises-compatible module"]);
+	return value;
+};
+var counter = 0;
+var uniqueName = () => {
+	counter = (counter + 1) % Number.MAX_SAFE_INTEGER;
+	return `media-${Array.from(crypto.getRandomValues(new Uint8Array(6))).map((b) => b.toString(16).padStart(2, "0")).join("")}-${counter}`;
+};
+var joinPath = (...parts) => parts.join("/").replace(/\/{2,}/g, "/");
+/**
+* Construct a {@link ScratchWorkspaceFactory} minting per-invocation directories under `root`.
+*
+* @param options - The root directory and fs resolver.
+* @returns A factory binary engines call once per invocation.
+*/
+var fsScratchWorkspace = (options) => {
+	if (typeof options?.root !== "string" || options.root.length === 0) throw new E_INVALID_MEDIA_PIPELINE_CONFIG(["fsScratchWorkspace requires an explicit root directory (no platform default)"]);
+	let fsPromise;
+	const getFs = () => {
+		fsPromise ??= resolveFs(options.fs);
+		return fsPromise;
+	};
+	return async () => {
+		const fs = await getFs();
+		const dir = joinPath(options.root, uniqueName());
+		await fs.mkdir(dir, { recursive: true });
+		return {
+			async materialize(bytes, filename) {
+				const path = joinPath(dir, filename.replace(/[/\\]/g, "_"));
+				await fs.writeFile(path, bytes);
+				return path;
+			},
+			async read(path) {
+				const bytes = await fs.readFile(path);
+				return isInstanceOf(bytes, "Uint8Array", Uint8Array) ? bytes : new Uint8Array(bytes);
+			},
+			dir() {
+				return dir;
+			},
+			async list() {
+				return fs.readdir(dir);
+			},
+			async dispose() {
+				await fs.rm(dir, {
+					recursive: true,
+					force: true
+				});
+			}
+		};
+	};
+};
+//#endregion
+export { fsScratchWorkspace };
+
+//# sourceMappingURL=fs_workspace.mjs.map

package/batteries/media/engines/fs_workspace.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs_workspace.mjs","names":[],"sources":["../../../../src/batteries/media/engines/fs_workspace.ts"],"sourcesContent":["/**\n * A {@link @nhtio/adk/batteries/media/contracts!ScratchWorkspace} implementation backed by the\n * local filesystem via `node:fs/promises`.\n *\n * @module @nhtio/adk/batteries/media/engines/fs_workspace\n *\n * @remarks\n * The bundled filesystem workspace. `node:fs/promises` is acquired through an async resolver\n * (default: a lazy dynamic import) so this module carries no static `node:*` import and the\n * builtin loads only when a workspace is actually minted.\n *\n * The factory requires an explicit `root` directory — there is no `os.tmpdir()` silent\n * default. Each minted workspace is a fresh unique subdirectory of `root`, removed on\n * `dispose()`. Any BYO implementation whose paths the paired `BinaryExecutor` can open\n * satisfies the same contract (tmpfs mounts, container volumes, sandbox dirs…).\n */\n\nimport { isError, isInstanceOf } from '@nhtio/adk/guards'\nimport { E_INVALID_MEDIA_PIPELINE_CONFIG } from '../exceptions'\nimport type { ScratchWorkspace, ScratchWorkspaceFactory } from '../contracts'\n\n/** The slice of `node:fs/promises` the workspace uses. */\nexport interface FsLike {\n  /** Create a directory (recursively). */\n  mkdir(path: string, options: { recursive: true }): Promise<unknown>\n  /** Write bytes to a path. */\n  writeFile(path: string, data: Uint8Array): Promise<void>\n  /** Read a file's bytes. */\n  readFile(path: string): Promise<Uint8Array>\n  /** List directory entries (basenames). */\n  readdir(path: string): Promise<string[]>\n  /** Remove a path recursively, ignoring absence. */\n  rm(path: string, options: { recursive: true; force: true }): Promise<void>\n}\n\n/** Resolver forms accepted for the fs module. */\nexport type FsResolver = FsLike | (() => FsLike | Promise<FsLike>)\n\n/** Options for {@link fsScratchWorkspace}. */\nexport interface FsScratchWorkspaceOptions {\n  /** The directory all workspaces are minted under. Required — no platform default. */\n  root: string\n  /** The fs module or a resolver for it. Defaults to a lazy `import('node:fs/promises')`. */\n  fs?: FsResolver\n}\n\nconst resolveFs = async (supplied: FsResolver | undefined): Promise<FsLike> => {\n  let value: unknown = supplied ?? ((): Promise<FsLike> => import('node:fs/promises'))\n  if (typeof value === 'function') {\n    try {\n      value = await (value as () => unknown)()\n    } catch (err) {\n      const detail = isError(err) ? err.message : String(err)\n      throw new E_INVALID_MEDIA_PIPELINE_CONFIG([`fs resolver failed: ${detail}`])\n    }\n  }\n  if (\n    value === null ||\n    typeof value !== 'object' ||\n    typeof (value as FsLike).writeFile !== 'function'\n  ) {\n    throw new E_INVALID_MEDIA_PIPELINE_CONFIG([\n      'fs resolver did not resolve to a node:fs/promises-compatible module',\n    ])\n  }\n  return value as FsLike\n}\n\nlet counter = 0\nconst uniqueName = (): string => {\n  counter = (counter + 1) % Number.MAX_SAFE_INTEGER\n  const rand = Array.from(crypto.getRandomValues(new Uint8Array(6)))\n    .map((b) => b.toString(16).padStart(2, '0'))\n    .join('')\n  return `media-${rand}-${counter}`\n}\n\nconst joinPath = (...parts: string[]): string => parts.join('/').replace(/\\/{2,}/g, '/')\n\n/**\n * Construct a {@link ScratchWorkspaceFactory} minting per-invocation directories under `root`.\n *\n * @param options - The root directory and fs resolver.\n * @returns A factory binary engines call once per invocation.\n */\nexport const fsScratchWorkspace = (options: FsScratchWorkspaceOptions): ScratchWorkspaceFactory => {\n  if (typeof options?.root !== 'string' || options.root.length === 0) {\n    throw new E_INVALID_MEDIA_PIPELINE_CONFIG([\n      'fsScratchWorkspace requires an explicit root directory (no platform default)',\n    ])\n  }\n  let fsPromise: Promise<FsLike> | undefined\n  const getFs = (): Promise<FsLike> => {\n    fsPromise ??= resolveFs(options.fs)\n    return fsPromise\n  }\n\n  return async (): Promise<ScratchWorkspace> => {\n    const fs = await getFs()\n    const dir = joinPath(options.root, uniqueName())\n    await fs.mkdir(dir, { recursive: true })\n    return {\n      async materialize(bytes: Uint8Array, filename: string): Promise<string> {\n        const safe = filename.replace(/[/\\\\]/g, '_')\n        const path = joinPath(dir, safe)\n        await fs.writeFile(path, bytes)\n        return path\n      },\n      async read(path: string): Promise<Uint8Array> {\n        const bytes = await fs.readFile(path)\n        return isInstanceOf(bytes, 'Uint8Array', Uint8Array) ? bytes : new Uint8Array(bytes)\n      },\n      dir(): string {\n        return dir\n      },\n      async list(): Promise<string[]> {\n        return fs.readdir(dir)\n      },\n      async dispose(): Promise<void> {\n        await fs.rm(dir, { recursive: true, force: true })\n      },\n    }\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AA8CA,IAAM,YAAY,OAAO,aAAsD;CAC7E,IAAI,QAAiB,mBAAoC,OAAO;CAChE,IAAI,OAAO,UAAU,YACnB,IAAI;EACF,QAAQ,MAAO,MAAwB;CACzC,SAAS,KAAK;EAEZ,MAAM,IAAI,gCAAgC,CAAC,uBAD5B,QAAQ,GAAG,IAAI,IAAI,UAAU,OAAO,GAAG,GACoB,CAAC;CAC7E;CAEF,IACE,UAAU,QACV,OAAO,UAAU,YACjB,OAAQ,MAAiB,cAAc,YAEvC,MAAM,IAAI,gCAAgC,CACxC,qEACF,CAAC;CAEH,OAAO;AACT;AAEA,IAAI,UAAU;AACd,IAAM,mBAA2B;CAC/B,WAAW,UAAU,KAAK,OAAO;CAIjC,OAAO,SAHM,MAAM,KAAK,OAAO,gBAAgB,IAAI,WAAW,CAAC,CAAC,CAAC,EAC9D,KAAK,MAAM,EAAE,SAAS,EAAE,EAAE,SAAS,GAAG,GAAG,CAAC,EAC1C,KAAK,EACQ,EAAK,GAAG;AAC1B;AAEA,IAAM,YAAY,GAAG,UAA4B,MAAM,KAAK,GAAG,EAAE,QAAQ,WAAW,GAAG;;;;;;;AAQvF,IAAa,sBAAsB,YAAgE;CACjG,IAAI,OAAO,SAAS,SAAS,YAAY,QAAQ,KAAK,WAAW,GAC/D,MAAM,IAAI,gCAAgC,CACxC,8EACF,CAAC;CAEH,IAAI;CACJ,MAAM,cAA+B;EACnC,cAAc,UAAU,QAAQ,EAAE;EAClC,OAAO;CACT;CAEA,OAAO,YAAuC;EAC5C,MAAM,KAAK,MAAM,MAAM;EACvB,MAAM,MAAM,SAAS,QAAQ,MAAM,WAAW,CAAC;EAC/C,MAAM,GAAG,MAAM,KAAK,EAAE,WAAW,KAAK,CAAC;EACvC,OAAO;GACL,MAAM,YAAY,OAAmB,UAAmC;IAEtE,MAAM,OAAO,SAAS,KADT,SAAS,QAAQ,UAAU,GACb,CAAI;IAC/B,MAAM,GAAG,UAAU,MAAM,KAAK;IAC9B,OAAO;GACT;GACA,MAAM,KAAK,MAAmC;IAC5C,MAAM,QAAQ,MAAM,GAAG,SAAS,IAAI;IACpC,OAAO,aAAa,OAAO,cAAc,UAAU,IAAI,QAAQ,IAAI,WAAW,KAAK;GACrF;GACA,MAAc;IACZ,OAAO;GACT;GACA,MAAM,OAA0B;IAC9B,OAAO,GAAG,QAAQ,GAAG;GACvB;GACA,MAAM,UAAyB;IAC7B,MAAM,GAAG,GAAG,KAAK;KAAE,WAAW;KAAM,OAAO;IAAK,CAAC;GACnD;EACF;CACF;AACF"}