dna-sdk 0.1.0

package/dist/memory/encodingContext.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Deterministic encoding_context stamping — the engraphy conditions snapshot
+ * (TS twin of `dna/memory/encoding_context.py`). Encoding-specificity (Semon
+ * 1904): conditions at engraphy must be partially reinstated at ecphory.
+ *
+ * s-memory-verbs (2026-07-09).
+ */
+type Spec = Record<string, unknown>;
+/** Map an hour to {morning, afternoon, evening, night}. */
+export declare function timeOfDay(hour: number): string;
+/** Build a deterministic encoding_context from the spec. Fresh object. */
+export declare function deriveEncodingContext(spec: Spec, opts?: {
+    ambient?: Record<string, unknown>;
+    derivedMarker?: string;
+}): Record<string, unknown>;
+/** Mutate `spec` in place: add encoding_context if missing/empty. Idempotent. */
+export declare function stampEncodingContextIfAbsent(spec: Spec, opts?: {
+    ambient?: Record<string, unknown>;
+    derivedMarker?: string;
+}): Spec;
+export {};

package/dist/memory/encodingContext.js

@@ -0,0 +1,62 @@
+/**
+ * Deterministic encoding_context stamping — the engraphy conditions snapshot
+ * (TS twin of `dna/memory/encoding_context.py`). Encoding-specificity (Semon
+ * 1904): conditions at engraphy must be partially reinstated at ecphory.
+ *
+ * s-memory-verbs (2026-07-09).
+ */
+/** Map an hour to {morning, afternoon, evening, night}. */
+export function timeOfDay(hour) {
+    if (hour >= 5 && hour < 12)
+        return "morning";
+    if (hour >= 12 && hour < 18)
+        return "afternoon";
+    if (hour >= 18 && hour < 22)
+        return "evening";
+    return "night";
+}
+function hourOfIso(value) {
+    if (typeof value !== "string" || !value)
+        return null;
+    const ms = Date.parse(value.replace("Z", "+00:00"));
+    if (Number.isNaN(ms))
+        return null;
+    return new Date(ms).getUTCHours();
+}
+/** Build a deterministic encoding_context from the spec. Fresh object. */
+export function deriveEncodingContext(spec, opts = {}) {
+    const ambient = opts.ambient ?? {};
+    const derivedMarker = opts.derivedMarker ?? "verb-autostamp";
+    const hour = hourOfIso(spec.created_at) ?? new Date().getUTCHours();
+    const tod = ambient.time_of_day || timeOfDay(hour);
+    const specTags = (spec.tags ?? [])
+        .filter((t) => typeof t === "string" || typeof t === "number")
+        .map((t) => String(t));
+    const ambientTopics = (ambient.recent_turn_topics ?? [])
+        .filter((t) => typeof t === "string" || typeof t === "number")
+        .map((t) => String(t));
+    const seen = [];
+    for (const t of [...specTags, ...ambientTopics]) {
+        if (t && !seen.includes(t))
+            seen.push(t);
+        if (seen.length >= 5)
+            break;
+    }
+    return {
+        area: spec.area ?? "",
+        affect: ambient.affect ?? spec.affect ?? "neutral",
+        time_of_day: tod,
+        co_topics: seen,
+        source_refs: [...(spec.source_refs ?? [])],
+        _derived: derivedMarker,
+    };
+}
+/** Mutate `spec` in place: add encoding_context if missing/empty. Idempotent. */
+export function stampEncodingContextIfAbsent(spec, opts = {}) {
+    const existing = spec.encoding_context;
+    if (existing && typeof existing === "object" && Object.keys(existing).length > 0) {
+        return spec;
+    }
+    spec.encoding_context = deriveEncodingContext(spec, opts);
+    return spec;
+}

package/dist/memory/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `dna/memory` — the deterministic memory-scoring core (TS twin).
+ *
+ * Memory in DNA is the Kinds the SDK already has (LessonLearned, Research,
+ * Evidence) recalled by the same RecordSearchProvider that powers search. This
+ * package holds the DETERMINISTIC pure scoring core ported from the upstream
+ * cognitive layer — ecphory (Semon's Law of Ecphory), BM25 retrieval,
+ * Ebbinghaus decay, encoding-context stamping, CoALA classification, and the
+ * recall/decay policy defaults. Parity with the Python twin
+ * (`dna/memory/*.py`) is pinned by `tests/fixtures/memory-scoring-parity.json`.
+ *
+ * The four VERBS (remember/recall/forget/consolidate) are kernel-bound and live
+ * on the Python side (the `dna` CLI); this twin ports the pure math the verbs
+ * compose, keeping Py↔TS parity of the scoring surface.
+ *
+ * s-memory-verbs (2026-07-09).
+ */
+export * from "./policy.js";
+export * from "./decay.js";
+export * from "./memoryType.js";
+export * from "./encodingContext.js";
+export * from "./retrieval.js";
+export * from "./ecphory.js";

package/dist/memory/index.js

@@ -0,0 +1,23 @@
+/**
+ * `dna/memory` — the deterministic memory-scoring core (TS twin).
+ *
+ * Memory in DNA is the Kinds the SDK already has (LessonLearned, Research,
+ * Evidence) recalled by the same RecordSearchProvider that powers search. This
+ * package holds the DETERMINISTIC pure scoring core ported from the upstream
+ * cognitive layer — ecphory (Semon's Law of Ecphory), BM25 retrieval,
+ * Ebbinghaus decay, encoding-context stamping, CoALA classification, and the
+ * recall/decay policy defaults. Parity with the Python twin
+ * (`dna/memory/*.py`) is pinned by `tests/fixtures/memory-scoring-parity.json`.
+ *
+ * The four VERBS (remember/recall/forget/consolidate) are kernel-bound and live
+ * on the Python side (the `dna` CLI); this twin ports the pure math the verbs
+ * compose, keeping Py↔TS parity of the scoring surface.
+ *
+ * s-memory-verbs (2026-07-09).
+ */
+export * from "./policy.js";
+export * from "./decay.js";
+export * from "./memoryType.js";
+export * from "./encodingContext.js";
+export * from "./retrieval.js";
+export * from "./ecphory.js";

package/dist/memory/memoryType.d.ts

@@ -0,0 +1,7 @@
+/**
+ * CoALA memory_type inference — heuristic, pure, conservative (TS twin of
+ * `dna/memory/memory_type.py`). Never overwrites an explicit `memory_type`.
+ *
+ * s-memory-verbs (2026-07-09).
+ */
+export declare function classifyMemoryType(spec: Record<string, unknown>): string;

package/dist/memory/memoryType.js

@@ -0,0 +1,24 @@
+/**
+ * CoALA memory_type inference — heuristic, pure, conservative (TS twin of
+ * `dna/memory/memory_type.py`). Never overwrites an explicit `memory_type`.
+ *
+ * s-memory-verbs (2026-07-09).
+ */
+const RULE_WORDS = [
+    "always", "never", "must", "should", "don't", "do not", "ensure",
+    "sempre", "nunca", "deve", "não ", "garanta", "evite", "prefira",
+];
+const EPISODIC_AREAS = ["feature/", "epic/", "story/", "issue/", "roadmap/"];
+export function classifyMemoryType(spec) {
+    const existing = spec.memory_type;
+    if (existing === "episodic" || existing === "semantic" || existing === "procedural") {
+        return existing;
+    }
+    const text = `${spec.summary ?? ""} ${spec.body ?? ""}`.toLowerCase();
+    if (RULE_WORDS.some((w) => text.includes(w)))
+        return "procedural";
+    const area = String(spec.area ?? "").toLowerCase();
+    if (EPISODIC_AREAS.some((p) => area.startsWith(p)))
+        return "episodic";
+    return "semantic";
+}

package/dist/memory/policy.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Recall/decay tuning knobs — pure declarative defaults (TS twin of
+ * `dna/memory/policy.py`). The kernel-reading resolvers are deliberately left
+ * behind (service concern); these defaults ARE the calibrated values and the
+ * pure scoring functions fall back to them.
+ *
+ * s-memory-verbs (2026-07-09). Parity-critical numeric constants.
+ */
+export interface RecallPolicy {
+    directThreshold: number;
+    cosineWeight: number;
+    contentWeight: number;
+    summaryPartialWeight: number;
+    coTopicsWeight: number;
+    sourceRefsWeight: number;
+    affectWeight: number;
+    timeWeight: number;
+    noveltyBoost: number;
+    recencyBoost: number;
+    saturationDecay: number;
+    saturationThreshold: number;
+    limitDirect: number;
+    limitHomophonic: number;
+}
+export declare const DEFAULT_RECALL_POLICY: RecallPolicy;
+export interface DecayPolicy {
+    tierFaint: number;
+    tierFirm: number;
+    tierBurning: number;
+    defaultStabilityDays: number;
+    maxStabilityDays: number;
+    relevanceDecaySeed: number;
+}
+export declare const DEFAULT_DECAY_POLICY: DecayPolicy;
+export declare function decayTiers(policy?: DecayPolicy): Record<string, number>;

package/dist/memory/policy.js

@@ -0,0 +1,35 @@
+/**
+ * Recall/decay tuning knobs — pure declarative defaults (TS twin of
+ * `dna/memory/policy.py`). The kernel-reading resolvers are deliberately left
+ * behind (service concern); these defaults ARE the calibrated values and the
+ * pure scoring functions fall back to them.
+ *
+ * s-memory-verbs (2026-07-09). Parity-critical numeric constants.
+ */
+export const DEFAULT_RECALL_POLICY = {
+    directThreshold: 0.3,
+    cosineWeight: 0.61,
+    contentWeight: 0.55,
+    summaryPartialWeight: 0.28,
+    coTopicsWeight: 0.2,
+    sourceRefsWeight: 0.15,
+    affectWeight: 0.05,
+    timeWeight: 0.05,
+    noveltyBoost: 0.05,
+    recencyBoost: 0.1,
+    saturationDecay: 0.6,
+    saturationThreshold: 3,
+    limitDirect: 8,
+    limitHomophonic: 6,
+};
+export const DEFAULT_DECAY_POLICY = {
+    tierFaint: 5.0,
+    tierFirm: 15.0,
+    tierBurning: 45.0,
+    defaultStabilityDays: 15.0,
+    maxStabilityDays: 60.0,
+    relevanceDecaySeed: 0.95,
+};
+export function decayTiers(policy = DEFAULT_DECAY_POLICY) {
+    return { faint: policy.tierFaint, firm: policy.tierFirm, burning: policy.tierBurning };
+}

package/dist/memory/retrieval.d.ts

@@ -0,0 +1,21 @@
+export interface Memory {
+    name: string;
+    spec: Record<string, unknown>;
+}
+export interface RankedMemory {
+    name: string;
+    score: number;
+    factors: Record<string, number | boolean>;
+}
+export declare function tokenize(text: string): string[];
+export declare function bm25Score(queryTokens: string[], docTokens: string[], docLengths: number[], idf: Map<string, number>): number;
+export declare function buildIdf(corpusTokens: string[][]): Map<string, number>;
+export declare function recencyFactor(lastSurfaced: unknown, now: number): number;
+export declare function affectFactor(affect: unknown): number;
+export declare function surfaceDamp(count: unknown): number;
+/** Rank memories by `bm25 × recency × affect × surface_damp × confidence`. Pure. */
+export declare function rankMemories(memories: Memory[], query: string, opts?: {
+    now?: number;
+    limit?: number;
+    partial?: boolean;
+}): RankedMemory[];

package/dist/memory/retrieval.js

@@ -0,0 +1,145 @@
+/**
+ * BM25 memory ranking — the pure lexical scoring core (TS twin of
+ * `dna/memory/retrieval.py`). Bit-identical arithmetic to Python:
+ *
+ *   final = base_bm25 × recency_decay × affect_weight × surface_damp × confidence
+ *
+ * s-memory-verbs (2026-07-09).
+ */
+import { confidenceScoreNumeric } from "./decay.js";
+const AFFECT_WEIGHTS = {
+    triumph: 1.2,
+    regret: 1.3,
+    surprise: 1.5,
+    wistful: 1.0,
+    ominous: 1.4,
+};
+const BM25_K1 = 1.5;
+const BM25_B = 0.75;
+const RECENCY_HALFLIFE_DAYS = 30.0;
+const SURFACE_DAMP_K = 0.1;
+const PARTIAL_PREFIX_FLOOR = 0.05;
+const PARTIAL_MIN_PREFIX_LEN = 3;
+export function tokenize(text) {
+    return text.toLowerCase().match(/[a-z0-9]+/g) ?? [];
+}
+function docText(spec) {
+    return `${spec.area ?? ""} ${spec.summary ?? ""}`;
+}
+export function bm25Score(queryTokens, docTokens, docLengths, idf) {
+    if (docTokens.length === 0)
+        return 0.0;
+    const avgDl = docLengths.length ? docLengths.reduce((a, b) => a + b, 0) / docLengths.length : 0.0;
+    if (avgDl === 0.0)
+        return 0.0;
+    const dl = docTokens.length;
+    const tf = new Map();
+    for (const t of docTokens)
+        tf.set(t, (tf.get(t) ?? 0) + 1);
+    let score = 0.0;
+    for (const term of queryTokens) {
+        const termIdf = idf.get(term);
+        if (termIdf === undefined)
+            continue;
+        const f = tf.get(term) ?? 0;
+        if (f === 0)
+            continue;
+        const num = f * (BM25_K1 + 1);
+        const den = f + BM25_K1 * (1 - BM25_B + (BM25_B * dl) / avgDl);
+        score += termIdf * (num / den);
+    }
+    return score;
+}
+export function buildIdf(corpusTokens) {
+    const n = corpusTokens.length;
+    const df = new Map();
+    for (const tokens of corpusTokens) {
+        for (const term of new Set(tokens))
+            df.set(term, (df.get(term) ?? 0) + 1);
+    }
+    const idf = new Map();
+    for (const [term, count] of df) {
+        idf.set(term, Math.log((n - count + 0.5) / (count + 0.5) + 1));
+    }
+    return idf;
+}
+export function recencyFactor(lastSurfaced, now) {
+    if (!lastSurfaced || typeof lastSurfaced !== "string")
+        return 1.0;
+    const ms = Date.parse(lastSurfaced.replace("Z", "+00:00"));
+    if (Number.isNaN(ms))
+        return 1.0;
+    const deltaDays = (now - ms) / 86_400_000;
+    if (deltaDays <= 0)
+        return 1.0;
+    return Math.exp(-deltaDays / RECENCY_HALFLIFE_DAYS);
+}
+export function affectFactor(affect) {
+    return AFFECT_WEIGHTS[String(affect ?? "")] ?? 1.0;
+}
+export function surfaceDamp(count) {
+    const n = typeof count === "number" ? count : 0;
+    return 1.0 / (1.0 + n * SURFACE_DAMP_K);
+}
+function hasPrefixOverlap(queryTokens, docTokens) {
+    const q = queryTokens.filter((t) => t.length >= PARTIAL_MIN_PREFIX_LEN);
+    const d = docTokens.filter((t) => t.length >= PARTIAL_MIN_PREFIX_LEN);
+    for (const qt of q) {
+        for (const dt of d) {
+            if (qt === dt)
+                continue;
+            const n = Math.min(qt.length, dt.length);
+            let i = 0;
+            while (i < n && qt[i] === dt[i])
+                i += 1;
+            if (i >= PARTIAL_MIN_PREFIX_LEN)
+                return true;
+        }
+    }
+    return false;
+}
+/** Rank memories by `bm25 × recency × affect × surface_damp × confidence`. Pure. */
+export function rankMemories(memories, query, opts = {}) {
+    const { now = Date.now(), limit = 5, partial = false } = opts;
+    const queryTokens = tokenize(query);
+    const corpusTokens = memories.map((m) => tokenize(docText(m.spec)));
+    const ranked = [];
+    if (queryTokens.length && memories.length) {
+        const docLengths = corpusTokens.map((t) => t.length);
+        const idf = buildIdf(corpusTokens);
+        memories.forEach((mem, i) => {
+            const tokens = corpusTokens[i];
+            let base = bm25Score(queryTokens, tokens, docLengths, idf);
+            let partialMatch = false;
+            if (base <= 0.0) {
+                if (!partial || !hasPrefixOverlap(queryTokens, tokens))
+                    return;
+                base = PARTIAL_PREFIX_FLOOR;
+                partialMatch = true;
+            }
+            const spec = mem.spec ?? {};
+            const rec = recencyFactor(spec.last_surfaced, now);
+            const aff = affectFactor(spec.affect);
+            const damp = surfaceDamp(spec.surface_count);
+            const conf = confidenceScoreNumeric(spec);
+            ranked.push({
+                name: mem.name,
+                score: base * rec * aff * damp * conf,
+                factors: {
+                    base,
+                    recency: rec,
+                    affect: aff,
+                    surface_damp: damp,
+                    confidence_score: conf,
+                    partial_match: partialMatch,
+                },
+            });
+        });
+    }
+    ranked.sort((a, b) => {
+        if (b.score !== a.score)
+            return b.score - a.score;
+        return a.name < b.name ? -1 : a.name > b.name ? 1 : 0;
+    });
+    return ranked.slice(0, limit);
+}

package/dist/testing/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Public testing kit for TS SDK port adapters (twin of Python `dna.testing`).
+ *
+ * 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.
+ */
+export { FIXTURE_SCOPE, fixtureRecords, recordSearchConformanceSuite, SearchCaseNotApplicable, type ConformanceProvider, type ProviderFactory, type RecordSearchCase, } from "./recordSearchConformance.js";

package/dist/testing/index.js

@@ -0,0 +1,8 @@
+/**
+ * Public testing kit for TS SDK port adapters (twin of Python `dna.testing`).
+ *
+ * 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.
+ */
+export { FIXTURE_SCOPE, fixtureRecords, recordSearchConformanceSuite, SearchCaseNotApplicable, } from "./recordSearchConformance.js";

package/dist/testing/recordSearchConformance.d.ts

@@ -0,0 +1,43 @@
+/**
+ * RecordSearchProvider conformance kit (TS twin of
+ * `dna/testing/record_search_conformance.py`).
+ *
+ * The behavioral contract every `RecordSearchProvider` implementation must
+ * satisfy — the search-plane conformance kit. The sqlite-vec provider runs it
+ * today; a future adapter runs the SAME kit. Cases assert only on PUBLIC
+ * behavior (relative ranking, filtering, overlay shadowing, k-limit,
+ * idempotence) under the deterministic fake embedder, so they hold for a real
+ * embedder too and run fully offline.
+ *
+ * A `factory` is an async zero-arg callable returning `{ provider, cleanup }`.
+ * The provider must expose async `index` / `search` / `delete`. Each case runs
+ * against a FRESH provider (isolation), then always awaits cleanup.
+ */
+export declare const FIXTURE_SCOPE = "search-conformance-kit";
+/** A record-search provider, structurally. */
+export interface ConformanceProvider {
+    index(records: Array<Record<string, unknown>>): Promise<number>;
+    search(opts: {
+        scope: string;
+        queryText: string;
+        kind?: string | null;
+        k?: number;
+        tenant?: string;
+    }): Promise<Array<Record<string, unknown>>>;
+    delete?(ids: Array<Record<string, unknown>>): Promise<number>;
+    close?(): void | Promise<void>;
+}
+export type ProviderFactory = () => Promise<{
+    provider: ConformanceProvider;
+    cleanup?: () => void | Promise<void>;
+}>;
+export declare function fixtureRecords(): Array<Record<string, unknown>>;
+declare class SkipCase extends Error {
+}
+export interface RecordSearchCase {
+    name: string;
+    requires: string;
+    run(): Promise<void>;
+}
+export declare function recordSearchConformanceSuite(factory: ProviderFactory): RecordSearchCase[];
+export { SkipCase as SearchCaseNotApplicable };

package/dist/testing/recordSearchConformance.js

@@ -0,0 +1,147 @@
+/**
+ * RecordSearchProvider conformance kit (TS twin of
+ * `dna/testing/record_search_conformance.py`).
+ *
+ * The behavioral contract every `RecordSearchProvider` implementation must
+ * satisfy — the search-plane conformance kit. The sqlite-vec provider runs it
+ * today; a future adapter runs the SAME kit. Cases assert only on PUBLIC
+ * behavior (relative ranking, filtering, overlay shadowing, k-limit,
+ * idempotence) under the deterministic fake embedder, so they hold for a real
+ * embedder too and run fully offline.
+ *
+ * A `factory` is an async zero-arg callable returning `{ provider, cleanup }`.
+ * The provider must expose async `index` / `search` / `delete`. Each case runs
+ * against a FRESH provider (isolation), then always awaits cleanup.
+ */
+export const FIXTURE_SCOPE = "search-conformance-kit";
+export function fixtureRecords() {
+    return [
+        { scope: FIXTURE_SCOPE, kind: "Story", name: "s-memory", title: "Memory recall",
+            text: "memory similarity vector embedding recall cognitive ecphory" },
+        { scope: FIXTURE_SCOPE, kind: "Story", name: "s-banana", title: "Banana smoothie",
+            text: "banana tropical yellow fruit smoothie breakfast" },
+        { scope: FIXTURE_SCOPE, kind: "Story", name: "s-fusion", title: "Hybrid fusion",
+            text: "hybrid search fusion reciprocal rank bm25 dense lexical" },
+        { scope: FIXTURE_SCOPE, kind: "Genome", name: "g-root", title: "Root genome",
+            text: "root genome package catalog identity" },
+    ];
+}
+class SkipCase extends Error {
+}
+async function indexFixture(p) {
+    await p.index(fixtureRecords().map((r) => ({ ...r })));
+}
+function names(hits) {
+    return hits.map((h) => h.name);
+}
+function assert(cond, msg) {
+    if (!cond)
+        throw new Error(msg);
+}
+// ---------------------------------------------------------------------------
+// cases
+// ---------------------------------------------------------------------------
+async function indexSearchRoundTrip(p) {
+    await indexFixture(p);
+    const hits = await p.search({ scope: FIXTURE_SCOPE, queryText: "memory recall cognitive", k: 10 });
+    assert(hits.length > 0, "search returned nothing after indexing");
+    assert(hits[0].name === "s-memory", `expected s-memory first, got ${names(hits).join(",")}`);
+    for (const h of hits) {
+        assert(["scope", "kind", "name", "score"].every((key) => key in h), `hit missing guaranteed keys: ${JSON.stringify(h)}`);
+        assert(h.scope === FIXTURE_SCOPE, "wrong scope on hit");
+    }
+}
+async function rrfOrdersByRelevance(p) {
+    await indexFixture(p);
+    const hits = await p.search({ scope: FIXTURE_SCOPE, queryText: "banana fruit smoothie", k: 10 });
+    assert(hits.length > 0 && hits[0].name === "s-banana", `RRF must rank s-banana first, got ${names(hits).join(",")}`);
+    const rank = new Map(names(hits).map((n, i) => [n, i]));
+    if (rank.has("s-memory")) {
+        assert(rank.get("s-banana") < rank.get("s-memory"), "relevant doc must outrank an unrelated one");
+    }
+}
+async function kindFilter(p) {
+    await indexFixture(p);
+    const hits = await p.search({ scope: FIXTURE_SCOPE, queryText: "root genome catalog", kind: "Genome", k: 10 });
+    assert(hits.length > 0, "kind-filtered search found nothing");
+    assert(hits.every((h) => h.kind === "Genome"), `kind filter leaked other kinds: ${JSON.stringify(hits.map((h) => [h.kind, h.name]))}`);
+    assert(names(hits).includes("g-root"), "expected g-root");
+}
+async function kLimit(p) {
+    await indexFixture(p);
+    const hits = await p.search({ scope: FIXTURE_SCOPE, queryText: "memory banana fusion genome", k: 2 });
+    assert(hits.length <= 2, `k=2 must cap results, got ${hits.length}`);
+}
+async function emptyQuery(p) {
+    await indexFixture(p);
+    for (const q of ["", "   "]) {
+        const hits = await p.search({ scope: FIXTURE_SCOPE, queryText: q, k: 10 });
+        assert(hits.length === 0, `empty query must return no hits, got ${names(hits).join(",")}`);
+    }
+}
+async function idempotentIndex(p) {
+    await indexFixture(p);
+    await indexFixture(p);
+    const hits = await p.search({ scope: FIXTURE_SCOPE, queryText: "memory recall", k: 10 });
+    const memory = hits.filter((h) => h.name === "s-memory");
+    assert(memory.length === 1, `re-index duplicated the doc: ${memory.length} copies of s-memory`);
+}
+async function deleteRemoves(p) {
+    if (typeof p.delete !== "function")
+        throw new SkipCase("no delete()");
+    await indexFixture(p);
+    await p.delete([{ scope: FIXTURE_SCOPE, kind: "Story", name: "s-banana" }]);
+    const hits = await p.search({ scope: FIXTURE_SCOPE, queryText: "banana fruit smoothie", k: 10 });
+    assert(!names(hits).includes("s-banana"), `deleted doc still returned: ${names(hits).join(",")}`);
+}
+async function tenantOverlayShadowsBase(p) {
+    await indexFixture(p);
+    await p.index([{
+            scope: FIXTURE_SCOPE, kind: "Story", name: "s-memory", tenant: "acme",
+            title: "Memory recall (acme)",
+            text: "memory similarity recall acme overlay variant tenant-specific",
+        }]);
+    const base = await p.search({ scope: FIXTURE_SCOPE, queryText: "memory recall", kind: "Story", k: 10, tenant: "" });
+    const over = await p.search({ scope: FIXTURE_SCOPE, queryText: "memory recall", kind: "Story", k: 10, tenant: "acme" });
+    assert(names(base).includes("s-memory"), "base s-memory missing");
+    const baseHit = base.find((h) => h.name === "s-memory");
+    assert(!String(baseHit.title ?? "").toLowerCase().includes("acme"), "tenant overlay leaked into a base-tenant search");
+    const overMemory = over.filter((h) => h.name === "s-memory");
+    assert(overMemory.length === 1, `overlay must shadow base (one s-memory), got ${overMemory.length}`);
+    assert(String(overMemory[0].title ?? "").toLowerCase().includes("acme"), "tenant search must return the overlay variant, not the base");
+}
+const CASES = [
+    { name: "index_search_round_trip", requires: "always", fn: indexSearchRoundTrip },
+    { name: "rrf_orders_by_relevance", requires: "always", fn: rrfOrdersByRelevance },
+    { name: "kind_filter", requires: "always", fn: kindFilter },
+    { name: "k_limit", requires: "always", fn: kLimit },
+    { name: "empty_query_returns_empty", requires: "always", fn: emptyQuery },
+    { name: "idempotent_index", requires: "always", fn: idempotentIndex },
+    { name: "delete_removes", requires: "delete()", fn: deleteRemoves },
+    { name: "tenant_overlay_shadows_base", requires: "index() tenant", fn: tenantOverlayShadowsBase },
+];
+export function recordSearchConformanceSuite(factory) {
+    return CASES.map(({ name, requires, fn }) => ({
+        name,
+        requires,
+        async run() {
+            const { provider, cleanup } = await factory();
+            try {
+                await fn(provider);
+            }
+            finally {
+                if (cleanup)
+                    await cleanup();
+                if (typeof provider.close === "function") {
+                    try {
+                        await provider.close();
+                    }
+                    catch {
+                        /* ignore */
+                    }
+                }
+            }
+        },
+    }));
+}
+export { SkipCase as SearchCaseNotApplicable };

package/dist/viz/ascii.d.ts

@@ -0,0 +1,7 @@
+/**
+ * ASCII tree rendering — standalone function operating on ManifestInstance.
+ *
+ * Extracted from ManifestInstance to keep the kernel class focused.
+ */
+import type { ManifestInstance } from "../kernel/instance.js";
+export declare function asciiTree(mi: ManifestInstance): string;