@elvisw/dsh-magic-context 0.0.0-stage → 0.14.0

package/lib/core/compartments.js

@@ -0,0 +1,424 @@
+import { errText } from "./types.js";
+/** The `[compacted §C<n>§]` placeholder (Magic Context's dropped-then-compacted marker). */
+export function compactedPlaceholder(compartmentId) {
+    return `[compacted §C${compartmentId}§]`;
+}
+/** Rough token estimate used for triggering and budgets (chars/4, min 1). */
+export function estimateTokens(text) {
+    return estimateTokensFromLength(text.length);
+}
+/** Length-only form for a surface node that already carries `textLength`. */
+export function estimateTokensFromLength(length) {
+    return Math.max(1, Math.ceil(length / 4));
+}
+/**
+ * Pick the detail tier for one compartment from its importance and age.
+ * Adapter-side approximation of Magic Context's decay math (documented
+ * divergence): four fixed age bands, promoted/demoted one step by importance.
+ */
+export function selectTier(importance, ageMs) {
+    const bands = ['p1', 'p2', 'p3', 'p4'];
+    const age = Math.max(0, ageMs);
+    let index = age < 10 * 60_000 ? 0 : age < 2 * 60 * 60_000 ? 1 : age < 24 * 60 * 60_000 ? 2 : 3;
+    if (importance >= 80)
+        index -= 1;
+    else if (importance <= 20)
+        index += 1;
+    return bands[Math.min(bands.length - 1, Math.max(0, index))];
+}
+/** The text of one compartment at its natural tier. */
+export function tierText(compartment, now) {
+    const tier = selectTier(compartment.importance, now - compartment.createdAt);
+    return { tier, text: compartment.tiers[tier] };
+}
+/** The header line identifying a compartment in a rendered baseline. */
+export function compartmentHeader(compartment, now) {
+    const { tier } = tierText(compartment, now);
+    const minutes = Math.max(0, Math.round((now - compartment.createdAt) / 60_000));
+    return `§C${compartment.compartmentId}§ [${tier}, importance ${String(compartment.importance)}, ${String(minutes)}m ago]`;
+}
+/**
+ * Render one compartment as a baseline block: header, digest, and the
+ * extracted facts/events. `mostCompressedTier` bounds fidelity downward (the
+ * budget path forces p4 on a compartment whose natural tier is more detailed).
+ */
+export function renderCompartment(compartment, now, mostCompressedTier) {
+    const natural = tierText(compartment, now);
+    const order = ['p1', 'p2', 'p3', 'p4'];
+    const forced = mostCompressedTier !== undefined
+        && order.indexOf(mostCompressedTier) > order.indexOf(natural.tier);
+    const tier = forced ? mostCompressedTier : natural.tier;
+    const lines = [`${compartmentHeader(compartment, now)}`, compartment.tiers[tier]];
+    if (compartment.facts.length > 0) {
+        lines.push(`facts: ${compartment.facts.map(fact => fact.category.length === 0 ? fact.content : `[${fact.category}] ${fact.content}`).join(' | ')}`);
+    }
+    if (compartment.events.length > 0)
+        lines.push(`events: ${compartment.events.join(' | ')}`);
+    return lines.join('\n');
+}
+/** The in-band sentinels wrapping the injected baseline inside its node. */
+export const BASELINE_OPEN = '<magic-context>';
+export const BASELINE_CLOSE = '</magic-context>';
+/**
+ * Magic Context's visibility sentinel: the mutation only flipped the row's
+ * cross-project visibility, the content is unchanged (§6.2).
+ */
+export const MEMORY_VISIBILITY_SENTINEL = '__mc_visibility__';
+/** MC inject-compartments.ts:1142 — forced rows per delta render, hard cap. */
+export const MAX_FORCED_MEMORIES_PER_DELTA = 10;
+export const MEMORY_UPDATES_OPEN = '<memory-updates>';
+export const MEMORY_UPDATES_CLOSE = '</memory-updates>';
+export const MEMORY_UPDATES_HEADER = 'These memories changed since the snapshot below — trust these:';
+/** Attribute escaping (MC `memory_render.rs:36-47`): `& < > "`. */
+function escapeAttribute(value) {
+    return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
+/** Text escaping (MC `memory_render.rs:36-47`): `& < >`. */
+function escapeText(value) {
+    return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+/**
+ * Render Magic Context's `<memory-updates>` block, or `''` when there is
+ * nothing to say. The header alone means "empty" (§6.4), so an empty delta
+ * contributes zero bytes — the cache-prefix invariant depends on it.
+ *
+ * @param options.renderedIds - ids whose content is already rendered in the
+ *   sibling `<new-memories>` block of the same m[1] region. An `<updated>`
+ *   line for one of them is dropped so no memory's content is rendered twice;
+ *   pointer lines (`<superseded>`/`<removed>`) are still emitted.
+ * @param options.baselineIds - ids rendered in the m[0] baseline. When given,
+ *   mutations for any other target are dropped entirely (MC
+ *   inject-compartments.ts:2843-2848): the model never saw that id, so an
+ *   `<updated>`/`<removed>` pointer for it would be phantom.
+ */
+export function renderMemoryUpdates(updates, options = {}) {
+    const lines = [MEMORY_UPDATES_HEADER];
+    const emitted = new Set();
+    // MC inject-compartments.ts:2822-2869 — rows the model never saw in m[0]
+    // can still be FORCED into `<new-memories>`: a `superseded` replacement and
+    // a visibility-flipped target are eligible even when out of the baseline.
+    const forcedIds = new Set();
+    for (const update of [...updates].sort((left, right) => left.id - right.id)) {
+        const target = update.targetMemoryId;
+        // When the caller supplies the eligible set it is authoritative (MC);
+        // without it a legacy caller cannot be checked — stay permissive.
+        const eligible = options.eligibleIds === undefined || options.eligibleIds.has(target);
+        if (update.mutationType === 'superseded') {
+            // MC order (:2825-2841): the replacement is forced FIRST (even when the
+            // target itself was never in the baseline), then the pointer line only
+            // renders when the target WAS in the baseline — otherwise it is phantom.
+            const replacement = update.supersededById;
+            const replacementVisible = options.eligibleIds === undefined
+                || (replacement !== undefined && options.eligibleIds.has(replacement));
+            const replacementResolvable = update.replacementResolvable === true && replacementVisible;
+            if (replacement !== undefined && replacementResolvable
+                && options.baselineIds?.has(replacement) !== true) {
+                forcedIds.add(replacement);
+            }
+            if (options.baselineIds !== undefined && !options.baselineIds.has(target))
+                continue;
+            emitted.add(target);
+            lines.push(replacement !== undefined && replacementResolvable
+                ? `  <superseded id="${String(target)}" by="${String(replacement)}"/>`
+                : `  <removed id="${String(target)}"/>`);
+            continue;
+        }
+        if (options.baselineIds !== undefined && !options.baselineIds.has(target)) {
+            // Out-of-baseline target: a visibility flip still surfaces the row
+            // (forced), anything else stays silent (MC :2843-2848).
+            if (update.mutationType === 'update'
+                && update.category === MEMORY_VISIBILITY_SENTINEL
+                && eligible) {
+                forcedIds.add(target);
+            }
+            continue;
+        }
+        // Coalescing already keeps one row per target upstream; this is the
+        // defensive second gate ("the same change never appears twice").
+        if (emitted.has(target))
+            continue;
+        if (update.mutationType !== 'update') {
+            emitted.add(target);
+            lines.push(`  <removed id="${String(target)}"/>`);
+            continue;
+        }
+        if (options.renderedIds?.has(target) === true)
+            continue;
+        const content = update.content;
+        if (content === undefined || content.length === 0) {
+            emitted.add(target);
+            lines.push(`  <removed id="${String(target)}"/>`);
+            continue;
+        }
+        emitted.add(target);
+        const category = update.category;
+        // MC omits the attribute for an empty category and for the visibility
+        // sentinel (it is not a real category) — §6.4.
+        const hasCategory = category !== undefined
+            && category.length > 0
+            && category !== MEMORY_VISIBILITY_SENTINEL;
+        lines.push(hasCategory
+            ? `  <updated id="${String(target)}" category="${escapeAttribute(category)}">${escapeText(content)}</updated>`
+            : `  <updated id="${String(target)}">${escapeText(content)}</updated>`);
+    }
+    const forcedMemoryIds = [...forcedIds].sort((left, right) => left - right)
+        .slice(0, MAX_FORCED_MEMORIES_PER_DELTA);
+    if (lines.length === 1)
+        return { block: '', count: 0, forcedMemoryIds };
+    return {
+        block: [MEMORY_UPDATES_OPEN, ...lines, MEMORY_UPDATES_CLOSE].join('\n'),
+        count: lines.length - 1,
+        forcedMemoryIds,
+    };
+}
+/**
+ * Compose the m[0] baseline / m[1] delta block. m[0] is frozen history
+ * (compartments created at or before the last hard rebuild, plus project
+ * memories); m[1] is the delta accumulated since. Newest first inside m[1],
+ * oldest first inside m[0] so the model reads a stable, chronological spine.
+ *
+ * @param budgetTokens - soft cap; older m[0] compartments degrade to their
+ *   compressed tier and then drop out when the budget is exhausted. m[1] is
+ *   never truncated (it is the part that must not be lost).
+ */
+export function renderBaseline(input) {
+    const sections = [];
+    const profileLines = input.profileLines ?? [];
+    if (profileLines.length > 0) {
+        sections.push(['<user-profile>', ...profileLines, '</user-profile>'].join('\n'));
+    }
+    if (input.memories.length > 0) {
+        sections.push(['<project-memories>', ...input.memories, '</project-memories>'].join('\n'));
+    }
+    if (input.baseline.length > 0) {
+        const ordered = [...input.baseline].sort((left, right) => left.createdAt - right.createdAt);
+        const rendered = [];
+        let used = 0;
+        for (const compartment of ordered) {
+            const full = renderCompartment(compartment, input.now);
+            const fullCost = estimateTokens(full);
+            if (used + fullCost <= input.budgetTokens) {
+                rendered.push(full);
+                used += fullCost;
+                continue;
+            }
+            const compressed = renderCompartment(compartment, input.now, 'p4');
+            const compressedCost = estimateTokens(compressed);
+            if (used + compressedCost <= input.budgetTokens) {
+                rendered.push(compressed);
+                used += compressedCost;
+            }
+        }
+        if (rendered.length > 0)
+            sections.push(['<compartment-baseline>', ...rendered, '</compartment-baseline>'].join('\n'));
+    }
+    // m[1] begins here: every section below is delta-shaped and may change without
+    // touching a single byte of the sections above (the cache-prefix invariant).
+    const memoryUpdates = renderMemoryUpdates(input.memoryUpdates ?? [], {
+        ...input.newMemoryIds === undefined ? {} : { renderedIds: new Set(input.newMemoryIds) },
+        ...input.baselineIds === undefined ? {} : { baselineIds: new Set(input.baselineIds) },
+        ...input.eligibleIds === undefined ? {} : { eligibleIds: new Set(input.eligibleIds) },
+    });
+    if (memoryUpdates.block.length > 0)
+        sections.push(memoryUpdates.block);
+    const forcedMemoryLines = input.forcedMemoryLines ?? [];
+    const budgetedNewMemories = input.newMemories ?? [];
+    const newMemories = budgetedNewMemories.length > 0 || forcedMemoryLines.length > 0
+        ? [...budgetedNewMemories, ...forcedMemoryLines]
+        : [];
+    if (newMemories.length > 0) {
+        sections.push(['<new-memories>', ...newMemories, '</new-memories>'].join('\n'));
+    }
+    const newProfileLines = input.newProfileLines ?? [];
+    if (newProfileLines.length > 0) {
+        sections.push(['<new-user-profile>', ...newProfileLines, '</new-user-profile>'].join('\n'));
+    }
+    if (input.delta.length > 0) {
+        const ordered = [...input.delta].sort((left, right) => right.createdAt - left.createdAt);
+        sections.push([
+            '<compartment-delta>',
+            ...ordered.map(compartment => renderCompartment(compartment, input.now)),
+            '</compartment-delta>',
+        ].join('\n'));
+    }
+    if (sections.length === 0)
+        return '';
+    return [BASELINE_OPEN, ...sections, BASELINE_CLOSE].join('\n');
+}
+/** Index of the baseline block inside a message's text, if it carries one. */
+export function findBaselineRange(text) {
+    const start = text.indexOf(BASELINE_OPEN);
+    if (start === -1)
+        return undefined;
+    const close = text.indexOf(BASELINE_CLOSE, start + BASELINE_OPEN.length);
+    if (close === -1)
+        return undefined;
+    return { start, end: close + BASELINE_CLOSE.length };
+}
+/** Strip any previously injected baseline block from a message text. */
+export function stripBaseline(text) {
+    const range = findBaselineRange(text);
+    if (range === undefined)
+        return text;
+    return (text.slice(0, range.start) + text.slice(range.end)).trim();
+}
+export class HistorianOutputError extends Error {
+    constructor(message) {
+        super(`magic-context historian output rejected: ${message}`);
+        this.name = 'HistorianOutputError';
+    }
+}
+function asTier(value, key) {
+    if (typeof value !== 'string' || value.trim().length === 0) {
+        throw new HistorianOutputError(`summary.${key} must be a non-empty string`);
+    }
+    return value.trim();
+}
+function asStringArray(value) {
+    if (value === undefined || value === null)
+        return [];
+    if (!Array.isArray(value))
+        throw new HistorianOutputError('facts/events must be arrays');
+    return value.filter((item) => typeof item === 'string' && item.trim().length > 0)
+        .map(item => item.trim());
+}
+/**
+ * Facts as `{category, content}` (Magic Context's promotable shape).
+ *
+ * Legacy plain strings are still accepted by the HISTORIAN contract — a model
+ * that returns `["..."]` must not fail the whole run — but they carry no
+ * category and are therefore not promotable; they are kept as `category: ''`
+ * so the compartment still renders them and the journal can explain why they
+ * were skipped. Unknown categories are kept verbatim for the same reason:
+ * Magic Context drops them at promotion time, not at parse time.
+ */
+function asFactArray(value) {
+    if (value === undefined || value === null)
+        return [];
+    if (!Array.isArray(value))
+        throw new HistorianOutputError('facts must be an array');
+    const facts = [];
+    for (const item of value) {
+        if (typeof item === 'string') {
+            const content = item.trim();
+            if (content.length > 0)
+                facts.push({ category: '', content });
+            continue;
+        }
+        if (item !== null && typeof item === 'object') {
+            const record = item;
+            const content = typeof record.content === 'string' ? record.content.trim() : '';
+            if (content.length === 0)
+                continue;
+            const category = typeof record.category === 'string' ? record.category.trim() : '';
+            facts.push({ category, content });
+        }
+    }
+    return facts;
+}
+/**
+ * A one-line description of why a JSON-ish text does not balance, for the
+ * failure journal.
+ *
+ * All four live `invalid-output` failures (2026-10-08..10-10) reported a JSON
+ * syntax error at the LAST character of the output — position = `outputChars - 1`
+ * — while the tail the journal kept was a well-formed ending (`...".` then `}`).
+ * A parser only trips on the final `}` when something earlier never closed, so
+ * the text looked intact at both ends and the defect sat in the middle, exactly
+ * where the journal kept nothing. Counting openers against closers, ignoring
+ * both inside string literals, turns that into a recorded fact instead of a
+ * guess about the model.
+ */
+export function describeJsonImbalance(text) {
+    const stack = [];
+    let inString = false;
+    let escaped = false;
+    for (const char of text) {
+        if (inString) {
+            if (escaped)
+                escaped = false;
+            else if (char === '\\')
+                escaped = true;
+            else if (char === '"')
+                inString = false;
+            continue;
+        }
+        if (char === '"') {
+            inString = true;
+            continue;
+        }
+        if (char === '{' || char === '[') {
+            stack.push(char);
+            continue;
+        }
+        if (char === '}' || char === ']') {
+            const want = char === '}' ? '{' : '[';
+            if (stack.length === 0)
+                return `unexpected '${char}'`;
+            if (stack[stack.length - 1] !== want)
+                return `'${stack[stack.length - 1]}' closed by '${char}'`;
+            stack.pop();
+        }
+    }
+    if (inString)
+        return 'unterminated string';
+    if (stack.length === 0)
+        return '';
+    const closers = new Map();
+    for (const open of stack) {
+        const close = open === '{' ? '}' : ']';
+        closers.set(close, (closers.get(close) ?? 0) + 1);
+    }
+    return `unclosed ${[...closers.entries()].map(([close, count]) => `'${close}'×${String(count)}`).join('+')}`;
+}
+/**
+ * Parse and validate a historian response. Throws {@link HistorianOutputError}
+ * on any contract violation — the run then fails closed (no compartment row,
+ * no mutation) rather than storing a half-digest.
+ */
+export function parseHistorianOutput(text) {
+    const open = text.indexOf('{');
+    const close = text.lastIndexOf('}');
+    if (open === -1 || close <= open) {
+        throw new HistorianOutputError('no JSON object found in the response');
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text.slice(open, close + 1));
+    }
+    catch (error) {
+        const imbalance = describeJsonImbalance(text.slice(open, close + 1));
+        throw new HistorianOutputError(`invalid JSON (${errText(error)})${imbalance === '' ? '' : ` [${imbalance}]`}`);
+    }
+    if (parsed === null || typeof parsed !== 'object') {
+        throw new HistorianOutputError('response is not a JSON object');
+    }
+    const record = parsed;
+    const summary = record.summary;
+    if (summary === null || typeof summary !== 'object') {
+        throw new HistorianOutputError('summary must be an object with p1..p4');
+    }
+    const tiers = summary;
+    const importanceRaw = record.importance;
+    const importance = typeof importanceRaw === 'number' && Number.isFinite(importanceRaw)
+        ? Math.min(100, Math.max(0, Math.round(importanceRaw)))
+        : importanceRaw === undefined
+            ? 50
+            : undefined;
+    if (importance === undefined)
+        throw new HistorianOutputError('importance must be a number when present');
+    return {
+        tiers: {
+            p1: asTier(tiers.p1, 'p1'),
+            p2: asTier(tiers.p2, 'p2'),
+            p3: asTier(tiers.p3, 'p3'),
+            p4: asTier(tiers.p4, 'p4'),
+        },
+        importance,
+        facts: asFactArray(record.facts),
+        events: asStringArray(record.events),
+        // WP5: absent on every digest written before the field existed, and on any
+        // model that follows the instruction by omitting an empty array.
+        userObservations: asStringArray(record.userObservations),
+    };
+}

package/lib/core/corpus-store.js

@@ -0,0 +1,176 @@
+/**
+ * Own-corpus bootstrap — the plugin's memory database, owned end to end.
+ *
+ * Cutover (user ruling 2026-10-13): before small-scale distribution the
+ * adapter stops sharing upstream Magic Context's `context.db`. Dual-writer
+ * conflicts were structural, not incidental — upstream releases near-daily
+ * (0.47/0.48/0.49 within four days), the fence had zero version margin, and
+ * MC 0.48's indexCoordination treats every non-MC connection as a foreign
+ * body. The corpus now lives in the plugin's OWN data dir; the legacy file is
+ * read exactly once, by the importer (2026-10-13, retired after the run; the
+ * recipe lives in git history at 5c45d04e6), and
+ * never touched again. Upstream is followed for FEATURES only, never for
+ * storage compatibility.
+ *
+ * Schema lineage: the shape is inherited verbatim from the upstream v95
+ * store the corpus was imported from (validated against the live DDL
+ * 2026-10-13), so `MEMORY_SCHEMA_MAX_VERSION` keeps guarding the SAME
+ * numbering — but from this module on, every new `schema_migrations` row is
+ * OURS: a version above the ceiling can only mean this build is older than
+ * the corpus, which must fence exactly as before.
+ *
+ * Table set: exactly what the openers touch (memory-bridge / memory-write /
+ * profile-write / memory-search / vector-lane), nothing more. Upstream
+ * subsystems the adapter never reads (workspaces, authority guards, tags,
+ * session_meta, primers, git_commits_fts …) are deliberately absent:
+ *  - `workspaces` absence is by design — domain resolution reads the
+ *    adapter's own domains tables (design v2, no workspace takeover);
+ *  - authority-guard triggers protected upstream's module-managed projects;
+ *    no such modules exist here, so the writer's hasAuthority=false path is
+ *    the honest one.
+ */
+import { existsSync, mkdirSync, statSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+/** The version this build creates and understands. Own lineage, inherited shape. */
+export const CORPUS_SCHEMA_VERSION = 95;
+/** Marker row for a corpus imported from the legacy shared store. The main
+ * fence lane reads `MAX(version) WHERE version < 10000`, so sidecar markers
+ * at ≥ 10000 never influence it. */
+export const CORPUS_IMPORT_MARKER_VERSION = 10_001;
+const SCHEMA_DDL = `
+  CREATE TABLE schema_migrations (
+    version INTEGER PRIMARY KEY,
+    name TEXT,
+    applied_at INTEGER NOT NULL DEFAULT 0
+  );
+
+  CREATE TABLE memories (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    project_path TEXT NOT NULL,
+    category TEXT NOT NULL,
+    content TEXT NOT NULL,
+    normalized_hash TEXT NOT NULL,
+    importance INTEGER,
+    scope TEXT NOT NULL DEFAULT 'project',
+    shareable INTEGER NOT NULL DEFAULT 0,
+    source_session_id TEXT,
+    source_type TEXT DEFAULT 'historian',
+    seen_count INTEGER DEFAULT 1,
+    retrieval_count INTEGER DEFAULT 0,
+    first_seen_at INTEGER NOT NULL,
+    created_at INTEGER NOT NULL,
+    updated_at INTEGER NOT NULL,
+    last_seen_at INTEGER NOT NULL,
+    last_retrieved_at INTEGER,
+    status TEXT DEFAULT 'active',
+    expires_at INTEGER,
+    verification_status TEXT DEFAULT 'unverified',
+    verified_at INTEGER,
+    classified_at INTEGER,
+    superseded_by_memory_id INTEGER,
+    merged_from TEXT,
+    metadata_json TEXT,
+    mural_cue TEXT,
+    mural_cue_hash TEXT,
+    mural_cue_at INTEGER,
+    mural_cue_rejection_count INTEGER NOT NULL DEFAULT 0,
+    UNIQUE(project_path, category, normalized_hash)
+  );
+  CREATE INDEX idx_memories_project_status_category ON memories(project_path, status, category);
+  CREATE INDEX idx_memories_project_status_expires ON memories(project_path, status, expires_at);
+  CREATE INDEX idx_memories_project_category_hash ON memories(project_path, category, normalized_hash);
+
+  CREATE VIRTUAL TABLE memories_fts USING fts5(
+    content, category, content='memories', content_rowid='id', tokenize='porter unicode61');
+
+  CREATE TRIGGER memories_ai AFTER INSERT ON memories BEGIN
+    INSERT INTO memories_fts(rowid, content, category) VALUES (new.id, new.content, new.category);
+  END;
+  CREATE TRIGGER memories_ad AFTER DELETE ON memories BEGIN
+    INSERT INTO memories_fts(memories_fts, rowid, content, category) VALUES ('delete', old.id, old.content, old.category);
+  END;
+  CREATE TRIGGER memories_au AFTER UPDATE ON memories BEGIN
+    INSERT INTO memories_fts(memories_fts, rowid, content, category) VALUES ('delete', old.id, old.content, old.category);
+    INSERT INTO memories_fts(rowid, content, category) VALUES (new.id, new.content, new.category);
+  END;
+
+  CREATE TABLE memory_embeddings (
+    memory_id INTEGER NOT NULL REFERENCES memories(id) ON DELETE CASCADE,
+    embedding BLOB NOT NULL,
+    model_id TEXT NOT NULL,
+    PRIMARY KEY(memory_id, model_id)
+  );
+
+  CREATE TABLE memory_mutation_log (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    project_path TEXT NOT NULL,
+    mutation_type TEXT NOT NULL CHECK (mutation_type IN ('archive', 'delete', 'update', 'superseded')),
+    target_memory_id INTEGER NOT NULL,
+    superseded_by_id INTEGER,
+    category TEXT,
+    new_content TEXT,
+    queued_at INTEGER NOT NULL
+  );
+  CREATE INDEX idx_memory_mutation_log_project ON memory_mutation_log(project_path, id);
+  CREATE INDEX idx_memory_mutation_log_visibility ON memory_mutation_log(project_path, category, id, target_memory_id);
+  CREATE INDEX idx_memory_mutation_log_target ON memory_mutation_log(project_path, target_memory_id, id);
+
+  CREATE TABLE project_state (
+    project_path TEXT PRIMARY KEY,
+    project_memory_epoch INTEGER NOT NULL DEFAULT 0,
+    project_user_profile_version INTEGER NOT NULL DEFAULT 0,
+    updated_at INTEGER NOT NULL DEFAULT 0
+  );
+
+  CREATE TABLE user_memories (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    content TEXT NOT NULL,
+    status TEXT NOT NULL DEFAULT 'active',
+    promoted_at INTEGER NOT NULL,
+    source_candidate_ids TEXT DEFAULT '[]',
+    created_at INTEGER NOT NULL,
+    updated_at INTEGER NOT NULL,
+    source_candidate_provenance TEXT
+  );
+
+  CREATE TABLE user_memory_candidates (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    content TEXT NOT NULL,
+    session_id TEXT NOT NULL,
+    source_compartment_start INTEGER,
+    source_compartment_end INTEGER,
+    created_at INTEGER NOT NULL
+  );
+`;
+/**
+ * Make sure an own-corpus store exists at `dbPath`. Idempotent, fail-open:
+ * every non-`exists` outcome still lets the caller open the store and hit
+ * the same refusals the openers would have raised anyway. An EXISTING file
+ * is never touched — an operator-pointed legacy store keeps its shape and
+ * the fence keeps guarding it.
+ */
+export function ensureOwnCorpusStore(dbPath) {
+    try {
+        const existed = existsSync(dbPath);
+        if (existed && statSync(dbPath).size > 0)
+            return { outcome: 'exists' };
+        mkdirSync(dirname(dbPath), { recursive: true });
+        const db = new DatabaseSync(dbPath);
+        try {
+            db.exec('PRAGMA journal_mode = WAL');
+            db.exec('BEGIN');
+            db.exec(SCHEMA_DDL);
+            db.prepare('INSERT INTO schema_migrations(version, name, applied_at) VALUES(?, ?, ?)')
+                .run(CORPUS_SCHEMA_VERSION, 'own-corpus init (inherited upstream v95 shape)', Date.now());
+            db.exec('COMMIT');
+        }
+        finally {
+            db.close();
+        }
+        return { outcome: existed ? 'repaired-empty' : 'created', detail: `v${String(CORPUS_SCHEMA_VERSION)}` };
+    }
+    catch (error) {
+        return { outcome: 'failed', detail: error instanceof Error ? error.message : String(error) };
+    }
+}