@treenity/core 3.0.0 → 3.0.1

package/src/server/actions.ts

@@ -117,7 +117,7 @@ async function resolveActionHandler(
 
   let deps: ResolvedDeps = await _collectDeps(node, fieldKey!, action, store);
 
-  let handler = resolve(comp, `action:${action}`);
+  let handler = resolve(type, `action:${action}`);
 
   // Fallback: try loading dynamic action from type definition node
   if (!handler) handler = await loadDynamicAction(store, type, action);

package/src/server/api.test.ts

@@ -312,6 +312,15 @@ describe('tRPC API integration', () => {
       const result = await caller.getChildren({ path: '/private' });
       assert.equal(result.items.length, 0);
     });
+
+    it('public cannot execute action on denied node', async () => {
+      // Node is inaccessible → execute returns NOT_FOUND (security: don't reveal existence)
+      await rawStore.set(createNode('/private/order', 'order.status', { status: 'new' }));
+      await assert.rejects(
+        () => caller.execute({ path: '/private/order', action: 'cook' }),
+        (e: any) => e.code === 'NOT_FOUND',
+      );
+    });
   });
 
   // ── Events ──

package/src/server/auth.ts

@@ -270,12 +270,13 @@ export function stripComponents(node: NodeData, userId: string | null, claims: s
 // ── Build claims ──
 
 export async function buildClaims(store: Tree, userId: string): Promise<string[]> {
-  const claims = [`u:${userId}`, 'authenticated'];
+  const group = userId.startsWith('anon:') ? 'public' : 'authenticated';
+  const claims = [`u:${userId}`, group];
   const userNode = await store.get(`/auth/users/${userId}`);
   if (userNode) {
     const gv = userNode['groups'];
-    const groups = isComponent(gv) ? gv as { $type: string; list?: string[] } : undefined;
-    if (groups?.list) claims.push(...groups.list);
+    const groups = isComponent(gv) ? gv : undefined;
+    if (Array.isArray(groups?.['list'])) claims.push(...groups['list']);
   }
   return claims;
 }

package/src/server/client.ts

@@ -17,7 +17,7 @@ export function createClient(url: string, token?: string) {
           EventSource: EventSource as any,
           connectionParams: () => (token ? { token } : {}),
         }),
-        false: httpBatchLink({ url, headers: () => headers }),
+        false: httpBatchLink({ url, maxURLLength: 2048, headers: () => headers }),
       }),
     ],
   });

package/src/server/coverage.test.ts

@@ -51,7 +51,7 @@ describe('Mount adapters', () => {
     register('t.mount.query', 'mount', (config: any, parentStore: Tree, _ctx: any, globalStore?: Tree) => {
       const n = config as NodeData;
       const qv = n['query'];
-      const query = isComponent(qv) ? qv as { source: string; match: Record<string, unknown> } : undefined;
+      const query = isComponent(qv) ? qv as unknown as { source: string; match: Record<string, unknown> } : undefined;
       if (!query?.source || !query?.match) throw new Error("t.mount.query requires 'query' component with source and match");
       return createQueryTree({ source: query.source, match: query.match }, globalStore || parentStore);
     });

package/src/server/doc-index.ts

@@ -116,23 +116,24 @@ function collectFiles(projectRoot: string, memoryDir?: string): string[] {
     for (const f of walkDir(memoryDir, new Set(['.md']))) files.add(f);
   }
 
-  // Core layers: full source
-  for (const d of ['src/core', 'src/store', 'src/comp', 'src/server']) {
+  // Core layers: full source (engine/core/src/*)
+  for (const d of ['engine/core/src/core', 'engine/core/src/tree', 'engine/core/src/comp', 'engine/core/src/server', 'engine/core/src/schema', 'engine/core/src/client']) {
     for (const f of walkDir(join(projectRoot, d), new Set(['.ts']), /\.test\.ts$/)) files.add(f);
   }
 
-  // Mods: types.ts, service.ts, client.ts, CLAUDE.md (CLAUDE.md already caught above)
-  for (const f of walkDir(join(projectRoot, 'src/mods'), new Set(['.ts']), /\.test\.ts$/)) {
-    const name = basename(f);
-    if (['types.ts', 'service.ts', 'client.ts', 'server.ts', 'mcp.ts', 'view.tsx'].includes(name)) files.add(f);
-  }
-  // Also include .tsx views from mods
-  for (const f of walkDir(join(projectRoot, 'src/mods'), new Set(['.tsx']), /\.test\.tsx$/)) {
-    files.add(f);
+  // Mods: types.ts, service.ts, etc. — engine/core/src/mods, engine/mods/*, mods/*
+  const modKeyFiles = new Set(['types.ts', 'service.ts', 'client.ts', 'server.ts', 'mcp.ts', 'view.tsx']);
+  for (const modDir of ['engine/core/src/mods', 'engine/mods', 'mods']) {
+    for (const f of walkDir(join(projectRoot, modDir), new Set(['.ts']), /\.test\.ts$/)) {
+      if (modKeyFiles.has(basename(f))) files.add(f);
+    }
+    for (const f of walkDir(join(projectRoot, modDir), new Set(['.tsx']), /\.test\.tsx$/)) {
+      files.add(f);
+    }
   }
 
-  // Frontend key files
-  for (const f of ['src/front/App.tsx', 'src/front/hooks.ts', 'src/front/cache.ts', 'src/front/trpc.ts', 'src/front/Inspector.tsx']) {
+  // Frontend key files (engine/packages/react/src/*)
+  for (const f of ['engine/packages/react/src/App.tsx', 'engine/packages/react/src/hooks.ts', 'engine/packages/react/src/cache.ts', 'engine/packages/react/src/trpc.ts']) {
     const full = join(projectRoot, f);
     if (existsSync(full)) files.add(full);
   }

package/src/server/e2e.test.ts

@@ -3,7 +3,7 @@
 // ACL security (no leaked data), and action return values.
 
 import { registerType } from '#comp';
-import { createNode, R, S, W } from '#core';
+import { createNode, R, S, W, register } from '#core';
 import { createMemoryTree } from '#tree';
 import assert from 'node:assert/strict';
 import type { Socket } from 'node:net';
@@ -97,6 +97,7 @@ describe('e2e: tRPC over HTTP', () => {
     registerType('streamer', Streamer);
     registerType('secret', Secret);
     registerType('task.priority', Priority);
+    register('test.task', 'schema', () => ({ type: 'object', title: 'Test Task' }));
   });
 
   beforeEach(async () => {
@@ -924,7 +925,7 @@ describe('e2e: tRPC over HTTP', () => {
 
       // Create new child (simulates action:task creating a task node)
       await pub.set.mutate({ node: {
-        $path: '/agent-test/tasks/t-1', $type: 'agent.task',
+        $path: '/agent-test/tasks/t-1', $type: 'test.task',
         prompt: 'test task', status: 'pending', createdAt: 12345,
       } });
 
@@ -933,7 +934,7 @@ describe('e2e: tRPC over HTTP', () => {
       assert.equal(received[0].type, 'set', 'Event type should be "set"');
       assert.equal(received[0].path, '/agent-test/tasks/t-1');
       const node = (received[0] as any).node;
-      assert.equal(node.$type, 'agent.task');
+      assert.equal(node.$type, 'test.task');
       assert.equal(node.prompt, 'test task');
       assert.equal(node.status, 'pending');
     });

package/src/server/factory.ts

@@ -1,15 +1,23 @@
-// treenity() — server factory
-// Builds the full pipeline from config, returns a composable server instance.
+// treenity() — universal server factory
+// Single entry point: loads infrastructure, mods, builds pipeline, wires logging.
+
+import '#contexts/schema/index';
+import '#contexts/text/index';
+import '#schema/load';
+import './mount-adapters';
 
 import { type ServiceHandle, startServices } from '#contexts/service/index';
-import { A, createNode, R, S, W } from '#core';
-import { loadLocalMods } from '#mod';
+import { A, createNode, type NodeData, R, S, W } from '#core';
+import { addOnLog, makeLogPath } from '#log';
+import { loadAllMods } from '#mod';
 import { createMemoryTree, type Tree } from '#tree';
 import type { Server } from 'node:http';
-import { createEnsure, type Ensure, seed as defaultSeed } from './seed';
+import { deploySeedPrefabs } from './prefab';
+import { createEnsure, type Ensure } from './seed';
 import { createHttpServer, createPipeline, type Pipeline } from './server';
 
 export type TreenityConfig = {
+  rootNode?: NodeData;
   dataDir?: string;
   modsDir?: string | false;
   seed?: (store: Tree, ensure: Ensure) => Promise<void>;
@@ -36,35 +44,49 @@ export async function treenity(config?: TreenityConfig): Promise<TreenityServer>
 
   // 1. Load mods
   if (config?.modsDir !== false) {
-    const modsDir = config?.modsDir ?? new URL('../mods', import.meta.url).pathname;
-    const { loaded, failed } = await loadLocalMods(modsDir, 'server');
-    if (failed.length) console.error('failed mods:', failed.map(f => `${f.name}: ${f.error.message}`).join(', '));
-    if (loaded.length) console.log(`mods: ${loaded.join(', ')}`);
+    const extraDirs = config?.modsDir ? [config.modsDir] : [];
+    await loadAllMods('server', ...extraDirs);
   }
 
-  // 2. Bootstrap: root node with overlay(base, work)
+  // 2. Bootstrap: root node
   const bootstrap = createMemoryTree();
-  const rootNode = createNode('/', 'root', {}, {
-    mount: { $type: 't.mount.overlay', layers: ['base', 'work'] },
-    base: { $type: 't.mount.fs', root: dataDir + '/base' },
-    work: { $type: 't.mount.fs', root: dataDir + '/work' },
-  });
-  rootNode.$acl = [
-    { g: 'public', p: R },
-    { g: 'authenticated', p: R | S },
-    { g: 'admins', p: R | W | A | S },
-  ];
+  let rootNode: NodeData;
+  if (config?.rootNode) {
+    rootNode = config.rootNode;
+  } else {
+    rootNode = createNode('/', 'root', {}, {
+      mount: { $type: 't.mount.overlay', layers: ['base', 'work'] },
+      base: { $type: 't.mount.fs', root: dataDir + '/base' },
+      work: { $type: 't.mount.fs', root: dataDir + '/work' },
+    });
+    rootNode.$acl = [
+      { g: 'authenticated', p: R | S },
+      { g: 'admins', p: R | W | A | S },
+    ];
+  }
   await bootstrap.set(rootNode);
 
   // 3. Build pipeline
   const pipeline = createPipeline(bootstrap);
   const { store, mountable } = pipeline;
 
-  // 4. Seed
-  const seedFn = config?.seed ?? defaultSeed;
-  await seedFn(mountable, createEnsure(mountable));
+  // 4. Seed — if rootNode declares seeds, only deploy those mods
+  if (config?.seed) {
+    await config.seed(mountable, createEnsure(mountable));
+  } else {
+    const seedFilter = (rootNode as Record<string, unknown>).seeds as string[] | undefined;
+    await deploySeedPrefabs(mountable, seedFilter);
+  }
+
+  // 5. Wire log → tree
+  addOnLog(entry => {
+    const p = makeLogPath()
+    // process.stderr.write(`[log→tree] ${p} ${entry.level}: ${entry.msg.slice(0, 60)}\n`)
+    mountable.set({ $path: p, $type: 't.log', ...entry })
+      .catch(e => process.stderr.write(`[log write err] ${e.message}\n`))
+  })
 
-  // 5. Autostart services
+  // 6. Autostart services
   let serviceHandle: ServiceHandle | null = null;
   if (autostart) {
     serviceHandle = await startServices(store, store.subscribe.bind(store) as import('#contexts/service/index').ServiceCtx['subscribe']);

package/src/server/main.ts

@@ -1,56 +1,24 @@
 import 'dotenv/config';
-import { startServices } from '#contexts/service/index';
 import { type NodeData } from '#core';
-import { loadLocalMods } from '#mod';
-import { createMemoryTree } from '#tree';
-import './mount-adapters';
 import { readFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
-import { seed } from './seed';
-import '#schema/load';
-import '#contexts/text/index';
-import '#contexts/schema/index';
-import { createTreenityServer } from './server';
+import { treenity } from './factory';
 
 // Lock CWD — no library may change it
 process.chdir = () => { throw new Error('process.chdir is forbidden'); };
 
-// ── Root config ──
 const rootPath = resolve(process.argv[2] || 'root.json');
 const rootNode = JSON.parse(await readFile(rootPath, 'utf-8')) as NodeData;
 
-// Internal mods (core/src/mods/)
-const internalModsDir = new URL('../mods', import.meta.url).pathname;
-const internal = await loadLocalMods(internalModsDir, 'server');
-
-// External mods (root mods/)
-const externalModsDir = new URL('../../../mods', import.meta.url).pathname;
-const external = await loadLocalMods(externalModsDir, 'server');
-
-const allFailed = [...internal.failed, ...external.failed];
-if (allFailed.length) console.error('failed mods:', allFailed.map(f => `${f.name}: ${f.error.message}`).join(', '));
-console.log(`mods: ${[...internal.loaded, ...external.loaded].join(', ')}`);
-
+const t = await treenity({ rootNode });
 const port = Number(process.env.PORT) || 3211;
-
-// ── Bootstrap from root.json ──
-const bootstrap = createMemoryTree();
-await bootstrap.set(rootNode);
-
-const { server, store, mountable } = createTreenityServer(bootstrap);
-await seed(mountable);
-
-// MCP now starts via autostart service (/sys/autostart/mcp → /sys/mcp)
-const serviceHandle = process.env.NO_SERVICES ? null
-  : await startServices(store, store.subscribe.bind(store) as import('#contexts/service/index').ServiceCtx['subscribe']);
-
 const host = process.env.HOST || '127.0.0.1';
-server.listen(port, host, () => console.log(`treenity trpc ${host}:${port}`));
+const server = await t.listen(port, { host });
 
 process.on('unhandledRejection', (err) => console.error('[UNHANDLED]', err));
 
 process.on('SIGTERM', async () => {
-  await serviceHandle?.stop();
+  await t.stop();
   server.close();
   process.exit(0);
 });

package/src/server/migrate.ts

@@ -12,7 +12,7 @@ type Migrations = Record<number, Migrator>;
 function getMigrations(type: string): { migrations: Migrations; version: number } | null {
   const handler = resolveExact(type, 'migrate');
   if (!handler) return null;
-  const migrations = handler() as unknown as Migrations;
+  const migrations = handler() as Migrations;
   const keys = Object.keys(migrations).map(Number).sort((a, b) => a - b);
   if (!keys.length) return null;
   return { migrations, version: keys[keys.length - 1] };
@@ -22,21 +22,21 @@ function migrateNode(node: NodeData): NodeData {
   const m = getMigrations(node.$type);
   if (!m) return node;
 
-  const nodeV = (node as any).$v as number ?? 0;
+  const nodeV = (node['$v'] as number) ?? 0;
   if (nodeV >= m.version) return node;
 
   const clone = structuredClone(node);
   for (const [v, fn] of Object.entries(m.migrations).sort(([a], [b]) => +a - +b)) {
     if (+v > nodeV) fn(clone as Record<string, unknown>);
   }
-  (clone as any).$v = m.version;
+  clone['$v'] = m.version;
   return clone;
 }
 
 function stampVersion(node: NodeData): void {
   const m = getMigrations(node.$type);
   if (!m) return;
-  (node as any).$v = m.version;
+  node['$v'] = m.version;
 }
 
 export function withMigration(store: Tree): Tree {

package/src/server/mods-mount.ts

@@ -11,8 +11,6 @@
 //   /sys/mods/{mod}/prefabs/{name}/      → prefab root (dir)
 //   /sys/mods/{mod}/prefabs/{name}/{...} → prefab nodes
 
-import '#mods/treenity/mod-type';
-
 import { createNode, type NodeData } from '#core';
 import { getLoadedMods } from '#mod/loader';
 import { getModPrefabs, getPrefab, getRegisteredMods } from '#mod/prefab';

package/src/server/mount-adapters.ts

@@ -44,13 +44,17 @@ register('t.mount.query', 'mount', (config: NodeData, parentStore, ctx, globalSt
 register('t.mount.fs', 'mount', async (config: NodeData) => {
   const root = config['root'] as string | undefined;
   if (!root) throw new Error('t.mount.fs: root required');
-  return createFsTree(root);
+  const tree = await createFsTree(root);
+  // shared: true — full tree paths (multiple mount points into one dir)
+  // default: dedicated — repath to local /
+  return config['shared'] ? tree : createRepathTree(tree, config.$path, '/');
 });
 
 register('t.mount.rawfs', 'mount', async (config: NodeData) => {
   const root = config['root'] as string | undefined;
   if (!root) throw new Error('t.mount.rawfs: root required');
-  return createRawFsStore(root);
+  const tree = await createRawFsStore(root);
+  return config['shared'] ? tree : createRepathTree(tree, config.$path, '/');
 });
 
 // Federation: mount a remote Treenity instance's tree via tRPC.
@@ -72,8 +76,9 @@ register('t.mount.overlay', 'mount', async (config: NodeData, parentStore, ctx,
     if (!isComponent(comp)) throw new Error(`t.mount.overlay: component "${name}" not found`);
     const adapter = resolve(comp.$type, 'mount');
     if (!adapter) throw new Error(`No mount adapter for "${comp.$type}"`);
-    // Overlay sub-adapters receive a component, not full node — they don't need $path
-    stores.push(await adapter(comp as NodeData, stores[0] ?? ({} as Tree), ctx, globalStore));
+    // Propagate parent $path so sub-adapters can repath correctly
+    const subConfig = { ...comp, $path: config.$path } as NodeData;
+    stores.push(await adapter(subConfig, stores[0] ?? ({} as Tree), ctx, globalStore));
   }
   // First = lower (base), last = upper (writes go here)
   let result = stores[0];

package/src/server/mount.test.ts

@@ -1,9 +1,14 @@
 import { createNode, ref, register } from '#core';
 import { clearRegistry } from '#core/index.test';
 import { createMemoryTree, type Tree } from '#tree';
+import { createFsTree } from '#tree/fs';
 import { createQueryTree } from '#tree/query';
+import { createRepathTree } from '#tree/repath';
 import assert from 'node:assert/strict';
-import { beforeEach, describe, it } from 'node:test';
+import { mkdtemp, readdir, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, it } from 'node:test';
 import { withMounts } from './mount';
 import { createTypesStore } from './types-mount';
 
@@ -370,9 +375,9 @@ describe('Types mount adapter', () => {
     register('test.block.text', 'schema', () => ({ label: 'Text', fields: {} }));
     const ts = createTypesStore(backingStore, '/types');
     const children = await ts.getChildren('/types');
-    assert.equal(children.items.length, 1); // /types/test folder
-    assert.equal(children.items[0].$path, '/types/test');
-    assert.equal(children.items[0].$type, 't.dir');
+    const testFolder = children.items.find(n => n.$path === '/types/test');
+    assert.ok(testFolder, '/types/test folder should exist');
+    assert.equal(testFolder.$type, 't.dir');
   });
 
   it('getChildren returns type nodes in category', async () => {
@@ -404,7 +409,9 @@ describe('Types mount adapter', () => {
     await backingStore.set(createNode('/types/custom', 'dir'));
     const ts = createTypesStore(backingStore, '/types');
     const children = await ts.getChildren('/types');
-    assert.equal(children.items.length, 2); // /types/test + /types/custom
+    const paths = children.items.map(n => n.$path);
+    assert.ok(paths.includes('/types/test'), '/types/test should exist');
+    assert.ok(paths.includes('/types/custom'), '/types/custom should exist');
   });
 
   it('registry wins on conflict', async () => {
@@ -495,3 +502,64 @@ describe('Types mount adapter', () => {
     ]);
   });
 });
+
+// Regression: FS mount at nested path should not duplicate prefix in file paths
+describe('FS mount repath (dedicated)', () => {
+  let rootStore: Tree;
+  let tmpDir: string;
+
+  beforeEach(async () => {
+    clearRegistry();
+    rootStore = createMemoryTree();
+    tmpDir = await mkdtemp(join(tmpdir(), 'treenity-fs-mount-'));
+  });
+
+  afterEach(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it('dedicated FS mount stores files without mount prefix', async () => {
+    const fsTree = await createFsTree(tmpDir);
+    const repathed = createRepathTree(fsTree, '/data/files', '/');
+
+    register('test.mount.fs', 'mount', () => repathed);
+    await rootStore.set(
+      createNode('/data/files', 'mount-point', {}, {
+        mount: { $type: 'test.mount.fs' },
+      }),
+    );
+
+    const ms = withMounts(rootStore);
+    await ms.set(createNode('/data/files/doc', 'document'));
+
+    // FS dir should contain doc.json, NOT data/files/doc.json
+    const entries = await readdir(tmpDir);
+    assert.ok(entries.includes('doc.json'), `expected doc.json in ${tmpDir}, got: ${entries}`);
+
+    // Read back through mount — path should be full tree path
+    const node = await ms.get('/data/files/doc');
+    assert.equal(node?.$path, '/data/files/doc');
+    assert.equal(node?.$type, 't.document');
+  });
+
+  it('getChildren returns full tree paths', async () => {
+    const fsTree = await createFsTree(tmpDir);
+    const repathed = createRepathTree(fsTree, '/data/files', '/');
+
+    register('test.mount.fs', 'mount', () => repathed);
+    await rootStore.set(
+      createNode('/data/files', 'mount-point', {}, {
+        mount: { $type: 'test.mount.fs' },
+      }),
+    );
+
+    const ms = withMounts(rootStore);
+    await ms.set(createNode('/data/files/a', 'item'));
+    await ms.set(createNode('/data/files/b', 'item'));
+
+    const children = await ms.getChildren('/data/files');
+    assert.equal(children.items.length, 2);
+    const paths = children.items.map(n => n.$path).sort();
+    assert.deepEqual(paths, ['/data/files/a', '/data/files/b']);
+  });
+});

package/src/server/prefab.ts

@@ -92,12 +92,13 @@ export async function deployByKey(
   return deployNodes(store, prefab, target, opts);
 }
 
-/** Deploy all seed prefabs. Respects TENANT env (only core-tier seeds). */
-export async function deploySeedPrefabs(store: Tree): Promise<void> {
+/** Deploy seed prefabs. If filter provided, only deploy seeds whose mod is in the list. */
+export async function deploySeedPrefabs(store: Tree, filter?: string[]): Promise<void> {
   const isTenant = !!process.env.TENANT;
   const seeds = getSeedPrefabs();
 
   for (const [mod, prefab] of seeds) {
+    if (filter && !filter.includes(mod)) continue;
     if (isTenant && prefab.meta?.tier !== 'core') continue;
     await deployNodes(store, prefab, '/', { allowAbsolute: true, params: { store } });
   }

package/src/server/refs.test.ts

@@ -0,0 +1,82 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { createMemoryTree } from '#tree';
+import { withRefIndex } from './refs';
+
+describe('withRefIndex', () => {
+  it('extracts $ref fields into $refs', async () => {
+    const tree = withRefIndex(createMemoryTree());
+    await tree.set({
+      $path: '/order/1',
+      $type: 'cafe.order',
+      customer: { $type: 'ref', $ref: '/customers/ivan' },
+      items: [{ $type: 'ref', $ref: '/menu/latte' }],
+    });
+
+    const node = await tree.get('/order/1');
+    assert.ok(node?.$refs);
+    assert.equal(node.$refs.length, 2);
+    assert.ok(node.$refs.some(r => r.t === '/customers/ivan' && r.f === '#customer'));
+    assert.ok(node.$refs.some(r => r.t === '/menu/latte' && r.f === '#items.0'));
+  });
+
+  it('preserves standalone refs (no f:)', async () => {
+    const tree = withRefIndex(createMemoryTree());
+    await tree.set({
+      $path: '/factory',
+      $type: 'mfg.factory',
+      $refs: [{ t: '/suppliers/bob', d: { $type: 'supplies', since: '2025-01' } }],
+    });
+
+    const node = await tree.get('/factory');
+    assert.ok(node?.$refs);
+    assert.equal(node.$refs.length, 1);
+    assert.equal(node.$refs[0].t, '/suppliers/bob');
+    assert.equal(node.$refs[0].d?.$type, 'supplies');
+    assert.equal(node.$refs[0].f, undefined);
+  });
+
+  it('merges standalone + derived refs', async () => {
+    const tree = withRefIndex(createMemoryTree());
+    await tree.set({
+      $path: '/order/2',
+      $type: 'cafe.order',
+      customer: { $type: 'ref', $ref: '/customers/ivan' },
+      $refs: [{ t: '/promos/summer', d: { $type: 'applied-promo' } }],
+    });
+
+    const node = await tree.get('/order/2');
+    assert.ok(node?.$refs);
+    assert.equal(node.$refs.length, 2);
+    // standalone first, then derived
+    assert.equal(node.$refs[0].t, '/promos/summer');
+    assert.equal(node.$refs[1].t, '/customers/ivan');
+  });
+
+  it('returns undefined $refs when no refs exist', async () => {
+    const tree = withRefIndex(createMemoryTree());
+    await tree.set({ $path: '/plain', $type: 'dir' });
+
+    const node = await tree.get('/plain');
+    assert.equal(node?.$refs, undefined);
+  });
+
+  it('scans nested component refs', async () => {
+    const tree = withRefIndex(createMemoryTree());
+    await tree.set({
+      $path: '/node',
+      $type: 'test',
+      delivery: {
+        $type: 'logistics.delivery',
+        courier: { $type: 'ref', $ref: '/couriers/alex' },
+        warehouse: { $type: 'ref', $ref: '/warehouses/main' },
+      },
+    });
+
+    const node = await tree.get('/node');
+    assert.ok(node?.$refs);
+    assert.equal(node.$refs.length, 2);
+    assert.ok(node.$refs.some(r => r.t === '/couriers/alex' && r.f === '#delivery.courier'));
+    assert.ok(node.$refs.some(r => r.t === '/warehouses/main' && r.f === '#delivery.warehouse'));
+  });
+});

package/src/server/refs.ts

@@ -0,0 +1,64 @@
+// withRefIndex — store combinator that auto-populates $refs on set()
+// Scans node fields for { $ref } entries, builds $refs array.
+// Standalone refs (no f:) pass through untouched.
+
+import { isRef, type NodeData, type RefEntry } from '#core';
+import type { Tree } from '#tree';
+
+/** Deep-scan node for $ref fields, return derived RefEntries */
+function extractRefs(node: NodeData): RefEntry[] {
+  const refs: RefEntry[] = [];
+
+  function scan(obj: unknown, prefix: string) {
+    if (!obj || typeof obj !== 'object') return;
+    if (isRef(obj)) {
+      refs.push({ t: obj.$ref, f: prefix || undefined });
+      return;
+    }
+    if (Array.isArray(obj)) {
+      for (let i = 0; i < obj.length; i++) scan(obj[i], `${prefix}.${i}`);
+      return;
+    }
+    for (const [k, v] of Object.entries(obj)) {
+      if (k.startsWith('$')) continue;
+      const path = prefix ? `${prefix}.${k}` : `#${k}`;
+      scan(v, path);
+    }
+  }
+
+  for (const [k, v] of Object.entries(node)) {
+    if (k.startsWith('$')) continue;
+    scan(v, `#${k}`);
+  }
+
+  return refs;
+}
+
+/** Merge derived refs with standalone refs (those without f:) */
+function buildRefs(node: NodeData): RefEntry[] | undefined {
+  const derived = extractRefs(node);
+  const standalone = node.$refs?.filter(r => !r.f) ?? [];
+  const merged = [...standalone, ...derived];
+  return merged.length ? merged : undefined;
+}
+
+export function withRefIndex(inner: Tree): Tree {
+  return {
+    ...inner,
+
+    async set(node, ctx) {
+      node.$refs = buildRefs(node);
+      return inner.set(node, ctx);
+    },
+
+    async patch(path, ops, ctx) {
+      await inner.patch(path, ops, ctx);
+      // Re-extract refs after patch
+      const updated = await inner.get(path, ctx);
+      if (updated) {
+        updated.$refs = buildRefs(updated);
+        await inner.set(updated, ctx);
+      }
+    },
+  };
+}