@unson/brainbase-mcp 0.2.4 → 0.3.0

package/dist/graph-diagnosis.js

@@ -0,0 +1,129 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { canonicalEdgeId, isActiveAt, validateCanonicalGraph } from './canonical-graph.js';
+import { getCanonicalRelation } from './relation-registry.js';
+export async function diagnoseGraph(dataDir, asOf = new Date().toISOString()) {
+    let graph;
+    let rawGraph;
+    try {
+        rawGraph = await readFile(join(dataDir, 'graph.json'), 'utf8');
+    }
+    catch (error) {
+        return emptyDiagnosis('unavailable', asOf, [{ class: 'unavailable', detail: error instanceof Error ? error.message : String(error) }]);
+    }
+    try {
+        graph = JSON.parse(rawGraph);
+    }
+    catch {
+        return emptyDiagnosis('invalid', asOf, [{ class: 'invalid', detail: 'graph.json is not valid JSON.' }]);
+    }
+    const schemaVersion = typeof graph?.version === 'number' ? graph.version : null;
+    const entities = Array.isArray(graph?.entities) ? graph.entities : [];
+    const edges = Array.isArray(graph?.edges) ? graph.edges : [];
+    const issues = [];
+    if (schemaVersion === 1)
+        issues.push({ class: 'migration', detail: 'Graph v1 must be migrated before ID-edge retrieval is available.' });
+    const entityIds = new Set();
+    let duplicateEntities = 0;
+    for (const entity of entities) {
+        if (typeof entity?.id !== 'string')
+            continue;
+        if (entityIds.has(entity.id))
+            duplicateEntities += 1;
+        entityIds.add(entity.id);
+    }
+    if (duplicateEntities > 0)
+        issues.push({ class: 'duplicate', detail: `${duplicateEntities} duplicate entity IDs` });
+    const edgeIds = new Set();
+    const tuples = new Set();
+    let danglingEdges = 0;
+    let invalidEdges = 0;
+    let duplicateEdges = 0;
+    let activeEdges = 0;
+    const entityById = new Map(entities.filter((entity) => typeof entity?.id === 'string').map((entity) => [entity.id, entity]));
+    for (const edge of edges) {
+        const tuple = JSON.stringify([edge?.fromId, edge?.relation, edge?.toId]);
+        const duplicate = edgeIds.has(edge?.id) || tuples.has(tuple);
+        if (duplicate) {
+            duplicateEdges += 1;
+            issues.push({ class: 'duplicate', recordId: String(edge?.id ?? ''), detail: 'Duplicate edge ID or tuple.' });
+        }
+        if (typeof edge?.id === 'string')
+            edgeIds.add(edge.id);
+        tuples.add(tuple);
+        const from = entityById.get(edge?.fromId);
+        const to = entityById.get(edge?.toId);
+        if (!from || !to) {
+            danglingEdges += 1;
+            issues.push({ class: 'dangling', recordId: String(edge?.id ?? ''), detail: 'Edge endpoint does not resolve to an entity ID.' });
+            continue;
+        }
+        let valid = true;
+        try {
+            const relation = getCanonicalRelation(edge.relation);
+            valid = from.type === relation.from && to.type === relation.to && edge.id === canonicalEdgeId(edge);
+            if (valid && !duplicate && isActiveAt(edge, asOf) && isActiveAt(from, asOf) && isActiveAt(to, asOf))
+                activeEdges += 1;
+        }
+        catch {
+            valid = false;
+        }
+        if (!valid) {
+            invalidEdges += 1;
+            issues.push({ class: 'invalid', recordId: String(edge?.id ?? ''), detail: 'Edge relation, endpoint types, stable ID, or validity interval is invalid.' });
+        }
+    }
+    const { projections, unresolvedRecords } = await diagnoseLegacyViews(dataDir, entities);
+    if (projections > 0)
+        issues.push({ class: 'projection', detail: `${projections} legacy records are projections of canonical entities.` });
+    if (unresolvedRecords > 0)
+        issues.push({ class: 'unresolved', detail: `${unresolvedRecords} legacy records do not resolve to a canonical entity ID.` });
+    let structurallyInvalid = false;
+    try {
+        validateCanonicalGraph(graph);
+    }
+    catch {
+        structurallyInvalid = true;
+    }
+    const status = schemaVersion === 1 ? 'migration_required' : structurallyInvalid ? 'invalid' : issues.length > 0 ? 'issues' : 'healthy';
+    return { status, schemaVersion, ontology: graph?.ontology ?? null, asOf, migrationRequired: schemaVersion === 1,
+        counts: { entities: entities.length, edges: edges.length, activeEdges, danglingEdges, invalidEdges, duplicateEdges, duplicateEntities, unresolvedRecords, projections }, issues };
+}
+async function diagnoseLegacyViews(dataDir, entities) {
+    const personKeys = canonicalKeys(entities.filter((entity) => entity.type === 'person'));
+    const decisionKeys = canonicalKeys(entities.filter((entity) => entity.type === 'decision'));
+    let projections = 0;
+    let unresolvedRecords = 0;
+    try {
+        const relationships = JSON.parse(await readFile(join(dataDir, 'relationships.json'), 'utf8')).relationships;
+        for (const record of Array.isArray(relationships) ? relationships : [])
+            personKeys.has(normalize(String(record.person ?? ''))) ? projections += 1 : unresolvedRecords += 1;
+    }
+    catch { /* loadPersonalOs reports sidecar errors */ }
+    try {
+        for (const row of (await readFile(join(dataDir, 'decisions.jsonl'), 'utf8')).split(/\r?\n/u).filter(Boolean)) {
+            const record = JSON.parse(row);
+            decisionKeys.has(String(record.id ?? '')) || decisionKeys.has(normalize(String(record.title ?? ''))) ? projections += 1 : unresolvedRecords += 1;
+        }
+    }
+    catch { /* loadPersonalOs reports sidecar errors */ }
+    return { projections, unresolvedRecords };
+}
+function canonicalKeys(entities) {
+    const candidates = new Map();
+    for (const entity of entities) {
+        const id = String(entity.id ?? '');
+        for (const key of [id, normalize(String(entity.name ?? '')), ...(Array.isArray(entity.aliases) ? entity.aliases.map((alias) => normalize(String(alias))) : [])]) {
+            if (!key)
+                continue;
+            const matches = candidates.get(key) ?? new Set();
+            matches.add(id);
+            candidates.set(key, matches);
+        }
+    }
+    return new Set([...candidates].filter(([, matches]) => matches.size === 1).map(([key]) => key));
+}
+function normalize(value) { return value.normalize('NFKC').replace(/\s+/g, '').toLowerCase(); }
+function emptyDiagnosis(status, asOf, issues) {
+    return { status, schemaVersion: null, ontology: null, asOf, migrationRequired: false, counts: { entities: 0, edges: 0, activeEdges: 0, danglingEdges: 0, invalidEdges: 0, duplicateEdges: 0, duplicateEntities: 0, unresolvedRecords: 0, projections: 0 }, issues };
+}

package/dist/guided-onboarding.js

@@ -70,7 +70,7 @@ export function buildGuidedFirstRun(input) {
         '--dir', input.dataDir,
         '--scenario', firstValueScenario
     ]);
-    const actualAgentPrompt = `Brainbaseのget_contextとsearchを使い、保存済み文脈を根拠に「${firstValueScenario}」へ回答してください。使った前提と未確認事項を分けてください。`;
+    const actualAgentPrompt = `Brainbaseのresolve_entity、get_context、searchを使い、保存済み文脈を根拠に「${firstValueScenario}」へ回答してください。使った正規ID、関係、前提、未確認事項を分けてください。`;
     const projectDryRunCommand = project
         ? projectCommand(input.dataDir, project.project.name, input.project, project.project.sources, false)
         : undefined;
@@ -132,7 +132,7 @@ export function buildGuidedFirstRun(input) {
             },
             {
                 id: 'doctor',
-                title: 'doctor と MCP get_context/search で確認する',
+                title: 'doctor と MCP resolve_entity/get_context/search で確認する',
                 when: 'MCP設定を実configへmergeし、対象エージェントを再起動した後',
                 command: operationalization.pending.find((item) => item.id === 'verification')?.command ?? command(['brainbase', 'doctor', '--dir', input.dataDir])
             },
@@ -202,9 +202,9 @@ export function buildGuidedFirstRun(input) {
         ],
         completionCheck: [
             'CLIサンプルは接続前プレビューであり、初回価値の達成証拠にしない。',
-            '新しい実エージェントがBrainbase MCPのget_context/searchを使って現実の依頼へ回答する。',
+            '新しい実エージェントがBrainbase MCPのresolve_entity/get_context/searchを使って現実の依頼へ回答する。',
             '実回答を見た本人が役立ったかを判断する。',
-            '完了報告には、公開skills、ohayo/oyasumi/retro、MCP実config merge、source allowlist/import/candidate review、MCP get_context/search確認の未完了タスクを必ず出す。',
+            '完了報告には、公開skills、ohayo/oyasumi/retro、MCP実config merge、source allowlist/import/candidate review、MCP resolve_entity/get_context/search確認の未完了タスクを必ず出す。',
             `${targetLabel(input.target)} のMCP設定に Brainbase が実登録されている。`,
             '最初のプロジェクトが get_context/search で見える。',
             '外部ソースは許可範囲、保存先、正本化前レビューの流れが説明できる。'

package/dist/import-extract.d.ts

@@ -1,4 +1,5 @@
-import type { DecisionRecord, GraphEntity, PersonalKgEntry, RelationshipRecord } from './types.js';
+import { type CanonicalWriteSet } from './canonical-edge-builder.js';
+import type { CanonicalEdge, CanonicalEntity, DecisionRecord, PersonalKgEntry, RelationshipRecord } from './types.js';
 export type SourceProvider = 'gmail' | 'calendar' | 'drive' | 'local';
 export interface GmailSourceRecord {
     kind: 'gmail';
@@ -86,14 +87,18 @@ export interface ExtractOptions {
 export declare function extractCandidates(records: SourceRecord[], options?: ExtractOptions): ExtractedCandidate[];
 export declare function buildExtractedCandidateSet(candidates: ExtractedCandidate[], dataDir: string): ExtractedCandidateSet;
 export interface ApplyInput {
-    graphEntities: GraphEntity[];
+    graphEntities: CanonicalEntity[];
+    graphEdges: CanonicalEdge[];
     relationships: RelationshipRecord[];
     personalKg: PersonalKgEntry[];
     decisions: DecisionRecord[];
     ownerName?: string;
+    provenanceSourceKind?: 'import' | 'onboarding';
 }
 export interface ApplyResult {
-    graphEntities: GraphEntity[];
+    graphEntities: CanonicalEntity[];
+    graphEdges: CanonicalEdge[];
+    canonicalWrites: CanonicalWriteSet;
     relationships: RelationshipRecord[];
     personalKgAdditions: PersonalKgEntry[];
     decisionAdditions: DecisionRecord[];

package/dist/import-extract.js

@@ -1,3 +1,4 @@
+import { buildCanonicalEdge } from './canonical-edge-builder.js';
 const PROVIDER_SOURCE_PATH = {
     gmail: 'sources/gmail/threads.jsonl',
     calendar: 'sources/calendar/events.jsonl',
@@ -306,13 +307,31 @@ export function loadApplyCandidates(raw) {
 }
 export function planApply(candidates, selection, base, now) {
     const graphEntities = [...base.graphEntities];
+    const graphEdges = [...base.graphEdges];
+    const canonicalWrites = { entities: [], edges: [] };
     const relationships = [...base.relationships];
     const personalKgAdditions = [];
     const decisionAdditions = [];
     const applied = [];
     const skipped = [];
     let ownerName = base.ownerName;
-    for (const candidate of candidates) {
+    const provenanceSourceKind = base.provenanceSourceKind ?? 'import';
+    const selectedCandidates = candidates.filter((candidate) => selection.all || selection.ids.has(candidate.id));
+    const availableProjectIds = new Set(graphEntities.filter((entity) => entity.type === 'project').map((entity) => entity.id));
+    const availableDecisionIds = new Set(graphEntities.filter((entity) => entity.type === 'decision').map((entity) => entity.id));
+    for (const candidate of selectedCandidates) {
+        if (candidate.kind === 'project') {
+            const name = payloadString(candidate.payload, 'name');
+            if (name)
+                availableProjectIds.add(`project-${stableHash(name)}`);
+        }
+        if (candidate.kind === 'decision') {
+            const text = payloadString(candidate.payload, 'decision') || payloadString(candidate.payload, 'text');
+            if (text)
+                availableDecisionIds.add(`decision-${stableHash(text)}`);
+        }
+    }
+    for (const candidate of [...candidates].sort((left, right) => left.id.localeCompare(right.id, 'en'))) {
         if (!selection.all && !selection.ids.has(candidate.id)) {
             skipped.push({ id: candidate.id, reason: 'not selected' });
             continue;
@@ -326,8 +345,8 @@ export function planApply(candidates, selection, base, now) {
                     break;
                 }
                 ownerName = name;
-                upsertEntity(graphEntities, { id: 'self', type: 'person', name, summary: 'Owner of this local Brainbase Personal OS.', tags: ['self'] });
-                personalKgAdditions.push({ id: `self-${stableHash(name)}`, type: 'self', text: `I am ${name}.`, tags: ['self'], source: candidate.id, updatedAt: now });
+                writeEntity(graphEntities, canonicalWrites.entities, { id: 'self', type: 'person', name, summary: 'Owner of this local Brainbase Personal OS.', tags: ['self'] });
+                personalKgAdditions.push(reuseById(base.personalKg, { id: `self-${stableHash(name)}`, type: 'self', text: `I am ${name}.`, tags: ['self'], source: candidate.id, updatedAt: now }));
                 applied.push({ id: candidate.id, kind: candidate.kind, summary: name, canonicalIds: ['self', `self-${stableHash(name)}`] });
                 break;
             }
@@ -338,19 +357,39 @@ export function planApply(candidates, selection, base, now) {
                     skipped.push({ id: candidate.id, reason: 'person candidate missing name' });
                     break;
                 }
+                const projectId = payloadString(payload, 'projectId');
+                if (!projectId) {
+                    skipped.push({ id: candidate.id, reason: 'unresolved_project_reference: explicit payload.projectId is required' });
+                    break;
+                }
+                if (!availableProjectIds.has(projectId)) {
+                    skipped.push({ id: candidate.id, reason: `unresolved_project_reference: ${projectId} is not a canonical or selected project` });
+                    break;
+                }
                 const context = payloadString(payload, 'context') || payloadString(payload, 'email') || 'Imported from onboarding sources.';
                 const role = payloadString(payload, 'role');
-                upsertEntity(graphEntities, { id: `person-${stableHash(person)}`, type: 'person', name: person, summary: context, tags: ['relationship'] });
+                const personId = `person-${stableHash(person)}`;
+                writeEntity(graphEntities, canonicalWrites.entities, { id: personId, type: 'person', name: person, summary: context, tags: ['relationship'] });
+                const edge = buildCanonicalEdge({
+                    fromId: personId,
+                    relation: 'participates_in',
+                    toId: projectId,
+                    role: role || undefined,
+                    context,
+                    provenance: { sourceKind: provenanceSourceKind, sourceId: candidate.id }
+                });
+                writeEdge(graphEdges, canonicalWrites.edges, edge);
+                const relationshipId = `relationship-${stableHash(`${person}|${context}`)}`;
                 if (candidate.kind === 'relationship' && !relationships.some((relationship) => relationship.person === person && relationship.context === context)) {
-                    relationships.push({ id: `relationship-${stableHash(`${person}|${context}`)}`, person, role: role || undefined, context, tags: ['relationship'], updatedAt: now });
+                    relationships.push({ id: relationshipId, person, role: role || undefined, context, tags: ['relationship'], updatedAt: now });
                 }
                 applied.push({
                     id: candidate.id,
                     kind: candidate.kind,
                     summary: person,
                     canonicalIds: candidate.kind === 'relationship'
-                        ? [`person-${stableHash(person)}`, `relationship-${stableHash(`${person}|${context}`)}`]
-                        : [`person-${stableHash(person)}`]
+                        ? [personId, edge.id, relationshipId]
+                        : [personId, edge.id]
                 });
                 break;
             }
@@ -360,7 +399,7 @@ export function planApply(candidates, selection, base, now) {
                     skipped.push({ id: candidate.id, reason: 'org candidate missing name' });
                     break;
                 }
-                upsertEntity(graphEntities, { id: `org-${stableHash(name)}`, type: 'org', name, summary: 'Imported from onboarding sources.', tags: ['org'] });
+                writeEntity(graphEntities, canonicalWrites.entities, { id: `org-${stableHash(name)}`, type: 'org', name, summary: 'Imported from onboarding sources.', tags: ['org'] });
                 applied.push({ id: candidate.id, kind: candidate.kind, summary: name, canonicalIds: [`org-${stableHash(name)}`] });
                 break;
             }
@@ -370,8 +409,8 @@ export function planApply(candidates, selection, base, now) {
                     skipped.push({ id: candidate.id, reason: 'project candidate missing name' });
                     break;
                 }
-                upsertEntity(graphEntities, { id: `project-${stableHash(name)}`, type: 'project', name, summary: 'Imported from onboarding sources.', tags: ['work'] });
-                personalKgAdditions.push({ id: `work-${stableHash(name)}`, type: 'work', text: name, tags: ['work'], source: candidate.id, updatedAt: now });
+                writeEntity(graphEntities, canonicalWrites.entities, { id: `project-${stableHash(name)}`, type: 'project', name, summary: 'Imported from onboarding sources.', tags: ['work'] });
+                personalKgAdditions.push(reuseById(base.personalKg, { id: `work-${stableHash(name)}`, type: 'work', text: name, tags: ['work'], source: candidate.id, updatedAt: now }));
                 applied.push({ id: candidate.id, kind: candidate.kind, summary: name, canonicalIds: [`project-${stableHash(name)}`, `work-${stableHash(name)}`] });
                 break;
             }
@@ -381,7 +420,7 @@ export function planApply(candidates, selection, base, now) {
                     skipped.push({ id: candidate.id, reason: 'value candidate missing text' });
                     break;
                 }
-                personalKgAdditions.push({ id: `value-${stableHash(text)}`, type: 'value', text, tags: ['onboarding'], source: candidate.id, updatedAt: now });
+                personalKgAdditions.push(reuseById(base.personalKg, { id: `value-${stableHash(text)}`, type: 'value', text, tags: ['onboarding'], source: candidate.id, updatedAt: now }));
                 applied.push({ id: candidate.id, kind: candidate.kind, summary: text, canonicalIds: [`value-${stableHash(text)}`] });
                 break;
             }
@@ -391,7 +430,7 @@ export function planApply(candidates, selection, base, now) {
                     skipped.push({ id: candidate.id, reason: 'next_action candidate missing text' });
                     break;
                 }
-                personalKgAdditions.push({ id: `next-action-${stableHash(text)}`, type: 'work', text, tags: ['next-action'], source: candidate.id, updatedAt: now });
+                personalKgAdditions.push(reuseById(base.personalKg, { id: `next-action-${stableHash(text)}`, type: 'work', text, tags: ['next-action'], source: candidate.id, updatedAt: now }));
                 applied.push({ id: candidate.id, kind: candidate.kind, summary: text, canonicalIds: [`next-action-${stableHash(text)}`] });
                 break;
             }
@@ -401,14 +440,30 @@ export function planApply(candidates, selection, base, now) {
                     skipped.push({ id: candidate.id, reason: 'decision candidate missing decision text' });
                     break;
                 }
+                const projectId = payloadString(payload, 'projectId');
+                if (!projectId) {
+                    skipped.push({ id: candidate.id, reason: 'unresolved_project_reference: explicit payload.projectId is required' });
+                    break;
+                }
+                if (!availableProjectIds.has(projectId)) {
+                    skipped.push({ id: candidate.id, reason: `unresolved_project_reference: ${projectId} is not a canonical or selected project` });
+                    break;
+                }
                 const topic = payloadString(payload, 'topic');
                 const effectiveAt = payloadString(payload, 'effectiveAt');
                 const rationale = payloadString(payload, 'rationale');
                 const supersedes = readStringArray(payload, ['supersedes']);
+                const unresolvedSupersedes = supersedes.find((id) => !availableDecisionIds.has(id));
+                if (unresolvedSupersedes) {
+                    skipped.push({ id: candidate.id, reason: `unresolved_decision_reference: ${unresolvedSupersedes} is not a canonical or selected decision` });
+                    break;
+                }
                 const tags = readStringArray(payload, ['tags']);
-                decisionAdditions.push({
-                    id: `decision-${stableHash(text)}`,
-                    title: payloadString(payload, 'title') || 'Promoted decision principle',
+                const decisionId = `decision-${stableHash(text)}`;
+                const title = payloadString(payload, 'title') || 'Promoted decision principle';
+                decisionAdditions.push(reuseById(base.decisions, {
+                    id: decisionId,
+                    title,
                     decision: text,
                     topic: topic || undefined,
                     supersedes: supersedes.length > 0 ? supersedes : undefined,
@@ -416,15 +471,45 @@ export function planApply(candidates, selection, base, now) {
                     rationale: rationale || undefined,
                     tags: tags.length > 0 ? tags : ['principle'],
                     updatedAt: now
+                }));
+                writeEntity(graphEntities, canonicalWrites.entities, {
+                    id: decisionId,
+                    type: 'decision',
+                    name: title,
+                    summary: text,
+                    tags: tags.length > 0 ? tags : ['principle'],
+                    validFrom: effectiveAt || undefined
+                });
+                const governs = buildCanonicalEdge({
+                    fromId: decisionId,
+                    relation: 'governs',
+                    toId: projectId,
+                    validFrom: effectiveAt || undefined,
+                    provenance: { sourceKind: provenanceSourceKind, sourceId: candidate.id }
                 });
-                applied.push({ id: candidate.id, kind: candidate.kind, summary: text, canonicalIds: [`decision-${stableHash(text)}`] });
+                writeEdge(graphEdges, canonicalWrites.edges, governs);
+                const canonicalIds = [decisionId, governs.id];
+                for (const supersededId of supersedes) {
+                    if (!availableDecisionIds.has(supersededId))
+                        continue;
+                    const supersedesEdge = buildCanonicalEdge({
+                        fromId: decisionId,
+                        relation: 'supersedes',
+                        toId: supersededId,
+                        validFrom: effectiveAt || undefined,
+                        provenance: { sourceKind: provenanceSourceKind, sourceId: candidate.id }
+                    });
+                    writeEdge(graphEdges, canonicalWrites.edges, supersedesEdge);
+                    canonicalIds.push(supersedesEdge.id);
+                }
+                applied.push({ id: candidate.id, kind: candidate.kind, summary: text, canonicalIds });
                 break;
             }
             default:
                 skipped.push({ id: candidate.id, reason: `unsupported candidate kind: ${candidate.kind}` });
         }
     }
-    return { graphEntities, relationships, personalKgAdditions, decisionAdditions, ownerName, applied, skipped };
+    return { graphEntities, graphEdges, canonicalWrites, relationships, personalKgAdditions, decisionAdditions, ownerName, applied, skipped };
 }
 // ---------------------------------------------------------------------------
 // Helpers
@@ -545,12 +630,52 @@ function payloadString(payload, key) {
 function upsertEntity(entities, entity) {
     const index = entities.findIndex((candidate) => candidate.id === entity.id);
     if (index >= 0) {
+        assertCompatibleCanonicalIdentity(entities[index], entity);
         entities[index] = { ...entities[index], ...entity };
     }
     else {
         entities.push(entity);
     }
 }
+function assertCompatibleCanonicalIdentity(existing, proposed) {
+    const existingIdentity = canonicalIdentity(existing);
+    const proposedIdentity = canonicalIdentity(proposed);
+    if (existingIdentity === proposedIdentity)
+        return;
+    const labels = [canonicalIdentityLabel(existing), canonicalIdentityLabel(proposed)].sort((left, right) => left.localeCompare(right, 'en'));
+    throw new Error(`canonical_id_collision: ${proposed.id} maps to distinct semantic identities: ${labels.join(' / ')}`);
+}
+function canonicalIdentity(entity) {
+    return JSON.stringify(entity.type === 'decision'
+        ? { type: entity.type, decision: entity.summary ?? entity.name }
+        : { type: entity.type, name: entity.name });
+}
+function canonicalIdentityLabel(entity) {
+    return entity.type === 'decision' ? entity.summary ?? entity.name : entity.name;
+}
+function writeEntity(entities, writes, entity) {
+    upsertEntity(entities, entity);
+    upsertEntity(writes, entity);
+}
+function writeEdge(edges, writes, edge) {
+    upsertRecord(edges, edge);
+    upsertRecord(writes, edge);
+}
+function upsertRecord(records, record) {
+    const index = records.findIndex((candidate) => candidate.id === record.id);
+    if (index >= 0)
+        records[index] = record;
+    else
+        records.push(record);
+}
+function reuseById(existing, addition) {
+    const found = existing.find((item) => item.id === addition.id);
+    if (!found)
+        return addition;
+    return JSON.stringify({ ...found, updatedAt: undefined }) === JSON.stringify({ ...addition, updatedAt: undefined })
+        ? found
+        : addition;
+}
 function truncate(value, max) {
     if (value.length <= max) {
         return value;

package/dist/onboarding.js

@@ -45,7 +45,7 @@ export function buildAgentOnboardingProtocol() {
                 questions: [
                     'Optionally run brainbase onboard:demo to preview which saved context should be used.',
                     'Install the MCP config after user approval and restart the selected agent.',
-                    'Send the real request through that agent and require get_context/search evidence.',
+                    'Send the real request through that agent and require resolve_entity/get_context/search evidence.',
                     'Ask the user whether the actual answer was useful. A CLI sample or synthetic evaluator is not onboarding completion.'
                 ]
             },
@@ -73,7 +73,7 @@ export function buildAgentOnboardingProtocol() {
             'brainbase onboard:seed --name "<name>" --value "<what should not be re-explained>" --project "<current project>" --relationship "<person>|<role>|<context>"',
             'brainbase onboard:projects --name "<project>" --goal "<goal>" --status "<status>" --role "<your role>"',
             'brainbase onboard:install --target codex --dry-run',
-            'Restart the selected agent, then send the real request and require Brainbase get_context/search.',
+            'Restart the selected agent, then send the real request and require Brainbase resolve_entity/get_context/search.',
             'Ask the user whether the actual answer was useful.',
             'brainbase onboard:demo --scenario "<optional local preview>"',
             'brainbase onboard:skills --target codex',
@@ -86,9 +86,9 @@ export function buildAgentOnboardingProtocol() {
             'Personal OS directory exists.',
             'The approved self, work, and person context are saved locally.',
             'The CLI sample, if used, is labeled as a preview rather than an onboarding completion signal.',
-            'The completion report lists public skills, ohayo/oyasumi/retro routines, real MCP config merge, source allowlists, and MCP get_context/search verification as unfinished operationalization work.',
+            'The completion report lists public skills, ohayo/oyasumi/retro routines, real MCP config merge, source allowlists, and MCP resolve_entity/get_context/search verification as unfinished operationalization work.',
             'The selected MCP client has a Brainbase config snippet merged into its real config after user approval.',
-            'A fresh agent session used Brainbase get_context/search for the real request.',
+            'A fresh agent session used Brainbase resolve_entity/get_context/search for the real request.',
             'The user personally confirmed that the actual agent answer was useful.',
             'Source diagnosis is optional follow-up work, but source allowlist/import/candidate review must be explicitly completed or deferred.'
         ]
@@ -123,7 +123,7 @@ export function buildValueDemo(input) {
         dataDir: input.os.dataDir,
         firstValueReady: ready
     });
-    const actualAgentPrompt = `Brainbaseのget_contextとsearchを使い、保存済み文脈を根拠に「${scenario}」へ回答してください。使った前提と未確認事項を分けてください。`;
+    const actualAgentPrompt = `Brainbaseのresolve_entity、get_context、searchを使い、保存済み文脈を根拠に「${scenario}」へ回答してください。使った正規ID、関係、前提、未確認事項を分けてください。`;
     return {
         goal: '実エージェント接続前に、保存した文脈から作れる出力をプレビューする。',
         ready,

package/dist/ontology-migration.d.ts

@@ -0,0 +1,30 @@
+import type { DecisionRecord, GraphFile, GraphFileV2, RelationshipsFile } from './types.js';
+export type MigrationIssueCode = 'ambiguous_person' | 'unresolved_person' | 'missing_project_evidence' | 'missing_project_endpoint' | 'ambiguous_decision_project' | 'missing_decision_endpoint' | 'decision_supersedes_self' | 'decision_supersedes_cycle' | 'unsupported_relationship_entity' | 'expected_input_digest_required' | 'input_digest_mismatch';
+export interface MigrationIssue {
+    code: MigrationIssueCode;
+    recordId: string;
+    detail: string;
+}
+export interface CanonicalGraphMigrationInput {
+    graph: GraphFile;
+    relationships?: RelationshipsFile;
+    decisions?: DecisionRecord[];
+}
+export interface CanonicalGraphMigrationPlan {
+    status: 'migration_required' | 'up_to_date' | 'blocked';
+    graph: GraphFileV2;
+    issues: MigrationIssue[];
+    inputDigest: string;
+    outputDigest: string;
+    changes: {
+        entitiesAdded: number;
+        edgesAdded: number;
+    };
+}
+/**
+ * Produces a side-effect-free v1 -> v2 migration preview.
+ *
+ * Only explicit IDs and unique exact-name matches are promoted. Free-form
+ * context is never interpreted as a canonical relationship.
+ */
+export declare function planCanonicalGraphMigration(input: CanonicalGraphMigrationInput): CanonicalGraphMigrationPlan;