@harrylabsj/kiwi 0.6.0

package/dist/agent/memory/store.js

@@ -0,0 +1,881 @@
+/**
+ * Copyright 2026 harrylabsj
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { uuidv7 } from "@earendil-works/pi-ai";
+import { isMemoryNamespace, isMemorySensitivity, isMemorySourceKind, isRetrievalPurpose, isVaultKind, MemoryError, parseMemoryScope, } from "./types.js";
+import { VaultKeyError } from "./vault.js";
+import { MEMORY_SCHEMA_VERSION } from "./schema.js";
+const SOURCE_WEIGHT = {
+    explicit: 1.0,
+    observed: 0.8,
+    inferred: 0.6,
+    imported: 0.7,
+};
+const DEFAULT_CONFIDENCE = {
+    explicit: 1.0,
+    observed: 0.5,
+    inferred: 0.3,
+    imported: 0.6,
+};
+/** Soft namespaces that repeated behavior may activate without confirmation. */
+const SOFT_ACTIVATABLE = new Set(["preference", "routine"]);
+const AUTO_ACTIVATE_EVIDENCE = 3;
+const MAX_LIMIT = 32;
+/**
+ * High-impact memories must never be auto-activated by a model `remember`
+ * call: a hard `constraint` and any `restricted` value stay `candidate` until
+ * the human confirms via `/confirm` (design §10.1/§16). The model asserting
+ * `explicit_user_statement` is not ground truth — only a human can promote.
+ */
+function requiresHumanConfirm(input) {
+    return input.namespace === "constraint" || input.sensitivity === "restricted";
+}
+/**
+ * Restricted writes: never let the plaintext echo into evidence summaries or
+ * audit reasons (design §6.3 minimal disclosure). The whole-DB plaintext-free
+ * guarantee only holds if the model-supplied summary is scrubbed too.
+ */
+function evidenceSummaryFor(input, summary) {
+    if (input.sensitivity !== "restricted" || input.restricted === undefined)
+        return summary;
+    const plaintext = input.restricted.plaintext;
+    const scrubbed = plaintext !== "" ? summary.split(plaintext).join("…") : summary;
+    return scrubbed.trim() !== "" ? scrubbed : "用户确认的敏感信息（已加密保存）";
+}
+/**
+ * Precise personal data must live in the Vault regardless of the sensitivity
+ * the model happened to claim (design §6.3, §17). A string value that clearly
+ * matches one of these patterns is escalated to `restricted`; if that then
+ * fails the Restricted validation (no explicit statement, no data key) the
+ * write is refused — never degraded to plaintext.
+ */
+const PRECISE_PERSONAL_PATTERNS = [
+    {
+        kind: "address",
+        pattern: /(住址|地址|收货|寄到|家庭住址|住在|家住)[^，。；;]{0,20}\d|(?:省|市|区|县|镇|街道).{0,12}(?:号|路|小区|巷)[\d一二三四五六七八九十]*/,
+    },
+    { kind: "contact", pattern: /(电话|手机|手机号|微信号|联系方式|邮箱|e-?mail|QQ)\s*[:：]?[\s-]*\d{5,}/i },
+    { kind: "private_budget", pattern: /(预算|心理价|心理价位|最高出价|上限价)\s*[:：]?\s*(\d+)/ },
+    { kind: "merchant_cost", pattern: /(成本|进价)\s*[:：]?\s*(\d+)/ },
+    { kind: "merchant_floor", pattern: /(底价|最低价|最低售价)\s*[:：]?\s*(\d+)/ },
+    { kind: "other", pattern: /(身份证|银行卡|银行账号|护照|护照号|卡号|账号)\s*[:：]?[\dXx]/i },
+];
+function classifyPersonalData(value) {
+    for (const { kind, pattern } of PRECISE_PERSONAL_PATTERNS) {
+        if (pattern.test(value))
+            return kind;
+    }
+    return undefined;
+}
+/**
+ * Escalate a string value that clearly is precise personal data to a
+ * Restricted (Vault) write. Object/array values are left alone — a structured
+ * value is the model's explicit non-Restricted choice, not a raw secret.
+ */
+function escalateSensitivity(input) {
+    if (input.sensitivity === "restricted")
+        return input;
+    if (input.value === undefined || typeof input.value !== "string")
+        return input;
+    const kind = classifyPersonalData(input.value);
+    if (kind === undefined)
+        return input;
+    return {
+        ...input,
+        sensitivity: "restricted",
+        restricted: { kind, plaintext: input.value },
+        value: undefined,
+    };
+}
+function optText(value) {
+    return value === null ? undefined : value;
+}
+function assertJsonValue(value, at) {
+    if (value === undefined)
+        return;
+    if (typeof value === "number" && !Number.isFinite(value)) {
+        throw new MemoryError("validation", `${at}: NaN/Infinity are not storable`);
+    }
+    if (Array.isArray(value)) {
+        for (let i = 0; i < value.length; i++)
+            assertJsonValue(value[i], `${at}[${i}]`);
+        return;
+    }
+    if (value !== null && typeof value === "object") {
+        for (const [k, v] of Object.entries(value)) {
+            assertJsonValue(v, `${at}.${k}`);
+        }
+        return;
+    }
+    if (typeof value !== "string" && typeof value !== "number" && typeof value !== "boolean" && value !== null) {
+        throw new MemoryError("validation", `${at}: unsupported value type`);
+    }
+}
+/** Redacted snapshot of an item for audit events — never Restricted plaintext. */
+function auditSnapshot(item) {
+    return {
+        memory_id: item.memory_id,
+        namespace: item.namespace,
+        key: item.key,
+        value: item.vault_ref !== undefined ? "[vault]" : item.value,
+        scope: item.scope,
+        source_kind: item.source_kind,
+        confidence: item.confidence,
+        sensitivity: item.sensitivity,
+        status: item.status,
+        version: item.version,
+    };
+}
+export class MemoryStore {
+    db;
+    vault;
+    now;
+    constructor(options) {
+        this.db = options.db;
+        this.vault = options.vault;
+        // Normalize to UTC ISO (lexicographic timestamp comparisons in SQLite).
+        const clock = options.now ?? (() => new Date().toISOString());
+        this.now = () => new Date(Date.parse(clock())).toISOString();
+    }
+    // ---- principals ---------------------------------------------------------
+    /** Create or return the principal. Role and owner are immutable — mismatch fails closed. */
+    ensurePrincipal(input) {
+        const existing = this.getPrincipal(input.principal_id);
+        const now = this.now();
+        if (existing !== undefined) {
+            if (existing.role !== input.role || existing.owner_id !== input.owner_id) {
+                throw new MemoryError("conflict", `principal ${input.principal_id} is bound to ${existing.role}/${existing.owner_id}; ` +
+                    `role and owner are immutable (physical isolation between agents)`);
+            }
+            return existing;
+        }
+        // One principal per agent database (design §17): a database that already
+        // belongs to another principal can never adopt a second identity.
+        const other = this.db.prepare("SELECT principal_id FROM principals LIMIT 1").get();
+        if (other !== undefined) {
+            throw new MemoryError("conflict", `this memory database belongs to ${other.principal_id}; ` +
+                `physical isolation between agents forbids binding ${input.principal_id}`);
+        }
+        this.db
+            .prepare(`INSERT INTO principals
+           (principal_id, owner_id, role, display_name, locale, timezone, memory_schema_version, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+            .run(input.principal_id, input.owner_id, input.role, input.display_name ?? null, input.locale ?? "zh-CN", input.timezone ?? "Asia/Shanghai", MEMORY_SCHEMA_VERSION, now, now);
+        return this.getPrincipal(input.principal_id);
+    }
+    getPrincipal(principalId) {
+        const row = this.db
+            .prepare("SELECT * FROM principals WHERE principal_id = ?")
+            .get(principalId);
+        if (row === undefined)
+            return undefined;
+        return {
+            principal_id: row.principal_id,
+            owner_id: row.owner_id,
+            role: row.role,
+            display_name: row.display_name ?? undefined,
+            locale: row.locale,
+            timezone: row.timezone,
+            memory_schema_version: row.memory_schema_version,
+            created_at: row.created_at,
+            updated_at: row.updated_at,
+        };
+    }
+    // ---- write path ---------------------------------------------------------
+    remember(input) {
+        // Precise personal data escalates to the Vault before validation, so a
+        // model mislabeling an address as `private`/`normal` is still sealed.
+        const effective = escalateSensitivity(input);
+        this.validateRemember(effective);
+        const now = this.now();
+        this.db.exec("BEGIN");
+        try {
+            const outcome = this.rememberTx(effective, now);
+            this.db.exec("COMMIT");
+            return outcome;
+        }
+        catch (err) {
+            this.db.exec("ROLLBACK");
+            if (err instanceof MemoryError || err instanceof VaultKeyError)
+                throw err;
+            throw new MemoryError("validation", err instanceof Error ? err.message : String(err));
+        }
+    }
+    validateRemember(input) {
+        if (!isMemoryNamespace(input.namespace)) {
+            throw new MemoryError("validation", `unknown namespace: ${String(input.namespace)}`);
+        }
+        if (typeof input.key !== "string" || input.key.length === 0 || input.key.length > 160) {
+            throw new MemoryError("validation", "key must be a non-empty string (<= 160 chars)");
+        }
+        if (!isMemorySourceKind(input.source_kind)) {
+            throw new MemoryError("validation", `unknown source_kind: ${String(input.source_kind)}`);
+        }
+        if (!isMemorySensitivity(input.sensitivity)) {
+            throw new MemoryError("validation", `unknown sensitivity: ${String(input.sensitivity)}`);
+        }
+        if ((input.value === undefined) === (input.restricted === undefined)) {
+            throw new MemoryError("validation", "exactly one of value / restricted must be provided (value_json and vault_ref are mutually exclusive)");
+        }
+        assertJsonValue(input.value, "value");
+        parseMemoryScope(input.scope);
+        if (input.namespace === "constraint" && input.source_kind !== "explicit") {
+            throw new MemoryError("validation", "hard constraints require an explicit source; inferred/observed signals can never become constraints");
+        }
+        if (input.sensitivity === "restricted") {
+            if (input.restricted === undefined) {
+                throw new MemoryError("validation", "restricted memories must carry a Vault plaintext");
+            }
+            if (!isVaultKind(input.restricted.kind)) {
+                throw new MemoryError("validation", `unknown vault kind: ${String(input.restricted.kind)}`);
+            }
+            if (input.source_kind !== "explicit") {
+                throw new MemoryError("validation", "Restricted memories require an explicit source (or a user-confirmed candidate)");
+            }
+            if (!input.explicit_user_statement) {
+                throw new MemoryError("validation", "Restricted memories require an explicit user statement");
+            }
+            if (!this.vault.available) {
+                throw new MemoryError("vault_unavailable", "no data key configured (KIWI_DATA_KEY); refusing Restricted write (fail closed)");
+            }
+        }
+        if (input.restricted !== undefined && input.sensitivity !== "restricted") {
+            throw new MemoryError("validation", "a Vault plaintext requires sensitivity=restricted");
+        }
+        if (input.expires_at !== undefined) {
+            if (Number.isNaN(Date.parse(input.expires_at))) {
+                throw new MemoryError("validation", "expires_at must be an RFC3339 timestamp");
+            }
+            // Normalize to UTC ISO: expireDue compares lexicographically against a
+            // UTC-Z now, so a "+08:00" input would otherwise silently never expire.
+            input.expires_at = new Date(Date.parse(input.expires_at)).toISOString();
+        }
+        if (input.confidence !== undefined && (input.confidence < 0 || input.confidence > 1)) {
+            throw new MemoryError("validation", "confidence must be in [0, 1]");
+        }
+    }
+    rememberTx(input, now) {
+        const principal = this.requirePrincipal();
+        const scope = parseMemoryScope(input.scope);
+        const existing = this.findLiveByKey(principal.principal_id, input.namespace, input.key, scope);
+        if (existing !== undefined) {
+            return this.mergeOrConflict(existing, input, scope, now);
+        }
+        // Constraint/restricted memories can never auto-activate from a model
+        // remember call — they stay candidate until the human /confirms them.
+        const explicitConfirmed = input.explicit_user_statement && !requiresHumanConfirm(input);
+        const status = explicitConfirmed ? "active" : "candidate";
+        const confidence = explicitConfirmed
+            ? 1.0
+            : (input.confidence ?? DEFAULT_CONFIDENCE[input.source_kind]);
+        const item = this.insertItem(principal.principal_id, input, scope, status, confidence, explicitConfirmed ? now : undefined, now);
+        this.addEvidenceTx(item.memory_id, { ...input.evidence, polarity: "support", summary: evidenceSummaryFor(input, input.evidence.summary) }, now, true);
+        this.appendEvent(item.memory_id, explicitConfirmed ? "memory.confirmed" : "memory.proposed", input.actor, undefined, { after: auditSnapshot({ ...item, evidence_count: 1 }) }, now);
+        return { kind: explicitConfirmed ? "active" : "candidate", memory: { ...item, evidence_count: 1 } };
+    }
+    /** Same live (namespace, key, scope): merge evidence or handle a value conflict. */
+    mergeOrConflict(existing, input, scope, now) {
+        const sameValue = existing.vault_ref === undefined &&
+            input.restricted === undefined &&
+            JSON.stringify(existing.value) === JSON.stringify(input.value);
+        if (sameValue) {
+            const added = this.addEvidenceTx(existing.memory_id, { ...input.evidence, polarity: "support", summary: evidenceSummaryFor(input, input.evidence.summary) }, now, true);
+            const updated = this.getMemory(existing.memory_id);
+            this.maybeAutoActivate(updated, now);
+            return { kind: "merged", memory: this.getMemory(existing.memory_id), evidence_added: added };
+        }
+        // Value conflict. A recent explicit user statement supersedes; anything
+        // weaker only appends contradict evidence — never a silent overwrite.
+        if (input.explicit_user_statement) {
+            this.db
+                .prepare("UPDATE memory_items SET status = 'superseded', updated_at = ? WHERE memory_id = ?")
+                .run(now, existing.memory_id);
+            this.appendEvent(existing.memory_id, "memory.superseded", input.actor, "replaced by a newer explicit statement", { before: auditSnapshot(existing), after: { status: "superseded" } }, now);
+            const humanConfirm = requiresHumanConfirm(input);
+            const item = this.insertItem(existing.principal_id, input, scope, humanConfirm ? "candidate" : "active", humanConfirm ? (input.confidence ?? DEFAULT_CONFIDENCE[input.source_kind]) : 1.0, humanConfirm ? undefined : now, now);
+            this.addEvidenceTx(item.memory_id, { ...input.evidence, polarity: "support", summary: evidenceSummaryFor(input, input.evidence.summary) }, now, true);
+            this.appendEvent(item.memory_id, humanConfirm ? "memory.proposed" : "memory.confirmed", input.actor, undefined, {
+                after: auditSnapshot({ ...item, evidence_count: 1 }),
+            }, now);
+            return { kind: humanConfirm ? "candidate" : "active", memory: { ...item, evidence_count: 1 } };
+        }
+        const added = this.addEvidenceTx(existing.memory_id, { ...input.evidence, polarity: "contradict", summary: evidenceSummaryFor(input, input.evidence.summary) }, now, false);
+        if (added) {
+            this.appendEvent(existing.memory_id, "memory.contradicted", input.actor, evidenceSummaryFor(input, input.evidence.summary), { before: auditSnapshot(existing) }, now);
+        }
+        return {
+            kind: "conflict",
+            existing: this.getMemory(existing.memory_id),
+            evidence_added: added,
+        };
+    }
+    insertItem(principalId, input, scope, status, confidence, confirmedAt, now) {
+        const memoryId = `mem_${uuidv7()}`;
+        let valueJson = null;
+        let vaultRef = null;
+        if (input.restricted !== undefined) {
+            vaultRef = this.sealVault(principalId, input.restricted.kind, input.restricted.plaintext, now);
+        }
+        else {
+            valueJson = JSON.stringify(input.value ?? null);
+        }
+        this.db
+            .prepare(`INSERT INTO memory_items
+           (memory_id, principal_id, namespace, key, value_json, vault_ref, scope_json,
+            source_kind, confidence, sensitivity, status, confirmed_at, valid_from, expires_at,
+            last_observed_at, evidence_count, version, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 0, 1, ?, ?)`)
+            .run(memoryId, principalId, input.namespace, input.key, valueJson, vaultRef, JSON.stringify(scope), input.source_kind, confidence, input.sensitivity, status, confirmedAt ?? null, now, input.expires_at ?? null, now, now, now);
+        return this.getMemory(memoryId);
+    }
+    sealVault(principalId, kind, plaintext, now) {
+        const fingerprint = this.vault.fingerprint(kind, plaintext);
+        const existing = this.db
+            .prepare("SELECT vault_ref FROM private_vault WHERE principal_id = ? AND kind = ? AND value_fingerprint = ?")
+            .get(principalId, kind, fingerprint);
+        if (existing !== undefined)
+            return existing.vault_ref;
+        const sealed = this.vault.seal(kind, plaintext);
+        const ref = `vr_${uuidv7()}`;
+        this.db
+            .prepare(`INSERT INTO private_vault
+           (vault_ref, principal_id, kind, ciphertext, nonce, key_version, value_fingerprint,
+            retention_json, created_at, updated_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, '{}', ?, ?)`)
+            .run(ref, principalId, kind, sealed.ciphertext, sealed.nonce, sealed.key_version, sealed.value_fingerprint, now, now);
+        return ref;
+    }
+    // ---- evidence -----------------------------------------------------------
+    /**
+     * Add evidence. Dedup (design §9.3): a repeat from the same source_ref
+     * never inflates evidence_count; only supporting, deduplicated evidence
+     * counts. Returns true when a new evidence row was inserted.
+     */
+    addEvidenceTx(memoryId, input, now, counts) {
+        const dup = this.db
+            .prepare("SELECT 1 AS x FROM memory_evidence WHERE memory_id = ? AND source_ref = ? LIMIT 1")
+            .get(memoryId, input.source_ref);
+        if (dup !== undefined)
+            return false;
+        const evidenceId = `ev_${uuidv7()}`;
+        this.db
+            .prepare(`INSERT INTO memory_evidence
+           (evidence_id, memory_id, source_type, source_ref, polarity, weight, summary, observed_at, created_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+            .run(evidenceId, memoryId, input.source_type, input.source_ref, input.polarity, Math.min(1, Math.max(0, input.weight ?? 1)), input.summary, input.observed_at ?? now, now);
+        if (counts && input.polarity === "support") {
+            this.db
+                .prepare(`UPDATE memory_items
+           SET evidence_count = (SELECT COUNT(DISTINCT source_ref) FROM memory_evidence
+                                   WHERE memory_id = ? AND polarity = 'support'),
+               last_observed_at = ?, updated_at = ?
+           WHERE memory_id = ?`)
+                .run(memoryId, now, now, memoryId);
+        }
+        return true;
+    }
+    /** >= 3 deduplicated signals activate a soft preference (design §10.1). */
+    maybeAutoActivate(item, now) {
+        if (item.status !== "candidate")
+            return;
+        if (!SOFT_ACTIVATABLE.has(item.namespace))
+            return;
+        if (item.source_kind !== "observed" && item.source_kind !== "inferred")
+            return;
+        if (item.sensitivity === "restricted")
+            return;
+        if (item.evidence_count < AUTO_ACTIVATE_EVIDENCE)
+            return;
+        const confidence = Math.min(0.9, Math.max(item.confidence, 0.5 + 0.1 * item.evidence_count));
+        this.db
+            .prepare("UPDATE memory_items SET status = 'active', confidence = ?, updated_at = ? WHERE memory_id = ?")
+            .run(confidence, now, item.memory_id);
+        this.appendEvent(item.memory_id, "memory.activated", "system", "evidence threshold reached", {
+            before: auditSnapshot(item),
+            after: { status: "active", confidence },
+        }, now);
+    }
+    /** Public evidence hook (task feedback, selections, rejections). */
+    addEvidence(memoryId, input) {
+        const now = this.now();
+        this.db.exec("BEGIN");
+        try {
+            const added = this.addEvidenceTx(memoryId, { ...input, polarity: input.polarity ?? "support" }, now, true);
+            if (added) {
+                const item = this.getMemory(memoryId);
+                if (item !== undefined)
+                    this.maybeAutoActivate(item, now);
+            }
+            this.db.exec("COMMIT");
+            return added;
+        }
+        catch (err) {
+            this.db.exec("ROLLBACK");
+            throw err;
+        }
+    }
+    // ---- user governance ----------------------------------------------------
+    /** User confirms a candidate (design: Restricted candidates become valid only here). */
+    confirmMemory(memoryId, actor) {
+        const now = this.now();
+        const item = this.requireMemory(memoryId);
+        if (item.status !== "candidate" && item.status !== "needs_review") {
+            throw new MemoryError("conflict", `memory ${memoryId} is ${item.status}, not confirmable`);
+        }
+        const confidence = item.source_kind === "explicit" ? 1.0 : Math.max(item.confidence, 0.9);
+        this.db.exec("BEGIN");
+        try {
+            this.db
+                .prepare(`UPDATE memory_items
+           SET status = 'active', confirmed_at = ?, confidence = ?, source_kind = 'explicit', updated_at = ?
+           WHERE memory_id = ?`)
+                .run(now, confidence, now, memoryId);
+            this.appendEvent(memoryId, "memory.confirmed", actor, undefined, {
+                before: auditSnapshot(item),
+                after: { status: "active", confidence },
+            }, now);
+            this.db.exec("COMMIT");
+        }
+        catch (err) {
+            this.db.exec("ROLLBACK");
+            throw err;
+        }
+        return this.getMemory(memoryId);
+    }
+    /**
+     * User correction (design §6.4 /correct): updates in place with a version
+     * bump and a before/after audit event. A correction IS an explicit user
+     * statement: source becomes explicit, confidence 1.0, confirmed.
+     * Restricted items keep their Vault value unless a new plaintext is given;
+     * sensitivity downgrades from restricted are refused.
+     */
+    correctMemory(memoryId, patch, actor, reason) {
+        const item = this.requireMemory(memoryId);
+        if (item.status === "deleted" || item.status === "superseded" || item.status === "expired") {
+            throw new MemoryError("conflict", `memory ${memoryId} is ${item.status}; cannot correct`);
+        }
+        const now = this.now();
+        this.db.exec("BEGIN");
+        try {
+            let valueJson;
+            let vaultRef;
+            if (patch.restricted !== undefined) {
+                if (item.sensitivity !== "restricted") {
+                    throw new MemoryError("validation", "cannot move a non-restricted memory into the Vault; forget it and remember again");
+                }
+                if (!this.vault.available) {
+                    throw new MemoryError("vault_unavailable", "no data key configured (KIWI_DATA_KEY)");
+                }
+                vaultRef = this.sealVault(item.principal_id, patch.restricted.kind, patch.restricted.plaintext, now);
+                valueJson = null;
+            }
+            else if (patch.value !== undefined) {
+                if (item.sensitivity === "restricted") {
+                    throw new MemoryError("validation", "cannot move a Restricted value out of the Vault; forget it and remember again");
+                }
+                assertJsonValue(patch.value, "value");
+                valueJson = JSON.stringify(patch.value);
+                vaultRef = null;
+            }
+            const scopeJson = patch.scope !== undefined ? JSON.stringify(parseMemoryScope(patch.scope)) : undefined;
+            this.db
+                .prepare(`UPDATE memory_items
+           SET value_json = COALESCE(?, value_json),
+               vault_ref = COALESCE(?, vault_ref),
+               scope_json = COALESCE(?, scope_json),
+               source_kind = 'explicit', confidence = 1.0, confirmed_at = ?,
+               status = CASE WHEN status = 'candidate' THEN 'active' ELSE status END,
+               version = version + 1, updated_at = ?
+           WHERE memory_id = ?`)
+                .run(valueJson === undefined ? null : valueJson, vaultRef === undefined ? null : vaultRef, scopeJson === undefined ? null : scopeJson, now, now, memoryId);
+            const updated = this.getMemory(memoryId);
+            this.appendEvent(memoryId, "memory.corrected", actor, reason, {
+                before: auditSnapshot(item),
+                after: auditSnapshot(updated),
+            }, now);
+            this.db.exec("COMMIT");
+            return updated;
+        }
+        catch (err) {
+            this.db.exec("ROLLBACK");
+            if (err instanceof MemoryError || err instanceof VaultKeyError)
+                throw err;
+            throw new MemoryError("validation", err instanceof Error ? err.message : String(err));
+        }
+    }
+    /**
+     * Forget (tombstone + audit; design §9.2). The Vault ciphertext of a
+     * Restricted memory is hard-deleted; retrieval never returns the item.
+     */
+    forgetMemory(memoryId, actor, reason) {
+        const item = this.requireMemory(memoryId);
+        if (item.status === "deleted")
+            return item;
+        const now = this.now();
+        this.db.exec("BEGIN");
+        try {
+            this.db
+                .prepare("UPDATE memory_items SET status = 'deleted', updated_at = ? WHERE memory_id = ?")
+                .run(now, memoryId);
+            // Vault rows are fingerprint-deduped and can be shared by several memory
+            // items (design §9.5). Only erase the ciphertext when no OTHER live item
+            // still references it — otherwise /forget of one would silently destroy
+            // the other's private value.
+            if (item.vault_ref !== undefined) {
+                const stillReferenced = this.db
+                    .prepare("SELECT COUNT(*) AS c FROM memory_items WHERE vault_ref = ? AND memory_id != ? AND status != 'deleted'")
+                    .get(item.vault_ref, memoryId);
+                if (stillReferenced.c === 0) {
+                    this.db.prepare("DELETE FROM private_vault WHERE vault_ref = ?").run(item.vault_ref);
+                }
+            }
+            this.appendEvent(memoryId, "memory.forgotten", actor, reason, {
+                before: auditSnapshot(item),
+                after: { status: "deleted", vault: item.vault_ref !== undefined ? "erased" : undefined },
+            }, now);
+            this.db.exec("COMMIT");
+        }
+        catch (err) {
+            this.db.exec("ROLLBACK");
+            throw err;
+        }
+        return this.getMemory(memoryId);
+    }
+    /** Expire due items (task_context after its task, dated memories at expires_at). */
+    expireDue() {
+        const now = this.now();
+        const due = this.db
+            .prepare(`SELECT memory_id FROM memory_items
+         WHERE status IN ('candidate','active','needs_review') AND expires_at IS NOT NULL AND expires_at < ?`)
+            .all(now);
+        this.db.exec("BEGIN");
+        try {
+            for (const { memory_id: dueId } of due) {
+                const item = this.getMemory(dueId);
+                this.db
+                    .prepare("UPDATE memory_items SET status = 'expired', updated_at = ? WHERE memory_id = ?")
+                    .run(now, dueId);
+                this.appendEvent(dueId, "memory.expired", "system", `expired at ${item.expires_at ?? ""}`, {
+                    before: auditSnapshot(item),
+                    after: { status: "expired" },
+                }, now);
+            }
+            this.db.exec("COMMIT");
+        }
+        catch (err) {
+            this.db.exec("ROLLBACK");
+            throw err;
+        }
+        return due.length;
+    }
+    // ---- retrieval ----------------------------------------------------------
+    retrieve(query) {
+        if (!isRetrievalPurpose(query.purpose)) {
+            throw new MemoryError("validation", `unknown retrieval purpose: ${String(query.purpose)}`);
+        }
+        const principal = this.requirePrincipal();
+        this.expireDue();
+        const now = this.now();
+        const limit = Math.min(MAX_LIMIT, Math.max(1, query.limit ?? 8));
+        const rows = this.db
+            .prepare(`SELECT * FROM memory_items
+         WHERE principal_id = ? AND status IN ('active','needs_review')`)
+            .all(principal.principal_id);
+        const queryTokens = tokenize(query.text);
+        const scored = [];
+        for (const row of rows) {
+            const item = this.rowToItem(row);
+            if (query.namespaces !== undefined && !query.namespaces.includes(item.namespace))
+                continue;
+            if (item.namespace === "task_context") {
+                if (query.task_id === undefined || item.scope.task_id !== query.task_id)
+                    continue;
+            }
+            const scopeMatch = scopeScore(item.scope, query.scopes);
+            if (scopeMatch === 0)
+                continue;
+            const relevance = relevanceScore(item, queryTokens);
+            const freshness = freshnessScore(item, now);
+            const penalty = item.status === "needs_review" ? 0.5 : 1;
+            const score = relevance *
+                scopeMatch *
+                item.confidence *
+                freshness *
+                SOURCE_WEIGHT[item.source_kind] *
+                penalty;
+            scored.push({
+                memory_id: item.memory_id,
+                namespace: item.namespace,
+                key: item.key,
+                ...(item.vault_ref === undefined ? { value: item.value } : {}),
+                scope: item.scope,
+                source_kind: item.source_kind,
+                confidence: item.confidence,
+                sensitivity: item.sensitivity,
+                status: item.status,
+                redaction_level: redactionLevel(item.sensitivity),
+                score,
+                ...(item.last_observed_at !== undefined
+                    ? { last_observed_at: item.last_observed_at }
+                    : {}),
+            });
+        }
+        scored.sort((a, b) => b.score - a.score || a.memory_id.localeCompare(b.memory_id));
+        const picked = scored.slice(0, limit);
+        for (const item of picked) {
+            this.db
+                .prepare(`INSERT INTO memory_retrieval_log
+             (retrieval_id, task_id, session_id, memory_id, purpose, redaction_level, created_at)
+           VALUES (?, ?, ?, ?, ?, ?, ?)`)
+                .run(`ret_${uuidv7()}`, query.task_id ?? null, query.session_id, item.memory_id, query.purpose, item.redaction_level, now);
+        }
+        return picked;
+    }
+    /** Data behind /why: the most recent retrieval batch for a session. */
+    explainLastRetrieval(sessionId) {
+        const last = this.db
+            .prepare("SELECT created_at FROM memory_retrieval_log WHERE session_id = ? ORDER BY created_at DESC LIMIT 1")
+            .get(sessionId);
+        if (last === undefined)
+            return { entries: [] };
+        const rows = this.db
+            .prepare(`SELECT l.*, i.key AS key, i.namespace AS namespace, i.confidence AS confidence
+         FROM memory_retrieval_log l JOIN memory_items i ON i.memory_id = l.memory_id
+         WHERE l.session_id = ? AND l.created_at = ?
+         ORDER BY l.memory_id`)
+            .all(sessionId, last.created_at);
+        return {
+            entries: rows.map((r) => ({
+                retrieval_id: r.retrieval_id,
+                task_id: r.task_id ?? undefined,
+                session_id: r.session_id,
+                memory_id: r.memory_id,
+                purpose: r.purpose,
+                redaction_level: r.redaction_level,
+                created_at: r.created_at,
+                key: r.key,
+                namespace: r.namespace,
+                confidence: r.confidence,
+            })),
+        };
+    }
+    retrievalLog(sessionId) {
+        const rows = this.db
+            .prepare("SELECT * FROM memory_retrieval_log WHERE session_id = ? ORDER BY created_at, memory_id")
+            .all(sessionId);
+        return rows.map((r) => ({
+            retrieval_id: r.retrieval_id,
+            task_id: r.task_id ?? undefined,
+            session_id: r.session_id,
+            memory_id: r.memory_id,
+            purpose: r.purpose,
+            redaction_level: r.redaction_level,
+            created_at: r.created_at,
+        }));
+    }
+    // ---- reads / listings ---------------------------------------------------
+    getMemory(memoryId) {
+        const row = this.db
+            .prepare("SELECT * FROM memory_items WHERE memory_id = ?")
+            .get(memoryId);
+        return row === undefined ? undefined : this.rowToItem(row);
+    }
+    /** /memory overview. Restricted items are listed without any value. */
+    listMemories(filter) {
+        const principal = this.requirePrincipal();
+        const statuses = filter.statuses ?? ["candidate", "active", "needs_review"];
+        const rows = this.db
+            .prepare(`SELECT * FROM memory_items
+         WHERE principal_id = ?
+           AND (${statuses.map(() => "status = ?").join(" OR ")})
+           AND (? IS NULL OR namespace = ?)
+           AND (? IS NULL OR sensitivity = ?)
+         ORDER BY namespace, key`)
+            .all(principal.principal_id, ...statuses, filter.namespace ?? null, filter.namespace ?? null, filter.sensitivity ?? null, filter.sensitivity ?? null);
+        return rows.map((r) => this.rowToItem(r));
+    }
+    memoryEvents(memoryId) {
+        const rows = this.db
+            .prepare("SELECT * FROM memory_events WHERE memory_id = ? ORDER BY created_at, event_id")
+            .all(memoryId);
+        return rows.map((r) => ({
+            event_id: r.event_id,
+            memory_id: r.memory_id,
+            type: r.type,
+            actor: r.actor,
+            reason: r.reason ?? undefined,
+            before_json: r.before_json === null ? undefined : JSON.parse(r.before_json),
+            after_json: r.after_json === null ? undefined : JSON.parse(r.after_json),
+            created_at: r.created_at,
+        }));
+    }
+    /** Vault metadata for /memory private — never ciphertext, never plaintext. */
+    vaultEntries() {
+        const principal = this.requirePrincipal();
+        const rows = this.db
+            .prepare("SELECT vault_ref, kind, created_at FROM private_vault WHERE principal_id = ? ORDER BY created_at")
+            .all(principal.principal_id);
+        return rows.map((r) => ({
+            vault_ref: r.vault_ref,
+            kind: r.kind,
+            created_at: r.created_at,
+        }));
+    }
+    /** Open a Vault value (owner-side use only; never exposed to the model). */
+    openVaultValue(vaultRef) {
+        const principal = this.requirePrincipal();
+        const row = this.db
+            .prepare("SELECT * FROM private_vault WHERE vault_ref = ? AND principal_id = ?")
+            .get(vaultRef, principal.principal_id);
+        if (row === undefined) {
+            throw new MemoryError("not_found", `no vault entry ${vaultRef}`);
+        }
+        return this.vault.open(row.key_version, row.nonce, row.ciphertext);
+    }
+    // ---- internals ----------------------------------------------------------
+    principalId;
+    /** Bind the store to one principal (set by the kernel after ensurePrincipal). */
+    bindPrincipal(principalId) {
+        this.principalId = principalId;
+    }
+    requirePrincipal() {
+        if (this.principalId === undefined) {
+            throw new MemoryError("validation", "MemoryStore is not bound to a principal");
+        }
+        const principal = this.getPrincipal(this.principalId);
+        if (principal === undefined) {
+            throw new MemoryError("not_found", `principal ${this.principalId} does not exist`);
+        }
+        return principal;
+    }
+    requireMemory(memoryId) {
+        const item = this.getMemory(memoryId);
+        if (item === undefined) {
+            throw new MemoryError("not_found", `no memory ${memoryId}`);
+        }
+        return item;
+    }
+    findLiveByKey(principalId, namespace, key, scope) {
+        const row = this.db
+            .prepare(`SELECT * FROM memory_items
+         WHERE principal_id = ? AND namespace = ? AND key = ? AND scope_json = ?
+           AND status IN ('candidate','active','needs_review')
+         ORDER BY created_at DESC LIMIT 1`)
+            .get(principalId, namespace, key, JSON.stringify(scope));
+        return row === undefined ? undefined : this.rowToItem(row);
+    }
+    rowToItem(row) {
+        const item = {
+            memory_id: row.memory_id,
+            principal_id: row.principal_id,
+            namespace: row.namespace,
+            key: row.key,
+            scope: JSON.parse(row.scope_json),
+            source_kind: row.source_kind,
+            confidence: row.confidence,
+            sensitivity: row.sensitivity,
+            status: row.status,
+            evidence_count: row.evidence_count,
+            version: row.version,
+            created_at: row.created_at,
+            updated_at: row.updated_at,
+        };
+        if (row.value_json !== null)
+            item.value = JSON.parse(row.value_json);
+        if (row.vault_ref !== null)
+            item.vault_ref = row.vault_ref;
+        const confirmed = optText(row.confirmed_at);
+        if (confirmed !== undefined)
+            item.confirmed_at = confirmed;
+        const validFrom = optText(row.valid_from);
+        if (validFrom !== undefined)
+            item.valid_from = validFrom;
+        const expires = optText(row.expires_at);
+        if (expires !== undefined)
+            item.expires_at = expires;
+        const observed = optText(row.last_observed_at);
+        if (observed !== undefined)
+            item.last_observed_at = observed;
+        return item;
+    }
+    appendEvent(memoryId, type, actor, reason, snapshots, now) {
+        for (const [label, snap] of [
+            ["before", snapshots.before],
+            ["after", snapshots.after],
+        ]) {
+            if (snap !== undefined)
+                assertJsonValue(snap, `memory_event.${label}`);
+        }
+        this.db
+            .prepare(`INSERT INTO memory_events
+           (event_id, memory_id, type, actor, reason, before_json, after_json, created_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?)`)
+            .run(`mev_${uuidv7()}`, memoryId, type, actor, reason ?? null, snapshots.before === undefined ? null : JSON.stringify(snapshots.before), snapshots.after === undefined ? null : JSON.stringify(snapshots.after), now);
+    }
+}
+function redactionLevel(sensitivity) {
+    return sensitivity === "restricted" ? "metadata_only" : sensitivity === "private" ? "coarse" : "full";
+}
+/** Deterministic tokenizer for relevance matching (CJK bigrams + word tokens). */
+function tokenize(text) {
+    if (text === undefined || text.trim() === "")
+        return [];
+    const lower = text.toLowerCase();
+    const words = lower.match(/[a-z0-9_]{2,}/g) ?? [];
+    const cjk = lower.match(/[一-鿿]/g) ?? [];
+    const bigrams = [];
+    for (let i = 0; i + 1 < cjk.length; i++)
+        bigrams.push(`${cjk[i]}${cjk[i + 1]}`);
+    return [...new Set([...words, ...bigrams])];
+}
+function relevanceScore(item, queryTokens) {
+    if (queryTokens.length === 0)
+        return 1;
+    const haystack = `${item.key} ${JSON.stringify(item.value ?? "")}`.toLowerCase();
+    let hits = 0;
+    for (const token of queryTokens) {
+        if (haystack.includes(token))
+            hits += 1;
+    }
+    return Math.min(1, Math.max(0.1, hits / queryTokens.length + (hits > 0 ? 0.2 : 0)));
+}
+function scopeScore(scope, queryScopes) {
+    const entries = Object.entries(scope).filter(([, v]) => v !== undefined);
+    if (entries.length === 0)
+        return 1.0; // global memory
+    if (queryScopes === undefined || queryScopes.length === 0)
+        return 0.6; // scoped memory, global query
+    let matched = false;
+    for (const [dimension, value] of entries) {
+        for (const qs of queryScopes) {
+            const qv = qs[dimension];
+            if (qv === undefined)
+                continue;
+            if (qv === value)
+                matched = true;
+            else
+                return 0.4; // explicit contradiction on a shared dimension
+        }
+    }
+    return matched ? 1.2 : 0.6;
+}
+function freshnessScore(item, now) {
+    if (item.last_observed_at === undefined)
+        return 1;
+    const ageMs = Date.parse(now) - Date.parse(item.last_observed_at);
+    const ageDays = Math.max(0, ageMs / 86_400_000);
+    return 0.5 + 0.5 * Math.exp(-ageDays / 90);
+}
+//# sourceMappingURL=store.js.map