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

package/dist/loader-5LUVXUY2.mjs

@@ -0,0 +1,9 @@
+import {
+  ensureDeviceToolsLoaded,
+  resetDeviceToolLoader
+} from "./chunk-PKDQLNBL.mjs";
+export {
+  ensureDeviceToolsLoaded,
+  resetDeviceToolLoader
+};
+//# sourceMappingURL=loader-5LUVXUY2.mjs.map

package/dist/loader-5LUVXUY2.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ateam-ai-mobile/plugin-runtime",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "ADAS plugin runtime for React Native hosts — plugin SDK, bundle pipeline with integrity verification, host bridge, surfaces. No Expo dependencies.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -9,7 +9,7 @@
     "build": "tsup"
   },
   "dependencies": {
-    "@ateam-ai-mobile/core": "^0.1.5",
+    "@ateam-ai-mobile/core": "0.1.7",
     "zustand": "^5.0.0"
   },
   "peerDependencies": {

package/src/bundles/bundleManager.ts

@@ -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,9 @@ import { useSurfaceStore } from '../registry/store';
 import SurfaceDispatcher from '../registry/SurfaceDispatcher';
 import { resolveBundleModule } from '../host';
 import { sha256Hex } from '../utils/sha256';
+import { assertBundleIntegrity } from './integrity';
 import { getBundleStorage, type BundleCacheEntry } from './storage';
+import { registerDeviceTools, unregisterDeviceTools, listDeviceTools } from '../tools/registry';
 import type { RegisteredUIPlugin } from '../sdk/types';
 
 // ── Require shim ─────────────────────────────────────────────
@@ -90,13 +92,132 @@ const CACHE_TTL = 7 * 24 * 60 * 60 * 1000; // 7 days
 
 // ── 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>();
+
+  /**
+   * 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.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;
+  }
+
+  /** Flip an existing provenance record to source:'memory' — a later serve of an
+   *  already-evaluated bundle came from the in-memory cache, not a fresh
+   *  download/disk read. No-op if nothing was recorded yet. */
+  private markMemoryHit(bundleUrl: string): void {
+    const prev = this.provenance.get(bundleUrl);
+    if (prev && prev.source !== 'memory') {
+      this.provenance.set(bundleUrl, { ...prev, source: 'memory' });
+    }
+  }
+
   // ── Public API ──────────────────────────────────────────────
 
   /**
@@ -114,22 +235,48 @@ class BundleManager {
     version: string,
     expectedHash?: string,
   ): 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);
+      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)');
+    }
+
     // 3. Extract component for this specific pluginId
     const component = this.getComponentFromMemory(pluginId, bundleUrl);
     if (!component) {
@@ -142,6 +289,53 @@ 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.
+   */
+  async loadTools(
+    pluginId: string,
+    bundleUrl: string,
+    version: string,
+    expectedHash?: string,
+  ): Promise<string[]> {
+    // 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)');
+    }
+
+    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
@@ -183,7 +377,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 +405,43 @@ 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)) {
+      const prev = this.provenance.get(bundleUrl);
+      if (prev) this.provenance.set(bundleUrl, { ...prev, source: 'memory', expected: expectedHash?.toLowerCase() ?? prev.expected });
+      return;
+    }
 
     const storage = getBundleStorage();
     const index = await storage.loadIndex();
@@ -220,15 +449,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 +473,116 @@ 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` : ''})`,
+    );
+
+    // Tools register at LOAD, not at mount — that is what makes a tool callable
+    // with nothing of the plugin on screen.
+    this.registerToolsFromModule(mod, bundleUrl);
+  }
+
+  /**
+   * Pick up every `tools` section in an evaluated bundle and put it in the
+   * device tool registry. Runs for UI, hybrid and tools-only bundles alike: a
+   * plugin that ships both gets its tools registered without its UI mounting.
+   */
+  private registerToolsFromModule(mod: any, bundleUrl: string): void {
+    if (!mod) return;
+
+    for (const key of Object.keys(mod)) {
+      const val = mod[key];
+      if (!val || typeof val !== 'object' || !Array.isArray(val.tools) || val.tools.length === 0) {
+        continue;
+      }
+      const pluginId = typeof val.id === 'string' ? val.id : `${bundleUrl}#${key}`;
+      try {
+        registerDeviceTools(pluginId, val.tools, val.capabilities, val.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),
+        );
+      }
+    }
   }
 
   /**
@@ -309,7 +635,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(

package/src/bundles/integrity.ts

@@ -0,0 +1,29 @@
+/**
+ * R8 remote-bundle integrity — the fail-closed check run INLINE, immediately
+ * before a remote bundle is evaluated with `new Function`.
+ *
+ * See docs/decisions/REMOTE_BUNDLE_INTEGRITY.md for the threat model and the
+ * (declined) publisher-signature decision. This is INTEGRITY, not a sandbox:
+ * it proves the bytes about to run are exactly the ones the trusted manifest
+ * hash names; it does not isolate what they can do.
+ */
+import { sha256Hex } from '../utils/sha256';
+
+/**
+ * Refuse to evaluate a bundle whose bytes do not match the SHA-256 that
+ * gate-kept them. Fail-closed on a MISSING hash too — an unverifiable bundle is
+ * treated exactly like a mismatched one. `verifiedHash` is the manifest hash for
+ * a cache hit or the freshly-verified download hash; re-hashing `content` here
+ * closes the disk-cache-tamper gap the download-time check leaves open.
+ */
+export function assertBundleIntegrity(content: string, verifiedHash: string | null, label: string): void {
+  const digest = sha256Hex(content);
+  if (!verifiedHash) {
+    throw new Error(`[bundle-integrity] refusing to evaluate ${label}: no verified SHA-256 (fail closed).`);
+  }
+  if (digest !== verifiedHash.toLowerCase()) {
+    throw new Error(
+      `[bundle-integrity] integrity FAIL at eval for ${label}: content sha256 ${digest.slice(0, 12)}… ≠ verified ${verifiedHash.slice(0, 12)}…. Refusing to evaluate.`,
+    );
+  }
+}

package/src/bundles/storage.ts

@@ -13,6 +13,46 @@ export interface BundleCacheEntry {
   bundleUrl: string;
   /** SHA-256 (hex, lowercase) of the cached bundle bytes — integrity proof */
   bundleHash?: string;
+  /**
+   * Tenant whose session downloaded these bytes.
+   *
+   * A bundle URL is NOT tenant-independent: `/api/ui-plugins/<id>/bundle.js`
+   * resolves per-tenant on the server, so the SAME url returns different code
+   * for different tenants. On the normal load path the hash gate catches this
+   * for free — the expected hash comes from the current tenant's manifest and
+   * will not match another tenant's cached bytes. The disk-cache recovery path
+   * has no manifest to check against, so it must discriminate by tenant.
+   *
+   * Absent on entries written before this field existed: unknown ownership, so
+   * untrusted. Never read a missing tenant as "mine".
+   */
+  tenant?: string;
+}
+
+/**
+ * Which cached entries belong to `tenant` and may therefore be re-evaluated.
+ *
+ * Lives here, beside the entry type, so "may I run this cached code" has ONE
+ * owner rather than being re-answered by each caller. `loadIndex()` returns
+ * every entry regardless of owner — it has to, since the manager looks entries
+ * up by url and rewrites them — so any caller that EVALUATES cached code must
+ * come through this function first.
+ *
+ * Fail-closed on both unknowns. An empty tenant owns nothing. An entry with no
+ * recorded tenant has unknown ownership and is never assumed to be the current
+ * one: every device already in the field has unstamped entries, so reading
+ * "missing" as "mine" would keep the hole open exactly where it is hardest to
+ * see.
+ *
+ * Compares the tenant field directly — it never builds a composite key, so
+ * there is no separator a tenant name could forge across.
+ */
+export function selectOwnedCacheEntries<T extends { tenant?: string }>(
+  entries: T[],
+  tenant: string | null | undefined,
+): T[] {
+  if (!tenant) return [];
+  return (entries || []).filter((e) => !!e && e.tenant === tenant);
 }
 
 export interface BundleStorage {