@camstack/types 1.2.391 → 1.2.392

package/dist/deps/archive-extract.d.ts

@@ -1,4 +1,5 @@
-export type ArchiveFormat = 'zip' | 'tar.gz' | 'tar.xz';
+/** `tar` = an uncompressed tarball (a `.deb` payload this module already decompressed). */
+export type ArchiveFormat = 'zip' | 'tar.gz' | 'tar.xz' | 'tar';
 export type ExecFile = (file: string, args: readonly string[]) => unknown;
 export interface ExtractDeps {
     readonly platform: NodeJS.Platform;

package/dist/deps/deb-extract.d.ts

@@ -0,0 +1,34 @@
+import { type ArchiveFormat } from './archive-extract.js';
+/** The host-tar step, injectable so a spec can see what it is handed. */
+export type TarExtract = (archivePath: string, format: ArchiveFormat, destDir: string) => void;
+export interface ArMember {
+    readonly name: string;
+    readonly data: Buffer;
+}
+/** Every member of an `ar` archive, in order. Throws on anything that is not one. */
+export declare function readArMembers(archive: Buffer): readonly ArMember[];
+export type DebPayloadCompression = 'zst' | 'xz' | 'gz' | 'none';
+export interface DebPayload {
+    readonly compression: DebPayloadCompression;
+    readonly data: Buffer;
+}
+/** The `data.tar.*` member of a `.deb`, with the compression its name declares. */
+export declare function debDataMember(deb: Buffer): DebPayload;
+/**
+ * Unpack a `.deb`'s payload into `destDir` (the package's own tree: `usr/lib/…`).
+ * zstd and gzip are decompressed in-process; the plain tar and the xz payload
+ * are expanded by the host `tar`.
+ */
+export declare function extractDebPayload(deb: Buffer, destDir: string, workDir: string, extract?: TarExtract): void;
+/**
+ * The first entry named exactly `name` under `dir` — a regular file OR a
+ * symlink: a library's soname (`libusb-1.0.so.0`) is a link to the versioned
+ * file in every package, so a file-only search never finds it.
+ */
+export declare function findEntryByName(dir: string, name: string): string | null;
+/**
+ * Copy the library `memberName` out of the `.deb` at `debPath` to `targetPath`,
+ * dereferencing the soname link to the real file. Throws, naming the member,
+ * when the package does not carry it.
+ */
+export declare function installLibraryFromDeb(debPath: string, memberName: string, targetPath: string, workDir: string, extract?: TarExtract): void;

package/dist/deps/edgetpu-delegate.d.ts

@@ -0,0 +1,83 @@
+import type { IScopedLogger } from '../interfaces/logging.js';
+/** The path override (a library PATH, never a secret). */
+export declare const EDGETPU_LIB_ENV = "CAMSTACK_EDGETPU_LIB";
+/** The pinned feranick release. Changing it is the delegate version change. */
+export declare const EDGETPU_DELEGATE_RELEASE: '16.0TF2.17.1-1';
+/** Where the hub image's installer has always put the delegate. */
+export declare const LEGACY_EDGETPU_LIB = "/data/deps/edgetpu/lib/libedgetpu.so.1";
+/** One file of the delegate set: where it comes from and the name it is staged as. */
+export interface EdgetpuStagedFile {
+    readonly url: string;
+    /** SHA-256 of the downloaded container, verified before a byte is extracted. */
+    readonly sha256: string;
+    readonly sizeBytes: number;
+    readonly container: 'deb' | 'zip';
+    /** deb: the library's file name inside the payload; zip: its path inside the archive. */
+    readonly member: string;
+    /** The name it is staged as in `<deps>/edgetpu/lib/`. */
+    readonly installAs: string;
+}
+export type EdgetpuDelegateArtifact = {
+    readonly supported: true;
+    /** The delegate first; libusb (Linux) after it. */
+    readonly files: readonly EdgetpuStagedFile[];
+} | {
+    readonly supported: false;
+    readonly reason: string;
+};
+/** The pinned delegate set for a platform and arch, or why there is none. */
+export declare function getEdgetpuDelegateArtifact(platform: NodeJS.Platform, arch: string): EdgetpuDelegateArtifact;
+/** The delegate's file name on a platform (what the Python pool loads). */
+export declare function edgetpuDelegateFileName(platform: NodeJS.Platform): string;
+/** `<dataDir>/deps/edgetpu/lib` — where the deps downloader stages the set. */
+export declare function edgetpuLibDir(dataDir: string): string;
+export type EdgetpuDelegateOrigin = 'override' | 'staged' | 'legacy';
+export interface EdgetpuDelegateChoice {
+    readonly path: string;
+    readonly origin: EdgetpuDelegateOrigin;
+}
+export interface EdgetpuDelegateLookup {
+    readonly platform: NodeJS.Platform;
+    /** The node data root (`CAMSTACK_DATA`), or `undefined` when unknown. */
+    readonly dataDir: string | undefined;
+    /** `CAMSTACK_EDGETPU_LIB`, verbatim. */
+    readonly override: string | undefined;
+    readonly exists: (path: string) => boolean;
+}
+/**
+ * The delegate this node loads, or `null` when none is present. An override
+ * that names a missing file is NOT followed past: the operator said where it
+ * is, and a silent fallback would load a different build than they chose.
+ */
+export declare function chooseEdgetpuDelegate(lookup: EdgetpuDelegateLookup): EdgetpuDelegateChoice | null;
+/** The node data root the way every node process names it. */
+export declare function nodeDataRootFromEnv(env: NodeJS.ProcessEnv): string | undefined;
+export type EdgetpuDelegateResult = {
+    readonly kind: 'ready';
+    readonly path: string;
+    readonly origin: EdgetpuDelegateOrigin | 'downloaded';
+} | {
+    readonly kind: 'unavailable';
+    readonly reason: string;
+};
+/**
+ * A requirements file names the native library its packages cannot run
+ * without on this line; `installPythonRequirements` stages it after pip.
+ * (`ai-edge-litert` imports without the delegate and is useless without it.)
+ */
+export declare const EDGETPU_DELEGATE_DIRECTIVE = "# camstack-native-dep: edgetpu-delegate";
+export declare function declaresEdgetpuDelegate(requirementsText: string): boolean;
+export interface EnsureEdgetpuDelegateOptions {
+    readonly env?: NodeJS.ProcessEnv;
+    /** The host, for a spec; defaults to this process's. */
+    readonly platform?: NodeJS.Platform;
+    readonly arch?: string;
+}
+/**
+ * The delegate this node loads, staging the pinned set under
+ * `<dataDir>/deps/edgetpu/lib/` when nothing is present yet. Never throws for
+ * a platform without a build — it answers `unavailable` with the reason; a
+ * download or checksum failure throws, naming the file. The line it logs says
+ * which delegate (and from where) the pool will load.
+ */
+export declare function ensureEdgetpuDelegate(dataDir: string, logger: IScopedLogger, opts?: EnsureEdgetpuDelegateOptions): Promise<EdgetpuDelegateResult>;

package/dist/node.d.ts

@@ -3,16 +3,18 @@ export { buildBinaryPath, downloadBinary, ensureBinary, findInPath, getPlatformI
 export { ensureFfmpeg } from './deps/ffmpeg-downloader.js';
 export type { OwnerOnlyDeps } from './util/owner-only-file.js';
 export { icaclsArgs, mkdirOwnerOnlySync, OwnerOnlyError, restrictDirToOwnerSync, restrictFileToOwnerSync, writeOwnerOnlyFileSync, } from './util/owner-only-file.js';
-export { FFMPEG_RELEASE, getFfmpegArtifact, getFfmpegDownloadUrl } from './deps/ffmpeg-artifacts.js';
+export { FFMPEG_RELEASE, getFfmpegArtifact, getFfmpegDownloadUrl, } from './deps/ffmpeg-artifacts.js';
 export { probeFfmpegBinary, parseFfmpegCapabilities, type FfmpegBinaryCapabilities, } from './ffmpeg/binary-capabilities.js';
 export { ensurePython, getPythonDownloadUrl, installPythonPackages, installPythonRequirements, PYTHON_VERSION, } from './deps/python-downloader.js';
+export { chooseEdgetpuDelegate, declaresEdgetpuDelegate, EDGETPU_DELEGATE_DIRECTIVE, EDGETPU_DELEGATE_RELEASE, EDGETPU_LIB_ENV, edgetpuDelegateFileName, edgetpuLibDir, ensureEdgetpuDelegate, getEdgetpuDelegateArtifact, LEGACY_EDGETPU_LIB, nodeDataRootFromEnv, type EdgetpuDelegateArtifact, type EdgetpuDelegateChoice, type EdgetpuDelegateLookup, type EdgetpuDelegateOrigin, type EdgetpuDelegateResult, type EdgetpuStagedFile, type EnsureEdgetpuDelegateOptions, } from './deps/edgetpu-delegate.js';
+export { debDataMember, extractDebPayload, installLibraryFromDeb, readArMembers, } from './deps/deb-extract.js';
 export type { Fmp4FragmentChildArgs, Fmp4FragmentChildDeps, } from './ffmpeg/fmp4-fragment-child.js';
 export { Fmp4FragmentChild } from './ffmpeg/fmp4-fragment-child.js';
 export type { Fmp4CloseReason, Fmp4Packet, Fmp4PrebufferOptions, Fmp4PrebufferStats, Fmp4SubscribeInput, Fmp4SubscriberInfo, Fmp4Subscription, } from './ffmpeg/fmp4-fragment-plane.js';
 export { Fmp4FragmentPlane } from './ffmpeg/fmp4-fragment-plane.js';
 export type { FfmpegExit, FfmpegExitClass, FfmpegProcessOptions, FfmpegSpawnFn, SpawnedFfmpegProcess, } from './ffmpeg/process.js';
 export { defaultFfmpegSpawn, FfmpegProcess } from './ffmpeg/process.js';
-export type { FfmpegArgvSpawn, PinnedFfmpegSpawnAnswer } from './ffmpeg/pinned-spawn.js';
+export type { FfmpegArgvSpawn, PinnedFfmpegSpawnAnswer, } from './ffmpeg/pinned-spawn.js';
 export { NO_PINNED_FFMPEG_DETAIL, pinnedFfmpegSpawner, resolvePinnedFfmpegSpawner, } from './ffmpeg/pinned-spawn.js';
 export type { ChildCostClaimHandle, ChildCostClaimInput, ProcStatReader, } from './process/child-cost-registry.js';
 export { ChildCostRegistry, NO_COST_CLAIM, nodeProcStatReader, parseProcCpuSeconds, parseProcRssBytes, readProcessCost, } from './process/child-cost-registry.js';
@@ -23,6 +25,6 @@ export { containsOrEquals, physicalRootOf } from './storage/physical-root.js';
 export { canonicalHash } from './utils/canonical-hash.js';
 export { customizationBlockName } from './composition/customization-name.js';
 export type { VerifyExpiringUrlInput } from './utils/expiring-url-signature.js';
-export { signExpiringUrl, verifyExpiringUrl } from './utils/expiring-url-signature.js';
+export { signExpiringUrl, verifyExpiringUrl, } from './utils/expiring-url-signature.js';
 export type { DeviceExportShape, ExportDelta, ExportTargetEntry, } from './utils/export-reconciler.js';
 export { canonicalDeviceFingerprint, diffExportTargets, resolveExportFingerprint, } from './utils/export-reconciler.js';

package/dist/node.js

@@ -178,8 +178,9 @@ function extractArchive(archivePath, format, destDir, overrides = {}) {
 		}
 		return;
 	}
+	const flags = format === "tar.xz" ? "-xJf" : format === "tar" ? "-xf" : "-xzf";
 	deps.exec(tar, [
-		format === "tar.xz" ? "-xJf" : "-xzf",
+		flags,
 		archivePath,
 		"-C",
 		destDir
@@ -873,6 +874,354 @@ async function installPythonRequirements(pythonPath, requirementsFile, logger) {
 	} });
 }
 //#endregion
+//#region src/deps/deb-extract.ts
+/**
+* Pull one shared library out of a Debian package without `dpkg-deb`.
+*
+* A `.deb` is an `ar` archive holding `debian-binary`, `control.tar.*` and
+* `data.tar.*`; the payload's compression is the packager's choice. The two
+* debs the Coral delegate needs show both live ones: feranick's libedgetpu
+* ships `data.tar.xz`, Ubuntu's libusb (24.04 and every release since 21.10)
+* ships `data.tar.zst` — which `dpkg-deb` older than 1.21.18 and a stock
+* macOS `tar` without a `zstd` binary cannot open. So the ar container and a
+* zstd/gzip payload are unpacked IN-PROCESS (`node:zlib` has zstd since Node
+* 22.15, which the hub and the desktop's Electron both run); only an xz
+* payload goes through `tar -xJf`, which every POSIX host has.
+*
+* POSIX only: the delegate is never staged on Windows (no build exists).
+*/
+var AR_MAGIC = "!<arch>\n";
+var AR_HEADER_BYTES = 60;
+/** Every member of an `ar` archive, in order. Throws on anything that is not one. */
+function readArMembers(archive) {
+	if (archive.subarray(0, 8).toString("latin1") !== AR_MAGIC) throw new Error("not an ar archive (a .deb starts with \"!<arch>\")");
+	const members = [];
+	let offset = 8;
+	while (offset + AR_HEADER_BYTES <= archive.length) {
+		const header = archive.subarray(offset, offset + AR_HEADER_BYTES).toString("latin1");
+		if (header.slice(58, 60) !== "`\n") throw new Error(`corrupt ar member header at byte ${offset}`);
+		const name = header.slice(0, 16).trim().replace(/\/$/, "");
+		const size = Number.parseInt(header.slice(48, 58).trim(), 10);
+		if (!Number.isInteger(size) || size < 0) throw new Error(`ar member "${name}" has no valid size`);
+		const start = offset + AR_HEADER_BYTES;
+		if (start + size > archive.length) throw new Error(`ar member "${name}" runs past the end of the archive`);
+		members.push({
+			name,
+			data: archive.subarray(start, start + size)
+		});
+		offset = start + size + size % 2;
+	}
+	return members;
+}
+/** The `data.tar.*` member of a `.deb`, with the compression its name declares. */
+function debDataMember(deb) {
+	const member = readArMembers(deb).find((m) => m.name.startsWith("data.tar"));
+	if (member === void 0) throw new Error(".deb has no data.tar member");
+	const suffix = member.name.slice(8);
+	const compression = suffix === ".zst" ? "zst" : suffix === ".xz" ? "xz" : suffix === ".gz" ? "gz" : suffix === "" ? "none" : null;
+	if (compression === null) throw new Error(`.deb payload ${member.name} uses a compression this extractor does not read`);
+	return {
+		compression,
+		data: member.data
+	};
+}
+/**
+* Unpack a `.deb`'s payload into `destDir` (the package's own tree: `usr/lib/…`).
+* zstd and gzip are decompressed in-process; the plain tar and the xz payload
+* are expanded by the host `tar`.
+*/
+function extractDebPayload(deb, destDir, workDir, extract = extractArchive) {
+	const payload = debDataMember(deb);
+	(0, node_fs.mkdirSync)(destDir, { recursive: true });
+	(0, node_fs.mkdirSync)(workDir, { recursive: true });
+	if (payload.compression === "xz") {
+		const xzPath = (0, node_path.join)(workDir, "data.tar.xz");
+		(0, node_fs.writeFileSync)(xzPath, payload.data);
+		extract(xzPath, "tar.xz", destDir);
+		return;
+	}
+	const tar = payload.compression === "zst" ? (0, node_zlib.zstdDecompressSync)(payload.data) : payload.compression === "gz" ? (0, node_zlib.gunzipSync)(payload.data) : payload.data;
+	const tarPath = (0, node_path.join)(workDir, "data.tar");
+	(0, node_fs.writeFileSync)(tarPath, tar);
+	extract(tarPath, "tar", destDir);
+}
+/**
+* The first entry named exactly `name` under `dir` — a regular file OR a
+* symlink: a library's soname (`libusb-1.0.so.0`) is a link to the versioned
+* file in every package, so a file-only search never finds it.
+*/
+function findEntryByName(dir, name) {
+	for (const entry of (0, node_fs.readdirSync)(dir, { withFileTypes: true })) {
+		const full = (0, node_path.join)(dir, entry.name);
+		if ((entry.isFile() || entry.isSymbolicLink()) && entry.name === name) return full;
+		if (entry.isDirectory()) {
+			const nested = findEntryByName(full, name);
+			if (nested !== null) return nested;
+		}
+	}
+	return null;
+}
+/**
+* Copy the library `memberName` out of the `.deb` at `debPath` to `targetPath`,
+* dereferencing the soname link to the real file. Throws, naming the member,
+* when the package does not carry it.
+*/
+function installLibraryFromDeb(debPath, memberName, targetPath, workDir, extract = extractArchive) {
+	const tree = (0, node_path.join)(workDir, "tree");
+	try {
+		extractDebPayload((0, node_fs.readFileSync)(debPath), tree, workDir, extract);
+		const found = findEntryByName(tree, memberName);
+		if (found === null) throw new Error(`${memberName} not found inside ${debPath}`);
+		(0, node_fs.copyFileSync)(found, targetPath);
+	} finally {
+		(0, node_fs.rmSync)(workDir, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+//#endregion
+//#region src/deps/edgetpu-delegate.ts
+/**
+* The Coral Edge TPU delegate (libedgetpu) this node loads, and how the deps
+* downloader stages it.
+*
+* The delegate is a native shared library, not a pip package, and its TF
+* version MUST match the interpreter: ai-edge-litert 2.1.6 pairs with
+* feranick's libedgetpu rebuilt against TF 2.17.1 (release
+* `16.0TF2.17.1-1`); Google's stock 16.0 "grouper" build fails at invoke.
+* Every artifact below was fetched and hashed on 2026-10-22 and inspected:
+*
+* - linux x64 / arm64 — the `libedgetpu1-std` deb for Ubuntu 24.04 (the same
+*   build `edgetpu-install.sh` installs on the hub image; it needs glibc
+*   2.38), payload `data.tar.xz`. The std delegate links libusb even for a
+*   PCIe Coral, so Ubuntu 24.04's `libusb-1.0-0` deb is staged beside it —
+*   payload `data.tar.zst`, which is why `deb-extract.ts` reads zstd itself.
+* - darwin arm64 — the `MacOS_Silicon` zip, `throttled/` (the std clock, as on
+*   Linux). `otool -L` shows no libusb: it is linked in, nothing else needed.
+* - darwin x64 — REFUSED: ai-edge-litert 2.1.6 publishes no macOS x86_64
+*   wheel, and the Intel delegate links MacPorts' `/opt/local/lib/libusb`.
+* - win32 — REFUSED: no TF 2.17.1 libedgetpu exists for Windows; Google's old
+*   Windows delegate is built for a TFLite ai-edge-litert 2.1.6 cannot load.
+*
+* Resolution order, mirrored by `edgetpu_device.edgetpu_library_path` in the
+* Python pool: the `CAMSTACK_EDGETPU_LIB` path override → the copy staged
+* under `<CAMSTACK_DATA>/deps/edgetpu/lib/` → the hub's historical
+* `/data/deps/edgetpu/lib/libedgetpu.so.1`. On the hub image
+* `CAMSTACK_DATA=/data`, so the staged path and the historical one are the
+* same file and nothing moves.
+*/
+/** The path override (a library PATH, never a secret). */
+var EDGETPU_LIB_ENV = "CAMSTACK_EDGETPU_LIB";
+/** The pinned feranick release. Changing it is the delegate version change. */
+var EDGETPU_DELEGATE_RELEASE = "16.0TF2.17.1-1";
+/** Where the hub image's installer has always put the delegate. */
+var LEGACY_EDGETPU_LIB = "/data/deps/edgetpu/lib/libedgetpu.so.1";
+var FERANICK = `https://github.com/feranick/libedgetpu/releases/download/${EDGETPU_DELEGATE_RELEASE}`;
+function linuxSet(deb, debSha, debSize, libusbUrl, libusbSha, libusbSize) {
+	return {
+		supported: true,
+		files: [{
+			url: `${FERANICK}/${deb}`,
+			sha256: debSha,
+			sizeBytes: debSize,
+			container: "deb",
+			member: "libedgetpu.so.1",
+			installAs: "libedgetpu.so.1"
+		}, {
+			url: libusbUrl,
+			sha256: libusbSha,
+			sizeBytes: libusbSize,
+			container: "deb",
+			member: "libusb-1.0.so.0",
+			installAs: "libusb-1.0.so.0"
+		}]
+	};
+}
+/** The pinned delegate set for a platform and arch, or why there is none. */
+function getEdgetpuDelegateArtifact(platform, arch) {
+	if (platform === "linux" && arch === "x64") return linuxSet("libedgetpu1-std_16.0tf2.17.1-1.ubuntu24.04_amd64.deb", "3cd98ae42d26a0ab601673d2162eb968921f751d3879ef960687637cad1cba96", 389600, "http://archive.ubuntu.com/ubuntu/pool/main/libu/libusb-1.0/libusb-1.0-0_1.0.27-1_amd64.deb", "d59e679a82ee2b724c556397e831e879936adbe8a007705872b65a5e1ec887b5", 54008);
+	if (platform === "linux" && arch === "arm64") return linuxSet("libedgetpu1-std_16.0tf2.17.1-1.ubuntu24.04_arm64.deb", "6d53b6f6f9a19a6685a488e0c262aed2b11b6ff8c953f10e0aa14a16122f0d37", 338416, "http://ports.ubuntu.com/ubuntu-ports/pool/main/libu/libusb-1.0/libusb-1.0-0_1.0.27-1_arm64.deb", "c8c34ef4385b6be34fe94aabd4de06c7bbd5ae617e80e9306f412f4c979aa5e4", 54082);
+	if (platform === "darwin" && arch === "arm64") return {
+		supported: true,
+		files: [{
+			url: `${FERANICK}/libedgetpu-16.0-tf2.17.1-1_MacOS_Silicon.zip`,
+			sha256: "5d57b4ff80bfe70d1d9306a3a8a83f52b38e8a151c35aecf68d807744eacf1f4",
+			sizeBytes: 760105,
+			container: "zip",
+			member: "libedgetpu-16.0-tf2.17.1-1_MacOS_Silicon/throttled/darwin_arm64/libedgetpu.1.0.dylib",
+			installAs: "libedgetpu.1.dylib"
+		}]
+	};
+	if (platform === "darwin") return {
+		supported: false,
+		reason: "ai-edge-litert 2.1.6 publishes no macOS x86_64 wheel, and the Intel delegate links MacPorts libusb at /opt/local/lib"
+	};
+	if (platform === "win32") return {
+		supported: false,
+		reason: "no libedgetpu built against TF 2.17.1 exists for Windows (feranick ships Linux and macOS only)"
+	};
+	return {
+		supported: false,
+		reason: `no pinned libedgetpu build for ${platform}-${arch}`
+	};
+}
+/** The delegate's file name on a platform (what the Python pool loads). */
+function edgetpuDelegateFileName(platform) {
+	return platform === "darwin" ? "libedgetpu.1.dylib" : "libedgetpu.so.1";
+}
+/** `<dataDir>/deps/edgetpu/lib` — where the deps downloader stages the set. */
+function edgetpuLibDir(dataDir) {
+	return (0, node_path.join)(dataDir, "deps", "edgetpu", "lib");
+}
+/**
+* The delegate this node loads, or `null` when none is present. An override
+* that names a missing file is NOT followed past: the operator said where it
+* is, and a silent fallback would load a different build than they chose.
+*/
+function chooseEdgetpuDelegate(lookup) {
+	const override = lookup.override?.trim();
+	if (override !== void 0 && override.length > 0) return lookup.exists(override) ? {
+		path: override,
+		origin: "override"
+	} : null;
+	if (lookup.dataDir !== void 0 && lookup.dataDir.length > 0) {
+		const staged = (0, node_path.join)(edgetpuLibDir(lookup.dataDir), edgetpuDelegateFileName(lookup.platform));
+		if (lookup.exists(staged)) return {
+			path: staged,
+			origin: "staged"
+		};
+	}
+	if (lookup.exists("/data/deps/edgetpu/lib/libedgetpu.so.1")) return {
+		path: LEGACY_EDGETPU_LIB,
+		origin: "legacy"
+	};
+	return null;
+}
+/** The node data root the way every node process names it. */
+function nodeDataRootFromEnv(env) {
+	return env["CAMSTACK_DATA"] ?? env["CAMSTACK_DATA_DIR"];
+}
+/** Under 1 MB each: held whole, written once, hashed from disk before use. */
+async function download(url, target) {
+	const response = await fetch(url, { redirect: "follow" });
+	if (!response.ok) throw new Error(`download failed: ${response.status} ${response.statusText} (${url})`);
+	(0, node_fs.writeFileSync)(target, Buffer.from(await response.arrayBuffer()));
+}
+async function stageFile(file, libDir, workRoot) {
+	const target = (0, node_path.join)(libDir, file.installAs);
+	if ((0, node_fs.existsSync)(target)) return;
+	const work = (0, node_path.join)(workRoot, file.installAs);
+	(0, node_fs.rmSync)(work, {
+		recursive: true,
+		force: true
+	});
+	(0, node_fs.mkdirSync)(work, { recursive: true });
+	const container = (0, node_path.join)(work, `download.${file.container}`);
+	const partial = `${target}.partial`;
+	try {
+		await download(file.url, container);
+		verifySha256(container, file.sha256, file.installAs, file.url);
+		if (file.container === "deb") installLibraryFromDeb(container, file.member, partial, (0, node_path.join)(work, "deb"));
+		else {
+			const tree = (0, node_path.join)(work, "tree");
+			(0, node_fs.mkdirSync)(tree, { recursive: true });
+			extractArchive(container, "zip", tree);
+			const inner = (0, node_path.join)(tree, file.member);
+			const found = (0, node_fs.existsSync)(inner) ? inner : findEntryByName(tree, file.member.split("/").pop() ?? file.member);
+			if (found === null) throw new Error(`${file.member} not found inside ${file.url}`);
+			(0, node_fs.copyFileSync)(found, partial);
+		}
+		(0, node_fs.renameSync)(partial, target);
+	} finally {
+		(0, node_fs.rmSync)(work, {
+			recursive: true,
+			force: true
+		});
+		(0, node_fs.rmSync)(partial, { force: true });
+	}
+}
+/**
+* A requirements file names the native library its packages cannot run
+* without on this line; `installPythonRequirements` stages it after pip.
+* (`ai-edge-litert` imports without the delegate and is useless without it.)
+*/
+var EDGETPU_DELEGATE_DIRECTIVE = "# camstack-native-dep: edgetpu-delegate";
+function declaresEdgetpuDelegate(requirementsText) {
+	return requirementsText.split(/\r?\n/).some((line) => line.trim() === EDGETPU_DELEGATE_DIRECTIVE);
+}
+/**
+* The delegate this node loads, staging the pinned set under
+* `<dataDir>/deps/edgetpu/lib/` when nothing is present yet. Never throws for
+* a platform without a build — it answers `unavailable` with the reason; a
+* download or checksum failure throws, naming the file. The line it logs says
+* which delegate (and from where) the pool will load.
+*/
+async function ensureEdgetpuDelegate(dataDir, logger, opts = {}) {
+	const env = opts.env ?? process.env;
+	const platform = opts.platform ?? process.platform;
+	const arch = opts.arch ?? process.arch;
+	const override = env[EDGETPU_LIB_ENV]?.trim();
+	const present = chooseEdgetpuDelegate({
+		platform,
+		dataDir,
+		override,
+		exists: node_fs.existsSync
+	});
+	if (present !== null) {
+		logger.info("Coral delegate resolved", { meta: {
+			path: present.path,
+			origin: present.origin
+		} });
+		return {
+			kind: "ready",
+			path: present.path,
+			origin: present.origin
+		};
+	}
+	if (override !== void 0 && override.length > 0) {
+		const reason = `${EDGETPU_LIB_ENV} names a file that does not exist: ${override}`;
+		logger.error("Coral delegate not staged", { meta: { reason } });
+		return {
+			kind: "unavailable",
+			reason
+		};
+	}
+	const artifact = getEdgetpuDelegateArtifact(platform, arch);
+	if (!artifact.supported) {
+		logger.warn("Coral delegate not staged", { meta: { reason: artifact.reason } });
+		return {
+			kind: "unavailable",
+			reason: artifact.reason
+		};
+	}
+	const libDir = edgetpuLibDir(dataDir);
+	(0, node_fs.mkdirSync)(libDir, { recursive: true });
+	logger.info("Coral delegate is not on this node yet — downloading the pinned set", { meta: {
+		release: EDGETPU_DELEGATE_RELEASE,
+		files: artifact.files.map((f) => f.installAs).join(",")
+	} });
+	const workRoot = (0, node_path.join)(dataDir, "deps", ".edgetpu-staging");
+	try {
+		for (const file of artifact.files) await stageFile(file, libDir, workRoot);
+	} finally {
+		(0, node_fs.rmSync)(workRoot, {
+			recursive: true,
+			force: true
+		});
+	}
+	const path = (0, node_path.join)(libDir, edgetpuDelegateFileName(platform));
+	logger.info("Coral delegate resolved", { meta: {
+		path,
+		origin: "downloaded"
+	} });
+	return {
+		kind: "ready",
+		path,
+		origin: "downloaded"
+	};
+}
+//#endregion
 //#region src/ffmpeg/fmp4-fragment-child.ts
 var DEFAULT_FIRST_UNIT_TIMEOUT_MS = 12e3;
 /** Heartbeat cadence — ~2 minutes of 4 s fragments. */
@@ -2274,11 +2623,15 @@ function resolveExportFingerprint(input) {
 }
 //#endregion
 exports.ChildCostRegistry = ChildCostRegistry;
+exports.EDGETPU_DELEGATE_DIRECTIVE = EDGETPU_DELEGATE_DIRECTIVE;
+exports.EDGETPU_DELEGATE_RELEASE = EDGETPU_DELEGATE_RELEASE;
+exports.EDGETPU_LIB_ENV = EDGETPU_LIB_ENV;
 exports.FFMPEG_RELEASE = require_composition.FFMPEG_RELEASE;
 exports.FfmpegProcess = FfmpegProcess;
 exports.FilesystemStorageProvider = FilesystemStorageProvider;
 exports.Fmp4FragmentChild = Fmp4FragmentChild;
 exports.Fmp4FragmentPlane = Fmp4FragmentPlane;
+exports.LEGACY_EDGETPU_LIB = LEGACY_EDGETPU_LIB;
 exports.NO_COST_CLAIM = NO_COST_CLAIM;
 exports.NO_PINNED_FFMPEG_DETAIL = NO_PINNED_FFMPEG_DETAIL;
 exports.OwnerOnlyError = OwnerOnlyError;
@@ -2286,23 +2639,33 @@ exports.PYTHON_VERSION = PYTHON_VERSION;
 exports.buildBinaryPath = buildBinaryPath;
 exports.canonicalDeviceFingerprint = canonicalDeviceFingerprint;
 exports.canonicalHash = require_composition.canonicalHash;
+exports.chooseEdgetpuDelegate = chooseEdgetpuDelegate;
 exports.containsOrEquals = containsOrEquals;
 exports.customizationBlockName = customizationBlockName;
+exports.debDataMember = debDataMember;
+exports.declaresEdgetpuDelegate = declaresEdgetpuDelegate;
 exports.defaultFfmpegSpawn = defaultFfmpegSpawn;
 exports.diffExportTargets = diffExportTargets;
 exports.downloadBinary = downloadBinary;
+exports.edgetpuDelegateFileName = edgetpuDelegateFileName;
+exports.edgetpuLibDir = edgetpuLibDir;
 exports.ensureBinary = ensureBinary;
+exports.ensureEdgetpuDelegate = ensureEdgetpuDelegate;
 exports.ensureFfmpeg = ensureFfmpeg;
 exports.ensurePython = ensurePython;
+exports.extractDebPayload = extractDebPayload;
 exports.findInPath = findInPath;
+exports.getEdgetpuDelegateArtifact = getEdgetpuDelegateArtifact;
 exports.getFfmpegArtifact = require_composition.getFfmpegArtifact;
 exports.getFfmpegDownloadUrl = require_composition.getFfmpegDownloadUrl;
 exports.getPlatformInfo = getPlatformInfo;
 exports.getPythonDownloadUrl = getPythonDownloadUrl;
 exports.icaclsArgs = icaclsArgs;
+exports.installLibraryFromDeb = installLibraryFromDeb;
 exports.installPythonPackages = installPythonPackages;
 exports.installPythonRequirements = installPythonRequirements;
 exports.mkdirOwnerOnlySync = mkdirOwnerOnlySync;
+exports.nodeDataRootFromEnv = nodeDataRootFromEnv;
 exports.nodeProcStatReader = nodeProcStatReader;
 exports.parseFfmpegCapabilities = parseFfmpegCapabilities;
 exports.parseProcCpuSeconds = parseProcCpuSeconds;
@@ -2310,6 +2673,7 @@ exports.parseProcRssBytes = parseProcRssBytes;
 exports.physicalRootOf = physicalRootOf;
 exports.pinnedFfmpegSpawner = pinnedFfmpegSpawner;
 exports.probeFfmpegBinary = probeFfmpegBinary;
+exports.readArMembers = readArMembers;
 exports.readProcessCost = readProcessCost;
 exports.resolveExportFingerprint = resolveExportFingerprint;
 exports.resolvePinnedFfmpegSpawner = resolvePinnedFfmpegSpawner;

package/dist/node.mjs

@@ -2,13 +2,13 @@ import { At as Fmp4BoxSplitter, Ct as FFMPEG_PATH_ENV, Dt as getFfmpegArtifact,
 import { t as errMsg } from "./err-msg-BXKzRBwg.mjs";
 import { createHash, createHmac, randomUUID, timingSafeEqual } from "node:crypto";
 import * as fs from "node:fs";
-import { chmodSync, createWriteStream, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
+import { chmodSync, copyFileSync, createWriteStream, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
 import * as path$1 from "node:path";
 import path, { basename, dirname, join, resolve, sep } from "node:path";
 import { pipeline } from "node:stream/promises";
 import { Readable } from "node:stream";
 import { execFile, execFileSync, spawn } from "node:child_process";
-import { crc32, inflateRawSync } from "node:zlib";
+import { crc32, gunzipSync, inflateRawSync, zstdDecompressSync } from "node:zlib";
 import { userInfo } from "node:os";
 import { readFile } from "node:fs/promises";
 //#region src/deps/zip-extract.ts
@@ -155,8 +155,9 @@ function extractArchive(archivePath, format, destDir, overrides = {}) {
 		}
 		return;
 	}
+	const flags = format === "tar.xz" ? "-xJf" : format === "tar" ? "-xf" : "-xzf";
 	deps.exec(tar, [
-		format === "tar.xz" ? "-xJf" : "-xzf",
+		flags,
 		archivePath,
 		"-C",
 		destDir
@@ -850,6 +851,354 @@ async function installPythonRequirements(pythonPath, requirementsFile, logger) {
 	} });
 }
 //#endregion
+//#region src/deps/deb-extract.ts
+/**
+* Pull one shared library out of a Debian package without `dpkg-deb`.
+*
+* A `.deb` is an `ar` archive holding `debian-binary`, `control.tar.*` and
+* `data.tar.*`; the payload's compression is the packager's choice. The two
+* debs the Coral delegate needs show both live ones: feranick's libedgetpu
+* ships `data.tar.xz`, Ubuntu's libusb (24.04 and every release since 21.10)
+* ships `data.tar.zst` — which `dpkg-deb` older than 1.21.18 and a stock
+* macOS `tar` without a `zstd` binary cannot open. So the ar container and a
+* zstd/gzip payload are unpacked IN-PROCESS (`node:zlib` has zstd since Node
+* 22.15, which the hub and the desktop's Electron both run); only an xz
+* payload goes through `tar -xJf`, which every POSIX host has.
+*
+* POSIX only: the delegate is never staged on Windows (no build exists).
+*/
+var AR_MAGIC = "!<arch>\n";
+var AR_HEADER_BYTES = 60;
+/** Every member of an `ar` archive, in order. Throws on anything that is not one. */
+function readArMembers(archive) {
+	if (archive.subarray(0, 8).toString("latin1") !== AR_MAGIC) throw new Error("not an ar archive (a .deb starts with \"!<arch>\")");
+	const members = [];
+	let offset = 8;
+	while (offset + AR_HEADER_BYTES <= archive.length) {
+		const header = archive.subarray(offset, offset + AR_HEADER_BYTES).toString("latin1");
+		if (header.slice(58, 60) !== "`\n") throw new Error(`corrupt ar member header at byte ${offset}`);
+		const name = header.slice(0, 16).trim().replace(/\/$/, "");
+		const size = Number.parseInt(header.slice(48, 58).trim(), 10);
+		if (!Number.isInteger(size) || size < 0) throw new Error(`ar member "${name}" has no valid size`);
+		const start = offset + AR_HEADER_BYTES;
+		if (start + size > archive.length) throw new Error(`ar member "${name}" runs past the end of the archive`);
+		members.push({
+			name,
+			data: archive.subarray(start, start + size)
+		});
+		offset = start + size + size % 2;
+	}
+	return members;
+}
+/** The `data.tar.*` member of a `.deb`, with the compression its name declares. */
+function debDataMember(deb) {
+	const member = readArMembers(deb).find((m) => m.name.startsWith("data.tar"));
+	if (member === void 0) throw new Error(".deb has no data.tar member");
+	const suffix = member.name.slice(8);
+	const compression = suffix === ".zst" ? "zst" : suffix === ".xz" ? "xz" : suffix === ".gz" ? "gz" : suffix === "" ? "none" : null;
+	if (compression === null) throw new Error(`.deb payload ${member.name} uses a compression this extractor does not read`);
+	return {
+		compression,
+		data: member.data
+	};
+}
+/**
+* Unpack a `.deb`'s payload into `destDir` (the package's own tree: `usr/lib/…`).
+* zstd and gzip are decompressed in-process; the plain tar and the xz payload
+* are expanded by the host `tar`.
+*/
+function extractDebPayload(deb, destDir, workDir, extract = extractArchive) {
+	const payload = debDataMember(deb);
+	mkdirSync(destDir, { recursive: true });
+	mkdirSync(workDir, { recursive: true });
+	if (payload.compression === "xz") {
+		const xzPath = join(workDir, "data.tar.xz");
+		writeFileSync(xzPath, payload.data);
+		extract(xzPath, "tar.xz", destDir);
+		return;
+	}
+	const tar = payload.compression === "zst" ? zstdDecompressSync(payload.data) : payload.compression === "gz" ? gunzipSync(payload.data) : payload.data;
+	const tarPath = join(workDir, "data.tar");
+	writeFileSync(tarPath, tar);
+	extract(tarPath, "tar", destDir);
+}
+/**
+* The first entry named exactly `name` under `dir` — a regular file OR a
+* symlink: a library's soname (`libusb-1.0.so.0`) is a link to the versioned
+* file in every package, so a file-only search never finds it.
+*/
+function findEntryByName(dir, name) {
+	for (const entry of readdirSync(dir, { withFileTypes: true })) {
+		const full = join(dir, entry.name);
+		if ((entry.isFile() || entry.isSymbolicLink()) && entry.name === name) return full;
+		if (entry.isDirectory()) {
+			const nested = findEntryByName(full, name);
+			if (nested !== null) return nested;
+		}
+	}
+	return null;
+}
+/**
+* Copy the library `memberName` out of the `.deb` at `debPath` to `targetPath`,
+* dereferencing the soname link to the real file. Throws, naming the member,
+* when the package does not carry it.
+*/
+function installLibraryFromDeb(debPath, memberName, targetPath, workDir, extract = extractArchive) {
+	const tree = join(workDir, "tree");
+	try {
+		extractDebPayload(readFileSync(debPath), tree, workDir, extract);
+		const found = findEntryByName(tree, memberName);
+		if (found === null) throw new Error(`${memberName} not found inside ${debPath}`);
+		copyFileSync(found, targetPath);
+	} finally {
+		rmSync(workDir, {
+			recursive: true,
+			force: true
+		});
+	}
+}
+//#endregion
+//#region src/deps/edgetpu-delegate.ts
+/**
+* The Coral Edge TPU delegate (libedgetpu) this node loads, and how the deps
+* downloader stages it.
+*
+* The delegate is a native shared library, not a pip package, and its TF
+* version MUST match the interpreter: ai-edge-litert 2.1.6 pairs with
+* feranick's libedgetpu rebuilt against TF 2.17.1 (release
+* `16.0TF2.17.1-1`); Google's stock 16.0 "grouper" build fails at invoke.
+* Every artifact below was fetched and hashed on 2026-10-22 and inspected:
+*
+* - linux x64 / arm64 — the `libedgetpu1-std` deb for Ubuntu 24.04 (the same
+*   build `edgetpu-install.sh` installs on the hub image; it needs glibc
+*   2.38), payload `data.tar.xz`. The std delegate links libusb even for a
+*   PCIe Coral, so Ubuntu 24.04's `libusb-1.0-0` deb is staged beside it —
+*   payload `data.tar.zst`, which is why `deb-extract.ts` reads zstd itself.
+* - darwin arm64 — the `MacOS_Silicon` zip, `throttled/` (the std clock, as on
+*   Linux). `otool -L` shows no libusb: it is linked in, nothing else needed.
+* - darwin x64 — REFUSED: ai-edge-litert 2.1.6 publishes no macOS x86_64
+*   wheel, and the Intel delegate links MacPorts' `/opt/local/lib/libusb`.
+* - win32 — REFUSED: no TF 2.17.1 libedgetpu exists for Windows; Google's old
+*   Windows delegate is built for a TFLite ai-edge-litert 2.1.6 cannot load.
+*
+* Resolution order, mirrored by `edgetpu_device.edgetpu_library_path` in the
+* Python pool: the `CAMSTACK_EDGETPU_LIB` path override → the copy staged
+* under `<CAMSTACK_DATA>/deps/edgetpu/lib/` → the hub's historical
+* `/data/deps/edgetpu/lib/libedgetpu.so.1`. On the hub image
+* `CAMSTACK_DATA=/data`, so the staged path and the historical one are the
+* same file and nothing moves.
+*/
+/** The path override (a library PATH, never a secret). */
+var EDGETPU_LIB_ENV = "CAMSTACK_EDGETPU_LIB";
+/** The pinned feranick release. Changing it is the delegate version change. */
+var EDGETPU_DELEGATE_RELEASE = "16.0TF2.17.1-1";
+/** Where the hub image's installer has always put the delegate. */
+var LEGACY_EDGETPU_LIB = "/data/deps/edgetpu/lib/libedgetpu.so.1";
+var FERANICK = `https://github.com/feranick/libedgetpu/releases/download/${EDGETPU_DELEGATE_RELEASE}`;
+function linuxSet(deb, debSha, debSize, libusbUrl, libusbSha, libusbSize) {
+	return {
+		supported: true,
+		files: [{
+			url: `${FERANICK}/${deb}`,
+			sha256: debSha,
+			sizeBytes: debSize,
+			container: "deb",
+			member: "libedgetpu.so.1",
+			installAs: "libedgetpu.so.1"
+		}, {
+			url: libusbUrl,
+			sha256: libusbSha,
+			sizeBytes: libusbSize,
+			container: "deb",
+			member: "libusb-1.0.so.0",
+			installAs: "libusb-1.0.so.0"
+		}]
+	};
+}
+/** The pinned delegate set for a platform and arch, or why there is none. */
+function getEdgetpuDelegateArtifact(platform, arch) {
+	if (platform === "linux" && arch === "x64") return linuxSet("libedgetpu1-std_16.0tf2.17.1-1.ubuntu24.04_amd64.deb", "3cd98ae42d26a0ab601673d2162eb968921f751d3879ef960687637cad1cba96", 389600, "http://archive.ubuntu.com/ubuntu/pool/main/libu/libusb-1.0/libusb-1.0-0_1.0.27-1_amd64.deb", "d59e679a82ee2b724c556397e831e879936adbe8a007705872b65a5e1ec887b5", 54008);
+	if (platform === "linux" && arch === "arm64") return linuxSet("libedgetpu1-std_16.0tf2.17.1-1.ubuntu24.04_arm64.deb", "6d53b6f6f9a19a6685a488e0c262aed2b11b6ff8c953f10e0aa14a16122f0d37", 338416, "http://ports.ubuntu.com/ubuntu-ports/pool/main/libu/libusb-1.0/libusb-1.0-0_1.0.27-1_arm64.deb", "c8c34ef4385b6be34fe94aabd4de06c7bbd5ae617e80e9306f412f4c979aa5e4", 54082);
+	if (platform === "darwin" && arch === "arm64") return {
+		supported: true,
+		files: [{
+			url: `${FERANICK}/libedgetpu-16.0-tf2.17.1-1_MacOS_Silicon.zip`,
+			sha256: "5d57b4ff80bfe70d1d9306a3a8a83f52b38e8a151c35aecf68d807744eacf1f4",
+			sizeBytes: 760105,
+			container: "zip",
+			member: "libedgetpu-16.0-tf2.17.1-1_MacOS_Silicon/throttled/darwin_arm64/libedgetpu.1.0.dylib",
+			installAs: "libedgetpu.1.dylib"
+		}]
+	};
+	if (platform === "darwin") return {
+		supported: false,
+		reason: "ai-edge-litert 2.1.6 publishes no macOS x86_64 wheel, and the Intel delegate links MacPorts libusb at /opt/local/lib"
+	};
+	if (platform === "win32") return {
+		supported: false,
+		reason: "no libedgetpu built against TF 2.17.1 exists for Windows (feranick ships Linux and macOS only)"
+	};
+	return {
+		supported: false,
+		reason: `no pinned libedgetpu build for ${platform}-${arch}`
+	};
+}
+/** The delegate's file name on a platform (what the Python pool loads). */
+function edgetpuDelegateFileName(platform) {
+	return platform === "darwin" ? "libedgetpu.1.dylib" : "libedgetpu.so.1";
+}
+/** `<dataDir>/deps/edgetpu/lib` — where the deps downloader stages the set. */
+function edgetpuLibDir(dataDir) {
+	return join(dataDir, "deps", "edgetpu", "lib");
+}
+/**
+* The delegate this node loads, or `null` when none is present. An override
+* that names a missing file is NOT followed past: the operator said where it
+* is, and a silent fallback would load a different build than they chose.
+*/
+function chooseEdgetpuDelegate(lookup) {
+	const override = lookup.override?.trim();
+	if (override !== void 0 && override.length > 0) return lookup.exists(override) ? {
+		path: override,
+		origin: "override"
+	} : null;
+	if (lookup.dataDir !== void 0 && lookup.dataDir.length > 0) {
+		const staged = join(edgetpuLibDir(lookup.dataDir), edgetpuDelegateFileName(lookup.platform));
+		if (lookup.exists(staged)) return {
+			path: staged,
+			origin: "staged"
+		};
+	}
+	if (lookup.exists("/data/deps/edgetpu/lib/libedgetpu.so.1")) return {
+		path: LEGACY_EDGETPU_LIB,
+		origin: "legacy"
+	};
+	return null;
+}
+/** The node data root the way every node process names it. */
+function nodeDataRootFromEnv(env) {
+	return env["CAMSTACK_DATA"] ?? env["CAMSTACK_DATA_DIR"];
+}
+/** Under 1 MB each: held whole, written once, hashed from disk before use. */
+async function download(url, target) {
+	const response = await fetch(url, { redirect: "follow" });
+	if (!response.ok) throw new Error(`download failed: ${response.status} ${response.statusText} (${url})`);
+	writeFileSync(target, Buffer.from(await response.arrayBuffer()));
+}
+async function stageFile(file, libDir, workRoot) {
+	const target = join(libDir, file.installAs);
+	if (existsSync(target)) return;
+	const work = join(workRoot, file.installAs);
+	rmSync(work, {
+		recursive: true,
+		force: true
+	});
+	mkdirSync(work, { recursive: true });
+	const container = join(work, `download.${file.container}`);
+	const partial = `${target}.partial`;
+	try {
+		await download(file.url, container);
+		verifySha256(container, file.sha256, file.installAs, file.url);
+		if (file.container === "deb") installLibraryFromDeb(container, file.member, partial, join(work, "deb"));
+		else {
+			const tree = join(work, "tree");
+			mkdirSync(tree, { recursive: true });
+			extractArchive(container, "zip", tree);
+			const inner = join(tree, file.member);
+			const found = existsSync(inner) ? inner : findEntryByName(tree, file.member.split("/").pop() ?? file.member);
+			if (found === null) throw new Error(`${file.member} not found inside ${file.url}`);
+			copyFileSync(found, partial);
+		}
+		renameSync(partial, target);
+	} finally {
+		rmSync(work, {
+			recursive: true,
+			force: true
+		});
+		rmSync(partial, { force: true });
+	}
+}
+/**
+* A requirements file names the native library its packages cannot run
+* without on this line; `installPythonRequirements` stages it after pip.
+* (`ai-edge-litert` imports without the delegate and is useless without it.)
+*/
+var EDGETPU_DELEGATE_DIRECTIVE = "# camstack-native-dep: edgetpu-delegate";
+function declaresEdgetpuDelegate(requirementsText) {
+	return requirementsText.split(/\r?\n/).some((line) => line.trim() === EDGETPU_DELEGATE_DIRECTIVE);
+}
+/**
+* The delegate this node loads, staging the pinned set under
+* `<dataDir>/deps/edgetpu/lib/` when nothing is present yet. Never throws for
+* a platform without a build — it answers `unavailable` with the reason; a
+* download or checksum failure throws, naming the file. The line it logs says
+* which delegate (and from where) the pool will load.
+*/
+async function ensureEdgetpuDelegate(dataDir, logger, opts = {}) {
+	const env = opts.env ?? process.env;
+	const platform = opts.platform ?? process.platform;
+	const arch = opts.arch ?? process.arch;
+	const override = env[EDGETPU_LIB_ENV]?.trim();
+	const present = chooseEdgetpuDelegate({
+		platform,
+		dataDir,
+		override,
+		exists: existsSync
+	});
+	if (present !== null) {
+		logger.info("Coral delegate resolved", { meta: {
+			path: present.path,
+			origin: present.origin
+		} });
+		return {
+			kind: "ready",
+			path: present.path,
+			origin: present.origin
+		};
+	}
+	if (override !== void 0 && override.length > 0) {
+		const reason = `${EDGETPU_LIB_ENV} names a file that does not exist: ${override}`;
+		logger.error("Coral delegate not staged", { meta: { reason } });
+		return {
+			kind: "unavailable",
+			reason
+		};
+	}
+	const artifact = getEdgetpuDelegateArtifact(platform, arch);
+	if (!artifact.supported) {
+		logger.warn("Coral delegate not staged", { meta: { reason: artifact.reason } });
+		return {
+			kind: "unavailable",
+			reason: artifact.reason
+		};
+	}
+	const libDir = edgetpuLibDir(dataDir);
+	mkdirSync(libDir, { recursive: true });
+	logger.info("Coral delegate is not on this node yet — downloading the pinned set", { meta: {
+		release: EDGETPU_DELEGATE_RELEASE,
+		files: artifact.files.map((f) => f.installAs).join(",")
+	} });
+	const workRoot = join(dataDir, "deps", ".edgetpu-staging");
+	try {
+		for (const file of artifact.files) await stageFile(file, libDir, workRoot);
+	} finally {
+		rmSync(workRoot, {
+			recursive: true,
+			force: true
+		});
+	}
+	const path = join(libDir, edgetpuDelegateFileName(platform));
+	logger.info("Coral delegate resolved", { meta: {
+		path,
+		origin: "downloaded"
+	} });
+	return {
+		kind: "ready",
+		path,
+		origin: "downloaded"
+	};
+}
+//#endregion
 //#region src/ffmpeg/fmp4-fragment-child.ts
 var DEFAULT_FIRST_UNIT_TIMEOUT_MS = 12e3;
 /** Heartbeat cadence — ~2 minutes of 4 s fragments. */
@@ -2250,4 +2599,4 @@ function resolveExportFingerprint(input) {
 	return input.persisted ?? input.fresh;
 }
 //#endregion
-export { ChildCostRegistry, FFMPEG_RELEASE, FfmpegProcess, FilesystemStorageProvider, Fmp4FragmentChild, Fmp4FragmentPlane, NO_COST_CLAIM, NO_PINNED_FFMPEG_DETAIL, OwnerOnlyError, PYTHON_VERSION, buildBinaryPath, canonicalDeviceFingerprint, canonicalHash, containsOrEquals, customizationBlockName, defaultFfmpegSpawn, diffExportTargets, downloadBinary, ensureBinary, ensureFfmpeg, ensurePython, findInPath, getFfmpegArtifact, getFfmpegDownloadUrl, getPlatformInfo, getPythonDownloadUrl, icaclsArgs, installPythonPackages, installPythonRequirements, mkdirOwnerOnlySync, nodeProcStatReader, parseFfmpegCapabilities, parseProcCpuSeconds, parseProcRssBytes, physicalRootOf, pinnedFfmpegSpawner, probeFfmpegBinary, readProcessCost, resolveExportFingerprint, resolvePinnedFfmpegSpawner, restrictDirToOwnerSync, restrictFileToOwnerSync, signExpiringUrl, verifyExpiringUrl, writeFileAtomic, writeOwnerOnlyFileSync };
+export { ChildCostRegistry, EDGETPU_DELEGATE_DIRECTIVE, EDGETPU_DELEGATE_RELEASE, EDGETPU_LIB_ENV, FFMPEG_RELEASE, FfmpegProcess, FilesystemStorageProvider, Fmp4FragmentChild, Fmp4FragmentPlane, LEGACY_EDGETPU_LIB, NO_COST_CLAIM, NO_PINNED_FFMPEG_DETAIL, OwnerOnlyError, PYTHON_VERSION, buildBinaryPath, canonicalDeviceFingerprint, canonicalHash, chooseEdgetpuDelegate, containsOrEquals, customizationBlockName, debDataMember, declaresEdgetpuDelegate, defaultFfmpegSpawn, diffExportTargets, downloadBinary, edgetpuDelegateFileName, edgetpuLibDir, ensureBinary, ensureEdgetpuDelegate, ensureFfmpeg, ensurePython, extractDebPayload, findInPath, getEdgetpuDelegateArtifact, getFfmpegArtifact, getFfmpegDownloadUrl, getPlatformInfo, getPythonDownloadUrl, icaclsArgs, installLibraryFromDeb, installPythonPackages, installPythonRequirements, mkdirOwnerOnlySync, nodeDataRootFromEnv, nodeProcStatReader, parseFfmpegCapabilities, parseProcCpuSeconds, parseProcRssBytes, physicalRootOf, pinnedFfmpegSpawner, probeFfmpegBinary, readArMembers, readProcessCost, resolveExportFingerprint, resolvePinnedFfmpegSpawner, restrictDirToOwnerSync, restrictFileToOwnerSync, signExpiringUrl, verifyExpiringUrl, writeFileAtomic, writeOwnerOnlyFileSync };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camstack/types",
-  "version": "1.2.391",
+  "version": "1.2.392",
   "description": "Shared types, interfaces, and model catalogs for the CamStack detection ecosystem",
   "keywords": [
     "camstack",