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

package/node_modules/@try-works/tool-mode-extension-sdk/lib/install/staged.js

@@ -0,0 +1,235 @@
+/**
+ * Staged installation (EXT-07, EXT-08).
+ *
+ * The ordering is the security property. A package is fetched into quarantine,
+ * verified, inspected as DATA, validated, and only then promoted into the store —
+ * and promotion is not activation. Nothing in this module imports extension code,
+ * runs inference, warms a model, or publishes a tool (EXT-07).
+ *
+ * The fetch and extract steps are INJECTED rather than implemented here, for two
+ * reasons: the SDK must stay free of a network stack and an archive library, and
+ * a test must be able to drive every rejection path without a real download or a
+ * real filesystem. The host supplies the real implementations.
+ *
+ * @module @try-works/tool-mode-extension-sdk/install/staged
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { linkRuntimeSdk, RUNTIME_SDK_NAME } from "./runtime-link.js";
+import { join, resolve, sep } from 'node:path';
+import { ManagementError } from "./../errors.js";
+import { discoverExtension } from "./../discovery.js";
+import { digestInstalledContent, ExtensionStore } from "./store.js";
+import { installDependencyGraph } from "./dependencies.js";
+import { DEFAULT_ARCHIVE_LIMITS, validateArchiveEntries, verifyIntegrity, } from "./archive.js";
+/** Conservative install limits. */
+export const DEFAULT_INSTALL_LIMITS = {
+    maxArchiveBytes: 256 * 1024 * 1024,
+    fetchTimeoutMs: 120_000,
+    archive: DEFAULT_ARCHIVE_LIMITS,
+};
+/**
+ * Install an extension into an operator-owned store, staged (EXT-08).
+ *
+ * Steps, in order: fetch into quarantine → verify integrity → list entries →
+ * validate the entry list → extract → discover → validate compatibility →
+ * promote atomically → record the installation. A failure at any step removes the
+ * quarantine, so a partial install never becomes visible.
+ *
+ * The store is RECORDED rather than merely written to: an installation that is not
+ * in the lock document cannot be activated later, because nothing would know what
+ * bytes were approved.
+ *
+ * @param options - the source, the store, the injected archive source, and limits.
+ * @returns the installed (but inactive) extension.
+ * @throws ManagementError for every rejection path.
+ */
+export async function stagedInstall(options) {
+    const limits = options.limits ?? DEFAULT_INSTALL_LIMITS;
+    const storeDir = resolve(options.storeDir);
+    const staging = join(storeDir, '.staging');
+    // A unique per-attempt directory, so two concurrent installs cannot collide and
+    // a crashed attempt leaves evidence rather than a half-written package.
+    const attempt = join(staging, `attempt-${process.pid}-${Date.now().toString(36)}`);
+    mkdirSync(attempt, { recursive: true });
+    /** Set when the runtime link could not be made, reported rather than thrown. */
+    let runtimeLinkDiagnostic;
+    try {
+        const bytes = await options.archive.fetch(options.source, {
+            maxBytes: limits.maxArchiveBytes,
+            timeoutMs: limits.fetchTimeoutMs,
+        });
+        if (bytes.byteLength > limits.maxArchiveBytes) {
+            throw new ManagementError('INVALID_EXTENSION', 'install', `the fetched archive is ${bytes.byteLength} bytes, over the ${limits.maxArchiveBytes} limit`, 'Ask the publisher to reduce the package, or raise the operator limit deliberately.');
+        }
+        // Integrity first: if the bytes are not the approved ones, nothing downstream
+        // is worth doing.
+        const archiveDigest = verifyIntegrity(bytes, options.expectedSha512);
+        // Entry validation runs on the LIST, before extraction. A traversal entry
+        // rejected here never reaches a path join.
+        const entries = options.archive.list(bytes);
+        validateArchiveEntries(entries, limits.archive);
+        const extracted = join(attempt, 'package');
+        mkdirSync(extracted, { recursive: true });
+        options.archive.extract(bytes, extracted, '');
+        // Discovery reads data and imports nothing; a manifest referencing a file the
+        // package does not ship is refused before anything is promoted.
+        const discovery = discoverExtension(extracted);
+        // EXT-09: the extension's runtime dependencies are resolved, verified and
+        // materialized into the extension's OWN directory before promotion. A
+        // package that declares dependencies without a provided graph installer is
+        // REFUSED rather than installed as a guaranteed-broken extension.
+        let lockedDependencies = [];
+        let declaredDependenciesCount = 0;
+        try {
+            const packageJson = JSON.parse(readFileSync(join(extracted, 'package.json'), 'utf8'));
+            declaredDependenciesCount = Object.keys(packageJson.dependencies ?? {}).length;
+        }
+        catch {
+            // The package.json was already read by discovery; this cannot fail.
+        }
+        if (declaredDependenciesCount > 0) {
+            if (options.dependencies === undefined) {
+                throw new ManagementError('DEPENDENCY_UNSATISFIED', 'install', `${discovery.packageName} declares ${declaredDependenciesCount} runtime dependenc${declaredDependenciesCount === 1 ? 'y' : 'ies'} but no dependency-graph installer was provided; the extension would be installed broken`, 'Provide the operator-configured registry resolver, or publish the extension with every runtime dependency bundled.');
+            }
+            lockedDependencies = await installDependencyGraph(extracted, options.dependencies);
+        }
+        // EXT-08: the operator approval PREVIEW runs BEFORE materialization — the
+        // caller sees the permissions/licenses/platform/download implications and
+        // may refuse (throw) to abort the install while nothing is promoted.
+        if (options.preview !== undefined) {
+            const manifest = discovery.manifest;
+            await options.preview({
+                extensionId: discovery.packageName,
+                version: discovery.packageVersion,
+                permissions: manifest.permissions,
+                models: manifest.models.map(model => ({
+                    id: model.id,
+                    assetSet: model.assetSet,
+                    platforms: model.platforms.map(platform => `${platform.os}-${platform.arch}${platform.accelerator === undefined ? '' : `-${platform.accelerator}`}`),
+                })),
+                licenses: (manifest.licenses ?? []).map(layer => `${layer.layer}: ${layer.name}`),
+                downloadImplications: manifest.models.length === 0
+                    ? 'no model assets declared; nothing is downloaded at install'
+                    : `${manifest.models.length} model asset set(s) declared; downloads require the separate preparation consent, never the install`,
+                requiresApproval: manifest.permissions.nativeCode
+                    || manifest.permissions.networkOrigins.length > 0
+                    || manifest.permissions.storage !== 'none'
+                    || manifest.models.length > 0,
+            });
+        }
+        // Promote by rename, which is atomic within a store. The destination is keyed
+        // by identity AND version, so an update installs side by side rather than
+        // mutating a live directory (EXT-30).
+        const destination = installPathFor(storeDir, discovery.packageName, discovery.packageVersion);
+        if (existsSync(destination)) {
+            throw new ManagementError('UPGRADE_FAILED', 'install', `${discovery.packageName}@${discovery.packageVersion} is already installed`, 'Install a different version, or uninstall the existing one first.');
+        }
+        mkdirSync(join(destination, '..'), { recursive: true });
+        renameSync(extracted, destination);
+        /**
+         * Make the RUNTIME SDK resolvable from inside the installed package.
+         *
+         * Without this the package lands in a directory with no `node_modules`, so an extension
+         * that declares the SDK — which the protocol requires it to depend on — dies on its
+         * first import with ERR_MODULE_NOT_FOUND. It is discoverable and activatable and cannot
+         * RUN, which is the worst of the three states because nothing reports it as broken.
+         *
+         * A failure here is RECORDED rather than thrown: a package that imports nothing (a
+         * declarative or tool-only extension) runs fine without the link, and failing the
+         * install would break working packages to fix a problem they do not have.
+         */
+        runtimeLinkDiagnostic = linkRuntimeSdk(destination);
+        /**
+         * A SHADOWED RUNTIME FAILS THE INSTALL.
+         *
+         * If the package shipped its own copy of the host SDK, the extension would execute
+         * against THAT copy while the operator was told the link was merely already present.
+         * Installing it is worse than refusing, because the receipt would then describe a
+         * containment the installation does not have. This is the one link outcome that is
+         * fatal rather than reported.
+         */
+        if (runtimeLinkDiagnostic.reason === 'sdk-shadowed') {
+            rmSync(destination, { recursive: true, force: true });
+            throw new ManagementError('INVALID_EXTENSION', 'install', runtimeLinkDiagnostic.detail ?? 'the package ships its own copy of the host runtime SDK', 'Remove node_modules/' + RUNTIME_SDK_NAME
+                + ' from the package; an extension must run against the host runtime.');
+        }
+        writeFileSync(join(destination, '.tool-mode-install.json'), `${JSON.stringify({
+            extensionId: discovery.packageName,
+            version: discovery.packageVersion,
+            archiveDigest,
+            ...runtimeLinkDiagnostic === undefined ? {} : { runtimeLink: runtimeLinkDiagnostic },
+            source: { kind: options.source.kind, requested: options.source.requested },
+            ...lockedDependencies.length === 0 ? {} : { dependencies: lockedDependencies },
+            ...options.provenance === undefined ? {} : { provenance: options.provenance },
+            installedAt: new Date().toISOString(),
+        }, null, 2)}\n`);
+        // Recorded AFTER the bytes are in place: a lock entry naming a directory that
+        // does not exist would be worse than no entry, because verification would then
+        // report a missing installation as a changed one.
+        if (options.record !== false) {
+            const store = new ExtensionStore(storeDir);
+            store.recordInstall({
+                extensionId: discovery.packageName,
+                version: discovery.packageVersion,
+                installPath: destination,
+                archiveDigest,
+                ...runtimeLinkDiagnostic === undefined ? {} : { runtimeLink: runtimeLinkDiagnostic },
+                // Digest the content as installed, so a later edit is detectable.
+                contentDigest: digestInstalledContent(destination),
+                source: { kind: options.source.kind, requested: options.source.requested },
+                ...lockedDependencies.length === 0 ? {} : { dependencies: lockedDependencies },
+                ...options.provenance === undefined ? {} : { provenance: options.provenance },
+                installedAt: new Date().toISOString(),
+            });
+        }
+        return {
+            extensionId: discovery.packageName,
+            version: discovery.packageVersion,
+            installPath: destination,
+            activation: 'inactive',
+            discovery,
+            archiveDigest,
+            ...runtimeLinkDiagnostic === undefined ? {} : { runtimeLink: runtimeLinkDiagnostic },
+        };
+    }
+    finally {
+        // Quarantine is removed on EVERY path, success included: the promoted copy is
+        // the installation, and leaving a second copy behind would let the two drift.
+        rmSync(attempt, { recursive: true, force: true });
+    }
+}
+/**
+ * The immutable installation directory for one extension version (EXT-33).
+ *
+ * The identity is VALIDATED rather than merely escaped. Escaping would turn
+ * `../../etc` into a harmless-looking directory name and silently install
+ * something under a package name that no registry would accept; refusing says
+ * what is actually wrong.
+ * @param storeDir - the operator's store root.
+ * @param extensionId - the validated extension identity.
+ * @param version - the validated version.
+ * @returns the absolute installation path.
+ * @throws ManagementError when the identity or version is not a legal one.
+ */
+export function installPathFor(storeDir, extensionId, version) {
+    // A package name is lower-case, may be scoped, and uses a restricted character
+    // set. EXT-14 already requires the manifest id to equal the package name, so an
+    // identity outside this grammar did not come from a real package.
+    const SEGMENT = '[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?';
+    const NAME = new RegExp(`^(?:@${SEGMENT}/)?${SEGMENT}$`);
+    if (!NAME.test(extensionId)) {
+        throw new ManagementError('INVALID_EXTENSION', 'install', `the extension identity ${JSON.stringify(extensionId)} is not a legal package name`, 'Use a normal npm package name; the manifest id must equal it exactly.');
+    }
+    if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(version)) {
+        throw new ManagementError('INVALID_EXTENSION', 'install', `the version ${JSON.stringify(version)} is not a semantic version`, 'Publish a semantic version.');
+    }
+    // The separator is the one character a legal name cannot contain, so a
+    // validated name needs no further escaping to stay inside the store.
+    const path = join(resolve(storeDir), 'extensions', extensionId, version);
+    const root = resolve(storeDir);
+    if (!path.startsWith(root + sep)) {
+        throw new ManagementError('INVALID_EXTENSION', 'install', 'the extension identity would escape the extension store', 'Use a normal package name.');
+    }
+    return path;
+}
+//# sourceMappingURL=staged.js.map

package/node_modules/@try-works/tool-mode-extension-sdk/lib/install/store.d.ts

@@ -0,0 +1,367 @@
+/**
+ * The operator-owned extension store (EXT-33).
+ *
+ * Three properties this module exists to guarantee:
+ *
+ * 1. **Identity survives restart.** Every installation is recorded in
+ *    `extensions.lock.json` with its resolved source and a CONTENT digest, so the
+ *    host can tell on a later boot whether the bytes it is about to activate are
+ *    still the bytes it installed.
+ * 2. **Corruption fails closed.** A state file that cannot be read yields NO
+ *    active extensions and a diagnostic. The tempting alternative — falling back
+ *    to "everything installed is active" — is precisely the failure EXT-33 names,
+ *    because a corrupted file would silently enable every package on the machine.
+ * 3. **A write that did not land is never reported as landed.** Every write goes
+ *    through a temporary file and a rename, and a failure throws rather than
+ *    leaving the caller believing a preference was stored.
+ *
+ * @module @try-works/tool-mode-extension-sdk/install/store
+ */
+import type { ExtensionState } from './../state.ts';
+import { STATE_VERSION, type MigratedAssetRecord, type MigrationReport } from './migration.ts';
+import type { LockedDependency } from './dependencies.ts';
+/** The lock document name, as EXT-33 specifies. */
+export declare const LOCK_FILE = "extensions.lock.json";
+/** One installed extension, as recorded at install time. */
+export interface InstalledRecord {
+    /** Extension identity, which equals the package name. */
+    readonly extensionId: string;
+    /** Installed version. */
+    readonly version: string;
+    /** Absolute installation directory. */
+    readonly installPath: string;
+    /** SHA-512 of the archive the package was installed from (EXT-12). */
+    readonly archiveDigest: string;
+    /**
+     * Digest over the installed files. Re-checked before activation so a package
+     * edited on disk after installation is detected rather than trusted.
+     */
+    readonly contentDigest: string;
+    /** Where the archive came from, recorded verbatim. */
+    readonly source: {
+        readonly kind: string;
+        readonly requested: string;
+    };
+    /** When it was installed, ISO 8601. */
+    readonly installedAt: string;
+    /**
+     * The installer-owned dependency graph (EXT-09, EXT-12): every runtime
+     * dependency at its EXACT resolved version with its verified integrity.
+     * Absent when the package declares no runtime dependencies.
+     */
+    readonly dependencies?: readonly LockedDependency[];
+    /**
+     * Provenance fields recorded AS DATA, NEVER AS TRUST (EXT-12): registry
+     * integrity/provenance flags travel with the record for audit; verification
+     * is always against the operator-supplied digest.
+     */
+    readonly provenance?: {
+        readonly registryIntegrity?: string;
+        readonly provenance?: boolean;
+        readonly attestations?: readonly string[];
+        readonly signatures?: readonly string[];
+    };
+}
+/** The lock document. */
+export interface StoreLock {
+    readonly lockVersion: 1;
+    readonly extensions: readonly InstalledRecord[];
+}
+/**
+ * A profile's persisted activation state (EXT-25, dimensions 2-6).
+ *
+ * The two version keys are BASE-09's: `stateVersion` is the migration-table era
+ * (a document with a higher number was written by a newer SDK and is refused,
+ * never rewritten), and `schemaVersion` identifies the schema dialect. Documents
+ * written before `schemaVersion` existed (stateVersion 1, no schemaVersion key)
+ * still read: the key was added without a data change, so there is no migration
+ * step between them.
+ */
+export interface ProfileStateFile {
+    readonly stateVersion: typeof STATE_VERSION;
+    readonly schemaVersion: string;
+    readonly profile: string;
+    readonly extensions: readonly ExtensionState[];
+    /** Legacy prepared-asset mappings recorded by the BASE-09 migration. */
+    readonly migratedAssets?: readonly MigratedAssetRecord[];
+    /** EXT-30: the active version per extension, the update flow's pointer. */
+    readonly activeVersions?: Readonly<Record<string, string>>;
+    /** EXT-30: the previous active version per extension, the rollback target. */
+    readonly previousVersions?: Readonly<Record<string, string>>;
+}
+/**
+ * One EXT-30 approval decision for a staged update.
+ *
+ * Retained for the store's lifetime (audit trail, no expiry) and write-once per
+ * staged version: a decision is a human act, and a later one never silently
+ * overwrites it.
+ */
+export interface UpdateApprovalRecord {
+    readonly extensionId: string;
+    readonly version: string;
+    readonly approved: boolean;
+    readonly deniedReason?: string;
+    readonly decidedAt: string;
+}
+/** The outcome of reading state, which never throws on corruption. */
+export interface StateReadResult<T> {
+    readonly value: T;
+    /** Set when the file existed but could not be trusted. */
+    readonly diagnostic?: string;
+    /** True when the file existed but could not be read or parsed. */
+    readonly corrupt: boolean;
+}
+/**
+ * Digest the files inside an installed package.
+ *
+ * Identity is `relative path` plus size plus a per-file digest, over a sorted
+ * walk, so a renamed file, an edited file, an added file and a removed file all
+ * change the result. The install receipt is excluded: it is store metadata, not
+ * package content, and including it would make the digest depend on itself.
+ * @param directory - the installed package directory.
+ * @returns the content digest, lowercase hex.
+ */
+export declare function digestInstalledContent(directory: string): string;
+/**
+ * Whether a process with this pid exists. `process.kill(pid, 0)` is the probe.
+ *
+ * Exported because surface ownership is recorded as a PID: telling a GONE owner (a
+ * crashed or restarted host, whose in-memory handles died with it) from a LIVE one
+ * (another host still serving) is the same question the store lock asks.
+ * @param pid - the process id to probe.
+ * @returns whether the process exists.
+ */
+export declare function isProcessAlive(pid: number): boolean;
+/** The operator-owned extension store. */
+export declare class ExtensionStore {
+    /** Absolute path of the store root. */
+    readonly rootDir: string;
+    constructor(rootDir: string);
+    /** Path of the lock document. */
+    get lockPath(): string;
+    /** Path of one profile's state file. */
+    profileStatePath(profile: string): string;
+    /**
+     * Take exclusive ownership of the store for offline edits (EXT-31).
+     *
+     * EXT-31 requires offline edits to hold exclusive store ownership, because an
+     * offline writer and a running host editing the same store would each be working
+     * from a state the other cannot see. The lock records the owning process so a
+     * stale lock from a crashed run can be reported as stale rather than blocking
+     * forever.
+     * @returns a release function.
+     * @throws ManagementError with `EXTENSION_IN_USE` when another process holds it.
+     */
+    acquireExclusive(): () => void;
+    /**
+     * Run a state-mutating operation under the store lock (EXT-31).
+     *
+     * The HOST LIFECYCLE takes this around every state write, and the offline CLI
+     * takes it around its edits; each side refuses while the other's process is
+     * alive. Reentrancy is keyed by the RESOLVED STORE ROOT, not the instance:
+     * the CLI creates fresh ExtensionStore objects around one directory, so
+     * per-instance counting would let an inner acquisition overwrite the outer's
+     * lock record (the round-49 review's hole 3). The depth is recorded only
+     * AFTER the file lock is taken, so a refusal throws WITHOUT poisoning the
+     * count (hole 1), and the lock file is removed only when the depth returns to
+     * zero (hole 2: a concurrent section still holds it).
+     * @param work - the mutating work.
+     * @returns the work's result.
+     */
+    exclusive<T>(work: () => Promise<T>): Promise<T>;
+    /**
+     * Read the lock document.
+     *
+     * A corrupt lock fails closed with a diagnostic and NO records, rather than
+     * reporting the store as empty-without-explanation or trusting a partial read.
+     * @returns the lock and a diagnostic when it could not be trusted.
+     */
+    readLock(): StateReadResult<StoreLock>;
+    /** List installed extensions. */
+    listInstalled(): StateReadResult<readonly InstalledRecord[]>;
+    /**
+     * Record an installation.
+     *
+     * Throws when the write fails, so a caller never treats a lost record as a
+     * completed install.
+     * @param record - the installation to record.
+     * @throws ManagementError when the same identity and version is already recorded.
+     */
+    recordInstall(record: InstalledRecord): void;
+    /**
+     * Remove an installation record.
+     *
+     * Removing a record does NOT delete the installed bytes: deletion is a separate,
+     * operator-driven step with its own failure modes (EXT-29), and conflating the
+     * two would make a failed deletion look like a failed uninstall.
+     * @param extensionId - the extension to forget.
+     */
+    removeRecord(extensionId: string): void;
+    /**
+     * Check whether an installation still matches what was recorded (EXT-33).
+     *
+     * Run before activation: a package edited on disk after installation is a
+     * different package, and activating it would execute bytes nobody approved.
+     * @param record - the recorded installation.
+     * @returns whether the content is unchanged, plus the current digest.
+     */
+    verifyUnchanged(record: InstalledRecord): {
+        unchanged: boolean;
+        contentDigest?: string;
+        diagnostic?: string;
+    };
+    /**
+     * Read one profile's activation state.
+     *
+     * A corrupt file yields NO states and a diagnostic. Returning the installed set
+     * instead would be the failure EXT-33 names: corruption would enable everything.
+     *
+     * Versioning (BASE-09): a document with a HIGHER `stateVersion` was written by
+     * a newer SDK and is refused, not read half-understood. A document with NO
+     * `stateVersion` is either a legacy model-id era document (enabled/disabled
+     * arrays, migrated via {@link ExtensionStore.migrateLegacyProfileState}) or
+     * something this store never wrote — both fail closed with a diagnostic.
+     * @param profile - the profile name.
+     * @returns the states and any diagnostic.
+     */
+    readProfileState(profile: string): StateReadResult<readonly ExtensionState[]>;
+    /**
+     * Persist one profile's activation state.
+     *
+     * The document carries both BASE-09 version keys: `stateVersion` (the
+     * migration era) and `schemaVersion` (the schema dialect), so a later reader
+     * can tell an up-to-date document from a legacy one without guessing.
+     *
+     * MIGRATED-ASSET DURABILITY (BASE-09): when the caller does not pass
+     * `migratedAssets`, the mappings already recorded in the file are PRESERVED
+     * verbatim instead of dropped. Every lifecycle write and CLI edit calls this
+     * method without the parameter, so requiring every caller to carry the
+     * mappings through would mean the first forgetful writer silently loses the
+     * migration's prepared-asset record; preserving by default makes the store
+     * itself the keeper of them. Pass an empty array to clear them deliberately.
+     * @param profile - the profile name.
+     * @param extensions - the complete state set for that profile.
+     * @param migratedAssets - durable legacy prepared-asset mappings. Omitted:
+     *   preserve the existing ones. `[]`: clear them.
+     * @throws ManagementError when the write fails.
+     */
+    writeProfileState(profile: string, extensions: readonly ExtensionState[], migratedAssets?: readonly MigratedAssetRecord[], activeVersions?: Readonly<Record<string, string>>, previousVersions?: Readonly<Record<string, string>>): void;
+    /**
+     * Read the EXT-30 active-version pointers from one profile's state document.
+     *
+     * The maps are OPTIONAL document keys written only by the update flow: an
+     * older document simply has no pointers, and a corrupt map fails closed
+     * rather than being half-read. The read is separate from
+     * {@link ExtensionStore.readProfileState} so the existing per-extension state
+     * contract is untouched.
+     * @param profile - the profile name.
+     * @returns the pointer maps and any diagnostic.
+     */
+    readProfilePointers(profile: string): StateReadResult<{
+        readonly activeVersions: Readonly<Record<string, string>>;
+        readonly previousVersions: Readonly<Record<string, string>>;
+    }>;
+    /** The approval-record path for one staged version (EXT-30, lifetime audit). */
+    approvalPath(extensionId: string, version: string): string;
+    /**
+     * Read the approval record for one staged version.
+     *
+     * A corrupt record fails closed with the diagnostic: an update whose approval
+     * cannot be read must NOT proceed as if it were approved.
+     * @param extensionId - the extension.
+     * @param version - the staged version.
+     * @returns the record (or undefined when none was written) and any diagnostic.
+     */
+    readApproval(extensionId: string, version: string): StateReadResult<UpdateApprovalRecord | undefined>;
+    /**
+     * Record ONE approval decision for one staged version (EXT-30).
+     *
+     * The record is retained for the store's LIFETIME (audit trail, no expiry)
+     * and is WRITE-ONCE per staged version: a later decision never silently
+     * overwrites an earlier one. A denied record stays as the audit entry.
+     * @param extensionId - the extension.
+     * @param version - the staged version.
+     * @param decision - the operator's decision.
+     * @throws ManagementError when an earlier decision exists.
+     */
+    recordApproval(extensionId: string, version: string, decision: {
+        approved: true;
+    } | {
+        approved: false;
+        reason: string;
+    }): void;
+    /**
+     * Remove ONE version's installation record (EXT-30 admission rollback).
+     *
+     * The per-version removal exists for the update flow's failure cleanup: when
+     * a commit fails after the new version was admitted, the new version's record
+     * is removed while every OTHER version's record survives.
+     * @param extensionId - the extension.
+     * @param version - the version to forget.
+     */
+    removeVersionRecord(extensionId: string, version: string): void;
+    /** The cleanup-pending tombstone directory. */
+    cleanupPendingDir(): string;
+    /**
+     * Record an owned deletion that could not complete (EXT-29).
+     *
+     * A tombstone keeps the CLEANUP_PENDING truth durable: the retry loop
+     * ({@link ExtensionStore.retryCleanupPending}) re-attempts the deletion on
+     * later runs, bounded, and the directory is never silently forgotten.
+     * @param targetPath - the path the deletion could not remove.
+     * @param reason - why the deletion failed.
+     */
+    writeCleanupTombstone(targetPath: string, reason: string): void;
+    /**
+     * Retry owned deletions recorded by tombstones (EXT-29), bounded.
+     *
+     * Every tombstone under the attempts cap gets ONE retry attempt per call;
+     * a still-failing deletion increments the counter and keeps the truthful
+     * CLEANUP_PENDING record. A path that no longer exists counts as deleted.
+     * @param maxAttempts - the attempts cap (default 5).
+     * @returns the per-run counts.
+     */
+    retryCleanupPending(maxAttempts?: number): {
+        retried: number;
+        deleted: number;
+        kept: number;
+    };
+    /**
+     * Read the durable legacy prepared-asset mappings a migration recorded.
+     *
+     * Kept on the store rather than folded into `readProfileState` because the
+     * state array is the lifecycle's working surface: changing its shape for the
+     * asset record would make every writer a silent dropper of the record, which
+     * is exactly the failure BASE-09's preservation clause names. The version
+     * gate matches {@link ExtensionStore.readProfileState}.
+     * @param profile - the profile name.
+     * @returns the recorded mappings and any diagnostic.
+     */
+    readMigratedAssets(profile: string): StateReadResult<readonly MigratedAssetRecord[]>;
+    /**
+     * Migrate a legacy model-id era document into this profile (BASE-09, BASE-10).
+     *
+     * The old world's `<DSH_HOME>/model-as-tool/state.json` held unversioned
+     * `enabled`/`disabled` MODEL-ID arrays. The host reads that document and hands
+     * its content here; this method runs it through the explicit migration table
+     * and writes the versioned profile state atomically under the store lock.
+     *
+     * Guarantees, per BASE-10:
+     * - Disabled choices are preserved as tool-level disables; nothing is
+     *   installed, activated or prepared by the migration.
+     * - Legacy enables are STAGED in the report, never granted.
+     * - Unresolved mappings are reported, never silently enabled.
+     * - A profile that already holds current-version state is left untouched
+     *   (double migration is idempotent); a document this SDK cannot interpret is
+     *   refused rather than overwritten.
+     * @param profile - the profile to migrate into.
+     * @param legacyJson - the legacy document's text. Omit it to migrate a
+     *   legacy-shaped document found at the profile state path itself.
+     * @param legacySource - description of the origin, for the report.
+     * @returns the migration report.
+     * @throws ManagementError when the input is not a usable legacy document or
+     *   the profile already holds a document this SDK refuses to overwrite.
+     */
+    migrateLegacyProfileState(profile: string, legacyJson?: string, legacySource?: string): Promise<MigrationReport>;
+}
+//# sourceMappingURL=store.d.ts.map

package/node_modules/@try-works/tool-mode-extension-sdk/lib/install/store.d.ts.map

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