@treenity/core 1.0.48 → 3.0.1

package/src/tree/fs.test.ts

@@ -0,0 +1,247 @@
+import { createNode } from '#core';
+import assert from 'node:assert/strict';
+import { mkdtemp, rm, stat } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, describe, it } from 'node:test';
+import { createFsTree } from './fs';
+import { mapSiftQuery } from './query';
+
+describe('FsStore', () => {
+  let dir: string;
+
+  afterEach(async () => {
+    if (dir) await rm(dir, { recursive: true, force: true });
+  });
+
+  async function setup() {
+    dir = await mkdtemp(join(tmpdir(), 'treenity-fs-test-'));
+    return createFsTree(dir);
+  }
+
+  function exists(path: string) {
+    return stat(join(dir, path)).then(() => true, () => false);
+  }
+
+  it('set and get', async () => {
+    const store = await setup();
+    const node = createNode('/users/alice', 'user');
+    await store.set(node);
+    assert.deepEqual(await store.get('/users/alice'), node);
+  });
+
+  it('get returns undefined for missing', async () => {
+    const store = await setup();
+    assert.equal(await store.get('/nope'), undefined);
+  });
+
+  it('getChildren direct', async () => {
+    const store = await setup();
+    await store.set(createNode('/app', 'root'));
+    await store.set(createNode('/app/a', 'item'));
+    await store.set(createNode('/app/b', 'item'));
+    await store.set(createNode('/app/a/deep', 'item'));
+
+    const children = await store.getChildren('/app');
+    assert.equal(children.items.length, 2);
+    assert.deepEqual(children.items.map((n) => n.$path).sort(), ['/app/a', '/app/b']);
+  });
+
+  it('getChildren with depth', async () => {
+    const store = await setup();
+    await store.set(createNode('/x', 'root'));
+    await store.set(createNode('/x/a', 'item'));
+    await store.set(createNode('/x/a/b', 'item'));
+    await store.set(createNode('/x/a/b/c', 'item'));
+
+    const d2 = await store.getChildren('/x', { depth: 2 });
+    assert.equal(d2.items.length, 2);
+    assert.deepEqual(d2.items.map((n) => n.$path).sort(), ['/x/a', '/x/a/b']);
+
+    const all = await store.getChildren('/x', { depth: Infinity });
+    assert.equal(all.items.length, 3);
+  });
+
+  it('remove', async () => {
+    const store = await setup();
+    await store.set(createNode('/z', 'item'));
+    assert.equal(await store.remove('/z'), true);
+    assert.equal(await store.get('/z'), undefined);
+    assert.equal(await store.remove('/z'), false);
+  });
+
+  it('handles nested paths', async () => {
+    const store = await setup();
+    const node = createNode('/a/b/c/d/e', 'deep');
+    await store.set(node);
+    assert.deepEqual(await store.get('/a/b/c/d/e'), node);
+  });
+
+  // ── Storage format tests ──
+
+  it('leaf node stored as name.json', async () => {
+    const store = await setup();
+    await store.set(createNode('/leaf', 'item'));
+
+    assert.ok(await exists('leaf.json'), 'leaf.json should exist');
+    assert.ok(!(await exists('leaf/$.json')), 'leaf/$.json should NOT exist');
+  });
+
+  it('root always stored as $/$.json (dir form)', async () => {
+    const store = await setup();
+    await store.set(createNode('/', 'root'));
+
+    assert.ok(await exists('$.json'), 'root $.json should exist');
+  });
+
+  it('auto-promotes leaf to dir when child is created', async () => {
+    const store = await setup();
+    await store.set(createNode('/parent', 'dir'));
+
+    // Initially leaf form
+    assert.ok(await exists('parent.json'), 'should be leaf form');
+    assert.ok(!(await exists('parent/$.json')), 'should NOT be dir form yet');
+
+    // Add child — parent must be promoted to dir form
+    await store.set(createNode('/parent/child', 'item'));
+
+    assert.ok(await exists('parent/$.json'), 'parent should now be dir form');
+    assert.ok(!(await exists('parent.json')), 'parent.json should be gone');
+    assert.ok(await exists('parent/child.json'), 'child should be leaf form');
+
+    // Both nodes still readable
+    const parent = await store.get('/parent');
+    assert.equal(parent?.$type, 't.dir');
+    const child = await store.get('/parent/child');
+    assert.equal(child?.$type, 't.item');
+  });
+
+  it('auto-demotes dir to leaf when last child is removed', async () => {
+    const store = await setup();
+    await store.set(createNode('/parent', 'dir'));
+    await store.set(createNode('/parent/child', 'item'));
+
+    // Parent in dir form
+    assert.ok(await exists('parent/$.json'));
+
+    // Remove the child
+    await store.remove('/parent/child');
+
+    // Parent should be demoted to leaf form
+    assert.ok(await exists('parent.json'), 'parent should be demoted to leaf form');
+    assert.ok(!(await exists('parent/$.json')), 'parent dir form should be gone');
+
+    // Parent still readable
+    const parent = await store.get('/parent');
+    assert.equal(parent?.$type, 't.dir');
+  });
+
+  it('node with children stays in dir form on re-save', async () => {
+    const store = await setup();
+    await store.set(createNode('/p', 'dir'));
+    await store.set(createNode('/p/a', 'item'));
+
+    // Re-save parent — should stay dir form because it has children
+    const p = await store.get('/p');
+    await store.set({ ...p!, $rev: p!.$rev });
+
+    assert.ok(await exists('p/$.json'), 'should remain dir form');
+    assert.ok(!(await exists('p.json')), 'should not have leaf form');
+  });
+
+  it('deep promotion chain', async () => {
+    const store = await setup();
+    await store.set(createNode('/a', 'n'));
+    await store.set(createNode('/a/b', 'n'));
+
+    // Both start as leaves where possible
+    assert.ok(await exists('a/$.json'), 'a has child b → dir form');
+    assert.ok(await exists('a/b.json'), 'b is leaf');
+
+    // Create deep child — b must promote
+    await store.set(createNode('/a/b/c', 'n'));
+
+    assert.ok(await exists('a/b/$.json'), 'b promoted to dir form');
+    assert.ok(!(await exists('a/b.json')), 'b.json gone');
+    assert.ok(await exists('a/b/c.json'), 'c is leaf');
+  });
+
+  it('deep demotion chain', async () => {
+    const store = await setup();
+    await store.set(createNode('/a', 'n'));
+    await store.set(createNode('/a/b', 'n'));
+    await store.set(createNode('/a/b/c', 'n'));
+
+    // Remove c — b should demote, a should demote too (b.json is still a child of a)
+    await store.remove('/a/b/c');
+
+    assert.ok(await exists('a/b.json'), 'b demoted to leaf');
+    assert.ok(await exists('a/$.json'), 'a still dir form (has child b.json)');
+
+    // Remove b — a should demote
+    await store.remove('/a/b');
+
+    assert.ok(await exists('a.json'), 'a demoted to leaf');
+    assert.ok(!(await exists('a/$.json')), 'a dir form gone');
+  });
+
+  it('data integrity through promotion/demotion', async () => {
+    const store = await setup();
+    const parent = createNode('/p', 'dir', { label: 'parent' });
+    await store.set(parent);
+
+    const child = createNode('/p/c', 'item', { label: 'child' });
+    await store.set(child);
+
+    // Verify data survived promotion
+    const p = await store.get('/p');
+    assert.equal((p as any).label, 'parent');
+
+    await store.remove('/p/c');
+
+    // Verify data survived demotion
+    const p2 = await store.get('/p');
+    assert.equal((p2 as any).label, 'parent');
+  });
+
+  it('OCC still works across storage forms', async () => {
+    const store = await setup();
+    await store.set(createNode('/n', 'item'));
+    const n = await store.get('/n');
+
+    // Promote by adding child
+    await store.set(createNode('/n/child', 'item'));
+
+    // OCC should still work on promoted node
+    await assert.rejects(() => store.set({ ...n!, $rev: 999 }));
+  });
+
+  it('getChildren applies sift query filter', async () => {
+    const store = await setup();
+    await store.set(createNode('/tasks', 'dir'));
+    await store.set(createNode('/tasks/t1', 'task', { status: 'pending' }));
+    await store.set(createNode('/tasks/t2', 'task', { status: 'done' }));
+    await store.set(createNode('/tasks/t3', 'task', { status: 'pending' }));
+
+    const pending = await store.getChildren('/tasks', {
+      query: mapSiftQuery({ $type: 't.task', status: 'pending' }) as Record<string, unknown>,
+    });
+    assert.equal(pending.items.length, 2);
+    assert.deepEqual(pending.items.map(n => n.$path).sort(), ['/tasks/t1', '/tasks/t3']);
+  });
+
+  it('getChildren sift filter excludes non-matching types', async () => {
+    const store = await setup();
+    await store.set(createNode('/parent', 'config'));
+    await store.set(createNode('/parent/mount-a', 'mount-point'));
+    await store.set(createNode('/parent/mount-b', 'mount-point'));
+    await store.set(createNode('/parent/t1', 'task', { status: 'pending' }));
+    await store.set(createNode('/parent/t2', 'task', { status: 'done' }));
+
+    const tasks = await store.getChildren('/parent', {
+      query: mapSiftQuery({ $type: 't.task' }) as Record<string, unknown>,
+    });
+    assert.equal(tasks.items.length, 2);
+    assert.ok(tasks.items.every(n => n.$type === 't.task'));
+  });
+});

package/src/tree/fs.ts

@@ -0,0 +1,257 @@
+// Treenity FS Tree — Layer 1
+// Stores nodes as JSON files on disk.
+// Leaf nodes → name.json, directory nodes (with children) → name/$.json
+// Auto-promotes leaf→dir when children appear, demotes dir→leaf when last child removed.
+
+import type { NodeData } from '#core';
+import { dirname as treeDirname } from '#core/path';
+import { mkdir, readdir, readFile, rmdir, unlink, writeFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import sift from 'sift';
+import type { Tree } from './index';
+import { paginate } from './index';
+import { defaultPatch } from './patch';
+import { mapNodeForSift } from './query';
+
+function securityCheck(root: string, file: string) {
+  if (!file.startsWith(resolve(root))) throw new Error(`Path traversal blocked`);
+}
+
+export async function createFsTree(rootDir: string): Promise<Tree> {
+  rootDir = resolve(rootDir);
+  await mkdir(rootDir, { recursive: true });
+
+  // Per-path write queue — serializes concurrent writes to the same file
+  const writeQueues = new Map<string, Promise<void>>();
+  function enqueue(path: string, fn: () => Promise<void>): Promise<void> {
+    const prev = writeQueues.get(path) ?? Promise.resolve();
+    const next = prev.then(fn, fn);
+    const cleanup = () => { if (writeQueues.get(path) === next) writeQueues.delete(path); };
+    next.then(cleanup, cleanup);
+    writeQueues.set(path, next);
+    return next;
+  }
+
+  // Read node from whichever form exists: dir (path/$.json) or leaf (path.json)
+  async function readNode(path: string): Promise<NodeData | undefined> {
+    const dirFile = resolve(join(rootDir, path, '$.json'));
+    securityCheck(rootDir, dirFile);
+    try {
+      return JSON.parse(await readFile(dirFile, 'utf-8'));
+    } catch (e: any) {
+      if (e.code === 'ENOENT') { /* fall through to leaf form */ }
+      else throw e; // SyntaxError = corrupted JSON, propagate loudly
+    }
+
+    if (path !== '/') {
+      const leafFile = resolve(join(rootDir, path + '.json'));
+      securityCheck(rootDir, leafFile);
+      try {
+        return JSON.parse(await readFile(leafFile, 'utf-8'));
+      } catch (e: any) {
+        if (e.code === 'ENOENT') { /* not found */ }
+        else throw e;
+      }
+    }
+
+    return undefined;
+  }
+
+  // Promote a node from leaf form (path.json) to dir form (path/$.json)
+  async function promoteIfNeeded(path: string): Promise<void> {
+    if (path === '/') return;
+    const leafFile = resolve(join(rootDir, path + '.json'));
+    try {
+      const data = await readFile(leafFile, 'utf-8');
+      const dir = resolve(join(rootDir, path));
+      await mkdir(dir, { recursive: true });
+      await writeFile(join(dir, '$.json'), data);
+      await unlink(leafFile);
+    } catch (e: any) {
+      if (e.code !== 'ENOENT') throw e;
+    }
+  }
+
+  // Promote all ancestors that might be in leaf form
+  async function promoteAncestors(path: string): Promise<void> {
+    const parts = path === '/' ? [] : path.slice(1).split('/');
+    for (let i = 0; i < parts.length - 1; i++) {
+      await promoteIfNeeded('/' + parts.slice(0, i + 1).join('/'));
+    }
+  }
+
+  // Check if a node's directory has children (entries beyond $.json)
+  async function hasChildren(path: string): Promise<boolean> {
+    const dir = resolve(join(rootDir, path));
+    try {
+      const entries = await readdir(dir);
+      return entries.some(e => e !== '$.json');
+    } catch (e: any) {
+      if (e.code === 'ENOENT') return false;
+      throw e;
+    }
+  }
+
+  // After removing a node, clean up empty dirs and demote childless parents
+  async function cleanupAfterRemove(removedPath: string): Promise<void> {
+    // Remove the node's now-empty directory if it exists
+    try {
+      const nodeDir = resolve(join(rootDir, removedPath));
+      const entries = await readdir(nodeDir);
+      if (entries.length === 0) await rmdir(nodeDir);
+    } catch (e: any) {
+      if (e.code !== 'ENOENT') console.error(`[fs] cleanup error at ${removedPath}:`, e);
+    }
+
+    // Walk up and demote parents that lost their last child
+    let current = treeDirname(removedPath);
+    while (current && current !== '/') {
+      const dir = resolve(join(rootDir, current));
+      try {
+        const entries = await readdir(dir);
+        if (entries.length === 1 && entries[0] === '$.json') {
+          // Only $.json remains — demote to leaf form
+          const data = await readFile(join(dir, '$.json'), 'utf-8');
+          await unlink(join(dir, '$.json'));
+          await rmdir(dir);
+          await writeFile(resolve(join(rootDir, current + '.json')), data);
+        } else if (entries.length === 0) {
+          await rmdir(dir);
+        } else {
+          break; // still has children
+        }
+      } catch (e: any) {
+        if (e.code !== 'ENOENT') console.error(`[fs] demotion walk error at ${current}:`, e);
+        break;
+      }
+      current = treeDirname(current);
+    }
+  }
+
+  // Collect children of a tree path up to given depth by walking only the relevant FS subtree
+  async function collectChildren(parent: string, depth: number): Promise<NodeData[]> {
+    const results: NodeData[] = [];
+    const fsDir = resolve(join(rootDir, parent));
+
+    async function walk(dir: string, currentDepth: number) {
+      let entries;
+      try { entries = await readdir(dir, { withFileTypes: true }); } catch (e: any) {
+        if (e.code === 'ENOENT') return;
+        throw e;
+      }
+
+      for (const e of entries) {
+        if (e.name === '$.json') continue; // parent's own data, not a child
+        const full = join(dir, e.name);
+
+        if (e.isDirectory()) {
+          // Directory child — read its $.json if exists
+          const childPath = full.slice(rootDir.length) || '/';
+          const node = await readNode(childPath);
+          if (node) results.push(node);
+          if (currentDepth < depth) await walk(full, currentDepth + 1);
+        } else if (e.name.endsWith('.json')) {
+          // Leaf child — name.json
+          const node: NodeData = JSON.parse(await readFile(full, 'utf-8'));
+          results.push(node);
+        }
+      }
+    }
+
+    await walk(fsDir, 1);
+    return results;
+  }
+
+  const tree: Tree = {
+    async get(path) {
+      return readNode(path);
+    },
+
+    async getChildren(parent, opts) {
+      const depth = opts?.depth ?? 1;
+      let filtered = await collectChildren(parent, depth);
+      if (opts?.query) {
+        const test = sift(opts.query);
+        filtered = filtered.filter(n => test(mapNodeForSift(n)));
+      }
+      return paginate(filtered, opts);
+    },
+
+    async set(node) {
+      return enqueue(node.$path, async () => {
+        const path = node.$path;
+
+        await promoteAncestors(path);
+
+        // OCC check
+        if (node.$rev != null) {
+          const existing = await readNode(path);
+          if (!existing) {
+            throw new Error(`OptimisticConcurrencyError: node ${path} does not exist but $rev was provided`);
+          }
+          if (existing.$rev !== node.$rev) {
+            throw new Error(`OptimisticConcurrencyError: node ${path} modified by another transaction. Expected $rev ${existing.$rev}, got ${node.$rev}`);
+          }
+        }
+
+        node.$rev = (node.$rev ?? 0) + 1;
+        const data = JSON.stringify(node, null, 2) + '\n';
+
+        if (path === '/' || await hasChildren(path)) {
+          // Dir form: has children
+          const dirFile = resolve(join(rootDir, path, '$.json'));
+          securityCheck(rootDir, dirFile);
+          await mkdir(resolve(join(rootDir, path)), { recursive: true });
+          await writeFile(dirFile, data);
+          // Clean up stale leaf form
+          if (path !== '/') {
+            try { await unlink(resolve(join(rootDir, path + '.json'))); } catch (e: any) { if (e.code !== 'ENOENT') throw e; }
+          }
+        } else {
+          // Leaf form: no children
+          const leafFile = resolve(join(rootDir, path + '.json'));
+          securityCheck(rootDir, leafFile);
+          await mkdir(dirname(leafFile), { recursive: true });
+          await writeFile(leafFile, data);
+          // Clean up stale dir form + empty dir
+          try { await unlink(resolve(join(rootDir, path, '$.json'))); } catch (e: any) { if (e.code !== 'ENOENT') throw e; }
+          try { await rmdir(resolve(join(rootDir, path))); } catch (e: any) { if (e.code !== 'ENOENT' && e.code !== 'ENOTEMPTY') throw e; }
+        }
+      });
+    },
+
+    async remove(path) {
+      // Try dir form first
+      const dirFile = resolve(join(rootDir, path, '$.json'));
+      securityCheck(rootDir, dirFile);
+      try {
+        await unlink(dirFile);
+        await cleanupAfterRemove(path);
+        return true;
+      } catch (e: any) {
+        if (e.code !== 'ENOENT') throw e;
+      }
+
+      // Try leaf form
+      if (path !== '/') {
+        const leafFile = resolve(join(rootDir, path + '.json'));
+        securityCheck(rootDir, leafFile);
+        try {
+          await unlink(leafFile);
+          await cleanupAfterRemove(path);
+          return true;
+        } catch (e: any) {
+          if (e.code !== 'ENOENT') throw e;
+        }
+      }
+
+      return false;
+    },
+
+    async patch(path, ops, ctx) {
+      return defaultPatch(readNode, (n) => tree.set(n, ctx), path, ops, ctx);
+    },
+  };
+
+  return tree;
+}

package/src/tree/index.test.ts

@@ -0,0 +1,190 @@
+import { createNode } from '#core';
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import { createMemoryTree, createOverlayTree } from './index';
+
+describe('MemoryStore', () => {
+  it('set and get', async () => {
+    const store = createMemoryTree();
+    const node = createNode('/tasks/1', 'task');
+    await store.set(node);
+    assert.deepEqual(await store.get('/tasks/1'), node);
+  });
+
+  it('get returns undefined for missing', async () => {
+    const store = createMemoryTree();
+    assert.equal(await store.get('/nope'), undefined);
+  });
+
+  it('getChildren returns direct children only', async () => {
+    const store = createMemoryTree();
+    await store.set(createNode('/bot', 'bot'));
+    await store.set(createNode('/bot/commands', 'dir'));
+    await store.set(createNode('/bot/commands/start', 'page'));
+    await store.set(createNode('/bot/commands/help', 'page'));
+    await store.set(createNode('/bot/config', 'config'));
+
+    const { items: botChildren } = await store.getChildren('/bot');
+    assert.equal(botChildren.length, 2);
+    assert.deepEqual(botChildren.map((n) => n.$path).sort(), ['/bot/commands', '/bot/config']);
+
+    const { items: commands } = await store.getChildren('/bot/commands');
+    assert.equal(commands.length, 2);
+    assert.deepEqual(commands.map((n) => n.$path).sort(), [
+      '/bot/commands/help',
+      '/bot/commands/start',
+    ]);
+  });
+
+  it('getChildren with depth=2 returns two levels', async () => {
+    const store = createMemoryTree();
+    await store.set(createNode('/a', 'dir'));
+    await store.set(createNode('/a/b', 'dir'));
+    await store.set(createNode('/a/b/c', 'item'));
+    await store.set(createNode('/a/b/c/d', 'item'));
+    await store.set(createNode('/a/x', 'item'));
+
+    const { items } = await store.getChildren('/a', { depth: 2 });
+    assert.equal(items.length, 3);
+    assert.deepEqual(items.map((n) => n.$path).sort(), ['/a/b', '/a/b/c', '/a/x']);
+  });
+
+  it('getChildren with depth=Infinity returns all descendants', async () => {
+    const store = createMemoryTree();
+    await store.set(createNode('/r', 'root'));
+    await store.set(createNode('/r/a', 'dir'));
+    await store.set(createNode('/r/a/b', 'dir'));
+    await store.set(createNode('/r/a/b/c', 'item'));
+
+    const result = await store.getChildren('/r', { depth: Infinity });
+    assert.equal(result.items.length, 3);
+    assert.deepEqual(result.items.map((n) => n.$path).sort(), ['/r/a', '/r/a/b', '/r/a/b/c']);
+  });
+
+  it('remove', async () => {
+    const store = createMemoryTree();
+    await store.set(createNode('/x', 'x'));
+    assert.equal(await store.remove('/x'), true);
+    assert.equal(await store.get('/x'), undefined);
+    assert.equal(await store.remove('/x'), false);
+  });
+
+  it('getChildren with limit', async () => {
+    const store = createMemoryTree();
+    await store.set(createNode('/p', 'dir'));
+    await store.set(createNode('/p/a', 'item'));
+    await store.set(createNode('/p/b', 'item'));
+    await store.set(createNode('/p/c', 'item'));
+
+    const result = await store.getChildren('/p', { limit: 2 });
+    assert.equal(result.items.length, 2);
+    assert.equal(result.total, 3);
+  });
+
+  it('remove does not cascade to children', async () => {
+    const store = createMemoryTree();
+    await store.set(createNode('/a', 'dir'));
+    await store.set(createNode('/a/b', 'item'));
+    await store.set(createNode('/a/b/c', 'item'));
+    assert.equal(await store.remove('/a'), true);
+    assert.equal(await store.get('/a'), undefined);
+    assert.equal((await store.get('/a/b'))?.$type, 't.item');
+    assert.equal((await store.get('/a/b/c'))?.$type, 't.item');
+  });
+
+  it('getChildren with limit and offset', async () => {
+    const store = createMemoryTree();
+    await store.set(createNode('/p', 'dir'));
+    await store.set(createNode('/p/a', 'item'));
+    await store.set(createNode('/p/b', 'item'));
+    await store.set(createNode('/p/c', 'item'));
+
+    const all = await store.getChildren('/p');
+    const result = await store.getChildren('/p', { limit: 2, offset: 1 });
+    assert.equal(result.items.length, 2);
+    assert.equal(result.total, 3);
+    assert.deepEqual(result.items, all.items.slice(1, 3));
+  });
+
+  it('get returns isolated copy — mutating result does not affect stored node', async () => {
+    const store = createMemoryTree();
+    await store.set(createNode('/x', 'item', { tags: ['a', 'b'] }));
+
+    const copy = await store.get('/x') as any;
+    copy.tags.push('mutated');
+    copy.extra = 'injected';
+
+    const stored = await store.get('/x') as any;
+    assert.deepEqual(stored.tags, ['a', 'b']);
+    assert.equal(stored.extra, undefined);
+  });
+
+  it('set stores isolated copy — mutating original after set does not affect stored node', async () => {
+    const store = createMemoryTree();
+    const node = createNode('/y', 'item', { value: 1 }) as any;
+    await store.set(node);
+
+    node.value = 999;
+    node.injected = true;
+
+    const stored = await store.get('/y') as any;
+    assert.equal(stored.value, 1);
+    assert.equal(stored.injected, undefined);
+  });
+
+});
+
+describe('OverlayStore', () => {
+  it('reads from upper first', async () => {
+    const upper = createMemoryTree();
+    const lower = createMemoryTree();
+    await upper.set(createNode('/a', 'upper'));
+    await lower.set(createNode('/a', 'lower'));
+    const store = createOverlayTree(upper, lower);
+    const node = await store.get('/a');
+    assert.equal(node?.$type, 't.upper');
+  });
+
+  it('falls back to lower on miss', async () => {
+    const upper = createMemoryTree();
+    const lower = createMemoryTree();
+    await lower.set(createNode('/b', 'lower'));
+    const store = createOverlayTree(upper, lower);
+    assert.equal((await store.get('/b'))?.$type, 't.lower');
+  });
+
+  it('writes go to upper only', async () => {
+    const upper = createMemoryTree();
+    const lower = createMemoryTree();
+    const store = createOverlayTree(upper, lower);
+    await store.set(createNode('/c', 'new'));
+    assert.equal((await upper.get('/c'))?.$type, 't.new');
+    assert.equal(await lower.get('/c'), undefined);
+  });
+
+  it('getChildren merges, upper wins', async () => {
+    const upper = createMemoryTree();
+    const lower = createMemoryTree();
+    await lower.set(createNode('/p/a', 'lower'));
+    await lower.set(createNode('/p/b', 'lower'));
+    await upper.set(createNode('/p/b', 'upper'));
+    await upper.set(createNode('/p/c', 'upper'));
+    const store = createOverlayTree(upper, lower);
+    const { items } = await store.getChildren('/p');
+    assert.equal(items.length, 3);
+    const map = Object.fromEntries(items.map((n) => [n.$path, n.$type]));
+    assert.equal(map['/p/a'], 't.lower');
+    assert.equal(map['/p/b'], 't.upper');
+    assert.equal(map['/p/c'], 't.upper');
+  });
+
+  it('remove only affects upper', async () => {
+    const upper = createMemoryTree();
+    const lower = createMemoryTree();
+    await upper.set(createNode('/x', 'upper'));
+    await lower.set(createNode('/y', 'lower'));
+    const store = createOverlayTree(upper, lower);
+    assert.equal(await store.remove('/x'), true);
+    assert.equal(await store.remove('/y'), false);
+  });
+});