@ateam-ai-mobile/plugin-runtime 0.1.5 → 0.1.8

package/src/bundles/bundleManager.ts

@@ -6,7 +6,7 @@
  * the BundleStorage adapter (in-memory by default; @ateam-ai-mobile/expo provides disk).
  *
  * Usage:
- *   const component = await bundleManager.load(pluginId, bundleUrl, version, hash);
+ *   const component = await bundleManager.load(pluginId, bundleUrl, version, hash, grants);
  *   // component = { id, type, Component, ... } (RegisteredUIPlugin)
  */
 import React from 'react';
@@ -15,7 +15,7 @@ import {
   useContext, useReducer, useLayoutEffect, useImperativeHandle, useDebugValue,
 } from 'react';
 import * as ReactNative from 'react-native';
-import { apiFetchRaw } from '@ateam-ai-mobile/core';
+import { apiFetchRaw, getTenant } from '@ateam-ai-mobile/core';
 import * as PluginSDKModule from '../sdk';
 import SurfaceDrawer from '../surfaces/SurfaceDrawer';
 import SurfaceCard from '../surfaces/SurfaceCard';
@@ -24,7 +24,10 @@ import { useSurfaceStore } from '../registry/store';
 import SurfaceDispatcher from '../registry/SurfaceDispatcher';
 import { resolveBundleModule } from '../host';
 import { sha256Hex } from '../utils/sha256';
-import { getBundleStorage, type BundleCacheEntry } from './storage';
+import { assertBundleIntegrity } from './integrity';
+import { getBundleStorage, type BundleCacheEntry, type TrustedToolDeclaration } from './storage';
+import { registerDeviceTools, unregisterDeviceTools, listDeviceTools } from '../tools/registry';
+import type { PluginGrants } from '../pluginRuntime';
 import type { RegisteredUIPlugin } from '../sdk/types';
 
 // ── Require shim ─────────────────────────────────────────────
@@ -88,15 +91,147 @@ const requireShim = (name: string) => {
 
 const CACHE_TTL = 7 * 24 * 60 * 60 * 1000; // 7 days
 
+// What findPluginExport looks for: a renderable plugin, or one with a `tools` section.
+const hasComponent = (val: any): boolean =>
+  !!val && typeof val === 'object' && typeof val.Component === 'function';
+const hasTools = (val: any): boolean =>
+  !!val && typeof val === 'object' && Array.isArray(val.tools) && val.tools.length > 0;
+
 // ── BundleManager singleton ──────────────────────────────────
 
+/** Where the bytes currently running came from. */
+export type LoadedBundleSource = 'download' | 'disk-cache' | 'memory';
+
+/**
+ * Provenance of one loaded bundle — what is RUNNING, not what was requested.
+ *
+ * `hash` is the sha256 of the evaluated bytes. `expected` is the hash the
+ * server's manifest advertised for that url. Equal means the phone is running
+ * the build the server currently describes; different means it is not, and the
+ * pair says so without needing a rebuild, a reinstall or a guess.
+ */
+export interface LoadedBundleInfo {
+  bundleUrl: string;
+  version: string;
+  /** sha256 (hex, lowercase) of the bytes that were evaluated. */
+  hash: string | null;
+  /** sha256 the server advertised for this url at load time, if any. */
+  expected: string | null;
+  source: LoadedBundleSource;
+  tenant: string | null;
+  loadedAt: number;
+}
+
 class BundleManager {
-  /** In-memory module cache: bundleUrl → evaluated module.exports */
+  /** In-memory module cache: bundleUrl → evaluated module.exports. Holds ONE
+   *  tenant's modules at a time — the tenant boundary is `cacheTenant` /
+   *  `requireTenant()`, NOT the key. */
   private modules = new Map<string, any>();
+  /** What is actually RUNNING, keyed by bundleUrl (for the current tenant). See
+   *  getLoadedBundles(). */
+  private provenance = new Map<string, LoadedBundleInfo>();
 
   /** In-flight download deduplication: bundleUrl → Promise */
   private inflight = new Map<string, Promise<any>>();
 
+  /**
+   * The tenant the in-memory caches (modules / provenance / inflight) currently
+   * belong to. This is the tenant BOUNDARY for evaluated code.
+   *
+   * A bundleUrl resolves PER-TENANT on the server — one url, different bytes for
+   * different tenants — so a memory hit keyed on url alone would hand tenant B
+   * the module tenant A already evaluated and ran. PR #9 scoped the DISK cache
+   * (per-tenant index + hash gate); the in-memory map was left url-keyed. This
+   * closes that: the caches only ever hold ONE tenant's modules, and a switch
+   * drops them before anything is served.
+   */
+  private cacheTenant: string | null = null;
+
+  /**
+   * pluginIds this manager registered device tools for. A tenant switch drops
+   * the in-memory modules AND unregisters these, so the incoming tenant's bundle
+   * re-registers into a clean registry instead of being refused as a duplicate
+   * of the previous tenant's tools.
+   */
+  private registeredToolPluginIds = new Set<string>();
+
+  /** bundleUrl → the trusted declaration last recorded on its disk-cache entry
+   *  this session, so a memory hit with unchanged grants skips the index I/O. */
+  private recordedDeclarations = new Map<string, string>();
+
+  /**
+   * Enforce the in-memory tenant boundary. Call at the top of every public load
+   * path, BEFORE any cache read.
+   *
+   * FAIL CLOSED: without a tenant identity we cannot prove a cached module is
+   * this session's, so we drop everything and refuse rather than risk serving
+   * one tenant's evaluated code to another. On a tenant change we drop the
+   * previous tenant's modules (and their tool registrations) before proceeding.
+   */
+  /**
+   * Monotonic load generation. Bumped on every in-memory wipe (a tenant change,
+   * fail-closed, or clearAll). A load captures it at ENTRY; a completion whose
+   * generation no longer matches is stale and is discarded before it can commit.
+   * This closes the async race the sequential guard cannot: tenant A's in-flight
+   * loadModule can resolve AFTER a switch to B — clearing `inflight` does not
+   * cancel that Promise — and would otherwise write A's module / provenance /
+   * device tools into the singleton now marked cacheTenant=B.
+   */
+  private epoch = 0;
+
+  private requireTenant(): string {
+    const tenant = getTenant();
+    if (!tenant) {
+      this.dropInMemory();
+      this.cacheTenant = null;
+      throw new Error(
+        '[BundleManager] refusing to load a tenant-scoped bundle without a tenant identity (fail closed)',
+      );
+    }
+    if (tenant !== this.cacheTenant) {
+      // First load, or a tenant switch: the caches hold the previous tenant's
+      // evaluated modules — none of it may cross the boundary.
+      this.dropInMemory();
+      this.cacheTenant = tenant;
+    }
+    return tenant;
+  }
+
+  /** Drop every in-memory cache and unregister the device tools this manager
+   *  registered — used on a tenant change and by clearAll(). */
+  private dropInMemory(): void {
+    for (const pluginId of this.registeredToolPluginIds) {
+      try { unregisterDeviceTools(pluginId); } catch { /* ignore */ }
+    }
+    this.registeredToolPluginIds.clear();
+    this.recordedDeclarations.clear();
+    this.modules.clear();
+    this.provenance.clear();
+    this.inflight.clear();
+    // Bump the generation: any load that started before this wipe is now stale
+    // and must not commit its results (see epoch / stale check in loadModule).
+    this.epoch++;
+  }
+
+  /** True once the boundary has moved since a load captured `epoch` — i.e. a
+   *  tenant switch (or wipe) happened while this load was in flight. Its results
+   *  belong to a tenant that is no longer current and must be discarded. */
+  private isStale(epoch: number, tenant: string): boolean {
+    return this.epoch !== epoch || getTenant() !== tenant;
+  }
+
+  /** Record a memory serve: the running bytes are the already-evaluated module,
+   *  and `expected` is refreshed from the manifest hash the caller JUST passed —
+   *  so after a redeploy the record reads hash !== expected (STALE) instead of
+   *  the old in-sync pair. The ONE place both memory paths (load()'s early return
+   *  and loadModule's) record reuse. No-op if nothing was recorded yet. */
+  private markMemoryHit(bundleUrl: string, expectedHash?: string): void {
+    const prev = this.provenance.get(bundleUrl);
+    if (prev) {
+      this.provenance.set(bundleUrl, { ...prev, source: 'memory', expected: expectedHash?.toLowerCase() ?? prev.expected });
+    }
+  }
+
   // ── Public API ──────────────────────────────────────────────
 
   /**
@@ -107,29 +242,68 @@ class BundleManager {
    * provided for any bundle the user has not previously verified — without
    * it, a tampered bundle is `eval`'d as JS with full RN runtime + every
    * native capability the manifest declares.
+   *
+   * `grants` is what the MANIFEST grants this plugin (resolvePluginGrants) — the
+   * only authority its device tools are registered under. Omitted (e.g. a
+   * prewarm from the slim plugin list) → the bundle is loaded but its tools are
+   * NOT registered: without the manifest there is nothing trusted to gate them
+   * on, and registering with nothing would downgrade a registration the
+   * manifest-driven tool loader already made.
    */
   async load(
     pluginId: string,
     bundleUrl: string,
     version: string,
     expectedHash?: string,
+    grants?: PluginGrants,
   ): Promise<RegisteredUIPlugin> {
+    // Tenant boundary FIRST — fail closed without a tenant, drop the previous
+    // tenant's modules on a switch, and CAPTURE the tenant + generation at entry
+    // so a switch during the async load is caught before any result is used.
+    const tenant = this.requireTenant();
+    const epoch = this.epoch;
+
     // 1. In-memory cache — instant
     const cached = this.getComponentFromMemory(pluginId, bundleUrl);
-    if (cached) return cached;
+    if (cached) {
+      // Record the reuse. load() returns HERE, before loadModule, so without
+      // this the provenance would freeze on the first download/disk source and
+      // getLoadedBundles() would never report a memory serve. (loadModule's
+      // own memory branch covers the loadTools path, which has no early return.)
+      this.markMemoryHit(bundleUrl, expectedHash);
+      if (grants) await this.commitTools(pluginId, bundleUrl, grants, tenant, epoch);
+      return cached;
+    }
 
     // 2. Deduplicate in-flight downloads for same bundleUrl
     let modulePromise = this.inflight.get(bundleUrl);
     if (!modulePromise) {
-      modulePromise = this.loadModule(bundleUrl, version, expectedHash);
-      this.inflight.set(bundleUrl, modulePromise);
+      const promise = this.loadModule(bundleUrl, version, expectedHash, tenant, epoch);
+      modulePromise = promise;
+      this.inflight.set(bundleUrl, promise);
       // Swallow rejection on the cleanup chain — the original `await` below
-      // still surfaces the error to the caller.
-      modulePromise.catch(() => {}).finally(() => this.inflight.delete(bundleUrl));
+      // still surfaces the error to the caller. Delete ONLY our own entry: a
+      // tenant switch clears `inflight` and the incoming tenant installs a NEW
+      // promise for the same url, so an unconditional delete here would evict
+      // B's live entry when stale A finally settles — breaking dedup and letting
+      // a duplicate B load start.
+      promise.catch(() => {}).finally(() => {
+        if (this.inflight.get(bundleUrl) === promise) this.inflight.delete(bundleUrl);
+      });
     }
 
     await modulePromise;
 
+    // The switch could have landed while we awaited. Even if another tenant has
+    // since populated modules[bundleUrl], this load must not return that code.
+    if (this.isStale(epoch, tenant)) {
+      throw new Error('[BundleManager] tenant changed while loading — discarding (fail closed)');
+    }
+
+    // Tools register at LOAD, not at mount — and for a UI bundle too, so a hybrid
+    // plugin's tools are callable whether or not its component is found.
+    if (grants) await this.commitTools(pluginId, bundleUrl, grants, tenant, epoch);
+
     // 3. Extract component for this specific pluginId
     const component = this.getComponentFromMemory(pluginId, bundleUrl);
     if (!component) {
@@ -142,6 +316,61 @@ class BundleManager {
     return component;
   }
 
+  /**
+   * Load a bundle for its `tools/` section only — no UI required.
+   *
+   * Same download, same integrity check, same evaluation as `load()`; the only
+   * difference is that a bundle exporting tools and no `Component` is a success
+   * here rather than "no component found". Returns the tool names registered.
+   *
+   * `grants` is REQUIRED: the tools are registered under `pluginId` with exactly
+   * what the manifest grants (see load()), never what the bundle claims.
+   */
+  async loadTools(
+    pluginId: string,
+    bundleUrl: string,
+    version: string,
+    expectedHash: string | undefined,
+    grants: PluginGrants,
+  ): Promise<string[]> {
+    if (!grants) {
+      throw new Error(`[BundleManager] loadTools(${pluginId}) needs the manifest's grants (resolvePluginGrants) — refusing to register tools on the bundle's own claim`);
+    }
+    // Tenant boundary FIRST — same fail-closed / drop-on-switch as load(), and
+    // capture the tenant + generation for the stale check after the async load.
+    const tenant = this.requireTenant();
+    const epoch = this.epoch;
+    let modulePromise = this.inflight.get(bundleUrl);
+    if (!modulePromise) {
+      const promise = this.loadModule(bundleUrl, version, expectedHash, tenant, epoch);
+      modulePromise = promise;
+      this.inflight.set(bundleUrl, promise);
+      // Delete ONLY our own entry — see load() for why an unconditional delete
+      // lets stale A evict B's live inflight promise across a tenant switch.
+      promise.catch(() => {}).finally(() => {
+        if (this.inflight.get(bundleUrl) === promise) this.inflight.delete(bundleUrl);
+      });
+    }
+    await modulePromise;
+
+    if (this.isStale(epoch, tenant)) {
+      throw new Error('[BundleManager] tenant changed while loading tools — discarding (fail closed)');
+    }
+    await this.commitTools(pluginId, bundleUrl, grants, tenant, epoch);
+
+    const names = listDeviceTools()
+      .filter(t => t.pluginId === pluginId)
+      .map(t => t.name);
+
+    if (names.length === 0) {
+      console.warn(
+        `[BundleManager] ${pluginId}: bundle loaded from ${bundleUrl} but registered no tools. ` +
+        `Available exports: ${this.describeModule(this.modules.get(bundleUrl))}`,
+      );
+    }
+    return names;
+  }
+
   /**
    * Prewarm: load every plugin bundle in the background after app boot, so a
    * later open is instant (in-memory hit) instead of round-tripping the
@@ -153,6 +382,8 @@ class BundleManager {
     bundleUrl: string;
     version: string;
     bundleHash?: string;
+    /** The manifest's grants, when the caller has the manifest (see load()). */
+    grants?: PluginGrants;
   }>): Promise<void> {
     const queue = [...items];
     const concurrency = Math.min(3, queue.length);
@@ -165,7 +396,7 @@ class BundleManager {
         const it = queue.shift();
         if (!it) return;
         try {
-          await this.load(it.pluginId, it.bundleUrl, it.version, it.bundleHash);
+          await this.load(it.pluginId, it.bundleUrl, it.version, it.bundleHash, it.grants);
           okCount++;
         } catch (err) {
           failCount++;
@@ -183,7 +414,10 @@ class BundleManager {
    * Clear all caches (in-memory + storage).
    */
   async clearAll(): Promise<void> {
-    this.modules.clear();
+    // Full reset — in-memory modules + provenance + inflight + the device tools
+    // this manager registered, then the tenant marker and the disk storage.
+    this.dropInMemory();
+    this.cacheTenant = null;
     try {
       await getBundleStorage().clearAll();
     } catch (err) {
@@ -208,11 +442,42 @@ class BundleManager {
     }
   }
 
+  /**
+   * What every loaded bundle IS, right now: the sha256 of the bytes running,
+   * the hash the server advertised, and where they came from.
+   *
+   * Deliberately not filtered or prettified — this is the raw answer to "did my
+   * redeploy reach the phone?", and it is comparable directly against the
+   * manifest `bundleHash` and the server's X-Bundle-SHA256 header.
+   */
+  getLoadedBundles(): LoadedBundleInfo[] {
+    return [...this.provenance.values()];
+  }
+
   // ── Private: module loading pipeline ────────────────────────
 
-  private async loadModule(bundleUrl: string, version: string, expectedHash?: string): Promise<void> {
-    // Already in memory?
-    if (this.modules.has(bundleUrl)) return;
+  private async loadModule(
+    bundleUrl: string,
+    version: string,
+    expectedHash: string | undefined,
+    // The tenant + generation captured at the caller's ENTRY. Every step that
+    // commits into the singleton (disk write, evaluate, module/provenance set,
+    // tool registration) is gated on these still being current — a switch to
+    // another tenant during the download must NOT let this load's results land.
+    expectedTenant: string,
+    expectedEpoch: number,
+  ): Promise<void> {
+    // The boundary may already have moved before we even start (a switch landed
+    // between requireTenant() and here). Fail closed rather than proceed.
+    if (this.isStale(expectedEpoch, expectedTenant)) {
+      throw new Error('[BundleManager] tenant changed before load started — discarding (fail closed)');
+    }
+    // Already in memory? Then the running bytes are whatever this session
+    // already evaluated — record the reuse so provenance never goes silent.
+    if (this.modules.has(bundleUrl)) {
+      this.markMemoryHit(bundleUrl, expectedHash);
+      return;
+    }
 
     const storage = getBundleStorage();
     const index = await storage.loadIndex();
@@ -220,15 +485,22 @@ class BundleManager {
 
     // Check disk cache. A cache hit is only valid when the cached SHA-256
     // matches the manifest hash exactly — never trust a cached bundle
-    // without proof.
+    // without proof. The file is read via entry.localPath (the content-addressed
+    // path recorded at write time), never reconstructed from url+version, so a
+    // hit follows the index straight to the right bytes.
     let content: string | null = null;
+    // The SHA-256 that gate-kept THIS content (the manifest hash for a cache hit,
+    // the freshly-verified download hash otherwise) — re-checked inline at the
+    // eval so a tampered cache file cannot run (see evaluate()).
+    let verifiedHash: string | null = null;
+    let servedFrom: LoadedBundleSource = 'download';
     for (const entry of Object.values(index)) {
       if (entry.bundleUrl === bundleUrl && entry.version === version) {
         const age = Date.now() - entry.timestamp;
         const hashOk = expectedLc && entry.bundleHash && entry.bundleHash.toLowerCase() === expectedLc;
         if (age < CACHE_TTL && hashOk) {
           content = await storage.readBundle(entry.localPath);
-          if (content) break;
+          if (content) { verifiedHash = entry.bundleHash!.toLowerCase(); servedFrom = 'disk-cache'; break; }
         }
       }
     }
@@ -237,26 +509,191 @@ class BundleManager {
     if (!content) {
       const downloaded = await this.download(bundleUrl, expectedLc);
       content = downloaded.content;
-      // Save with verified hash
-      const safeName = bundleUrl.replace(/[^a-zA-Z0-9]/g, '_').slice(-80);
+      verifiedHash = downloaded.sha256.toLowerCase();
+      // The download is the long await where a tenant switch is most likely to
+      // land. If it did, discard NOW — before we stamp a disk-cache entry with
+      // the (now wrong) current tenant.
+      if (this.isStale(expectedEpoch, expectedTenant)) {
+        throw new Error('[BundleManager] tenant changed during download — discarding (fail closed)');
+      }
+      // Save with verified hash. CONTENT-ADDRESS the file by its own sha256, NOT
+      // by url+version: a bundleUrl+version pair is identical across tenants but
+      // resolves to DIFFERENT bytes per tenant, so a url+version filename is
+      // SHARED between them. A stale tenant-A writeBundle that completes after a
+      // switch to B would then clobber B's cached file bytes at that shared path.
+      // Keying the file by verifiedHash gives A's bytes and B's bytes distinct
+      // paths that can never collide (identical bytes dedup to one file, which is
+      // correct). The index entry below — keyed by url, stamped with the captured
+      // tenant + hash + this localPath — is unchanged and stays authoritative.
       try {
-        const localPath = await storage.writeBundle(`${safeName}@${version}.js`, content);
-        index[bundleUrl] = {
-          localPath,
-          version,
-          timestamp: Date.now(),
-          bundleUrl,
-          bundleHash: downloaded.sha256,
-        } satisfies BundleCacheEntry;
-        await storage.saveIndex(index);
+        const localPath = await storage.writeBundle(`${verifiedHash}.js`, content);
+        // The index entry is the AUTHORITATIVE disk-cache commit: loadFromDiskCache
+        // reads the index (a loose file with no entry is never selected), and it
+        // trusts the entry's `tenant` stamp as the authorization boundary while
+        // passing the entry's OWN hash (an integrity check that cannot fail). So:
+        //  (a) stamp ownership from the CAPTURED tenant, never live getTenant() —
+        //      writeBundle awaited, and a switch here would otherwise label A's
+        //      bytes as B, which the recovery path would later re-run under B;
+        //  (b) do not publish the entry at all if the tenant/generation moved
+        //      while we awaited — fail closed, leaving only an orphan file.
+        if (!this.isStale(expectedEpoch, expectedTenant)) {
+          index[bundleUrl] = {
+            localPath,
+            version,
+            timestamp: Date.now(),
+            bundleUrl,
+            bundleHash: downloaded.sha256,
+            tenant: expectedTenant,
+          } satisfies BundleCacheEntry;
+          await storage.saveIndex(index);
+        }
       } catch (err) {
         console.warn('[BundleManager] Cache write error:', err);
       }
     }
 
-    // Evaluate
-    const mod = this.evaluate(content, bundleUrl);
+    // FINAL boundary check before anything commits into the singleton. This is
+    // the one that also covers the disk-cache-hit path (which never entered the
+    // download branch above). Everything after this line — evaluate, module set,
+    // provenance set, tool registration — writes tenant-scoped state; if the
+    // tenant moved while we awaited, none of it may land (fail closed).
+    if (this.isStale(expectedEpoch, expectedTenant)) {
+      throw new Error('[BundleManager] tenant changed while loading — discarding stale bundle before eval (fail closed)');
+    }
+
+    // Evaluate — the eval re-hashes `content` against verifiedHash first.
+    const mod = this.evaluate(content, bundleUrl, verifiedHash);
     this.modules.set(bundleUrl, mod);
+
+    // Record WHAT IS RUNNING. Until this existed, nothing on the device or the
+    // server could answer "which build is the phone actually executing?" — so a
+    // redeploy that failed to arrive was indistinguishable from one that did,
+    // and the only diagnosis available was to reinstall and guess.
+    // `expected` is the server's advertised manifest hash: when it differs from
+    // `hash`, the phone is running something the server did not just describe.
+    this.provenance.set(bundleUrl, {
+      bundleUrl,
+      version,
+      hash: verifiedHash,
+      expected: expectedLc,
+      source: servedFrom,
+      // The captured owner — same rule as the disk stamp. The final stale check
+      // above guarantees getTenant() === expectedTenant here, but binding it to
+      // the captured value keeps the ownership record impossible to mislabel.
+      tenant: expectedTenant,
+      loadedAt: Date.now(),
+    });
+    console.log(
+      `[BundleManager] RUNNING ${bundleUrl} v${version} sha=${(verifiedHash || 'none').slice(0, 12)} ` +
+      `(${servedFrom}${expectedLc && verifiedHash && expectedLc !== verifiedHash ? `, EXPECTED ${expectedLc.slice(0, 12)} — STALE` : ''})`,
+    );
+  }
+
+  /**
+   * Register THIS plugin's device tools under the TRUSTED declaration, then
+   * record that declaration on the disk-cache entry. Runs on every trusted load
+   * — memory hit included — so the grants in force are always the latest the
+   * manifest gave (a revoked grant stops applying on the next load, not the next
+   * app start). Callers run it only after their stale check.
+   */
+  private async commitTools(
+    pluginId: string,
+    bundleUrl: string,
+    grants: PluginGrants,
+    tenant: string,
+    epoch: number,
+  ): Promise<void> {
+    const declaration: TrustedToolDeclaration = {
+      pluginId,
+      capabilities: grants.capabilities,
+      stateDomains: grants.stateDomains,
+    };
+    this.registerToolsFromModule(this.modules.get(bundleUrl), declaration);
+    await this.recordTrustedDeclaration(bundleUrl, declaration, tenant, epoch);
+  }
+
+  /**
+   * Put the plugin's own `tools` section in the device tool registry — under the
+   * pluginId and grants the MANIFEST resolved, never the bundle's own `id`,
+   * `capabilities` or `stateDomains`. A bundle is code the manifest authorised
+   * by hash; what it may touch is the manifest's to say, same as its rendered
+   * surface (resolvePluginRuntimeProps). Its own `id` would also let it register
+   * as another plugin — including the host's platform tools, which a same-id
+   * re-registration replaces.
+   *
+   * Only this plugin's export (the same lookup the component uses) is
+   * registered. Another export's tools in the same bundle belong to another
+   * plugin and register when THAT plugin's manifest loads it.
+   */
+  private registerToolsFromModule(mod: any, { pluginId, capabilities, stateDomains }: TrustedToolDeclaration): void {
+    if (!mod) return;
+
+    const own = this.findPluginExport(mod, pluginId, hasTools);
+    const others = Object.keys(mod).filter((k) => hasTools(mod[k]) && mod[k] !== own);
+    if (others.length > 0) {
+      console.warn(
+        `[BundleManager] ${pluginId}: not registering tools from export(s) ${others.join(', ')} — ` +
+        `they are not this plugin's, and only their own manifest can grant them`,
+      );
+    }
+    if (!own) return;
+
+    // The bundle's own declaration grants nothing, but a gap between it and the
+    // manifest is the author's bug — name it, or the tool just reads "not declared".
+    const ungranted = [
+      ...(Array.isArray(own.stateDomains) ? own.stateDomains : []).filter((d: any) => !stateDomains?.includes(d)),
+      ...Object.keys(own.capabilities || {}).filter((k) => own.capabilities[k] === true && !(capabilities as any)?.[k]),
+    ];
+    if (ungranted.length > 0) {
+      console.warn(
+        `[BundleManager] ${pluginId}: bundle declares ${ungranted.join(', ')} but the manifest does not grant it — denied`,
+      );
+    }
+
+    try {
+      registerDeviceTools(pluginId, own.tools, capabilities, stateDomains);
+      // Remember it so a tenant switch (or clearAll) can unregister the OLD
+      // tenant's tools before the incoming tenant re-registers.
+      this.registeredToolPluginIds.add(pluginId);
+    } catch (err) {
+      console.warn(
+        `[BundleManager] tool registration failed for ${pluginId}:`,
+        err instanceof Error ? err.message : String(err),
+      );
+    }
+  }
+
+  /**
+   * Record the trusted declaration on this tenant's disk-cache entry for the
+   * bytes RUNNING — the recovery path (tools/loader loadFromDiskCache) has no
+   * manifest and re-registers with exactly this. Only onto an entry this tenant
+   * owns whose hash is the running hash: the grant was issued for these bytes,
+   * and those are the bytes recovery will evaluate. Best-effort — a lost write
+   * leaves no `trusted`, which recovery treats as fail closed.
+   */
+  private async recordTrustedDeclaration(
+    bundleUrl: string,
+    declaration: TrustedToolDeclaration,
+    tenant: string,
+    epoch: number,
+  ): Promise<void> {
+    const key = JSON.stringify(declaration);
+    if (this.recordedDeclarations.get(bundleUrl) === key) return;
+    try {
+      const storage = getBundleStorage();
+      const index = await storage.loadIndex();
+      const entry = index[bundleUrl];
+      const running = this.provenance.get(bundleUrl)?.hash;
+      if (!entry || entry.tenant !== tenant || !running || entry.bundleHash?.toLowerCase() !== running) return;
+      if (this.isStale(epoch, tenant)) return;
+      if (JSON.stringify(entry.trusted) !== key) {
+        index[bundleUrl] = { ...entry, trusted: declaration };
+        await storage.saveIndex(index);
+      }
+      this.recordedDeclarations.set(bundleUrl, key);
+    } catch (err) {
+      console.warn('[BundleManager] could not record trusted declaration:', err);
+    }
   }
 
   /**
@@ -309,7 +746,22 @@ class BundleManager {
     return { content, sha256: computed };
   }
 
-  private evaluate(content: string, bundleUrl: string): any {
+  private evaluate(content: string, bundleUrl: string, verifiedHash: string | null): any {
+    // R8 SECURITY GATE — mandatory, fail-closed integrity INLINE at the eval, on
+    // the exact bytes about to run. The download path verifies too, but a disk-
+    // cache hit reads a file whose STORED metadata hash matched; it never re-hashes
+    // the actual bytes, so a tampered cache file would execute. Re-hashing here
+    // refuses a missing or mismatched hash whatever path produced `content`.
+    //
+    // NOTE — this is integrity, NOT a sandbox. `new Function` shares this JS
+    // realm; a bundle that passes the hash still runs with full in-app authority
+    // (its only capability gating is the plugin manifest via gatePluginNative).
+    // The hash proves the bytes are the ones the trusted manifest names; it does
+    // not isolate them. Publisher SIGNATURE is deliberately NOT required — the
+    // manifest hash already comes from an authenticated Core call
+    // (docs/decisions/REMOTE_BUNDLE_INTEGRITY.md).
+    assertBundleIntegrity(content, verifiedHash, bundleUrl);
+
     // Strip __toESM wrapping — our shim already provides correct ESM objects.
     // esbuild's __toESM + isNodeMode=1 double-wraps and breaks React 19 hooks.
     let cleaned = content.replace(
@@ -350,44 +802,37 @@ class BundleManager {
 
   // ── Private: component extraction ───────────────────────────
 
+  /** Find a plugin component in a loaded module. */
+  private getComponentFromMemory(pluginId: string, bundleUrl: string): RegisteredUIPlugin | null {
+    return this.findPluginExport(this.modules.get(bundleUrl), pluginId, hasComponent);
+  }
+
   /**
-   * Find a plugin component in a loaded module.
-   * Handles: default export, direct key match, multi-plugin .id match.
+   * Find THIS plugin's export in a loaded module — the one lookup both the
+   * component and the device tools use, so a plugin's UI and its tools always
+   * come from the same export. `accept` says what the caller needs from it.
+   * Handles: direct key match, PascalCase key, default export, multi-plugin .id match.
    */
-  private getComponentFromMemory(pluginId: string, bundleUrl: string): RegisteredUIPlugin | null {
-    const mod = this.modules.get(bundleUrl);
+  private findPluginExport(mod: any, pluginId: string, accept: (val: any) => boolean): any | null {
     if (!mod) return null;
 
     const shortName = pluginId.includes(':') ? pluginId.split(':').pop()! : pluginId;
 
     // 1. Direct key match (full pluginId as key)
-    if (mod[pluginId] && typeof mod[pluginId].Component === 'function') {
-      return mod[pluginId] as RegisteredUIPlugin;
-    }
+    if (accept(mod[pluginId])) return mod[pluginId];
 
     // 2. PascalCase match from shortName (most reliable for combined bundles)
     //    e.g., "memories-panel" → "MemoriesPanel"
     const pascal = shortName.replace(/(^|-)([a-z])/g, (_: string, __: string, c: string) => c.toUpperCase());
-    if (mod[pascal] && typeof mod[pascal] === 'object' && typeof mod[pascal].Component === 'function') {
-      return mod[pascal] as RegisteredUIPlugin;
-    }
+    if (accept(mod[pascal])) return mod[pascal];
 
     // 3. Default export (single-plugin bundles)
-    if (mod.default && typeof mod.default === 'object' && typeof mod.default.Component === 'function') {
-      return mod.default as RegisteredUIPlugin;
-    }
+    if (accept(mod.default)) return mod.default;
 
     // 4. Match by .id field (last resort — can be unreliable in combined bundles)
     for (const key of Object.keys(mod)) {
       const val = mod[key];
-      if (
-        val &&
-        typeof val === 'object' &&
-        val.id === shortName &&
-        typeof val.Component === 'function'
-      ) {
-        return val as RegisteredUIPlugin;
-      }
+      if (val && (val.id === pluginId || val.id === shortName) && accept(val)) return val;
     }
 
     return null;