@try-works/dsh-tool-mode 0.0.0-stage → 0.5.44

package/lib/prepared-assets.d.ts

@@ -0,0 +1,269 @@
+/**
+ * The host's prepared-assets path (RES-02/03/05, the last in-repo slice):
+ * lock reading → preparation plan → approval-gated, digest-verified acquisition
+ * into an isolated content-addressed cache → the prepared-cold readiness flip →
+ * the PreparedAssetMapV1 the provider routes consume.
+ *
+ * The verified components this module finally gives callers to:
+ *
+ * - `planPreparation`/`DeploymentIdentity` (deployment-coordinator.ts) — the
+ *   pre-approval disclosure;
+ * - `acquireAsset` (asset-acquisition.ts) — digest+size verified, atomic,
+ *   resumable acquisition with tamper refusal;
+ * - `createHttpSource` (http-acquisition.ts) — the default ranged source.
+ *
+ * Honesty rules carried through:
+ *
+ * - a lock with no digests REFUSES (no guessed values);
+ * - an executable asset WITHOUT the explicit executable-preparation approval
+ *   refuses (RES-02);
+ * - a tampered final path is refused and never flips readiness;
+ * - the cache lives under the host's isolated state dir, never the repo or
+ *   HOME; a REAL network run is opt-in (the default source), and the suite
+ *   injects a local file source so it performs no network.
+ *
+ * @module @try-works/dsh-tool-mode/prepared-assets
+ */
+import { type AcquisitionSource } from './asset-acquisition.ts';
+import type { DeploymentIdentity, PlannedAsset, PreparationPlan } from './deployment-coordinator.ts';
+/** One lock asset, read from an extension's models.lock.json. */
+interface LockAsset {
+    readonly id: string;
+    readonly file: string;
+    readonly bytes: number;
+    readonly source: string;
+    readonly digest: string;
+    readonly executable: boolean;
+}
+/** One lock group with its enabled modalities and assets. */
+export interface LockGroup {
+    readonly id: string;
+    readonly assets: readonly LockAsset[];
+}
+/** One lock asset set, with the pinning state and license. */
+interface LockAssetSet {
+    readonly groups: readonly LockGroup[];
+    readonly revision: string;
+    readonly license: {
+        readonly name: string;
+        readonly url: string;
+    };
+}
+/** A parsed asset lock, ready to plan from. */
+export interface ParsedAssetLock {
+    readonly revision: string;
+    readonly license: {
+        readonly name: string;
+        readonly url: string;
+    };
+    readonly sets: Readonly<Record<string, LockAssetSet>>;
+}
+/** One verified asset FILE inside a prepared group (EXT-18). */
+export interface PreparedAssetFile {
+    /** The lock's asset id, e.g. `needle-engine-win-x64`. */
+    readonly assetId: string;
+    /** The lock's package-relative file path, e.g. `needle.exe`. */
+    readonly file: string;
+    /** The absolute path the file was materialized at. */
+    readonly path: string;
+    /** The pinned digest the materialized bytes verified against. */
+    readonly digest: string;
+}
+/** The group directories one preparation materialized. */
+export interface PreparedGroup {
+    /** The group id (text-backbone, vision-encoder, ...). */
+    readonly groupId: string;
+    /** The absolute directory holding the lock's per-asset file layout. */
+    readonly path: string;
+    /** The digests this group holds. */
+    readonly digests: readonly string[];
+    /**
+     * The individual verification handles of this group's assets.
+     *
+     * EXT-18's `PreparedAssetMapV1` is a mapping from asset ids to local handles, and
+     * a deployment may resolve an individual file by its lock asset id rather than a
+     * group directory (extension-needle does exactly that). Both projections are
+     * carried so neither consumer has to guess the other's convention.
+     */
+    readonly files: readonly PreparedAssetFile[];
+}
+/** The outcome of one preparation. */
+export type PreparationOutcome = {
+    readonly ok: true;
+    readonly groups: readonly PreparedGroup[];
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/**
+ * Parse a models.lock.json document.
+ *
+ * A lock with no digest on any asset REFUSES: a preparation built on guessed
+ * bytes would verify nothing (RES-03).
+ * @param bytes - the lock document.
+ * @returns the parsed lock.
+ */
+export declare function parseAssetLock(bytes: string): ParsedAssetLock;
+/** The identity the lock implies for one model deployment. */
+export declare function identityFor(extensionId: string, modelId: string, lock: ParsedAssetLock): DeploymentIdentity;
+/** The flat PlannedAsset list for one asset set. */
+export declare function plannedAssets(lock: ParsedAssetLock, assetSetId: string): readonly PlannedAsset[];
+/** The group map for one asset set, keyed by group id. */
+export declare function lockGroups(lock: ParsedAssetLock, assetSetId: string): readonly LockGroup[];
+/**
+ * Whether one lock `source` is a resolvable http(s) download URL.
+ * @param source - the lock's source string.
+ * @returns whether a transfer can be planned for it.
+ */
+export declare function isFetchableAssetSource(source: string): boolean;
+/** The minimum an asset needs for a source check. */
+export interface AssetSourceProbe {
+    readonly assetId: string;
+    readonly source: string;
+    readonly digest: string;
+}
+/**
+ * The operator-facing reason an asset has no transferable location.
+ *
+ * A prose `source` (e.g. "the split export of the pinned checkpoint") is not a
+ * download URL; the bytes must be produced by the documented export and placed in
+ * the prepared-assets cache (file name = the pinned digest) before a transfer-free
+ * preparation can succeed.
+ * @param assetId - the lock asset id.
+ * @param source - the prose/non-URL source.
+ * @returns the exact refusal reason.
+ */
+export declare function assetSourceUnavailableReason(assetId: string, source: string): string;
+/**
+ * The first planned asset with neither an http(s) URL nor bytes already in the cache.
+ *
+ * A cache hit is a legitimate source: a later acquisition still verifies the blob
+ * against the pinned digest, so pre-seeded artifacts are verified rather than trusted.
+ * @param assets - the planned assets to check.
+ * @param cacheRoot - the content-addressed cache root (blob filename = digest).
+ * @returns the first unavailable asset, or undefined when every asset is reachable.
+ */
+export declare function firstUnavailableAssetSource(assets: readonly AssetSourceProbe[], cacheRoot: string): AssetSourceProbe | undefined;
+/**
+ * The default free-space probe (TASK-131): `statfs` at the nearest existing
+ * ancestor of the path, so a cache root that does not exist yet probes the
+ * volume it will be created on.
+ * @param path - the cache root (which may not exist yet).
+ * @returns the available bytes (bavail × bsize), or 0 when unreadable.
+ */
+export declare function defaultFreeSpaceBytes(path: string): number;
+/** The host-side prepared-assets registry (session-scoped). */
+export interface PreparedAssetRegistry {
+    /** The content-addressed cache root (blob filename = the pinned digest). */
+    readonly cacheDirectory: string;
+    /** The plan the last extensions-prepare-plan built, per extension id. */
+    plans(): ReadonlyMap<string, PreparationPlan>;
+    /** The acquired group map per extension id (PreparedAssetMapV1 shapes). */
+    assetMapFor(extensionId: string): PreparedAssetMap | undefined;
+    /** All acquired group directories per extension id. */
+    groupsFor(extensionId: string): readonly PreparedGroup[];
+    /**
+     * Rebuild the in-process handles for a preparation that ALREADY happened in an
+     * earlier process (a restart): the group directories and their files are on
+     * disk, so this verifies each pinned file is present at its recorded size and
+     * publishes the same map `prepare` would have. It reads no bytes and transfers
+     * nothing; a missing or resized file refuses rather than publishing a stale
+     * handle, and the extension's own load-time digest verification remains the
+     * authority on content.
+     */
+    restore(extensionId: string, plan: PreparationPlan, groups: readonly LockGroup[]): PreparationOutcome;
+    /**
+     * Prepare one plan: acquire every asset (digest+size verified, atomic), then
+     * materialize the group directories. Idempotent: an already-acquired asset is
+     * a cache hit and its bytes are never re-fetched.
+     */
+    prepare(extensionId: string, plan: PreparationPlan, groups: readonly LockGroup[], options: {
+        readonly source: AcquisitionSource;
+        readonly allowExecutable: boolean;
+        readonly signal: AbortSignal;
+    }): Promise<PreparationOutcome>;
+    /**
+     * Remove one deployment's materialized asset groups (EXT-04 asset purging).
+     *
+     * Only the extension's OWN group directory is removed. The content-addressed
+     * blobs are shared by any other owner and are deliberately retained; an
+     * operator can reap truly unreferenced blobs separately without this call
+     * breaking a still-installed package.
+     * @param extensionId - the extension whose materialized groups are purged.
+     * @returns whether a group directory existed and was removed.
+     */
+    purge(extensionId: string): {
+        readonly removed: boolean;
+    };
+}
+/** The PreparedAssetMapV1 shape the provider routes consume. */
+export interface PreparedAssetMap {
+    readonly assetIds: readonly string[];
+    get(assetId: string): {
+        readonly path: string;
+        readonly digest: string;
+    } | undefined;
+}
+/** Options for the registry factory. */
+export interface PreparedAssetRegistryOptions {
+    /** The isolated cache root (the host's state dir, never the repo or HOME). */
+    readonly cacheRoot: string;
+    /** The default acquisition source (real network, opt-in). */
+    readonly defaultSource?: AcquisitionSource;
+    /**
+     * TASK-131 (RC2): the free-space probe. The preflight compares the planned
+     * missing bytes against the free bytes at the cache root BEFORE any
+     * transfer, so a disk that cannot hold the set refuses with a named,
+     * actionable error instead of a bare mid-stream `fetch failed`/ENOSPC.
+     *
+     * Injectable so the tests never need a real 3 GB download; the default
+     * reads the filesystem (`statfs`), walking up to the nearest existing
+     * ancestor when the cache root does not exist yet.
+     */
+    readonly freeSpaceBytes?: (path: string) => number;
+}
+/**
+ * The management-channel surface the host wires over the registry: the plan
+ * disclosure (before approval) and the acquisition (the approval itself, with
+ * the executable gate). The plan cache lives in the caller so a disclosed plan
+ * is exactly what a later prepare executes.
+ */
+export interface PrepareAssetsSurface {
+    /** Build and cache the preparation plan for one installed extension. */
+    plan(extensionId: string): PreparationPlan;
+    /** The lock groups behind the cached plan (the prepare call needs the layout). */
+    groupsForPlan(extensionId: string): readonly LockGroup[];
+    /** The manifest model id the plan prepares. */
+    modelIdFor(extensionId: string): string;
+    /** Acquire every planned asset with the given source. */
+    prepare(extensionId: string, options: {
+        readonly source: AcquisitionSource;
+        readonly allowExecutable: boolean;
+        readonly signal: AbortSignal;
+    }): Promise<PreparationOutcome>;
+    /** The prepared map, or undefined before a successful prepare. */
+    assetMapFor(extensionId: string): PreparedAssetMap | undefined;
+    /**
+     * Rebuild the handles for a preparation an EARLIER process performed, using the
+     * cache directories it left behind (a restart must not require a re-prepare
+     * before the tools work). Stat-only; no byte is read or transferred.
+     */
+    restore(extensionId: string): PreparationOutcome;
+    /**
+     * Remove one extension's materialized groups and reset its readiness to
+     * needs-preparation (EXT-04 asset purging); shared blobs stay.
+     */
+    purge(extensionId: string): Promise<{
+        readonly removed: boolean;
+    }>;
+    /** The underlying registry (diagnostics/tests). */
+    readonly registry: PreparedAssetRegistry;
+}
+/**
+ * Create the prepared-assets registry.
+ * @param options - the cache root and the default source.
+ * @returns the registry.
+ */
+export declare function createPreparedAssetRegistry(options: PreparedAssetRegistryOptions): PreparedAssetRegistry;
+export {};
+//# sourceMappingURL=prepared-assets.d.ts.map

package/lib/prepared-assets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prepared-assets.d.ts","sourceRoot":"","sources":["../src/prepared-assets.ts"],"names":[],"mappings":"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"}