@nimbus-sh/worker 0.1.0

package/dist/npm/tarball-stream.d.ts

@@ -0,0 +1,85 @@
+/**
+ * npm-tarball-stream.ts — pure streaming tar primitives.
+ *
+ * Extracted from npm-tarball.ts so these helpers can be esbuild-bundled
+ * WITHOUT dragging in NpmCache / NpmResolver / SqliteVFS. Consumed by
+ * scripts/bundle-facet-workers.mjs which emits a string constant the
+ * NimbusLoaderPool uses to inject the tar parser into dynamic workers.
+ *
+ * Zero dependencies. Works identically on the supervisor and inside a
+ * facet isolate. Never buffers the full decompressed tarball — peak
+ * transient heap is one file's bytes plus a 512-byte carry.
+ */
+/**
+ * Maximum size of a single file inside a tarball. Larger entries are skipped.
+ *
+ * History: 5 MB was too low — it silently dropped `esbuild-wasm/esbuild.wasm`
+ * (11.35 MB on v0.24.2), which made Nimbus-in-Nimbus `npm run dev` fail with
+ * `No such module "esbuild-wasm/esbuild.wasm"` since the missing file caused
+ * esbuild's VFS plugin to mark the import `external`, and workerd's LOADER
+ * has no entry for that specifier. 20 MB covers esbuild-wasm with headroom
+ * while keeping per-facet peak heap bounded for the streaming extractor.
+ */
+export declare const MAX_FILE_BYTES = 20000000;
+/**
+ * Read one tar header (USTAR) out of `block`. Returns parsed fields or
+ * `null` for an end-of-archive block (all zeros).
+ */
+export declare function parseTarHeader(block: Uint8Array): {
+    name: string;
+    size: number;
+    typeFlag: number;
+} | null;
+/**
+ * Wrap a `ReadableStream<Uint8Array>` as an async iterable. Workerd and
+ * Node both support `Symbol.asyncIterator` on ReadableStream, but we
+ * spell the reader loop out so we don't depend on ambient lib typings.
+ */
+export declare function readableStreamToAsyncIterable(rs: ReadableStream<Uint8Array>): AsyncGenerator<Uint8Array, void, undefined>;
+/**
+ * Reason a tar entry was skipped and never yielded. Surfaced to callers
+ * via the optional `onSkip` callback on `streamTarEntries`.
+ *
+ * - 'too-large': size > MAX_FILE_BYTES. The most common reason Nimbus
+ *   cares about — it's what caused esbuild-wasm/esbuild.wasm to vanish
+ *   silently in Nimbus-in-Nimbus before the cap was raised.
+ * - 'non-regular': typeFlag indicates a symlink / hardlink / directory /
+ *   PaxHeader / GNU LongName etc. These aren't files we stage.
+ * - 'no-name': header parsed but name was empty (malformed or a PaxHeader
+ *   that our parser didn't recognize as non-regular).
+ */
+export type TarSkipReason = 'too-large' | 'non-regular' | 'no-name';
+/**
+ * Optional skip-observer passed to `streamTarEntries`. Called ONCE per
+ * skipped entry, with the declared name (may be empty for 'no-name'
+ * skips) and the declared size in bytes.
+ *
+ * Consumers typically push these into a per-package warnings array so
+ * users see what wasn't installed. The callback is synchronous and
+ * must not throw — thrown errors are swallowed to keep the extractor
+ * best-effort.
+ */
+export type TarSkipCallback = (name: string, size: number, reason: TarSkipReason) => void;
+/**
+ * Streaming tar extractor.
+ *
+ * Consumes an async iterable of Uint8Array chunks (the decompressed tar
+ * byte stream) and yields one `{ name, data }` entry per regular file,
+ * as each file completes.
+ *
+ * Memory invariant: holds at most one pending file's bytes (≤ MAX_FILE_BYTES)
+ * plus a small carry buffer for the tar header being assembled.
+ *
+ * Skips: symlinks, directories, hardlinks, long-name extensions (PaxHeader),
+ * and any file whose declared size exceeds MAX_FILE_BYTES.
+ *
+ * If `onSkip` is provided, it is invoked for each skipped entry with the
+ * name, declared size, and reason code. Callers that need to surface
+ * dropped-file warnings to users should pass one; legacy callers that
+ * omit the arg still behave exactly as before (silent skip).
+ */
+export declare function streamTarEntries(source: AsyncIterable<Uint8Array>, onSkip?: TarSkipCallback): AsyncGenerator<{
+    name: string;
+    data: Uint8Array;
+}, void, undefined>;
+//# sourceMappingURL=tarball-stream.d.ts.map

package/dist/npm/tarball-stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tarball-stream.d.ts","sourceRoot":"","sources":["../../src/npm/tarball-stream.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;;;;;;;;GASG;AACH,eAAO,MAAM,cAAc,WAAa,CAAC;AAEzC;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,UAAU,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAsBzG;AAED;;;;GAIG;AACH,wBAAuB,6BAA6B,CAClD,EAAE,EAAE,cAAc,CAAC,UAAU,CAAC,GAC7B,cAAc,CAAC,UAAU,EAAE,IAAI,EAAE,SAAS,CAAC,CAW7C;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,aAAa,GAAG,WAAW,GAAG,aAAa,GAAG,SAAS,CAAC;AAEpE;;;;;;;;;GASG;AACH,MAAM,MAAM,eAAe,GAAG,CAC5B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,aAAa,KAClB,IAAI,CAAC;AAEV;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAuB,gBAAgB,CACrC,MAAM,EAAE,aAAa,CAAC,UAAU,CAAC,EACjC,MAAM,CAAC,EAAE,eAAe,GACvB,cAAc,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,UAAU,CAAA;CAAE,EAAE,IAAI,EAAE,SAAS,CAAC,CA6GrE"}

package/dist/npm/tarball-stream.js

@@ -0,0 +1,205 @@
+/**
+ * npm-tarball-stream.ts — pure streaming tar primitives.
+ *
+ * Extracted from npm-tarball.ts so these helpers can be esbuild-bundled
+ * WITHOUT dragging in NpmCache / NpmResolver / SqliteVFS. Consumed by
+ * scripts/bundle-facet-workers.mjs which emits a string constant the
+ * NimbusLoaderPool uses to inject the tar parser into dynamic workers.
+ *
+ * Zero dependencies. Works identically on the supervisor and inside a
+ * facet isolate. Never buffers the full decompressed tarball — peak
+ * transient heap is one file's bytes plus a 512-byte carry.
+ */
+/**
+ * Maximum size of a single file inside a tarball. Larger entries are skipped.
+ *
+ * History: 5 MB was too low — it silently dropped `esbuild-wasm/esbuild.wasm`
+ * (11.35 MB on v0.24.2), which made Nimbus-in-Nimbus `npm run dev` fail with
+ * `No such module "esbuild-wasm/esbuild.wasm"` since the missing file caused
+ * esbuild's VFS plugin to mark the import `external`, and workerd's LOADER
+ * has no entry for that specifier. 20 MB covers esbuild-wasm with headroom
+ * while keeping per-facet peak heap bounded for the streaming extractor.
+ */
+export const MAX_FILE_BYTES = 20_000_000;
+/**
+ * Read one tar header (USTAR) out of `block`. Returns parsed fields or
+ * `null` for an end-of-archive block (all zeros).
+ */
+export function parseTarHeader(block) {
+    if (block[0] === 0)
+        return null;
+    let name = '';
+    for (let i = 0; i < 100 && block[i] !== 0; i++) {
+        name += String.fromCharCode(block[i]);
+    }
+    let prefix = '';
+    for (let i = 345; i < 500 && block[i] !== 0; i++) {
+        prefix += String.fromCharCode(block[i]);
+    }
+    if (prefix)
+        name = prefix + '/' + name;
+    // Strip the npm `package/` convention.
+    name = name.replace(/^package\//, '');
+    let sizeStr = '';
+    for (let i = 124; i < 136 && block[i] !== 0; i++) {
+        sizeStr += String.fromCharCode(block[i]);
+    }
+    const size = parseInt(sizeStr.trim(), 8) || 0;
+    const typeFlag = block[156];
+    return { name, size, typeFlag };
+}
+/**
+ * Wrap a `ReadableStream<Uint8Array>` as an async iterable. Workerd and
+ * Node both support `Symbol.asyncIterator` on ReadableStream, but we
+ * spell the reader loop out so we don't depend on ambient lib typings.
+ */
+export async function* readableStreamToAsyncIterable(rs) {
+    const reader = rs.getReader();
+    try {
+        while (true) {
+            const { value, done } = await reader.read();
+            if (done)
+                return;
+            if (value && value.length > 0)
+                yield value;
+        }
+    }
+    finally {
+        try {
+            reader.releaseLock();
+        }
+        catch { /* ignore */ }
+    }
+}
+/**
+ * Streaming tar extractor.
+ *
+ * Consumes an async iterable of Uint8Array chunks (the decompressed tar
+ * byte stream) and yields one `{ name, data }` entry per regular file,
+ * as each file completes.
+ *
+ * Memory invariant: holds at most one pending file's bytes (≤ MAX_FILE_BYTES)
+ * plus a small carry buffer for the tar header being assembled.
+ *
+ * Skips: symlinks, directories, hardlinks, long-name extensions (PaxHeader),
+ * and any file whose declared size exceeds MAX_FILE_BYTES.
+ *
+ * If `onSkip` is provided, it is invoked for each skipped entry with the
+ * name, declared size, and reason code. Callers that need to surface
+ * dropped-file warnings to users should pass one; legacy callers that
+ * omit the arg still behave exactly as before (silent skip).
+ */
+export async function* streamTarEntries(source, onSkip) {
+    let carry = new Uint8Array(0);
+    let state = { kind: 'header' };
+    function concat(a, b) {
+        if (a.length === 0)
+            return b;
+        if (b.length === 0)
+            return a;
+        const out = new Uint8Array(a.length + b.length);
+        out.set(a, 0);
+        out.set(b, a.length);
+        return out;
+    }
+    for await (const chunkRaw of source) {
+        let buf = concat(carry, chunkRaw);
+        let cursor = 0;
+        while (true) {
+            if (state.kind === 'header') {
+                if (buf.length - cursor < 512)
+                    break;
+                const header = buf.subarray(cursor, cursor + 512);
+                const parsed = parseTarHeader(header);
+                cursor += 512;
+                if (!parsed)
+                    return; // end-of-archive
+                const { name, size, typeFlag } = parsed;
+                const pad = size === 0 ? 0 : (512 - (size % 512)) % 512;
+                const isRegularFile = (typeFlag === 48 /* '0' */ || typeFlag === 0);
+                if (size === 0) {
+                    if (isRegularFile && name) {
+                        yield { name, data: new Uint8Array(0) };
+                    }
+                    state = { kind: 'header' };
+                    continue;
+                }
+                if (!isRegularFile || !name || size > MAX_FILE_BYTES) {
+                    if (onSkip) {
+                        // Classify before entering the skip state so the reason is
+                        // exact. Precedence matches the condition order above:
+                        // non-regular first (directories/symlinks/PaxHeaders are
+                        // skipped regardless of size), then no-name, then too-large.
+                        const reason = !isRegularFile
+                            ? 'non-regular'
+                            : !name
+                                ? 'no-name'
+                                : 'too-large';
+                        try {
+                            onSkip(name, size, reason);
+                        }
+                        catch { /* best-effort */ }
+                    }
+                    state = { kind: 'skip', remaining: size + pad };
+                    continue;
+                }
+                state = {
+                    kind: 'file',
+                    name,
+                    remaining: size,
+                    fileBuf: new Uint8Array(size),
+                    fileOffset: 0,
+                    pad,
+                    skip: false,
+                };
+                continue;
+            }
+            if (state.kind === 'file') {
+                const avail = buf.length - cursor;
+                if (avail === 0)
+                    break;
+                if (state.remaining > 0) {
+                    const take = Math.min(state.remaining, avail);
+                    state.fileBuf.set(buf.subarray(cursor, cursor + take), state.fileOffset);
+                    state.fileOffset += take;
+                    state.remaining -= take;
+                    cursor += take;
+                    if (state.remaining > 0)
+                        break;
+                }
+                if (state.pad > 0) {
+                    const avail2 = buf.length - cursor;
+                    if (avail2 === 0)
+                        break;
+                    const take = Math.min(state.pad, avail2);
+                    state.pad -= take;
+                    cursor += take;
+                    if (state.pad > 0)
+                        break;
+                }
+                yield { name: state.name, data: state.fileBuf };
+                state = { kind: 'header' };
+                continue;
+            }
+            // state.kind === 'skip'
+            const avail = buf.length - cursor;
+            if (avail === 0)
+                break;
+            const take = Math.min(state.remaining, avail);
+            cursor += take;
+            state.remaining -= take;
+            if (state.remaining > 0)
+                break;
+            state = { kind: 'header' };
+        }
+        if (cursor >= buf.length) {
+            carry = new Uint8Array(0);
+        }
+        else if (cursor === 0) {
+            carry = buf;
+        }
+        else {
+            carry = buf.slice(cursor);
+        }
+    }
+}

package/dist/npm/tarball.d.ts

@@ -0,0 +1,51 @@
+/**
+ * npm-tarball.ts — tarball extraction + cache-restore payload builder.
+ *
+ * Phase 2 A'.1 reduced this module to:
+ *   - extractTarball / extractTarballFromResponse — streaming gunzip+tar.
+ *     Used by the install-batch facet (which holds the bytes inside its
+ *     own 128 MiB envelope, not the supervisor's).
+ *   - buildCacheRestorePayload — supervisor-side BatchWritePayload
+ *     builder for the cached-tarball fast path. Runs only on a cache
+ *     hit; the bytes already live in the per-DO npm cache rather than
+ *     being fetched off the network.
+ *
+ * The legacy `fetchWaves` async generator + `buildBatchPayload` builder
+ * were removed — they ran in supervisor heap and held tarball bytes long
+ * enough to OOM the DO on large installs. The single batch-facet path
+ * (src/npm-install-batch-facet.ts) supersedes them.
+ */
+import type { NpmCache } from './cache.js';
+import type { ResolvedPackage, HoistPlan } from './resolver.js';
+import type { BatchWritePayload } from '../vfs/sqlite-vfs.js';
+export interface FetchedPackage {
+    pkg: ResolvedPackage;
+    files: Map<string, Uint8Array>;
+}
+/**
+ * Streaming extractor driven by a `Response` body.
+ *
+ * Pipes `resp.body` through `DecompressionStream('gzip')` (npm tarballs are
+ * always gzipped) and walks the tar stream entry-by-entry. Never buffers the
+ * full decompressed tarball — peak transient heap is one file's bytes plus a
+ * small carry buffer. This is the path used by live installs; the cache
+ * restore path (in-memory bytes from SQLite) still uses `extractTarball`.
+ *
+ * The returned Map is per-file Uint8Arrays, same shape as the legacy
+ * extractor so downstream `putTarballFiles` / `buildBatchPayload` don't care.
+ * If the response has no body (unusual but possible with some proxies), we
+ * fall back to `arrayBuffer()` + `extractTarball` so we still make progress.
+ */
+export declare function extractTarballFromResponse(resp: Response): Promise<Map<string, Uint8Array>>;
+/**
+ * Legacy buffered extractor. Kept for code paths that receive a fully-buffered
+ * tarball (e.g. the tarball cache restore path, which already stores bytes in
+ * SQLite as Uint8Arrays). New install paths use `streamTarEntries` instead.
+ */
+export declare function extractTarball(tarball: ArrayBuffer): Promise<Map<string, Uint8Array>>;
+/**
+ * Build a BatchWritePayload from the tarball cache (for packages that were
+ * already cached — no fetch needed).
+ */
+export declare function buildCacheRestorePayload(packages: ResolvedPackage[], hoistPlan: HoistPlan, nodeModulesDir: string, cache: NpmCache): BatchWritePayload;
+//# sourceMappingURL=tarball.d.ts.map

package/dist/npm/tarball.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tarball.d.ts","sourceRoot":"","sources":["../../src/npm/tarball.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC3C,OAAO,KAAK,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAChE,OAAO,KAAK,EAAoC,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAShG,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,eAAe,CAAC;IACrB,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;CAChC;AAUD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,0BAA0B,CAC9C,IAAI,EAAE,QAAQ,GACb,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAmClC;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,WAAW,GACnB,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAsBlC;AAoBD;;;GAGG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,eAAe,EAAE,EAC3B,SAAS,EAAE,SAAS,EACpB,cAAc,EAAE,MAAM,EACtB,KAAK,EAAE,QAAQ,GACd,iBAAiB,CAgEnB"}

package/dist/npm/tarball.js

@@ -0,0 +1,185 @@
+/**
+ * npm-tarball.ts — tarball extraction + cache-restore payload builder.
+ *
+ * Phase 2 A'.1 reduced this module to:
+ *   - extractTarball / extractTarballFromResponse — streaming gunzip+tar.
+ *     Used by the install-batch facet (which holds the bytes inside its
+ *     own 128 MiB envelope, not the supervisor's).
+ *   - buildCacheRestorePayload — supervisor-side BatchWritePayload
+ *     builder for the cached-tarball fast path. Runs only on a cache
+ *     hit; the bytes already live in the per-DO npm cache rather than
+ *     being fetched off the network.
+ *
+ * The legacy `fetchWaves` async generator + `buildBatchPayload` builder
+ * were removed — they ran in supervisor heap and held tarball bytes long
+ * enough to OOM the DO on large installs. The single batch-facet path
+ * (src/npm-install-batch-facet.ts) supersedes them.
+ */
+import { streamTarEntries, readableStreamToAsyncIterable, } from './tarball-stream.js';
+import { CHUNK_SIZE } from '../constants.js';
+// ── Tarball extraction ──────────────────────────────────────────────────
+//
+// The streaming primitives (parseTarHeader, streamTarEntries,
+// readableStreamToAsyncIterable, MAX_FILE_BYTES) live in
+// ./npm-tarball-stream.ts — a dependency-free leaf so
+// scripts/bundle-facet-workers.mjs can esbuild it into a string the facet
+// pool injects into dynamic workers. Import them directly from that module.
+/**
+ * Streaming extractor driven by a `Response` body.
+ *
+ * Pipes `resp.body` through `DecompressionStream('gzip')` (npm tarballs are
+ * always gzipped) and walks the tar stream entry-by-entry. Never buffers the
+ * full decompressed tarball — peak transient heap is one file's bytes plus a
+ * small carry buffer. This is the path used by live installs; the cache
+ * restore path (in-memory bytes from SQLite) still uses `extractTarball`.
+ *
+ * The returned Map is per-file Uint8Arrays, same shape as the legacy
+ * extractor so downstream `putTarballFiles` / `buildBatchPayload` don't care.
+ * If the response has no body (unusual but possible with some proxies), we
+ * fall back to `arrayBuffer()` + `extractTarball` so we still make progress.
+ */
+export async function extractTarballFromResponse(resp) {
+    const files = new Map();
+    const body = resp.body;
+    if (!body) {
+        // Fallback: no streamable body (shouldn't happen, but handle it).
+        const buf = await resp.arrayBuffer();
+        return extractTarball(buf);
+    }
+    // Time-bound the whole extraction to detect hung gunzip streams.
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 60_000);
+    try {
+        const decompressed = body.pipeThrough(new DecompressionStream('gzip'));
+        const source = readableStreamToAsyncIterable(decompressed);
+        for await (const entry of streamTarEntries(source)) {
+            if (controller.signal.aborted)
+                throw new Error('tarball extract timeout');
+            files.set(entry.name, entry.data);
+        }
+    }
+    catch (e) {
+        // On any error, just return whatever we managed to extract. Callers
+        // treat `files.size === 0` as a failed fetch and mark the package failed.
+        // If partial data is present (some files succeeded before the stream
+        // broke), we propagate it; the installer will re-fetch on mismatch.
+        if (files.size === 0) {
+            clearTimeout(timer);
+            throw e;
+        }
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    return files;
+}
+/**
+ * Legacy buffered extractor. Kept for code paths that receive a fully-buffered
+ * tarball (e.g. the tarball cache restore path, which already stores bytes in
+ * SQLite as Uint8Arrays). New install paths use `streamTarEntries` instead.
+ */
+export async function extractTarball(tarball) {
+    const files = new Map();
+    const raw = new Uint8Array(tarball);
+    // Adapter: wrap the single buffer as an async iterable. If gzipped, pipe
+    // through DecompressionStream so the streaming parser still sees tar bytes.
+    let source;
+    if (raw[0] === 0x1f && raw[1] === 0x8b) {
+        const rs = new Blob([tarball]).stream().pipeThrough(new DecompressionStream('gzip'));
+        source = readableStreamToAsyncIterable(rs);
+    }
+    else {
+        source = (async function* () { yield raw; })();
+    }
+    try {
+        for await (const entry of streamTarEntries(source)) {
+            files.set(entry.name, entry.data);
+        }
+    }
+    catch {
+        return files;
+    }
+    return files;
+}
+// ── Removed Phase 2 A'.1 ─────────────────────────────────────────────────
+//
+// The supervisor-resident `fetchWaves` async generator and its companion
+// `buildBatchPayload` BatchWritePayload builder were deleted when the
+// install became single-path (batch-facet only). Both ran in supervisor
+// heap and held tarball bytes in memory long enough to OOM the DO on
+// large installs. The single batch-facet path
+// (src/npm-install-batch-facet.ts) streams gunzip+tar inside a dynamic-
+// worker isolate with its own 128 MiB envelope and emits one writeBatch
+// RPC per package — the supervisor's heap only sees one inbound RPC
+// payload at a time.
+//
+// `WaveResult` is also gone (no other consumers). `FetchedPackage` is
+// retained because `extractTarballFromResponse` returns a `Files` map
+// that the cache restore path still uses.
+// ── Batch payload construction ──────────────────────────────────────────
+/**
+ * Build a BatchWritePayload from the tarball cache (for packages that were
+ * already cached — no fetch needed).
+ */
+export function buildCacheRestorePayload(packages, hoistPlan, nodeModulesDir, cache) {
+    const inodes = [];
+    const chunks = [];
+    const dirs = new Set();
+    const mtime = Date.now();
+    for (const pkg of packages) {
+        const files = cache.getTarballFiles(pkg.name, pkg.version);
+        if (files.length === 0)
+            continue;
+        const pkgDir = hoistPlan.root.has(pkg.name)
+            ? nodeModulesDir + '/' + pkg.name
+            : nodeModulesDir + '/' + pkg.name;
+        dirs.add(pkgDir);
+        for (const file of files) {
+            const filePath = pkgDir + '/' + file.relPath;
+            const parts = filePath.split('/');
+            for (let i = 1; i < parts.length; i++) {
+                dirs.add(parts.slice(0, i).join('/'));
+            }
+            const chunkCount = file.data.length === 0 ? 0 : Math.ceil(file.data.length / CHUNK_SIZE);
+            inodes.push({
+                path: filePath,
+                parentPath: parentOf(filePath),
+                isDir: false,
+                size: file.data.length,
+                mtime,
+                mode: 0o644,
+                chunkCount,
+            });
+            if (file.data.length <= CHUNK_SIZE) {
+                if (file.data.length > 0) {
+                    chunks.push({ path: filePath, chunkId: 0, data: file.data });
+                }
+            }
+            else {
+                for (let c = 0; c < chunkCount; c++) {
+                    chunks.push({
+                        path: filePath,
+                        chunkId: c,
+                        data: file.data.slice(c * CHUNK_SIZE, (c + 1) * CHUNK_SIZE),
+                    });
+                }
+            }
+        }
+    }
+    for (const dir of dirs) {
+        inodes.push({
+            path: dir,
+            parentPath: parentOf(dir),
+            isDir: true,
+            size: 0,
+            mtime,
+            mode: 0o755,
+            chunkCount: 0,
+        });
+    }
+    return { inodes, chunks };
+}
+// ── Helpers ─────────────────────────────────────────────────────────────
+function parentOf(path) {
+    return path.includes('/') ? path.substring(0, path.lastIndexOf('/')) : '';
+}