@treenity/core 1.0.47 → 3.0.0

package/src/server/types-mount.ts

@@ -0,0 +1,142 @@
+// Treenity Types Mount — Layer 4
+// Union of registry (code-defined types) + backing store (dynamic types)
+
+import { type ComponentData, createNode, getContextsForType, getRegisteredTypes, type NodeData, resolve } from '#core';
+import { paginate, type Tree } from '#tree';
+
+export function createTypesStore(backingStore: Tree, typesPath = '/sys/types'): Tree {
+  // block.hero → /types/block/hero
+  const toPath = (type: string) => `${typesPath}/${type.replace(/\./g, '/')}`;
+  // /types/block/hero → block.hero
+  const toType = (path: string) => path.slice(typesPath.length + 1).replace(/\//g, '.');
+
+  function isRegistryType(path: string): boolean {
+    const typeName = toType(path);
+    return getContextsForType(typeName).length > 0;
+  }
+
+  function typeNode(typeName: string): NodeData | undefined {
+    const contexts = getContextsForType(typeName);
+    if (contexts.length === 0) return undefined;
+    const components: Record<string, ComponentData> = {};
+    for (const ctx of contexts) {
+      // "schema" returns data object; other contexts (twa, react) are renderers — just mark presence
+      if (ctx === 'schema') {
+        const handler = resolve(typeName, ctx)!;
+        const schema = handler() as Record<string, unknown>;
+        components[ctx] = { $type: ctx, ...schema } as ComponentData;
+      } else {
+        components[ctx] = { $type: ctx } as ComponentData;
+      }
+    }
+    return createNode(toPath(typeName), 'type', undefined, components);
+  }
+
+  // Merge registry node with backing store node — registry wins for code-defined
+  // components, backing store adds dynamic components (view, actions from AI agent)
+  async function mergedTypeNode(typeName: string): Promise<NodeData | undefined> {
+    const fromRegistry = typeNode(typeName);
+    if (!fromRegistry) return undefined;
+    const fromStore = await backingStore.get(fromRegistry.$path);
+    if (!fromStore) return fromRegistry;
+    // Backing store fields first, registry overwrites (code-defined always wins)
+    return { ...fromStore, ...fromRegistry };
+  }
+
+  return {
+    async get(path) {
+      const typeName = toType(path);
+      const merged = await mergedTypeNode(typeName);
+      if (merged) return merged;
+      // Check if it's a category folder (e.g. /types/block)
+      const prefix = typeName + '.';
+      if (getRegisteredTypes('schema').some((t) => t.startsWith(prefix))) {
+        return createNode(path, 'dir');
+      }
+      return backingStore.get(path);
+    },
+
+    async getChildren(path, opts) {
+      const depth = opts?.depth ?? 1;
+      const prefix = path === typesPath ? '' : toType(path) + '.';
+      const types = getRegisteredTypes();
+      const byPath = new Map<string, NodeData>();
+      // Backing store — scan deep to discover category folders, synthesize intermediate dirs
+      const backingItems = (await backingStore.getChildren(path, { depth: Infinity })).items;
+      for (const n of backingItems) {
+        const rel = path === '/' ? n.$path.slice(1) : n.$path.slice(path.length + 1);
+        const parts = rel.split('/');
+        if (parts.length <= depth) byPath.set(n.$path, n);
+        // Synthesize dir nodes for intermediate paths (like registry does for categories)
+        for (let i = 0; i < parts.length - 1; i++) {
+          if (i + 1 > depth) break;
+          const dirPath = `${path}/${parts.slice(0, i + 1).join('/')}`;
+          if (!byPath.has(dirPath)) byPath.set(dirPath, createNode(dirPath, 'dir'));
+        }
+      }
+      // Registry types — merge with backing store data (dynamic views, actions)
+      const seenDirs = new Set<string>();
+      for (const t of types) {
+        if (prefix && !t.startsWith(prefix)) continue;
+        if (!prefix && !t.includes('.')) {
+          const reg = typeNode(t);
+          if (reg) {
+            const stored = byPath.get(reg.$path);
+            byPath.set(reg.$path, stored ? { ...stored, ...reg } : reg);
+          }
+          continue;
+        }
+        const rest = prefix ? t.slice(prefix.length) : t;
+        const parts = rest.split('.');
+        if (parts.length === 1) {
+          // Direct child leaf type — merge with any backing store data
+          const reg = typeNode(t);
+          if (reg) {
+            const stored = byPath.get(reg.$path);
+            byPath.set(reg.$path, stored ? { ...stored, ...reg } : reg);
+          }
+        } else {
+          // Category folder (always emit)
+          const cat = parts[0];
+          if (!seenDirs.has(cat)) {
+            seenDirs.add(cat);
+            const folderPath = `${path}/${cat}`;
+            byPath.set(folderPath, createNode(folderPath, 'dir'));
+          }
+          // Deep types — emit when depth allows, merge with backing store
+          if (depth > 1) {
+            const reg = typeNode(t);
+            if (reg) {
+              const stored = byPath.get(reg.$path);
+              byPath.set(reg.$path, stored ? { ...stored, ...reg } : reg);
+            }
+            // Intermediate dirs
+            for (let i = 1; i < parts.length - 1; i++) {
+              const dirKey = parts.slice(0, i + 1).join('.');
+              if (!seenDirs.has(dirKey)) {
+                seenDirs.add(dirKey);
+                const dirPath = `${path}/${parts.slice(0, i + 1).join('/')}`;
+                byPath.set(dirPath, createNode(dirPath, 'dir'));
+              }
+            }
+          }
+        }
+      }
+      return paginate([...byPath.values()], opts);
+    },
+
+    async set(node) {
+      return backingStore.set(node);
+    },
+
+    async remove(path) {
+      // Never remove code-registered types
+      if (isRegistryType(path)) throw new Error(`Cannot remove registry type: ${toType(path)}`);
+      return backingStore.remove(path);
+    },
+
+    async patch(path, ops, ctx) {
+      return backingStore.patch(path, ops, ctx);
+    },
+  };
+}

package/src/server/validate.test.ts

@@ -0,0 +1,91 @@
+import { createNode, type NodeData, register } from '#core';
+import { clearRegistry } from '#core/index.test';
+import { createMemoryTree } from '#tree';
+import assert from 'node:assert/strict';
+import { beforeEach, describe, it } from 'node:test';
+import { withValidation } from './validate';
+
+describe('withValidation (Write-Barrier)', () => {
+  let store: ReturnType<typeof createMemoryTree>;
+
+  beforeEach(() => {
+    clearRegistry();
+    store = createMemoryTree();
+
+    register('metadata', 'schema', () => ({
+      title: 'Metadata',
+      type: 'object',
+      properties: {
+        title: { type: 'string', title: 'Title' },
+        count: { type: 'number', title: 'Count' },
+        active: { type: 'boolean', title: 'Active' },
+      },
+    }));
+  });
+
+  it('allows valid components', async () => {
+    const vs = withValidation(store);
+    await vs.set({
+      $path: '/a', $type: 'item',
+      metadata: { $type: 'metadata', title: 'Hello', count: 5, active: true },
+    } as NodeData);
+
+    const node = await vs.get('/a');
+    assert.equal((node?.metadata as any).title, 'Hello');
+  });
+
+  it('rejects wrong type: string expected, got number', async () => {
+    const vs = withValidation(store);
+    await assert.rejects(
+      () => vs.set({
+        $path: '/a', $type: 'item',
+        metadata: { $type: 'metadata', title: 42 },
+      } as NodeData),
+    );
+  });
+
+  it('rejects wrong type: number expected, got string', async () => {
+    const vs = withValidation(store);
+    await assert.rejects(
+      () => vs.set({
+        $path: '/a', $type: 'item',
+        metadata: { $type: 'metadata', count: 'not a number' },
+      } as NodeData),
+    );
+  });
+
+  it('allows missing optional fields', async () => {
+    const vs = withValidation(store);
+    // Only title set, count and active missing — fine
+    await vs.set({
+      $path: '/a', $type: 'item',
+      metadata: { $type: 'metadata', title: 'Hello' },
+    } as NodeData);
+    assert.ok(await vs.get('/a'));
+  });
+
+  it('passes through nodes without schemas', async () => {
+    const vs = withValidation(store);
+    await vs.set({
+      $path: '/a', $type: 'item',
+      custom: { $type: 'no-schema-type', anything: 'goes' },
+    } as NodeData);
+    assert.ok(await vs.get('/a'));
+  });
+
+  it('skips system fields', async () => {
+    const vs = withValidation(store);
+    // $path, $type, $rev etc should not trigger validation
+    await vs.set(createNode('/a', 'item'));
+    assert.ok(await vs.get('/a'));
+  });
+
+  it('get/getChildren/remove pass through', async () => {
+    const vs = withValidation(store);
+    await store.set(createNode('/a', 'item'));
+    assert.ok(await vs.get('/a'));
+    const children = await vs.getChildren('/');
+    assert.equal(children.items.length, 1);
+    assert.equal(await vs.remove('/a'), true);
+  });
+});

package/src/server/validate.ts

@@ -0,0 +1,22 @@
+// Write-Barrier — validates node components against their schemas before store.set()
+// Rejects writes with malformed data. AI agents get "compilation errors" instead of garbage in DB.
+
+import { validateNode } from '#comp/validate';
+import type { Tree } from '#tree';
+
+export function withValidation(store: Tree): Tree {
+  return {
+    ...store,
+    async set(node) {
+      const errors = validateNode(node);
+      if (errors.length) {
+        const msg = errors.map(e => `${e.path}: ${e.message}`).join('; ');
+        throw new Error(`Validation: ${msg}`);
+      }
+      return store.set(node);
+    },
+    async patch(path, ops, ctx) {
+      return store.patch(path, ops, ctx);
+    },
+  };
+}

package/src/server/volatile.test.ts

@@ -0,0 +1,140 @@
+import { register } from '#core';
+import { clearRegistry } from '#core/index.test';
+import { createMemoryTree } from '#tree';
+import { mapSiftQuery } from '#tree/query';
+import assert from 'node:assert/strict';
+import { beforeEach, describe, it } from 'node:test';
+import { extractPaths, withVolatile } from './volatile';
+
+describe('withVolatile', () => {
+  let store: ReturnType<typeof withVolatile>;
+  let backing: ReturnType<typeof createMemoryTree>;
+
+  beforeEach(() => {
+    clearRegistry();
+    backing = createMemoryTree();
+    store = withVolatile(backing);
+  });
+
+  it('node with $volatile lives in memory only', async () => {
+    await store.set({ $path: '/status', $type: 'stats', $volatile: true, msgs: 42 });
+    assert.equal(await backing.get('/status'), undefined);
+    const node = await store.get('/status');
+    assert.ok(node);
+    assert.equal(node.msgs, 42);
+  });
+
+  it('node without $volatile goes to backing store', async () => {
+    await store.set({ $path: '/bot1', $type: 'bot', name: 'mybot' });
+    const raw = await backing.get('/bot1');
+    assert.ok(raw);
+    assert.equal(raw.name, 'mybot');
+  });
+
+  it('type registration makes node volatile', async () => {
+    register('bot-status', 'volatile', () => true);
+    await store.set({ $path: '/s1', $type: 'bot-status', cpu: 50 });
+    assert.equal(await backing.get('/s1'), undefined);
+    const node = await store.get('/s1');
+    assert.ok(node);
+    assert.equal(node.cpu, 50);
+  });
+
+  it('$volatile: false overrides type registration', async () => {
+    register('stats', 'volatile', () => true);
+    await store.set({ $path: '/s1', $type: 'stats', $volatile: false, v: 99 });
+    const raw = await backing.get('/s1');
+    assert.ok(raw);
+    assert.equal(raw.v, 99);
+  });
+
+  it('$volatile: true overrides non-volatile type', async () => {
+    await store.set({ $path: '/bot1', $type: 'bot', $volatile: true, name: 'x' });
+    assert.equal(await backing.get('/bot1'), undefined);
+    const node = await store.get('/bot1');
+    assert.ok(node);
+    assert.equal(node.name, 'x');
+  });
+
+  it('getChildren merges volatile and persistent nodes', async () => {
+    await store.set({ $path: '/bots', $type: 'dir' });
+    await store.set({ $path: '/bots/b1', $type: 'bot', name: 'one' });
+    await store.set({ $path: '/bots/b2', $type: 'bot', $volatile: true, name: 'two' });
+    const { items } = await store.getChildren('/bots');
+    assert.equal(items.length, 2);
+    const names = items.map((n) => n.name).sort();
+    assert.deepEqual(names, ['one', 'two']);
+  });
+
+  it('remove clears volatile node', async () => {
+    await store.set({ $path: '/s1', $type: 'stats', $volatile: true, v: 1 });
+    await store.remove('/s1');
+    assert.equal(await store.get('/s1'), undefined);
+  });
+
+  it('remove works for both volatile and persistent', async () => {
+    await store.set({ $path: '/b1', $type: 'bot', name: 'x' });
+    await store.set({ $path: '/s1', $type: 'stats', $volatile: true, v: 1 });
+    await store.remove('/b1');
+    await store.remove('/s1');
+    assert.equal(await store.get('/b1'), undefined);
+    assert.equal(await store.get('/s1'), undefined);
+  });
+
+  it('getChildren passes sift query through to backing store', async () => {
+    await store.set({ $path: '/tasks', $type: 'dir' });
+    await store.set({ $path: '/tasks/t1', $type: 'task', status: 'pending' });
+    await store.set({ $path: '/tasks/t2', $type: 'task', status: 'done' });
+    await store.set({ $path: '/tasks/t3', $type: 'task', status: 'pending' });
+    await store.set({ $path: '/tasks/mp', $type: 'mount-point' });
+
+    const pending = await store.getChildren('/tasks', {
+      query: mapSiftQuery({ $type: 'task', status: 'pending' }) as Record<string, unknown>,
+    });
+    assert.equal(pending.items.length, 2);
+    assert.ok(pending.items.every(n => n.$type === 'task' && n.status === 'pending'));
+  });
+
+  it('getChildren query filters across both volatile and persistent', async () => {
+    register('live', 'volatile', () => true);
+    await store.set({ $path: '/mix', $type: 'dir' });
+    await store.set({ $path: '/mix/a', $type: 'task', status: 'done' });
+    await store.set({ $path: '/mix/b', $type: 'live', status: 'done', $volatile: true });
+    await store.set({ $path: '/mix/c', $type: 'task', status: 'pending' });
+
+    const done = await store.getChildren('/mix', {
+      query: mapSiftQuery({ status: 'done' }) as Record<string, unknown>,
+    });
+    assert.equal(done.items.length, 2);
+    assert.ok(done.items.every(n => n.status === 'done'));
+  });
+});
+
+describe('extractPaths', () => {
+  it('extracts from Page (items array)', () => {
+    const result = {
+      items: [
+        { $path: '/a', $type: 't' },
+        { $path: '/b', $type: 't' },
+      ],
+      total: 2,
+    };
+    assert.deepEqual(extractPaths(result), ['/a', '/b']);
+  });
+
+  it('extracts from single node', () => {
+    assert.deepEqual(extractPaths({ $path: '/a', $type: 't' }), ['/a']);
+  });
+
+  it('returns empty for plain data', () => {
+    assert.deepEqual(extractPaths({ count: 42 }), []);
+    assert.deepEqual(extractPaths(null), []);
+    assert.deepEqual(extractPaths(42), []);
+    assert.deepEqual(extractPaths('hello'), []);
+  });
+
+  it('filters items without $path', () => {
+    const result = { items: [{ $path: '/a', $type: 't' }, { name: 'no path' }], total: 2 };
+    assert.deepEqual(extractPaths(result), ['/a']);
+  });
+});

package/src/server/volatile.ts

@@ -0,0 +1,32 @@
+// Treenity Volatile Nodes — Layer 3
+// Nodes with $volatile go to memory, rest to backing store.
+// Cascade: $volatile on instance > register(type, 'volatile') > false
+
+import { type NodeData, resolve as resolveHandler } from '#core';
+import { createFilterTree, createMemoryTree, type Tree } from '#tree';
+
+declare module '#core/context' {
+  interface ContextHandlers {
+    volatile: () => boolean;
+  }
+}
+
+export function isVolatile(node: NodeData): boolean {
+  if ('$volatile' in node) return !!node.$volatile;
+  return !!resolveHandler(node.$type, 'volatile');
+}
+
+export function extractPaths(result: unknown): string[] {
+  if (!result || typeof result !== 'object') return [];
+  const r = result as Record<string, unknown>;
+  if (Array.isArray(r.items))
+    return (r.items as Record<string, unknown>[])
+      .filter((n) => typeof n?.$path === 'string')
+      .map((n) => n.$path as string);
+  if (typeof r.$path === 'string') return [r.$path];
+  return [];
+}
+
+export function withVolatile(store: Tree): Tree {
+  return createFilterTree(createMemoryTree(), store, isVolatile);
+}