@north-light/api 0.3.579 → 0.3.587

package/dist/core/providers/bundles.js

@@ -0,0 +1,638 @@
+// Capability-provider bundles on this runtime (contract 3, "Installing" and
+// "Which major serves a call"; D3-INS-*, D3-VER-*).
+//
+// A runtime knows a provider's tools only through the bundle the directory
+// serves at `GET <issuer>/providers/<id>/plugin[?version=N]`: an uncompressed
+// tar with `bundle.json` (the `provider` block, the provider's own transport)
+// and `commands.json`, an ETag over the tar bytes, 304 on a matching
+// `If-None-Match`, 410 `provider_version_retired` for a dropped major, 404 for
+// a provider or major never served.
+//
+// - The newest major installs as an ordinary archive plugin named `<id>` at
+//   `<crtrHome>/plugins/<id>/`, through the same stage-and-swap and the same
+//   candidate validation as `crtr pkg plugin install --endpoint`
+//   (`installPluginArchive`). Its validator is the plugin state ledger's
+//   `etag`, exactly as for any archive plugin.
+// - A pinned major is cached, not installed, at
+//   `<crtrHome>/providers/<id>/v<N>/{bundle.tar,etag}`; a major the directory
+//   answered 410 for keeps only a `retired` marker, so later pinned calls fail
+//   without a fetch.
+//
+// Grant sync (`syncProviderBundles`, hooked from `grants/on-sync.ts`) installs
+// every provider an active grant names, refreshes installed ones
+// conditionally, then revalidates every cached pinned major. A bundle that
+// fails validation is never swapped in: the previous one stays, and the
+// failure is logged as `daemon.providers.bundle_invalid`. The same pass then
+// uninstalls an installed provider bundle no active grant names any more.
+import { existsSync, readdirSync, readFileSync, rmSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { validateCommandManifest } from '../../api/command-manifest/manifest.js';
+import { crtrHome } from '../canvas/paths.js';
+import { isCloudRole } from '../canvas/person-state.js';
+import { withCanvasWrite } from '../canvas/db.js';
+import { bundleVersion, isInstalledGeneration, recordCheckedGeneration } from '../command-plugins/bundle.js';
+import { readState, updateConfig, updateState } from '../config.js';
+import { directoryIssuer } from '../directory/issuer.js';
+import { emitEvent } from '../events/emit.js';
+import { describeOutboundFailure, outboundFetch, outboundRefusal, OutboundError } from '../events/outbound.js';
+import { withExclusiveDirectoryLockAsync } from '../exclusive-lock.js';
+import { atomicWriteText, ensureDir, pathExists } from '../fs-utils.js';
+import { reconcilePackages } from '../graph/package-reconcile.js';
+import { readPluginManifest } from '../manifest.js';
+import { bundleSwapLockPath } from '../plugin-swap-lock.js';
+import { pluginsDir, userScopeRoot } from '../scope.js';
+import { installedProviderPlugins } from './roots.js';
+import { allGrants, localGrants, providerIdsFromGrants } from '../grants/mirror.js';
+import { ProviderError } from './errors.js';
+/** Contract 1's `<id>` grammar, shared by provider ids and group ids. */
+const ID = '[A-Za-z0-9_-]{1,64}';
+const PROVIDER_ID = new RegExp(`^${ID}$`);
+/** Under G3 the directory refreshes the provider (`/versions` plus every
+ *  major) before it answers a conditional fetch, so allow for that round trip. */
+const FETCH_TIMEOUT_MS = 30_000;
+/** A sync waits this long for another process's swap of the same plugin. */
+const SWAP_WAIT_MS = 30_000;
+// ── Grants → provider ids ────────────────────────────────────────────────────
+// ── Paths ────────────────────────────────────────────────────────────────────
+function pluginRoot(id) {
+    return join(pluginsDir('user'), id);
+}
+// A cloud role serves many people from one plugin directory, so the install record of a bundle in it is the deployment's, not a person's
+// (`scope_plugins` rows hold a person's). Installed means a valid provider manifest in that directory; its `version` is the installed
+// generation; the validator of the bytes there is one sidecar file beside it. A Mac keeps the record in the user's config and state.
+function etagFile(id) {
+    return join(pluginsDir('user'), `.${id}.etag`);
+}
+function storedEtag(id) {
+    if (!isCloudRole())
+        return readState('user').plugins[id]?.etag;
+    try {
+        return readFileSync(etagFile(id), 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+}
+async function recordEtag(id, etag) {
+    if (!isCloudRole())
+        return recordCheckedGeneration('user', id, etag, { swapped: false });
+    if (etag === undefined)
+        rmSync(etagFile(id), { force: true });
+    else
+        atomicWriteText(etagFile(id), etag);
+}
+// Publishing a bundle's `memory/**` documents reconciles every installed user plugin. A cloud role has no per-person plugin list at grant sync
+// (outside a request), so that pass would see none installed and delete shipped documents, clear manifest kinds and revoke app tokens
+// deployment-wide. Provider documents are therefore not published on a cloud role.
+async function reconcileProviderDocs(id) {
+    if (isCloudRole())
+        return;
+    try {
+        await withCanvasWrite(async (db) => await reconcilePackages(db));
+    }
+    catch (error) {
+        emitEvent({ level: 'error', event: 'daemon.providers.docs_reconcile_failed', fields: { provider: id }, error });
+    }
+}
+function installedGeneration(id, root, version) {
+    if (!isCloudRole())
+        return isInstalledGeneration(id, 'user', root, version);
+    return readPluginManifest(root)?.version === version && pathExists(join(root, 'commands.json'));
+}
+function providersRoot() {
+    return join(crtrHome(), 'providers');
+}
+function majorDir(id, major) {
+    return join(providersRoot(), id, `v${major}`);
+}
+function assertId(id) {
+    if (!PROVIDER_ID.test(id))
+        throw new ProviderError('not_found', `"${id}" is not a provider id`, { param: 'provider' });
+}
+function directoryBase() {
+    const issuer = directoryIssuer();
+    if (!issuer)
+        throw new ProviderError('not_found', 'provider bundles need a directory-connected runtime');
+    return issuer;
+}
+/** One public GET of a provider bundle. Distinguishes 304, 404 and 410, which
+ *  the plugin archive fetcher folds into one protocol error. */
+async function fetchProviderBundle(id, options) {
+    const url = `${directoryBase()}/providers/${encodeURIComponent(id)}/plugin${options.version !== undefined ? `?version=${options.version}` : ''}`;
+    let response;
+    try {
+        response = await outboundFetch('bundle_fetch', url, {
+            headers: { Accept: 'application/x-tar', ...(options.ifNoneMatch !== undefined ? { 'If-None-Match': options.ifNoneMatch } : {}) },
+            signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+        });
+    }
+    catch (error) {
+        return { status: 'failed', message: `could not reach ${url}: ${error instanceof Error ? error.message : String(error)}`, cause: error };
+    }
+    if (response.status === 304) {
+        if (options.ifNoneMatch === undefined) {
+            const message = `HTTP 304 from ${url} without a conditional request`;
+            return { status: 'failed', message, cause: outboundRefusal('bundle_fetch', url, message) };
+        }
+        return { status: 304 };
+    }
+    if (response.status === 404 || response.status === 410) {
+        await response.body?.cancel().catch(() => { });
+        return { status: response.status === 404 ? 404 : 410, message: `HTTP ${response.status} from ${url}` };
+    }
+    if (response.status < 200 || response.status >= 300) {
+        await response.body?.cancel().catch(() => { });
+        {
+            const message = `HTTP ${response.status} from ${url}`;
+            return { status: 'failed', message, cause: outboundRefusal('bundle_fetch', url, message) };
+        }
+    }
+    let raw;
+    try {
+        raw = new Uint8Array(await response.arrayBuffer());
+    }
+    catch (error) {
+        return { status: 'failed', message: `reading ${url} failed: ${error instanceof Error ? error.message : String(error)}`, cause: new OutboundError('bundle_fetch', url, error) };
+    }
+    const etag = response.headers.get('etag');
+    return { status: 200, raw, ...(etag !== null ? { etag } : {}) };
+}
+// ── Validation shared by both kinds of major ─────────────────────────────────
+/** Errors already logged as `bundle_invalid`, so the sync pass does not log them twice. */
+const logged = new WeakSet();
+class BundleInvalid extends Error {
+    issues;
+    constructor(message, issues) {
+        super(message);
+        this.issues = issues;
+    }
+}
+/** Why a validated archive is not the bundle this fetch asked for. */
+function wrongBundle(id, major, bundle) {
+    if (bundle.provider === undefined)
+        return 'the archive carries no provider block';
+    if (bundle.provider.id !== id)
+        return `the archive is provider "${bundle.provider.id}", not "${id}"`;
+    if (major !== undefined && bundle.provider.major !== major)
+        return `the archive is major ${bundle.provider.major}, not ${major}`;
+    // A provider bundle is `bundle.json`, `commands.json` and `memory/**` only.
+    // Hooks, kinds, page components and memory extensions put code or config the
+    // runtime acts on into an install no person approved, so they are refused.
+    const extras = ['hooks', 'kinds', 'page_components', 'memory_extensions'].filter((key) => bundle[key] !== undefined);
+    if (extras.length > 0)
+        return `a provider bundle may not carry ${extras.join(', ')}`;
+    return undefined;
+}
+function logInvalid(id, major, error) {
+    emitEvent({ level: 'error', event: 'daemon.providers.bundle_invalid', fields: { provider: id, ...(major !== undefined ? { major } : {}),
+            ...(error instanceof BundleInvalid ? { issues: error.issues } : {}) }, error });
+}
+/** One line per completed bundle fetch that installed nothing new, so a day-old log shows which major each sync saw and whether the directory answered 304. */
+function logChecked(id, major, status, etag, outcome) {
+    emitEvent({ level: 'info', event: 'daemon.providers.bundle_checked', fields: { provider: id, ...(major !== undefined ? { major } : {}), status, ...(etag !== undefined ? { etag } : {}), outcome } });
+}
+function logFailure(id, major, error) {
+    emitEvent({ level: 'warn', event: 'daemon.providers.bundle_fetch_failed', fields: { provider: id, ...(major !== undefined ? { major } : {}),
+            message: error instanceof Error ? error.message : String(error), ...describeOutboundFailure(error instanceof Error ? error.cause : undefined) } });
+}
+async function pluginManage() {
+    return import('../../commands/pkg/plugin-manage.js');
+}
+const installAttempts = new Map();
+const installKey = (id) => `${crtrHome()}\0${id}`;
+/** Never publish an upstream message, URL, archive content, or stack trace. */
+function publicInstallCause(error) {
+    const cause = error;
+    const code = cause?.code ?? cause?.cause?.code;
+    if (typeof code === 'string' && /^[A-Z][A-Z0-9_]{1,30}$/.test(code))
+        return `${code} on provider install directory`;
+    if (error instanceof ProviderError && error.message.includes('HTTP 404'))
+        return 'directory returned HTTP 404';
+    if (error instanceof ProviderError && error.message.includes('HTTP 410'))
+        return 'directory returned HTTP 410';
+    return 'provider bundle could not be installed';
+}
+export function providerInstallState(id) {
+    if (installedManifest(id) !== undefined)
+        return undefined;
+    return installAttempts.get(installKey(id)) ?? { status: 'installing' };
+}
+/** A stable, sanitized error for calls while the newest bundle is absent. */
+export function unavailableProviderError(id) {
+    return new ProviderError('provider_unavailable', `provider "${id}" unavailable: ${providerInstallState(id)?.error ?? 'bundle installation pending'}`);
+}
+function installedManifest(id) {
+    const manifest = readPluginManifest(pluginRoot(id));
+    if (manifest?.provider === undefined || (manifest.transport?.kind !== 'http' && manifest.transport?.kind !== 'machine'))
+        return undefined;
+    if (!pathExists(join(pluginRoot(id), 'commands.json')))
+        return undefined;
+    // A 0-byte commands.json (a write cut short) is not an installed bundle: report it absent so the next sync reinstalls it.
+    try {
+        if (statSync(join(pluginRoot(id), 'commands.json')).size === 0)
+            return undefined;
+    }
+    catch {
+        return undefined;
+    }
+    return { provider: manifest.provider, transport: manifest.transport.kind === 'machine' ? { kind: 'machine' } : { kind: 'http', endpoint: manifest.transport.endpoint } };
+}
+/**
+ * Fetch the newest major and swap it in when it changed. `conditional` sends
+ * the validator stored for the installed bundle; an absent bundle is always
+ * fetched outright. Throws a `ProviderError`: `not_found` when the directory
+ * serves no such provider or the archive is invalid (the previous bundle
+ * stays), `provider_unavailable` when the fetch itself failed.
+ */
+async function refreshInstalled(id, conditional, ifAbsent = false) {
+    const scopeRootPath = userScopeRoot();
+    if (installedManifest(id) === undefined)
+        installAttempts.set(installKey(id), { status: 'installing' });
+    try {
+        ensureDir(join(scopeRootPath, 'tmp'));
+        return await withExclusiveDirectoryLockAsync(bundleSwapLockPath(scopeRootPath, id), async () => {
+            const root = pluginRoot(id);
+            const existing = readPluginManifest(root);
+            if (existing !== null && existing.provider === undefined) {
+                // A plugin the person installed under this name is theirs; never replace it.
+                throw new ProviderError('provider_unavailable', `plugin "${id}" is installed and is not the directory's provider bundle`);
+            }
+            const present = installedManifest(id) !== undefined;
+            // An `ensure` that waited on the lock behind another install has nothing left to do.
+            if (present && ifAbsent)
+                return 'unchanged';
+            const etag = present && conditional ? storedEtag(id) : undefined;
+            const fetched = await fetchProviderBundle(id, etag !== undefined ? { ifNoneMatch: etag } : {});
+            if (fetched.status === 304) {
+                logChecked(id, installedManifest(id)?.provider.major, 304, etag, 'unchanged');
+                return 'unchanged';
+            }
+            if (fetched.status === 404 || fetched.status === 410)
+                throw new ProviderError('not_found', `the directory serves no provider "${id}" (${fetched.message})`, { param: 'provider' });
+            if (fetched.status === 'failed')
+                throw new ProviderError('provider_unavailable', `provider "${id}" bundle fetch failed: ${fetched.message}`, { cause: fetched.cause });
+            const version = bundleVersion(fetched.raw);
+            if (present && installedGeneration(id, root, version)) {
+                await recordEtag(id, fetched.etag);
+                logChecked(id, installedManifest(id)?.provider.major, 200, fetched.etag, 'unchanged');
+                return 'unchanged';
+            }
+            const { installPluginArchive } = await pluginManage();
+            // The validator must never name an older directory after a crash between swapping the new one and writing its sidecar.
+            // Clearing it before the swap is safe: a refused archive leaves the old bundle, which the next sync fetches again.
+            if (isCloudRole())
+                rmSync(etagFile(id), { force: true });
+            try {
+                await installPluginArchive(id, fetched.raw, {
+                    scope: 'user', scopeRootPath, root, version, etag: fetched.etag,
+                    // A fresh install is enabled; an update keeps a person's `crtr pkg plugin disable`.
+                    enable: !present,
+                    bundle: { endpoint: `${directoryBase()}/providers/${encodeURIComponent(id)}/plugin` },
+                    // Replaced by the archive's own provider transport; a bundle without one is refused below.
+                    transport: { kind: 'http', endpoint: directoryBase() },
+                    accept: (bundle) => wrongBundle(id, undefined, bundle),
+                    record: !isCloudRole(),
+                });
+            }
+            catch (error) {
+                logInvalid(id, undefined, error);
+                const refused = new ProviderError('not_found', `provider "${id}" served an invalid bundle: ${error instanceof Error ? error.message : String(error)}`, { param: 'provider' });
+                logged.add(refused);
+                throw refused;
+            }
+            // The bundle is installed now. A sidecar write failure is not an invalid archive; the installed bundle remains usable.
+            if (isCloudRole())
+                await recordEtag(id, fetched.etag);
+            await reconcileProviderDocs(id);
+            emitEvent({ level: 'info', event: 'daemon.providers.bundle_installed', fields: { provider: id, major: installedManifest(id)?.provider.major, version, replaced: present, ...(fetched.etag !== undefined ? { etag: fetched.etag } : {}) } });
+            installAttempts.delete(installKey(id));
+            return present ? 'updated' : 'installed';
+        }, {
+            timeoutMs: SWAP_WAIT_MS,
+            timeoutError: () => new ProviderError('provider_unavailable', `timed out waiting for another process replacing plugin "${id}"`),
+        });
+    }
+    catch (error) {
+        if (installedManifest(id) === undefined)
+            installAttempts.set(installKey(id), { status: 'install_failed', error: publicInstallCause(error) });
+        if (error instanceof ProviderError)
+            throw error;
+        emitEvent({ level: 'error', event: 'daemon.providers.bundle_install_failed', fields: { provider: id }, error });
+        throw unavailableProviderError(id);
+    }
+}
+/** Install the provider's newest major when it is absent (D3-CALL-5); an
+ *  installed one is left as is. Throws like `refreshProviderBundle`. */
+export async function ensureProviderBundle(id) {
+    assertId(id);
+    if (installedManifest(id) !== undefined)
+        return;
+    await refreshInstalled(id, false, true);
+}
+/**
+ * Bring a provider's bundle in step with the directory. `conditional`
+ * (grant sync, D3-INS-2) sends the stored ETag; unconditional (a
+ * `manifest_stale` answer, D3-ERR-5) asks for the archive outright. With
+ * `version`, the pinned major's cache is refetched instead.
+ */
+export async function refreshProviderBundle(id, options) {
+    assertId(id);
+    if (options.version !== undefined && installedManifest(id)?.provider.major !== options.version) {
+        return refreshPinned(id, options.version, options.conditional);
+    }
+    return refreshInstalled(id, options.conditional);
+}
+// ── Pinned majors (cached) ───────────────────────────────────────────────────
+async function validateArchive(id, major, raw) {
+    const { validatePluginArchive } = await pluginManage();
+    const result = await validatePluginArchive(raw);
+    if (result.bundle === undefined)
+        throw new BundleInvalid(`provider "${id}" major ${major} bundle is invalid: ${result.issues.map((i) => i.message).join('; ')}`, result.issues);
+    const wrong = wrongBundle(id, major, result.bundle);
+    if (wrong !== undefined)
+        throw new BundleInvalid(`provider "${id}" major ${major} bundle is invalid: ${wrong}`, []);
+    if (result.bundle.transport === undefined)
+        throw new BundleInvalid(`provider "${id}" major ${major} bundle declares no transport`, []);
+    return result.bundle;
+}
+function retire(dir) {
+    ensureDir(dir);
+    atomicWriteText(join(dir, 'retired'), `${new Date().toISOString()}\n`);
+    rmSync(join(dir, 'bundle.tar'), { force: true });
+    rmSync(join(dir, 'etag'), { force: true });
+}
+function retiredError(id, major) {
+    return new ProviderError('provider_version_retired', `provider "${id}" major ${major} is retired`, { param: 'version' });
+}
+/** Fetch a pinned major into its cache. A 410 leaves a `retired` marker; an
+ *  invalid archive keeps whatever was cached. */
+async function refreshPinned(id, major, conditional) {
+    const dir = majorDir(id, major);
+    const tar = join(dir, 'bundle.tar');
+    const had = existsSync(tar);
+    const etag = had && conditional && existsSync(join(dir, 'etag')) ? readFileSync(join(dir, 'etag'), 'utf8') : undefined;
+    const fetched = await fetchProviderBundle(id, { version: major, ...(etag !== undefined ? { ifNoneMatch: etag } : {}) });
+    if (fetched.status === 304) {
+        logChecked(id, major, 304, etag, 'unchanged');
+        return 'unchanged';
+    }
+    if (fetched.status === 410) {
+        retire(dir);
+        emitEvent({ level: 'info', event: 'daemon.providers.major_retired', fields: { provider: id, major } });
+        throw retiredError(id, major);
+    }
+    if (fetched.status === 404)
+        throw new ProviderError('not_found', `provider "${id}" never served major ${major}`, { param: 'version' });
+    if (fetched.status === 'failed')
+        throw new ProviderError('provider_unavailable', `provider "${id}" major ${major} bundle fetch failed: ${fetched.message}`, { cause: fetched.cause });
+    try {
+        await validateArchive(id, major, fetched.raw);
+    }
+    catch (error) {
+        logInvalid(id, major, error);
+        const refused = new ProviderError(had ? 'provider_unavailable' : 'not_found', error instanceof Error ? error.message : String(error), { param: 'version' });
+        logged.add(refused);
+        throw refused;
+    }
+    ensureDir(dir);
+    rmSync(join(dir, 'retired'), { force: true });
+    const same = had && Buffer.from(fetched.raw).equals(readFileSync(tar));
+    if (!same)
+        atomicWriteText(tar, fetched.raw);
+    if (fetched.etag !== undefined)
+        atomicWriteText(join(dir, 'etag'), fetched.etag);
+    else
+        rmSync(join(dir, 'etag'), { force: true });
+    const outcome = same ? 'unchanged' : had ? 'updated' : 'installed';
+    logChecked(id, major, 200, fetched.etag, outcome);
+    return outcome;
+}
+/** Every cached major, `[id, major]`, retired ones excluded. */
+function cachedMajors() {
+    const out = [];
+    const root = providersRoot();
+    if (!existsSync(root))
+        return out;
+    for (const id of readdirSync(root)) {
+        if (!PROVIDER_ID.test(id))
+            continue;
+        let entries;
+        try {
+            entries = readdirSync(join(root, id));
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            const match = /^v([1-9][0-9]*)$/.exec(entry);
+            if (match && existsSync(join(root, id, entry, 'bundle.tar')))
+                out.push([id, Number(match[1])]);
+        }
+    }
+    return out;
+}
+// ── Resolution (R4, R8) ──────────────────────────────────────────────────────
+function readCommands(raw) {
+    const validation = validateCommandManifest(raw, { transport: 'http', reservedCoreNames: new Set() });
+    if (validation.manifest === undefined)
+        throw new ProviderError('not_found', 'the provider bundle\'s commands.json no longer validates');
+    return validation.manifest;
+}
+/** Validated pinned archives, keyed `<id>/<major>` and stamped with the cached
+ *  tar's mtime and size, so a pinned call validates the tar once per write. */
+const pinnedCache = new Map();
+/** Validated installed `commands.json`, per provider, stamped with the file's
+ *  inode, mtime and size. An install or update stages a new directory and
+ *  swaps it in, so the stamp changes on every replacement; between them the
+ *  file is immutable and a large catalog (Integrations: ~9 MB) is parsed and
+ *  validated once instead of on every tool listing and call. */
+const installedCache = new Map();
+function installedCommands(id, file) {
+    const stat = statSync(file);
+    const stamp = `${stat.ino}:${stat.mtimeMs}:${stat.size}`;
+    const cached = installedCache.get(id);
+    if (cached?.stamp === stamp)
+        return cached.commands;
+    const commands = readCommands(JSON.parse(readFileSync(file, 'utf8')));
+    installedCache.set(id, { stamp, commands });
+    return commands;
+}
+/**
+ * The major a call runs against (D3-VER-1, D3-VER-3). No `version`: the
+ * installed newest major (`not_found` when none is installed — call
+ * `ensureProviderBundle` first). `version: N`: the installed bundle when it is
+ * major N, else major N's cached archive, fetched on first use; a retired
+ * major is `provider_version_retired` with no fetch, one never served is
+ * `not_found`.
+ */
+export async function resolveProviderBundle(id, version) {
+    assertId(id);
+    const installed = installedManifest(id);
+    if (version === undefined || installed?.provider.major === version) {
+        if (installed === undefined)
+            throw new ProviderError('not_found', `provider "${id}" has no installed bundle`, { param: 'provider' });
+        const root = pluginRoot(id);
+        const commands = installedCommands(id, join(root, 'commands.json'));
+        return { id, major: installed.provider.major, provider: installed.provider, commands, transport: installed.transport, source: 'installed', root };
+    }
+    if (!Number.isInteger(version) || version < 1)
+        throw new ProviderError('invalid_request', 'version must be an integer of at least 1', { param: 'version' });
+    const dir = majorDir(id, version);
+    if (existsSync(join(dir, 'retired')))
+        throw retiredError(id, version);
+    const tar = join(dir, 'bundle.tar');
+    if (!existsSync(tar))
+        await refreshPinned(id, version, false);
+    const key = `${id}/${version}`;
+    const stat = statSync(tar);
+    const stamp = `${stat.mtimeMs}:${stat.size}`;
+    let bundle = pinnedCache.get(key)?.stamp === stamp ? pinnedCache.get(key).bundle : undefined;
+    if (bundle === undefined) {
+        try {
+            bundle = await validateArchive(id, version, new Uint8Array(readFileSync(tar)));
+        }
+        catch (error) {
+            logInvalid(id, version, error);
+            throw new ProviderError('not_found', `provider "${id}" has no valid bundle for major ${version}`, { param: 'version' });
+        }
+        pinnedCache.set(key, { stamp, bundle });
+    }
+    return { id, major: version, provider: bundle.provider, commands: bundle.commands,
+        transport: bundle.transport.kind === 'machine' ? { kind: 'machine' } : { kind: 'http', endpoint: bundle.transport.endpoint }, source: 'pinned' };
+}
+let running = null;
+/** Longer than a swap-lock wait or one directory fetch, but not a deadline: a slow pass keeps running. */
+const PASS_STALLED_MS = 4 * 60_000;
+function enter(pass, stage) {
+    pass.stage = stage;
+    pass.stageAt = Date.now();
+}
+/** Whether the plugin at `id` is the directory's provider bundle: installed by
+ *  this module, so its recorded bundle URL is the directory's for this id. A
+ *  provider plugin a person installed from a path, git or marketplace has no
+ *  such record and is theirs. */
+function isDirectoryBundle(manifest, id) {
+    return manifest?.provider?.id === id && manifest.bundle?.endpoint === `${directoryBase()}/providers/${encodeURIComponent(id)}/plugin`;
+}
+/** The active-grant source for provider installation on this runtime. */
+async function bundleGrants() {
+    // `localGrants` asks whether this is an unsandboxed single-person Mac; that question reads a person's config and is meaningless
+    // outside a cloud request. The cloud mirror already contains the deployment's grants for every person.
+    return isCloudRole() ? allGrants() : localGrants();
+}
+/** Whether an active grant names this provider right now. */
+async function grantNames(id) {
+    return providerIdsFromGrants(await bundleGrants()).includes(id);
+}
+/** Remove one installed directory provider bundle and its cached pinned majors. */
+async function uninstallProvider(id) {
+    await withExclusiveDirectoryLockAsync(bundleSwapLockPath(userScopeRoot(), id), async () => {
+        // Re-read under the lock: the grants may have changed while this pass fetched
+        // other bundles, and only the directory's own bundle is ours to remove.
+        if (await grantNames(id) || !isDirectoryBundle(readPluginManifest(pluginRoot(id)), id))
+            return;
+        rmSync(pluginRoot(id), { recursive: true, force: true });
+        if (isCloudRole())
+            rmSync(etagFile(id), { force: true });
+        else {
+            await updateConfig('user', (cfg) => { delete cfg.plugins[id]; });
+            await updateState('user', (state) => { delete state.plugins[id]; });
+        }
+        rmSync(join(providersRoot(), id), { recursive: true, force: true });
+        installedCache.delete(id);
+        installAttempts.delete(installKey(id));
+        for (const key of [...pinnedCache.keys()])
+            if (key.startsWith(`${id}/`))
+                pinnedCache.delete(key);
+        await reconcileProviderDocs(id);
+        emitEvent({ level: 'info', event: 'daemon.providers.bundle_uninstalled', fields: { provider: id } });
+    }, {
+        timeoutMs: SWAP_WAIT_MS,
+        timeoutError: () => new ProviderError('provider_unavailable', `timed out waiting for another process replacing plugin "${id}"`),
+    });
+}
+/** Remove installed directory provider bundles that no active grant names any
+ *  more (the person disconnected the provider, or the directory stopped
+ *  resolving its groups for them). Skipped while no grant is active: an empty
+ *  mirror means a runtime that is signed out or not yet synced, not a
+ *  disconnect. Never touches a plugin that is not the directory's bundle.
+ *  On a cloud role the grant mirror holds every person's grants, so a shared
+ *  bundle goes only when no active grant of any person names it. */
+async function uninstallDisconnected() {
+    if ((await bundleGrants()).every((grant) => grant.status !== 'active'))
+        return;
+    for (const plugin of installedProviderPlugins()) {
+        if (plugin.manifest.provider === undefined || await grantNames(plugin.name))
+            continue;
+        try {
+            await uninstallProvider(plugin.name);
+        }
+        catch (error) {
+            emitEvent({ level: 'error', event: 'daemon.providers.bundle_uninstall_failed', fields: { provider: plugin.name }, error });
+        }
+    }
+}
+async function syncOnce(pass) {
+    if (!directoryIssuer())
+        return;
+    enter(pass, 'reading grants');
+    const wanted = providerIdsFromGrants(await bundleGrants());
+    for (const id of wanted) {
+        enter(pass, `refreshing installed bundle ${id}`);
+        try {
+            await refreshInstalled(id, true);
+        }
+        catch (error) {
+            if (!(error instanceof Object && logged.has(error)))
+                logFailure(id, undefined, error);
+        }
+    }
+    enter(pass, 'uninstalling disconnected bundles');
+    await uninstallDisconnected();
+    for (const [id, major] of cachedMajors()) {
+        enter(pass, `refreshing pinned bundle ${id} v${major}`);
+        try {
+            await refreshPinned(id, major, true);
+        }
+        catch (error) {
+            if (error instanceof ProviderError && error.code === 'provider_version_retired')
+                continue;
+            if (error instanceof Object && logged.has(error))
+                continue;
+            logFailure(id, major, error);
+        }
+    }
+}
+/**
+ * After a grant sync (D3-INS-1, D3-INS-2, D3-INS-4, D3-VER-2): install every
+ * provider an active grant names that is absent, refresh each installed one
+ * conditionally, then revalidate every cached pinned major. Never throws;
+ * each failure is logged and leaves the previous bundle. Syncs that arrive
+ * while one runs coalesce into one more pass.
+ */
+export function syncProviderBundles() {
+    if (running !== null) {
+        running.rerun = true;
+        const stalledMs = Date.now() - running.stageAt;
+        if (stalledMs >= PASS_STALLED_MS) {
+            emitEvent({ level: 'error', event: 'daemon.providers.sync_stalled', fields: { stage: running.stage, stalled_ms: stalledMs } });
+        }
+        return running.promise;
+    }
+    const pass = { promise: Promise.resolve(), stage: 'starting', stageAt: Date.now(), rerun: false };
+    running = pass;
+    pass.promise = (async () => {
+        try {
+            do {
+                pass.rerun = false;
+                await syncOnce(pass);
+            } while (pass.rerun);
+        }
+        finally {
+            running = null;
+        }
+    })();
+    return pass.promise;
+}