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

package/lib/core/memory-bridge.js

@@ -0,0 +1,818 @@
+/**
+ * The project-memory bridge — the plugin's OWN corpus (`memories.db`, cut
+ * over from the legacy shared store 2026-10-13), read by the DSH adapter.
+ *
+ * Facts this module is built on (shape inherited verbatim from Magic
+ * Context's v95 storage layer; the schema is OURS now — see corpus-store.ts):
+ *  - `memories` has NO `harness` column: project memories are shared across
+ *    sessions on this machine through the corpus;
+ *  - `project_path` stores an IDENTITY (`git:<root-commit-sha>` or
+ *    `dir:<hash>`), not a path; legacy rows may still hold raw paths, so the
+ *    bridge matches the identity and the normalized path;
+ *  - the schema version lives in `schema_migrations` (lane `< 10000`);
+ *    a database newer than `MEMORY_SCHEMA_MAX_VERSION` is
+ *    fail-closed (read nothing) rather than guessed at;
+ *  - injectable rows are `status IN ('active','permanent')` and not expired;
+ *    domain-shared rows additionally need `shareable = 1`,
+ *    `scope IN ('project','ecosystem','universe')` and a category in the
+ *    active domains' `share_categories` allowlist;
+ *  - selection priority is permanent → importance → max(last_seen_at,
+ *    verified_at) → id, trimmed to a token budget.
+ *
+ * WRITES ARE DELIBERATELY ABSENT: inserting memories also means computing
+ * Magic Context's normalized hash, bumping `project_state.project_memory_epoch`
+ * only when the injectable set changes, appending `memory_mutation_log`, and
+ * honoring the authority guard — invariants owned by Magic Context's storage
+ * layer. The adapter recalls; it does not fork the memory store.
+ */
+import { DatabaseSync } from 'node:sqlite';
+import { createHash } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, normalize, resolve } from 'node:path';
+import { estimateTokens, MEMORY_VISIBILITY_SENTINEL } from "./compartments.js";
+import { memoryCategoryOrder } from "./memory-categories.js";
+import { scoreMemory } from "./memory-scoring.js";
+import { errText } from "./types.js";
+/** The corpus schema ceiling this build understands. Own lineage: the shape
+ * was inherited verbatim from upstream MC's v95 store at the 2026-10-13
+ * cutover (the adapter stopped sharing `context.db`; see corpus-store.ts),
+ * and every future `schema_migrations` row is OURS — a version above this
+ * ceiling can only mean the corpus is newer than this build, which must
+ * fence to read-only exactly as before. */
+export const MEMORY_SCHEMA_MAX_VERSION = 95;
+/** MC's terminal mutation types (`storage-memory-mutation-log.ts:9-15`): an
+ * `update` queued after one of these must not resurrect the memory. */
+export const TERMINAL_MUTATION_TYPES = new Set(['archive', 'delete', 'superseded']);
+/** MC's `MAX_MEMORY_REPLACEMENT_DEPTH` — the supersede-chain walk cap. */
+export const MAX_MEMORY_REPLACEMENT_DEPTH = 8;
+/** Default page size for one cursor read (the real log holds hundreds of rows). */
+export const DEFAULT_MUTATION_PAGE_LIMIT = 1_000;
+/** The default domain sharing allowlist when `share_categories` is absent. */
+export const DEFAULT_SHARE_CATEGORIES = ['CONSTRAINTS'];
+/** Direct-caller fallback for the corpus path (scripts, tools). The lane itself
+ *  resolves the corpus explicitly — beside the adapter store in the profile's
+ *  dataDir — and never consults this (cutover 2026-10-13: no more sharing
+ *  upstream MC's `context.db`). */
+export function defaultMemoryDbPath() {
+    return join(homedir(), '.local', 'share', 'cortexkit', 'magic-context-dsh-poc', 'memories.db');
+}
+/** Default m[0] budget for `<user-profile>` (Magic Context's own number). */
+export const PROFILE_M0_BUDGET_TOKENS = 4000;
+const SELECT_COLUMNS = 'id, project_path, category, content, importance, shareable, status, expires_at, updated_at, last_seen_at, verified_at';
+/** Magic Context's normalized-hash whitespace set, for stable digests only. */
+export function normalizeMemoryContent(content) {
+    return content.toLowerCase().replace(/\s+/g, ' ').trim();
+}
+/**
+ * Directory identity, byte-for-byte compatible with Magic Context's
+ * `directoryFallback` (`project-identity.ts`): MD5 of `path.resolve(directory)`
+ * truncated to 12 hex characters.
+ *
+ * Do NOT normalize separators here: Magic Context hashes the resolved path
+ * verbatim, so on Windows the digest contains the backslashes. A
+ * forward-slash canonicalisation silently orphans every memory of a non-git
+ * project (measured: `dir:1afbff92eb86` vs a wrong `dir:931289036571` for the
+ * same directory).
+ */
+export function directoryIdentity(directory) {
+    const canonical = resolve(directory);
+    return `dir:${createHash('md5').update(canonical, 'utf8').digest('hex').slice(0, 12)}`;
+}
+/** Cache of git identities, since a directory's root commit cannot change. */
+const gitIdentityCache = new Map();
+/**
+ * `git:<root commit sha>` for a directory inside a git repository, matching
+ * Magic Context's primary identity. Best effort by design: a missing git, a
+ * non-repository, or an empty history yields undefined and the caller falls
+ * back to {@link directoryIdentity}. Magic Context itself retries git with a
+ * cooldown; the adapter instead caches the verdict for the process lifetime.
+ */
+export function gitProjectIdentity(directory, timeoutMs = 3_000) {
+    const key = resolve(directory);
+    const cached = gitIdentityCache.get(key);
+    if (cached !== undefined || gitIdentityCache.has(key))
+        return cached;
+    let identity;
+    try {
+        const result = spawnSync('git', ['rev-list', '--max-parents=0', 'HEAD'], {
+            cwd: key,
+            encoding: 'utf8',
+            timeout: timeoutMs,
+            windowsHide: true,
+        });
+        // Multi-root histories: pick the lexicographically smallest root sha so the
+        // identity is a pure function of the root-commit set (MC project-identity.ts).
+        const first = result.status === 0
+            ? (result.stdout ?? '').split('\n').map(line => line.trim().slice(0, 64)).filter(line => /^[0-9a-f]{7,64}$/.test(line)).sort()[0]
+            : undefined;
+        identity = first === undefined ? undefined : `git:${first}`;
+    }
+    catch {
+        identity = undefined;
+    }
+    gitIdentityCache.set(key, identity);
+    return identity;
+}
+/** The identity Magic Context would use for a directory: git when possible. */
+export function resolveProjectIdentity(directory) {
+    return gitProjectIdentity(directory) ?? directoryIdentity(directory);
+}
+/** The one identity normalizer: `git:`/`dir:` identities pass through, any
+ * other string resolves as a directory. Every caller (session scope, the
+ * `ctx_memory` `project` argument, recall scoping) shares this spelling. */
+export function resolveIdentitySpec(spec) {
+    if (spec.startsWith('git:') || spec.startsWith('dir:'))
+        return spec;
+    return resolveProjectIdentity(spec);
+}
+function identityCandidates(project) {
+    if (project === undefined || project.length === 0)
+        return [];
+    if (project.startsWith('git:') || project.startsWith('dir:'))
+        return [project];
+    // A directory: resolve it the way Magic Context would (git root commit, then
+    // the dir hash), and keep the raw normalized path as a legacy candidate for
+    // rows written before identities replaced paths.
+    const primary = resolveProjectIdentity(project);
+    const legacy = normalize(project).replace(/\\/g, '/');
+    return primary === legacy ? [primary] : [primary, legacy];
+}
+function priorityOf(row) {
+    return [
+        row.permanent ? 1 : 0,
+        row.importance,
+        Math.max(row.lastSeenAt, row.verifiedAt ?? 0),
+        row.id,
+    ];
+}
+function comparePriority(left, right) {
+    const a = priorityOf(left);
+    const b = priorityOf(right);
+    for (let index = 0; index < a.length; index += 1) {
+        const difference = (b[index] ?? 0) - (a[index] ?? 0);
+        if (difference !== 0)
+            return difference;
+    }
+    return 0;
+}
+function categoryRank(category) {
+    return memoryCategoryOrder(category);
+}
+/** Render one memory as a baseline line (category-tagged, MC render order). */
+export function renderMemoryLine(row) {
+    const badge = row.permanent ? ', permanent' : '';
+    return `- [${row.category || 'MEMORY'}${badge}] ${row.content.replace(/\s+/g, ' ').trim()}`;
+}
+/** Render one profile row as a baseline line. */
+export function renderProfileLine(row) {
+    return `- ${row.content.replace(/\s+/g, ' ').trim()}`;
+}
+/**
+ * Open the shared memory database read-only. Any incompatibility (missing
+ * file, unknown schema version, missing table) disables recall with a loud
+ * warning — never an exception into the turn, never a write.
+ */
+export function openMemoryBridge(options) {
+    const dbPath = options.dbPath ?? defaultMemoryDbPath();
+    const unavailable = (detail) => {
+        options.logger.warn(`magic-context memory bridge disabled: ${detail} (${dbPath})`);
+        return {
+            dbPath,
+            status: { ok: false, detail },
+            recall: () => undefined,
+            // No space resolution without a store: recall is off, and so is every
+            // domain-scoped read that would have used this.
+            searchSpace: () => undefined,
+            maxMemoryId: () => 0,
+            mutations: () => undefined,
+            maxMemoryMutationId: () => 0,
+            projectMemoryEpochFingerprint: () => '',
+            profileRecall: () => undefined,
+            close: () => undefined,
+        };
+    };
+    if (!existsSync(dbPath))
+        return unavailable('database not found');
+    let db;
+    try {
+        db = new DatabaseSync(dbPath, { readOnly: true });
+    }
+    catch (error) {
+        return unavailable(`cannot open (${errText(error)})`);
+    }
+    try {
+        const versionRow = db.prepare('SELECT MAX(version) AS version FROM schema_migrations WHERE version < 10000').get();
+        const schemaVersion = versionRow?.version ?? undefined;
+        if (schemaVersion === undefined || schemaVersion === null) {
+            db.close();
+            return unavailable('schema_migrations carries no recognized version');
+        }
+        if (schemaVersion > MEMORY_SCHEMA_MAX_VERSION) {
+            db.close();
+            return unavailable(`schema v${String(schemaVersion)} is newer than the adapter understands (v${String(MEMORY_SCHEMA_MAX_VERSION)})`);
+        }
+        const table = db.prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'memories'").get();
+        if (table === undefined) {
+            db.close();
+            return unavailable('memories table missing');
+        }
+        const columns = new Set(db.prepare('PRAGMA table_info(memories)').all().map(row => row.name));
+        for (const required of ['id', 'project_path', 'category', 'content', 'status', 'updated_at']) {
+            if (!columns.has(required)) {
+                db.close();
+                return unavailable(`memories.${required} missing (older schema than expected)`);
+            }
+        }
+        const selfStatement = db.prepare(`SELECT ${SELECT_COLUMNS} FROM memories
+       WHERE project_path = ?
+         AND status IN ('active','permanent')
+         AND (expires_at IS NULL OR expires_at > ?)`);
+        const foreignStatement = db.prepare(`SELECT ${SELECT_COLUMNS} FROM memories
+       WHERE project_path = ?
+         AND status IN ('active','permanent')
+         AND (expires_at IS NULL OR expires_at > ?)
+         AND shareable = 1
+         AND scope IN ('project','ecosystem','universe')`);
+        // B1: the watermark is the VISIBILITY-qualified max — expired/archived
+        // rows and non-shared peer rows must never force a HARD rebuild when they
+        // land above it (MC freezes the max over the visible pool, not the table).
+        const maxIdStatement = db.prepare(`SELECT MAX(id) AS id FROM memories WHERE project_path = ?`
+            + ` AND status IN ('active','permanent') AND (expires_at IS NULL OR expires_at > ?)`);
+        /** WP3: THE activation function (see MemoryBridgeOptions.domainResolver). */
+        const peersFor = (identities) => {
+            const resolve = options.domainResolver;
+            if (resolve === undefined)
+                return { members: [], peers: [] };
+            const domains = [];
+            let answered = false;
+            for (const identity of identities) {
+                const answer = resolve(identity);
+                if (answer === undefined)
+                    continue;
+                answered = true;
+                for (const domain of answer) {
+                    if (!domains.some(existing => existing.identity === domain.identity))
+                        domains.push(domain);
+                }
+            }
+            // No domain has this identity yet: no peers. The old fallback to the
+            // shared store's `workspaces` membership died with the 2026-10-13
+            // corpus cutover — the own corpus carries no workspace tables, and
+            // cross-project sharing is exclusively domain-driven.
+            if (!answered)
+                return { members: [], peers: [] };
+            const members = domains.map(domain => domain.identity).filter(identity => !identities.includes(identity));
+            if (members.length === 0)
+                return { members: [], peers: [] };
+            // The SQL filter is a single `category IN (...)`, so the effective
+            // allowlist is the union of the activated domains'. That cannot widen what
+            // a domain is allowed to share because publishing pre-checks the category
+            // against ITS OWN allowlist (core/global-domains).
+            const categories = [...new Set(domains.flatMap(domain => [...domain.shareCategories]))]
+                .sort((left, right) => left.localeCompare(right));
+            return {
+                domains: domains.map(domain => domain.identity).join('+'),
+                members,
+                shareCategories: categories,
+                peers: domains,
+            };
+        };
+        // WP8: the user profile. `user_memories` is optional (older contracts lack
+        // it) and its stamp columns are probed rather than assumed, so a schema
+        // drift degrades to "no profile" instead of taking the recall path down.
+        let profileStatement;
+        if (db.prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'user_memories'").get() !== undefined) {
+            const profileColumns = new Set(db.prepare('PRAGMA table_info(user_memories)').all().map(row => row.name));
+            if (profileColumns.has('id') && profileColumns.has('content') && profileColumns.has('status')) {
+                const promoted = profileColumns.has('promoted_at')
+                    ? 'promoted_at'
+                    : profileColumns.has('created_at') ? 'created_at' : 'id';
+                const updated = profileColumns.has('updated_at') ? 'updated_at' : promoted;
+                profileStatement = db.prepare('SELECT id, content, ' + promoted + ' AS promoted_at, ' + updated + ' AS updated_at '
+                    + "FROM user_memories WHERE status = 'active' ORDER BY " + promoted + ' ASC, id ASC');
+            }
+        }
+        const toRow = (row) => ({ id: row.id,
+            projectPath: row.project_path,
+            category: row.category ?? '',
+            content: row.content,
+            importance: row.importance ?? 50,
+            shareable: row.shareable === 1,
+            permanent: row.status === 'permanent',
+            updatedAt: row.updated_at,
+            lastSeenAt: row.last_seen_at ?? row.updated_at,
+            ...row.verified_at === null ? {} : { verifiedAt: row.verified_at },
+        });
+        const maxFor = (identities, now) => {
+            let highest = 0;
+            for (const identity of identities) {
+                const row = maxIdStatement.get(identity, now);
+                if (row?.id != null && row.id > highest)
+                    highest = row.id;
+            }
+            return highest;
+        };
+        /** B1: the peer-side max carries the share filter (shareable + scope +
+         *  category allowlist) — a hidden peer row above the watermark is not
+         *  "visible", so freezing it would only produce a phantom m[1] line. */
+        const maxForeignId = (peerIdentities, categories, now) => {
+            if (peerIdentities.length === 0 || categories.length === 0)
+                return 0;
+            const placeholders = peerIdentities.map(() => '?').join(', ');
+            const categoryPlaceholders = categories.map(() => '?').join(', ');
+            const row = db.prepare(`SELECT MAX(id) AS id FROM memories WHERE project_path IN (${placeholders})`
+                + ` AND status IN ('active','permanent') AND (expires_at IS NULL OR expires_at > ?)`
+                + ` AND shareable = 1 AND scope IN ('project','ecosystem','universe')`
+                + ` AND category IN (${categoryPlaceholders})`).get(...peerIdentities, now, ...categories);
+            return row?.id ?? 0;
+        };
+        /** The watermark max over the visible pool: own rows (eligible) plus peer
+         *  rows (eligible AND shared). */
+        const maxVisibleId = (ownIdentities, peerIdentities, categories, now) => Math.max(maxFor(ownIdentities, now), maxForeignId(peerIdentities, categories, now));
+        // ── The non-additive change lane (`memory_mutation_log`, contract §6) ────
+        // Everything below is strictly read-only. Both tables are probed, because
+        // an older schema (or a synthetic fixture) may lack them: a missing table
+        // means "no deltas", never a failure. The same applies to the optional
+        // `memories` columns — the lane must never take the recall path down.
+        const memoryColumnNames = new Set(db.prepare('PRAGMA table_info(memories)').all().map(row => row.name));
+        const memoryColumn = (name) => memoryColumnNames.has(name) ? name : `NULL AS ${name}`;
+        let hasMutationLog = false;
+        let mutationStatement;
+        let mutationMaxStatement;
+        let epochStatement;
+        let mutationMemoryStatement;
+        try {
+            hasMutationLog = db.prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'memory_mutation_log'").get() !== undefined;
+            const hasProjectState = db.prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'project_state'").get() !== undefined;
+            const MUTATION_COLUMNS = 'id, project_path, mutation_type, target_memory_id, superseded_by_id, category, new_content, queued_at';
+            mutationStatement = hasMutationLog
+                ? db.prepare(`SELECT ${MUTATION_COLUMNS} FROM memory_mutation_log
+            WHERE project_path = ? AND id > ? ORDER BY id ASC LIMIT ?`)
+                : undefined;
+            mutationMaxStatement = hasMutationLog
+                ? db.prepare('SELECT MAX(id) AS id FROM memory_mutation_log WHERE project_path = ?')
+                : undefined;
+            epochStatement = hasProjectState
+                ? db.prepare('SELECT project_memory_epoch AS epoch FROM project_state WHERE project_path = ?')
+                : undefined;
+            // The mutation payload is resolved against the *live* memory row: MC
+            // re-reads the target for `update` (a later write is the truth) and walks
+            // `superseded_by_memory_id` to the terminal replacement (§6.3-§6.4).
+            mutationMemoryStatement = db.prepare(`SELECT id, project_path, category, content, ${memoryColumn('scope')}, ${memoryColumn('shareable')}, `
+                + `status, ${memoryColumn('expires_at')}, ${memoryColumn('superseded_by_memory_id')} `
+                + 'FROM memories WHERE id = ?');
+        }
+        catch (error) {
+            mutationStatement = undefined;
+            mutationMaxStatement = undefined;
+            epochStatement = undefined;
+            mutationMemoryStatement = undefined;
+            options.logger.warn('magic-context memory mutation lane disabled: '
+                + `${errText(error)} (${dbPath})`);
+        }
+        const epochOf = (identity) => {
+            if (epochStatement === undefined)
+                return 0;
+            const row = epochStatement.get(identity);
+            return row?.epoch ?? 0;
+        };
+        /**
+         * The epoch identity of a baseline. A bare epoch integer is not enough:
+         * domain membership changes move the epoch of a *peer*, and MC compares
+         * a fingerprint that hashes every member's epoch (`workspaces.ts:312-334`).
+         */
+        const epochFingerprint = (identities) => {
+            const pairs = [...new Set(identities)].sort().map(identity => `${identity}:${String(epochOf(identity))}`);
+            return createHash('sha1').update(pairs.join('|')).digest('hex').slice(0, 16);
+        };
+        const maxMutationFor = (identities) => {
+            if (mutationMaxStatement === undefined)
+                return 0;
+            let highest = 0;
+            for (const identity of identities) {
+                const row = mutationMaxStatement.get(identity);
+                if (row?.id != null && row.id > highest)
+                    highest = row.id;
+            }
+            return highest;
+        };
+        /**
+         * MC's `coalesceMutations` (`storage-memory-mutation-log.ts:144-229`): one
+         * row per target memory, and a terminal state beats a later non-terminal
+         * one so an `update` queued after an `archive`/`delete`/`superseded`
+         * cannot resurrect the memory. Input arrives oldest-first.
+         */
+        const coalesceMutations = (rows) => {
+            const byTarget = new Map();
+            for (const row of rows) {
+                const selected = byTarget.get(row.targetMemoryId);
+                if (selected === undefined) {
+                    byTarget.set(row.targetMemoryId, row);
+                    continue;
+                }
+                if (TERMINAL_MUTATION_TYPES.has(selected.mutationType)
+                    && !TERMINAL_MUTATION_TYPES.has(row.mutationType))
+                    continue;
+                byTarget.set(row.targetMemoryId, row);
+            }
+            return [...byTarget.values()].sort((left, right) => left.id - right.id);
+        };
+        const eligibleRow = (row, now) => (row.status === 'active' || row.status === 'permanent')
+            && (row.expires_at === null || row.expires_at > now);
+        /** Own rows are always ours; a peer's row only while it is shared here. */
+        const visibleRow = (row, identities, shared) => identities.includes(row.project_path)
+            || (row.shareable === 1
+                && row.scope !== null
+                && ['project', 'ecosystem', 'universe'].includes(row.scope)
+                && row.category !== null
+                && shared.has(row.category));
+        /**
+         * Walk `superseded_by_memory_id` to the terminal replacement (§6.3 step 4),
+         * bounded by MC's depth cap. Returns undefined when the chain is broken,
+         * cyclic, too deep, or the replacement is not currently eligible/visible —
+         * the caller then degrades `<superseded .../>` to `<removed .../>`.
+         */
+        const resolveReplacement = (startId, identities, shared, now) => {
+            let current = startId;
+            const visited = new Set();
+            for (let depth = 0; depth < MAX_MEMORY_REPLACEMENT_DEPTH; depth += 1) {
+                if (current === undefined || visited.has(current) || mutationMemoryStatement === undefined)
+                    return undefined;
+                visited.add(current);
+                const row = mutationMemoryStatement.get(current);
+                if (row === undefined)
+                    return undefined;
+                if (!eligibleRow(row, now) || !visibleRow(row, identities, shared))
+                    return undefined;
+                const next = row.superseded_by_memory_id;
+                if (next === null || next === undefined)
+                    return row;
+                current = next;
+            }
+            return undefined;
+        };
+        const toMutationRow = (raw) => ({
+            id: raw.id,
+            projectPath: raw.project_path,
+            mutationType: raw.mutation_type,
+            targetMemoryId: raw.target_memory_id,
+            ...raw.superseded_by_id === null ? {} : { supersededById: raw.superseded_by_id },
+            ...raw.category === null ? {} : { category: raw.category },
+            ...raw.new_content === null ? {} : { newContent: raw.new_content },
+            queuedAt: raw.queued_at,
+        });
+        /** Fold a coalesced row into the value object `<memory-updates>` renders. */
+        const toUpdateLine = (row, identities, shared, now) => {
+            const target = mutationMemoryStatement?.get(row.targetMemoryId);
+            const realCategory = row.category !== undefined && row.category.length > 0
+                && row.category !== MEMORY_VISIBILITY_SENTINEL
+                ? row.category
+                : target?.category ?? undefined;
+            // A peer's change is only rendered when its category is shared with us.
+            if (!identities.includes(row.projectPath)
+                && !(realCategory !== undefined && shared.has(realCategory)))
+                return undefined;
+            const base = {
+                id: row.id,
+                targetMemoryId: row.targetMemoryId,
+                mutationType: row.mutationType,
+                ...realCategory === undefined ? {} : { category: realCategory },
+            };
+            if (row.mutationType === 'superseded') {
+                const replacement = resolveReplacement(row.supersededById, identities, shared, now);
+                return {
+                    ...base,
+                    ...row.supersededById === undefined ? {} : { supersededById: row.supersededById },
+                    replacementResolvable: replacement !== undefined,
+                };
+            }
+            if (row.mutationType !== 'update')
+                return base;
+            // MC re-reads the live row for the update payload; `new_content` is the
+            // queued snapshot and the fallback when the row is already gone.
+            const content = target?.content ?? row.newContent;
+            if (content === undefined || content.length === 0)
+                return base;
+            return { ...base, content };
+        };
+        const readMutations = (request) => {
+            try {
+                const identities = identityCandidates(request.project);
+                const auto = peersFor(identities);
+                const peers = request.domainProjects ?? auto.members;
+                const peerIdentities = peers.flatMap(candidate => identityCandidates(candidate));
+                const allIdentities = [...identities, ...peerIdentities];
+                const shared = new Set(request.shareCategories ?? auto.shareCategories ?? DEFAULT_SHARE_CATEGORIES);
+                const limit = Math.max(1, Math.floor(request.limit ?? DEFAULT_MUTATION_PAGE_LIMIT));
+                const fingerprint = epochFingerprint(allIdentities);
+                const raw = [];
+                const seenIds = new Set();
+                for (const identity of allIdentities) {
+                    if (mutationStatement === undefined)
+                        break;
+                    // `limit + 1` so a truncated page is detectable rather than guessed.
+                    const page = mutationStatement.all(identity, request.afterId, limit + 1);
+                    for (const item of page) {
+                        if (seenIds.has(item.id))
+                            continue;
+                        seenIds.add(item.id);
+                        raw.push(toMutationRow(item));
+                    }
+                }
+                const ordered = raw.sort((left, right) => left.id - right.id);
+                const hasMore = ordered.length > limit;
+                const page = hasMore ? ordered.slice(0, limit) : ordered;
+                const cursor = page.length === 0
+                    ? request.afterId
+                    : Math.max(request.afterId, page[page.length - 1].id);
+                const coalesced = coalesceMutations(page);
+                const updates = coalesced
+                    .map(row => toUpdateLine(row, identities, shared, request.now))
+                    .filter((line) => line !== undefined);
+                return {
+                    updates,
+                    rows: coalesced,
+                    cursor,
+                    currentCursor: maxMutationFor(allIdentities),
+                    projectEpochFingerprint: fingerprint,
+                    projectEpoch: identities[0] === undefined ? 0 : epochOf(identities[0]),
+                    hasMore,
+                    ...identities[0] === undefined ? {} : { identity: identities[0] },
+                    members: peers,
+                };
+            }
+            catch (error) {
+                options.logger.warn(`magic-context memory mutation read failed (continuing without deltas): `
+                    + `${errText(error)}`);
+                return undefined;
+            }
+        };
+        return {
+            dbPath,
+            status: { ok: true, schemaVersion },
+            searchSpace: (project) => {
+                try {
+                    const identities = identityCandidates(project);
+                    if (identities.length === 0)
+                        return undefined;
+                    const auto = peersFor(identities);
+                    const foreignIdentities = auto.members.flatMap(candidate => identityCandidates(candidate));
+                    return {
+                        identity: identities[0],
+                        ownIdentities: identities,
+                        foreignIdentities,
+                        members: auto.members,
+                        ...auto.domains === undefined ? {} : { domains: auto.domains },
+                        ...auto.shareCategories === undefined ? {} : { shareCategories: auto.shareCategories },
+                    };
+                }
+                catch {
+                    return undefined;
+                }
+            },
+            maxMemoryId: (project) => {
+                try {
+                    const identities = identityCandidates(project);
+                    const auto = peersFor(identities);
+                    const peerIdentities = auto.members.flatMap(candidate => identityCandidates(candidate));
+                    return maxVisibleId(identities, peerIdentities, auto.shareCategories ?? DEFAULT_SHARE_CATEGORIES, Date.now());
+                }
+                catch {
+                    return 0;
+                }
+            },
+            maxMemoryMutationId: (project) => {
+                try {
+                    const identities = identityCandidates(project);
+                    const peers = peersFor(identities).members.flatMap(candidate => identityCandidates(candidate));
+                    return maxMutationFor([...identities, ...peers]);
+                }
+                catch {
+                    return 0;
+                }
+            },
+            projectMemoryEpochFingerprint: (project) => {
+                try {
+                    const identities = identityCandidates(project);
+                    const peers = peersFor(identities).members.flatMap(candidate => identityCandidates(candidate));
+                    return epochFingerprint([...identities, ...peers]);
+                }
+                catch {
+                    return '';
+                }
+            },
+            mutations: readMutations,
+            profileRecall: (request) => {
+                try {
+                    if (profileStatement === undefined)
+                        return undefined;
+                    const rows = profileStatement.all().map(row => ({
+                        id: row.id,
+                        content: row.content,
+                        promotedAt: row.promoted_at ?? row.id,
+                        updatedAt: row.updated_at ?? row.promoted_at ?? row.id,
+                    }));
+                    if (rows.length === 0)
+                        return undefined;
+                    const budget = request.budgetTokens ?? PROFILE_M0_BUDGET_TOKENS;
+                    const watermark = request.maxId;
+                    const pool = watermark === undefined ? rows : rows.filter(row => row.id <= watermark);
+                    const additions = watermark === undefined ? [] : rows.filter(row => row.id > watermark);
+                    const pick = (candidates, tokens) => {
+                        const selected = [];
+                        let used = 0;
+                        for (const row of candidates) {
+                            const cost = estimateTokens(renderProfileLine(row));
+                            // `continue`, not `break`: one expensive entry must not hide the
+                            // cheaper ones behind it (the same rule the memory picker keeps).
+                            if (used + cost > tokens)
+                                continue;
+                            used += cost;
+                            selected.push(row);
+                        }
+                        return selected;
+                    };
+                    const selectedPool = pick(pool, budget);
+                    const selectedDelta = pick(additions, Math.max(1, Math.floor(budget * 0.25)));
+                    if (selectedPool.length === 0 && selectedDelta.length === 0 && rows.length === 0)
+                        return undefined;
+                    const digestOf = (list) => createHash('sha1').update(list.map(row => `${String(row.id)}:${String(row.updatedAt)}`).join('|')).digest('hex');
+                    return {
+                        rows: selectedPool,
+                        lines: selectedPool.map(renderProfileLine),
+                        digest: digestOf(pool),
+                        foldDigest: digestOf(rows),
+                        newRows: selectedDelta,
+                        newLines: selectedDelta.map(renderProfileLine),
+                        currentMaxId: rows.reduce((max, row) => Math.max(max, row.id), 0),
+                    };
+                }
+                catch (error) {
+                    options.logger.warn(`magic-context profile read failed (continuing without it): ${errText(error)}`);
+                    return undefined;
+                }
+            },
+            recall: (request) => {
+                try {
+                    // B3 (MC single_store_reads): one deferred read transaction so the
+                    // pool query, the max and the watermark observe ONE snapshot — a
+                    // concurrent writer between statements must not tear the digest.
+                    db.exec('BEGIN');
+                    try {
+                        const identities = identityCandidates(request.project);
+                        const auto = peersFor(identities);
+                        const rows = [];
+                        const seen = new Set();
+                        for (const identity of identities) {
+                            for (const raw of selfStatement.all(identity, request.now)) {
+                                const row = toRow(raw);
+                                if (!seen.has(row.id)) {
+                                    seen.add(row.id);
+                                    rows.push(row);
+                                }
+                            }
+                        }
+                        const shared = new Set(request.shareCategories ?? auto.shareCategories ?? DEFAULT_SHARE_CATEGORIES);
+                        const peers = request.domainProjects ?? auto.members;
+                        const peerIdentities = peers.flatMap(candidate => identityCandidates(candidate));
+                        for (const identity of peerIdentities) {
+                            for (const raw of foreignStatement.all(identity, request.now)) {
+                                const row = toRow(raw);
+                                if (seen.has(row.id))
+                                    continue;
+                                if (identities.includes(row.projectPath))
+                                    continue;
+                                if (!shared.has(row.category))
+                                    continue;
+                                seen.add(row.id);
+                                rows.push(row);
+                            }
+                        }
+                        const context = {
+                            ...identities[0] === undefined ? {} : { identity: identities[0] },
+                            ...auto.domains === undefined ? {} : { domains: auto.domains },
+                            members: peers,
+                        };
+                        if (rows.length === 0)
+                            return undefined;
+                        const needle = request.query?.trim().toLowerCase();
+                        const filtered = needle === undefined || needle.length === 0
+                            ? rows
+                            : rows.filter(row => row.content.toLowerCase().includes(needle) || row.category.toLowerCase().includes(needle));
+                        if (filtered.length === 0)
+                            return undefined;
+                        // S(t) decay scoring (schema v7): retired rows drop out of the
+                        // injection pool but stay in eligibleIds — searchable, and
+                        // `<memory-updates>` pointers for them stay resolvable. The picker
+                        // prefers hotter rows (score desc, MC priority as the tiebreak);
+                        // the RENDER order below stays MC's category order, so the injected
+                        // block still reads like the OpenCode/Pi block.
+                        const scoring = request.scoring;
+                        const scoringActive = scoring !== undefined && scoring.config.enabled;
+                        const retiredIds = new Set();
+                        const scoreOf = (row) => {
+                            if (scoring === undefined)
+                                return 0;
+                            const stat = scoring.statsById.get(row.id);
+                            return scoreMemory({
+                                importance: row.importance,
+                                category: row.category,
+                                hits: stat?.hits ?? 0,
+                                ...stat?.lastHitAt === undefined ? {} : { lastHitAt: stat.lastHitAt },
+                            }, scoring.config, request.now);
+                        };
+                        if (scoringActive && scoring !== undefined) {
+                            for (const row of filtered) {
+                                const stat = scoring.statsById.get(row.id);
+                                if (stat?.localArchived === true || scoreOf(row) < scoring.config.archiveThreshold) {
+                                    retiredIds.add(row.id);
+                                }
+                            }
+                        }
+                        // The additive lane: rows above the stored watermark are in-session
+                        // additions and render in m[1], so they never disturb the m[0] pool
+                        // digest below (Magic Context's maxMemoryId contract).
+                        const watermark = request.maxMemoryId;
+                        const pool = watermark === undefined ? filtered : filtered.filter(row => row.id <= watermark);
+                        const additions = watermark === undefined ? [] : filtered.filter(row => row.id > watermark);
+                        const pick = (candidates, budgetTokens) => {
+                            // Priority order picks the budget (S(t) score desc first when the
+                            // decay scoring is on, MC priority as the tiebreak); the render
+                            // order is MC's category order, so the injected block reads like
+                            // the OpenCode/Pi block.
+                            const usable = scoringActive
+                                ? candidates.filter(row => !retiredIds.has(row.id))
+                                : candidates;
+                            const selected = [];
+                            let used = 0;
+                            const ranked = scoringActive
+                                ? [...usable].sort((left, right) => scoreOf(right) - scoreOf(left) || comparePriority(left, right))
+                                : [...usable].sort(comparePriority);
+                            for (const row of ranked) {
+                                if (selected.length >= request.limit)
+                                    break;
+                                const cost = estimateTokens(renderMemoryLine(row));
+                                if (used + cost > budgetTokens)
+                                    continue;
+                                used += cost;
+                                selected.push(row);
+                            }
+                            return selected;
+                        };
+                        const poolSelected = pick(pool, request.budgetTokens);
+                        // MC budgets the additions at 25% of the memory injection budget.
+                        const deltaSelected = pick(additions, Math.max(1, Math.floor(request.budgetTokens * 0.25)));
+                        if (poolSelected.length === 0 && deltaSelected.length === 0)
+                            return undefined;
+                        const order = (selected) => [...selected].sort((left, right) => categoryRank(left.category) - categoryRank(right.category) || right.updatedAt - left.updatedAt);
+                        const orderedPool = order(poolSelected);
+                        const orderedAdditions = order(deltaSelected);
+                        // Digest covers the m[0] pool ONLY: a new memory may not bust the cache.
+                        const digest = createHash('sha1')
+                            .update(orderedPool.map(row => `${String(row.id)}:${String(row.updatedAt)}`).join('|'))
+                            .digest('hex');
+                        // B1: visibility-qualified max (own eligible + peers eligible AND shared).
+                        const currentMaxMemoryId = maxVisibleId(identities, peerIdentities, [...shared], request.now);
+                        return {
+                            rows: orderedPool,
+                            lines: orderedPool.map(renderMemoryLine),
+                            digest,
+                            newRows: orderedAdditions,
+                            newLines: orderedAdditions.map(renderMemoryLine),
+                            currentMaxMemoryId,
+                            eligibleIds: rows.map(row => row.id),
+                            eligibleRows: rows,
+                            ...context,
+                        };
+                    }
+                    finally {
+                        // COMMIT ends the read snapshot; a failed body leaves the tx
+                        // aborted and the END is a no-op (readonly — nothing to roll back).
+                        try {
+                            db.exec('COMMIT');
+                        }
+                        catch {
+                            /* aborted transaction */
+                        }
+                    }
+                }
+                catch (error) {
+                    options.logger.warn(`magic-context memory recall failed (continuing without memories): ${errText(error)}`);
+                    return undefined;
+                }
+            },
+            close: () => db.close(),
+        };
+    }
+    catch (error) {
+        try {
+            db.close();
+        }
+        catch {
+            /* best effort */
+        }
+        return unavailable(`probe failed (${errText(error)})`);
+    }
+}