trellis 3.1.1 → 3.1.3

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+## 3.1.2
+
+- Fixed `trellis/cms` collection reads for inferred collections whose normalized key differs from the stored entity type casing, such as `blogpost` reading `BlogPost` entities.
+- Added graph-link awareness to CMS entries so reference links such as `post --author--> author` appear in `fields` and can be expanded.
+- Added `status` fact fallback when `cms_status` is absent, preserving content created by agents or lower-level store tools.
+- Added shared polling for CMS subscriptions so duplicate subscribers to the same collection or entry reuse one poll stream.
+- Added `onError` and custom `equals` subscription options.
+- Fixed CMS entity pagination to respect the opencode store route's 1000-entity page limit.
+- Added CMS client/scaffold tests and included them in the default test script.
+- Added `directory` support to CMS consumer scaffolds for multi-instance opencode routing.
+
+## 3.1.1
+
+- Published the first `trellis/cms` SDK package update after adding scaffold helpers.
+
+## 3.1.0
+
+- Added the `trellis/cms` subpath with `createCmsClient`, collection reads, entry reads, polling subscriptions, reference expansion, collection discovery, and consumer scaffold helpers for vanilla, React, Solid, and Vue.

package/README.md

@@ -50,6 +50,43 @@ See the [CLI guide](https://trellis.computer/docs/cli) for complete documentatio
 
 ---
 
+## CMS Client SDK
+
+Use `trellis/cms` from browser apps to read content from a Trellis-compatible HTTP server such as opencode at `http://localhost:4096`.
+
+```typescript
+import { createCmsClient } from 'trellis/cms';
+
+const cms = createCmsClient({
+  url: 'http://localhost:4096',
+  directory: '/path/to/project',
+});
+
+const posts = await cms.collection('blogpost').list({
+  status: 'all',
+  expand: ['author'],
+});
+
+const off = cms.collection('blogpost').subscribe(
+  (entries) => {
+    console.log(entries);
+  },
+  {
+    status: 'published',
+    onError: console.error,
+  },
+);
+
+off();
+```
+
+- **Collections**: `cms.collections()` returns explicit `TypeSchema` collections and inferred collections from existing entity types.
+- **Normalized keys**: `cms.collection('blogpost')` matches stored entity types like `BlogPost`.
+- **References**: `expand` resolves reference ids from facts and graph links into nested entries.
+- **Scaffolds**: `scaffoldConsumer({ collection, framework, directory })` generates starter consumer code for vanilla, React, Solid, or Vue.
+
+---
+
 ## What is Trellis?
 
 Trellis is an **event-sourced causal graph engine** that unifies version control, knowledge management, and semantic analysis. Every action is an immutable operation in a causal stream:

package/dist/cms/client.d.ts

@@ -23,7 +23,8 @@
  *
  * @module trellis/cms
  */
-import type { CmsClientOptions, Collection, Entry, EntrySubscriber, GetOptions, ListOptions, ListSubscriber, Unsubscribe } from './types.js';
+import type { CmsClientOptions, Collection, Entry, EntrySubscribeOptions, EntrySubscriber, GetOptions, ListOptions, ListSubscribeOptions, ListSubscriber, Unsubscribe } from './types.js';
+import { type RawEntity } from './internal.js';
 export declare class CmsClient {
     private readonly url;
     private readonly basePath;
@@ -31,15 +32,29 @@ export declare class CmsClient {
     readonly pollIntervalMs: number;
     private readonly fetchFn;
     private readonly apiKey?;
+    private readonly subscriptions;
     constructor(opts: CmsClientOptions);
     collection<T extends Record<string, unknown> = Record<string, unknown>>(key: string): CollectionRef<T>;
     entry<T extends Record<string, unknown> = Record<string, unknown>>(id: string): EntryRef<T>;
     /** List all CMS collections (explicit + inferred). */
     collections(): Promise<Collection[]>;
     close(): void;
+    /**
+     * Shared polling subscription. Multiple subscribers to the same key share a
+     * single timer and one HTTP request per poll cycle. New subscribers receive
+     * the most recently fetched value immediately if one is cached.
+     *
+     * @internal
+     */
+    _share<T>(key: string, fetcher: () => Promise<T>, callback: (value: T) => void, extras?: {
+        equals?: (prev: unknown, next: unknown) => boolean;
+        onError?: (err: unknown) => void;
+    }): Unsubscribe;
     /** @internal */
     _get<T>(path: string): Promise<T | undefined>;
     /** @internal */
+    _entities(): Promise<RawEntity[]>;
+    /** @internal */
     _entryById(id: string): Promise<Entry | null>;
 }
 export declare class CollectionRef<T extends Record<string, unknown> = Record<string, unknown>> {
@@ -51,15 +66,18 @@ export declare class CollectionRef<T extends Record<string, unknown> = Record<st
     /**
      * Subscribe to changes. Currently implemented as polling; a future SSE-backed
      * upgrade will replace the transport without changing this API.
+     *
+     * Multiple subscribers to the same collection + opts share one polling timer
+     * and one HTTP request per cycle.
      */
-    subscribe(callback: ListSubscriber<T>, opts?: ListOptions): Unsubscribe;
+    subscribe(callback: ListSubscriber<T>, opts?: ListSubscribeOptions): Unsubscribe;
 }
 export declare class EntryRef<T extends Record<string, unknown> = Record<string, unknown>> {
     private readonly client;
     readonly id: string;
     constructor(client: CmsClient, id: string);
     get(opts?: GetOptions): Promise<Entry<T> | null>;
-    subscribe(callback: EntrySubscriber<T>, opts?: GetOptions): Unsubscribe;
+    subscribe(callback: EntrySubscriber<T>, opts?: EntrySubscribeOptions): Unsubscribe;
 }
 export declare function createCmsClient(opts: CmsClientOptions): CmsClient;
 //# sourceMappingURL=client.d.ts.map

package/dist/cms/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/cms/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EACV,gBAAgB,EAChB,UAAU,EACV,KAAK,EACL,eAAe,EACf,UAAU,EACV,WAAW,EACX,cAAc,EACd,WAAW,EACZ,MAAM,YAAY,CAAC;AAiBpB,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAS;IACpC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAe;IACvC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAS;gBAErB,IAAI,EAAE,gBAAgB;IASlC,UAAU,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpE,GAAG,EAAE,MAAM,GACV,aAAa,CAAC,CAAC,CAAC;IAInB,KAAK,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,EAAE,EAAE,MAAM,GAAG,QAAQ,CAAC,CAAC,CAAC;IAI3F,sDAAsD;IAChD,WAAW,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;IAiD1C,KAAK,IAAI,IAAI;IAIb,gBAAgB;IACV,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;IAYnD,gBAAgB;IACV,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC;CASpD;AAED,qBAAa,aAAa,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAElF,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM;gBADH,MAAM,EAAE,SAAS,EACzB,GAAG,EAAE,MAAM;IAGhB,IAAI,CAAC,IAAI,GAAE,WAAgB,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;IA+BjD,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,GAAE,UAAe,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAYtE;;;OAGG;IACH,SAAS,CAAC,QAAQ,EAAE,cAAc,CAAC,CAAC,CAAC,EAAE,IAAI,GAAE,WAAgB,GAAG,WAAW;CAyB5E;AAED,qBAAa,QAAQ,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAE7E,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,QAAQ,CAAC,EAAE,EAAE,MAAM;gBADF,MAAM,EAAE,SAAS,EACzB,EAAE,EAAE,MAAM;IAGf,GAAG,CAAC,IAAI,GAAE,UAAe,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAY1D,SAAS,CAAC,QAAQ,EAAE,eAAe,CAAC,CAAC,CAAC,EAAE,IAAI,GAAE,UAAe,GAAG,WAAW;CAyB5E;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,gBAAgB,GAAG,SAAS,CAEjE"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/cms/client.ts"],"names":[],"mappings":"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"}

package/dist/cms/index.d.ts

@@ -4,7 +4,7 @@
  * @module trellis/cms
  */
 export { CmsClient, CollectionRef, EntryRef, createCmsClient } from './client.js';
-export type { CmsClientOptions, Collection, Entry, EntryStatus, EntrySubscriber, Framework, GetOptions, ListOptions, ListSubscriber, Unsubscribe, } from './types.js';
+export type { CmsClientOptions, Collection, Entry, EntryStatus, EntrySubscribeOptions, EntrySubscriber, Framework, GetOptions, ListOptions, ListSubscribeOptions, ListSubscriber, SubscribeExtras, Unsubscribe, } from './types.js';
 export { scaffoldConsumer, scaffoldFilename } from './scaffold.js';
 export type { ScaffoldOptions } from './scaffold.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/cms/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cms/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAElF,YAAY,EACV,gBAAgB,EAChB,UAAU,EACV,KAAK,EACL,WAAW,EACX,eAAe,EACf,SAAS,EACT,UAAU,EACV,WAAW,EACX,cAAc,EACd,WAAW,GACZ,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACnE,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cms/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAElF,YAAY,EACV,gBAAgB,EAChB,UAAU,EACV,KAAK,EACL,WAAW,EACX,qBAAqB,EACrB,eAAe,EACf,SAAS,EACT,UAAU,EACV,WAAW,EACX,oBAAoB,EACpB,cAAc,EACd,eAAe,EACf,WAAW,GACZ,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACnE,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC"}

package/dist/cms/index.js

@@ -29,18 +29,34 @@ function isSystemType(type) {
 function typeKey(type) {
   return type.trim().toLowerCase();
 }
-function entryFromFacts(entity, facts) {
+function entryFromFacts(entity, facts, links) {
   const fields = {};
   let status = "draft";
+  let cmsStatusSeen = false;
   for (const f of facts) {
     if (f.a === "type")
       continue;
     if (f.a === "cms_status") {
       status = f.v === "published" ? "published" : "draft";
+      cmsStatusSeen = true;
       continue;
     }
     fields[f.a] = f.v;
   }
+  if (!cmsStatusSeen) {
+    if (fields.status === "published")
+      status = "published";
+    else if (fields.status === "draft")
+      status = "draft";
+  }
+  if (links) {
+    for (const link of links) {
+      if (link.e1 !== entity.id)
+        continue;
+      if (!(link.a in fields))
+        fields[link.a] = link.e2;
+    }
+  }
   return { id: entity.id, type: entity.type, status, fields };
 }
 function groupFactsByEntity(facts) {
@@ -54,6 +70,17 @@ function groupFactsByEntity(facts) {
   }
   return map;
 }
+function groupLinksBySource(links) {
+  const map = new Map;
+  for (const l of links) {
+    const list = map.get(l.e1);
+    if (list)
+      list.push(l);
+    else
+      map.set(l.e1, [l]);
+  }
+  return map;
+}
 async function expandReferences(entries, expandKeys, fetchEntity) {
   const ids = new Set;
   for (const entry of entries) {
@@ -93,6 +120,8 @@ var DEFAULT_BASE_PATH = "/trellis/store";
 var DEFAULT_POLL_MS = 2000;
 var MIN_POLL_MS = 500;
 var MAX_FACTS_PER_FETCH = 5000;
+var MAX_ENTITIES_PER_FETCH = 1000;
+var defaultEquals = (prev, next) => fingerprint(prev) === fingerprint(next);
 
 class CmsClient {
   url;
@@ -101,6 +130,7 @@ class CmsClient {
   pollIntervalMs;
   fetchFn;
   apiKey;
+  subscriptions = new Map;
   constructor(opts) {
     this.url = opts.url.replace(/\/+$/, "");
     this.basePath = (opts.basePath ?? DEFAULT_BASE_PATH).replace(/\/+$/, "");
@@ -117,7 +147,7 @@ class CmsClient {
   }
   async collections() {
     const [entities, facts] = await Promise.all([
-      this._get("/entities?limit=10000"),
+      this._entities(),
       this._get(`/facts?limit=${MAX_FACTS_PER_FETCH}`)
     ]);
     const factsByEntity = groupFactsByEntity(facts ?? []);
@@ -160,7 +190,64 @@ class CmsClient {
     }
     return [...out.values()].sort((a, b) => a.label.localeCompare(b.label));
   }
-  close() {}
+  close() {
+    for (const sub of this.subscriptions.values()) {
+      clearInterval(sub.interval);
+      sub.subscribers.clear();
+    }
+    this.subscriptions.clear();
+  }
+  _share(key, fetcher, callback, extras = {}) {
+    let sub = this.subscriptions.get(key);
+    if (!sub) {
+      const fresh = {
+        subscribers: new Set,
+        interval: undefined,
+        hasLast: false,
+        fetcher
+      };
+      const tick = async () => {
+        try {
+          const next = await fresh.fetcher();
+          fresh.last = next;
+          fresh.hasLast = true;
+          for (const item2 of fresh.subscribers) {
+            if (!item2.hasLast || !item2.equals(item2.last, next)) {
+              item2.last = next;
+              item2.hasLast = true;
+              item2.callback(next);
+            }
+          }
+        } catch (err) {
+          for (const item2 of fresh.subscribers)
+            item2.onError?.(err);
+        }
+      };
+      fresh.interval = setInterval(tick, this.pollIntervalMs);
+      this.subscriptions.set(key, fresh);
+      sub = fresh;
+      tick();
+    }
+    const item = {
+      callback,
+      equals: extras.equals ?? defaultEquals,
+      onError: extras.onError,
+      hasLast: false
+    };
+    sub.subscribers.add(item);
+    if (sub.hasLast) {
+      item.last = sub.last;
+      item.hasLast = true;
+      callback(sub.last);
+    }
+    return () => {
+      sub.subscribers.delete(item);
+      if (sub.subscribers.size === 0) {
+        clearInterval(sub.interval);
+        this.subscriptions.delete(key);
+      }
+    };
+  }
   async _get(path) {
     const u = new URL(`${this.basePath}${path}`, this.url);
     if (this.directory && !u.searchParams.has("directory")) {
@@ -169,17 +256,30 @@ class CmsClient {
     const res = await this.fetchFn(u.toString(), {
       headers: this.apiKey ? { Authorization: `Bearer ${this.apiKey}` } : {}
     });
-    if (!res.ok)
+    if (res.status === 404)
       return;
+    if (!res.ok)
+      throw new Error(`Trellis CMS request failed (${res.status}) ${u.pathname}`);
     return await res.json();
   }
+  async _entities() {
+    const out = [];
+    let offset = 0;
+    while (true) {
+      const page = await this._get(`/entities?limit=${MAX_ENTITIES_PER_FETCH}&offset=${offset}`) ?? [];
+      out.push(...page);
+      if (page.length < MAX_ENTITIES_PER_FETCH)
+        return out;
+      offset += MAX_ENTITIES_PER_FETCH;
+    }
+  }
   async _entryById(id) {
     const detail = await this._get(`/entity/${encodeURIComponent(id)}`);
     if (!detail)
       return null;
     const typeFact = detail.facts.find((f) => f.a === "type");
     const type = typeof typeFact?.v === "string" ? typeFact.v : "unknown";
-    return entryFromFacts({ id: detail.id, type }, detail.facts);
+    return entryFromFacts({ id: detail.id, type }, detail.facts, detail.links);
   }
 }
 
@@ -193,18 +293,26 @@ class CollectionRef {
   async list(opts = {}) {
     const status = opts.status ?? "published";
     const limit = opts.limit ?? 100;
-    const [entities, facts] = await Promise.all([
-      this.client._get(`/entities?type=${encodeURIComponent(this.key)}&limit=${limit}`),
-      this.client._get(`/facts?limit=${MAX_FACTS_PER_FETCH}`)
+    const wantsExpand = opts.expand && opts.expand.length > 0;
+    const [allEntities, facts, links] = await Promise.all([
+      this.client._entities(),
+      this.client._get(`/facts?limit=${MAX_FACTS_PER_FETCH}`),
+      this.client._get(`/links`)
     ]);
-    if (!entities || entities.length === 0)
+    if (!allEntities)
+      return [];
+    const wantedKey = typeKey(this.key);
+    const matching = allEntities.filter((e) => typeKey(e.type) === wantedKey);
+    if (matching.length === 0)
       return [];
     const factsByEntity = groupFactsByEntity(facts ?? []);
-    let entries = entities.map((e) => entryFromFacts(e, factsByEntity.get(e.id) ?? []));
+    const linksBySource = groupLinksBySource(links ?? []);
+    let entries = matching.map((e) => entryFromFacts(e, factsByEntity.get(e.id) ?? [], linksBySource.get(e.id) ?? []));
     if (status !== "all") {
       entries = entries.filter((e) => e.status === status);
     }
-    if (opts.expand && opts.expand.length > 0) {
+    entries = entries.slice(0, limit);
+    if (wantsExpand) {
       entries = await expandReferences(entries, opts.expand, (id) => this.client._entryById(id));
     }
     return entries;
@@ -220,26 +328,9 @@ class CollectionRef {
     return entry;
   }
   subscribe(callback, opts = {}) {
-    let stopped = false;
-    let last = "";
-    const tick = async () => {
-      if (stopped)
-        return;
-      try {
-        const entries = await this.list(opts);
-        const sig = fingerprint(entries);
-        if (sig !== last) {
-          last = sig;
-          callback(entries);
-        }
-      } catch {}
-    };
-    tick();
-    const interval = setInterval(tick, this.client.pollIntervalMs);
-    return () => {
-      stopped = true;
-      clearInterval(interval);
-    };
+    const { onError, equals, ...listOpts } = opts;
+    const key = `coll:${typeKey(this.key)}:${JSON.stringify(listOpts)}`;
+    return this.client._share(key, () => this.list(listOpts), callback, { onError, equals });
   }
 }
 
@@ -261,26 +352,9 @@ class EntryRef {
     return entry;
   }
   subscribe(callback, opts = {}) {
-    let stopped = false;
-    let last = "";
-    const tick = async () => {
-      if (stopped)
-        return;
-      try {
-        const entry = await this.get(opts);
-        const sig = fingerprint(entry);
-        if (sig !== last) {
-          last = sig;
-          callback(entry);
-        }
-      } catch {}
-    };
-    tick();
-    const interval = setInterval(tick, this.client.pollIntervalMs);
-    return () => {
-      stopped = true;
-      clearInterval(interval);
-    };
+    const { onError, equals, ...getOpts } = opts;
+    const key = `entry:${this.id}:${JSON.stringify(getOpts)}`;
+    return this.client._share(key, () => this.get(getOpts), callback, { onError, equals });
   }
 }
 function createCmsClient(opts) {
@@ -293,12 +367,17 @@ function expandLiteral(expand) {
     return "";
   return ` expand: ${JSON.stringify(expand)},`;
 }
+function clientLiteral(url, directory) {
+  if (!directory)
+    return `createCmsClient({ url: "${url}" })`;
+  return `createCmsClient({ url: "${url}", directory: ${JSON.stringify(directory)} })`;
+}
 function vanilla(opts) {
   const url = opts.url ?? DEFAULT_URL;
   const exp = expandLiteral(opts.expand);
   return `import { createCmsClient } from "trellis/cms";
 
-const cms = createCmsClient({ url: "${url}" });
+const cms = ${clientLiteral(url, opts.directory)};
 
 const collection = cms.collection("${opts.collection}");
 
@@ -322,7 +401,7 @@ function react(opts) {
   return `import { useEffect, useState } from "react";
 import { createCmsClient, type Entry } from "trellis/cms";
 
-const cms = createCmsClient({ url: "${url}" });
+const cms = ${clientLiteral(url, opts.directory)};
 
 export function use${pascal(opts.collection)}() {
   const [entries, setEntries] = useState<Entry[]>([]);
@@ -344,7 +423,7 @@ function solid(opts) {
   return `import { createSignal, onCleanup } from "solid-js";
 import { createCmsClient, type Entry } from "trellis/cms";
 
-const cms = createCmsClient({ url: "${url}" });
+const cms = ${clientLiteral(url, opts.directory)};
 
 export function create${pascal(opts.collection)}() {
   const [entries, setEntries] = createSignal<Entry[]>([]);
@@ -364,7 +443,7 @@ function vue(opts) {
   return `import { ref, onUnmounted } from "vue";
 import { createCmsClient, type Entry } from "trellis/cms";
 
-const cms = createCmsClient({ url: "${url}" });
+const cms = ${clientLiteral(url, opts.directory)};
 
 export function use${pascal(opts.collection)}() {
   const entries = ref<Entry[]>([]);

package/dist/cms/internal.d.ts

@@ -11,10 +11,16 @@ export type RawEntity = {
     id: string;
     type: string;
 };
+export type RawLink = {
+    e1: string;
+    a: string;
+    e2: string;
+};
 export declare function isSystemType(type: string): boolean;
 export declare function typeKey(type: string): string;
-export declare function entryFromFacts(entity: RawEntity, facts: RawFact[]): Entry;
+export declare function entryFromFacts(entity: RawEntity, facts: RawFact[], links?: RawLink[]): Entry;
 export declare function groupFactsByEntity(facts: RawFact[]): Map<string, RawFact[]>;
+export declare function groupLinksBySource(links: RawLink[]): Map<string, RawLink[]>;
 /**
  * For each entry, replace string ids in `expand` field keys with the resolved Entry.
  * Lookups are batched in parallel.

package/dist/cms/internal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"internal.d.ts","sourceRoot":"","sources":["../../src/cms/internal.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAe,MAAM,YAAY,CAAC;AAErD,MAAM,MAAM,OAAO,GAAG;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAA;CAAE,CAAC;AAC7E,MAAM,MAAM,SAAS,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAwBrD,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAElD;AAED,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE5C;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,KAAK,CAYzE;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,CAQ3E;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,KAAK,EAAE,EAChB,UAAU,EAAE,MAAM,EAAE,EACpB,WAAW,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,GACjD,OAAO,CAAC,KAAK,EAAE,CAAC,CA+BlB;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAElD"}
+{"version":3,"file":"internal.d.ts","sourceRoot":"","sources":["../../src/cms/internal.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAe,MAAM,YAAY,CAAC;AAErD,MAAM,MAAM,OAAO,GAAG;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAA;CAAE,CAAC;AAC7E,MAAM,MAAM,SAAS,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AACrD,MAAM,MAAM,OAAO,GAAG;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAwB5D,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAElD;AAED,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE5C;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,KAAK,CAAC,EAAE,OAAO,EAAE,GAAG,KAAK,CA+B5F;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,CAQ3E;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,CAQ3E;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,KAAK,EAAE,EAChB,UAAU,EAAE,MAAM,EAAE,EACpB,WAAW,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,KAAK,GAAG,IAAI,CAAC,GACjD,OAAO,CAAC,KAAK,EAAE,CAAC,CA+BlB;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAElD"}

package/dist/cms/scaffold.d.ts

@@ -12,6 +12,11 @@ export type ScaffoldOptions = {
     expand?: string[];
     /** Override the CMS server URL. Default: http://localhost:4096 */
     url?: string;
+    /**
+     * Project directory for multi-instance backends (e.g. opencode requires this).
+     * Baked into the generated client literal so requests route to the correct project.
+     */
+    directory?: string;
 };
 export declare function scaffoldConsumer(opts: ScaffoldOptions): string;
 export declare function scaffoldFilename(opts: ScaffoldOptions): string;

package/dist/cms/scaffold.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scaffold.d.ts","sourceRoot":"","sources":["../../src/cms/scaffold.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,MAAM,MAAM,eAAe,GAAG;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,kEAAkE;IAClE,GAAG,CAAC,EAAE,MAAM,CAAC;CACd,CAAC;AAwGF,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,CAW9D;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,CAW9D"}
+{"version":3,"file":"scaffold.d.ts","sourceRoot":"","sources":["../../src/cms/scaffold.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,MAAM,MAAM,eAAe,GAAG;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,kEAAkE;IAClE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AA6GF,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,CAW9D;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,CAW9D"}

package/dist/cms/types.d.ts

@@ -25,6 +25,18 @@ export type ListOptions = {
 export type GetOptions = {
     expand?: string[];
 };
+export type SubscribeExtras = {
+    /** Called when a poll fails. If absent, errors are silently swallowed. */
+    onError?: (err: unknown) => void;
+    /**
+     * Custom equality check between consecutive results. Default: deep JSON
+     * comparison. Override with a faster check (e.g. id/version-based) for
+     * very large payloads.
+     */
+    equals?: (prev: unknown, next: unknown) => boolean;
+};
+export type ListSubscribeOptions = ListOptions & SubscribeExtras;
+export type EntrySubscribeOptions = GetOptions & SubscribeExtras;
 export type Unsubscribe = () => void;
 export type ListSubscriber<T extends Record<string, unknown> = Record<string, unknown>> = (entries: Entry<T>[]) => void;
 export type EntrySubscriber<T extends Record<string, unknown> = Record<string, unknown>> = (entry: Entry<T> | null) => void;

package/dist/cms/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/cms/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,WAAW,CAAC;AAEhD,MAAM,MAAM,KAAK,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI;IAC/E,oEAAoE;IACpE,EAAE,EAAE,MAAM,CAAC;IACX,sEAAsE;IACtE,IAAI,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,MAAM,EAAE,WAAW,CAAC;IACpB,4FAA4F;IAC5F,MAAM,EAAE,CAAC,CAAC;CACX,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,2EAA2E;IAC3E,MAAM,CAAC,EAAE,KAAK,GAAG,WAAW,CAAC;IAC7B,oFAAoF;IACpF,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,iCAAiC;IACjC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC;AACrC,MAAM,MAAM,cAAc,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,CACxF,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,KAChB,IAAI,CAAC;AACV,MAAM,MAAM,eAAe,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,CACzF,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,GAAG,IAAI,KACnB,IAAI,CAAC;AAEV,MAAM,MAAM,UAAU,GAAG;IACvB,mDAAmD;IACnD,GAAG,EAAE,MAAM,CAAC;IACZ,4BAA4B;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,wFAAwF;IACxF,QAAQ,EAAE,OAAO,CAAC;IAClB,wCAAwC;IACxC,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,iGAAiG;IACjG,GAAG,EAAE,MAAM,CAAC;IACZ;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4EAA4E;IAC5E,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,sFAAsF;IACtF,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB,sDAAsD;IACtD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,OAAO,GAAG,KAAK,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/cms/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,WAAW,CAAC;AAEhD,MAAM,MAAM,KAAK,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI;IAC/E,oEAAoE;IACpE,EAAE,EAAE,MAAM,CAAC;IACX,sEAAsE;IACtE,IAAI,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,MAAM,EAAE,WAAW,CAAC;IACpB,4FAA4F;IAC5F,MAAM,EAAE,CAAC,CAAC;CACX,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,2EAA2E;IAC3E,MAAM,CAAC,EAAE,KAAK,GAAG,WAAW,CAAC;IAC7B,oFAAoF;IACpF,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,iCAAiC;IACjC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,0EAA0E;IAC1E,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,CAAC;IACjC;;;;OAIG;IACH,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC;CACpD,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG,WAAW,GAAG,eAAe,CAAC;AACjE,MAAM,MAAM,qBAAqB,GAAG,UAAU,GAAG,eAAe,CAAC;AAEjE,MAAM,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC;AACrC,MAAM,MAAM,cAAc,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,CACxF,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,KAChB,IAAI,CAAC;AACV,MAAM,MAAM,eAAe,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,CACzF,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,GAAG,IAAI,KACnB,IAAI,CAAC;AAEV,MAAM,MAAM,UAAU,GAAG;IACvB,mDAAmD;IACnD,GAAG,EAAE,MAAM,CAAC;IACZ,4BAA4B;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,wFAAwF;IACxF,QAAQ,EAAE,OAAO,CAAC;IAClB,wCAAwC;IACxC,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,iGAAiG;IACjG,GAAG,EAAE,MAAM,CAAC;IACZ;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4EAA4E;IAC5E,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,sFAAsF;IACtF,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB,sDAAsD;IACtD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,OAAO,GAAG,KAAK,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trellis",
-  "version": "3.1.1",
+  "version": "3.1.3",
   "description": "Agentic State Engine — event-sourced causal graph with branching, decision traces, and realtime sync for AI-native applications",
   "type": "module",
   "main": "./dist/index.js",
@@ -99,6 +99,7 @@
     "logo.png",
     "logo.svg",
     "LICENSE",
+    "CHANGELOG.md",
     "README.md"
   ],
   "scripts": {
@@ -108,7 +109,7 @@
     "mcp:docs": "bun run src/mcp/docs.ts",
     "build": "bun build src/index.ts src/core/index.ts src/vcs/index.ts src/embeddings/index.ts src/links/index.ts src/decisions/index.ts src/server/index.ts src/client/index.ts src/react/index.ts src/db/index.ts src/cli/index.ts src/cms/index.ts --outdir dist --target bun --splitting --format esm --root src --external @xenova/transformers --external @huggingface/transformers --external react && mkdir -p dist/ui && cp src/ui/client.html dist/ui/client.html && tsc -p tsconfig.build.json --emitDeclarationOnly --noEmit false --noEmitOnError false && bun run build:inspector",
     "build:inspector": "vite build --config vite.inspector.config.ts",
-    "test": "bun test test/core test/vcs test/git test/p2 test/p3 test/p4 test/p5 test/p6 test/p7 test/engine.test.ts",
+    "test": "bun test test/core test/cms test/vcs test/git test/p2 test/p3 test/p4 test/p5 test/p6 test/p7 test/engine.test.ts",
     "test:all": "bun test",
     "prepublishOnly": "npm run test && npm run build"
   },