@bevel-software/platform-core-backend 0.1.0

package/src/modules/workspace/__tests__/kb-seed.service.test.ts

@@ -0,0 +1,213 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { KbSeedService } from '../kb-seed.service.js';
+import { defaultKbTemplateDir } from '../../../assets.js';
+
+const execFileAsync = promisify(execFile);
+
+/** The real seed template shipped inside this package (see assets.ts). */
+const TEMPLATE_DIR = defaultKbTemplateDir();
+
+const PROTECTED = ['current-company-state', 'target-company-state'];
+const DEFAULT_BRANCH = 'current-company-state';
+const ADMINS = ['alice@example.com', 'bob@example.com'];
+
+async function git(cwd: string, args: string[]): Promise<string> {
+  const { stdout } = await execFileAsync('git', args, {
+    cwd,
+    env: {
+      ...process.env,
+      GIT_AUTHOR_NAME: 'Test', GIT_AUTHOR_EMAIL: 't@x.com',
+      GIT_COMMITTER_NAME: 'Test', GIT_COMMITTER_EMAIL: 't@x.com',
+    },
+  });
+  return stdout.toString();
+}
+
+function makeSeeder(upstream: string, admins: readonly string[] = ADMINS): KbSeedService {
+  return new KbSeedService(upstream, TEMPLATE_DIR, PROTECTED, DEFAULT_BRANCH, admins);
+}
+
+/** Clone a branch of the upstream into a fresh checkout for inspection. */
+async function checkout(root: string, upstream: string, branch: string): Promise<string> {
+  const dir = path.join(root, `checkout-${branch}-${Math.random().toString(36).slice(2)}`);
+  await git(root, ['clone', '-b', branch, upstream, dir]);
+  return dir;
+}
+
+async function exists(p: string): Promise<boolean> {
+  try {
+    await fs.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function headCommitCount(root: string, upstream: string, branch: string): Promise<number> {
+  const dir = await checkout(root, upstream, branch);
+  const out = await git(dir, ['rev-list', '--count', 'HEAD']);
+  return Number(out.trim());
+}
+
+describe('KbSeedService', () => {
+  let root: string;
+
+  beforeEach(async () => {
+    root = await fs.mkdtemp(path.join(os.tmpdir(), 'kb-seed-test-'));
+  });
+  afterEach(async () => {
+    await fs.rm(root, { recursive: true, force: true }).catch(() => {});
+  });
+
+  /** A bare, branch-less "empty" remote. */
+  async function emptyUpstream(): Promise<string> {
+    const upstream = path.join(root, 'upstream.git');
+    await git(root, ['init', '--bare', upstream]);
+    return upstream;
+  }
+
+  /** A bare remote pre-seeded on `branches`, each with `files` written at the root. */
+  async function seededUpstream(
+    branches: string[],
+    files: Record<string, string>,
+  ): Promise<string> {
+    const upstream = path.join(root, 'upstream.git');
+    await git(root, ['init', '--bare', upstream]);
+    const seed = path.join(root, '.seed');
+    await fs.mkdir(seed);
+    await git(seed, ['init', '-b', branches[0]]);
+    await git(seed, ['remote', 'add', 'origin', upstream]);
+    for (const [name, content] of Object.entries(files)) {
+      const abs = path.join(seed, name);
+      await fs.mkdir(path.dirname(abs), { recursive: true });
+      await fs.writeFile(abs, content, 'utf8');
+    }
+    await git(seed, ['add', '-A']);
+    await git(seed, ['commit', '-m', 'pre-seed']);
+    for (const b of branches.slice(1)) await git(seed, ['branch', b]);
+    await git(seed, ['push', 'origin', ...branches]);
+    return upstream;
+  }
+
+  describe('empty remote → full seed', () => {
+    it('seeds every protected branch with base scaffolding + generated roles.yaml', async () => {
+      const upstream = await emptyUpstream();
+      await makeSeeder(upstream).ensureRemoteSeeded();
+
+      for (const branch of PROTECTED) {
+        const dir = await checkout(root, upstream, branch);
+        expect(await exists(path.join(dir, 'access.md'))).toBe(true);
+        expect(await exists(path.join(dir, 'CLAUDE.md'))).toBe(true);
+        expect(await exists(path.join(dir, '.bevelignore'))).toBe(true);
+        expect(await exists(path.join(dir, '.gitignore'))).toBe(true);
+        // The well-known KB roots are seeded (kept present via their .gitkeep).
+        expect(await exists(path.join(dir, 'KnowledgeBase/.gitkeep'))).toBe(true);
+        expect(await exists(path.join(dir, 'Skills/.gitkeep'))).toBe(true);
+
+        const roles = await fs.readFile(path.join(dir, 'roles.yaml'), 'utf8');
+        for (const email of ADMINS) expect(roles).toContain(email);
+        // The template's illustrative placeholder must NOT leak into the seed.
+        expect(roles).not.toContain('admin@example.com');
+      }
+    });
+
+    it('throws when no admin emails are configured', async () => {
+      const upstream = await emptyUpstream();
+      await expect(makeSeeder(upstream, []).ensureRemoteSeeded()).rejects.toThrow(
+        /SEED_ADMIN_EMAILS/,
+      );
+    });
+  });
+
+  describe('existing remote → conservative top-up', () => {
+    it('creates a missing protected branch off an existing one', async () => {
+      // Only current-company-state exists; target-company-state is missing.
+      const upstream = await seededUpstream([DEFAULT_BRANCH], {
+        'roles.yaml': 'roles:\n  Admin:\n    - keep@example.com\n',
+        'access.md': 'existing',
+        'CLAUDE.md': 'existing',
+        '.bevelignore': 'x',
+        '.gitignore': 'x',
+        'KnowledgeBase/Real/Knowledge/.gitkeep': '',
+        'Skills/.gitkeep': '',
+      });
+
+      await makeSeeder(upstream).ensureRemoteSeeded();
+
+      const heads = await git(root, ['ls-remote', '--heads', upstream]);
+      expect(heads).toContain('refs/heads/target-company-state');
+    });
+
+    it('topUpWorkspace adds only missing scaffolding and never overwrites existing files', async () => {
+      const upstream = await seededUpstream(PROTECTED, {
+        // roles.yaml + access.md already exist with custom content — must survive.
+        'roles.yaml': 'roles:\n  Admin:\n    - keep@example.com\n',
+        'access.md': 'CUSTOM ACCESS RULES',
+        // CLAUDE.md / .bevelignore / .gitignore are absent → should be added.
+        'KnowledgeBase/Real/Knowledge/.gitkeep': '',
+        'Skills/.gitkeep': '',
+      });
+
+      // Simulate the app loading the branch: a fresh clone, then top-up on it.
+      const repoDir = await checkout(root, upstream, DEFAULT_BRANCH);
+      await makeSeeder(upstream).topUpWorkspace(repoDir, DEFAULT_BRANCH);
+
+      // Verify the pushed remote state via an independent clone.
+      const dir = await checkout(root, upstream, DEFAULT_BRANCH);
+      // Existing files preserved verbatim.
+      expect(await fs.readFile(path.join(dir, 'access.md'), 'utf8')).toBe('CUSTOM ACCESS RULES');
+      expect(await fs.readFile(path.join(dir, 'roles.yaml'), 'utf8')).toContain('keep@example.com');
+      // Missing scaffolding added.
+      expect(await exists(path.join(dir, 'CLAUDE.md'))).toBe(true);
+      expect(await exists(path.join(dir, '.bevelignore'))).toBe(true);
+      // Sample content is NOT restored — the real KnowledgeBase already had content,
+      // so no placeholder .gitkeep is dropped into it, and no ExampleOntology appears.
+      expect(await exists(path.join(dir, 'KnowledgeBase/.gitkeep'))).toBe(false);
+      expect(await exists(path.join(dir, 'KnowledgeBase/ExampleOntology'))).toBe(false);
+    });
+
+    it('topUpWorkspace is idempotent — a second load makes no new commit', async () => {
+      const upstream = await seededUpstream(PROTECTED, {
+        'roles.yaml': 'roles:\n  Admin:\n    - keep@example.com\n',
+        'KnowledgeBase/Real/Knowledge/.gitkeep': '',
+        'Skills/.gitkeep': '',
+      });
+
+      const first = await checkout(root, upstream, DEFAULT_BRANCH);
+      await makeSeeder(upstream).topUpWorkspace(first, DEFAULT_BRANCH);
+      const after1 = await headCommitCount(root, upstream, DEFAULT_BRANCH);
+
+      // A later reload: fresh clone reflects the pushed scaffolding, so top-up
+      // finds nothing missing and makes no new commit.
+      const second = await checkout(root, upstream, DEFAULT_BRANCH);
+      await makeSeeder(upstream).topUpWorkspace(second, DEFAULT_BRANCH);
+      const after2 = await headCommitCount(root, upstream, DEFAULT_BRANCH);
+
+      expect(after2).toBe(after1);
+    });
+
+    it('topUpWorkspace fills scaffolding on a non-protected feature branch too', async () => {
+      const upstream = await seededUpstream(PROTECTED, {
+        'roles.yaml': 'roles:\n  Admin:\n    - keep@example.com\n',
+        'KnowledgeBase/Real/Knowledge/.gitkeep': '',
+        'Skills/.gitkeep': '',
+      });
+      // Branch a feature off the default and load it.
+      const seed = await checkout(root, upstream, DEFAULT_BRANCH);
+      await git(seed, ['checkout', '-b', 'alice/feature']);
+      await git(seed, ['push', 'origin', 'alice/feature']);
+
+      const repoDir = await checkout(root, upstream, 'alice/feature');
+      await makeSeeder(upstream).topUpWorkspace(repoDir, 'alice/feature');
+
+      const dir = await checkout(root, upstream, 'alice/feature');
+      expect(await exists(path.join(dir, 'CLAUDE.md'))).toBe(true);
+      expect(await exists(path.join(dir, 'access.md'))).toBe(true);
+    });
+  });
+});

package/src/modules/workspace/__tests__/routine-write-policy.test.ts

@@ -0,0 +1,68 @@
+import { describe, it, expect } from 'vitest';
+import { RoutineWritePolicyService } from '../routine-write-policy.js';
+import { ToolError } from '../../tool-helpers/tool.contract.js';
+
+const SID = 'watchlistcheck-gtm-run-1';
+
+describe('RoutineWritePolicyService', () => {
+  it('allows any write when the session has no restriction', () => {
+    const policy = new RoutineWritePolicyService();
+    expect(() => policy.assertPathWritable(SID, 'knowledge-base/KnowledgeBase/Product/Knowledge/Foo.md')).not.toThrow();
+    expect(() => policy.assertUnrestricted(SID)).not.toThrow();
+  });
+
+  it('allows only the restricted extensions and blocks everything else with a 403', () => {
+    const policy = new RoutineWritePolicyService();
+    policy.restrictToExtensions(SID, ['.html', '.htm']);
+
+    // Dashboard writes pass (case-insensitive).
+    expect(() => policy.assertPathWritable(SID, 'knowledge-base/KnowledgeBase/GTM/Dashboard.html')).not.toThrow();
+    expect(() => policy.assertPathWritable(SID, 'knowledge-base/KnowledgeBase/GTM/Dashboard.HTM')).not.toThrow();
+
+    // Graph nodes and any other path are refused.
+    for (const blocked of [
+      'knowledge-base/KnowledgeBase/Product/Knowledge/sc-b2g-no-self-billing.md',
+      'knowledge-base/CLAUDE.md',
+      'knowledge-base/KnowledgeBase/GTM/notes.txt',
+      'knowledge-base/KnowledgeBase/GTM', // a directory (mkdir) — no extension
+    ]) {
+      const err = getThrown(() => policy.assertPathWritable(SID, blocked));
+      expect(err).toBeInstanceOf(ToolError);
+      expect((err as ToolError).status).toBe(403);
+    }
+  });
+
+  it('never restricts a caller with no session id', () => {
+    const policy = new RoutineWritePolicyService();
+    policy.restrictToExtensions(SID, ['.html']);
+    // A different (or absent) session id is unaffected by SID's restriction.
+    expect(() => policy.assertPathWritable(undefined, 'anything.md')).not.toThrow();
+    expect(() => policy.assertPathWritable('other-session', 'anything.md')).not.toThrow();
+    expect(() => policy.assertUnrestricted(undefined)).not.toThrow();
+  });
+
+  it('blocks the pathless shell tool for a restricted session', () => {
+    const policy = new RoutineWritePolicyService();
+    policy.restrictToExtensions(SID, ['.html']);
+    const err = getThrown(() => policy.assertUnrestricted(SID));
+    expect(err).toBeInstanceOf(ToolError);
+    expect((err as ToolError).status).toBe(403);
+  });
+
+  it('clear() lifts the restriction', () => {
+    const policy = new RoutineWritePolicyService();
+    policy.restrictToExtensions(SID, ['.html']);
+    policy.clear(SID);
+    expect(() => policy.assertPathWritable(SID, 'foo.md')).not.toThrow();
+    expect(() => policy.assertUnrestricted(SID)).not.toThrow();
+  });
+});
+
+function getThrown(fn: () => void): unknown {
+  try {
+    fn();
+  } catch (e) {
+    return e;
+  }
+  throw new Error('expected the function to throw, but it did not');
+}

package/src/modules/workspace/__tests__/session-ontology.gate.test.ts

@@ -0,0 +1,237 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+
+import {
+  recordOntologyRead,
+  assertOntologyWriteAllowed,
+  assertShellAllowedWithinOntology,
+  MissingSessionError,
+  type SessionOntologyGate,
+} from '../session-ontology.gate.js';
+import type { ToolContext } from '../../tool-helpers/tool.contract.js';
+import type { ISessionOntologyService, OperationDecision } from '../../workflow/session-ontology.service.js';
+import { WorkflowHooks } from '../../workflow/workflow-hooks.js';
+import { ontologyOf } from '../../../shared/kb-layout.js';
+
+const KB = 'knowledge-base';
+const P_FILE = 'KnowledgeBase/Product/Knowledge/Foo.md';
+const PL_FILE = 'KnowledgeBase/Platform/Knowledge/Bar.md';
+const NEUTRAL = 'access.md';
+const RECOVERY_EMAIL = 'recovery-bot@bevel.local';
+
+/**
+ * In-memory stand-in for the touched-set service — applies the real
+ * reads-record / writes-block-once-multi rule against a per-session set, so the
+ * gate's interaction with it is exercised end to end without a DB.
+ */
+function makeFakeService(): ISessionOntologyService {
+  const touched = new Map<string, Set<string>>();
+  const setFor = (s: string) => touched.get(s) ?? new Set<string>();
+  return {
+    async checkOperation(sessionId, wsPath, isWrite): Promise<OperationDecision> {
+      const ont = ontologyOf(wsPath, KB);
+      const set = setFor(sessionId);
+      if (ont === null) return { allow: true, touched: [...set].sort() };
+      if (isWrite) {
+        const spanned = new Set(set).add(ont);
+        if (spanned.size > 1) {
+          return {
+            allow: false,
+            reason: set.size >= 2 ? 'multi-ontology' : 'different-ontology',
+            touched: [...set].sort(),
+            attempted: ont,
+          };
+        }
+      }
+      set.add(ont);
+      touched.set(sessionId, set);
+      return { allow: true, touched: [...set].sort() };
+    },
+    checkOntology: async () => ({ allow: true, touched: [] }),
+    getTouched: async (s) => [...setFor(s)].sort(),
+    delete: async (s) => { touched.delete(s); },
+    sweepOlderThan: async () => 0,
+  };
+}
+
+/**
+ * Build a gate wired the way the CORE composition wires it: the fake
+ * touched-set service plus an EMPTY hooks registry. Core registers no
+ * `preWrite` hook, so the gate only TRACKS touches and never blocks — the
+ * blocking assertions (the ontology-block hook the enterprise composition
+ * root registers) live with that hook in the enterprise repo.
+ */
+function makeGate(): SessionOntologyGate {
+  const service = makeFakeService();
+  const hooks = new WorkflowHooks();
+  return { service, enabled: true, kbDirName: KB, recoveryBotEmail: RECOVERY_EMAIL, hooks };
+}
+
+function ctx(overrides: Partial<ToolContext> = {}): ToolContext {
+  return {
+    user: { id: 'u1', email: 'dev@bevel.local', name: 'Dev' },
+    scope: 'write',
+    source: 'internal',
+    sessionId: 's1',
+    abortSignal: new AbortController().signal,
+    workspaceService: {} as never,
+    workflowService: {} as never,
+    events: {} as never,
+    getFilesystem: async () => ({} as never),
+    ...overrides,
+  };
+}
+
+describe('recordOntologyRead', () => {
+  let gate: SessionOntologyGate;
+
+  beforeEach(() => {
+    gate = makeGate();
+  });
+
+  it('does nothing when the flag is disabled', async () => {
+    gate.enabled = false;
+    await expect(recordOntologyRead(gate, ctx(), P_FILE)).resolves.toBeUndefined();
+    expect(await gate.service.getTouched('s1')).toEqual([]);
+  });
+
+  it('skips neutral paths (no record)', async () => {
+    await expect(recordOntologyRead(gate, ctx(), NEUTRAL)).resolves.toBeUndefined();
+    expect(await gate.service.getTouched('s1')).toEqual([]);
+  });
+
+  it('skips non-agent (browser session) callers', async () => {
+    await expect(
+      recordOntologyRead(gate, ctx({ source: 'session', sessionId: undefined }), P_FILE),
+    ).resolves.toBeUndefined();
+  });
+
+  it('skips the recovery bot by identity', async () => {
+    await expect(
+      recordOntologyRead(
+        gate,
+        ctx({ user: { id: 'bot', email: 'Recovery-Bot@Bevel.Local', name: 'bot' }, sessionId: undefined }),
+        PL_FILE,
+      ),
+    ).resolves.toBeUndefined();
+  });
+
+  it('fails closed when an agent read of a named path has no session id', async () => {
+    await expect(recordOntologyRead(gate, ctx({ sessionId: undefined }), P_FILE)).rejects.toBeInstanceOf(
+      MissingSessionError,
+    );
+  });
+
+  it('allows a neutral read without a session id', async () => {
+    await expect(recordOntologyRead(gate, ctx({ sessionId: undefined }), NEUTRAL)).resolves.toBeUndefined();
+  });
+
+  it('records a read and allows it', async () => {
+    await recordOntologyRead(gate, ctx(), P_FILE);
+    expect(await gate.service.getTouched('s1')).toEqual(['KnowledgeBase/Product']);
+  });
+
+  it('allows reads across ontologies (recording both)', async () => {
+    await recordOntologyRead(gate, ctx(), P_FILE);
+    await expect(recordOntologyRead(gate, ctx(), PL_FILE)).resolves.toBeUndefined();
+    expect(await gate.service.getTouched('s1')).toEqual(['KnowledgeBase/Platform', 'KnowledgeBase/Product']);
+  });
+
+  it('never blocks — a read into a second ontology still passes (delete_file relies on this)', async () => {
+    await recordOntologyRead(gate, ctx(), P_FILE);
+    // A delete_file in a different ontology records its touch but never throws.
+    await expect(recordOntologyRead(gate, ctx(), PL_FILE)).resolves.toBeUndefined();
+  });
+});
+
+describe('assertOntologyWriteAllowed', () => {
+  let gate: SessionOntologyGate;
+
+  beforeEach(() => {
+    gate = makeGate();
+  });
+
+  it('does nothing when the flag is disabled', async () => {
+    gate.enabled = false;
+    // Even a cross-ontology write must pass when disabled.
+    await recordOntologyRead(gate, ctx(), P_FILE);
+    await expect(assertOntologyWriteAllowed(gate, ctx(), PL_FILE)).resolves.toBeUndefined();
+  });
+
+  it('skips neutral paths (no record, no block)', async () => {
+    await expect(assertOntologyWriteAllowed(gate, ctx(), NEUTRAL)).resolves.toBeUndefined();
+    expect(await gate.service.getTouched('s1')).toEqual([]);
+  });
+
+  it('fails closed when an agent write of a named path has no session id', async () => {
+    await expect(assertOntologyWriteAllowed(gate, ctx({ sessionId: undefined }), P_FILE)).rejects.toBeInstanceOf(
+      MissingSessionError,
+    );
+  });
+
+  it('allows a write confined to the one touched ontology', async () => {
+    await recordOntologyRead(gate, ctx(), P_FILE);
+    await expect(assertOntologyWriteAllowed(gate, ctx(), P_FILE)).resolves.toBeUndefined();
+  });
+
+  // NOTE (core split): the "blocks a write to a different ontology" and
+  // "blocks ALL writes once the session has read across two ontologies" cases
+  // moved with the ontology-block hook (`registerOntologyBlockHook`) to the
+  // enterprise repo — core registers no preWrite hook, so a core-only
+  // deployment TRACKS but never blocks. The tests below pin exactly that.
+
+  it('core: allows a write to a different ontology (tracking only, no block hook)', async () => {
+    await recordOntologyRead(gate, ctx(), P_FILE);
+    await expect(assertOntologyWriteAllowed(gate, ctx(), PL_FILE)).resolves.toBeUndefined();
+  });
+
+  it('core: still allows writes after reading across two ontologies (no block hook)', async () => {
+    await recordOntologyRead(gate, ctx(), P_FILE);
+    await recordOntologyRead(gate, ctx(), PL_FILE);
+    await expect(assertOntologyWriteAllowed(gate, ctx(), P_FILE)).resolves.toBeUndefined();
+  });
+});
+
+describe('assertShellAllowedWithinOntology (shell / no-path tools)', () => {
+  let gate: SessionOntologyGate;
+
+  beforeEach(() => {
+    gate = makeGate();
+  });
+
+  it('allows a fresh session (nothing touched)', async () => {
+    await expect(assertShellAllowedWithinOntology(gate, ctx())).resolves.toBeUndefined();
+  });
+
+  it('allows a session confined to a single ontology', async () => {
+    await recordOntologyRead(gate, ctx(), P_FILE);
+    await expect(assertShellAllowedWithinOntology(gate, ctx())).resolves.toBeUndefined();
+  });
+
+  // NOTE (core split): the "blocks once the session has crossed into two
+  // ontologies" case moved with the enterprise ontology-block hook. Core
+  // registers no preWrite hook, so shell is never refused here.
+  it('core: allows shell even after crossing into two ontologies (no block hook)', async () => {
+    await recordOntologyRead(gate, ctx(), P_FILE);
+    await recordOntologyRead(gate, ctx(), PL_FILE);
+    await expect(assertShellAllowedWithinOntology(gate, ctx())).resolves.toBeUndefined();
+  });
+
+  it('does nothing when the flag is disabled', async () => {
+    gate.enabled = false;
+    await gate.service.checkOperation('s1', P_FILE, false);
+    await gate.service.checkOperation('s1', PL_FILE, false);
+    await expect(assertShellAllowedWithinOntology(gate, ctx())).resolves.toBeUndefined();
+  });
+
+  it('exempts the recovery bot', async () => {
+    await gate.service.checkOperation('s1', P_FILE, false);
+    await gate.service.checkOperation('s1', PL_FILE, false);
+    await expect(
+      assertShellAllowedWithinOntology(gate, ctx({ user: { id: 'bot', email: RECOVERY_EMAIL, name: 'bot' } })),
+    ).resolves.toBeUndefined();
+  });
+
+  it('allows when there is no session id (nothing to evaluate)', async () => {
+    await expect(assertShellAllowedWithinOntology(gate, ctx({ sessionId: undefined }))).resolves.toBeUndefined();
+  });
+});

package/src/modules/workspace/__tests__/spill-store.test.ts

@@ -0,0 +1,43 @@
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { SpillStore } from '../spill-store.js';
+
+describe('SpillStore', () => {
+  let root: string;
+  let store: SpillStore;
+
+  beforeEach(async () => {
+    root = await mkdtemp(join(tmpdir(), 'spill-test-'));
+    store = new SpillStore(root);
+  });
+  afterEach(async () => {
+    await rm(root, { recursive: true, force: true });
+  });
+
+  it('round-trips content under a recognisable spill ref', async () => {
+    const { ref, bytes } = await store.write('hello world');
+    expect(store.isSpillRef(ref)).toBe(true);
+    expect(ref.startsWith('__tool_chain_spill__/')).toBe(true);
+    expect(bytes).toBe('hello world'.length);
+    expect(await store.read(ref)).toBe('hello world');
+  });
+
+  it('slices by offset/limit (byte range, read off disk)', async () => {
+    const { ref } = await store.write('0123456789');
+    expect(await store.read(ref, 3)).toBe('3456789');
+    expect(await store.read(ref, 2, 4)).toBe('2345');
+    expect(await store.read(ref, 0, 0)).toBe('');
+  });
+
+  it('does not treat a normal workspace path as a spill ref', () => {
+    expect(store.isSpillRef('docs/readme.md')).toBe(false);
+    expect(store.isSpillRef('knowledge-base/CLAUDE.md')).toBe(false);
+  });
+
+  it('rejects a ref whose id tries to escape the store', async () => {
+    await expect(store.read('__tool_chain_spill__/../secret')).rejects.toThrow(/invalid spill ref/i);
+    await expect(store.read('__tool_chain_spill__/a/b.json')).rejects.toThrow(/invalid spill ref/i);
+  });
+});