stratagate-dsh 0.2.34 → 0.2.36

package/dist/index.js

@@ -2554,7 +2554,7 @@ function errorMessage(error) {
 }
 var STRATAGATE_CONSTRUCTOR_TOKEN = /* @__PURE__ */ Symbol("StrataGate constructor");
 var StrataGate = class _StrataGate {
-  blockTurnSize;
+  blockTurnSizeValue;
   blockDecayLambdaValue;
   summarizer;
   extractor;
@@ -2586,7 +2586,7 @@ var StrataGate = class _StrataGate {
     if (token !== STRATAGATE_CONSTRUCTOR_TOKEN) {
       throw new TypeError("Use StrataGate.open() for SQLite or StrataGate.inMemory() for explicit ephemeral storage");
     }
-    this.blockTurnSize = Math.max(1, Math.floor(options.blockTurnSize ?? DEFAULT_BLOCK_TURN_SIZE));
+    this.blockTurnSizeValue = Math.max(1, Math.floor(options.blockTurnSize ?? DEFAULT_BLOCK_TURN_SIZE));
     const blockDecayLambda = options.blockDecayLambda ?? BLOCK_DECAY_LAMBDA;
     if (!Number.isFinite(blockDecayLambda) || blockDecayLambda < 0) {
       throw new TypeError("blockDecayLambda must be a non-negative finite number");
@@ -2734,6 +2734,18 @@ var StrataGate = class _StrataGate {
   get storageRevision() {
     return this.revision;
   }
+  get blockTurnSize() {
+    return this.blockTurnSizeValue;
+  }
+  async setBlockTurnSize(value) {
+    if (!Number.isSafeInteger(value) || value < 1) {
+      throw new TypeError("blockTurnSize must be a positive integer");
+    }
+    if (value === this.blockTurnSizeValue) return;
+    await this.commitMutation(() => {
+      this.blockTurnSizeValue = value;
+    });
+  }
   get blockDecayLambda() {
     return this.blockDecayLambdaValue;
   }
@@ -3479,6 +3491,16 @@ var StrataGate = class _StrataGate {
   }
   async searchGraphNodes(query, limit = 8) {
     const candidates = this.graphNodes.filter((node) => node.status === "active" || node.status === "disputed");
+    const queryTokens = [...new Set(searchTokens(query))];
+    const fieldValues = (node) => [
+      ["name", node.name],
+      ["aliases", node.aliases.join(" ")],
+      ["tags", (node.tags ?? []).join(" ")],
+      ["type", node.type],
+      ["currentState", node.currentState],
+      ["facts", node.facts.map((fact) => `${fact.key} ${Array.isArray(fact.value) ? fact.value.join(" ") : fact.value}`).join(" ")],
+      ["relations", this.graphEdges.filter((edge) => edge.fromNodeId === node.id || edge.toNodeId === node.id).map(({ relation }) => relation).join(" ")]
+    ];
     const ranked = bm25Rank(candidates, query, (node) => weightedSearchTokens([
       [node.name, 6],
       [node.aliases.join(" "), 5],
@@ -3487,9 +3509,28 @@ var StrataGate = class _StrataGate {
       [node.currentState, 4],
       [node.facts.map((fact) => `${fact.key} ${Array.isArray(fact.value) ? fact.value.join(" ") : fact.value}`).join(" "), 4],
       [this.graphEdges.filter((edge) => edge.fromNodeId === node.id || edge.toNodeId === node.id).map(({ relation }) => relation).join(" "), 3]
-    ])).slice(0, Math.max(1, Math.min(20, limit)));
+    ])).filter(({ item }) => {
+      const fields = fieldValues(item);
+      const matches = fields.filter(([, value]) => {
+        const haystack = new Set(searchTokens(value));
+        return queryTokens.some((token) => haystack.has(token));
+      }).map(([field]) => field);
+      if (!matches.some((field) => field !== "relations")) return false;
+      return matches.some((field) => field !== "relations");
+    }).slice(0, Math.max(1, Math.min(20, limit)));
     if (searchTokens(query).length > 0 && ranked.length === 0) return [];
-    return ranked.map(({ item: node, score }) => ({ node, score }));
+    return ranked.map(({ item: node, score }) => {
+      const matchedFields = fieldValues(node).filter(([, value]) => {
+        const haystack = new Set(searchTokens(value));
+        return queryTokens.some((token) => haystack.has(token));
+      }).map(([field]) => field);
+      return {
+        node,
+        score,
+        matchedFields,
+        matchReason: `Lexical match in ${matchedFields.join(", ") || "indexed fields"}; score is ranking-only.`
+      };
+    });
   }
   requireGraphProjectionJob(id) {
     const job = this.graphProjectionJobs.get(id);
@@ -4614,6 +4655,17 @@ var DshMetadataStore = class {
     this.database = new DatabaseSync2(filename);
     this.database.exec(METADATA_SCHEMA);
   }
+  blockTurnSize() {
+    const row = this.database.prepare("SELECT value FROM stratagate_dsh_settings WHERE key = 'blockTurnSize'").get();
+    const value = Number(row?.value);
+    return Number.isSafeInteger(value) && value >= 1 ? value : null;
+  }
+  setBlockTurnSize(value) {
+    if (!Number.isSafeInteger(value) || value < 1) {
+      throw new TypeError("blockTurnSize must be a positive integer");
+    }
+    this.setSetting("blockTurnSize", value);
+  }
   blockDecayLambda() {
     const row = this.database.prepare("SELECT value FROM stratagate_dsh_settings WHERE key = 'blockDecayLambda'").get();
     const value = Number(row?.value);
@@ -4623,11 +4675,14 @@ var DshMetadataStore = class {
     if (!Number.isFinite(value) || value < 0) {
       throw new TypeError("blockDecayLambda must be a non-negative finite number");
     }
+    this.setSetting("blockDecayLambda", value);
+  }
+  setSetting(key, value) {
     this.database.prepare(`
       INSERT INTO stratagate_dsh_settings (key, value, updated_at)
-      VALUES ('blockDecayLambda', ?, ?)
+      VALUES (?, ?, ?)
       ON CONFLICT (key) DO UPDATE SET value = excluded.value, updated_at = excluded.updated_at
-    `).run(String(value), (/* @__PURE__ */ new Date()).toISOString());
+    `).run(key, String(value), (/* @__PURE__ */ new Date()).toISOString());
   }
   workspaceName(namespace) {
     const row = this.database.prepare("SELECT display_name FROM stratagate_dsh_workspaces WHERE namespace = ?").get(namespace);
@@ -4668,6 +4723,7 @@ var StrataGateRuntime = class {
     this.models = models;
     this.onIngestError = onIngestError;
     this.flushNativeSession = flushNativeSession;
+    this.blockTurnSize = config.blockTurnSize;
     this.blockDecayLambda = config.blockDecayLambda;
   }
   config;
@@ -4685,6 +4741,7 @@ var StrataGateRuntime = class {
   batchSequence = 0;
   closed = false;
   ingestError;
+  blockTurnSize;
   blockDecayLambda;
   acceptEvent(session, event) {
     if (this.closed) return;
@@ -4718,7 +4775,7 @@ var StrataGateRuntime = class {
     return this.batch(session, results.map(({ event }) => ({
       ref: `event:${event.id}`,
       target: { eventIds: [event.id], elementIds: [] }
-    })), results);
+    })), results.map(({ event, score }) => compactEvent(event, score)));
   }
   async searchElements(session, query, options = {}) {
     await this.flush();
@@ -4726,7 +4783,18 @@ var StrataGateRuntime = class {
     return this.batch(session, results.map((result) => ({
       ref: `element:${result.elementId}:fact:${result.id}`,
       target: { eventIds: [], elementIds: [result.elementId] }
-    })), results);
+    })), results.map((result) => ({
+      id: result.id,
+      elementId: result.elementId,
+      name: result.name,
+      type: result.type,
+      factKey: result.fact.key,
+      value: Array.isArray(result.fact.value) ? result.fact.value.join(", ") : result.fact.value,
+      validFrom: result.fact.validFrom,
+      validTo: result.fact.validTo,
+      rankScore: result.score,
+      scoreMeaning: "Ranking-only BM25/RRF score; not confidence or factual accuracy."
+    })));
   }
   async searchRaw(session, query, limit, scope = "namespace") {
     await this.flush();
@@ -4736,7 +4804,7 @@ var StrataGateRuntime = class {
     return this.batch(session, results.map((result, index) => ({
       ref: `raw:${result.blockId}:${result.message.id}:${index}`,
       target: { eventIds: [], elementIds: [] }
-    })), results, { scope, namespace: this.namespaceFor(session), threadId });
+    })), results.map(compactRawHit), { scope, namespace: this.namespaceFor(session), threadId });
   }
   async blocks(session, scope = "session") {
     await this.flush();
@@ -5035,6 +5103,7 @@ var StrataGateRuntime = class {
     if (this.config.database === ":memory:" || !existsSync(this.config.database)) return;
     const metadata = new DshMetadataStore(this.config.database);
     try {
+      this.blockTurnSize = metadata.blockTurnSize() ?? this.config.blockTurnSize;
       this.blockDecayLambda = metadata.blockDecayLambda() ?? this.config.blockDecayLambda;
     } finally {
       metadata.close();
@@ -5043,10 +5112,10 @@ var StrataGateRuntime = class {
     try {
       for (const namespace of storage.listNamespaces()) {
         const loaded = await storage.load(namespace);
-        if (!loaded || loaded.snapshot.blockTurnSize === this.config.blockTurnSize && loaded.snapshot.blockDecayLambda === this.blockDecayLambda) continue;
+        if (!loaded || loaded.snapshot.blockTurnSize === this.blockTurnSize && loaded.snapshot.blockDecayLambda === this.blockDecayLambda) continue;
         await storage.save(namespace, {
           ...loaded.snapshot,
-          blockTurnSize: this.config.blockTurnSize,
+          blockTurnSize: this.blockTurnSize,
           blockDecayLambda: this.blockDecayLambda
         }, loaded.revision);
       }
@@ -5082,7 +5151,7 @@ var StrataGateRuntime = class {
       memory = await StrataGate.open({
         database: this.config.database,
         namespace: key,
-        blockTurnSize: this.config.blockTurnSize,
+        blockTurnSize: this.blockTurnSize,
         blockDecayLambda: this.blockDecayLambda,
         graphProjector: this.models.graphProjector,
         disableElementProjection: true
@@ -5127,6 +5196,18 @@ var StrataGateRuntime = class {
     await update;
     return value;
   }
+  async adminSetBlockTurnSize(value) {
+    if (!Number.isSafeInteger(value) || value < 1) {
+      throw new TypeError("blockTurnSize must be a positive integer");
+    }
+    const update = this.settingsTail.catch(() => {
+    }).then(() => this.applyBlockTurnSize(value));
+    this.settingsTail = update.then(() => {
+    }, () => {
+    });
+    await update;
+    return value;
+  }
   async adminExpandBlock(namespace, id, target) {
     const key = namespace.trim();
     if (!key) throw new TypeError("StrataGate admin namespace must not be empty");
@@ -5141,7 +5222,7 @@ var StrataGateRuntime = class {
       const memory = await StrataGate.open({
         database: this.config.database,
         namespace: key,
-        blockTurnSize: this.config.blockTurnSize,
+        blockTurnSize: this.blockTurnSize,
         blockDecayLambda: this.blockDecayLambda,
         summarizer: this.models.summarizer,
         extractor: this.models.extractor,
@@ -5190,6 +5271,37 @@ var StrataGateRuntime = class {
       }
     }
   }
+  async applyBlockTurnSize(value) {
+    await this.flush();
+    this.blockTurnSize = value;
+    if (this.config.database !== ":memory:") {
+      const metadata = new DshMetadataStore(this.config.database);
+      try {
+        metadata.setBlockTurnSize(value);
+      } finally {
+        metadata.close();
+      }
+    }
+    const openNamespaces = /* @__PURE__ */ new Set();
+    for (const [namespace, opening] of this.spaces) {
+      const memory = await opening;
+      await memory.setBlockTurnSize(value);
+      openNamespaces.add(namespace);
+    }
+    if (this.config.database !== ":memory:" && existsSync(this.config.database)) {
+      const storage = new SqliteStorage({ filename: this.config.database });
+      try {
+        for (const namespace of storage.listNamespaces()) {
+          if (openNamespaces.has(namespace)) continue;
+          const loaded = await storage.load(namespace);
+          if (!loaded || loaded.snapshot.blockTurnSize === value) continue;
+          await storage.save(namespace, { ...loaded.snapshot, blockTurnSize: value }, loaded.revision);
+        }
+      } finally {
+        await storage.close();
+      }
+    }
+  }
   space(session) {
     const namespace = this.namespaceFor(session);
     this.rememberWorkspace(namespace, session.header.cwd);
@@ -5198,7 +5310,7 @@ var StrataGateRuntime = class {
       opening = StrataGate.open({
         database: this.config.database,
         namespace,
-        blockTurnSize: this.config.blockTurnSize,
+        blockTurnSize: this.blockTurnSize,
         blockDecayLambda: this.blockDecayLambda,
         summarizer: this.models.summarizer,
         extractor: this.models.extractor,
@@ -5244,7 +5356,7 @@ var StrataGateRuntime = class {
     return this.batch(session, results.map(({ node }) => ({
       ref: `graph-node:${node.id}`,
       target: { eventIds: node.sourceEventIds, elementIds: [] }
-    })), results);
+    })), results.map(({ node, score, matchedFields, matchReason }) => compactGraphNode(node, score, matchedFields, matchReason)));
   }
   async expandGraphNode(session, id) {
     await this.flush();
@@ -5444,6 +5556,67 @@ function renderBlockSurfaceMessage(context) {
     context.content
   ].join("\n");
 }
+function compactTemporal(event) {
+  const temporal = event.temporal;
+  return Object.fromEntries(Object.entries({
+    mentionedAt: temporal.mentionedAt,
+    happenedStart: temporal.happenedStart,
+    happenedEnd: temporal.happenedEnd,
+    precision: temporal.precision,
+    status: temporal.status,
+    eventType: temporal.eventType
+  }).filter(([, value]) => value !== void 0));
+}
+function compactText2(value, limit = 800) {
+  return value.replace(/\s+/gu, " ").trim().slice(0, limit);
+}
+function compactEvent(event, score) {
+  return {
+    id: event.id,
+    title: compactText2(event.title, 240),
+    summary: compactText2(event.summary),
+    sourceTime: event.temporal.happenedStart ?? event.temporal.mentionedAt ?? event.createdAt,
+    temporal: compactTemporal(event),
+    sourceBlockId: event.sourceBlockId,
+    status: event.status,
+    scope: event.scope,
+    criticality: event.criticality,
+    rankScore: score,
+    scoreMeaning: "Ranking-only BM25/RRF score; not confidence, probability, or factual accuracy."
+  };
+}
+function compactGraphNode(node, score, matchedFields, matchReason) {
+  return {
+    id: node.id,
+    name: node.name,
+    type: node.type,
+    aliases: node.aliases.map((alias) => compactText2(alias, 160)),
+    currentState: compactText2(node.currentState, 500),
+    status: node.status,
+    rankScore: score,
+    ...matchedFields ? { matchedFields } : {},
+    ...matchReason ? { matchReason } : {},
+    scoreMeaning: "Ranking-only BM25/RRF score; not confidence, probability, or factual accuracy."
+  };
+}
+function compactRawHit(result) {
+  const message = {
+    id: result.message.id,
+    role: result.message.role,
+    content: compactText2(result.message.content, 500),
+    createdAt: result.message.createdAt,
+    ...result.message.threadId ? { threadId: result.message.threadId } : {}
+  };
+  return {
+    id: result.message.id,
+    blockId: result.blockId,
+    turnRange: result.turnRange,
+    message,
+    sourceTime: result.message.createdAt,
+    ...result.message.threadId ? { threadId: result.message.threadId } : {},
+    detailHint: "Use memory_expand_block with blockId for complete block/source details."
+  };
+}
 function currentBlockSurfaceMessages(session) {
   const blocks = /* @__PURE__ */ new Map();
   if (!session.surface?.nodes) return blocks;
@@ -5588,7 +5761,7 @@ function sessionOf(exec) {
 function registerMemoryTools(ctx, runtime) {
   ctx.tools.register(defineTool({
     name: "memory_search_events",
-    description: "Search durable StrataGate event memories. Returns a batchId, evidenceRefs, and ranked event cards. Pass that batchId to memory_assess before relying on its evidence.",
+    description: "Search durable StrataGate event memories. Returns a compact batch of event cards (id, title, summary, time, and evidence refs); call memory_expand_event for narrative/quotes/source messages. rankScore is BM25/RRF ordering only, never confidence or factual accuracy. Pass batchId to memory_assess before relying on evidence.",
     parameters: {
       query: { type: "string", required: true, description: "What historical decision, event, preference, or outcome to find." },
       limit: { type: "integer", description: "Maximum results, 1-20." },
@@ -5606,7 +5779,7 @@ function registerMemoryTools(ctx, runtime) {
   }));
   ctx.tools.register(defineTool({
     name: "memory_search_graph",
-    description: "Search the current Event-backed Knowledge Graph for people, projects, organizations, tools, places, facts, and relations. Returns an independently assessable retrieval batch.",
+    description: "Search the current Event-backed Knowledge Graph for people, projects, organizations, tools, places, facts, and relations. Returns compact node cards with matchedFields/matchReason; call memory_expand_graph_node for complete facts and edges. rankScore is BM25/RRF ordering only, never confidence or factual accuracy. Results are independently assessable.",
     parameters: {
       query: { type: "string", required: true },
       limit: { type: "integer", description: "Maximum results, 1-20." }
@@ -5623,7 +5796,7 @@ function registerMemoryTools(ctx, runtime) {
   }));
   ctx.tools.register(defineTool({
     name: "memory_search_elements",
-    description: "Deprecated compatibility search for legacy Element-card data. Prefer memory_search_graph.",
+    description: "Deprecated compatibility search for legacy Element-card data. Returns compact fact hits; rankScore is BM25/RRF ordering only, never confidence or factual accuracy. Prefer memory_search_graph.",
     parameters: {
       query: { type: "string", required: true },
       limit: { type: "integer" },
@@ -5639,7 +5812,7 @@ function registerMemoryTools(ctx, runtime) {
   }));
   ctx.tools.register(defineTool({
     name: "memory_search_raw",
-    description: "Search verbatim archived messages when summarized memories are insufficient. By default searches the whole current namespace; use scope=session to restrict results to the active thread. Returns raw evidence refs and a batchId for assessment.",
+    description: "Search archived messages when summarized memories are insufficient. Returns compact raw hits (message id, blockId, excerpt, role, and time); use memory_expand_block with blockId for complete source details. By default searches the whole current namespace; use scope=session for the active thread. Returns evidence refs and batchId for assessment.",
     parameters: {
       query: { type: "string", required: true },
       limit: { type: "integer" },
@@ -5835,7 +6008,7 @@ function clusterKnowledgeGraph(rawNodes, rawEdges) {
 }
 
 // src/web.ts
-var STRATAGATE_DSH_VERSION = "0.2.32";
+var STRATAGATE_DSH_VERSION = "0.2.36";
 var LEGACY_THREAD_ID = "__legacy__";
 var nodeRequire = createRequire(import.meta.url);
 function installedPackageVersion(names) {
@@ -6024,12 +6197,31 @@ async function overview(runtime) {
   };
 }
 async function updateSettings(runtime, url) {
-  const raw = url.searchParams.get("blockDecayLambda")?.trim() ?? "";
-  const value = Number(raw);
-  if (!raw || !Number.isFinite(value) || value < 0) {
-    throw new AdminHttpError(400, "blockDecayLambda must be a non-negative finite number");
-  }
-  return { blockDecayLambda: await runtime.adminSetBlockDecayLambda(value) };
+  const rawTurnSize = url.searchParams.get("blockTurnSize")?.trim();
+  const rawLambda = url.searchParams.get("blockDecayLambda")?.trim();
+  if (rawTurnSize === void 0 && rawLambda === void 0) {
+    throw new AdminHttpError(400, "blockTurnSize or blockDecayLambda is required");
+  }
+  let turnSize;
+  let lambda;
+  if (rawTurnSize !== void 0) {
+    const value = Number(rawTurnSize);
+    if (!rawTurnSize || !Number.isSafeInteger(value) || value < 1) {
+      throw new AdminHttpError(400, "blockTurnSize must be a positive integer");
+    }
+    turnSize = value;
+  }
+  if (rawLambda !== void 0) {
+    const value = Number(rawLambda);
+    if (!rawLambda || !Number.isFinite(value) || value < 0) {
+      throw new AdminHttpError(400, "blockDecayLambda must be a non-negative finite number");
+    }
+    lambda = value;
+  }
+  const result = {};
+  if (turnSize !== void 0) result.blockTurnSize = await runtime.adminSetBlockTurnSize(turnSize);
+  if (lambda !== void 0) result.blockDecayLambda = await runtime.adminSetBlockDecayLambda(lambda);
+  return result;
 }
 async function importExternalMemory(runtime, req) {
   let suppliedBody = req.body;