@elvisw/dsh-magic-context 0.0.0-bootstrap.0 → 0.0.0-stage

package/lib/core/memory-bridge.js

@@ -1,818 +0,0 @@
-/**
- * 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)})`);
-    }
-}