@unson/brainbase-mcp 0.1.0

package/dist/ssot.js

@@ -0,0 +1,387 @@
+import { randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { access, copyFile, mkdir, readFile, readdir, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { hostname } from 'node:os';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { assertOntologyValid } from './ontology.js';
+import { emptyGraph, emptyRelationships, schemaTemplates } from './templates.js';
+const canonicalFiles = ['graph.json', 'relationships.json', 'personal-kg.jsonl', 'decisions.jsonl'];
+const lockName = '.brainbase-ssot.lock';
+const stagingPrefix = '.brainbase-staging-';
+const transactionPrefix = '.brainbase-transaction-';
+const graphEntitySchema = z.object({
+    id: z.string().min(1),
+    type: z.enum(['person', 'org', 'project', 'relationship']),
+    name: z.string().min(1),
+    summary: z.string().optional(),
+    tags: z.array(z.string()).optional(),
+    metadata: z.record(z.unknown()).optional()
+});
+const graphSchema = z.object({
+    version: z.literal(1),
+    owner: z.object({
+        name: z.string().optional(),
+        summary: z.string().optional()
+    }).optional(),
+    entities: z.array(graphEntitySchema)
+});
+const personalKgSchema = z.object({
+    id: z.string().min(1),
+    type: z.enum(['self', 'work', 'relationship', 'value', 'judgment', 'experience', 'sns_context']),
+    text: z.string().min(1),
+    tags: z.array(z.string()).optional(),
+    source: z.string().optional(),
+    updatedAt: z.string().optional()
+});
+const relationshipSchema = z.object({
+    id: z.string().min(1),
+    person: z.string().min(1),
+    role: z.string().optional(),
+    context: z.string().min(1),
+    tags: z.array(z.string()).optional(),
+    updatedAt: z.string().optional()
+});
+const relationshipsSchema = z.object({
+    version: z.literal(1),
+    relationships: z.array(relationshipSchema)
+});
+const decisionSchema = z.object({
+    id: z.string().min(1),
+    title: z.string().min(1),
+    decision: z.string().min(1),
+    topic: z.string().min(1).optional(),
+    supersedes: z.array(z.string().min(1)).optional(),
+    effectiveAt: z.string().datetime({ offset: true }).optional(),
+    rationale: z.string().optional(),
+    tags: z.array(z.string()).optional(),
+    updatedAt: z.string().optional()
+});
+export async function initializePersonalOs(dataDir) {
+    await mkdir(dataDir, { recursive: true });
+    await withSsotLock(dataDir, async () => {
+        await recoverTransactions(dataDir);
+        const present = await canonicalPresence(dataDir);
+        if (present.length === canonicalFiles.length) {
+            await ensureAncillaryDirectories(dataDir);
+            return;
+        }
+        if (present.length > 0) {
+            throw new Error(`Partial canonical SSOT set in ${dataDir}: found ${present.join(', ')}`);
+        }
+        await ensureAncillaryDirectories(dataDir);
+        await commitAggregate(dataDir, {
+            dataDir,
+            graph: emptyGraph,
+            relationships: emptyRelationships,
+            personalKg: [],
+            decisions: [],
+            sourceCount: 0
+        }, 'initialization');
+    });
+}
+export async function loadPersonalOs(dataDir) {
+    return withSsotLock(dataDir, async () => {
+        await recoverTransactions(dataDir);
+        assertCompleteCanonicalSet(dataDir, await canonicalPresence(dataDir));
+        return loadPersonalOsUnlocked(dataDir);
+    });
+}
+export async function mutatePersonalOs(dataDir, mutator) {
+    return withSsotLock(dataDir, async () => {
+        await recoverTransactions(dataDir);
+        assertCompleteCanonicalSet(dataDir, await canonicalPresence(dataDir));
+        const current = await loadPersonalOsUnlocked(dataDir);
+        const next = await mutator(current);
+        const normalized = { ...next, dataDir, sourceCount: current.sourceCount };
+        validateAggregate(normalized);
+        await commitAggregate(dataDir, normalized, 'mutation');
+        return normalized;
+    });
+}
+async function loadPersonalOsUnlocked(dataDir) {
+    const graph = graphSchema.parse(await readJson(join(dataDir, 'graph.json')));
+    const relationships = relationshipsSchema.parse(await readJson(join(dataDir, 'relationships.json')));
+    const personalKg = await readJsonl(join(dataDir, 'personal-kg.jsonl'), personalKgSchema, 'personal-kg.jsonl');
+    const decisions = await readJsonl(join(dataDir, 'decisions.jsonl'), decisionSchema, 'decisions.jsonl');
+    const sourceCount = await countSources(dataDir);
+    return { dataDir, graph, personalKg, relationships, decisions, sourceCount };
+}
+async function commitAggregate(dataDir, next, mode) {
+    validateAggregate(next);
+    const id = randomUUID();
+    const stagingDir = join(dataDir, `${stagingPrefix}${id}`);
+    const transactionDir = join(dataDir, `${transactionPrefix}${id}`);
+    const nextDir = join(stagingDir, 'next');
+    const previousDir = join(stagingDir, 'previous');
+    await mkdir(nextDir, { recursive: true });
+    await writeAggregate(nextDir, next);
+    if (mode === 'mutation') {
+        await mkdir(previousDir, { recursive: true });
+        await copyCanonicalSet(dataDir, previousDir);
+    }
+    const metadata = { version: 1, mode };
+    await writeFile(join(stagingDir, 'transaction.json'), `${JSON.stringify(metadata, null, 2)}\n`);
+    await writeFile(join(stagingDir, 'PREPARED'), '');
+    await rename(stagingDir, transactionDir);
+    try {
+        await publishCanonicalSet(dataDir, join(transactionDir, 'next'), id, true);
+        await writeFile(join(transactionDir, 'COMMITTED'), '');
+    }
+    catch (error) {
+        await recoverTransaction(dataDir, transactionDir).catch(() => undefined);
+        throw error;
+    }
+    await cleanupCommittedTransaction(transactionDir);
+}
+async function cleanupCommittedTransaction(transactionDir) {
+    try {
+        if (process.env.BRAINBASE_SSOT_FAIL_COMMITTED_CLEANUP === '1') {
+            throw new Error('Injected committed SSOT transaction cleanup failure');
+        }
+        await rm(transactionDir, { recursive: true, force: true });
+    }
+    catch (error) {
+        warnCleanupFailure(`committed SSOT transaction ${transactionDir}`, error);
+    }
+}
+async function recoverTransactions(dataDir) {
+    const entries = await readdir(dataDir);
+    for (const entry of entries.filter((value) => value.startsWith(stagingPrefix)).sort()) {
+        await rm(join(dataDir, entry), { recursive: true, force: true });
+    }
+    for (const entry of entries.filter((value) => value.startsWith(transactionPrefix)).sort()) {
+        await recoverTransaction(dataDir, join(dataDir, entry));
+    }
+}
+async function recoverTransaction(dataDir, transactionDir) {
+    if (await exists(join(transactionDir, 'COMMITTED'))) {
+        await rm(transactionDir, { recursive: true, force: true });
+        return;
+    }
+    if (!(await exists(join(transactionDir, 'PREPARED')))) {
+        throw new Error(`Incomplete registered SSOT transaction ${transactionDir}`);
+    }
+    const metadata = await readTransactionMetadata(transactionDir);
+    const retainedDir = join(transactionDir, metadata.mode === 'initialization' ? 'next' : 'previous');
+    assertCompleteCanonicalSet(retainedDir, await canonicalPresence(retainedDir));
+    if (process.env.BRAINBASE_SSOT_FAIL_RECOVERY === '1') {
+        throw new Error(`Injected SSOT transaction recovery failure for ${transactionDir}`);
+    }
+    await publishCanonicalSet(dataDir, retainedDir, `recovery-${randomUUID()}`, false);
+    await rm(transactionDir, { recursive: true, force: true });
+}
+async function publishCanonicalSet(dataDir, retainedDir, token, allowInjectedFailure) {
+    let published = 0;
+    const failAfter = Number.parseInt(process.env.BRAINBASE_SSOT_FAIL_AFTER_PUBLISH ?? '', 10);
+    const pauseAfterPublishMs = parsePositiveInteger(process.env.BRAINBASE_SSOT_PAUSE_AFTER_PUBLISH_MS, 0);
+    for (const fileName of canonicalFiles) {
+        const temporary = join(dataDir, `.brainbase-${fileName}-${token}.tmp`);
+        await copyFile(join(retainedDir, fileName), temporary);
+        await rename(temporary, join(dataDir, fileName));
+        published += 1;
+        if (allowInjectedFailure && pauseAfterPublishMs > 0) {
+            await delay(pauseAfterPublishMs);
+        }
+        if (allowInjectedFailure && Number.isFinite(failAfter) && published === failAfter) {
+            throw new Error(`Injected SSOT publish failure after ${published} file(s)`);
+        }
+    }
+}
+async function writeAggregate(targetDir, os) {
+    await writeFile(join(targetDir, 'graph.json'), `${JSON.stringify(os.graph, null, 2)}\n`);
+    await writeFile(join(targetDir, 'relationships.json'), `${JSON.stringify(os.relationships, null, 2)}\n`);
+    await writeFile(join(targetDir, 'personal-kg.jsonl'), serializeJsonl(os.personalKg));
+    await writeFile(join(targetDir, 'decisions.jsonl'), serializeJsonl(os.decisions));
+}
+function validateAggregate(os) {
+    graphSchema.parse(os.graph);
+    relationshipsSchema.parse(os.relationships);
+    os.personalKg.forEach((entry) => personalKgSchema.parse(entry));
+    os.decisions.forEach((decision) => decisionSchema.parse(decision));
+    assertOntologyValid(os);
+}
+function serializeJsonl(values) {
+    return values.length === 0 ? '' : `${values.map((value) => JSON.stringify(value)).join('\n')}\n`;
+}
+async function copyCanonicalSet(sourceDir, targetDir) {
+    for (const fileName of canonicalFiles) {
+        await copyFile(join(sourceDir, fileName), join(targetDir, fileName));
+    }
+}
+async function ensureAncillaryDirectories(dataDir) {
+    for (const relative of ['sources', 'sources/gmail', 'sources/calendar', 'sources/drive', 'sources/tasks', 'candidates', 'schemas']) {
+        await mkdir(join(dataDir, relative), { recursive: true });
+    }
+    for (const [fileName, schema] of Object.entries(schemaTemplates)) {
+        await writeFile(join(dataDir, 'schemas', fileName), `${JSON.stringify(schema, null, 2)}\n`, { flag: 'wx' }).catch((error) => {
+            if (error.code !== 'EEXIST')
+                throw error;
+        });
+    }
+}
+async function withSsotLock(dataDir, operation) {
+    await mkdir(dataDir, { recursive: true });
+    const owner = await acquireLock(dataDir);
+    try {
+        return await operation();
+    }
+    finally {
+        await releaseLock(dataDir, owner).catch((error) => {
+            warnCleanupFailure(`canonical SSOT lock ${join(dataDir, lockName)}`, error);
+        });
+    }
+}
+async function acquireLock(dataDir) {
+    const lockDir = join(dataDir, lockName);
+    const timeoutMs = parsePositiveInteger(process.env.BRAINBASE_SSOT_LOCK_TIMEOUT_MS, 5_000);
+    const retryMs = parsePositiveInteger(process.env.BRAINBASE_SSOT_LOCK_RETRY_MS, 20);
+    const deadline = Date.now() + timeoutMs;
+    const owner = { token: randomUUID(), pid: process.pid, hostname: hostname() };
+    while (true) {
+        try {
+            await mkdir(lockDir);
+            await writeFile(join(lockDir, 'owner.json'), `${JSON.stringify(owner)}\n`, { flag: 'wx' });
+            return owner;
+        }
+        catch (error) {
+            const code = error.code;
+            if (code !== 'EEXIST') {
+                await rm(lockDir, { recursive: true, force: true }).catch(() => undefined);
+                throw error;
+            }
+            await quarantineDeadSameHostLock(dataDir, lockDir);
+            if (Date.now() >= deadline) {
+                throw new Error(`Timed out waiting for canonical SSOT lock ${lockDir}`);
+            }
+            await delay(retryMs);
+        }
+    }
+}
+async function quarantineDeadSameHostLock(dataDir, lockDir) {
+    const current = await readLockOwner(lockDir);
+    if (!current || current.hostname !== hostname() || isProcessAlive(current.pid))
+        return;
+    const quarantine = join(dataDir, `.brainbase-ssot-lock-stale-${randomUUID()}`);
+    try {
+        await rename(lockDir, quarantine);
+        await rm(quarantine, { recursive: true, force: true });
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+}
+async function releaseLock(dataDir, owner) {
+    const lockDir = join(dataDir, lockName);
+    const current = await readLockOwner(lockDir);
+    if (current?.token === owner.token) {
+        await rm(lockDir, { recursive: true, force: true });
+    }
+}
+async function readLockOwner(lockDir) {
+    try {
+        const value = JSON.parse(await readFile(join(lockDir, 'owner.json'), 'utf8'));
+        if (typeof value.token === 'string' && typeof value.pid === 'number' && typeof value.hostname === 'string') {
+            return value;
+        }
+    }
+    catch {
+        // Missing or malformed owner metadata is never safe to steal.
+    }
+    return undefined;
+}
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code !== 'ESRCH';
+    }
+}
+async function canonicalPresence(dataDir) {
+    const result = [];
+    for (const fileName of canonicalFiles) {
+        if (await exists(join(dataDir, fileName)))
+            result.push(fileName);
+    }
+    return result;
+}
+function assertCompleteCanonicalSet(dataDir, present) {
+    if (present.length !== canonicalFiles.length) {
+        throw new Error(`Partial canonical SSOT set in ${dataDir}: found ${present.join(', ') || 'none'}`);
+    }
+}
+async function readTransactionMetadata(transactionDir) {
+    const value = await readJson(join(transactionDir, 'transaction.json'));
+    if (value.version !== 1 || (value.mode !== 'initialization' && value.mode !== 'mutation')) {
+        throw new Error(`Invalid registered SSOT transaction metadata in ${transactionDir}`);
+    }
+    return value;
+}
+async function exists(path) {
+    try {
+        await access(path, constants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function readJson(filePath) {
+    try {
+        return JSON.parse(await readFile(filePath, 'utf8'));
+    }
+    catch (error) {
+        throw new Error(`Failed to read canonical SSOT file ${filePath}: ${formatError(error)}`);
+    }
+}
+async function readJsonl(filePath, schema, label) {
+    let content = '';
+    try {
+        content = await readFile(filePath, 'utf8');
+    }
+    catch (error) {
+        throw new Error(`Failed to read canonical SSOT file ${filePath}: ${formatError(error)}`);
+    }
+    const rows = content.split('\n').map((line) => line.trim()).filter(Boolean);
+    return rows.map((line, index) => {
+        try {
+            return schema.parse(JSON.parse(line));
+        }
+        catch (error) {
+            throw new Error(`Invalid ${label} line ${index + 1}: ${formatError(error)}`);
+        }
+    });
+}
+async function countSources(dataDir) {
+    return countSourceFiles(join(dataDir, 'sources'));
+}
+async function countSourceFiles(sourceDir) {
+    try {
+        const entries = await readdir(sourceDir);
+        const counts = await Promise.all(entries.filter((entry) => !entry.startsWith('.')).map(async (entry) => {
+            const entryPath = join(sourceDir, entry);
+            const entryStat = await stat(entryPath);
+            return entryStat.isDirectory() ? countSourceFiles(entryPath) : entryStat.isFile() ? 1 : 0;
+        }));
+        return counts.reduce((sum, count) => sum + count, 0);
+    }
+    catch {
+        return 0;
+    }
+}
+function parsePositiveInteger(value, fallback) {
+    const parsed = Number.parseInt(value ?? '', 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+function delay(milliseconds) {
+    return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+function formatError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function warnCleanupFailure(resource, error) {
+    process.emitWarning(`Failed to clean up ${resource}: ${formatError(error)}`);
+}

package/dist/templates.d.ts

@@ -0,0 +1,4 @@
+import type { GraphFile, RelationshipsFile } from './types.js';
+export declare const emptyGraph: GraphFile;
+export declare const emptyRelationships: RelationshipsFile;
+export declare const schemaTemplates: Record<string, unknown>;

package/dist/templates.js

@@ -0,0 +1,89 @@
+export const emptyGraph = {
+    version: 1,
+    owner: {},
+    entities: []
+};
+export const emptyRelationships = {
+    version: 1,
+    relationships: []
+};
+export const schemaTemplates = {
+    'graph.schema.json': {
+        type: 'object',
+        required: ['version', 'entities'],
+        properties: {
+            version: { const: 1 },
+            owner: {
+                type: 'object',
+                properties: {
+                    name: { type: 'string' },
+                    summary: { type: 'string' }
+                }
+            },
+            entities: {
+                type: 'array',
+                items: {
+                    type: 'object',
+                    required: ['id', 'type', 'name'],
+                    properties: {
+                        id: { type: 'string', minLength: 1 },
+                        type: { enum: ['person', 'org', 'project', 'relationship'] },
+                        name: { type: 'string', minLength: 1 },
+                        summary: { type: 'string' },
+                        tags: { type: 'array', items: { type: 'string' } },
+                        metadata: { type: 'object' }
+                    }
+                }
+            }
+        }
+    },
+    'personal-kg.schema.json': {
+        type: 'object',
+        required: ['id', 'type', 'text'],
+        properties: {
+            id: { type: 'string', minLength: 1 },
+            type: { enum: ['self', 'work', 'relationship', 'value', 'judgment', 'experience', 'sns_context'] },
+            text: { type: 'string', minLength: 1 },
+            tags: { type: 'array', items: { type: 'string' } },
+            source: { type: 'string' },
+            updatedAt: { type: 'string' }
+        }
+    },
+    'relationships.schema.json': {
+        type: 'object',
+        required: ['version', 'relationships'],
+        properties: {
+            version: { const: 1 },
+            relationships: {
+                type: 'array',
+                items: {
+                    type: 'object',
+                    required: ['id', 'person', 'context'],
+                    properties: {
+                        id: { type: 'string', minLength: 1 },
+                        person: { type: 'string', minLength: 1 },
+                        role: { type: 'string' },
+                        context: { type: 'string', minLength: 1 },
+                        tags: { type: 'array', items: { type: 'string' } },
+                        updatedAt: { type: 'string' }
+                    }
+                }
+            }
+        }
+    },
+    'decisions.schema.json': {
+        type: 'object',
+        required: ['id', 'title', 'decision'],
+        properties: {
+            id: { type: 'string', minLength: 1 },
+            title: { type: 'string', minLength: 1 },
+            decision: { type: 'string', minLength: 1 },
+            rationale: { type: 'string' },
+            topic: { type: 'string', minLength: 1 },
+            supersedes: { type: 'array', items: { type: 'string', minLength: 1 } },
+            effectiveAt: { type: 'string', format: 'date-time' },
+            tags: { type: 'array', items: { type: 'string' } },
+            updatedAt: { type: 'string' }
+        }
+    }
+};

package/dist/tools.d.ts

@@ -0,0 +1,6 @@
+import type { EntityKind, PersonalOs, SearchResult } from './types.js';
+export declare function getContext(os: PersonalOs): Record<string, unknown>;
+export declare function listEntities(os: PersonalOs, type?: EntityKind): Record<string, unknown>;
+export declare function searchPersonalKg(os: PersonalOs, query: string, limit?: number): SearchResult[];
+export declare function searchAll(os: PersonalOs, query: string, limit?: number): SearchResult[];
+export declare function onboardingStatus(os: PersonalOs): Record<string, unknown>;

package/dist/tools.js

@@ -0,0 +1,180 @@
+import { buildOperationalizationPlan } from './operationalization.js';
+export function getContext(os) {
+    const selfEntries = os.personalKg.filter((entry) => entry.type === 'self' || entry.type === 'value' || entry.type === 'judgment');
+    const workEntries = os.personalKg.filter((entry) => entry.type === 'work' || entry.type === 'experience');
+    const projects = os.graph.entities.filter((entity) => entity.type === 'project').map((entity) => ({
+        id: entity.id,
+        name: entity.name,
+        summary: entity.summary,
+        goal: readMetadataString(entity.metadata, 'goal'),
+        status: readMetadataString(entity.metadata, 'status'),
+        role: readMetadataString(entity.metadata, 'role'),
+        sources: Array.isArray(entity.metadata?.sources) ? entity.metadata.sources : [],
+        taskSources: Array.isArray(entity.metadata?.taskSources) ? entity.metadata.taskSources : [],
+        decisionPrinciples: Array.isArray(entity.metadata?.decisionPrinciples) ? entity.metadata.decisionPrinciples : []
+    }));
+    return {
+        owner: os.graph.owner ?? {},
+        self: selfEntries.map((entry) => entry.text),
+        projects,
+        work: [
+            ...projects.map((project) => project.summary ? `${project.name}: ${project.summary}` : project.name),
+            ...workEntries.map((entry) => entry.text)
+        ],
+        relationships: os.relationships.relationships.map((relationship) => ({
+            person: relationship.person,
+            role: relationship.role,
+            context: relationship.context
+        })),
+        decisions: os.decisions.map((decision) => ({
+            title: decision.title,
+            decision: decision.decision,
+            rationale: decision.rationale
+        })),
+        canonicalFiles: ['graph.json', 'personal-kg.jsonl', 'relationships.json', 'decisions.jsonl'],
+        note: 'Canonical local SSOT data is preferred over raw sources.'
+    };
+}
+export function listEntities(os, type) {
+    const graphEntities = os.graph.entities.filter((entity) => !type || entity.type === type);
+    const relationshipEntities = type && type !== 'relationship'
+        ? []
+        : os.relationships.relationships.map((relationship) => ({
+            id: relationship.id,
+            type: 'relationship',
+            name: relationship.person,
+            summary: relationship.context,
+            tags: relationship.tags
+        }));
+    const decisionEntities = type && type !== 'decision'
+        ? []
+        : os.decisions.map((decision) => ({
+            id: decision.id,
+            type: 'decision',
+            name: decision.title,
+            summary: decision.decision,
+            tags: decision.tags
+        }));
+    return {
+        entities: [...graphEntities, ...relationshipEntities, ...decisionEntities]
+    };
+}
+export function searchPersonalKg(os, query, limit = 10) {
+    return rank(os.personalKg.map((entry) => ({
+        source: 'personal-kg',
+        id: entry.id,
+        title: entry.type,
+        text: entry.text,
+        score: scoreText(query, [entry.id, entry.type, entry.text, ...(entry.tags ?? [])])
+    })), limit);
+}
+export function searchAll(os, query, limit = 10) {
+    const graphResults = os.graph.entities.map((entity) => ({
+        source: 'graph',
+        id: entity.id,
+        title: entity.name,
+        text: [entity.summary ?? entity.name, metadataText(entity.metadata)].filter(Boolean).join('\n'),
+        score: scoreText(query, [entity.id, entity.type, entity.name, entity.summary ?? '', metadataText(entity.metadata), ...(entity.tags ?? [])])
+    }));
+    const relationshipResults = os.relationships.relationships.map((relationship) => ({
+        source: 'relationships',
+        id: relationship.id,
+        title: relationship.person,
+        text: relationship.context,
+        score: scoreText(query, [relationship.id, relationship.person, relationship.role ?? '', relationship.context, ...(relationship.tags ?? [])])
+    }));
+    const decisionResults = os.decisions.map((decision) => ({
+        source: 'decisions',
+        id: decision.id,
+        title: decision.title,
+        text: [decision.decision, decision.rationale ?? ''].filter(Boolean).join('\n'),
+        score: scoreText(query, [decision.id, decision.title, decision.decision, decision.rationale ?? '', ...(decision.tags ?? [])])
+    }));
+    return rank([...graphResults, ...searchPersonalKg(os, query, limit), ...relationshipResults, ...decisionResults], limit);
+}
+export function onboardingStatus(os) {
+    const seeded = {
+        self: Boolean(os.graph.owner?.name) || os.personalKg.some((entry) => entry.type === 'self'),
+        work: os.graph.entities.some((entity) => entity.type === 'project') || os.personalKg.some((entry) => entry.type === 'work'),
+        relationships: os.relationships.relationships.length > 0
+    };
+    const missing = Object.entries(seeded)
+        .filter(([, value]) => !value)
+        .map(([key]) => key);
+    const valueDemoReady = missing.length === 0;
+    const operationalization = buildOperationalizationPlan({
+        dataDir: os.dataDir,
+        firstValueReady: valueDemoReady
+    });
+    return {
+        connected: true,
+        dataDir: os.dataDir,
+        seeded,
+        missing,
+        valueDemo: {
+            ready: valueDemoReady,
+            missing,
+            command: 'brainbase onboard:demo --scenario "<real request>"',
+            completionSignal: valueDemoReady ? 'first_value_demo_ready' : 'needs_seed'
+        },
+        operationalization,
+        counts: {
+            graphEntities: os.graph.entities.length,
+            personalKgEntries: os.personalKg.length,
+            relationships: os.relationships.relationships.length,
+            decisions: os.decisions.length,
+            rawSources: os.sourceCount
+        },
+        backend: 'local'
+    };
+}
+function rank(results, limit) {
+    return results
+        .filter((result) => result.score > 0)
+        .sort((a, b) => b.score - a.score || a.title.localeCompare(b.title))
+        .slice(0, Math.max(1, limit));
+}
+function scoreText(query, fields) {
+    const terms = searchTokens(query);
+    if (terms.length === 0) {
+        return 0;
+    }
+    const haystack = fields.join('\n').toLowerCase();
+    const phrase = query.trim().toLowerCase();
+    const matchedTerms = terms.filter((term) => haystack.includes(term));
+    if (phrase && haystack.includes(phrase)) {
+        return terms.length + 20;
+    }
+    if (matchedTerms.length === terms.length) {
+        return terms.length + 10;
+    }
+    return matchedTerms.length;
+}
+function searchTokens(query) {
+    const seen = new Set();
+    return query
+        .normalize('NFKC')
+        .replace(/[|/\\,;:()[\]{}"'`“”‘’、。・･，．：；（）［］｛｝「」『』【】]/g, ' ')
+        .replace(/[-_]+/g, ' ')
+        .toLowerCase()
+        .split(/\s+/)
+        .map((term) => term.trim())
+        .filter(Boolean)
+        .filter((term) => {
+        if (seen.has(term)) {
+            return false;
+        }
+        seen.add(term);
+        return true;
+    });
+}
+function metadataText(metadata) {
+    if (!metadata) {
+        return '';
+    }
+    return JSON.stringify(metadata);
+}
+function readMetadataString(metadata, key) {
+    const value = metadata?.[key];
+    return typeof value === 'string' ? value : undefined;
+}