@lmzhen/dsh-evolution-core 0.26.26 → 0.27.1

package/lib/types/memory-store.js

@@ -0,0 +1,606 @@
+/**
+ * File-backed durable memory with Hermes-compatible semantics.
+ * Stores are MEMORY.md and USER.md under $DSH_HOME/memories (~/.dsh/memories).
+ */
+import { basename, join } from 'node:path';
+import { nodeEvolutionIo, transactIo } from "./io.js";
+import { evolutionRoot } from "./state-store.js";
+import { makeSerialQueue } from "./serial.js";
+import { payloadText } from "./payload.js";
+import { scanMemoryThreats } from "./threats.js";
+import { ENTRY_DELIMITER, DEFAULT_MEMORY_CHAR_LIMIT, DEFAULT_USER_CHAR_LIMIT, DEFAULT_CONSOLIDATION_FAILURES } from "./constants.js";
+export { ENTRY_DELIMITER } from "./constants.js";
+/**
+ * Read-guard factor: a memory file larger than this multiple of its target's
+ * char limit is treated as externally corrupted and skipped instead of being
+ * read whole (aligned with claw `tools/memory.ts` size guard, which uses the
+ * same 10× bound around a file that should never exceed the store limit).
+ */
+const READ_GUARD_FACTOR = 10;
+/**
+ * Consolidation-failure backoff window (package-private, rc.42 audit P2-1):
+ * only failures inside the window count toward `maxConsolidationFailures`.
+ * The store cannot observe turn boundaries, so the model-facing "this turn"
+ * phrasing is approximated with ten minutes — generous enough to cover one
+ * turn's retry loop, short enough that a failure yesterday never makes today's
+ * first refusal say "stop retrying".
+ */
+const FAILURE_WINDOW_MS = 10 * 60_000;
+/**
+ * Recoverable-error preview bounds (B-line G5, Hermes `_previews` parity):
+ * failed replace/remove/batch calls echo the current entries so the model can
+ * self-recover without re-reading the store. Bounded to five entries of eighty
+ * characters each; package-private because it is an error-message shape, not a
+ * behavior switch.
+ */
+const ERROR_PREVIEW_ENTRIES = 5;
+const ERROR_PREVIEW_WIDTH = 80;
+function previewEntries(entries) {
+    if (entries.length === 0)
+        return '';
+    const shown = entries.slice(0, ERROR_PREVIEW_ENTRIES).map((entry) => {
+        const text = entry.length > ERROR_PREVIEW_WIDTH ? `${entry.slice(0, ERROR_PREVIEW_WIDTH)}…` : entry;
+        return `- ${text}`;
+    });
+    const more = entries.length > ERROR_PREVIEW_ENTRIES ? `\n  (+${entries.length - ERROR_PREVIEW_ENTRIES} more)` : '';
+    return `\n\nCurrent entries (preview):\n${shown.join('\n')}${more}`;
+}
+export function memoryRoot(env = process.env) {
+    // V9-05 (0.3.51): single resolver — evolutionRoot() holds the ONLY
+    // DSH_HOME empty/whitespace fallback; the old bare `||` here resolved
+    // `DSH_HOME=" "` to a CWD-relative " /memories" sidecar.
+    return join(evolutionRoot(env), 'memories');
+}
+function fileFor(root, target) {
+    return join(root, target === 'memory' ? 'MEMORY.md' : 'USER.md');
+}
+function normalizeEntries(raw) {
+    return raw.split(ENTRY_DELIMITER).map(entry => entry.trim()).filter(Boolean);
+}
+function render(entries) {
+    return entries.join(ENTRY_DELIMITER) + '\n';
+}
+function stripDatePrefix(entry) {
+    return entry.replace(/^## \d{4}-\d{2}-\d{2}\n/, '');
+}
+/** F-201: does `content` carry the on-disk entry delimiter or a trailing
+ * `\n§` fragment that would combine with the render terminator into a real
+ * delimiter boundary? Both split the fact into multiple entries on read-back
+ * (and a delimiter-ending fact is permanent drift — `render(entries)!==raw`
+ * bricks every later write). A leading/plain `§` is safe and round-trips. */
+function hasEntryDelimiter(content) {
+    return content.includes(ENTRY_DELIMITER) || content.endsWith('\n§');
+}
+export class MemoryStore {
+    memoryLimit;
+    userLimit;
+    addDatePrefix;
+    root;
+    maxFailures;
+    io;
+    /** V10-03 (P2-18): see MemoryStoreOptions.threatExemptLabels. */
+    threatExemptLabels;
+    /** V6-16 (0.3.37): same-process RMW serialization (the SkillLibrary queue) —
+     * on a backend WITHOUT a transact lock two concurrent callers compute on the
+     * same old content and the last rename wins, silently dropping one op's
+     * update. The node backend's cross-process lock already serializes; this
+     * chain covers the no-transact custom backends. */
+    serial = makeSerialQueue();
+    failureCount = 0;
+    lastFailureAt = 0;
+    constructor(options = {}) {
+        this.io = options.io ?? nodeEvolutionIo();
+        this.memoryLimit = options.memoryCharLimit ?? DEFAULT_MEMORY_CHAR_LIMIT;
+        this.userLimit = options.userCharLimit ?? DEFAULT_USER_CHAR_LIMIT;
+        this.addDatePrefix = options.addDatePrefix ?? false;
+        this.root = options.root ?? memoryRoot();
+        this.maxFailures = options.maxConsolidationFailures ?? DEFAULT_CONSOLIDATION_FAILURES;
+        this.threatExemptLabels = options.threatExemptLabels ?? [];
+    }
+    /** V10-03 (P2-18): ScanOptions shared by every threat check of this store —
+     * the constructor's exempt labels, empty by default (behavior unchanged). */
+    threatScanOptions() {
+        return this.threatExemptLabels.length > 0 ? { excludeLabels: this.threatExemptLabels } : {};
+    }
+    /** V10-03 (P2-18): the strict-scan write gate. A block message names the hit
+     * label (scanMemoryThreats already embeds it) plus the self-heal hint. */
+    memoryThreatBlock(text) {
+        // A2-16 (v18): scanMemoryThreats already appends its exemption hint;
+        // a store-side append duplicated the sentence (the old THREAT_EXEMPT_HINT
+        // export was removed in v21 — see threats.ts THREAT_EXEMPTION_HINT).
+        return scanMemoryThreats(text, undefined, this.threatScanOptions());
+    }
+    limitFor(target) {
+        return target === 'memory' ? this.memoryLimit : this.userLimit;
+    }
+    /** P2-1 (v18): the generated date prefix participates in duplicate detection
+     * only when THIS store writes it. With addDatePrefix=false a fact's own
+     * leading `## YYYY-MM-DD\n` is content, not a generated prefix. */
+    dedupeKey(entry) {
+        return this.addDatePrefix ? stripDatePrefix(entry) : entry;
+    }
+    /**
+     * Read-guard probe: `{ size, limit }` when the on-disk file exceeds
+     * `limit * READ_GUARD_FACTOR` bytes, `null` when it is absent, unknown
+     * (backend without a size probe), under the bound, or the target has no
+     * limit configured.
+     */
+    async oversizedFile(target) {
+        const size = await this.io.size?.(fileFor(this.root, target));
+        if (size === null || size === undefined)
+            return null;
+        const limit = this.limitFor(target);
+        if (limit <= 0)
+            return null;
+        return size > limit * READ_GUARD_FACTOR ? { size, limit } : null;
+    }
+    async read(target) {
+        // Oversized files are skipped whole (claw alignment); a later write to the
+        // same target is refused via `oversizedRefusal` instead of overwriting.
+        if (await this.oversizedFile(target))
+            return [];
+        const raw = await this.io.readText(fileFor(this.root, target));
+        return raw === null ? [] : [...new Set(normalizeEntries(raw))];
+    }
+    // 0.3.16 (S1.10, D-2): `write()` was a bare public write path bypassing
+    // transact/threat-scan/drift checks, with ZERO callers in the family —
+    // removed. Memory mutations go through `applyBatch` only.
+    resetFailures() {
+        this.failureCount = 0;
+    }
+    failure(target, message, entries) {
+        // Rolling-window decay (rc.42 audit P2-1): the backoff counter used to be
+        // process-lifetime, so three failures EVER — across turns and sessions —
+        // made every later failure say "stop retrying" even though the model had
+        // moved on. The store cannot see turn boundaries, so "this turn" is
+        // approximated with a window: failures older than it stop counting and
+        // the counter restarts from one.
+        if (Date.now() - this.lastFailureAt > FAILURE_WINDOW_MS)
+            this.failureCount = 0;
+        this.lastFailureAt = Date.now();
+        this.failureCount += 1;
+        const chars = entries.join(ENTRY_DELIMITER).length;
+        if (this.failureCount > this.maxFailures) {
+            return {
+                ok: false,
+                message: `本轮记忆整理已失败 ${this.failureCount} 次。请停止重试记忆调用，继续处理用户的任务。${previewEntries(entries)}`,
+                entries, chars, limit: this.limitFor(target),
+            };
+        }
+        return { ok: false, message: `${message}${previewEntries(entries)}`, entries, chars, limit: this.limitFor(target) };
+    }
+    /**
+     * StorageHint percentage must clamp at 100 like the render header: a drifted
+     * entry can push chars past the limit, and "Storage at 125%" contradicts the
+     * clamped usage indicator.
+     */
+    storageHint(target, chars) {
+        const limit = this.limitFor(target);
+        if (limit <= 0)
+            return '';
+        const percent = Math.min(100, Math.floor((chars * 100) / limit));
+        return percent >= 80 ? ` ⚠️ Storage at ${percent}% (${chars}/${limit} chars).` : '';
+    }
+    /**
+     * Best-effort raw-copy backup of the on-disk file to `<file>.bak` before a
+     * refusal, so an externally modified (or oversized) file stays recoverable.
+     * Copies bytes instead of reading them so a pathologically large file is
+     * never loaded just to back it up. Failure to back up does not change the
+     * refusal semantics. V8-23⑫ (0.3.49): ONE fixed backup name per target —
+     * a fresh refusal overwrites it (the previous timestamped names accumulated
+     * per drift incident with no retention policy). V9-08 (0.3.51) declares the
+     * two failure shapes: (1) the pre-copy remove of the previous `.bak` fails —
+     * harmless, because the copy contract is overwrite (`cp force`);
+     * (2) the copy itself fails (disk/backend) — returns `null` and the refusal
+     * message simply carries no backup suffix; the refusal semantics and the
+     * on-disk file are untouched either way.
+     */
+    async backupFile(target) {
+        const path = fileFor(this.root, target);
+        const backup = `${path}.bak`;
+        // P3-13 (v14): stage the copy under a transient name and only then replace
+        // the fixed `.bak`, so a FAILED copy leaves the previous backup intact —
+        // the old shape removed `.bak` first and lost the last good generation.
+        const staging = `${backup}.${process.pid}.${Date.now().toString(36)}.tmp`;
+        try {
+            await this.io.remove(staging).catch(() => { });
+            await this.io.copy(path, staging);
+            await this.io.rename(staging, backup);
+            return backup;
+        }
+        catch {
+            await this.io.remove(staging).catch(() => { });
+            return null;
+        }
+    }
+    /**
+     * Read-guard refusal for write paths. Returns the refusal result when the
+     * target file is oversized, `null` otherwise. The file is skipped for
+     * reading (never loaded), backed up by raw copy, and the model is told to
+     * fix it manually — mirroring the drift refusal so corrupted state is never
+     * silently overwritten.
+     */
+    async oversizedRefusal(target) {
+        const oversized = await this.oversizedFile(target);
+        if (!oversized)
+            return null;
+        const backup = await this.backupFile(target);
+        const suffix = backup ? ` 已把备份保存到 ${basename(backup)}。` : '';
+        return {
+            ok: false,
+            message: `记忆文件为 ${oversized.size} 字节（上限 ${oversized.limit * READ_GUARD_FACTOR}）—— 跳过读取。${suffix} 请手动修复该文件后重试。`,
+            entries: [], chars: 0, limit: this.limitFor(target),
+        };
+    }
+    /**
+     * The ONE memory write skeleton (V27 G2.5): oversized read-guard pre-transact,
+     * one transaction over the target path, and the C-01 structured refusal when a
+     * backend never invokes the task. `addChained` and `applyBatchChained` supply
+     * only their own in-transaction core, so the two write paths cannot drift in
+     * their guard order, their missing-file handling or their error text.
+     *
+     * @param target - memory target being written
+     * @param core - the in-transaction read-modify-write for the locked body
+     * @param shrinkOnly - v29 MEM-02: every queued operation REMOVES an entry
+     *   (the recovery path for a limit lowered under existing content). The
+     *   oversized read-guard is skipped for these batches: a canonical file
+     *   written under a ≥10× higher limit trips the `limit × 10` byte bound, and
+     *   the guard's "fix the file manually" refusal would pre-empt exactly the
+     *   shrink recovery MEM-01 advertises. The load is bounded by what the store
+     *   itself wrote under the old limit.
+     * @returns the core's result, or the oversized / contract-violation refusal
+     */
+    async chainedWrite(target, core, shrinkOnly = false) {
+        // M-7 (v3 audit): the oversized read-guard must run BEFORE the transact —
+        // inside it, node transact has already loaded the whole file, so the
+        // "skipped for reading (never loaded)" contract only holds pre-lock.
+        // v33 R2-1: the shrinkOnly bypass keeps a hard ceiling - a pathological
+        // (externally corrupted) file must not be loaded whole just because the
+        // batch is remove-only.
+        const SHRINK_LOAD_CEILING = 64 * 1024 * 1024;
+        if (!shrinkOnly) {
+            const refusal = await this.oversizedRefusal(target);
+            if (refusal)
+                return refusal;
+        }
+        else {
+            const size = await this.io.size?.(fileFor(this.root, target));
+            if (typeof size === 'number' && size > SHRINK_LOAD_CEILING) {
+                return {
+                    ok: false,
+                    message: `记忆文件为 ${size} 字节 —— 即使只做删除批处理也过大、无法加载。请手动修复该文件后重试。`,
+                    entries: [], chars: 0, limit: this.limitFor(target),
+                };
+            }
+        }
+        let outcome;
+        await transactIo(this.io, fileFor(this.root, target), async (current) => {
+            const step = await core(current ?? '');
+            outcome = step.result;
+            // M-4 (v3 audit): a failure on a MISSING file must keep it missing —
+            // returning '' would fabricate an empty file. `null` (DELETE) is safe
+            // here: the file does not exist, so the remove is a no-op.
+            return step.write ?? (current ?? null);
+        });
+        // C-01: a transact backend that violates the contract (never invokes the
+        // task) leaves `outcome` undefined — the old `undefined as
+        // MemoryApplyResult` cast handed callers an object whose `.ok` dereference
+        // raised a raw TypeError. Structured refusal instead, mirroring
+        // skill-store's V6-19 guard.
+        return outcome ?? {
+            ok: false,
+            message: '内部错误：记忆写事务没有调用任务；未执行任何写入',
+            entries: [], chars: 0, limit: this.limitFor(target),
+        };
+    }
+    async add(target, facts) {
+        return await this.serial(() => this.addChained(target, facts));
+    }
+    async addChained(target, facts) {
+        if (!facts.trim())
+            return { ok: false, message: '内容不能为空。', entries: [], chars: 0, limit: this.limitFor(target) };
+        return await this.chainedWrite(target, async (raw) => await this.addCore(target, facts, raw));
+    }
+    /**
+     * Single-entry add inside the transaction: shared checks (oversized,
+     * drift, threat) and the content computation. `raw` is the locked view
+     * (`current`) — never a second IO read. `write: null` means "no change".
+     */
+    async addCore(target, facts, raw) {
+        const content = facts.trim();
+        // P3 (v15): structured rejection, NOT `this.failure()` — failure() feeds
+        // the consolidation-failure backoff counter, and an empty-facts validation
+        // error is not a write failure (same discipline as applyBatchCore's
+        // inline empty-facts rejection). Unreachable via the public entries
+        // (addChained pre-trims), kept as a defence against future callers.
+        if (!content)
+            return { result: { ok: false, message: '内容不能为空。', entries: [], chars: 0, limit: this.limitFor(target) }, write: null };
+        // The oversized guard runs pre-transact in add(); drift is derived from
+        // the locked view below.
+        const refusal = await this.driftRefusal(target, raw);
+        if (refusal)
+            return { result: refusal, write: null };
+        const threat = this.memoryThreatBlock(content);
+        if (threat)
+            return { result: { ok: false, message: threat, entries: [], chars: 0, limit: this.limitFor(target) }, write: null };
+        // V8-02 (0.3.47): the delimiter guard must inspect the FINAL on-disk entry
+        // — with addDatePrefix the prefix+content seam can SYNTHESIZE `\n§\n`
+        // (`§\nfoo` passes the pre-prefix check but becomes `## date\n§\nfoo`).
+        // C-03: the prefix is computed ONCE — the delimiter check and the
+        // appended entry below must see the same string (a midnight rollover
+        // between two computations made the checked string ≠ the written string).
+        const prefixed = this.addDatePrefix ? `## ${new Date().toISOString().slice(0, 10)}\n${content}` : content;
+        if (hasEntryDelimiter(prefixed)) {
+            // F-201: a fact carrying the delimiter (or ending in `\n§`) would split
+            // into multiple entries on read-back, and a delimiter-ending fact is
+            // permanent drift. Refuse up front with the position so the model can
+            // rewrite it as separate facts. V4-49: no batch-style `Operation N`
+            // prefix here — this is a single add, and addCore's other rejections
+            // (drift/threat/limit) are likewise prefix-free.
+            return { result: { ok: false, message: '该条目含有分隔符（§），会被拆成多条；请改写为多条独立的事实。', entries: [], chars: 0, limit: this.limitFor(target) }, write: null };
+        }
+        const entries = [...new Set(normalizeEntries(raw))];
+        // P2-1 (v18): only strip the generated date prefix when THIS store writes
+        // one (see dedupeKey). With addDatePrefix=false a user fact may
+        // legitimately start with `## YYYY-MM-DD\n`; stripping it made
+        // `add('alpha')` a false duplicate of a stored `## 2020-01-01\nalpha`.
+        if (entries.some(entry => this.dedupeKey(entry) === content)) {
+            this.resetFailures();
+            return { result: { ok: true, message: `该条目已存在（未重复添加）。${this.storageHint(target, entries.join(ENTRY_DELIMITER).length)}`, entries, chars: entries.join(ENTRY_DELIMITER).length, limit: this.limitFor(target) }, write: null };
+        }
+        const next = [...entries, prefixed];
+        const total = next.join(ENTRY_DELIMITER).length;
+        const addLimit = this.limitFor(target);
+        if (addLimit > 0 && total > addLimit) {
+            return { result: this.failure(target, `添加该条目会超过 ${addLimit} 字符上限。请先合并或删除过期条目，再重试。`, entries), write: null };
+        }
+        this.resetFailures();
+        return { result: { ok: true, message: `已添加条目。${this.storageHint(target, total)}`, entries: next, chars: total, limit: this.limitFor(target) }, write: render(next) };
+    }
+    /**
+     * The single drift evaluation. `raw` is in canonical form when it byte-matches
+     * `render(normalizeEntries(raw))`; anything else means it was edited outside
+     * MemoryStore (empty/`§`-only entries, stray blank lines, leading or trailing
+     * delimiters — structural anomalies the writer would quietly normalize away).
+     * Both write paths derive this from their locked view and `detectDrift` from
+     * a fresh read, so a write and a later read can never disagree about the same
+     * bytes.
+     *
+     * An absent, empty, or whitespace-only body is the "never written" state
+     * (rc.42 audit P1-6): it parses to zero entries, and the canonical form
+     * `'\n'` can never byte-match it, so flagging it would permanently refuse
+     * every write path — including the repairs the model would need to make.
+     * Such files are adopted instead of flagged.
+     *
+     * Returns one of:
+     * - `'external'` — non-canonical body, i.e. real external modification. This
+     *   includes the Hermes-parity signal #2 (an entry larger than the whole-file
+     *   limit): that shape is only meaningful as external evidence on a
+     *   NON-canonical body, because free-form external appends never render
+     *   canonically.
+     * - `'over-limit'` — v28 MEM-01: a CANONICAL body whose entries exceed the
+     *   CURRENT configured limit. Those bytes were written by this store under a
+     *   previous (higher) limit, so they are not external drift; treating them as
+     *   such misattributed a config change to an "external editor" and bricked
+     *   every write path (the advertised recovery — remove/consolidate — is
+     *   exactly what the drift gate refused). Callers route this state to a
+     *   config-naming refusal and let shrink-only batches through.
+     * - `null` — no drift: writable as-is.
+     *
+     * @param target - memory target whose char limit bounds one parsed entry
+     * @param raw - on-disk body, or `null` when the file does not exist
+     */
+    driftKind(target, raw) {
+        if (raw === null || raw.trim() === '')
+            return null;
+        const entries = normalizeEntries(raw);
+        if (render(entries) !== raw)
+            return 'external';
+        const limit = this.limitFor(target);
+        // A zero/negative limit means "unbounded".
+        if (limit > 0 && entries.some(entry => entry.length > limit))
+            return 'over-limit';
+        return null;
+    }
+    /** External-drift predicate: canonical-form violations only (see
+     * {@link driftKind}). `detectDrift` and the write paths share it, so a write
+     * and a later read never disagree about the same bytes. */
+    drifted(target, raw) {
+        return this.driftKind(target, raw) === 'external';
+    }
+    /**
+     * Drift refusal for a body already read under the write lock, or `null` when
+     * writing may proceed. Both write paths return this unchanged, so their
+     * refusals stay byte-identical and each carries the same backup.
+     *
+     * The `'over-limit'` state never refuses shrink-only batches (`shrinkOnly`):
+     * removing entries is the advertised recovery for a limit lowered under
+     * existing content, and the batch's own final limit check still gates the
+     * result.
+     *
+     * @param target - memory target that owns the drifted file
+     * @param raw - locked file body
+     * @param shrinkOnly - every queued operation removes an entry (no growth)
+     * @returns the refusal to hand back, or `null` to continue writing
+     */
+    async driftRefusal(target, raw, shrinkOnly = false) {
+        const kind = this.driftKind(target, raw);
+        if (kind === null)
+            return null;
+        if (kind === 'over-limit') {
+            if (shrinkOnly)
+                return null;
+            const limit = this.limitFor(target);
+            const entries = normalizeEntries(raw);
+            const over = entries.filter(entry => entry.length > limit).length;
+            return {
+                ok: false,
+                message: `${over} 条记忆超过了配置的 ${target}CharLimit（${limit}）；它们是在更高上限下写入的。请提高上限或删除条目 —— 删除类操作仍然可用。`,
+                entries,
+                chars: entries.join(ENTRY_DELIMITER).length,
+                limit,
+            };
+        }
+        const backup = await this.backupFile(target);
+        const suffix = backup ? ` 已把备份保存到 ${basename(backup)}。` : '';
+        return { ok: false, message: `检测到记忆文件被外部改动。${suffix} 请先处理该漂移再重试。`, entries: [], chars: 0, limit: this.limitFor(target) };
+    }
+    async applyBatch(target, operations) {
+        return await this.serial(() => this.applyBatchChained(target, operations));
+    }
+    async applyBatchChained(target, operations) {
+        if (operations.length === 0)
+            return { ok: false, message: 'operations 列表为空。', entries: [], chars: 0, limit: this.limitFor(target) };
+        // v28 MEM-01: remove-only batches are the recovery path for the
+        // 'over-limit' state (canonical body under a lowered limit) — the drift
+        // gate lets them through; grows still refuse with the config-naming text.
+        // v29 MEM-02: they also bypass the oversized read-guard (see chainedWrite).
+        const shrinkOnly = operations.every(op => op.action === 'remove');
+        return await this.chainedWrite(target, async (raw) => await this.applyBatchCore(target, operations, raw, shrinkOnly), shrinkOnly);
+    }
+    /** Batch RMW inside the transaction. `write: null` = failure/no-op, disk untouched. */
+    async applyBatchCore(target, operations, raw, shrinkOnly = false) {
+        // The oversized guard runs pre-transact in applyBatch(); drift is derived
+        // from the locked view below.
+        const refusal = await this.driftRefusal(target, raw, shrinkOnly);
+        if (refusal)
+            return { result: refusal, write: null };
+        const entries = [...new Set(normalizeEntries(raw))];
+        const working = [...entries];
+        // C-02: one date prefix per batch — the replace branch gains the
+        // same addDatePrefix treatment as add, and every op in the batch shares a
+        // single computation (no midnight seam between ops).
+        const datePrefix = this.addDatePrefix ? `## ${new Date().toISOString().slice(0, 10)}\n` : '';
+        for (const [index, op] of operations.entries()) {
+            const position = index + 1;
+            if (op.action === 'add') {
+                // PLAN-R2 P2-6 (2026-09-16): `content` is the schema alias for the new
+                // body. T3-06/A34: precedence goes to the first NON-BLANK of the two
+                // (core's `payloadText`), not to a blank `facts` that shadows a body the
+                // op does carry.
+                const body = payloadText(op);
+                if (!body)
+                    return { result: { ok: false, message: `第 ${position} 个操作（add）：必须提供 facts。未应用任何操作。${previewEntries(entries)}`, entries, chars: entries.join(ENTRY_DELIMITER).length, limit: this.limitFor(target) }, write: null };
+                const threat = this.memoryThreatBlock(body);
+                if (threat)
+                    return { result: { ok: false, message: `第 ${position} 个操作：${threat}${previewEntries(entries)}`, entries, chars: entries.join(ENTRY_DELIMITER).length, limit: this.limitFor(target) }, write: null };
+                // V8-02 (0.3.47): same post-prefix inspection as addCore — the
+                // `## date\n${body}` seam must not synthesize the delimiter.
+                const entryBody = `${datePrefix}${body}`;
+                if (hasEntryDelimiter(entryBody)) {
+                    return { result: { ok: false, message: `第 ${position} 个操作（add）：该条目含有分隔符（§），会被拆成多条；请改写为多条独立的事实。${previewEntries(entries)}`, entries, chars: entries.join(ENTRY_DELIMITER).length, limit: this.limitFor(target) }, write: null };
+                }
+                if (!working.some(entry => this.dedupeKey(entry) === body)) {
+                    working.push(entryBody);
+                }
+                continue;
+            }
+            // V6-25 (0.3.37): an enum-outside action (e.g. 'Add'/'upsert') used to
+            // silently fall into the REPLACE branch — a semantic drift that passed
+            // as ok:true. Fail loud on the contract violation instead. The action is
+            // inspected through unknown (the caller's type can lie).
+            const rawAction = op.action;
+            if (rawAction !== 'remove' && rawAction !== 'replace') {
+                return { result: { ok: false, message: `第 ${position} 个操作：未知动作「${String(rawAction)}」（应为 add/remove/replace）。未应用任何操作。${previewEntries(entries)}`, entries, chars: entries.join(ENTRY_DELIMITER).length, limit: this.limitFor(target) }, write: null };
+            }
+            const needle = (op.old_text ?? '').trim();
+            if (!needle)
+                return { result: { ok: false, message: `第 ${position} 个操作（${op.action}）：必须提供 old_text。未应用任何操作。${previewEntries(entries)}`, entries, chars: entries.join(ENTRY_DELIMITER).length, limit: this.limitFor(target) }, write: null };
+            const matches = working.map((entry, matchIndex) => ({ entry, matchIndex })).filter(({ entry }) => entry.includes(needle));
+            if (matches.length === 0) {
+                return { result: this.failure(target, `第 ${position} 个操作：找不到匹配 "${needle}" 的条目。未应用任何操作。`, entries), write: null };
+            }
+            if (new Set(matches.map(m => m.entry)).size > 1) {
+                return { result: { ok: false, message: `第 ${position} 个操作：「${needle}」匹配到多条不同条目。未应用任何操作。${previewEntries(entries)}`, entries, chars: entries.join(ENTRY_DELIMITER).length, limit: this.limitFor(target) }, write: null };
+            }
+            const matchIndex = matches[0]?.matchIndex ?? -1;
+            if (op.action === 'remove') {
+                working.splice(matchIndex, 1);
+            }
+            else {
+                // PLAN-R2 P2-6 (2026-09-16): same `content` alias as the add branch —
+                // this is the replacement body slot, not a facts-only field.
+                const body = payloadText(op);
+                if (!body)
+                    return { result: { ok: false, message: `第 ${position} 个操作（replace）：必须提供 facts。${previewEntries(entries)}`, entries, chars: entries.join(ENTRY_DELIMITER).length, limit: this.limitFor(target) }, write: null };
+                const threat = this.memoryThreatBlock(body);
+                if (threat)
+                    return { result: { ok: false, message: `第 ${position} 个操作：${threat}${previewEntries(entries)}`, entries, chars: entries.join(ENTRY_DELIMITER).length, limit: this.limitFor(target) }, write: null };
+                // C-02: the replaced entry carries the date prefix like an
+                // added one, and the delimiter guard inspects the FINAL on-disk entry
+                // (the V8-02 seam rule — a leading-§ body would synthesize `\n§\n`).
+                const entryBody = `${datePrefix}${body}`;
+                if (hasEntryDelimiter(entryBody)) {
+                    return { result: { ok: false, message: `第 ${position} 个操作（replace）：该条目含有分隔符（§），会被拆成多条；请改写为多条独立的事实。${previewEntries(entries)}`, entries, chars: entries.join(ENTRY_DELIMITER).length, limit: this.limitFor(target) }, write: null };
+                }
+                working[matchIndex] = entryBody;
+            }
+        }
+        const total = working.join(ENTRY_DELIMITER).length;
+        const batchLimit = this.limitFor(target);
+        if (batchLimit > 0 && total > batchLimit) {
+            return { result: this.failure(target, `批处理结果（${total} 字符）超过 ${batchLimit} 上限。请在同一个批里再删除或缩短一些条目。`, entries), write: null };
+        }
+        this.resetFailures();
+        return { result: { ok: true, message: `已应用 ${operations.length} 个操作。${this.storageHint(target, total)}`, entries: working, chars: total, limit: this.limitFor(target) }, write: render(working) };
+    }
+    async renderContext() {
+        const memory = await this.read('memory');
+        const user = await this.read('user');
+        const parts = [];
+        for (const [target, label, entries] of [['memory', 'Memory', memory], ['user', 'User Profile', user]]) {
+            // An oversized file read as empty; probe once more here so the injected
+            // context states the skip instead of silently dropping the block.
+            const oversized = entries.length === 0 ? await this.oversizedFile(target) : null;
+            if (oversized) {
+                parts.push(`## ${label} — file skipped: ${oversized.size} bytes (limit ${oversized.limit * READ_GUARD_FACTOR}); not read`);
+                continue;
+            }
+            // V10-03 (P2-18): the same exempt labels apply on render — an entry the
+            // deployment allowed into the store must not silently vanish from the
+            // injected context.
+            const safe = entries.filter(entry => !scanMemoryThreats(entry, undefined, this.threatScanOptions()));
+            if (safe.length > 0) {
+                const body = safe.join(ENTRY_DELIMITER);
+                const limit = this.limitFor(target);
+                const note = safe.length === entries.length ? '' : ` (${entries.length - safe.length} threat-matched entries filtered)`;
+                // Usage indicator aligned with Hermes `_render_block`: floor percentage clamped at 100.
+                // C-04: with no limit (limit <= 0) the whole usage segment is
+                // omitted — the old form rendered a bogus "[0% — N/0 chars]".
+                const usage = limit > 0
+                    ? ` [${Math.min(100, Math.floor((body.length * 100) / limit))}% — ${body.length}/${limit} chars]`
+                    : '';
+                parts.push(`## ${label} (${safe.length} entries)${usage}${note}\n${body}`);
+            }
+            else if (entries.length > 0) {
+                // P3-14 (v14): every entry was threat-matched. The block used to
+                // vanish with no trace, so the model (and an operator reading the
+                // transcript) could not tell "no memories" from "all filtered" — the
+                // oversized branch above already states its skip explicitly.
+                parts.push(`## ${label} — ${entries.length} entries withheld by the security scan; none injected`);
+            }
+        }
+        // G6-S2/W8: the injected docs are registered with `interpolate: false` by their consumer
+        // (tool-memory), so stored entries keep literal `{{...}}`: the platform never resolves them and
+        // never throws on one. MemoryStore no longer rewrites the text — the escape belonged to the
+        // consumer's registration flag, not to the stored knowledge (two homes would drift).
+        return parts.join('\n\n');
+    }
+    /**
+     * Detect on-disk drift for a caller that holds no locked view: `true` when the
+     * file is not in canonical form, or when its size trips the read guard. The
+     * write paths apply the same predicate (`drifted`) to the body they read under
+     * the lock, so a write and a follow-up read agree about the same bytes.
+     *
+     * @param target - memory target to inspect
+     * @returns whether the file on disk counts as externally drifted
+     */
+    async detectDrift(target) {
+        // Oversized files are an external-modification signal by the read guard;
+        // report drift so a write followed by a read never loads them.
+        if (await this.oversizedFile(target))
+            return true;
+        return this.drifted(target, await this.io.readText(fileFor(this.root, target)));
+    }
+}
+//# sourceMappingURL=memory-store.js.map