@try-works/dsh-model-as-tool 0.1.2 → 0.3.6

package/lib/planning.js

@@ -0,0 +1,457 @@
+/**
+ * The host-side `tools_plan` discipline (NDL-02, NDL-03).
+ *
+ * The Needle extension implements the ENGINE half of the planning contract: one-shot
+ * proposals over a caller-supplied tool list, with the list validated by the extension
+ * itself. What NDL-02 forbids is the HOST trusting that caller-supplied list. The list is
+ * the authorization surface: whatever schemas the planner receives, it may propose calls
+ * against, and a caller who could hand over the whole registry — or a list of its own
+ * invention — would be using `tools_plan` as a permission oracle. So the host owns four
+ * things the extension never sees:
+ *
+ * 1. **The frozen snapshot.** At first use, the host captures the currently registered
+ *    tool schemas (name, description, parameters — nothing executable) into a snapshot
+ *    that is deep-copied and deep-frozen. Later registry changes cannot leak into it, and
+ *    a holder of the snapshot cannot mutate it. The planner receives ONLY entries from
+ *    this snapshot; it never receives the caller's declared tool list, an unfiltered
+ *    registry, or anything callable (NDL-02's "narrow public broker").
+ *
+ * 2. **The requested-name gate.** The caller asks for names; the host intersects them
+ *    with the LIVE registry. Unknown names (never registered, or withdrawn), excluded
+ *    names (management and composition), duplicates, and live-but-unsnapshotted names are
+ *    all REJECTED — the whole call fails with every rejection named, never a silently
+ *    smaller offer set (the CODE-03 "reject rather than omit" discipline).
+ *
+ * 3. **Host-side re-validation.** When the provider returns proposals, the host
+ *    re-validates every proposal against the SNAPSHOT schema, not the provider's own
+ *    verdict. A proposal the engine fabricated outside the offered set, or arguments that
+ *    violate the frozen schema, are moved to `rejected` with the violations named.
+ *
+ * 4. **Fresh policy checks.** A proposal is DATA; executing it goes through the registry's
+ *    own admission later (NDL-03). The host still refuses to return a proposal whose tool
+ *    is no longer registered — deactivated or withdrawn after the snapshot was captured —
+ *    so a caller never receives a proposal for a tool that is not currently callable.
+ *
+ * Everything here is a pure function over plain data: the DSH context, the store and the
+ * lifecycle stay in the host wiring, so the discipline is testable without mounting a
+ * plugin and without the pinned engine artifacts.
+ *
+ * @module @try-works/dsh-model-as-tool/planning
+ */
+import { Ajv } from 'ajv';
+import { EXCLUDED_BINDINGS } from "./ptc-authority.js";
+/**
+ * The validator the proposal re-checks compile with.
+ *
+ * Deliberately NON-STRICT, matching the extension's own `checkArguments` policy: the
+ * snapshot entries come from the DSH registry's model-facing projection, which may omit
+ * keywords a strict compiler refuses (`additionalProperties` in particular), and a
+ * caller-facing tool list must not be rejected because the registry's projection is not
+ * strict-authored. The strict compiler stays for DECLARED schemas, which are authored
+ * under the contracts package's own discipline.
+ */
+const PROPOSAL_AJV = new Ajv({ allErrors: true, strict: false });
+/** The caller-facing name of the planning contract (NDL-02). */
+export const PLANNING_TOOL_NAME = 'tools_plan';
+/**
+ * Tool names the planning surface must never offer or propose (NDL-02 + CODE-07).
+ *
+ * The program-binding exclusions are reused rather than restated: a proposal targeting
+ * `tool_mode_run` (the recursive composition door) or the management surface would hand a
+ * caller the same proxy grant CODE-07 withholds from programs. `tools_plan` itself is
+ * added so a plan can never propose planning — recursive planning is noise, and the
+ * planning tool is not a leaf inference tool.
+ *
+ * SEALED like {@link EXCLUDED_BINDINGS} — a frozen ARRAY, because freezing a `Set` does
+ * not stop `add`/`delete` — so the planning surface and the program-binding surface
+ * cannot desynchronize through a runtime mutation.
+ */
+export const PLANNING_EXCLUDED_TOOLS = Object.freeze([...EXCLUDED_BINDINGS, PLANNING_TOOL_NAME]);
+/**
+ * Deep-copy a JSON value, guarding against cycles.
+ *
+ * Hand-rolled rather than `structuredClone` so the module stays independent of which
+ * global typings a build resolves, and so a cyclic schema cannot recurse forever.
+ * @param value - the value to copy.
+ * @param seen - objects already copied, keyed by source.
+ * @returns the copy.
+ */
+function deepClone(value, seen) {
+    if (value === null || typeof value !== 'object')
+        return value;
+    const existing = seen.get(value);
+    if (existing !== undefined)
+        return existing;
+    if (Array.isArray(value)) {
+        const out = [];
+        seen.set(value, out);
+        for (const item of value)
+            out.push(deepClone(item, seen));
+        return out;
+    }
+    const out = {};
+    seen.set(value, out);
+    for (const [key, child] of Object.entries(value)) {
+        out[key] = deepClone(child, seen);
+    }
+    return out;
+}
+/**
+ * Freeze a value transitively, guarding against cycles.
+ * @param value - the value to freeze.
+ * @param seen - objects already visited, so a cyclic schema cannot recurse forever.
+ */
+function deepFreeze(value, seen) {
+    if (value === null || typeof value !== 'object')
+        return;
+    if (seen.has(value))
+        return;
+    seen.add(value);
+    for (const child of Object.values(value))
+        deepFreeze(child, seen);
+    Object.freeze(value);
+}
+/**
+ * Capture the frozen host-approved tool schema snapshot (NDL-02).
+ *
+ * The capture is a DEEP COPY: mutating the registry afterwards — registering a tool,
+ * withdrawing one, changing a description — cannot change the snapshot, and mutating the
+ * snapshot is refused by the runtime because every node is frozen. Excluded names are
+ * skipped rather than captured-then-filtered, so a management tool's schema never enters
+ * the snapshot at all.
+ *
+ * An empty description is replaced with a stated placeholder rather than captured empty:
+ * the planner-side input contract requires a non-empty description, and a capture that
+ * guaranteed a later refusal would freeze a call failure into the snapshot.
+ * @param schemas - the registry view at capture time.
+ * @param options - the generation, and optionally the excluded names (defaults to
+ *   {@link PLANNING_EXCLUDED_TOOLS}).
+ * @returns the frozen snapshot.
+ */
+export function captureToolSchemaSnapshot(schemas, options) {
+    const excluded = options.excluded ?? PLANNING_EXCLUDED_TOOLS;
+    const tools = new Map();
+    for (const schema of schemas) {
+        if (excluded.includes(schema.name))
+            continue;
+        if (typeof schema.parameters !== 'object' || schema.parameters === null || Array.isArray(schema.parameters)) {
+            // A tool whose parameters cannot be described as JSON Schema cannot be planned
+            // against; capturing it would hand the planner an entry it cannot use.
+            continue;
+        }
+        const description = typeof schema.description === 'string' && schema.description.trim().length > 0
+            ? schema.description
+            : 'No host description is declared for this tool.';
+        const entry = {
+            name: schema.name,
+            description,
+            // deepClone, then freeze: the snapshot must share NO structure with the
+            // registry's live objects, or a later registry edit would reach a caller.
+            parameters: deepClone(schema.parameters, new Map()),
+        };
+        deepFreeze(entry.parameters, new Set());
+        deepFreeze(entry, new Set());
+        tools.set(schema.name, entry);
+    }
+    // The OUTER record is frozen too: "the snapshot is frozen" must include the
+    // container a caller holds, not only the entries inside it (the map is frozen
+    // below via the same walk, and the record itself last).
+    const snapshot = { generation: options.generation, tools };
+    deepFreeze(snapshot, new Set());
+    return snapshot;
+}
+/**
+ * Intersect the requested names with the live registry and the frozen snapshot (NDL-02).
+ *
+ * All-or-nothing, mirroring the CODE-03 bindings gate: if ANY requested name is
+ * unattainable the whole call is refused with every rejection named, because handing the
+ * caller a smaller offer set than it asked for would produce a plan for a different
+ * request than the one it stated.
+ * @param snapshot - the frozen snapshot, the ONLY source of schemas.
+ * @param requested - the names the caller asked to plan over.
+ * @param liveLeaf - the leaf tool names currently registered, exclusions already applied.
+ * @param excluded - the names refused by policy regardless of registration. Defaults to
+ *   {@link PLANNING_EXCLUDED_TOOLS}.
+ * @returns the offered entries, or every rejection.
+ */
+export function offerToolsFromSnapshot(snapshot, requested, liveLeaf, excluded = PLANNING_EXCLUDED_TOOLS) {
+    const rejections = [];
+    const offered = [];
+    const seen = new Set();
+    for (const name of requested) {
+        if (seen.has(name)) {
+            rejections.push({
+                name,
+                reason: 'duplicate',
+                remedy: 'Request each tool once; a repeated name makes the offered set ambiguous.',
+            });
+            continue;
+        }
+        seen.add(name);
+        if (excluded.includes(name)) {
+            rejections.push({
+                name,
+                reason: 'excluded',
+                remedy: `"${name}" is not a leaf tool a plan may target: management and composition bindings are excluded (CODE-07, NDL-02).`,
+            });
+            continue;
+        }
+        if (!liveLeaf.has(name)) {
+            rejections.push({
+                name,
+                reason: 'unknown',
+                remedy: 'The tool is not currently registered; its owning extension may be deactivated, or the name may never have existed.',
+            });
+            continue;
+        }
+        const entry = snapshot.tools.get(name);
+        if (entry === undefined) {
+            rejections.push({
+                name,
+                reason: 'not-in-snapshot',
+                remedy: 'The tool is registered but was added after the frozen snapshot was captured, so no authorized schema exists for it.',
+            });
+            continue;
+        }
+        offered.push(entry);
+    }
+    if (rejections.length > 0)
+        return { ok: false, rejections };
+    return { ok: true, offered };
+}
+/**
+ * Describe a refused request for a caller (NDL-02).
+ * @param rejections - the refusals.
+ * @returns a readable summary naming every rejection and why.
+ */
+export function describePlanningRejections(rejections) {
+    const lines = rejections.map(entry => `  ${entry.name}: ${entry.reason} — ${entry.remedy}`);
+    return `tools_plan cannot offer the requested tools:\n${lines.join('\n')}`;
+}
+/**
+ * Raised when a provider returns a proposal record that is not proposal-shaped.
+ *
+ * The provider's declared output contract types every field and closes the record, so a
+ * malformed entry is a PROVIDER DEFECT — and it is surfaced as one rather than silently
+ * coerced. Coercing a non-object `arguments` into `{}` would present a record the
+ * provider never produced as if the host had validated it, and dropping undeclared
+ * fields would hide a contract violation the output validator should refuse.
+ */
+export class ProviderDefectError extends Error {
+    name = 'ProviderDefectError';
+}
+/** The keys the declared proposal contract admits. */
+const PROPOSAL_FIELDS = new Set(['name', 'arguments', 'offered', 'valid', 'issues']);
+/**
+ * Normalize one proposal record from the provider's payload, STRICTLY.
+ *
+ * Structural violations throw {@link ProviderDefectError}: a non-object record, a missing
+ * or non-string name, non-object arguments, or undeclared fields. The typed fields the
+ * declared output schema constrains (`offered`, `valid`, `issues`) are read tolerantly —
+ * their types are enforced by the output validator that runs after the re-check.
+ * @param raw - the record.
+ * @returns the normalized entry.
+ * @throws ProviderDefectError when the record is not proposal-shaped.
+ */
+function normalizeEntry(raw) {
+    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
+        throw new ProviderDefectError('a provider returned a proposal record that is not an object');
+    }
+    const record = raw;
+    const extra = Object.keys(record).filter(key => !PROPOSAL_FIELDS.has(key));
+    if (extra.length > 0) {
+        throw new ProviderDefectError(`a provider returned a proposal record with undeclared field(s) ${extra.map(key => JSON.stringify(key)).join(', ')}`);
+    }
+    if (typeof record.name !== 'string') {
+        throw new ProviderDefectError('a provider returned a proposal record whose name is not a string');
+    }
+    const rawArguments = record.arguments;
+    if (typeof rawArguments !== 'object' || rawArguments === null || Array.isArray(rawArguments)) {
+        throw new ProviderDefectError(`a provider returned a proposal record whose arguments are not an object (${JSON.stringify(rawArguments)})`);
+    }
+    const issues = Array.isArray(record.issues)
+        ? record.issues.filter((issue) => typeof issue === 'string').slice(0, 32)
+        : [];
+    return {
+        name: record.name,
+        arguments: rawArguments,
+        offered: record.offered === true,
+        valid: record.valid === true,
+        issues,
+    };
+}
+/**
+ * Re-check the provider's proposals against the frozen snapshot, the per-call offered set
+ * AND the live authorization state (NDL-02, NDL-03).
+ *
+ * The provider's own validation is not trusted here: it validated against the list the
+ * HOST built, but the host still re-checks every proposal before it reaches a caller,
+ * because a proposal is the one thing a caller will treat as authorized. Four checks:
+ *
+ * - the name must be IN the frozen snapshot (the engine cannot invent a plannable tool);
+ * - the arguments must satisfy the SNAPSHOT's schema, compiled fresh per snapshot entry;
+ * - the name must be in the OFFERED set for THIS call — a provider proposing a tool the
+ *   caller never requested must not pass it through as valid, even when it is
+ *   snapshotted, schema-valid and still registered;
+ * - the tool must STILL BE AUTHORIZED right now (NDL-03): a tool deactivated, withdrawn
+ *   or quarantined after capture fails the fresh policy check, and the proposal is
+ *   refused rather than returned as if it were executable.
+ *
+ * A proposal failing any check is MOVED to `rejected` with the issues appended, and one
+ * bounded warning per moved proposal is returned for the receipt and the meta envelope.
+ * A proposal record that is not proposal-shaped throws {@link ProviderDefectError}: the
+ * defect belongs to the provider, and silently repairing it would hide the violation.
+ * @param snapshot - the frozen snapshot.
+ * @param payload - the provider's result.
+ * @param offeredNames - the names the HOST offered for this call.
+ * @param isCurrentlyAuthorized - the live authorization predicate, read at re-check time;
+ *   `true` admits, a string is the refusal reason.
+ * @returns the amended payload and the warnings.
+ */
+export function recheckProposals(snapshot, payload, offeredNames, isCurrentlyAuthorized) {
+    const warnings = [];
+    const compiled = new Map();
+    /** Compile a snapshot entry's schema once; an uncompilable schema is an issue, not a crash. */
+    const validatorFor = (entry) => {
+        const cached = compiled.get(entry.name);
+        if (cached !== undefined)
+            return cached;
+        let validate;
+        try {
+            validate = PROPOSAL_AJV.compile(entry.parameters);
+        }
+        catch {
+            // Kept uncompiled: every proposal for this entry then carries the compile failure
+            // as an issue instead of the host throwing mid-call.
+            return undefined;
+        }
+        const validator = value => (validate(value) ? [] : [...(validate.errors ?? [])]
+            .map(error => `${error.instancePath === '' ? '(root)' : error.instancePath} ${error.message ?? 'is invalid'}`));
+        compiled.set(entry.name, validator);
+        return validator;
+    };
+    const rawProposals = Array.isArray(payload.proposals) ? payload.proposals : [];
+    const rawRejected = Array.isArray(payload.rejected) ? payload.rejected : [];
+    const kept = [];
+    const rejected = [...rawRejected];
+    for (const raw of rawProposals) {
+        const entry = normalizeEntry(raw);
+        const hostIssues = [];
+        let offered = entry.offered;
+        const snapshotEntry = snapshot.tools.get(entry.name);
+        if (snapshotEntry === undefined) {
+            // A proposal outside the snapshot was never offered by the HOST, whatever the
+            // provider believed: the host's offer set is the snapshot by construction.
+            offered = false;
+            hostIssues.push(`the tool ${JSON.stringify(entry.name)} is not in the frozen host-approved snapshot`);
+        }
+        else {
+            const validate = validatorFor(snapshotEntry);
+            if (validate === undefined) {
+                hostIssues.push(`the frozen schema for ${JSON.stringify(entry.name)} does not compile, so no arguments can be validated`);
+            }
+            else {
+                hostIssues.push(...validate(entry.arguments));
+            }
+            if (hostIssues.length === 0 && !offeredNames.has(entry.name)) {
+                // F6: the OFFERED set is per-call. A snapshotted, schema-valid, still-registered
+                // proposal for a tool the caller never requested is still not a valid plan step:
+                // the provider had no business proposing it this turn.
+                offered = false;
+                hostIssues.push(`the tool ${JSON.stringify(entry.name)} was not offered for this turn`);
+            }
+            if (hostIssues.length === 0) {
+                const authorization = isCurrentlyAuthorized(entry.name);
+                if (authorization !== true) {
+                    // NDL-03: fresh policy checks at execution time. The tool was authorized when the
+                    // snapshot froze, but it is not callable NOW — withdrawn, deactivated or
+                    // quarantined — so returning the proposal would present a tool that would fail
+                    // admission as a valid plan step.
+                    hostIssues.push(`the tool ${JSON.stringify(entry.name)} is no longer authorized: ${authorization}`);
+                }
+            }
+        }
+        if (hostIssues.length === 0) {
+            kept.push(entry);
+            continue;
+        }
+        // The bounded report shape: the provider's issues first, then the host's, capped at
+        // the shipped schema's own 32-item bound rather than grown without limit.
+        rejected.push({
+            name: entry.name,
+            arguments: entry.arguments,
+            offered,
+            valid: false,
+            issues: [...entry.issues, ...hostIssues].slice(0, 32),
+        });
+        warnings.push(`the host refused the ${entry.name} proposal: ${hostIssues[0] ?? 'invalid'}`);
+    }
+    return {
+        payload: { ...payload, proposals: kept, rejected },
+        warnings,
+    };
+}
+/**
+ * The input the HOST advertises and validates for `tools_plan` (NDL-02).
+ *
+ * The caller names tools as STRINGS — a requested eligible subset, never a grant and
+ * never full declarations. The extension's own shipped input schema (full tool objects)
+ * remains its provider contract; the host is the broker that turns requested names into
+ * snapshot entries, so a caller never supplies the schemas the planner reasons over.
+ * Bounds mirror the shipped extension input, so the advertised surface and the transport
+ * surface cannot admit different requests.
+ */
+export const PLANNING_TOOL_INPUT_SCHEMA = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['request', 'tools'],
+    properties: {
+        request: {
+            type: 'string',
+            minLength: 1,
+            maxLength: 32_768,
+            description: 'The user request the plan is derived from, verbatim.',
+        },
+        tools: {
+            type: 'array',
+            minItems: 1,
+            maxItems: 64,
+            description: 'The tool names to plan over. A requested eligible subset, never a grant; unknown or excluded names refuse the call.',
+            items: { type: 'string', minLength: 1 },
+        },
+        system: {
+            type: 'string',
+            maxLength: 4_096,
+            description: 'Session facts the model should assume: the date, the locale, the device.',
+        },
+        max_new_tokens: {
+            type: 'integer',
+            minimum: 16,
+            maximum: 4_096,
+            description: 'Response-token budget for the planner.',
+        },
+    },
+};
+/**
+ * Whether a declared input schema has the planning shape (a `tools` array property).
+ *
+ * The NAME alone is not enough to treat a contribution as the planning contract: a
+ * package that named a tool `tools_plan` without the planning input would otherwise be
+ * served through the planning pipeline and fail in ways nobody could see. The name plus
+ * the shape is the contract; the host refuses the name without the shape.
+ * @param schema - the declared input schema.
+ * @returns whether the schema declares an array-valued `tools` property.
+ */
+export function hasPlanningInputShape(schema) {
+    if (schema === undefined)
+        return false;
+    const properties = schema.properties;
+    if (typeof properties !== 'object' || properties === null || Array.isArray(properties))
+        return false;
+    const tools = properties.tools;
+    if (typeof tools !== 'object' || tools === null || Array.isArray(tools))
+        return false;
+    const type = tools.type;
+    return type === 'array' || (Array.isArray(type) && type.includes('array'));
+}
+//# sourceMappingURL=planning.js.map

package/lib/prepared-assets.d.ts

@@ -0,0 +1,178 @@
+/**
+ * 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-model-as-tool/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[];
+/** The host-side prepared-assets registry (session-scoped). */
+export interface PreparedAssetRegistry {
+    /** 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[];
+    /**
+     * 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>;
+}
+/** 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;
+}
+/**
+ * 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;
+    /** 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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"}