@chiligpt/memory 0.1.0

package/dist/core/context-graph.js

@@ -0,0 +1,363 @@
+/**
+ * Context graph — ContextNode write path (F-57) and entity coupling (F-58).
+ *
+ * Hooks into `session_before_compact` (blocking). An LLM call extracts
+ * userContext, agentContext, topics[], and entities[] from branch entries.
+ * Writes a ContextNode and coupled EntityNodes to storage.
+ *
+ * Adapted for @chili/memory: uses IMemoryStorage (collection names) instead of
+ * StorageLayout (file paths), LLMCompleteFn instead of @chili/ai types, and
+ * MemoryBranchEntry instead of chili-internal SessionEntry.
+ */
+import { createEntity, nameHash, updateEntity, validityScore } from "./entity.js";
+function extractText(content) {
+    if (typeof content === "string")
+        return content;
+    if (Array.isArray(content)) {
+        return content
+            .filter((b) => b.type === "text")
+            .map((b) => b.text)
+            .join(" ");
+    }
+    return "";
+}
+/** Serialise branch entries to a readable transcript for the LLM. */
+function formatBranchEntries(entries) {
+    const lines = [];
+    for (const entry of entries) {
+        if (entry.type === "message" && entry.message) {
+            const msg = entry.message;
+            if (msg.role === "user") {
+                const text = extractText(msg.content).trim();
+                if (text)
+                    lines.push(`User: ${text}`);
+            }
+            else if (msg.role === "assistant") {
+                const text = extractText(msg.content).trim();
+                if (text)
+                    lines.push(`Assistant: ${text.slice(0, 500)}`);
+            }
+        }
+    }
+    return lines.join("\n") || "(no messages)";
+}
+const EXTRACTION_SYSTEM_PROMPT = `You are a memory extraction assistant for a coding agent session.
+Analyze the provided conversation transcript and extract structured metadata.
+Respond ONLY with valid JSON matching the schema — no markdown, no explanation.`;
+function buildExtractionPrompt(transcript, cwd) {
+    return [
+        {
+            role: "user",
+            timestamp: Date.now(),
+            content: `Extract metadata from this coding session transcript.
+Working directory: ${cwd}
+
+TRANSCRIPT:
+${transcript}
+
+Respond with JSON only:
+{
+  "userContext": "<1-3 sentences: what the user was asking or working on>",
+  "agentContext": "<1-3 sentences: what the agent did in response>",
+  "topics": ["<topic1>", "<topic2>"],
+  "entities": [
+    { "name": "<canonical name>", "type": "<file|person|concept|module|decision|url>" }
+  ],
+  "relevantFilePaths": ["<file path mentioned in agent work>"],
+  "relevantModules": ["<package or module name referenced>"],
+  "searchTerms": ["<query 1>", "<query 2>"],
+  "entityEvents": [
+    { "name": "<entity canonical name>", "type": "<entity type>", "event": "<renamed|deprecated|replaced>", "newName": "<new name if renamed>" }
+  ]
+}
+
+Rules:
+- userContext: from the user's perspective — their goal/question
+- agentContext: from the agent's perspective — actions taken
+- topics: 2-5 short keyword phrases for categorization
+- entities: named things that appeared — files, people, modules, decisions, URLs, and concepts (including programming languages, frameworks, algorithms, data structures, and named techniques)
+- relevantFilePaths: actual file paths the agent read/edited/created (empty if none)
+- relevantModules: npm packages or internal module names mentioned (empty if none)
+- searchTerms: 3-5 natural-language queries someone would type to find this session later — use varied vocabulary, not just technical terms (e.g. "how we fixed the memory search bug", "storage adapter interface design")
+- entityEvents: observable state changes — renames, deprecations, replacements (empty if none)
+- Keep all strings concise (under 200 chars each)`,
+        },
+    ];
+}
+function parseExtractionResponse(response) {
+    const textBlock = Array.isArray(response.content)
+        ? response.content.find((b) => b.type === "text")
+        : null;
+    const raw = textBlock ? textBlock.text : "";
+    // Strip markdown code fences if present
+    const cleaned = raw.replace(/^```(?:json)?\n?/m, "").replace(/\n?```$/m, "").trim();
+    try {
+        const parsed = JSON.parse(cleaned);
+        const validTypes = ["file", "person", "concept", "module", "decision", "url"];
+        return {
+            userContext: typeof parsed.userContext === "string" ? parsed.userContext : "(no context)",
+            agentContext: typeof parsed.agentContext === "string" ? parsed.agentContext : "(no context)",
+            topics: Array.isArray(parsed.topics) ? parsed.topics.filter((t) => typeof t === "string") : [],
+            entities: Array.isArray(parsed.entities)
+                ? parsed.entities.filter((e) => typeof e?.name === "string" && validTypes.includes(e?.type))
+                : [],
+            relevantFilePaths: Array.isArray(parsed.relevantFilePaths)
+                ? parsed.relevantFilePaths.filter((p) => typeof p === "string")
+                : [],
+            relevantModules: Array.isArray(parsed.relevantModules)
+                ? parsed.relevantModules.filter((m) => typeof m === "string")
+                : [],
+            searchTerms: Array.isArray(parsed.searchTerms)
+                ? parsed.searchTerms.filter((s) => typeof s === "string")
+                : [],
+            entityEvents: Array.isArray(parsed.entityEvents)
+                ? parsed.entityEvents.filter((e) => typeof e?.name === "string" &&
+                    validTypes.includes(e?.type) &&
+                    ["renamed", "deprecated", "replaced"].includes(e?.event))
+                : [],
+        };
+    }
+    catch {
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Entity coupling (F-58)
+// ---------------------------------------------------------------------------
+const VALID_ENTITY_TYPES = new Set(["file", "person", "concept", "module", "decision", "url"]);
+async function coupleEntities(entities, entityIndex, storage, sessionOrdinal, now) {
+    const entityPointerIds = [];
+    for (const { name, type } of entities) {
+        if (!VALID_ENTITY_TYPES.has(type))
+            continue;
+        const existing = entityIndex.get(name, type);
+        if (existing) {
+            // Update lastReferencedAt in memory and on disk
+            const updated = { ...existing, lastReferencedAt: now };
+            entityIndex.update(existing.id, { lastReferencedAt: now });
+            await updateEntity(storage, existing.id, { lastReferencedAt: now });
+            entityPointerIds.push(updated.id);
+        }
+        else {
+            // Create new EntityNode with confirmed event (eventType=1)
+            const hash = nameHash(name);
+            const node = {
+                id: globalThis.crypto.randomUUID(),
+                type,
+                canonicalName: name,
+                currentNameHash: hash,
+                eventMatrix: [[1, now, 0, hash, sessionOrdinal]],
+                lastReferencedAt: now,
+                edges: [],
+            };
+            await createEntity(storage, node);
+            entityIndex.set(node);
+            entityPointerIds.push(node.id);
+        }
+    }
+    return entityPointerIds;
+}
+// ---------------------------------------------------------------------------
+// ContextNode CRUD
+// ---------------------------------------------------------------------------
+export async function loadAllContextNodes(storage) {
+    return storage.readAll("context");
+}
+export async function updateContextNode(storage, id, patch) {
+    await storage.update("context", id, patch);
+}
+export async function loadContextNodeWithSupersession(storage, id) {
+    const all = await loadAllContextNodes(storage);
+    const node = all.find((n) => n.id === id) ?? null;
+    if (!node)
+        return [null, null];
+    const neighbourId = node.supersededBy ?? node.supersedes;
+    const neighbour = neighbourId ? (all.find((n) => n.id === neighbourId) ?? null) : null;
+    return [node, neighbour];
+}
+// ---------------------------------------------------------------------------
+// F-67: Entity event updates from agent observations
+// ---------------------------------------------------------------------------
+const EVENT_TYPE_MAP = {
+    renamed: 2,
+    deprecated: 3,
+    replaced: 4,
+};
+async function applyEntityEvents(events, entityIndex, storage, sessionOrdinal, now) {
+    for (const evt of events) {
+        // AC-67-02: Skip entities not in index — no creation in this path
+        const existing = entityIndex.get(evt.name, evt.type);
+        if (!existing)
+            continue;
+        const eventType = EVENT_TYPE_MAP[evt.event];
+        const newHash = evt.newName ? nameHash(evt.newName) : existing.currentNameHash;
+        const vector = [eventType, now, existing.currentNameHash, newHash, sessionOrdinal];
+        const updatedMatrix = [...existing.eventMatrix, vector];
+        const patch = { eventMatrix: updatedMatrix };
+        // Update currentNameHash on rename
+        if (evt.event === "renamed" && evt.newName) {
+            patch.currentNameHash = newHash;
+        }
+        await updateEntity(storage, existing.id, patch);
+        entityIndex.update(existing.id, patch);
+    }
+}
+// ---------------------------------------------------------------------------
+// Main: write ContextNode from compaction event (F-57 + F-58 + F-67 + F-68)
+// ---------------------------------------------------------------------------
+export async function writeContextNodeFromCompaction(params) {
+    const { branchEntries, sessionId, sessionFile, storage, entityIndex, complete, sessionOrdinal = 0, cwd = "" } = params;
+    if (branchEntries.length === 0)
+        return null;
+    const transcript = formatBranchEntries(branchEntries);
+    const messages = buildExtractionPrompt(transcript, cwd);
+    let extraction = null;
+    try {
+        const response = await complete(messages, { systemPrompt: EXTRACTION_SYSTEM_PROMPT });
+        extraction = parseExtractionResponse(response);
+    }
+    catch (err) {
+        console.error("[memory] LLM extraction failed:", err instanceof Error ? err.message : String(err));
+        return null;
+    }
+    if (!extraction)
+        return null;
+    const now = Date.now();
+    // F-58: Entity coupling — write entity nodes and get their IDs
+    const entityPointerIds = await coupleEntities(extraction.entities, entityIndex, storage, sessionOrdinal, now);
+    // F-67: Apply entity event updates (AC-67-01, AC-67-02)
+    if (extraction.entityEvents.length > 0) {
+        await applyEntityEvents(extraction.entityEvents, entityIndex, storage, sessionOrdinal, now);
+    }
+    // F-57 + F-68 + F-75: Write ContextNode with extended staleness fields and session file path
+    const node = {
+        id: globalThis.crypto.randomUUID(),
+        sessionId,
+        sessionIds: [sessionId],
+        timestamp: now,
+        userContext: extraction.userContext,
+        agentContext: extraction.agentContext,
+        topics: extraction.topics,
+        entityPointerIds,
+        // F-68: Extended staleness-evidence fields (AC-68-01, AC-68-02)
+        workingDirectory: cwd || undefined,
+        relevantFilePaths: extraction.relevantFilePaths,
+        relevantModules: extraction.relevantModules,
+        // F-108: Search-oriented query terms for BM25F recall widening
+        searchTerms: extraction.searchTerms,
+        // F-75: Self-contained Layer 1 file path (AC-75-01)
+        sessionFile: sessionFile || undefined,
+    };
+    await storage.append("context", node);
+    // F-59: Supersession detection (second LLM call — best-effort, non-blocking)
+    try {
+        await detectSupersession(node, storage, sessionId, complete);
+    }
+    catch {
+        // Non-fatal
+    }
+    return node;
+}
+// ---------------------------------------------------------------------------
+// F-59: Supersession detection (second LLM call after F-58)
+// ---------------------------------------------------------------------------
+const SUPERSESSION_SYSTEM_PROMPT = `You are a memory deduplication assistant for a coding agent.
+You will be shown a new context summary and a list of previous summaries from the same session.
+Determine if the new summary substantially revisits or supersedes exactly one of the previous ones.
+
+Return ONLY the ID of the superseded summary, or null if nothing is superseded.
+A summary is superseded if the new one covers the same ground with updated or corrected information.
+Do NOT mark as superseded if both summaries are simultaneously valid (different scope, different files, different problems).
+
+Respond ONLY with valid JSON — no markdown, no explanation.`;
+function buildSupersessionPrompt(newNode, candidates) {
+    const candidateText = candidates
+        .map((c, i) => `[${i + 1}] ID: ${c.id}\nUser: ${c.userContext}\nAgent: ${c.agentContext}`)
+        .join("\n\n");
+    return [
+        {
+            role: "user",
+            timestamp: Date.now(),
+            content: `New summary:
+User: ${newNode.userContext}
+Agent: ${newNode.agentContext}
+
+Previous summaries from this session:
+${candidateText}
+
+Does the new summary substantially revisit or supersede exactly one of the previous summaries?
+If yes, return the ID of the superseded summary. If no, return null.
+
+Respond with JSON only:
+{ "supersededId": "<id>" | null }`,
+        },
+    ];
+}
+async function detectSupersession(newNode, storage, sessionId, complete) {
+    // AC-59-03: Only consider nodes from the current session (parent-chain scoping)
+    const all = await loadAllContextNodes(storage);
+    const candidates = all.filter((n) => n.id !== newNode.id && n.sessionIds.includes(sessionId) && !n.supersededBy);
+    if (candidates.length === 0)
+        return;
+    const messages = buildSupersessionPrompt(newNode, candidates);
+    let raw;
+    try {
+        const response = await complete(messages, { systemPrompt: SUPERSESSION_SYSTEM_PROMPT });
+        const textBlock = Array.isArray(response.content)
+            ? response.content.find((b) => b.type === "text")
+            : null;
+        raw = textBlock ? textBlock.text : "";
+    }
+    catch {
+        return; // Non-fatal — supersession is best-effort
+    }
+    const cleaned = raw.replace(/^```(?:json)?\n?/m, "").replace(/\n?```$/m, "").trim();
+    let supersededId = null;
+    try {
+        const parsed = JSON.parse(cleaned);
+        supersededId = typeof parsed.supersededId === "string" ? parsed.supersededId : null;
+    }
+    catch {
+        return;
+    }
+    if (!supersededId)
+        return;
+    // Verify the ID is actually a candidate (guard against hallucinated IDs)
+    const superseded = candidates.find((n) => n.id === supersededId);
+    if (!superseded)
+        return;
+    // AC-59-01: Update both sides of the supersession pair
+    const now = Date.now();
+    await updateContextNode(storage, superseded.id, { supersededBy: newNode.id, supersededAt: now });
+    await updateContextNode(storage, newNode.id, { supersedes: superseded.id });
+}
+export function projectHealth(node, entityIndex, now) {
+    if (node.entityPointerIds.length === 0) {
+        return { meanValidity: 1, minValidity: 1, degradedCount: 0, deprecatedCount: 0 };
+    }
+    let sum = 0;
+    let min = Number.POSITIVE_INFINITY;
+    let degradedCount = 0;
+    let deprecatedCount = 0;
+    for (const id of node.entityPointerIds) {
+        const entity = entityIndex.getById(id);
+        if (!entity)
+            continue;
+        const score = validityScore(entity.eventMatrix, entity.type, now);
+        sum += score;
+        if (score < min)
+            min = score;
+        if (score < 0.3)
+            degradedCount++;
+        if (score < 0)
+            deprecatedCount++;
+    }
+    const count = node.entityPointerIds.length;
+    return {
+        meanValidity: sum / count,
+        minValidity: min === Number.POSITIVE_INFINITY ? 1 : min,
+        degradedCount,
+        deprecatedCount,
+    };
+}
+//# sourceMappingURL=context-graph.js.map

package/dist/core/entity-index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * O(1) in-memory entity lookup index (F-55).
+ *
+ * Primary key: `${canonicalName}:${type}` — for name+type lookups.
+ * Secondary key: entity UUID — for ID-based lookups (used in health projection).
+ *
+ * Both maps are kept in sync. Built once at session_start from
+ * layer2-entity.jsonl (O(N)). Updated in-place on every create or update.
+ */
+import type { EntityNode, EntityType } from "./entity.js";
+export type EntityIndexKey = `${string}:${EntityType}`;
+export declare class EntityIndex {
+    private nameMap;
+    private idMap;
+    /**
+     * Populate the index from all records read from disk.
+     * Called once during session_start (O(N) — acceptable).
+     */
+    build(nodes: EntityNode[]): void;
+    /** O(1) lookup by canonical name and type (AC-55-01). */
+    get(canonicalName: string, type: EntityType): EntityNode | undefined;
+    /** O(1) lookup by entity UUID (used by projectHealth). */
+    getById(id: string): EntityNode | undefined;
+    /** Register a new entity in the index without a full rebuild (AC-55-02). */
+    set(node: EntityNode): void;
+    /** Update an existing entity's in-memory state in-place. */
+    update(id: string, patch: Partial<EntityNode>): void;
+    /** Iterate all nodes (used by orphan detection). */
+    values(): IterableIterator<EntityNode>;
+    /** Number of entities currently indexed. */
+    get size(): number;
+}
+//# sourceMappingURL=entity-index.d.ts.map

package/dist/core/entity-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-index.d.ts","sourceRoot":"","sources":["../../src/core/entity-index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE1D,MAAM,MAAM,cAAc,GAAG,GAAG,MAAM,IAAI,UAAU,EAAE,CAAC;AAMvD,qBAAa,WAAW;IACvB,OAAO,CAAC,OAAO,CAA8C;IAC7D,OAAO,CAAC,KAAK,CAAsC;IAEnD;;;OAGG;IACH,KAAK,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,IAAI,CAO/B;IAED,yDAAyD;IACzD,GAAG,CAAC,aAAa,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,GAAG,UAAU,GAAG,SAAS,CAEnE;IAED,0DAA0D;IAC1D,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAE1C;IAED,4EAA4E;IAC5E,GAAG,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,CAG1B;IAED,4DAA4D;IAC5D,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG,IAAI,CAMnD;IAED,oDAAoD;IACpD,MAAM,IAAI,gBAAgB,CAAC,UAAU,CAAC,CAErC;IAED,4CAA4C;IAC5C,IAAI,IAAI,IAAI,MAAM,CAEjB;CACD","sourcesContent":["/**\n * O(1) in-memory entity lookup index (F-55).\n *\n * Primary key: `${canonicalName}:${type}` — for name+type lookups.\n * Secondary key: entity UUID — for ID-based lookups (used in health projection).\n *\n * Both maps are kept in sync. Built once at session_start from\n * layer2-entity.jsonl (O(N)). Updated in-place on every create or update.\n */\n\nimport type { EntityNode, EntityType } from \"./entity.js\";\n\nexport type EntityIndexKey = `${string}:${EntityType}`;\n\nfunction indexKey(canonicalName: string, type: EntityType): EntityIndexKey {\n\treturn `${canonicalName}:${type}` as EntityIndexKey;\n}\n\nexport class EntityIndex {\n\tprivate nameMap: Map<EntityIndexKey, EntityNode> = new Map();\n\tprivate idMap: Map<string, EntityNode> = new Map();\n\n\t/**\n\t * Populate the index from all records read from disk.\n\t * Called once during session_start (O(N) — acceptable).\n\t */\n\tbuild(nodes: EntityNode[]): void {\n\t\tthis.nameMap.clear();\n\t\tthis.idMap.clear();\n\t\tfor (const node of nodes) {\n\t\t\tthis.nameMap.set(indexKey(node.canonicalName, node.type), node);\n\t\t\tthis.idMap.set(node.id, node);\n\t\t}\n\t}\n\n\t/** O(1) lookup by canonical name and type (AC-55-01). */\n\tget(canonicalName: string, type: EntityType): EntityNode | undefined {\n\t\treturn this.nameMap.get(indexKey(canonicalName, type));\n\t}\n\n\t/** O(1) lookup by entity UUID (used by projectHealth). */\n\tgetById(id: string): EntityNode | undefined {\n\t\treturn this.idMap.get(id);\n\t}\n\n\t/** Register a new entity in the index without a full rebuild (AC-55-02). */\n\tset(node: EntityNode): void {\n\t\tthis.nameMap.set(indexKey(node.canonicalName, node.type), node);\n\t\tthis.idMap.set(node.id, node);\n\t}\n\n\t/** Update an existing entity's in-memory state in-place. */\n\tupdate(id: string, patch: Partial<EntityNode>): void {\n\t\tconst node = this.idMap.get(id);\n\t\tif (!node) return;\n\t\tconst updated = { ...node, ...patch };\n\t\tthis.nameMap.set(indexKey(node.canonicalName, node.type), updated);\n\t\tthis.idMap.set(id, updated);\n\t}\n\n\t/** Iterate all nodes (used by orphan detection). */\n\tvalues(): IterableIterator<EntityNode> {\n\t\treturn this.idMap.values();\n\t}\n\n\t/** Number of entities currently indexed. */\n\tget size(): number {\n\t\treturn this.idMap.size;\n\t}\n}\n"]}

package/dist/core/entity-index.js

@@ -0,0 +1,59 @@
+/**
+ * O(1) in-memory entity lookup index (F-55).
+ *
+ * Primary key: `${canonicalName}:${type}` — for name+type lookups.
+ * Secondary key: entity UUID — for ID-based lookups (used in health projection).
+ *
+ * Both maps are kept in sync. Built once at session_start from
+ * layer2-entity.jsonl (O(N)). Updated in-place on every create or update.
+ */
+function indexKey(canonicalName, type) {
+    return `${canonicalName}:${type}`;
+}
+export class EntityIndex {
+    nameMap = new Map();
+    idMap = new Map();
+    /**
+     * Populate the index from all records read from disk.
+     * Called once during session_start (O(N) — acceptable).
+     */
+    build(nodes) {
+        this.nameMap.clear();
+        this.idMap.clear();
+        for (const node of nodes) {
+            this.nameMap.set(indexKey(node.canonicalName, node.type), node);
+            this.idMap.set(node.id, node);
+        }
+    }
+    /** O(1) lookup by canonical name and type (AC-55-01). */
+    get(canonicalName, type) {
+        return this.nameMap.get(indexKey(canonicalName, type));
+    }
+    /** O(1) lookup by entity UUID (used by projectHealth). */
+    getById(id) {
+        return this.idMap.get(id);
+    }
+    /** Register a new entity in the index without a full rebuild (AC-55-02). */
+    set(node) {
+        this.nameMap.set(indexKey(node.canonicalName, node.type), node);
+        this.idMap.set(node.id, node);
+    }
+    /** Update an existing entity's in-memory state in-place. */
+    update(id, patch) {
+        const node = this.idMap.get(id);
+        if (!node)
+            return;
+        const updated = { ...node, ...patch };
+        this.nameMap.set(indexKey(node.canonicalName, node.type), updated);
+        this.idMap.set(id, updated);
+    }
+    /** Iterate all nodes (used by orphan detection). */
+    values() {
+        return this.idMap.values();
+    }
+    /** Number of entities currently indexed. */
+    get size() {
+        return this.idMap.size;
+    }
+}
+//# sourceMappingURL=entity-index.js.map

package/dist/core/entity.d.ts

@@ -0,0 +1,56 @@
+/**
+ * EntityNode schema, EventVector encoding, and validity scoring (F-54).
+ *
+ * Validity uses exponential decay so that recent confirmed events raise
+ * a score while stale or deprecated ones lower it — no binary threshold.
+ */
+export type EntityType = "file" | "person" | "concept" | "module" | "decision" | "url";
+/**
+ * Fixed-width tuple: [eventType, timestamp, prevNameHash, newNameHash, sessionOrdinal]
+ *
+ * eventType encoding:
+ *   1 = confirmed   (+1.0 contribution)
+ *   2 = renamed     (+0.5 contribution)
+ *   3 = deprecated  (-1.0 contribution)
+ *   4 = replaced    (-0.5 contribution)
+ */
+export type EventVector = [
+    eventType: 1 | 2 | 3 | 4,
+    timestamp: number,
+    prevNameHash: number,
+    newNameHash: number,
+    sessionOrdinal: number
+];
+export interface EntityEdge {
+    predicate: "replaced_by" | "alias_of" | "derived_from";
+    targetId: string;
+}
+export interface EntityNode {
+    id: string;
+    type: EntityType;
+    canonicalName: string;
+    currentNameHash: number;
+    eventMatrix: EventVector[];
+    lastReferencedAt: number;
+    edges: EntityEdge[];
+    /** Set by orphan detection when the entity is moved to archive storage. */
+    _archived?: boolean;
+}
+/**
+ * Compute validity score for an entity's event matrix at a given time.
+ *
+ * score = Σ CONTRIBUTION[eventType] × exp(−λ × age)
+ *
+ * Validity gradient:
+ *   > 0.7  → trusted
+ *   0.3–0.7 → uncertain
+ *   0–0.3  → degraded
+ *   < 0    → deprecated signal dominates
+ */
+export declare function validityScore(matrix: EventVector[], type: EntityType, now: number): number;
+import type { IMemoryStorage } from "../storage/adapter.js";
+export declare function createEntity(storage: IMemoryStorage, node: EntityNode): Promise<void>;
+export declare function updateEntity(storage: IMemoryStorage, id: string, patch: Partial<EntityNode>): Promise<void>;
+export declare function loadAllEntities(storage: IMemoryStorage): Promise<EntityNode[]>;
+export declare function nameHash(name: string): number;
+//# sourceMappingURL=entity.d.ts.map

package/dist/core/entity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity.d.ts","sourceRoot":"","sources":["../../src/core/entity.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,UAAU,GAAG,KAAK,CAAC;AAEvF;;;;;;;;GAQG;AACH,MAAM,MAAM,WAAW,GAAG;IACzB,SAAS,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC;IACxB,SAAS,EAAE,MAAM;IACjB,YAAY,EAAE,MAAM;IACpB,WAAW,EAAE,MAAM;IACnB,cAAc,EAAE,MAAM;CACtB,CAAC;AAEF,MAAM,WAAW,UAAU;IAC1B,SAAS,EAAE,aAAa,GAAG,UAAU,GAAG,cAAc,CAAC;IACvD,QAAQ,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,UAAU;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,UAAU,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,WAAW,EAAE,CAAC;IAC3B,gBAAgB,EAAE,MAAM,CAAC;IACzB,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,2EAA2E;IAC3E,SAAS,CAAC,EAAE,OAAO,CAAC;CACpB;AAyBD;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,WAAW,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAQ1F;AAOD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE5D,wBAAsB,YAAY,CAAC,OAAO,EAAE,cAAc,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAE3F;AAED,wBAAsB,YAAY,CAAC,OAAO,EAAE,cAAc,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAEjH;AAED,wBAAsB,eAAe,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAEpF;AAMD,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAM7C","sourcesContent":["/**\n * EntityNode schema, EventVector encoding, and validity scoring (F-54).\n *\n * Validity uses exponential decay so that recent confirmed events raise\n * a score while stale or deprecated ones lower it — no binary threshold.\n */\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\nexport type EntityType = \"file\" | \"person\" | \"concept\" | \"module\" | \"decision\" | \"url\";\n\n/**\n * Fixed-width tuple: [eventType, timestamp, prevNameHash, newNameHash, sessionOrdinal]\n *\n * eventType encoding:\n *   1 = confirmed   (+1.0 contribution)\n *   2 = renamed     (+0.5 contribution)\n *   3 = deprecated  (-1.0 contribution)\n *   4 = replaced    (-0.5 contribution)\n */\nexport type EventVector = [\n\teventType: 1 | 2 | 3 | 4,\n\ttimestamp: number,\n\tprevNameHash: number,\n\tnewNameHash: number,\n\tsessionOrdinal: number,\n];\n\nexport interface EntityEdge {\n\tpredicate: \"replaced_by\" | \"alias_of\" | \"derived_from\";\n\ttargetId: string;\n}\n\nexport interface EntityNode {\n\tid: string;\n\ttype: EntityType;\n\tcanonicalName: string;\n\tcurrentNameHash: number;\n\teventMatrix: EventVector[];\n\tlastReferencedAt: number;\n\tedges: EntityEdge[];\n\t/** Set by orphan detection when the entity is moved to archive storage. */\n\t_archived?: boolean;\n}\n\n// ---------------------------------------------------------------------------\n// Validity scoring\n// ---------------------------------------------------------------------------\n\n/** TTL expressed as λ for exponential decay: ln(2) / half-life-in-ms */\nconst MS_PER_DAY = 86_400_000;\n\nconst LAMBDA: Record<EntityType, number> = {\n\tfile: Math.LN2 / (7 * MS_PER_DAY),\n\tmodule: Math.LN2 / (14 * MS_PER_DAY),\n\turl: Math.LN2 / (14 * MS_PER_DAY),\n\tperson: Math.LN2 / (30 * MS_PER_DAY),\n\tconcept: Math.LN2 / (90 * MS_PER_DAY),\n\tdecision: Math.LN2 / (90 * MS_PER_DAY),\n};\n\nconst CONTRIBUTION: Record<1 | 2 | 3 | 4, number> = {\n\t1: +1.0,\n\t2: +0.5,\n\t3: -1.0,\n\t4: -0.5,\n};\n\n/**\n * Compute validity score for an entity's event matrix at a given time.\n *\n * score = Σ CONTRIBUTION[eventType] × exp(−λ × age)\n *\n * Validity gradient:\n *   > 0.7  → trusted\n *   0.3–0.7 → uncertain\n *   0–0.3  → degraded\n *   < 0    → deprecated signal dominates\n */\nexport function validityScore(matrix: EventVector[], type: EntityType, now: number): number {\n\tconst λ = LAMBDA[type];\n\tlet score = 0;\n\tfor (const [eventType, timestamp] of matrix) {\n\t\tconst age = now - timestamp;\n\t\tscore += CONTRIBUTION[eventType as 1 | 2 | 3 | 4] * Math.exp(-λ * age);\n\t}\n\treturn score;\n}\n\n// ---------------------------------------------------------------------------\n// CRUD helpers (over IMemoryStorage — F-53 storage primitives)\n// Adapted for @chili/memory: uses IMemoryStorage instead of direct file paths.\n// ---------------------------------------------------------------------------\n\nimport type { IMemoryStorage } from \"../storage/adapter.js\";\n\nexport async function createEntity(storage: IMemoryStorage, node: EntityNode): Promise<void> {\n\tawait storage.append<EntityNode>(\"entities\", node);\n}\n\nexport async function updateEntity(storage: IMemoryStorage, id: string, patch: Partial<EntityNode>): Promise<void> {\n\tawait storage.update<EntityNode>(\"entities\", id, patch);\n}\n\nexport async function loadAllEntities(storage: IMemoryStorage): Promise<EntityNode[]> {\n\treturn storage.readAll<EntityNode>(\"entities\");\n}\n\n// ---------------------------------------------------------------------------\n// Simple djb2 name hash (deterministic, collision-tolerant for audit trail)\n// ---------------------------------------------------------------------------\n\nexport function nameHash(name: string): number {\n\tlet hash = 5381;\n\tfor (let i = 0; i < name.length; i++) {\n\t\thash = ((hash << 5) + hash + name.charCodeAt(i)) >>> 0;\n\t}\n\treturn hash;\n}\n"]}

package/dist/core/entity.js

@@ -0,0 +1,65 @@
+/**
+ * EntityNode schema, EventVector encoding, and validity scoring (F-54).
+ *
+ * Validity uses exponential decay so that recent confirmed events raise
+ * a score while stale or deprecated ones lower it — no binary threshold.
+ */
+// ---------------------------------------------------------------------------
+// Validity scoring
+// ---------------------------------------------------------------------------
+/** TTL expressed as λ for exponential decay: ln(2) / half-life-in-ms */
+const MS_PER_DAY = 86_400_000;
+const LAMBDA = {
+    file: Math.LN2 / (7 * MS_PER_DAY),
+    module: Math.LN2 / (14 * MS_PER_DAY),
+    url: Math.LN2 / (14 * MS_PER_DAY),
+    person: Math.LN2 / (30 * MS_PER_DAY),
+    concept: Math.LN2 / (90 * MS_PER_DAY),
+    decision: Math.LN2 / (90 * MS_PER_DAY),
+};
+const CONTRIBUTION = {
+    1: +1.0,
+    2: +0.5,
+    3: -1.0,
+    4: -0.5,
+};
+/**
+ * Compute validity score for an entity's event matrix at a given time.
+ *
+ * score = Σ CONTRIBUTION[eventType] × exp(−λ × age)
+ *
+ * Validity gradient:
+ *   > 0.7  → trusted
+ *   0.3–0.7 → uncertain
+ *   0–0.3  → degraded
+ *   < 0    → deprecated signal dominates
+ */
+export function validityScore(matrix, type, now) {
+    const λ = LAMBDA[type];
+    let score = 0;
+    for (const [eventType, timestamp] of matrix) {
+        const age = now - timestamp;
+        score += CONTRIBUTION[eventType] * Math.exp(-λ * age);
+    }
+    return score;
+}
+export async function createEntity(storage, node) {
+    await storage.append("entities", node);
+}
+export async function updateEntity(storage, id, patch) {
+    await storage.update("entities", id, patch);
+}
+export async function loadAllEntities(storage) {
+    return storage.readAll("entities");
+}
+// ---------------------------------------------------------------------------
+// Simple djb2 name hash (deterministic, collision-tolerant for audit trail)
+// ---------------------------------------------------------------------------
+export function nameHash(name) {
+    let hash = 5381;
+    for (let i = 0; i < name.length; i++) {
+        hash = ((hash << 5) + hash + name.charCodeAt(i)) >>> 0;
+    }
+    return hash;
+}
+//# sourceMappingURL=entity.js.map