dna-sdk 0.1.0

package/dist/kernel/write-pipeline.js

@@ -0,0 +1,271 @@
+import { deriveEventType } from "./events.js";
+import { createAjv } from "./kind_base.js";
+import { SpecValidationError, TenantScope, TenantRequired, TenantNotAllowed, validateTenantSlug, } from "./protocols.js";
+/** Compiled-validator cache for the generic write-path schema check
+ *  (s-write-path-validation, i-008) — keyed by KindPort identity so each
+ *  port's schema compiles once per process, not once per write. `null`
+ *  marks a schema-less (permissive) port. */
+const _writeValidators = new WeakMap();
+export class WritePipeline {
+    _k;
+    constructor(kernel) {
+        this._k = kernel;
+    }
+    /** Read the write-validation mode knob. `enforce` (default) vetoes an
+     *  invalid write; `warn` logs and persists; `off` skips the step. Read
+     *  per-write (not memoized) so tests / operators can flip it live. */
+    static _validationMode() {
+        const mode = (process.env.DNA_WRITE_VALIDATION ?? "enforce").trim().toLowerCase();
+        return mode === "warn" || mode === "off" ? mode : "enforce";
+    }
+    /**
+     * Validate `raw.spec` against the Kind's declared JSON Schema at WRITE
+     * time (s-write-path-validation, i-008 — the systemic gap found on the
+     * Automation work: the kernel only schema-validated at scan/read via the
+     * fail-soft `parse_error` channel, so a shape-broken doc persisted and
+     * exploded later, far from the author). Twin of Python
+     * `WritePipeline._validate_spec_schema`.
+     *
+     * Contract:
+     * - Kinds without a schema (`schema()` null/empty, or throwing) stay
+     *   PERMISSIVE — validation is opt-in by data, as always.
+     * - `spec_defaults` (descriptor D5) are shallow-merged into the spec
+     *   BEFORE validating, mirroring `DeclarativeKindPort.parse`.
+     * - Runs AFTER the `pre_save` veto hooks (Kind-owned cures mutate
+     *   ctx.raw first), BEFORE persistence.
+     * - Didactic failure (install #26 pattern): names the field, the
+     *   violation, and points at `dna kind show <Kind>`.
+     */
+    _validateSpecSchema(scope, kind, name, raw, port) {
+        const mode = WritePipeline._validationMode();
+        if (mode === "off" || port === null || typeof raw !== "object" || raw === null) {
+            return;
+        }
+        let validate = _writeValidators.get(port);
+        if (validate === undefined) {
+            let schema = null;
+            try {
+                schema = port.schema?.() ?? null;
+            }
+            catch {
+                schema = null; // a Kind whose schema errors stays permissive
+            }
+            validate =
+                schema !== null && typeof schema === "object" && Object.keys(schema).length > 0
+                    ? createAjv().compile(schema)
+                    : null;
+            _writeValidators.set(port, validate);
+        }
+        if (validate === null)
+            return;
+        const rawSpec = raw.spec;
+        let spec = rawSpec !== null && typeof rawSpec === "object" && !Array.isArray(rawSpec)
+            ? rawSpec
+            : {};
+        // Descriptor D5: defaults fill, spec overrides — exactly what the
+        // validating parse sees.
+        const defaults = port
+            ._specDefaults;
+        if (defaults != null && Object.keys(defaults).length > 0) {
+            spec = { ...defaults, ...spec };
+        }
+        if (validate(spec))
+            return;
+        const first = validate.errors?.[0];
+        const path = (first?.instancePath ?? "").replace(/^\//, "").replace(/\//g, ".");
+        const loc = path ? `spec.${path}` : "spec";
+        const detail = first?.message ?? "spec does not match the Kind's schema";
+        const msg = `write vetoed for ${scope}/${kind}/${name}: schema validation failed ` +
+            `at ${loc}: ${detail} — see \`dna kind show ${kind}\` for the expected shape`;
+        if (mode === "warn") {
+            // eslint-disable-next-line no-console
+            console.warn(`${msg} (DNA_WRITE_VALIDATION=warn — persisted anyway)`);
+            return;
+        }
+        throw new SpecValidationError(msg);
+    }
+    /**
+     * Reconcile tenant + layer args + Kernel.tenant + KindPort.scope.
+     * Returns `[effectiveTenant, residualLayer]`. Back-compat:
+     * `layer=("tenant", X)` is rewritten to `tenant=X` with a deprecation
+     * console.warn. Validation: TENANTED kind requires a tenant; GLOBAL kind
+     * forbids it. Moved verbatim from `Kernel._resolveTenantArg`.
+     */
+    resolveTenantArg(kind, tenant, layer) {
+        const k = this._k;
+        let residualLayer = layer;
+        let explicitTenant = tenant;
+        // Back-compat: layer=("tenant", X) → tenant=X
+        if (layer !== undefined && layer[0] === "tenant") {
+            // eslint-disable-next-line no-console
+            console.warn("[DEPRECATION] layer=('tenant', X) is deprecated — pass tenant=X to writeDocument/deleteDocument instead");
+            if (explicitTenant === null || explicitTenant === undefined) {
+                explicitTenant = layer[1];
+            }
+            residualLayer = undefined;
+        }
+        // Effective tenant: explicit per-call > Kernel.tenant binding
+        const effective = explicitTenant !== null && explicitTenant !== undefined
+            ? explicitTenant
+            : k.tenant;
+        validateTenantSlug(effective);
+        // Validate against KindPort.scope when EXPLICITLY declared.
+        const scopeDecl = k._kindScope(kind);
+        if (scopeDecl === TenantScope.TENANTED && effective === null) {
+            throw new TenantRequired(`Kind ${JSON.stringify(kind)} is TENANTED — pass tenant=<slug> to ` +
+                `writeDocument() or bind one via new Kernel({tenant: ...}) / ` +
+                `kernel.withTenant(...)`);
+        }
+        if (scopeDecl === TenantScope.GLOBAL && effective !== null) {
+            throw new TenantNotAllowed(`Kind ${JSON.stringify(kind)} is GLOBAL — must NOT pass a tenant. ` +
+                `Use the unbound kernel (new Kernel() with no tenant) or ` +
+                `kernel.withTenant(null) for global writes.`);
+        }
+        return [effective, residualLayer];
+    }
+    /** Real writeDocument body — the facade (`Kernel.writeDocument`) is a thin
+     *  delegator. Persists through the writable source with the `pre_save` veto
+     *  gate + `post_save` emission. */
+    async write(scope, kind, name, raw, options) {
+        const k = this._k;
+        const src = k._requireWritableSource();
+        // Resolve tenant + validate against KindPort.scope (back-compat for
+        // layer=("tenant", X) → tenant=X with deprecation warning)
+        const [effectiveTenant, residualLayer] = this.resolveTenantArg(kind, options?.tenant, options?.layer);
+        const policyCheckLayer = effectiveTenant !== null ? ["tenant", effectiveTenant] : residualLayer;
+        if (policyCheckLayer !== undefined) {
+            await k._checkLayerPolicyAsync(scope, kind, name, raw, policyCheckLayer);
+        }
+        // pre_save veto hooks (s-write-path-despecialize) — Kind-specific write
+        // rules (platform-agent fork guard, Kind-Writer contract, ...) live in
+        // the extension that OWNS the Kind and register here via
+        // `kernel.onVeto("pre_save", fn, {priority})`. A throw vetoes the
+        // write; listeners may mutate `ctx.raw` in place. Fires regardless of
+        // `skipHooks` — these are integrity gates, not notifications
+        // (`skipHooks` only silences post_save).
+        if (k.hooks.hasVeto("pre_save")) {
+            await k.hooks.emitVeto("pre_save", {
+                scope, kind, name, raw,
+                tenant: effectiveTenant,
+                ...(policyCheckLayer !== undefined ? { layer: policyCheckLayer } : {}),
+                kernel: k,
+            });
+        }
+        // --- generic spec↔schema validation (s-write-path-validation, i-008) ---
+        // AFTER the veto hooks (Kind-owned cures mutate ctx.raw first), BEFORE
+        // persistence: what gets validated is the exact shape that would be
+        // saved. i-195: resolve the port by the doc's own apiVersion.
+        this._validateSpecSchema(scope, kind, name, raw, k.kindPortFor(kind, raw?.apiVersion));
+        const version = await src.saveDocument(scope, kind, name, raw, {
+            author: options?.author,
+            tenant: effectiveTenant ?? undefined,
+            layer: residualLayer,
+        });
+        // Cache invalidation only for true base writes (no tenant + no overlay)
+        if (effectiveTenant === null && residualLayer === undefined) {
+            // Base instance cache lives in Python; TS kernel doesn't cache here.
+        }
+        if (!options?.skipHooks) {
+            // Hook layer keeps legacy shape for back-compat with subscribers.
+            const hookLayer = policyCheckLayer;
+            await this.emitPostSave(scope, kind, name, raw, options?.author, false, hookLayer);
+        }
+        return version;
+    }
+    /** Real deleteDocument body — the facade is a thin delegator. NOTE: deletes
+     *  have NO pre_save veto gate (only writes do). */
+    async delete(scope, kind, name, options) {
+        const k = this._k;
+        const src = k._requireWritableSource();
+        // Resolve tenant + validate against KindPort.scope.
+        const [effectiveTenant, residualLayer] = this.resolveTenantArg(kind, options?.tenant, options?.layer);
+        const policyCheckLayer = effectiveTenant !== null ? ["tenant", effectiveTenant] : residualLayer;
+        if (policyCheckLayer !== undefined) {
+            await k._checkLayerPolicyAsync(scope, kind, name, null, policyCheckLayer);
+        }
+        await src.deleteDocument(scope, kind, name, {
+            author: options?.author,
+            tenant: effectiveTenant ?? undefined,
+            layer: residualLayer,
+        });
+        if (!options?.skipHooks) {
+            await this.emitPostDelete(scope, kind, name, policyCheckLayer);
+        }
+    }
+    /** Emit the post_save hook (shared by the new and legacy write paths).
+     *  Async so async listeners (event bus publishers etc.) can await I/O. */
+    async emitPostSave(scope, kind, name, raw, author, isUpdate, layer) {
+        const k = this._k;
+        if (!k.hooks.has("post_save"))
+            return;
+        await k.hooks.emitAsync("post_save", {
+            scope,
+            kind,
+            name,
+            data: {
+                event_type: deriveEventType(kind, isUpdate ?? false),
+                author: author ?? "sdk",
+                is_update: isUpdate ?? false,
+                spec: raw,
+            },
+            ...(layer !== undefined ? { layer } : {}),
+        });
+    }
+    /** Emit the post_delete hook (only from the new delegation path). */
+    async emitPostDelete(scope, kind, name, layer) {
+        const k = this._k;
+        if (!k.hooks.has("post_delete"))
+            return;
+        await k.hooks.emitAsync("post_delete", {
+            scope,
+            kind,
+            name,
+            data: {},
+            ...(layer !== undefined ? { layer } : {}),
+        });
+    }
+    /** Validate a SINGLE Kind-Writer target's slot↔schema contract. Moved from
+     *  `Kernel._validateOneKindWriterEntry`. */
+    validateOneKindWriterEntry(target, creativeSlots, systemSlots) {
+        const port = this._k.kindPortFor(target);
+        const schema = port?.schema?.() ?? null;
+        if (schema === null || typeof schema !== "object") {
+            throw new Error(`Kind-Writer Agent writes_kind=${JSON.stringify(target)} has no ` +
+                `schema (Kind is unknown or schema-less); a Kind-Writer must target a ` +
+                `schema-bearing Kind.`);
+        }
+        const properties = schema.properties ?? {};
+        for (const slot of creativeSlots) {
+            if (!(slot in properties)) {
+                throw new Error(`Kind-Writer Agent creative_slot ${JSON.stringify(slot)} is not ` +
+                    `a property of Kind ${JSON.stringify(target)}'s schema.`);
+            }
+        }
+        const covered = new Set([...creativeSlots, ...Object.keys(systemSlots ?? {})]);
+        const required = schema.required ?? [];
+        for (const req of required) {
+            if (!covered.has(req)) {
+                throw new Error(`Kind-Writer Agent: required field ${JSON.stringify(req)} of ` +
+                    `Kind ${JSON.stringify(target)} is unmapped — cover it via ` +
+                    `creative_slots or system_slots.`);
+            }
+        }
+    }
+    /** Validate a Kind-Writer Agent's slot↔schema contract. Fired by the
+     *  Helix extension's Kind-Writer `pre_save` guard via the
+     *  `kernel._validateKindWriter` shim. Moved from `Kernel._validateKindWriter`. */
+    validateKindWriter(spec) {
+        // Multi-Kind (writes_kinds): validate EACH {kind: {creative_slots,
+        // system_slots}} entry the same way. An agent uses EITHER writes_kind
+        // (single) OR writes_kinds (multi). Twin of Python validate_kind_writer.
+        const writesKinds = spec.writes_kinds;
+        if (writesKinds && Object.keys(writesKinds).length > 0) {
+            for (const [target, entry] of Object.entries(writesKinds)) {
+                const e = entry ?? {};
+                this.validateOneKindWriterEntry(target, e.creative_slots ?? [], e.system_slots ?? {});
+            }
+            return;
+        }
+        this.validateOneKindWriterEntry(spec.writes_kind, spec.creative_slots ?? [], spec.system_slots ?? {});
+    }
+}

package/dist/kernel/writer-helpers.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Shared helpers for KindPort writers — TS twin of
+ * `dna.kernel.writer_helpers` (Python).
+ *
+ * L3 (s-writer-binary-entries 2026-05-25): user-content bundle Kinds
+ * (HtmlArtifact, ImagePrompt, Pictogram, Asset) share the
+ * convention `spec.source_files: Record<string, string | Uint8Array>`
+ * which becomes sibling bundle entries alongside the writer's primary
+ * marker. Centralising the pop+convert+write logic keeps writers honest
+ * and lets adapter-level enhancements land in one place.
+ */
+import type { BundleHandle } from "./bundle-handle.js";
+import type { SerializedFile } from "./protocols.js";
+/**
+ * Pop `spec.source_files` from spec (mutates) and convert each file
+ * to a bundle-entry dict. Returns SerializedFile[] using `content`
+ * for strings and `contentBytes` for binary.
+ */
+export declare function popSourceFilesAsEntries(spec: Record<string, unknown>, kindName: string): SerializedFile[];
+/**
+ * Write a list of bundle entries (mixed text/binary) to a BundleHandle.
+ * Dispatches each entry to bundle.writeText or bundle.writeBytes.
+ */
+export declare function writeEntriesToHandle(bundle: BundleHandle, entries: SerializedFile[]): Promise<void>;

package/dist/kernel/writer-helpers.js

@@ -0,0 +1,42 @@
+/**
+ * Pop `spec.source_files` from spec (mutates) and convert each file
+ * to a bundle-entry dict. Returns SerializedFile[] using `content`
+ * for strings and `contentBytes` for binary.
+ */
+export function popSourceFilesAsEntries(spec, kindName) {
+    const extra = spec.source_files;
+    delete spec.source_files;
+    if (extra == null)
+        return [];
+    if (typeof extra !== "object" || Array.isArray(extra)) {
+        throw new TypeError(`${kindName}.spec.source_files must be a Record<string, string|Uint8Array>, got ${typeof extra}`);
+    }
+    const out = [];
+    for (const [relPath, payload] of Object.entries(extra)) {
+        if (payload instanceof Uint8Array) {
+            out.push({ relativePath: relPath, contentBytes: payload });
+        }
+        else if (typeof payload === "string") {
+            out.push({ relativePath: relPath, content: payload });
+        }
+        else {
+            throw new TypeError(`${kindName}.spec.source_files[${JSON.stringify(relPath)}] must be ` +
+                `string or Uint8Array, got ${typeof payload}`);
+        }
+    }
+    return out;
+}
+/**
+ * Write a list of bundle entries (mixed text/binary) to a BundleHandle.
+ * Dispatches each entry to bundle.writeText or bundle.writeBytes.
+ */
+export async function writeEntriesToHandle(bundle, entries) {
+    for (const f of entries) {
+        if (f.contentBytes !== undefined) {
+            await bundle.writeBytes(f.relativePath, f.contentBytes);
+        }
+        else if (f.content !== undefined) {
+            await bundle.writeText(f.relativePath, f.content);
+        }
+    }
+}

package/dist/memory/decay.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Ebbinghaus forgetting curve + bi-temporal validity — pure math (TS twin of
+ * `dna/memory/decay.py`). R(t) = e^(-t/S). Bit-identical arithmetic to Python.
+ *
+ * s-memory-verbs (2026-07-09).
+ */
+import { DecayPolicy } from "./policy.js";
+type Spec = Record<string, unknown> | null | undefined;
+/** `confidence_score` → number. Numeric passthrough or tier (faint=1, firm=3, burning=5). */
+export declare function confidenceScoreNumeric(spec: Spec, def?: number): number;
+/** Resolve stability (days) from a memory spec — explicit → tier → legacy numeric → default. */
+export declare function stabilityFromSpec(spec: Spec, policy?: DecayPolicy): number;
+/** Days elapsed since `ts` (ISO). null on unparseable input. `now` in epoch ms. */
+export declare function daysSince(ts: unknown, now?: number): number | null;
+/** R(t) = e^(-t/S). 1.0 when never recalled (`daysSinceRecall` null/≤0). */
+export declare function ebbinghausRetention(stabilityDays: number, daysSinceRecall: number | null): number;
+/** Spacing-effect bump: S_new = S_old × (1 + 0.5 × R(t)); capped. */
+export declare function recallBump(currentStability: number, daysSinceRecall: number | null, policy?: DecayPolicy): number;
+/** Multiply a ranking score by current retention. Returns `[adjusted, retention]`. */
+export declare function decayAdjustedScore(baseScore: number, spec: Spec, opts?: {
+    floor?: number;
+    now?: number;
+    policy?: DecayPolicy;
+}): [number, number];
+/**
+ * Bi-temporal filter (Zep valid_from/valid_to). True when the memory is still
+ * current — `valid_to` unset OR in the future. A memory invalidated in the past
+ * never surfaces. Unparseable `valid_to` fails OPEN (never hide on a bad stamp).
+ */
+export declare function currentlyValid(validTo: unknown, now?: number): boolean;
+export {};

package/dist/memory/decay.js

@@ -0,0 +1,97 @@
+/**
+ * Ebbinghaus forgetting curve + bi-temporal validity — pure math (TS twin of
+ * `dna/memory/decay.py`). R(t) = e^(-t/S). Bit-identical arithmetic to Python.
+ *
+ * s-memory-verbs (2026-07-09).
+ */
+import { DEFAULT_DECAY_POLICY, decayTiers } from "./policy.js";
+function parseIso(ts) {
+    if (typeof ts !== "string" || !ts)
+        return null;
+    const ms = Date.parse(ts.replace("Z", "+00:00"));
+    return Number.isNaN(ms) ? null : ms;
+}
+/** `confidence_score` → number. Numeric passthrough or tier (faint=1, firm=3, burning=5). */
+export function confidenceScoreNumeric(spec, def = 1.0) {
+    if (!spec || typeof spec !== "object")
+        return def;
+    const raw = spec.confidence_score;
+    if (raw == null)
+        return def;
+    if (typeof raw === "number")
+        return raw;
+    if (typeof raw === "string") {
+        const map = { faint: 1.0, firm: 3.0, burning: 5.0 };
+        return map[raw.toLowerCase()] ?? def;
+    }
+    return def;
+}
+/** Resolve stability (days) from a memory spec — explicit → tier → legacy numeric → default. */
+export function stabilityFromSpec(spec, policy = DEFAULT_DECAY_POLICY) {
+    const tiers = decayTiers(policy);
+    if (!spec || typeof spec !== "object" || Object.keys(spec).length === 0) {
+        return policy.defaultStabilityDays;
+    }
+    const s = spec;
+    const explicit = s.engram_stability_days;
+    if (typeof explicit === "number" && explicit > 0)
+        return explicit;
+    const strength = s.confidence_score;
+    if (typeof strength === "string") {
+        return tiers[strength.toLowerCase()] ?? policy.defaultStabilityDays;
+    }
+    if (typeof strength === "number") {
+        const v = strength;
+        if (v <= 1.0)
+            return tiers.faint;
+        if (v <= 5.0)
+            return tiers.faint + ((v - 1.0) / 4.0) * (tiers.firm - tiers.faint);
+        if (v <= 10.0)
+            return tiers.firm + ((v - 5.0) / 5.0) * (tiers.burning - tiers.firm);
+        return tiers.burning;
+    }
+    return policy.defaultStabilityDays;
+}
+/** Days elapsed since `ts` (ISO). null on unparseable input. `now` in epoch ms. */
+export function daysSince(ts, now = Date.now()) {
+    const ms = parseIso(ts);
+    if (ms === null)
+        return null;
+    return Math.max((now - ms) / 86_400_000, 0.0);
+}
+/** R(t) = e^(-t/S). 1.0 when never recalled (`daysSinceRecall` null/≤0). */
+export function ebbinghausRetention(stabilityDays, daysSinceRecall) {
+    if (daysSinceRecall === null || daysSinceRecall <= 0)
+        return 1.0;
+    const s = Math.max(0.1, stabilityDays);
+    return Math.exp(-daysSinceRecall / s);
+}
+/** Spacing-effect bump: S_new = S_old × (1 + 0.5 × R(t)); capped. */
+export function recallBump(currentStability, daysSinceRecall, policy = DEFAULT_DECAY_POLICY) {
+    const s = Math.max(0.1, currentStability);
+    const r = ebbinghausRetention(s, daysSinceRecall);
+    return Math.min(s * (1.0 + 0.5 * r), policy.maxStabilityDays);
+}
+/** Multiply a ranking score by current retention. Returns `[adjusted, retention]`. */
+export function decayAdjustedScore(baseScore, spec, opts = {}) {
+    const { floor = 0.05, now = Date.now(), policy = DEFAULT_DECAY_POLICY } = opts;
+    const s = stabilityFromSpec(spec, policy);
+    const last = spec?.last_surfaced
+        ?? spec?.last_recall_at;
+    const days = daysSince(last, now);
+    const retention = ebbinghausRetention(s, days);
+    return [baseScore * Math.max(floor, retention), retention];
+}
+/**
+ * Bi-temporal filter (Zep valid_from/valid_to). True when the memory is still
+ * current — `valid_to` unset OR in the future. A memory invalidated in the past
+ * never surfaces. Unparseable `valid_to` fails OPEN (never hide on a bad stamp).
+ */
+export function currentlyValid(validTo, now = Date.now()) {
+    if (!validTo)
+        return true;
+    const ms = parseIso(validTo);
+    if (ms === null)
+        return true;
+    return ms > now;
+}

package/dist/memory/ecphory.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Deterministic ecphory — Semon's Law of Ecphory as a pure function (TS twin of
+ * `dna/memory/ecphory.py`). Partial-match between a cue context and an engram's
+ * encoding_context, weighted overlap, saturation/novelty/recency adjustments,
+ * homophony propagation. No LLM, no kernel — the verb layer owns persistence.
+ *
+ * s-memory-verbs (2026-07-09).
+ */
+import { RecallPolicy } from "./policy.js";
+export interface EngramRef {
+    name: string;
+    spec: Record<string, unknown>;
+}
+export interface EcphoryScore {
+    engram: EngramRef;
+    score: number;
+    matchedDims: string[];
+    reasonTags: string[];
+}
+/** Partial-match score between an engram's encoding_context and a cue. */
+export declare function scoreEngram(engram: EngramRef, cueCtx: Record<string, unknown>, semanticScores?: Record<string, number>, policy?: RecallPolicy): EcphoryScore;
+/** Saturation / novelty / recency / high-fidelity modifiers. */
+export declare function applySemonAdjustments(s: EcphoryScore, now: number, policy?: RecallPolicy): EcphoryScore;
+/** Surface homophonic neighbors via `homophonic_links`. Score = direct × 0.7 × resonance. */
+export declare function expandHomophony(directs: EcphoryScore[], engramByName: Map<string, EngramRef>): EcphoryScore[];

package/dist/memory/ecphory.js

@@ -0,0 +1,178 @@
+/**
+ * Deterministic ecphory — Semon's Law of Ecphory as a pure function (TS twin of
+ * `dna/memory/ecphory.py`). Partial-match between a cue context and an engram's
+ * encoding_context, weighted overlap, saturation/novelty/recency adjustments,
+ * homophony propagation. No LLM, no kernel — the verb layer owns persistence.
+ *
+ * s-memory-verbs (2026-07-09).
+ */
+import { DEFAULT_RECALL_POLICY } from "./policy.js";
+function tokenize(s) {
+    return new Set(s.toLowerCase().split(/[\s/_-]+/).filter(Boolean));
+}
+function withinWindow(atIso, now, hours) {
+    if (typeof atIso !== "string" || !atIso)
+        return false;
+    const ms = Date.parse(atIso.replace("Z", "+00:00"));
+    if (Number.isNaN(ms))
+        return false;
+    return now - ms <= hours * 3_600_000;
+}
+/** Partial-match score between an engram's encoding_context and a cue. */
+export function scoreEngram(engram, cueCtx, semanticScores, policy = DEFAULT_RECALL_POLICY) {
+    const spec = engram.spec;
+    const ec = spec.encoding_context ?? {};
+    const matched = [];
+    let score = 0.0;
+    const ecArea = String(ec.area ?? spec.area ?? "").trim();
+    const cueArea = String(cueCtx.area_inferred ?? cueCtx.query ?? "").trim();
+    const cueQ = cueArea.toLowerCase();
+    // Path 1: area token overlap.
+    let areaScore = 0.0;
+    let areaLabel = "";
+    if (ecArea && cueArea) {
+        const ecTokens = tokenize(ecArea);
+        const cueTokens = tokenize(cueArea);
+        if (ecTokens.size && cueTokens.size) {
+            const common = new Set([...ecTokens].filter((t) => cueTokens.has(t)));
+            const union = new Set([...ecTokens, ...cueTokens]);
+            const isSuperset = common.size === ecTokens.size || common.size === cueTokens.size;
+            if (isSuperset) {
+                areaScore = policy.contentWeight;
+                areaLabel = "area";
+            }
+            else if (common.size) {
+                const jaccard = common.size / union.size;
+                areaScore = policy.contentWeight * jaccard;
+                areaLabel = `area~${jaccard.toFixed(2)}`;
+            }
+        }
+    }
+    // Path 2: query phrase in summary/title/body.
+    let summaryScore = 0.0;
+    let summaryLabel = "";
+    if (cueQ && cueQ.length >= 3) {
+        const haystack = ["summary", "title", "body"]
+            .map((f) => String(spec[f] ?? ""))
+            .join(" ")
+            .toLowerCase();
+        if (haystack && haystack.includes(cueQ)) {
+            summaryScore = policy.contentWeight;
+            summaryLabel = "summary";
+        }
+        else if (haystack) {
+            const qTokens = tokenize(cueQ);
+            const contentTokens = tokenize(haystack);
+            if (qTokens.size && [...qTokens].every((t) => contentTokens.has(t))) {
+                summaryScore = policy.summaryPartialWeight;
+                summaryLabel = "summary-tokens";
+            }
+        }
+    }
+    // Path 3: embedding cosine (only when caller feeds semanticScores).
+    let semanticScore = 0.0;
+    let semanticLabel = "";
+    if (semanticScores) {
+        const cos = Number(semanticScores[engram.name] ?? 0.0);
+        if (cos > 0.0) {
+            semanticScore = policy.cosineWeight * cos;
+            semanticLabel = `semantic~${cos.toFixed(2)}`;
+        }
+    }
+    const primary = Math.max(areaScore, summaryScore, semanticScore);
+    if (primary > 0) {
+        score += primary;
+        if (primary === areaScore && areaLabel)
+            matched.push(areaLabel);
+        else if (primary === summaryScore && summaryLabel)
+            matched.push(summaryLabel);
+        else if (semanticLabel)
+            matched.push(semanticLabel);
+    }
+    // co_topics jaccard.
+    const ecTopics = new Set(ec.co_topics ?? []);
+    const cueTopics = new Set(cueCtx.co_topics ?? []);
+    if (ecTopics.size && cueTopics.size) {
+        const overlap = new Set([...ecTopics].filter((t) => cueTopics.has(t)));
+        const union = new Set([...ecTopics, ...cueTopics]);
+        if (union.size) {
+            score += policy.coTopicsWeight * (overlap.size / union.size);
+            if (overlap.size)
+                matched.push(`co_topics(${overlap.size})`);
+        }
+    }
+    // source_refs distinctiveness.
+    const ecRefs = new Set((ec.source_refs ?? spec.source_refs) ?? []);
+    const cueRefs = new Set(cueCtx.source_refs ?? []);
+    if (ecRefs.size && cueRefs.size && [...ecRefs].some((r) => cueRefs.has(r))) {
+        score += policy.sourceRefsWeight;
+        matched.push("source_refs");
+    }
+    // affect mood (marginal boost).
+    const ecAffect = ec.affect ?? spec.affect;
+    const cueAffect = cueCtx.affect_mood;
+    if (ecAffect && cueAffect && ecAffect !== "neutral" && cueAffect !== "neutral" && ecAffect === cueAffect) {
+        score += policy.affectWeight;
+        matched.push("affect");
+    }
+    // time_of_day (perceptual, marginal).
+    if (ec.time_of_day && cueCtx.time_of_day && ec.time_of_day === cueCtx.time_of_day) {
+        score += policy.timeWeight;
+        matched.push("time");
+    }
+    return { engram, score, matchedDims: matched, reasonTags: [] };
+}
+/** Saturation / novelty / recency / high-fidelity modifiers. */
+export function applySemonAdjustments(s, now, policy = DEFAULT_RECALL_POLICY) {
+    const spec = s.engram.spec;
+    const cues = spec.cues_history ?? [];
+    const recent24h = cues.filter((c) => c && typeof c === "object" && withinWindow(c.at, now, 24)).length;
+    if (recent24h >= policy.saturationThreshold) {
+        s.score *= policy.saturationDecay;
+        s.reasonTags.push("saturation_decay");
+    }
+    if (cues.length === 0) {
+        s.score += policy.noveltyBoost;
+        s.reasonTags.push("novelty_boost");
+    }
+    if (withinWindow(spec.created_at, now, 24)) {
+        s.score += policy.recencyBoost;
+        s.reasonTags.push("recency_boost");
+    }
+    const strength = spec.confidence_score;
+    if (typeof strength === "number" && strength > 1.1) {
+        s.score += 0.05;
+        s.reasonTags.push("high_fidelity");
+    }
+    return s;
+}
+/** Surface homophonic neighbors via `homophonic_links`. Score = direct × 0.7 × resonance. */
+export function expandHomophony(directs, engramByName) {
+    const homo = new Map();
+    for (const d of directs) {
+        const links = d.engram.spec.homophonic_links ?? [];
+        for (const link of links) {
+            if (!link || typeof link !== "object")
+                continue;
+            const l = link;
+            const targetName = String(l.target_name ?? l.engram_name ?? "").trim();
+            if (!targetName || targetName === d.engram.name)
+                continue;
+            const target = engramByName.get(targetName);
+            if (!target)
+                continue;
+            const resonance = Number(l.resonance_score ?? 0.5);
+            const newScore = d.score * 0.7 * resonance;
+            const existing = homo.get(targetName);
+            if (!existing || newScore > existing.score) {
+                homo.set(targetName, {
+                    engram: target,
+                    score: newScore,
+                    matchedDims: ["homophonic"],
+                    reasonTags: [`via=${d.engram.name}`, `basis=${l.basis ?? "co-area"}`],
+                });
+            }
+        }
+    }
+    return [...homo.values()].sort((a, b) => b.score - a.score);
+}