dna-sdk 0.1.0 → 0.3.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/dist/testing/index.d.ts

@@ -3,6 +3,9 @@
  *
  * Ship-with-the-SDK conformance suites: an adapter author hands us a factory
  * for their adapter and gets back the battery of cases every conforming
- * implementation must pass. Currently the RecordSearchProvider search-plane kit.
+ * implementation must pass. Currently the RecordSearchProvider search-plane
+ * kit and the memory-scoring kit (the pure twin of Python's memory kit — the
+ * kernel-bound memory VERBS are Py-only by the SDK's declared boundary).
  */
 export { FIXTURE_SCOPE, fixtureRecords, recordSearchConformanceSuite, SearchCaseNotApplicable, type ConformanceProvider, type ProviderFactory, type RecordSearchCase, } from "./recordSearchConformance.js";
+export { KIT_NOW, MemoryCaseNotApplicable, memoryScoringConformanceSuite, type ConformanceEmbedder, type EmbedderFactory, type MemoryScoringCase, } from "./memoryScoringConformance.js";

package/dist/testing/index.js

@@ -3,6 +3,9 @@
  *
  * Ship-with-the-SDK conformance suites: an adapter author hands us a factory
  * for their adapter and gets back the battery of cases every conforming
- * implementation must pass. Currently the RecordSearchProvider search-plane kit.
+ * implementation must pass. Currently the RecordSearchProvider search-plane
+ * kit and the memory-scoring kit (the pure twin of Python's memory kit — the
+ * kernel-bound memory VERBS are Py-only by the SDK's declared boundary).
  */
 export { FIXTURE_SCOPE, fixtureRecords, recordSearchConformanceSuite, SearchCaseNotApplicable, } from "./recordSearchConformance.js";
+export { KIT_NOW, MemoryCaseNotApplicable, memoryScoringConformanceSuite, } from "./memoryScoringConformance.js";

package/dist/testing/memoryScoringConformance.d.ts

@@ -0,0 +1,27 @@
+/** An embedder, structurally: async texts → vectors. */
+export interface ConformanceEmbedder {
+    embed(texts: string[]): Promise<number[][]>;
+}
+export type EmbedderFactory = () => Promise<{
+    embedder: ConformanceEmbedder;
+    cleanup?: () => void | Promise<void>;
+}>;
+/** Simulated clock anchor — the kit never reads the wall clock. */
+export declare const KIT_NOW: number;
+declare class SkipCase extends Error {
+}
+export interface MemoryScoringCase {
+    name: string;
+    requires: string;
+    run(): Promise<void>;
+}
+/**
+ * THE public conformance suite for the pure memory-scoring core.
+ *
+ * @param factory optional async factory returning `{ embedder, cleanup }`;
+ *   omit to run against the deterministic fake floor (fully offline).
+ * @returns one runnable case per invariant — feed them to your test runner
+ *   and `await case.run()`.
+ */
+export declare function memoryScoringConformanceSuite(factory?: EmbedderFactory): MemoryScoringCase[];
+export { SkipCase as MemoryCaseNotApplicable };

package/dist/testing/memoryScoringConformance.js

@@ -0,0 +1,212 @@
+/**
+ * Memory-scoring conformance kit (TS twin of the pure half of
+ * `dna/testing/memory_conformance.py`, s-memory-conformance-kit).
+ *
+ * The behavioral contract of the deterministic memory-scoring core — ecphory
+ * weights + threshold, deterministic ordering, the semantic hook, RRF fusion,
+ * Ebbinghaus decay, bi-temporal fail-open. Twinned 1:1 with the Python
+ * `memory_scoring_conformance_suite`: SAME case names, SAME assertions — the
+ * kit itself is a parity artifact. For anyone evolving the scoring (a public
+ * regression pin) or shipping a custom embedder (the two embedder-driven
+ * cases assert RELATIVE similarity, search-kit style, so a real model passes
+ * too).
+ *
+ * The kernel-bound memory VERB suite (`memory_conformance_suite`) has no TS
+ * twin by design: the verbs (remember/recall/forget/consolidate) are Py-only
+ * by the SDK's declared boundary — TypeScript ships the pure scoring core
+ * only.
+ *
+ * A `factory` is an async zero-arg callable returning `{ embedder, cleanup }`
+ * where `embedder` exposes async `embed(texts) -> vectors` (an
+ * `EmbeddingPort` works as-is). Omit it to run against the deterministic
+ * fake floor — fully offline. Note that `semantic_hook_lifts_paraphrase`
+ * honestly requires the embedder to score an easy paraphrase above the
+ * ecphory gate (`cos >= (directThreshold - noveltyBoost) / cosineWeight`
+ * ~ 0.41) — an embedder that can't clear it cannot power semantic recall.
+ */
+import { fakeEmbedOne } from "../kernel/embedding.js";
+import { currentlyValid, ebbinghausRetention, recallBump, } from "../memory/decay.js";
+import { DEFAULT_DECAY_POLICY, DEFAULT_RECALL_POLICY, } from "../memory/policy.js";
+import { cosineSimilarity, ecphoryRank, engramText, fuseSemanticRecall, semanticScoresFromVectors, } from "../memory/semantic.js";
+/** Simulated clock anchor — the kit never reads the wall clock. */
+export const KIT_NOW = Date.UTC(2026, 6, 10, 12, 0, 0);
+const CREATED_AT = "2026-07-01T00:00:00+00:00";
+class SkipCase extends Error {
+}
+function assert(cond, msg) {
+    if (!cond)
+        throw new Error(msg);
+}
+async function defaultEmbed(texts) {
+    return texts.map((t) => fakeEmbedOne(t));
+}
+const PARAPHRASE_QUERY = "mutating documents safely";
+/**
+ * Target/decoy pair: the query is a PARAPHRASE of the target (no shared
+ * phrase, no token-subset — the cue-match paths score it 0 + novelty) and
+ * unrelated to the decoy. Never-recalled engrams, so Semon's novelty boost
+ * applies to both equally (the decoy still stays under the gate).
+ */
+function paraphraseEngrams() {
+    return [
+        { name: "rem-target", spec: {
+                area: "Feature/kernel",
+                summary: "deep-copy before mutating documents",
+                created_at: CREATED_AT,
+            } },
+        { name: "rem-decoy", spec: {
+                area: "Feature/ops",
+                summary: "safely archive old reports nightly",
+                created_at: CREATED_AT,
+            } },
+    ];
+}
+// ---------------------------------------------------------------------------
+// cases — names + assertions twinned with the Python scoring suite
+// ---------------------------------------------------------------------------
+async function cosineTracksSimilarity(embed) {
+    const texts = [
+        "deep copy before mutating documents",
+        "mutating documents safely",
+        "banana tropical smoothie breakfast",
+    ];
+    const vecs = await embed(texts);
+    const again = await embed([texts[0]]);
+    const selfCos = cosineSimilarity(vecs[0], again[0]);
+    assert(selfCos > 1.0 - 1e-6, `identical text must be maximally similar, got ${selfCos}`);
+    const para = cosineSimilarity(vecs[0], vecs[1]);
+    const unrelated = cosineSimilarity(vecs[0], vecs[2]);
+    assert(para > unrelated, `paraphrase must be closer than unrelated text: ${para} !> ${unrelated}`);
+}
+async function ecphoryWeightsAndThreshold(_embed) {
+    const pol = DEFAULT_RECALL_POLICY;
+    const oldCue = [{ at: "2020-01-01T00:00:00+00:00", cue: "old", actor: "kit" }];
+    const eArea = { name: "rem-area", spec: {
+            area: "kernel cache mutation", summary: "",
+            created_at: CREATED_AT, cues_history: oldCue,
+        } };
+    const eSem = { name: "rem-sem", spec: {
+            area: "Feature/elsewhere", summary: "totally unrelated words entirely",
+            created_at: CREATED_AT, cues_history: oldCue,
+        } };
+    const eBelow = { name: "rem-below", spec: {
+            area: "Feature/nowhere", summary: "different disjoint vocabulary again",
+            created_at: CREATED_AT, cues_history: oldCue,
+        } };
+    const sem = { "rem-sem": 0.8, "rem-below": 0.4 };
+    const ranked = ecphoryRank([eArea, eSem, eBelow], "kernel cache mutation", sem, pol, KIT_NOW);
+    const byName = new Map(ranked.map((s) => [s.engram.name, s]));
+    assert(byName.size === 2 && byName.has("rem-area") && byName.has("rem-sem"), `0.61×0.4 < directThreshold must gate rem-below out, got ${[...byName.keys()].sort().join(",")}`);
+    const area = byName.get("rem-area");
+    assert(Math.abs(area.score - pol.contentWeight) < 1e-9, `exact area match must score contentWeight, got ${area.score}`);
+    assert(area.matchedDims[0] === "area", `expected 'area', got ${area.matchedDims[0]}`);
+    const semHit = byName.get("rem-sem");
+    assert(Math.abs(semHit.score - pol.cosineWeight * 0.8) < 1e-9, `Path 3 must blend cosineWeight × cos, got ${semHit.score}`);
+    assert(semHit.matchedDims[0].startsWith("semantic~"), `expected semantic~ label, got ${semHit.matchedDims[0]}`);
+}
+async function ecphoryDeterministicOrdering(_embed) {
+    const oldCue = [{ at: "2020-01-01T00:00:00+00:00", cue: "old", actor: "kit" }];
+    const spec = {
+        area: "kernel cache mutation", summary: "",
+        created_at: CREATED_AT, cues_history: oldCue,
+    };
+    const engrams = [
+        { name: "rem-b", spec: { ...spec } },
+        { name: "rem-a", spec: { ...spec } },
+    ];
+    const first = ecphoryRank(engrams, "kernel cache mutation", undefined, DEFAULT_RECALL_POLICY, KIT_NOW);
+    assert(first.map((s) => s.engram.name).join(",") === "rem-a,rem-b", "equal scores must order by name ascending");
+    const second = ecphoryRank(engrams, "kernel cache mutation", undefined, DEFAULT_RECALL_POLICY, KIT_NOW);
+    assert(JSON.stringify(first.map((s) => [s.engram.name, s.score])) ===
+        JSON.stringify(second.map((s) => [s.engram.name, s.score])), "rerun must be identical");
+}
+async function semanticHookLiftsParaphrase(embed) {
+    const engrams = paraphraseEngrams();
+    const without = ecphoryRank(engrams, PARAPHRASE_QUERY, undefined, DEFAULT_RECALL_POLICY, KIT_NOW);
+    assert(without.length === 0, "the cue-match paths must NOT find a paraphrase on their own");
+    const vecs = await embed([PARAPHRASE_QUERY, ...engrams.map((e) => engramText(e.spec))]);
+    const sem = semanticScoresFromVectors(engrams.map((e) => e.name), vecs.slice(1), vecs[0]);
+    const ranked = ecphoryRank(engrams, PARAPHRASE_QUERY, sem, DEFAULT_RECALL_POLICY, KIT_NOW);
+    const names = ranked.map((s) => s.engram.name);
+    assert(names.includes("rem-target"), `the embedder's paraphrase similarity must lift the target over the ` +
+        `ecphory threshold (cos×${DEFAULT_RECALL_POLICY.cosineWeight} + novelty ≥ ` +
+        `${DEFAULT_RECALL_POLICY.directThreshold}); got [${names.join(",")}] ` +
+        `from cosines ${JSON.stringify(sem)}`);
+    if (names.includes("rem-decoy")) {
+        assert(names.indexOf("rem-target") < names.indexOf("rem-decoy"), `the paraphrase target must outrank the decoy: ${names.join(",")}`);
+    }
+}
+async function fusionPreservesAndAnnotates(_embed) {
+    const engrams = paraphraseEngrams();
+    const hits = [
+        { kind: "LessonLearned", name: "rem-decoy", score: 0.048 },
+        { kind: "LessonLearned", name: "rem-target", score: 0.033 },
+    ];
+    const sem = { "rem-target": 0.9 };
+    const fused = fuseSemanticRecall(hits, engrams, PARAPHRASE_QUERY, sem, DEFAULT_RECALL_POLICY, KIT_NOW);
+    assert(fused.map((h) => h.name).join(",") === "rem-target,rem-decoy", `fusion must promote the semantic match, got ${fused.map((h) => h.name).join(",")}`);
+    const [target, decoy] = fused;
+    // RRF (k=60): target = 1/(60+2) [recall #2] + 1/(60+1) [ecphory #1].
+    assert(Math.abs(target.score - (1 / 62 + 1 / 61)) < 1e-12, `fused score must be the reciprocal-rank sum, got ${target.score}`);
+    assert(target.rank_recall === 2 && target.rank_ecphory === 1, `expected ranks (2, 1), got (${target.rank_recall}, ${target.rank_ecphory})`);
+    assert(Math.abs(target.score_recall - 0.033) < 1e-12, "score_recall must preserve the pre-fusion score");
+    assert(Math.abs(target.semantic - 0.9) < 1e-12, "the cue↔memory cosine must be annotated");
+    // The decoy is under the ecphory gate: recall rank only, never dropped.
+    assert(Math.abs(decoy.score - 1 / 61) < 1e-12, `one-list RRF must keep the below-threshold hit, got ${decoy.score}`);
+    assert(decoy.rank_recall === 1 && !("rank_ecphory" in decoy), "the below-threshold hit rides its recall rank only");
+    assert(fuseSemanticRecall([], engrams, PARAPHRASE_QUERY, sem, DEFAULT_RECALL_POLICY, KIT_NOW).length === 0, "empty hits fuse to empty");
+}
+async function decayRetentionMonotonic(_embed) {
+    assert(ebbinghausRetention(10.0, null) === 1.0, "never recalled → R = 1");
+    assert(ebbinghausRetention(10.0, 0.0) === 1.0, "just recalled → R = 1");
+    const [r1, r5, r50] = [1.0, 5.0, 50.0].map((d) => ebbinghausRetention(10.0, d));
+    assert(1.0 > r1 && r1 > r5 && r5 > r50 && r50 > 0.0, `retention must decay monotonically: ${[r1, r5, r50].join(", ")}`);
+    const cap = DEFAULT_DECAY_POLICY.maxStabilityDays;
+    assert(recallBump(cap - 1.0, 0.001) <= cap, "the spacing bump must respect the cap");
+    assert(recallBump(10.0, 1.0) > 10.0, "a recall must strengthen the engram");
+}
+async function bitemporalFailOpen(_embed) {
+    assert(currentlyValid(null, KIT_NOW) === true, "unset valid_to → valid");
+    assert(currentlyValid("", KIT_NOW) === true, "empty valid_to → valid");
+    assert(currentlyValid("2026-07-09T00:00:00+00:00", KIT_NOW) === false, "past valid_to → invalid");
+    assert(currentlyValid("2026-07-11T00:00:00+00:00", KIT_NOW) === true, "future valid_to → valid");
+    assert(currentlyValid("not-a-timestamp", KIT_NOW) === true, "unparseable valid_to must NEVER hide a memory (fail-open)");
+}
+const CASES = [
+    { name: "cosine_tracks_similarity", requires: "embedder", fn: cosineTracksSimilarity },
+    { name: "ecphory_weights_and_threshold", requires: "pure", fn: ecphoryWeightsAndThreshold },
+    { name: "ecphory_deterministic_ordering", requires: "pure", fn: ecphoryDeterministicOrdering },
+    { name: "semantic_hook_lifts_paraphrase", requires: "embedder", fn: semanticHookLiftsParaphrase },
+    { name: "fusion_preserves_and_annotates", requires: "pure", fn: fusionPreservesAndAnnotates },
+    { name: "decay_retention_monotonic", requires: "pure", fn: decayRetentionMonotonic },
+    { name: "bitemporal_fail_open", requires: "pure", fn: bitemporalFailOpen },
+];
+/**
+ * THE public conformance suite for the pure memory-scoring core.
+ *
+ * @param factory optional async factory returning `{ embedder, cleanup }`;
+ *   omit to run against the deterministic fake floor (fully offline).
+ * @returns one runnable case per invariant — feed them to your test runner
+ *   and `await case.run()`.
+ */
+export function memoryScoringConformanceSuite(factory) {
+    return CASES.map(({ name, requires, fn }) => ({
+        name,
+        requires,
+        async run() {
+            if (!factory) {
+                await fn(defaultEmbed);
+                return;
+            }
+            const { embedder, cleanup } = await factory();
+            try {
+                await fn((texts) => embedder.embed(texts));
+            }
+            finally {
+                if (cleanup)
+                    await cleanup();
+            }
+        },
+    }));
+}
+export { SkipCase as MemoryCaseNotApplicable };

package/package.json

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