dna-sdk 0.1.0 → 0.2.0

package/dist/memory/index.d.ts

@@ -21,3 +21,4 @@ export * from "./memoryType.js";
 export * from "./encodingContext.js";
 export * from "./retrieval.js";
 export * from "./ecphory.js";
+export * from "./semantic.js";

package/dist/memory/index.js

@@ -21,3 +21,4 @@ export * from "./memoryType.js";
 export * from "./encodingContext.js";
 export * from "./retrieval.js";
 export * from "./ecphory.js";
+export * from "./semantic.js";

package/dist/memory/semantic.d.ts

@@ -0,0 +1,51 @@
+import { EcphoryScore, EngramRef } from "./ecphory.js";
+import { RecallPolicy } from "./policy.js";
+/**
+ * The spec fields that carry an engram's semantic payload — the SAME planes
+ * the ecphory content paths score (`area` for Path 1; `summary`/`title`/`body`
+ * for Path 2). The cue-side cosine embeds exactly this text, NOT the index's
+ * full `documentText` blob: names, dates, affect labels and other metadata
+ * strings would dilute the similarity without carrying meaning.
+ */
+export declare const ENGRAM_TEXT_FIELDS: readonly ["area", "title", "summary", "body"];
+/** The text a memory means, for cue-side embedding (see `ENGRAM_TEXT_FIELDS`). */
+export declare function engramText(spec: Record<string, unknown>): string;
+/**
+ * Cosine similarity between two vectors. 0.0 when either has no signal
+ * (all-zero — the fake embedder's honest "no tokens" vector). Accumulation
+ * order is index order, so the result is bit-identical to the Py twin.
+ */
+export declare function cosineSimilarity(a: readonly number[], b: readonly number[]): number;
+/**
+ * Per-name cosine against the cue vector, in the shape `scoreEngram`'s Path 3
+ * consumes. Non-positive cosines are dropped (no signal, never a penalty).
+ * On a duplicate name the FIRST vector wins (deterministic).
+ */
+export declare function semanticScoresFromVectors(names: readonly string[], vectors: readonly (readonly number[])[], queryVector: readonly number[]): Record<string, number>;
+/**
+ * The existing ecphory ranking over candidate engrams, with the semantic hook
+ * fed. `scoreEngram` (cue = the query) + Semon adjustments, gated by
+ * `RecallPolicy.directThreshold`, sorted (score desc, name asc — fully
+ * deterministic, Py↔TS identical). Pure — the shared parity core.
+ */
+export declare function ecphoryRank(engrams: readonly EngramRef[], query: string, semanticScores?: Record<string, number>, policy?: RecallPolicy, now?: number): EcphoryScore[];
+/** A recall hit as the fusion sees it — `name` + `score` plus passthrough keys. */
+export interface RecallHit {
+    name?: string;
+    score?: number;
+    [key: string]: unknown;
+}
+/**
+ * Fuse the existing recall ranking with the semantic ecphory ranking.
+ *
+ * `hits` is the recall ranking (best-first); `engrams` are the same candidates
+ * as `EngramRef` views. The two rank lists are fused with
+ * `reciprocalRankFusion` — a candidate below the ecphory threshold keeps its
+ * recall rank (one-list RRF), never disappears. Returns NEW hit objects in
+ * fused order, annotated: `score` = fused RRF score, `score_recall` = the
+ * pre-fusion score, `rank_recall` / `rank_ecphory` (1-based), `score_ecphory`
+ * and `semantic` (cue↔memory cosine) when present. Rankings are keyed by hit
+ * `name`; on a duplicate the first (best) hit wins. Pure; the caller owns
+ * truncation to top-k.
+ */
+export declare function fuseSemanticRecall(hits: readonly RecallHit[], engrams: readonly EngramRef[], query: string, semanticScores: Record<string, number>, policy?: RecallPolicy, now?: number, rrfK?: number): RecallHit[];

package/dist/memory/semantic.js

@@ -0,0 +1,136 @@
+/**
+ * Semantic recall — embedding similarity fed into the EXISTING ecphory ranking
+ * (TS twin of `dna/memory/semantic.py`, s-memory-semantic-recall).
+ *
+ * Activates the inert semantic hook: `scoreEngram`'s Path 3 blends an embedding
+ * cosine into the primary content score (`RecallPolicy.cosineWeight`), and the
+ * two rankings — the recall verb's and ecphory's — are fused with the same
+ * `reciprocalRankFusion` the search provider uses for its dense + lexical
+ * planes. Pure: no kernel, no IO; parity is pinned by the shared
+ * `memory-scoring-parity.json` fixture.
+ */
+import { DEFAULT_RRF_K, reciprocalRankFusion } from "../adapters/search/rrf.js";
+import { applySemonAdjustments, scoreEngram } from "./ecphory.js";
+import { DEFAULT_RECALL_POLICY } from "./policy.js";
+/**
+ * The spec fields that carry an engram's semantic payload — the SAME planes
+ * the ecphory content paths score (`area` for Path 1; `summary`/`title`/`body`
+ * for Path 2). The cue-side cosine embeds exactly this text, NOT the index's
+ * full `documentText` blob: names, dates, affect labels and other metadata
+ * strings would dilute the similarity without carrying meaning.
+ */
+export const ENGRAM_TEXT_FIELDS = ["area", "title", "summary", "body"];
+/** The text a memory means, for cue-side embedding (see `ENGRAM_TEXT_FIELDS`). */
+export function engramText(spec) {
+    return ENGRAM_TEXT_FIELDS
+        .filter((f) => spec[f])
+        .map((f) => String(spec[f]))
+        .join(" ")
+        .trim();
+}
+/**
+ * Cosine similarity between two vectors. 0.0 when either has no signal
+ * (all-zero — the fake embedder's honest "no tokens" vector). Accumulation
+ * order is index order, so the result is bit-identical to the Py twin.
+ */
+export function cosineSimilarity(a, b) {
+    let dot = 0.0;
+    let normA = 0.0;
+    let normB = 0.0;
+    const n = Math.min(a.length, b.length);
+    for (let i = 0; i < n; i++) {
+        dot += a[i] * b[i];
+        normA += a[i] * a[i];
+        normB += b[i] * b[i];
+    }
+    if (normA === 0.0 || normB === 0.0)
+        return 0.0;
+    return dot / Math.sqrt(normA) / Math.sqrt(normB);
+}
+/**
+ * Per-name cosine against the cue vector, in the shape `scoreEngram`'s Path 3
+ * consumes. Non-positive cosines are dropped (no signal, never a penalty).
+ * On a duplicate name the FIRST vector wins (deterministic).
+ */
+export function semanticScoresFromVectors(names, vectors, queryVector) {
+    const scores = {};
+    const n = Math.min(names.length, vectors.length);
+    for (let i = 0; i < n; i++) {
+        const name = names[i];
+        if (name in scores)
+            continue;
+        const cos = cosineSimilarity(queryVector, vectors[i]);
+        if (cos > 0.0)
+            scores[name] = cos;
+    }
+    return scores;
+}
+/**
+ * The existing ecphory ranking over candidate engrams, with the semantic hook
+ * fed. `scoreEngram` (cue = the query) + Semon adjustments, gated by
+ * `RecallPolicy.directThreshold`, sorted (score desc, name asc — fully
+ * deterministic, Py↔TS identical). Pure — the shared parity core.
+ */
+export function ecphoryRank(engrams, query, semanticScores, policy = DEFAULT_RECALL_POLICY, now = Date.now()) {
+    const cueCtx = { query };
+    const ranked = [];
+    for (const engram of engrams) {
+        let s = scoreEngram(engram, cueCtx, semanticScores, policy);
+        s = applySemonAdjustments(s, now, policy);
+        if (s.score >= policy.directThreshold)
+            ranked.push(s);
+    }
+    ranked.sort((x, y) => y.score - x.score || (x.engram.name < y.engram.name ? -1 : x.engram.name > y.engram.name ? 1 : 0));
+    return ranked;
+}
+/**
+ * Fuse the existing recall ranking with the semantic ecphory ranking.
+ *
+ * `hits` is the recall ranking (best-first); `engrams` are the same candidates
+ * as `EngramRef` views. The two rank lists are fused with
+ * `reciprocalRankFusion` — a candidate below the ecphory threshold keeps its
+ * recall rank (one-list RRF), never disappears. Returns NEW hit objects in
+ * fused order, annotated: `score` = fused RRF score, `score_recall` = the
+ * pre-fusion score, `rank_recall` / `rank_ecphory` (1-based), `score_ecphory`
+ * and `semantic` (cue↔memory cosine) when present. Rankings are keyed by hit
+ * `name`; on a duplicate the first (best) hit wins. Pure; the caller owns
+ * truncation to top-k.
+ */
+export function fuseSemanticRecall(hits, engrams, query, semanticScores, policy = DEFAULT_RECALL_POLICY, now = Date.now(), rrfK = DEFAULT_RRF_K) {
+    if (!hits.length)
+        return [];
+    const recallOrder = [];
+    const firstByName = new Map();
+    for (const hit of hits) {
+        const name = String(hit.name ?? "");
+        if (!name || firstByName.has(name))
+            continue;
+        firstByName.set(name, hit);
+        recallOrder.push(name);
+    }
+    const directs = ecphoryRank(engrams, query, semanticScores, policy, now);
+    const ecphoryOrder = directs.map((s) => s.engram.name);
+    const fused = reciprocalRankFusion([recallOrder, ecphoryOrder], rrfK);
+    const recallPos = new Map(recallOrder.map((name, i) => [name, i + 1]));
+    const ecphoryPos = new Map(ecphoryOrder.map((name, i) => [name, i + 1]));
+    const ecphoryScore = new Map(directs.map((s) => [s.engram.name, s.score]));
+    const out = [];
+    for (const [name, fusedScore] of fused) {
+        const src = firstByName.get(name);
+        if (!src)
+            continue; // ecphory-only name — impossible when engrams ⊆ hits
+        const hit = { ...src };
+        hit.score_recall = Number(src.score ?? 0.0);
+        hit.score = fusedScore;
+        hit.rank_recall = recallPos.get(name);
+        if (ecphoryPos.has(name)) {
+            hit.rank_ecphory = ecphoryPos.get(name);
+            hit.score_ecphory = ecphoryScore.get(name);
+        }
+        const cos = semanticScores[name] ?? 0.0;
+        if (cos > 0.0)
+            hit.semantic = cos;
+        out.push(hit);
+    }
+    return out;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dna-sdk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "DNA — Domain Notation of Anything (TypeScript SDK)",
   "type": "module",
   "license": "MIT",