@intx/tool-packaging 0.2.2 → 0.3.0

package/README.md

@@ -19,23 +19,28 @@ transitives are reachable from inside it.
 Concretely the loader:
 
 1. Walks every manifest entry and validates that each one is
-   registry-chain-consistent: every entry the manifest says lives at a
-   registry resolves end-to-end against that registry, and every entry
-   that lives in an asset resolves against the asset's `assetMounts`
-   map.
+   source-consistent: every entry the manifest says lives at a
+   registry resolves end-to-end against that registry; an asset entry
+   whose `package.format` is `"tarball"` resolves against the asset's
+   `assetMounts` map; an asset entry whose `package.format` is
+   `"source"` (a git subtree, used by source-format workflow
+   definitions) resolves against the separate `gitDirs` map.
 2. Materializes every entry into the content-addressable tarball
    cache: bytes pulled from the entry's source on a miss are verified
    through `cache.put`, and the bytes are then unpacked once via
    `cache.extractTarball`. A single sha512 produces a single
-   extraction shared across instances.
+   extraction shared across instances. A `"source"` asset entry is the
+   exception: it has no tarball and no SRI, so it bypasses the cache
+   entirely — its subtree is checked out in place from the indexed
+   `gitDir` (`materializeGitEntry`) and verified against the frozen git
+   `treeOid` rather than an sha512.
 3. Lays out each entry under `<scratch>/store/<name>/<version>/` by
-   hardlinking the file tree from the cache extraction. Each layout
-   directory then gets `node_modules/<dep>` symlinked into it pointing
-   at the sibling `store/<dep>/<depVersion>/` chosen for that
-   requirer. Hardlinks keep on-disk usage to one copy per integrity
-   per filesystem; symlinks at the `node_modules/` boundary let
-   Node's realpath-based resolver walk to the dep's own layout dir
-   (which has its own `node_modules/`).
+   copying the file tree from the cache extraction — or, for a
+   `"source"` entry, from its git checkout. Each layout directory then
+   gets `node_modules/<dep>` symlinked into it pointing at the sibling
+   `store/<dep>/<depVersion>/` chosen for that requirer. Symlinks at
+   the `node_modules/` boundary let Node's realpath-based resolver walk
+   to the dep's own layout dir (which has its own `node_modules/`).
 4. Dynamically imports each top-level entry's `interchange.tools`
    module and collects the `AnnotatedToolFactory` /
    `AnnotatedPluginFactory` values it exports.

package/dist/atomic-apply.d.ts

@@ -12,6 +12,11 @@ export interface ApplyAtomicArgs {
      * Forwarded verbatim to `ToolLoader.loadManifest`.
      */
     readonly assetMounts: ReadonlyMap<string, string>;
+    /**
+     * Maps a source-format asset entry's `source.assetId` to an absolute
+     * indexed git directory. Forwarded verbatim to `ToolLoader.loadManifest`.
+     */
+    readonly gitDirs: ReadonlyMap<string, string>;
     readonly attemptId: string;
     /**
      * The deploy id the instance is currently running. Retained on disk

package/dist/atomic-apply.js

@@ -127,6 +127,7 @@ export async function applyAtomic(args) {
             instanceScratchDir: deployDir,
             assetRoot: args.assetRoot,
             assetMounts: args.assetMounts,
+            gitDirs: args.gitDirs,
         });
     }
     catch (err) {

package/dist/cache.d.ts

@@ -18,7 +18,7 @@ export interface TarballCache {
      * cannot reuse the on-disk extraction. The extraction directory's
      * physical reclaim is deferred until every in-flight reader released
      * by `extractTarball` has dropped its reference, so an evict that
-     * races a concurrent `hardlinkTree` walk of the same extraction does
+     * races a concurrent `copyTree` walk of the same extraction does
      * not pull the tree out from under the walk and surface as ENOENT.
      *
      * Until every reader releases, the on-disk extraction is left in

package/dist/cache.js

@@ -11,10 +11,11 @@
 // one entry (used after extraction discovers a corrupted file on disk).
 //
 // `maxBytes` covers both the tarball bytes and the size of the
-// extracted directory tree the loader hardlinks from. The extraction
+// extracted directory tree the loader copies from. The extraction
 // tree dominates disk usage in practice (tarballs are gzip-compressed;
-// the unpacked tree is multiples larger), so the cap reflects the
-// caller-visible cost of holding an entry.
+// the unpacked tree is multiples larger), so the cap reflects the cost
+// of holding one cache entry but excludes the loader's per-instance
+// copies.
 //
 // Integrity is verified on store and re-verified inside
 // `extractTarball` before unpacking. `get` returns bytes without
@@ -24,7 +25,7 @@
 //
 // `extractTarball` is the second face of the same on-disk store: it
 // unpacks the tarball into a sibling `extracted/` directory keyed by
-// the same integrity, so the per-instance loader can symlink into a
+// the same integrity, so the per-instance loader can copy from a
 // stable, deduplicated extraction without re-doing the tar work on
 // every apply. The unpack is gated by a per-integrity tmp-and-rename
 // dance with the same crash-safety properties as `put`.
@@ -82,7 +83,7 @@ export function createTarballCache(config) {
     // defers physical removal of the extraction tree until the count
     // reaches zero. This decouples mark-as-bad (atomic, prompt) from
     // physical reclaim (deferred, safe) so an integrity-mismatch evict
-    // that races a concurrent `hardlinkTree` walk against the same
+    // that races a concurrent `copyTree` walk against the same
     // extraction does not pull the tree out from under the walk and
     // surface as ENOENT mid-readdir.
     //
@@ -238,21 +239,15 @@ export function createTarballCache(config) {
     }
     /**
      * Sum the on-disk size of every regular file under `dir` recursively.
-     * Returns 0 when `dir` does not exist. Hardlinks are counted once
-     * per inode would be ideal, but `node:fs` does not expose inode-
-     * dedup walking without a manual ino map; the loader hardlinks
-     * extraction trees into per-instance store dirs, so the extraction
-     * tree itself holds one link per file and `stat.size` per entry is
-     * the right number to charge to this cache entry.
+     * Returns 0 when `dir` does not exist. Each regular file's
+     * `stat.size` is charged to this cache entry once.
      *
      * ACCOUNTING vs. DISK USAGE: `maxBytes` bounds the sum reported by
      * this walker, not the actual disk consumption of the cache plus
-     * its downstream hardlink consumers. The loader's per-instance
-     * store dirs share inodes with `cache/extracted/`; evicting an
-     * entry here drops the cache's reference but the underlying file
-     * survives as long as any per-instance dir still points at it.
-     * The cap is a steady-state ceiling on the cache tree's own
-     * accounting, not a disk-usage limit. Concurrent vanishes during
+     * its downstream consumers. The loader's per-instance store dirs
+     * contain independent copies that are outside this cache tree, so
+     * the cap is a steady-state ceiling on the cache's own accounting,
+     * not a sidecar-wide disk-usage limit. Concurrent vanishes during
      * the walk are silently dropped via the inner `lstat` try/catch
      * below; under the single-process contract this is rare, but the
      * returned `total` reports the cap-relevant sum within one sweep's
@@ -262,7 +257,7 @@ export function createTarballCache(config) {
      * `lstat` here returns the link itself rather than its target, and
      * `dirent.isSymbolicLink()` is the entry-walk equivalent. An npm
      * tarball that ships symlinks is preserved verbatim by the loader's
-     * hardlink-tree pass; charging the link's own size (zero in our
+     * copy-tree pass; charging the link's own size (zero in our
      * accounting) avoids both symlink-loop divergence and double-counting
      * the target through whatever path also names it directly.
      *
@@ -464,7 +459,7 @@ export function createTarballCache(config) {
                     throw err;
             }
             // The extraction is derived from the tarball bytes and is
-            // useless once the tarball is gone. If a hardlinkTree walk is
+            // useless once the tarball is gone. If a copyTree walk is
             // in-flight for the same integrity, removing the tree now would
             // surface as ENOENT mid-walk; defer the physical reclaim until
             // every outstanding `release` from `extractTarball` has fired.

package/dist/git-materialize.d.ts

@@ -0,0 +1,19 @@
+import type { ToolPackageAssetSourceTree } from "@intx/types/tool-packages";
+/**
+ * Read the entry's pinned subtree from `gitDir`, verify it against the frozen
+ * `treeOid`, and write it into a fresh scratch directory under
+ * `instanceScratchDir`. Returns the same `{ dir, release }` shape the tarball
+ * path returns; `release` is a no-op because there is no content-addressed
+ * cache handle to hold — the scratch dir lives under the deploy directory the
+ * caller reclaims.
+ */
+export declare function materializeGitEntry(args: {
+    tree: ToolPackageAssetSourceTree;
+    name: string;
+    version: string;
+    gitDir: string;
+    instanceScratchDir: string;
+}): Promise<{
+    dir: string;
+    release: () => void;
+}>;

package/dist/git-materialize.js

@@ -0,0 +1,77 @@
+// Materialize a source-format asset closure entry (`kind:"asset"` with
+// `package.format:"source"`) from an indexed pack.
+//
+// A source-format entry's files come from a subtree of a hub `workflow` git
+// asset at a pinned commit, not a tarball. The pack is indexed once at
+// checkout time (the caller supplies the resulting `gitDir`); this reads the
+// pinned subtree straight from those authenticated objects, verifies its git
+// tree oid against the frozen `treeOid`, and writes the subtree into a scratch
+// directory the store layout then copies from. The tarball cache is bypassed:
+// `treeOid` is a git oid, not an SRI.
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import git from "isomorphic-git";
+import { getLogger } from "@intx/log";
+import { DEFAULT_PACK_MATERIALIZATION_LIMITS, writeTreeToDisk, } from "@intx/storage-isogit/node";
+import { ToolLoaderError, describeError } from "./loader-internal.js";
+const logger = getLogger(["sidecar", "tool-packaging", "git-materialize"]);
+/**
+ * Read the entry's pinned subtree from `gitDir`, verify it against the frozen
+ * `treeOid`, and write it into a fresh scratch directory under
+ * `instanceScratchDir`. Returns the same `{ dir, release }` shape the tarball
+ * path returns; `release` is a no-op because there is no content-addressed
+ * cache handle to hold — the scratch dir lives under the deploy directory the
+ * caller reclaims.
+ */
+export async function materializeGitEntry(args) {
+    const { tree: source, name, version, gitDir, instanceScratchDir } = args;
+    // `readTree` peels the commit to its tree; `filepath` then navigates to the
+    // pinned member. `packageDir === "."` selects the repo root, i.e. the
+    // commit's own tree, so it takes no `filepath`.
+    let subtreeOid;
+    try {
+        const { oid } = await git.readTree({
+            fs,
+            dir: gitDir,
+            oid: source.commitSha,
+            ...(source.packageDir === "." ? {} : { filepath: source.packageDir }),
+        });
+        subtreeOid = oid;
+    }
+    catch (err) {
+        throw new ToolLoaderError({
+            category: "git.materialization.failed",
+            message: `git subtree ${JSON.stringify(source.packageDir)} for ${name}@${version} could not be read at ${source.commitSha}: ${describeError(err)}`,
+            package: { name, version },
+        });
+    }
+    // The frozen `treeOid` is the content identity. The hub read it from the
+    // same git objects, so a mismatch means the delivered pack diverges from
+    // what was frozen; fail loud rather than materialize unverified bytes.
+    if (subtreeOid !== source.treeOid) {
+        throw new ToolLoaderError({
+            category: "git.materialization.failed",
+            message: `git subtree ${JSON.stringify(source.packageDir)} at ${source.commitSha} for ${name}@${version} hashed to tree ${subtreeOid}, not the frozen ${source.treeOid}`,
+            package: { name, version },
+        });
+    }
+    const dir = await fs.mkdtemp(path.join(instanceScratchDir, "git-"));
+    try {
+        await writeTreeToDisk(gitDir, dir, subtreeOid, DEFAULT_PACK_MATERIALIZATION_LIMITS);
+    }
+    catch (err) {
+        // Best-effort cleanup of the partial scratch dir; log a secondary rm
+        // failure so it does not silently mask state. The primary error is still
+        // thrown. Mirrors the cleanup logging in `applyAssetPack` and the sidecar's
+        // source-asset delivery.
+        await fs.rm(dir, { recursive: true, force: true }).catch((rmErr) => {
+            logger.warn `git subtree scratch cleanup failed at ${dir}: ${describeError(rmErr)}`;
+        });
+        throw new ToolLoaderError({
+            category: "git.materialization.failed",
+            message: `writing git subtree for ${name}@${version} failed: ${describeError(err)}`,
+            package: { name, version },
+        });
+    }
+    return { dir, release: () => undefined };
+}

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { type ClosureResolver, type ClosureResolverConfig, type MaterializedRef, type Packument, type PackumentFetcher, type PackumentVersion, type PeerDependencyViolation, type RegistryConfig, type RegistrySource, type ScopeRoute, AssetRegistrySource, HttpRegistrySource, ManifestInvalidError, createClosureResolver, parsePin, } from "./resolver.js";
 export { type TarballCache, type TarballCacheConfig, TarballIntegrityMismatchError, createTarballCache, } from "./cache.js";
-export { type HostPlatform, type LoadManifestArgs, type LoadedDirectorFactory, type LoadedToolFactory, type LoadedToolPackage, type LoaderConfig, type TarballFetcher, type ToolLoader, ToolLoaderError, createToolLoader, } from "./loader.js";
+export { type HostPlatform, type LoadManifestArgs, type LoadedDirectorFactory, type LoadedToolFactory, type LoadedToolPackage, type LoaderConfig, type MaterializeClosureArgs, type MaterializeClosureResult, type TarballFetcher, type ToolLoader, ToolLoaderError, createToolLoader, materializeClosure, storeEntryDir, } from "./loader.js";
 export { type ApplyAtomicArgs, type ApplyAtomicFailure, type ApplyAtomicResult, type ApplyAtomicSuccess, applyAtomic, } from "./atomic-apply.js";
 export { type ExtractPackageJSONOutcome, extractTarballPackageJSON, } from "./package-json-extract.js";

package/dist/index.js

@@ -25,6 +25,6 @@
 //       `ApplyAtomicFailure` the caller surfaces as a rejected apply.
 export { AssetRegistrySource, HttpRegistrySource, ManifestInvalidError, createClosureResolver, parsePin, } from "./resolver.js";
 export { TarballIntegrityMismatchError, createTarballCache, } from "./cache.js";
-export { ToolLoaderError, createToolLoader, } from "./loader.js";
+export { ToolLoaderError, createToolLoader, materializeClosure, storeEntryDir, } from "./loader.js";
 export { applyAtomic, } from "./atomic-apply.js";
 export { extractTarballPackageJSON, } from "./package-json-extract.js";

package/dist/loader-internal.d.ts

@@ -0,0 +1,47 @@
+import type { DeployApplyErrorCategory } from "@intx/types/sidecar";
+/**
+ * Maximum bytes a single registry tarball fetch will read before aborting. The
+ * cap bounds the memory a malicious or misconfigured registry can force a
+ * deploy to buffer while the atomic-apply mirror replays it.
+ */
+export declare const DEFAULT_MAX_REGISTRY_TARBALL_BYTES: number;
+/**
+ * Default deadline for a single HTTP-registry tarball fetch, covering both the
+ * request and the streamed body read. `readResponseWithLimit` consumes the body
+ * through a manual reader loop, so the byte cap bounds size but nothing bounds
+ * time: a registry that accepts the connection and then stalls mid-stream would
+ * block the fetch -- and the deploy's tool materialization awaiting it --
+ * indefinitely. The deadline is generous so a legitimately large tarball on a
+ * slow link still completes within it. Callers that need a different bound pass
+ * `registryFetchTimeoutMs` to `createToolLoader`.
+ */
+export declare const DEFAULT_REGISTRY_FETCH_TIMEOUT_MS: number;
+/**
+ * A tool-loader failure carrying the atomic-apply error category (and, when the
+ * failure is attributable to a specific package, its name and version) so the
+ * apply layer can map every loader failure onto a `DeployApplyErrorCategory`.
+ */
+export declare class ToolLoaderError extends Error {
+    readonly category: DeployApplyErrorCategory;
+    readonly package: {
+        readonly name: string;
+        readonly version: string;
+    } | undefined;
+    constructor(opts: {
+        category: DeployApplyErrorCategory;
+        message: string;
+        package?: {
+            name: string;
+            version: string;
+        };
+    });
+}
+/**
+ * Whether a `platform`/`os`/`cpu`-style allowlist matches `host`. A list with a
+ * `!`-negated entry matches everything except the negated hosts; an unnegated
+ * list matches only its members.
+ */
+export declare function platformListMatches(entries: readonly string[], host: string): boolean;
+export declare function isEEXIST(err: unknown): boolean;
+export declare function isENOENT(err: unknown): boolean;
+export declare function describeError(err: unknown): string;

package/dist/loader-internal.js

@@ -0,0 +1,66 @@
+// Shared internals of the tool-package loader: the failure type, the fetch
+// byte/time caps, and the small cross-cutting helpers. Split out so the
+// registry-fetch and store-layout modules and `loader.ts` itself can all depend
+// on them without an import cycle. `loader.ts` re-exports the public members
+// (`ToolLoaderError`, the `DEFAULT_*` caps) so existing consumers are unaffected.
+/**
+ * Maximum bytes a single registry tarball fetch will read before aborting. The
+ * cap bounds the memory a malicious or misconfigured registry can force a
+ * deploy to buffer while the atomic-apply mirror replays it.
+ */
+export const DEFAULT_MAX_REGISTRY_TARBALL_BYTES = 10 * 1024 * 1024;
+/**
+ * Default deadline for a single HTTP-registry tarball fetch, covering both the
+ * request and the streamed body read. `readResponseWithLimit` consumes the body
+ * through a manual reader loop, so the byte cap bounds size but nothing bounds
+ * time: a registry that accepts the connection and then stalls mid-stream would
+ * block the fetch -- and the deploy's tool materialization awaiting it --
+ * indefinitely. The deadline is generous so a legitimately large tarball on a
+ * slow link still completes within it. Callers that need a different bound pass
+ * `registryFetchTimeoutMs` to `createToolLoader`.
+ */
+export const DEFAULT_REGISTRY_FETCH_TIMEOUT_MS = 120 * 1000;
+/**
+ * A tool-loader failure carrying the atomic-apply error category (and, when the
+ * failure is attributable to a specific package, its name and version) so the
+ * apply layer can map every loader failure onto a `DeployApplyErrorCategory`.
+ */
+export class ToolLoaderError extends Error {
+    category;
+    package;
+    constructor(opts) {
+        super(opts.message);
+        this.name = "ToolLoaderError";
+        this.category = opts.category;
+        this.package = opts.package;
+    }
+}
+/**
+ * Whether a `platform`/`os`/`cpu`-style allowlist matches `host`. A list with a
+ * `!`-negated entry matches everything except the negated hosts; an unnegated
+ * list matches only its members.
+ */
+export function platformListMatches(entries, host) {
+    const hasNegation = entries.some((e) => e.startsWith("!"));
+    if (hasNegation) {
+        return !entries.includes(`!${host}`);
+    }
+    return entries.includes(host);
+}
+export function isEEXIST(err) {
+    if (err === null || typeof err !== "object")
+        return false;
+    if (!("code" in err))
+        return false;
+    return err.code === "EEXIST";
+}
+export function isENOENT(err) {
+    if (err === null || typeof err !== "object")
+        return false;
+    if (!("code" in err))
+        return false;
+    return err.code === "ENOENT";
+}
+export function describeError(err) {
+    return err instanceof Error ? err.message : String(err);
+}

package/dist/loader.d.ts

@@ -1,8 +1,12 @@
 import type { AnnotatedDirectorFactory, AnnotatedPluginFactory, AnnotatedToolFactory, BaseEnv } from "@intx/agent";
-import type { DeployApplyErrorCategory } from "@intx/types/sidecar";
+import type { ToolCredentialDeclaration } from "@intx/types/package-json";
 import type { ToolPackageManifest, ToolPackageManifestEntry } from "@intx/types/tool-packages";
 import type { TarballCache } from "./cache.js";
+import { DEFAULT_MAX_REGISTRY_TARBALL_BYTES, DEFAULT_REGISTRY_FETCH_TIMEOUT_MS, ToolLoaderError } from "./loader-internal.js";
+import { buildRegistryFetchOpts, readResponseWithLimit } from "./registry-fetch.js";
 import type { RegistryConfig } from "./resolver.js";
+import { materializeClosure, storeEntryDir } from "./store-layout.js";
+export { ToolLoaderError, DEFAULT_MAX_REGISTRY_TARBALL_BYTES, DEFAULT_REGISTRY_FETCH_TIMEOUT_MS, buildRegistryFetchOpts, readResponseWithLimit, materializeClosure, storeEntryDir, };
 /**
  * Loaded factory shape. We re-export `AnnotatedToolFactory<BaseEnv>` so
  * callers receive the canonical agent type without re-deriving it; the
@@ -40,6 +44,17 @@ export interface LoadedToolPackage {
      * valid.
      */
     readonly directors: readonly LoadedDirectorFactory[];
+    /**
+     * The provider-backed credentials the package's tools statically
+     * declare via `interchange.credentials`. A declaration is advisory: it
+     * names a handle the agent definition binds to a concrete credential and
+     * the launch-time grant gate authorizes; it consents to nothing on its
+     * own. Surfaced here -- parsed from the SAME `package.json` the code
+     * loaded from -- so the declared set is the authoritative one (the loaded
+     * package's own) rather than a hub manifest that could drift. Empty when
+     * the package omits the field; a tools-only package stays valid.
+     */
+    readonly credentials: readonly ToolCredentialDeclaration[];
 }
 export interface HostPlatform {
     readonly os: string;
@@ -96,25 +111,6 @@ export interface LoaderConfig {
      */
     readonly importModule?: (importUrl: string) => Promise<unknown>;
 }
-/**
- * Default cap on a single HTTP-registry tarball fetch. Matches the
- * hub's `DEFAULT_HUB_MAX_TARBALL_BYTES` so a tarball the hub accepted
- * on upload is one the sidecar can also fetch back when a registry
- * mirror replays it.
- */
-export declare const DEFAULT_MAX_REGISTRY_TARBALL_BYTES: number;
-/**
- * Default deadline for a single HTTP-registry tarball fetch, covering
- * both the request and the streamed body read. `readResponseWithLimit`
- * consumes the body through a manual reader loop, so the byte cap bounds
- * size but nothing bounds time: a registry that accepts the connection
- * and then stalls mid-stream would block the fetch -- and the deploy's
- * tool materialization awaiting it -- indefinitely.
- * The deadline is generous so a legitimately large tarball on a slow
- * link still completes within it. Callers that need a different bound
- * pass `registryFetchTimeoutMs` to `createToolLoader`.
- */
-export declare const DEFAULT_REGISTRY_FETCH_TIMEOUT_MS: number;
 export type TarballFetcher = (entry: ToolPackageManifestEntry, ctx: {
     registries: ReadonlyMap<string, RegistryConfig>;
     assetRoot: string;
@@ -138,52 +134,65 @@ export interface LoadManifestArgs {
      * sources from an asset.
      */
     readonly assetMounts: ReadonlyMap<string, string>;
+    /**
+     * Maps a source-format asset entry's `source.assetId` to an absolute path
+     * to an indexed git directory whose object database holds the pinned
+     * commit and its trees. The caller checks the delivered pack out into
+     * this directory once per asset before applying. Empty map is valid
+     * when no entry sources from a git subtree.
+     */
+    readonly gitDirs: ReadonlyMap<string, string>;
 }
 export interface ToolLoader {
     loadManifest(args: LoadManifestArgs): Promise<LoadedToolPackage[]>;
 }
-export declare class ToolLoaderError extends Error {
-    readonly category: DeployApplyErrorCategory;
-    readonly package: {
-        readonly name: string;
-        readonly version: string;
-    } | undefined;
-    constructor(opts: {
-        category: DeployApplyErrorCategory;
-        message: string;
-        package?: {
-            name: string;
-            version: string;
-        };
-    });
+/**
+ * Arguments for `materializeClosure`, the eval-free materialization
+ * primitive `loadManifest` wraps. Everything phases 1-2 need is passed
+ * explicitly so the function stands alone without a `ToolLoader`
+ * instance: the closure's `cache`, `registries`, `host`, and resolved
+ * `fetchTarball` are threaded in directly. There is no import seam here
+ * because `materializeClosure` never imports author code — that first
+ * `import()` belongs to `loadManifest`'s phase-3 loop.
+ */
+export interface MaterializeClosureArgs {
+    readonly manifest: ToolPackageManifest;
+    readonly instanceScratchDir: string;
+    readonly assetRoot: string;
+    readonly assetMounts: ReadonlyMap<string, string>;
+    /**
+     * Maps a source-format asset entry's `source.assetId` to an absolute
+     * indexed git directory the pinned subtree is read from. Empty map is valid
+     * when no entry sources from a git subtree.
+     */
+    readonly gitDirs: ReadonlyMap<string, string>;
+    readonly host: HostPlatform;
+    readonly cache: TarballCache;
+    /**
+     * Registry identifier → registry config, the same map
+     * `createToolLoader` keys its registries under. Used both to gate
+     * `kind: "registry"` entries against the sidecar config and as the
+     * `registries` context handed to `fetchTarball`.
+     */
+    readonly registries: ReadonlyMap<string, RegistryConfig>;
+    /**
+     * Resolved tarball fetcher. `createToolLoader` builds the default
+     * (npm-registry-fetch + filesystem) fetcher or honors a test seam and
+     * threads the result here; `materializeClosure` does not construct one
+     * of its own.
+     */
+    readonly fetchTarball: TarballFetcher;
 }
-export declare function createToolLoader(config: LoaderConfig): ToolLoader;
-export declare function buildRegistryFetchOpts(registry: RegistryConfig): Record<string, unknown>;
 /**
- * Read an HTTP-registry tarball response into a Uint8Array while enforcing
- * `maxBytes`. Two guards:
- *
- *   1. If the upstream sent a `Content-Length` header, parse it (digit-
- *      only, per RFC 9110 §8.6) and reject up front when the declared
- *      length exceeds the cap. A header that fails the digit shape is
- *      also rejected so a header like `1e9` cannot read as 1e9 against
- *      `Number()` while a digit-only cap check would pass.
- *   2. Stream the body chunk-by-chunk, tallying byte length, and abort
- *      the read when the running total crosses the cap. This catches
- *      the missing-or-lying header case.
- *
- * An optional `signal` adds a time guard: when it aborts (the caller's
- * fetch deadline), the in-flight read is cancelled and the call rejects,
- * so a registry that streams the body slowly or stalls mid-stream cannot
- * outlast the deadline while staying under the byte cap.
- *
- * All rejections surface as `registry.fetch.failed` so the apply layer
- * routes them the same as any other registry-side fetch defect.
- *
- * Exported for direct unit testing.
+ * Result of `materializeClosure`: the per-instance store directory the
+ * closure was laid out under (`<instanceScratchDir>/store`), plus the exact
+ * host-filtered entries that were laid out under it. A caller computes a
+ * specific package's directory with `storeEntryDir`, and iterates `entries` to
+ * load exactly what was materialized -- rather than re-deriving the host filter
+ * with a second predicate and risking the two drifting apart.
  */
-export declare function readResponseWithLimit(res: Response, maxBytes: number, ctx: {
-    readonly registry: string;
-    readonly name: string;
-    readonly version: string;
-}, signal?: AbortSignal): Promise<Uint8Array>;
+export interface MaterializeClosureResult {
+    readonly storeDir: string;
+    readonly entries: readonly ToolPackageManifestEntry[];
+}
+export declare function createToolLoader(config: LoaderConfig): ToolLoader;