stratagate-dsh 0.2.34 → 0.2.35

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.2.35 - 2026-08-27
+
+- Return compact Event, Knowledge Graph, and raw-memory search cards while keeping full details in expand tools.
+- Rename tool-facing ranking output to `rankScore` and document that it is not confidence or factual accuracy.
+- Filter relation-only Knowledge Graph matches, report matched fields, and preserve distinct same-name entity types.
+
 ## 0.2.34 - 2026-08-27
 
 - Add explicit `session` and `namespace` scopes to block and raw-memory retrieval.

package/README.md

@@ -110,6 +110,13 @@ blocks, and `open_tail_pending` means matching turns exist but have not sealed y
 so a raw hit's `blockId` can be followed by `memory_get_blocks(scope=namespace)`
 or `memory_expand_block` without an unexplained visibility mismatch.
 
+Search responses use compact cards by default. Event cards keep `id`, `title`, `summary`, source time,
+status/scope, `sourceBlockId`, `batchId`, and `evidenceRefs`; graph cards keep `id`, `name`, type,
+aliases, current state, status, and explainable `matchedFields`/`matchReason`; raw cards keep the
+message id, `blockId`, role, turn range, and a bounded excerpt. Narrative, quotes, source message lists,
+full graph facts/edges, and nearby raw messages are available through the corresponding expand tools.
+`rankScore` is a BM25/RRF ordering metric only—it is not a probability, confidence, or factual-accuracy score.
+
 Legacy Element tool names remain available only for compatibility with existing installations.
 
 The prompt protocol requires assessment before relying on retrieved evidence. Search does not strengthen a memory. Non-empty `memory_record_use` submissions accept only evidence adopted by a sufficient assessment of the selected batch and use the DSH tool call id as an idempotency receipt. `batch_id` may be omitted for compatibility in strictly sequential flows, where it selects the latest batch; parallel or interleaved retrievals must pass it explicitly. Assessment responses list rejected refs and their reasons.

package/dist/index.js

@@ -3479,6 +3479,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 +3497,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);
@@ -4718,7 +4747,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 +4755,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 +4776,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();
@@ -5244,7 +5284,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 +5484,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 +5689,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 +5707,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 +5724,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 +5740,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" },