@liquidmetal-ai/precip 1.0.0

package/src/sandbox/bridges/storage-bridge.test.ts

@@ -0,0 +1,893 @@
+/**
+ * Tests for the unified storage bridge with actor-storage, write options, and list options
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { executeWithAsyncHost } from '../test-helper.js';
+import { installStorage, type StorageMountInfo } from './storage.js';
+
+// ============================================================================
+// Mock Factories
+// ============================================================================
+
+function createMockBucket(
+  files: Record<
+    string,
+    { content: string; contentType?: string; customMetadata?: Record<string, string> }
+  >
+) {
+  return {
+    async get(key: string) {
+      const file = files[key];
+      if (!file) return null;
+
+      const encoder = new TextEncoder();
+      const data = encoder.encode(file.content);
+      let offset = 0;
+      const chunkSize = 100;
+
+      const stream = new ReadableStream<Uint8Array>({
+        pull(controller) {
+          if (offset >= data.length) {
+            controller.close();
+            return;
+          }
+          const chunk = data.slice(offset, offset + chunkSize);
+          controller.enqueue(chunk);
+          offset += chunkSize;
+        }
+      });
+
+      return {
+        key,
+        body: stream,
+        size: data.length,
+        uploaded: new Date('2024-01-15T00:00:00Z'),
+        httpMetadata: { contentType: file.contentType || 'application/octet-stream' },
+        customMetadata: file.customMetadata || {}
+      };
+    },
+
+    async put(key: string, content: string, options?: any) {
+      files[key] = {
+        content,
+        contentType: options?.httpMetadata?.contentType,
+        customMetadata: options?.customMetadata
+      };
+      return { key, size: content.length, uploaded: new Date(), etag: 'test', version: '1' };
+    },
+
+    async list(options?: any) {
+      const prefix = options?.prefix || '';
+      let entries = Object.keys(files).filter(k => k.startsWith(prefix));
+
+      if (options?.startAfter) {
+        entries = entries.filter(k => k > options.startAfter);
+      }
+      if (options?.limit) {
+        entries = entries.slice(0, options.limit);
+      }
+
+      const objects = entries.map(key => ({
+        key,
+        size: files[key].content.length,
+        uploaded: new Date('2024-01-15T00:00:00Z')
+      }));
+      return { objects, truncated: false, delimitedPrefixes: [] };
+    },
+
+    async delete(key: string) {
+      delete files[key];
+    }
+  };
+}
+
+function createMockKvCache(
+  data: Record<string, { value: string; metadata?: any; expiration?: number }>
+) {
+  return {
+    async get(key: string) {
+      return data[key]?.value ?? null;
+    },
+    async getWithMetadata(key: string) {
+      const entry = data[key];
+      return {
+        value: entry?.value ?? null,
+        metadata: entry?.metadata ?? null,
+        cacheStatus: null
+      };
+    },
+    async put(key: string, value: string, options?: any) {
+      data[key] = {
+        value,
+        metadata: options?.metadata,
+        expiration:
+          options?.expiration ||
+          (options?.expirationTtl ? Date.now() / 1000 + options.expirationTtl : undefined)
+      };
+    },
+    async list(options?: any) {
+      const prefix = options?.prefix || '';
+      const keys = Object.keys(data)
+        .filter(k => k.startsWith(prefix))
+        .map(name => ({
+          name,
+          expiration: data[name].expiration,
+          metadata: data[name].metadata
+        }));
+      return { keys, list_complete: true, cacheStatus: null };
+    },
+    async delete(key: string) {
+      delete data[key];
+    },
+    async clear() {
+      const total = Object.keys(data).length;
+      for (const key of Object.keys(data)) delete data[key];
+      return { deleted: total, total };
+    }
+  };
+}
+
+function createMockActorStorage(data: Map<string, unknown> = new Map()) {
+  return {
+    async get(keyOrKeys: string | string[]) {
+      if (Array.isArray(keyOrKeys)) {
+        const result = new Map();
+        for (const key of keyOrKeys) {
+          const value = data.get(key);
+          if (value !== undefined) result.set(key, value);
+        }
+        return result;
+      }
+      return data.get(keyOrKeys);
+    },
+    async put(keyOrEntries: string | Record<string, any>, value?: any) {
+      if (typeof keyOrEntries === 'string') {
+        data.set(keyOrEntries, value);
+      } else {
+        for (const [k, v] of Object.entries(keyOrEntries)) {
+          data.set(k, v);
+        }
+      }
+    },
+    async delete(keyOrKeys: string | string[]) {
+      if (Array.isArray(keyOrKeys)) {
+        let count = 0;
+        for (const key of keyOrKeys) {
+          if (data.delete(key)) count++;
+        }
+        return count;
+      }
+      return data.delete(keyOrKeys);
+    },
+    async deleteAll() {
+      data.clear();
+    },
+    async list(options?: any) {
+      const result = new Map();
+      let entries = Array.from(data.entries()).sort(([a], [b]) => a.localeCompare(b));
+
+      if (options?.prefix) {
+        entries = entries.filter(([key]) => key.startsWith(options.prefix));
+      }
+      if (options?.start) {
+        entries = entries.filter(([key]) => key >= options.start);
+      }
+      if (options?.startAfter) {
+        entries = entries.filter(([key]) => key > options.startAfter);
+      }
+      if (options?.end) {
+        entries = entries.filter(([key]) => key <= options.end);
+      }
+      if (options?.reverse) {
+        entries.reverse();
+      }
+      if (options?.limit) {
+        entries = entries.slice(0, options.limit);
+      }
+
+      for (const [key, value] of entries) {
+        result.set(key, value);
+      }
+      return result;
+    },
+    async getAlarm() {
+      return null;
+    },
+    async setAlarm() {},
+    async deleteAlarm() {}
+  };
+}
+
+// ============================================================================
+// Actor Storage Tests
+// ============================================================================
+
+describe('Storage Bridge - Actor Storage', () => {
+  it('should read string values from actor storage', async () => {
+    const encoder = new TextEncoder();
+    const data = new Map<string, unknown>([
+      ['counter', encoder.encode('42')],
+      ['prefs', encoder.encode(JSON.stringify({ theme: 'dark', lang: 'en' }))]
+    ]);
+    const mockStorage = createMockActorStorage(data);
+    const storageMounts = new Map<string, StorageMountInfo>([
+      ['state', { name: 'state', type: 'actor-storage', resource: mockStorage as any, mode: 'rw' }]
+    ]);
+
+    const result = await executeWithAsyncHost(
+      `
+      const counterRes = await read("/state/counter");
+      const prefsRes = await read("/state/prefs");
+
+      // Verify consistent Response-like interface
+      const hasBody = counterRes.body !== null;
+      const hasText = typeof counterRes.text === 'function';
+      const hasJson = typeof counterRes.json === 'function';
+      const ok = counterRes.ok;
+      const status = counterRes.status;
+
+      const counter = await counterRes.text();
+      const prefs = await prefsRes.json();
+      return { counter, prefs, hasBody, hasText, hasJson, ok, status };
+    `,
+      {},
+      {
+        bridgeInstallers: [ctx => installStorage(ctx, storageMounts)]
+      }
+    );
+
+    expect(result.success).toBe(true);
+    expect(result.result.counter).toBe('42');
+    expect(result.result.prefs).toEqual({ theme: 'dark', lang: 'en' });
+    // Same Response-like shape as bucket reads
+    expect(result.result.hasBody).toBe(true);
+    expect(result.result.hasText).toBe(true);
+    expect(result.result.hasJson).toBe(true);
+    expect(result.result.ok).toBe(true);
+    expect(result.result.status).toBe(200);
+  });
+
+  it('should write values to actor storage as bytes', async () => {
+    const data = new Map<string, unknown>();
+    const mockStorage = createMockActorStorage(data);
+    const storageMounts = new Map<string, StorageMountInfo>([
+      ['state', { name: 'state', type: 'actor-storage', resource: mockStorage as any, mode: 'rw' }]
+    ]);
+
+    const result = await executeWithAsyncHost(
+      `
+      await write("/state/counter", "42");
+      await write("/state/prefs", JSON.stringify({ theme: "dark", lang: "en" }));
+      await write("/state/name", "Alice");
+      return { success: true };
+    `,
+      {},
+      {
+        bridgeInstallers: [ctx => installStorage(ctx, storageMounts)]
+      }
+    );
+
+    expect(result.success).toBe(true);
+    // Values are stored as Uint8Array
+    const decoder = new TextDecoder();
+    expect(decoder.decode(data.get('counter') as Uint8Array)).toBe('42');
+    expect(decoder.decode(data.get('prefs') as Uint8Array)).toBe('{"theme":"dark","lang":"en"}');
+    expect(decoder.decode(data.get('name') as Uint8Array)).toBe('Alice');
+  });
+
+  it('should list keys from actor storage', async () => {
+    const encoder = new TextEncoder();
+    const data = new Map<string, unknown>([
+      ['user:alice', encoder.encode('{"name":"Alice"}')],
+      ['user:bob', encoder.encode('{"name":"Bob"}')],
+      ['config:theme', encoder.encode('dark')]
+    ]);
+    const mockStorage = createMockActorStorage(data);
+    const storageMounts = new Map<string, StorageMountInfo>([
+      ['state', { name: 'state', type: 'actor-storage', resource: mockStorage as any, mode: 'rw' }]
+    ]);
+
+    const result = await executeWithAsyncHost(
+      `
+      const all = await list("/state/");
+      const users = await list("/state/user:");
+      return { allCount: all.count, userCount: users.count, userKeys: users.files.map(f => f.key) };
+    `,
+      {},
+      {
+        bridgeInstallers: [ctx => installStorage(ctx, storageMounts)]
+      }
+    );
+
+    expect(result.success).toBe(true);
+    expect(result.result.allCount).toBe(3);
+    expect(result.result.userCount).toBe(2);
+    expect(result.result.userKeys).toEqual(['/state/user:alice', '/state/user:bob']);
+  });
+
+  it('should support range queries on actor storage list', async () => {
+    const data = new Map<string, unknown>([
+      ['a', new Uint8Array([1])],
+      ['b', new Uint8Array([2])],
+      ['c', new Uint8Array([3])],
+      ['d', new Uint8Array([4])],
+      ['e', new Uint8Array([5])]
+    ]);
+    const mockStorage = createMockActorStorage(data);
+    const storageMounts = new Map<string, StorageMountInfo>([
+      ['state', { name: 'state', type: 'actor-storage', resource: mockStorage as any, mode: 'rw' }]
+    ]);
+
+    const result = await executeWithAsyncHost(
+      `
+      const reversed = await list("/state/", { reverse: true, limit: 3 });
+      const range = await list("/state/", { start: "b", end: "d" });
+      return {
+        reversedKeys: reversed.files.map(f => f.key),
+        rangeKeys: range.files.map(f => f.key),
+      };
+    `,
+      {},
+      {
+        bridgeInstallers: [ctx => installStorage(ctx, storageMounts)]
+      }
+    );
+
+    expect(result.success).toBe(true);
+    expect(result.result.reversedKeys).toEqual(['/state/e', '/state/d', '/state/c']);
+    expect(result.result.rangeKeys).toEqual(['/state/b', '/state/c', '/state/d']);
+  });
+
+  it('should delete from actor storage', async () => {
+    const encoder = new TextEncoder();
+    const data = new Map<string, unknown>([
+      ['key1', encoder.encode('value1')],
+      ['key2', encoder.encode('value2')]
+    ]);
+    const mockStorage = createMockActorStorage(data);
+    const storageMounts = new Map<string, StorageMountInfo>([
+      ['state', { name: 'state', type: 'actor-storage', resource: mockStorage as any, mode: 'rw' }]
+    ]);
+
+    const result = await executeWithAsyncHost(
+      `
+      await remove("/state/key1");
+      const remaining = await list("/state/");
+      return { count: remaining.count, keys: remaining.files.map(f => f.key) };
+    `,
+      {},
+      {
+        bridgeInstallers: [ctx => installStorage(ctx, storageMounts)]
+      }
+    );
+
+    expect(result.success).toBe(true);
+    expect(result.result.count).toBe(1);
+    expect(result.result.keys).toEqual(['/state/key2']);
+  });
+
+  it('should throw when reading non-existent key from actor storage', async () => {
+    const data = new Map<string, unknown>();
+    const mockStorage = createMockActorStorage(data);
+    const storageMounts = new Map<string, StorageMountInfo>([
+      ['state', { name: 'state', type: 'actor-storage', resource: mockStorage as any, mode: 'rw' }]
+    ]);
+
+    const result = await executeWithAsyncHost(
+      `
+      try {
+        await read("/state/nonexistent");
+        return { error: false };
+      } catch (e) {
+        return { error: true, message: String(e) };
+      }
+    `,
+      {},
+      {
+        bridgeInstallers: [ctx => installStorage(ctx, storageMounts)]
+      }
+    );
+
+    expect(result.success).toBe(true);
+    expect(result.result.error).toBe(true);
+    expect(result.result.message).toContain('not found');
+  });
+});
+
+// ============================================================================
+// Write Options Tests
+// ============================================================================
+
+describe('Storage Bridge - Write Options', () => {
+  it('should pass ttl option to KV cache', async () => {
+    const data: Record<string, any> = {};
+    const mockKv = createMockKvCache(data);
+    const putSpy = vi.spyOn(mockKv, 'put');
+    const storageMounts = new Map<string, StorageMountInfo>([
+      ['cache', { name: 'cache', type: 'kv', resource: mockKv as any, mode: 'rw' }]
+    ]);
+
+    const result = await executeWithAsyncHost(
+      `
+      await write("/cache/session:abc", "data", { ttl: 300 });
+      return { success: true };
+    `,
+      {},
+      {
+        bridgeInstallers: [ctx => installStorage(ctx, storageMounts)]
+      }
+    );
+
+    expect(result.success).toBe(true);
+    expect(putSpy).toHaveBeenCalledWith('session:abc', 'data', { expirationTtl: 300 });
+  });
+
+  it('should pass expiration option to KV cache', async () => {
+    const data: Record<string, any> = {};
+    const mockKv = createMockKvCache(data);
+    const putSpy = vi.spyOn(mockKv, 'put');
+    const storageMounts = new Map<string, StorageMountInfo>([
+      ['cache', { name: 'cache', type: 'kv', resource: mockKv as any, mode: 'rw' }]
+    ]);
+
+    const result = await executeWithAsyncHost(
+      `
+      await write("/cache/temp", "value", { expiration: 1720000000 });
+      return { success: true };
+    `,
+      {},
+      {
+        bridgeInstallers: [ctx => installStorage(ctx, storageMounts)]
+      }
+    );
+
+    expect(result.success).toBe(true);
+    expect(putSpy).toHaveBeenCalledWith('temp', 'value', { expiration: 1720000000 });
+  });
+
+  it('should pass metadata option to KV cache', async () => {
+    const data: Record<string, any> = {};
+    const mockKv = createMockKvCache(data);
+    const putSpy = vi.spyOn(mockKv, 'put');
+    const storageMounts = new Map<string, StorageMountInfo>([
+      ['cache', { name: 'cache', type: 'kv', resource: mockKv as any, mode: 'rw' }]
+    ]);
+
+    const result = await executeWithAsyncHost(
+      `
+      await write("/cache/user:123", "data", { metadata: { source: "api" } });
+      return { success: true };
+    `,
+      {},
+      {
+        bridgeInstallers: [ctx => installStorage(ctx, storageMounts)]
+      }
+    );
+
+    expect(result.success).toBe(true);
+    expect(putSpy).toHaveBeenCalledWith('user:123', 'data', { metadata: { source: 'api' } });
+  });
+
+  it('should pass contentType option to bucket', async () => {
+    const files: Record<string, any> = {};
+    const mockBucket = createMockBucket(files);
+    const putSpy = vi.spyOn(mockBucket, 'put');
+    const storageMounts = new Map<string, StorageMountInfo>([
+      ['uploads', { name: 'uploads', type: 'bucket', resource: mockBucket as any, mode: 'rw' }]
+    ]);
+
+    const result = await executeWithAsyncHost(
+      `
+      await write("/uploads/report.json", '{"key":"value"}', { contentType: "application/json" });
+      return { success: true };
+    `,
+      {},
+      {
+        bridgeInstallers: [ctx => installStorage(ctx, storageMounts)]
+      }
+    );
+
+    expect(result.success).toBe(true);
+    expect(putSpy).toHaveBeenCalledWith('report.json', '{"key":"value"}', {
+      httpMetadata: { contentType: 'application/json' }
+    });
+  });
+
+  it('should pass customMetadata option to bucket', async () => {
+    const files: Record<string, any> = {};
+    const mockBucket = createMockBucket(files);
+    const putSpy = vi.spyOn(mockBucket, 'put');
+    const storageMounts = new Map<string, StorageMountInfo>([
+      ['uploads', { name: 'uploads', type: 'bucket', resource: mockBucket as any, mode: 'rw' }]
+    ]);
+
+    const result = await executeWithAsyncHost(
+      `
+      await write("/uploads/file.txt", "content", { customMetadata: { author: "alice", version: "2" } });
+      return { success: true };
+    `,
+      {},
+      {
+        bridgeInstallers: [ctx => installStorage(ctx, storageMounts)]
+      }
+    );
+
+    expect(result.success).toBe(true);
+    expect(putSpy).toHaveBeenCalledWith('file.txt', 'content', {
+      customMetadata: { author: 'alice', version: '2' }
+    });
+  });
+
+  it('should write without options (backward compatible)', async () => {
+    const data: Record<string, any> = {};
+    const mockKv = createMockKvCache(data);
+    const storageMounts = new Map<string, StorageMountInfo>([
+      ['cache', { name: 'cache', type: 'kv', resource: mockKv as any, mode: 'rw' }]
+    ]);
+
+    const result = await executeWithAsyncHost(
+      `
+      await write("/cache/simple", "value");
+      return { success: true };
+    `,
+      {},
+      {
+        bridgeInstallers: [ctx => installStorage(ctx, storageMounts)]
+      }
+    );
+
+    expect(result.success).toBe(true);
+    expect(data['simple']?.value).toBe('value');
+  });
+});
+
+// ============================================================================
+// List Options Tests
+// ============================================================================
+
+describe('Storage Bridge - List Options', () => {
+  it('should pass limit to bucket list', async () => {
+    const files: Record<string, any> = {
+      'a.txt': { content: 'a' },
+      'b.txt': { content: 'b' },
+      'c.txt': { content: 'c' }
+    };
+    const mockBucket = createMockBucket(files);
+    const storageMounts = new Map<string, StorageMountInfo>([
+      ['uploads', { name: 'uploads', type: 'bucket', resource: mockBucket as any }]
+    ]);
+
+    const result = await executeWithAsyncHost(
+      `
+      const limited = await list("/uploads/", { limit: 2 });
+      return { count: limited.count };
+    `,
+      {},
+      {
+        bridgeInstallers: [ctx => installStorage(ctx, storageMounts)]
+      }
+    );
+
+    expect(result.success).toBe(true);
+    expect(result.result.count).toBe(2);
+  });
+
+  it('should pass startAfter to bucket list', async () => {
+    const files: Record<string, any> = {
+      'a.txt': { content: 'a' },
+      'b.txt': { content: 'b' },
+      'c.txt': { content: 'c' }
+    };
+    const mockBucket = createMockBucket(files);
+    const storageMounts = new Map<string, StorageMountInfo>([
+      ['uploads', { name: 'uploads', type: 'bucket', resource: mockBucket as any }]
+    ]);
+
+    const result = await executeWithAsyncHost(
+      `
+      const after = await list("/uploads/", { startAfter: "a.txt" });
+      return { keys: after.files.map(f => f.key) };
+    `,
+      {},
+      {
+        bridgeInstallers: [ctx => installStorage(ctx, storageMounts)]
+      }
+    );
+
+    expect(result.success).toBe(true);
+    expect(result.result.keys).toEqual(['/uploads/b.txt', '/uploads/c.txt']);
+  });
+
+  it('should include expiration in KV list results', async () => {
+    const data: Record<string, any> = {
+      key1: { value: 'val1', expiration: 1720000000 },
+      key2: { value: 'val2' }
+    };
+    const mockKv = createMockKvCache(data);
+    const storageMounts = new Map<string, StorageMountInfo>([
+      ['cache', { name: 'cache', type: 'kv', resource: mockKv as any }]
+    ]);
+
+    const result = await executeWithAsyncHost(
+      `
+      const listed = await list("/cache/");
+      return { files: listed.files };
+    `,
+      {},
+      {
+        bridgeInstallers: [ctx => installStorage(ctx, storageMounts)]
+      }
+    );
+
+    expect(result.success).toBe(true);
+    const fileWithExpiration = result.result.files.find((f: any) => f.key === '/cache/key1');
+    expect(fileWithExpiration?.expiration).toBe(1720000000);
+  });
+});
+
+// ============================================================================
+// KV Read with Metadata Tests
+// ============================================================================
+
+describe('Storage Bridge - KV Read with Metadata', () => {
+  it('should include metadata in KV read response', async () => {
+    const data: Record<string, any> = {
+      'user:123': {
+        value: JSON.stringify({ name: 'Alice' }),
+        metadata: { source: 'api', version: '2' }
+      }
+    };
+    const mockKv = createMockKvCache(data);
+    const storageMounts = new Map<string, StorageMountInfo>([
+      ['cache', { name: 'cache', type: 'kv', resource: mockKv as any }]
+    ]);
+
+    const result = await executeWithAsyncHost(
+      `
+      const res = await read("/cache/user:123");
+      const value = await res.json();
+      return { value, metadata: res.metadata, ok: res.ok, hasBody: res.body !== null, hasText: typeof res.text === 'function' };
+    `,
+      {},
+      {
+        bridgeInstallers: [ctx => installStorage(ctx, storageMounts)]
+      }
+    );
+
+    expect(result.success).toBe(true);
+    expect(result.result.value).toEqual({ name: 'Alice' });
+    // metadata is serialized as JSON string via createResponseObject metadata
+    expect(result.result.metadata).toBe('{"source":"api","version":"2"}');
+    expect(result.result.ok).toBe(true);
+    expect(result.result.hasBody).toBe(true);
+    expect(result.result.hasText).toBe(true);
+  });
+
+  it('should throw when reading non-existent KV key', async () => {
+    const data: Record<string, any> = {};
+    const mockKv = createMockKvCache(data);
+    const storageMounts = new Map<string, StorageMountInfo>([
+      ['cache', { name: 'cache', type: 'kv', resource: mockKv as any }]
+    ]);
+
+    const result = await executeWithAsyncHost(
+      `
+      try {
+        await read("/cache/nonexistent");
+        return { error: false };
+      } catch (e) {
+        return { error: true, message: String(e) };
+      }
+    `,
+      {},
+      {
+        bridgeInstallers: [ctx => installStorage(ctx, storageMounts)]
+      }
+    );
+
+    expect(result.success).toBe(true);
+    expect(result.result.error).toBe(true);
+    expect(result.result.message).toContain('not found');
+  });
+});
+
+// ============================================================================
+// Mixed Mount Tests (ensure unified API works across types)
+// ============================================================================
+
+describe('Storage Bridge - Mixed Mounts', () => {
+  it('should read/write across bucket, KV, and actor-storage using same API', async () => {
+    const bucketFiles: Record<string, any> = {
+      'readme.txt': { content: 'Hello from bucket' }
+    };
+    const kvData: Record<string, any> = {
+      'session:abc': { value: JSON.stringify({ user: 'alice' }) }
+    };
+    const actorData = new Map<string, unknown>([['counter', new TextEncoder().encode('42')]]);
+
+    const mockBucket = createMockBucket(bucketFiles);
+    const mockKv = createMockKvCache(kvData);
+    const mockStorage = createMockActorStorage(actorData);
+
+    const storageMounts = new Map<string, StorageMountInfo>([
+      ['uploads', { name: 'uploads', type: 'bucket', resource: mockBucket as any, mode: 'rw' }],
+      ['cache', { name: 'cache', type: 'kv', resource: mockKv as any, mode: 'rw' }],
+      ['state', { name: 'state', type: 'actor-storage', resource: mockStorage as any, mode: 'rw' }]
+    ]);
+
+    const result = await executeWithAsyncHost(
+      `
+      // Read from each
+      const fileText = await (await read("/uploads/readme.txt")).text();
+      const kvData = await (await read("/cache/session:abc")).json();
+      const stateVal = await (await read("/state/counter")).text();
+
+      // Write to each
+      await write("/uploads/new.txt", "new file");
+      await write("/cache/temp", "cached", { ttl: 60 });
+      await write("/state/counter", "43");
+
+      // Verify writes
+      const newFile = await (await read("/uploads/new.txt")).text();
+      const newState = await (await read("/state/counter")).text();
+
+      return { fileText, kvData, stateVal, newFile, newState };
+    `,
+      {},
+      {
+        bridgeInstallers: [ctx => installStorage(ctx, storageMounts)],
+        timeoutMs: 10000
+      }
+    );
+
+    expect(result.success).toBe(true);
+    expect(result.result.fileText).toBe('Hello from bucket');
+    expect(result.result.kvData).toEqual({ user: 'alice' });
+    expect(result.result.stateVal).toBe('42');
+    expect(result.result.newFile).toBe('new file');
+    expect(result.result.newState).toBe('43');
+  });
+});
+
+// ============================================================================
+// Read-Only Mode Enforcement Tests
+// ============================================================================
+
+describe('Storage Bridge - Read-Only Mode Enforcement', () => {
+  it('should reject writes to read-only KV mount', async () => {
+    const data: Record<string, any> = {};
+    const mockKv = createMockKvCache(data);
+    const storageMounts = new Map<string, StorageMountInfo>([
+      ['cache', { name: 'cache', type: 'kv', resource: mockKv as any }] // no mode = read-only
+    ]);
+
+    const result = await executeWithAsyncHost(
+      `
+      try {
+        await write("/cache/key", "value");
+        return { error: false };
+      } catch (e) {
+        return { error: true, message: String(e) };
+      }
+    `,
+      {},
+      {
+        bridgeInstallers: [ctx => installStorage(ctx, storageMounts)]
+      }
+    );
+
+    expect(result.success).toBe(true);
+    expect(result.result.error).toBe(true);
+    expect(result.result.message).toContain('read-only');
+  });
+
+  it('should reject deletes from read-only KV mount', async () => {
+    const data: Record<string, any> = {
+      key1: { value: 'val1' }
+    };
+    const mockKv = createMockKvCache(data);
+    const storageMounts = new Map<string, StorageMountInfo>([
+      ['cache', { name: 'cache', type: 'kv', resource: mockKv as any }]
+    ]);
+
+    const result = await executeWithAsyncHost(
+      `
+      try {
+        await remove("/cache/key1");
+        return { error: false };
+      } catch (e) {
+        return { error: true, message: String(e) };
+      }
+    `,
+      {},
+      {
+        bridgeInstallers: [ctx => installStorage(ctx, storageMounts)]
+      }
+    );
+
+    expect(result.success).toBe(true);
+    expect(result.result.error).toBe(true);
+    expect(result.result.message).toContain('read-only');
+  });
+
+  it('should reject writes to read-only actor-storage mount', async () => {
+    const data = new Map<string, unknown>();
+    const mockStorage = createMockActorStorage(data);
+    const storageMounts = new Map<string, StorageMountInfo>([
+      ['state', { name: 'state', type: 'actor-storage', resource: mockStorage as any }] // no mode = read-only
+    ]);
+
+    const result = await executeWithAsyncHost(
+      `
+      try {
+        await write("/state/key", "value");
+        return { error: false };
+      } catch (e) {
+        return { error: true, message: String(e) };
+      }
+    `,
+      {},
+      {
+        bridgeInstallers: [ctx => installStorage(ctx, storageMounts)]
+      }
+    );
+
+    expect(result.success).toBe(true);
+    expect(result.result.error).toBe(true);
+    expect(result.result.message).toContain('read-only');
+  });
+
+  it('should reject deletes from read-only actor-storage mount', async () => {
+    const encoder = new TextEncoder();
+    const data = new Map<string, unknown>([['key1', encoder.encode('value1')]]);
+    const mockStorage = createMockActorStorage(data);
+    const storageMounts = new Map<string, StorageMountInfo>([
+      ['state', { name: 'state', type: 'actor-storage', resource: mockStorage as any }]
+    ]);
+
+    const result = await executeWithAsyncHost(
+      `
+      try {
+        await remove("/state/key1");
+        return { error: false };
+      } catch (e) {
+        return { error: true, message: String(e) };
+      }
+    `,
+      {},
+      {
+        bridgeInstallers: [ctx => installStorage(ctx, storageMounts)]
+      }
+    );
+
+    expect(result.success).toBe(true);
+    expect(result.result.error).toBe(true);
+    expect(result.result.message).toContain('read-only');
+  });
+
+  it('should allow reads from read-only mounts', async () => {
+    const data: Record<string, any> = {
+      greeting: { value: 'hello' }
+    };
+    const mockKv = createMockKvCache(data);
+    const storageMounts = new Map<string, StorageMountInfo>([
+      ['cache', { name: 'cache', type: 'kv', resource: mockKv as any }] // no mode = read-only
+    ]);
+
+    const result = await executeWithAsyncHost(
+      `
+      const res = await read("/cache/greeting");
+      const value = await res.text();
+      return { value };
+    `,
+      {},
+      {
+        bridgeInstallers: [ctx => installStorage(ctx, storageMounts)]
+      }
+    );
+
+    expect(result.success).toBe(true);
+    expect(result.result.value).toBe('hello');
+  });
+});