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

package/lib/legacy-migration.js

@@ -0,0 +1,429 @@
+/**
+ * The startup hook that migrates a legacy model-id era `state.json` into the
+ * versioned world (BASE-09, BASE-10), ONCE per profile — as a REAL
+ * transaction with crash recovery, not a read-then-overwrite.
+ *
+ * Before this module the migration table existed only as an SDK library with
+ * tests: nothing in the host's production startup ever ran it, so a real
+ * upgrade kept reading the old-world document forever. This module is the
+ * production caller. Its guarantees:
+ *
+ * - ONCE-ANCHOR + COMMIT: a non-secret sidecar marker
+ *   (`<stateFile>.migrated.json`) is the commit record, written ATOMICALLY
+ *   (temp + fsync + rename) as the LAST step of the transaction. The host's
+ *   own state document keeps its exact shape — the store's writes are
+ *   untouched and no parallel format is written. A marker is VALIDATED on
+ *   every read (parse + exact version + list shape): a corrupt or
+ *   foreign-version marker FAILS CLOSED instead of silently counting the
+ *   profile as migrated;
+ * - IMMUTABLE JOURNAL: before ANY mutation, the original legacy document is
+ *   journaled to `<stateFile>.legacy-backup.json` with EXCLUSIVE creation
+ *   (`wx`). The journal is the legacy INPUT for every recovery. Its
+ *   first-write-wins behavior is guaranteed BY THE TRANSACTION LOCK (the
+ *   exists-check before the rename is advisory, not a lock);
+ * - RECOVERY: a crash between the host write and the marker leaves a journal
+ *   WITHOUT a committed marker. The next boot detects that state and re-runs
+ *   the transaction FROM THE VALIDATED JOURNAL — never from the already-
+ *   rewritten state file, which has lost the staged enables, provider picks
+ *   and prepared-asset facts. The host write MERGES with the current
+ *   document (current enables are operator-era facts and are preserved;
+ *   legacy disables are added), so an operator change after the crash is
+ *   never discarded. A corrupt journal with no marker FAILS CLOSED;
+ * - TRANSACTION LOCK: the whole transaction runs under an exclusive lock
+ *   file with an ownership token and pid. A stale lock is NEVER taken over
+ *   automatically — the read-then-remove sequence is not atomic and two
+ *   concurrent reapers could delete a successor's fresh lock — so a held lock
+ *   FAILS CLOSED at the deadline and the operator removes it deliberately;
+ *   release removes only a token-owned lock (the same discipline as the
+ *   credential store);
+ * - the SDK profile half runs THROUGH the SDK's own
+ *   `migrateLegacyProfileState` (its lock, idempotence, version gate) BEFORE
+ *   the host document is written;
+ * - DISABLED legacy choices are preserved — ALL of them, mapped or not: an
+ *   unmapped disabled id that vanished from the host state would let a later
+ *   package restore silently enable what the operator turned off. Unresolved
+ *   ids are REPORTED separately, never enabled;
+ * - legacy ENABLES are STAGED, never granted (BASE-10: a legacy enable is
+ *   not consent to install, activate or prepare third-party code);
+ * - every persisted artifact (marker, journal, lock) is NON-SECRET by
+ *   construction: model ids, provider identifiers and counts, never a secret.
+ *
+ * @module @try-works/dsh-model-as-tool/legacy-migration
+ */
+import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeFileSync, } from 'node:fs';
+import { dirname } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { applyLegacyChoices, ExtensionStore, parseLegacyModelState, } from '@try-works/tool-mode-extension-sdk';
+import { StateError } from "./state.js";
+/** The marker version this host writes; equality, never a lower bound. */
+export const MIGRATION_MARKER_VERSION = 1;
+/** The marker path for one state file. */
+export function migrationMarkerPath(stateFile) {
+    return `${stateFile}.migrated.json`;
+}
+/** The backup path for one state file. */
+export function legacyBackupPath(stateFile) {
+    return `${stateFile}.legacy-backup.json`;
+}
+/** The transaction lock path for one state file. */
+export function migrationLockPath(stateFile) {
+    return `${stateFile}.migration.lock`;
+}
+/** Unique ids in first-seen order. */
+function unique(ids) {
+    return [...new Set(ids)];
+}
+/** A real blocking sleep, without burning the CPU. */
+function sleep(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+/**
+ * The transaction lock: exclusive creation, ownership token + pid, bounded
+ * retries, and release removes ONLY a token-owned lock. There is NO automatic
+ * stale takeover: two concurrent reapers could each read a stale record and
+ * remove a SUCCESSOR's fresh lock between its create and its next open — the
+ * read→rm sequence is not atomic. A lock whose holder cannot be proven live
+ * therefore FAILS CLOSED at the deadline and the operator removes the lock
+ * file deliberately.
+ */
+function acquireMigrationLock(stateFile) {
+    const lockPath = migrationLockPath(stateFile);
+    const token = randomBytes(16).toString('hex');
+    const deadline = Date.now() + 10_000;
+    for (;;) {
+        try {
+            const fd = openSync(lockPath, 'wx');
+            try {
+                writeFileSync(fd, JSON.stringify({ token, pid: process.pid, at: Date.now() }), 'utf8');
+                fsyncSync(fd);
+            }
+            finally {
+                closeSync(fd);
+            }
+            return () => {
+                let held;
+                try {
+                    held = JSON.parse(readFileSync(lockPath, 'utf8'));
+                }
+                catch {
+                    return;
+                }
+                if (held === undefined || held.token !== token)
+                    return;
+                try {
+                    rmSync(lockPath, { force: true });
+                }
+                catch {
+                    // Already gone.
+                }
+            };
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            if (Date.now() > deadline) {
+                throw new StateError('the legacy migration is locked by another writer; the transaction was not attempted '
+                    + `(remove ${lockPath} only after confirming no writer holds it)`);
+            }
+            sleep(25);
+        }
+    }
+}
+/** Read and VALIDATE the marker; a corrupt or foreign marker fails closed. */
+function readMarker(stateFile) {
+    let text;
+    try {
+        text = readFileSync(migrationMarkerPath(stateFile), 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw new StateError(`cannot read the migration marker ${migrationMarkerPath(stateFile)}: `
+            + `${error instanceof Error ? error.message : String(error)}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (error) {
+        throw new StateError(`the migration marker ${migrationMarkerPath(stateFile)} is not valid JSON and will not be trusted: `
+            + `${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new StateError(`the migration marker ${migrationMarkerPath(stateFile)} is not a JSON object`);
+    }
+    const marker = parsed;
+    if (marker.hostStateVersion !== MIGRATION_MARKER_VERSION) {
+        throw new StateError(`the migration marker ${migrationMarkerPath(stateFile)} was written by a different era `
+            + `(hostStateVersion ${JSON.stringify(marker.hostStateVersion)}); this host writes ${MIGRATION_MARKER_VERSION}`);
+    }
+    // The FULL shape is validated: a marker that parses but does not say what a
+    // committed transaction says (legacy flag, timestamp, STRING id lists) is
+    // corrupt, and trusting it would silently count the profile as migrated.
+    if (typeof marker.legacy !== 'boolean' || typeof marker.migratedAt !== 'string') {
+        throw new StateError(`the migration marker ${migrationMarkerPath(stateFile)} does not carry a committed transaction record`);
+    }
+    if (!Array.isArray(marker.staged) || marker.staged.some(id => typeof id !== 'string')) {
+        throw new StateError(`the migration marker ${migrationMarkerPath(stateFile)} carries a malformed staged list`);
+    }
+    if (!Array.isArray(marker.unresolved) || marker.unresolved.some(id => typeof id !== 'string')) {
+        throw new StateError(`the migration marker ${migrationMarkerPath(stateFile)} carries a malformed unresolved list`);
+    }
+    return marker;
+}
+/** Write the marker ATOMICALLY: temp + fsync + rename, never a truncating write. */
+function writeMarkerAtomic(stateFile, marker) {
+    mkdirSync(dirname(stateFile), { recursive: true });
+    const temporary = `${migrationMarkerPath(stateFile)}.tmp-${randomBytes(8).toString('hex')}`;
+    const fd = openSync(temporary, 'wx', 0o600);
+    try {
+        writeFileSync(fd, `${JSON.stringify(marker, null, 2)}\n`, 'utf8');
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+    try {
+        renameSync(temporary, migrationMarkerPath(stateFile));
+    }
+    catch (error) {
+        rmSync(temporary, { force: true });
+        throw error;
+    }
+}
+/** Read and VALIDATE the journal; undefined only when it does not exist. */
+function readBackup(stateFile) {
+    let text;
+    try {
+        text = readFileSync(legacyBackupPath(stateFile), 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw new StateError(`cannot read the migration journal ${legacyBackupPath(stateFile)}: `
+            + `${error instanceof Error ? error.message : String(error)}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (error) {
+        throw new StateError(`the migration journal ${legacyBackupPath(stateFile)} is not valid JSON; `
+            + `an interrupted transaction cannot be recovered safely: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)
+        || !('legacyDocument' in parsed)) {
+        throw new StateError(`the migration journal ${legacyBackupPath(stateFile)} does not hold a legacyDocument`);
+    }
+    return parsed;
+}
+/** Journal the ORIGINAL document EXCLUSIVELY: `wx` create; the first-write-wins
+ * guarantee across retries comes from the TRANSACTION LOCK that serializes
+ * writers, with the exists-check as an advisory belt. */
+function journalLegacyDocument(stateFile, legacyDocument) {
+    mkdirSync(dirname(stateFile), { recursive: true });
+    const temporary = `${legacyBackupPath(stateFile)}.tmp-${randomBytes(8).toString('hex')}`;
+    const backup = { migratedAt: new Date().toISOString(), legacyDocument };
+    const fd = openSync(temporary, 'wx', 0o600);
+    try {
+        writeFileSync(fd, `${JSON.stringify(backup, null, 2)}\n`, 'utf8');
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+    try {
+        // link-or-rename is not available; the rename loses if a journal already
+        // exists (first-write-wins), which is exactly the retry discipline.
+        if (existsSync(legacyBackupPath(stateFile))) {
+            rmSync(temporary, { force: true });
+            return;
+        }
+        renameSync(temporary, legacyBackupPath(stateFile));
+    }
+    catch (error) {
+        rmSync(temporary, { force: true });
+        throw error;
+    }
+}
+/**
+ * Derive the migration facts from one legacy document (the SDK's table — no
+ * parallel format): staged enables, unresolved ids, the disabled ids and the
+ * enabled ids (the journal-enabled set the recovery merge stages by).
+ */
+function deriveFacts(legacyDocument, source) {
+    const legacy = parseLegacyModelState(legacyDocument, source);
+    if (legacy.state === undefined) {
+        throw new StateError(legacy.diagnostic ?? `${source} is not a usable legacy state document`);
+    }
+    const applied = applyLegacyChoices(legacy.state);
+    const staged = [];
+    const unresolved = [];
+    for (const entry of applied.entries) {
+        switch (entry.kind) {
+            case 'enabled-choice':
+                if (entry.outcome === 'staged')
+                    staged.push(entry.legacyModelId);
+                else if (entry.outcome === 'unresolved' || entry.outcome === 'conflicting')
+                    unresolved.push(entry.legacyModelId);
+                break;
+            case 'disabled-choice':
+            case 'provider-selection':
+            case 'prepared-asset':
+                if (entry.outcome === 'unresolved')
+                    unresolved.push(entry.legacyModelId);
+                break;
+        }
+    }
+    return {
+        staged,
+        unresolved,
+        legacyDisabled: [...legacy.state.disabled],
+        legacyEnabled: [...legacy.state.enabled],
+        legacyJson: JSON.stringify(legacyDocument),
+    };
+}
+/**
+ * Run the one-time legacy startup migration (with crash recovery).
+ *
+ * @param options.stateFile - the host's configured isolated state path.
+ * @param options.store - the host's state store over that path.
+ * @param options.extensionStoreDir - when the deployment mounts an extension
+ *   store, the SDK profile migration runs there too.
+ * @param options.log - a non-secret log sink (the host's logger).
+ * @returns the outcome; the caller ALWAYS adopts `hostState` (the hook returns
+ * a fresh post-lock read on every path, so adopting it never re-applies a
+ * pre-hook snapshot).
+ */
+export async function runLegacyStartupMigration(options) {
+    const { stateFile, store, extensionStoreDir, log } = options;
+    // The parent chain must exist BEFORE the lock file is created: a fresh
+    // profile's first boot has no directory yet.
+    mkdirSync(dirname(stateFile), { recursive: true });
+    const release = acquireMigrationLock(stateFile);
+    try {
+        return await transaction(stateFile, store, extensionStoreDir, log);
+    }
+    finally {
+        release();
+    }
+}
+async function transaction(stateFile, store, extensionStoreDir, log) {
+    // The once-anchor, VALIDATED: a marker is trusted only when it parses and
+    // carries exactly this host's version. A committed transaction is final.
+    const marker = readMarker(stateFile);
+    if (marker !== undefined) {
+        return {
+            ran: false,
+            hostState: store.read(),
+            staged: marker.staged,
+            unresolved: marker.unresolved,
+            logLine: undefined,
+            recovered: false,
+        };
+    }
+    // RECOVERY DECISION: a journal WITHOUT a committed marker is an interrupted
+    // transaction. The legacy INPUT is the VALIDATED journal — never the
+    // already-rewritten state file, which has lost the staged enables, provider
+    // picks and prepared-asset facts.
+    const backup = readBackup(stateFile);
+    const recovered = backup !== undefined;
+    let legacyDocument;
+    if (recovered) {
+        legacyDocument = backup.legacyDocument;
+    }
+    else {
+        let raw;
+        try {
+            raw = readFileSync(stateFile, 'utf8');
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT') {
+                throw new StateError(`cannot read ${stateFile}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        if (raw === undefined) {
+            // A FRESH profile: nothing to migrate. The marker is written anyway so
+            // the profile's own later enable/disable writes can never be mis-read as
+            // a legacy era on a future boot.
+            writeMarkerAtomic(stateFile, {
+                hostStateVersion: MIGRATION_MARKER_VERSION,
+                migratedAt: new Date().toISOString(),
+                legacy: false,
+                staged: [],
+                unresolved: [],
+            });
+            return { ran: false, hostState: store.read(), staged: [], unresolved: [], logLine: undefined, recovered: false };
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch (error) {
+            throw new StateError(`${stateFile} is not valid JSON and will not be migrated or overwritten: `
+                + `${error instanceof Error ? error.message : String(error)}`);
+        }
+        // A document carrying a version key is not the legacy era. ANY version
+        // fails closed here (the SDK's equality gate, not a lower bound).
+        if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)) {
+            const version = parsed.stateVersion;
+            if (version !== undefined) {
+                throw new StateError(`${stateFile} carries a stateVersion (${JSON.stringify(version)}) this host does not write; `
+                    + 'the migration refuses to re-interpret a versioned document');
+            }
+        }
+        legacyDocument = parsed;
+    }
+    const facts = deriveFacts(legacyDocument, recovered ? legacyBackupPath(stateFile) : stateFile);
+    // TRANSACTION ORDER — journal first (fresh runs only), SDK second, host
+    // write third, marker last. The journal exists BEFORE any mutation, so a
+    // crash at any later step leaves a recovery path from the original.
+    if (!recovered)
+        journalLegacyDocument(stateFile, legacyDocument);
+    let sdkEntries = [];
+    if (extensionStoreDir !== undefined && extensionStoreDir.length > 0) {
+        const extensionStore = new ExtensionStore(extensionStoreDir);
+        const report = await extensionStore.migrateLegacyProfileState('default', facts.legacyJson, legacyBackupPath(stateFile));
+        sdkEntries = report.entries;
+    }
+    // CONSERVATIVE MERGE, recovery only: the journal's ENABLED ids are legacy
+    // facts and are ALWAYS staged — even if the current document still carries
+    // them (a crash before the host write leaves the original legacy document
+    // in place, and trusting its enables would grant what BASE-10 stages).
+    // Current enables that are NOT journal-enabled ids are operator-era facts
+    // from after the crash and are kept. On a first run the current document IS
+    // the legacy document: nothing may be carried into `enabled` at all.
+    const current = store.read();
+    const journalEnabled = new Set(facts.legacyEnabled);
+    const hostState = recovered
+        ? {
+            enabled: unique(current.enabled.filter(id => !journalEnabled.has(id))).sort(),
+            disabled: unique([...current.disabled, ...facts.legacyDisabled]).sort(),
+        }
+        : {
+            enabled: [],
+            disabled: unique(facts.legacyDisabled).sort(),
+        };
+    store.write(hostState);
+    const stagedIds = unique(facts.staged);
+    const unresolvedIds = unique([...facts.unresolved, ...sdkEntries
+            .filter(entry => entry.outcome === 'unresolved')
+            .map(entry => entry.legacyModelId)]);
+    writeMarkerAtomic(stateFile, {
+        hostStateVersion: MIGRATION_MARKER_VERSION,
+        migratedAt: new Date().toISOString(),
+        legacy: true,
+        staged: stagedIds,
+        unresolved: unresolvedIds,
+    });
+    const logLine = `${recovered ? 'legacy migration RECOVERED from the journal' : 'legacy migration'}: `
+        + `${hostState.disabled.length} disabled choice(s) preserved, `
+        + `${stagedIds.length} enable(s) staged (not granted), `
+        + `${unresolvedIds.length} unresolved id(s) reported`
+        + (unresolvedIds.length > 0 ? `: ${unresolvedIds.join(', ')}` : '')
+        + (sdkEntries.length > 0 ? `; SDK profile entries: ${sdkEntries.length}` : '')
+        + `; original document journaled at ${legacyBackupPath(stateFile)}`;
+    log?.(logLine);
+    return { ran: true, hostState, staged: stagedIds, unresolved: unresolvedIds, logLine, recovered };
+}
+//# sourceMappingURL=legacy-migration.js.map

package/lib/managed-workers.d.ts

@@ -0,0 +1,151 @@
+/**
+ * The host's managed-worker registry (EXT-20, the host half).
+ *
+ * The SDK ships the mechanism — {@link ManagedExtensionWorker}, a scrubbed-environment
+ * child process speaking the bounded invoke protocol — and this module is the host-side
+ * LIFETIME discipline: ONE worker process per extension per activation GENERATION,
+ * reused across invocations, disposed the moment the generation advances (a
+ * re-activation gets a fresh process, the old one never serves another call).
+ *
+ * What stays OUT of the worker, by construction:
+ *
+ * - the grant: the host authorizes the caller BEFORE dispatch ever builds a provider,
+ *   so `providerFor` here runs only for calls that already passed authorization, and
+ *   the worker receives exactly `{implementationId, input}` — no grant, no caller
+ *   identity, no configuration secrets;
+ * - the schemas: input validation happened host-side before the call, and the returned
+ *   value is validated against the declared output schema by the same path that
+ *   validates the in-process result — the worker's payload is treated as untrusted
+ *   data exactly like an in-process provider's;
+ * - receipts and accounting: untouched — they record the call in the same code path.
+ *
+ * IDENTITY: the worker is keyed by the extension's TRUE MANIFEST ID, never by a path
+ * or a package specifier (an install path must not leak into diagnostics or collide
+ * with a package name). The SDK child also derives its implementation->model mapping
+ * from the owning package.json + the manifest beside the entry, so this registry
+ * STAGES a host-owned worker directory — package.json + the manifest + a junction to
+ * the entry's directory — when the entry's own package root does not carry them
+ * (a staged store copy extracts no manifest). The entry's REAL bytes are the ones the
+ * worker executes: the junction resolves to the verified installed copy, never a host
+ * rewrite.
+ *
+ * Every worker failure surfaces as the SDK's ManagementError vocabulary
+ * (EXTENSION_FAULT), which the dispatch path converts into a tool error; the host
+ * process is never affected.
+ *
+ * @module @try-works/dsh-model-as-tool/managed-workers
+ */
+import type { PreparedAssetMapV1, ProviderInspectionV1 } from '@try-works/tool-mode-extension-sdk';
+/** What the host needs to route one extension's calls out of process. */
+export interface ManagedWorkerBinding {
+    /**
+     * The extension's TRUE MANIFEST ID (the `id` field of the manifest), which keys
+     * the worker and is passed to the child as its identity. Never a path.
+     */
+    readonly extensionId: string;
+    /** Absolute path of the built `./tool-mode` entry (plain Node ESM). */
+    readonly entryPath: string;
+    /**
+     * Absolute path of the extension manifest, when the host can resolve one. Absent
+     * (a store copy with no extracted manifest), the worker cannot derive the model
+     * mapping and the call fails with the precise reason — until the SDK lands the
+     * host-supplied mapping API.
+     */
+    readonly manifestPath?: string;
+    /** The activation generation this binding serves (EXT-20 lifetime discipline). */
+    readonly generation: number;
+    /** Explicit environment names passed through to the scrubbed child env. */
+    readonly envPassthrough?: readonly string[];
+}
+/** The dispatch-provider shape the registry hands back. */
+export interface ManagedWorkerProvider {
+    load(request: {
+        /** The manifest model id the assets prepare (worker.load keys by model id). */
+        readonly modelId: string;
+        readonly assets: Readonly<PreparedAssetMapV1>;
+        readonly signal: AbortSignal;
+    }): Promise<void>;
+    invoke(request: {
+        readonly implementationId: string;
+        readonly input: Readonly<Record<string, unknown>>;
+        readonly context: unknown;
+    }): Promise<Record<string, unknown>>;
+}
+/**
+ * The catalog-adapter surface a managed worker serves (EXT-20, host half).
+ *
+ * This is what the ProviderBridge uses in managed mode. The worker receives the
+ * narrow validated input plus a REQUEST-SCOPED path broker (the host's own
+ * authority, `resolvePath` — omitted means denial by the protocol), and answers
+ * with the payload; the host then applies the same reserved-meta assertion and
+ * contract translation as the in-process path. The worker never sees the grant,
+ * the caller identity or the host environment. Inspection and load/unload run
+ * ENTIRELY in the managed process through the SDK's inspect/load/unload APIs.
+ */
+export interface ManagedWorkerAdapter {
+    /** Inspect one manifest model, entirely in the managed process (EXT-18). */
+    inspect(modelId: string, options?: {
+        readonly signal?: AbortSignal;
+    }): Promise<ProviderInspectionV1>;
+    /** Load the host-prepared assets for one model in the managed process. */
+    load(modelId: string, options: {
+        readonly assets: Readonly<PreparedAssetMapV1>;
+        readonly signal?: AbortSignal;
+    }): Promise<void>;
+    /** Release one model's loaded resources without disposing the worker. */
+    unload(modelId: string, options?: {
+        readonly signal?: AbortSignal;
+    }): Promise<void>;
+    /** Invoke one implementation through the managed process. */
+    invoke(request: {
+        readonly implementationId: string;
+        readonly input: Readonly<Record<string, unknown>>;
+        readonly signal?: AbortSignal;
+        /** The HOST's request-scoped canonical path broker; omitted means the child denies. */
+        readonly resolvePath?: (candidate: string) => string | Promise<string>;
+    }): Promise<Record<string, unknown>>;
+    /** Dispose the worker process and forget it (deactivation/teardown). */
+    dispose(): Promise<void>;
+    /** The child pid, when the process is alive. */
+    pid(): number | undefined;
+}
+/** Which provider lifecycle phases the CURRENT protocol serves in the child. */
+export interface ManagedWorkerCapabilities {
+    /** TRUE: the SDK child serves the inspect message. */
+    readonly inspect: true;
+    /** TRUE: the SDK child serves the load/unload messages (host-prepared assets only). */
+    readonly load: true;
+}
+/** The registry of live extension workers. */
+export interface ManagedWorkerRegistry {
+    /**
+     * The dispatch provider for one extension, creating or reusing the worker bound to
+     * the CURRENT generation. A generation change disposes the old process before the
+     * new one is created, so a stale worker can never serve a new activation's calls.
+     */
+    providerFor(binding: ManagedWorkerBinding): Promise<ManagedWorkerProvider>;
+    /**
+     * The catalog-adapter surface for one extension (the ProviderBridge's managed
+     * path): invoke over the wire, disposal, and the child pid. The same
+     * per-generation binding discipline as {@link providerFor}.
+     */
+    adapterFor(binding: ManagedWorkerBinding): Promise<ManagedWorkerAdapter>;
+    /** Dispose one extension's worker and forget it (the deactivation hook). */
+    dispose(extensionId: string): Promise<void>;
+    /** What the current SDK protocol serves, for the callers that refuse the rest. */
+    capabilities(): ManagedWorkerCapabilities;
+    /** The live bindings, for tests and diagnostics. */
+    bindings(): readonly {
+        readonly extensionId: string;
+        readonly generation: number;
+        readonly pid: number | undefined;
+    }[];
+    /** Dispose every worker (host teardown). */
+    disposeAll(): Promise<void>;
+}
+/**
+ * Create the host's managed-worker registry.
+ * @returns the registry.
+ */
+export declare function createManagedWorkerRegistry(): ManagedWorkerRegistry;
+//# sourceMappingURL=managed-workers.d.ts.map

package/lib/managed-workers.d.ts.map

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