@adia-ai/a2ui-compose 0.0.1 → 0.1.0

package/engines/zettel/state-cache.js

@@ -0,0 +1,153 @@
+/**
+ * State-cache — bounded LRU for multi-turn gen-UI compositions.
+ *
+ * Keyed by `state_id`. Bounded by `maxSize` (default 64; configurable via the
+ * `A2UI_STATE_CACHE_SIZE` env var). When the cache is at capacity, the
+ * least-recently-touched entry is evicted on the next `set`. Entries are
+ * touched on every `get` and on every overwriting `set`. `peek` reads without
+ * touching recency — used by the issue-reporter when attaching traces.
+ *
+ * Pure data structure: no I/O, no LLM, no async. Safe to instantiate as a
+ * server-process singleton; survives only as long as the MCP process.
+ *
+ * Recommended entry shape (caller-enforced — the cache itself stores any object):
+ *   {
+ *     state_id,            // mirrors the key
+ *     intent,              // user's request that produced this state
+ *     html,                // materialized output
+ *     plan,                // chunk-binding plan (or null for refinements)
+ *     ops_history,         // chronological A2UI message list
+ *     parent_state_id,     // chain-back for refinements (null for created roots)
+ *     created_at,          // ISO timestamp
+ *   }
+ *
+ * Spec: docs/specs/genui-multiturn-architecture.md §2.2 + §4.4.
+ */
+
+const DEFAULT_MAX_SIZE = 64;
+
+function envMaxSize() {
+  const v = process.env.A2UI_STATE_CACHE_SIZE;
+  if (!v) return null;
+  const n = parseInt(v, 10);
+  return Number.isFinite(n) && n > 0 ? n : null;
+}
+
+export class StateCache {
+  constructor({ maxSize } = {}) {
+    this.maxSize = maxSize ?? envMaxSize() ?? DEFAULT_MAX_SIZE;
+    this._map = new Map();
+  }
+
+  /** Insert or update; touches recency. Returns the state_id. */
+  set(state_id, state) {
+    if (this._map.has(state_id)) {
+      this._map.delete(state_id);
+    } else if (this._map.size >= this.maxSize) {
+      const firstKey = this._map.keys().next().value;
+      this._map.delete(firstKey);
+    }
+    this._map.set(state_id, state);
+    return state_id;
+  }
+
+  /** Read; touches recency on hit. Returns null on miss. */
+  get(state_id) {
+    if (!this._map.has(state_id)) return null;
+    const entry = this._map.get(state_id);
+    this._map.delete(state_id);
+    this._map.set(state_id, entry);
+    return entry;
+  }
+
+  /** Read without touching recency. Returns null on miss. */
+  peek(state_id) {
+    return this._map.get(state_id) ?? null;
+  }
+
+  has(state_id) {
+    return this._map.has(state_id);
+  }
+
+  /** Returns true if removed, false if absent. */
+  evict(state_id) {
+    return this._map.delete(state_id);
+  }
+
+  /** Insertion-ordered list of keys (oldest → newest). */
+  list() {
+    return Array.from(this._map.keys());
+  }
+
+  size() {
+    return this._map.size;
+  }
+
+  clear() {
+    this._map.clear();
+  }
+}
+
+/**
+ * Mint a state_id for a freshly created composition.
+ *
+ * Format: `<intent-prefix>-<rand4>-v<N>-<unix-min>`
+ *  - intent-prefix — first whitespace-delimited word of the intent, lowercased,
+ *    non-alphanumeric stripped, capped at 12 chars; falls back to `state` when empty.
+ *  - rand4 — 4 hex chars; prevents collisions on identical intents.
+ *  - v<N> — 1-based version (v1 for created, v2+ for refinements).
+ *  - unix-min — Math.floor(Date.now() / 60000), giving a compact minute-resolution
+ *    timestamp that humans can scan for chronological order.
+ *
+ * Spec: docs/specs/genui-multiturn-architecture.md §2.2.
+ *
+ * @param {string} intent
+ * @param {number} [version=1]
+ * @returns {string}
+ */
+export function mintStateId(intent, version = 1) {
+  const prefix = (intent ?? '')
+    .toLowerCase()
+    .split(/\s+/)[0]
+    ?.replace(/[^a-z0-9]/g, '')
+    ?.slice(0, 12) || 'state';
+  const rand4 = Math.floor(Math.random() * 0xffff).toString(16).padStart(4, '0');
+  const unixMin = Math.floor(Date.now() / 60000);
+  const v = Math.max(1, Math.floor(version));
+  return `${prefix}-${rand4}-v${v}-${unixMin}`;
+}
+
+/**
+ * Mint the next state_id in a refinement chain.
+ *
+ * Preserves the parent's prefix + rand4 stem so the lineage is visible at a
+ * glance (`dash-3f9a-v1-…` → `dash-3f9a-v2-…`). Bumps the version and
+ * timestamp. Falls back to a fresh `mintStateId` if the parent id doesn't
+ * match the expected format.
+ *
+ * @param {string} parentStateId
+ * @param {number} version — should be parent's version + 1
+ * @returns {string}
+ */
+export function mintNextStateId(parentStateId, version) {
+  const m = parentStateId?.match(/^([a-z0-9]+)-([a-f0-9]{4})-v\d+-\d+$/);
+  if (!m) return mintStateId(parentStateId ?? '', version);
+  const [, prefix, rand4] = m;
+  const unixMin = Math.floor(Date.now() / 60000);
+  const v = Math.max(1, Math.floor(version));
+  return `${prefix}-${rand4}-v${v}-${unixMin}`;
+}
+
+let _cache = null;
+
+/** Module-level singleton. Lazily instantiated. */
+export function getStateCache(opts) {
+  if (!_cache) _cache = new StateCache(opts);
+  return _cache;
+}
+
+/** Replace the singleton; useful for tests + server boot. */
+export function resetStateCache(opts) {
+  _cache = new StateCache(opts);
+  return _cache;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/a2ui-compose",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "description": "AdiaUI A2UI compose engine — framework-agnostic. Takes natural-language intents + a catalog and produces A2UI protocol messages. Pairs with `@adia-ai/a2ui-retrieval` (intent classification, catalog lookup) and `@adia-ai/a2ui-validator` (schema + semantic checks).",
   "type": "module",
   "exports": {