@unson/brainbase-mcp 0.2.4 → 0.3.0

package/dist/projects.js

@@ -1,3 +1,4 @@
+import { buildCanonicalEdge } from './canonical-edge-builder.js';
 export function parseProjectSource(value) {
     const [areaRaw, labelRaw, refRaw] = value.split('|').map((part) => part.trim());
     const area = parseProjectSourceArea(areaRaw);
@@ -74,6 +75,43 @@ export function buildProjectRegistrationPlan(input) {
         tags: ['project', 'principle'],
         updatedAt: now
     }));
+    const decisionEntities = decisions.map((decision) => ({
+        id: decision.id,
+        type: 'decision',
+        name: decision.title,
+        summary: decision.decision,
+        tags: decision.tags,
+        metadata: {
+            rationale: decision.rationale,
+            projectId
+        }
+    }));
+    const canonicalEntities = [
+        { ...projectEntity, type: 'project' },
+        ...stakeholderEntities.map((entity) => ({ ...entity, type: 'person' })),
+        ...decisionEntities
+    ];
+    const participationEdges = stakeholders.map((stakeholder) => {
+        const personId = `person-${stableHash(stakeholder.person)}`;
+        return buildCanonicalEdge({
+            fromId: personId,
+            relation: 'participates_in',
+            toId: projectId,
+            role: stakeholder.role,
+            context: stakeholder.context,
+            provenance: {
+                sourceKind: 'onboarding',
+                sourceId: `relationship-${stableHash(`${name}|${stakeholder.person}|${stakeholder.context}`)}`
+            }
+        });
+    });
+    const governanceEdges = decisions.map((decision) => buildCanonicalEdge({
+        fromId: decision.id,
+        relation: 'governs',
+        toId: projectId,
+        context: decision.decision,
+        provenance: { sourceKind: 'onboarding', sourceId: decision.id }
+    }));
     return {
         goal: 'Review project registration before promoting it into canonical Brainbase SSOT.',
         canonicalWrites: false,
@@ -91,6 +129,8 @@ export function buildProjectRegistrationPlan(input) {
         stakeholders,
         writes: {
             graphEntities: [projectEntity, ...stakeholderEntities],
+            canonicalEntities,
+            canonicalEdges: [...participationEdges, ...governanceEdges],
             relationships,
             personalKg,
             decisions

package/dist/relation-registry.d.ts

@@ -0,0 +1,11 @@
+import type { CanonicalEntityKind, CoreRelation } from './types.js';
+export interface CanonicalRelationDefinition {
+    id: CoreRelation;
+    from: CanonicalEntityKind;
+    to: CanonicalEntityKind;
+    meaning: string;
+    scopeTraversal: 'none' | 'project_direct' | 'project_transitive';
+    traversalDirection: 'none' | 'forward' | 'reverse';
+}
+export declare const canonicalRelationRegistry: Readonly<Record<CoreRelation, Readonly<CanonicalRelationDefinition>>>;
+export declare function getCanonicalRelation(relation: string): Readonly<CanonicalRelationDefinition>;

package/dist/relation-registry.js

@@ -0,0 +1,66 @@
+const definitions = {
+    member_of: {
+        id: 'member_of',
+        from: 'person',
+        to: 'org',
+        meaning: 'A person is a member of an organization.',
+        scopeTraversal: 'none',
+        traversalDirection: 'none'
+    },
+    participates_in: {
+        id: 'participates_in',
+        from: 'person',
+        to: 'project',
+        meaning: 'A person participates in a project.',
+        scopeTraversal: 'project_direct',
+        traversalDirection: 'forward'
+    },
+    accountable_for: {
+        id: 'accountable_for',
+        from: 'person',
+        to: 'project',
+        meaning: 'A person is accountable for a project outcome or decision.',
+        scopeTraversal: 'project_direct',
+        traversalDirection: 'forward'
+    },
+    owned_by: {
+        id: 'owned_by',
+        from: 'project',
+        to: 'org',
+        meaning: 'A project is owned by an organization.',
+        scopeTraversal: 'project_direct',
+        traversalDirection: 'reverse'
+    },
+    governs: {
+        id: 'governs',
+        from: 'decision',
+        to: 'project',
+        meaning: 'A durable decision or principle governs a project.',
+        scopeTraversal: 'project_direct',
+        traversalDirection: 'forward'
+    },
+    supersedes: {
+        id: 'supersedes',
+        from: 'decision',
+        to: 'decision',
+        meaning: 'A durable decision explicitly supersedes another decision.',
+        scopeTraversal: 'project_transitive',
+        traversalDirection: 'forward'
+    }
+};
+export const canonicalRelationRegistry = deepFreeze(definitions);
+export function getCanonicalRelation(relation) {
+    const definition = canonicalRelationRegistry[relation];
+    if (!definition) {
+        throw new Error(`ONTOLOGY-RELATION-UNKNOWN: unsupported canonical relation ${JSON.stringify(relation)}`);
+    }
+    return definition;
+}
+function deepFreeze(value) {
+    if (value && typeof value === 'object' && !Object.isFrozen(value)) {
+        Object.freeze(value);
+        for (const nested of Object.values(value))
+            deepFreeze(nested);
+    }
+    return value;
+}

package/dist/server.d.ts

@@ -8,6 +8,15 @@ export declare const toolDefinitions: readonly [{
             readonly dataDir: {
                 readonly type: "string";
             };
+            readonly project: {
+                readonly type: "string";
+                readonly description: "Optional canonical project ID, name, or alias.";
+            };
+            readonly as_of: {
+                readonly type: "string";
+                readonly format: "date-time";
+                readonly description: "RFC 3339 validity instant. Defaults to now.";
+            };
         };
     };
 }, {
@@ -40,6 +49,15 @@ export declare const toolDefinitions: readonly [{
             readonly limit: {
                 readonly type: "number";
             };
+            readonly project: {
+                readonly type: "string";
+                readonly description: "Optional canonical project ID, name, or alias.";
+            };
+            readonly as_of: {
+                readonly type: "string";
+                readonly format: "date-time";
+                readonly description: "RFC 3339 validity instant. Defaults to now.";
+            };
         };
     };
 }, {
@@ -380,7 +398,7 @@ export declare const toolDefinitions: readonly [{
                 readonly type: "string";
             };
             readonly ontologyVersion: {
-                readonly enum: readonly ["0.0.0", "1.0.0"];
+                readonly enum: readonly ["0.0.0", "1.0.0", "2.0.0"];
             };
         };
     };
@@ -398,7 +416,7 @@ export declare const toolDefinitions: readonly [{
                 readonly format: "date-time";
             };
             readonly ontologyVersion: {
-                readonly enum: readonly ["0.0.0", "1.0.0"];
+                readonly enum: readonly ["0.0.0", "1.0.0", "2.0.0"];
             };
         };
     };
@@ -413,6 +431,72 @@ export declare const toolDefinitions: readonly [{
             };
         };
     };
+}, {
+    readonly name: "resolve_entity";
+    readonly description: "Resolve mentions in text to canonical Graph v2 entity IDs and return a privacy-safe evidence receipt.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly required: readonly ["text", "asOf"];
+        readonly additionalProperties: false;
+        readonly properties: {
+            readonly dataDir: {
+                readonly type: "string";
+                readonly description: "Optional Personal OS directory.";
+            };
+            readonly text: {
+                readonly type: "string";
+                readonly description: "Text whose entity mentions should be resolved. The text is hashed, not stored in the receipt.";
+            };
+            readonly asOf: {
+                readonly type: "string";
+                readonly format: "date-time";
+                readonly description: "RFC 3339 instant used for temporal entity and edge validity.";
+            };
+            readonly mentionSpans: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "object";
+                    readonly required: readonly ["start", "end"];
+                    readonly additionalProperties: false;
+                    readonly properties: {
+                        readonly start: {
+                            readonly type: "integer";
+                            readonly minimum: 0;
+                        };
+                        readonly end: {
+                            readonly type: "integer";
+                            readonly minimum: 1;
+                        };
+                    };
+                };
+            };
+            readonly projectScope: {
+                readonly type: "object";
+                readonly required: readonly ["projectIds"];
+                readonly additionalProperties: false;
+                readonly properties: {
+                    readonly projectIds: {
+                        readonly type: "array";
+                        readonly minItems: 1;
+                        readonly items: {
+                            readonly type: "string";
+                            readonly minLength: 1;
+                        };
+                    };
+                    readonly policy: {
+                        readonly enum: readonly ["strict", "prefer_project", "allow_global_fallback"];
+                    };
+                };
+            };
+            readonly entityTypes: {
+                readonly type: "array";
+                readonly minItems: 1;
+                readonly items: {
+                    readonly enum: readonly ["person", "org", "project", "decision"];
+                };
+            };
+        };
+    };
 }];
 export declare function callBrainbaseTool(name: string, rawArgs?: unknown): Promise<unknown>;
 export declare function createServer(): Server;

package/dist/server.js

@@ -1,8 +1,13 @@
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { z } from 'zod';
 import { ConnectedOnboardingRuntime } from './connected-onboarding.js';
+import { validateCanonicalGraph } from './canonical-graph.js';
+import { resolveText } from './entity-resolution.js';
 import { resolveDataDir } from './paths.js';
 import { auditPersonalOsDirectory } from './ontology-ssot.js';
 import { getOntologyImpact, inferPersonalOs, portableOntology, resolveOntologyVersion } from './ontology.js';
@@ -15,7 +20,34 @@ const argsSchema = z.object({
     type: z.enum(['person', 'org', 'project', 'relationship', 'decision']).optional(),
     fromVersion: z.string().optional(),
     ontologyVersion: z.string().optional(),
-    asOf: z.string().datetime({ offset: true }).optional()
+    asOf: z.string().datetime({ offset: true }).optional(),
+    project: z.string().min(1).optional(),
+    as_of: z.string().datetime({ offset: true }).optional()
+});
+const mentionSpanSchema = z.object({
+    start: z.number().int().nonnegative(),
+    end: z.number().int().positive()
+}).strict().refine((span) => span.end > span.start, { message: 'mention span end must be after start' });
+const resolveEntitySchema = z.object({
+    dataDir: z.string().optional(),
+    text: z.string(),
+    asOf: z.string().datetime({ offset: true }),
+    mentionSpans: z.array(mentionSpanSchema).optional(),
+    projectScope: z.object({
+        projectIds: z.array(z.string().min(1)).min(1),
+        policy: z.enum(['strict', 'prefer_project', 'allow_global_fallback']).optional()
+    }).strict().optional(),
+    entityTypes: z.array(z.enum(['person', 'org', 'project', 'decision'])).min(1).optional()
+}).strict().superRefine((value, context) => {
+    for (const [index, span] of (value.mentionSpans ?? []).entries()) {
+        if (span.end > value.text.length) {
+            context.addIssue({
+                code: z.ZodIssueCode.custom,
+                path: ['mentionSpans', index, 'end'],
+                message: 'mention span must be within text'
+            });
+        }
+    }
 });
 const sourceInventorySchema = z.object({
     id: z.string(),
@@ -89,7 +121,9 @@ export const toolDefinitions = [
         inputSchema: {
             type: 'object',
             properties: {
-                dataDir: { type: 'string' }
+                dataDir: { type: 'string' },
+                project: { type: 'string', description: 'Optional canonical project ID, name, or alias.' },
+                as_of: { type: 'string', format: 'date-time', description: 'RFC 3339 validity instant. Defaults to now.' }
             }
         }
     },
@@ -113,7 +147,9 @@ export const toolDefinitions = [
             properties: {
                 dataDir: { type: 'string' },
                 query: { type: 'string' },
-                limit: { type: 'number' }
+                limit: { type: 'number' },
+                project: { type: 'string', description: 'Optional canonical project ID, name, or alias.' },
+                as_of: { type: 'string', format: 'date-time', description: 'RFC 3339 validity instant. Defaults to now.' }
             }
         }
     },
@@ -230,7 +266,7 @@ export const toolDefinitions = [
             type: 'object',
             properties: {
                 dataDir: { type: 'string' },
-                ontologyVersion: { enum: ['0.0.0', '1.0.0'] }
+                ontologyVersion: { enum: ['0.0.0', '1.0.0', '2.0.0'] }
             }
         }
     },
@@ -242,7 +278,7 @@ export const toolDefinitions = [
             properties: {
                 dataDir: { type: 'string' },
                 asOf: { type: 'string', format: 'date-time' },
-                ontologyVersion: { enum: ['0.0.0', '1.0.0'] }
+                ontologyVersion: { enum: ['0.0.0', '1.0.0', '2.0.0'] }
             }
         }
     },
@@ -255,12 +291,52 @@ export const toolDefinitions = [
                 fromVersion: { type: 'string' }
             }
         }
+    },
+    {
+        name: 'resolve_entity',
+        description: 'Resolve mentions in text to canonical Graph v2 entity IDs and return a privacy-safe evidence receipt.',
+        inputSchema: {
+            type: 'object',
+            required: ['text', 'asOf'],
+            additionalProperties: false,
+            properties: {
+                dataDir: { type: 'string', description: 'Optional Personal OS directory.' },
+                text: { type: 'string', description: 'Text whose entity mentions should be resolved. The text is hashed, not stored in the receipt.' },
+                asOf: { type: 'string', format: 'date-time', description: 'RFC 3339 instant used for temporal entity and edge validity.' },
+                mentionSpans: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        required: ['start', 'end'],
+                        additionalProperties: false,
+                        properties: { start: { type: 'integer', minimum: 0 }, end: { type: 'integer', minimum: 1 } }
+                    }
+                },
+                projectScope: {
+                    type: 'object',
+                    required: ['projectIds'],
+                    additionalProperties: false,
+                    properties: {
+                        projectIds: { type: 'array', minItems: 1, items: { type: 'string', minLength: 1 } },
+                        policy: { enum: ['strict', 'prefer_project', 'allow_global_fallback'] }
+                    }
+                },
+                entityTypes: {
+                    type: 'array',
+                    minItems: 1,
+                    items: { enum: ['person', 'org', 'project', 'decision'] }
+                }
+            }
+        }
     }
 ];
 export async function callBrainbaseTool(name, rawArgs = {}) {
     if (name in connectedSchemas) {
         return callConnectedOnboardingTool(name, rawArgs);
     }
+    if (name === 'resolve_entity') {
+        return callResolveEntityTool(rawArgs);
+    }
     const args = argsSchema.parse(rawArgs ?? {});
     const dataDir = resolveDataDir(args.dataDir);
     switch (name) {
@@ -316,21 +392,25 @@ export async function callBrainbaseTool(name, rawArgs = {}) {
                 ...portableOntology
             };
         case 'audit_ontology':
-            return auditPersonalOsDirectory(dataDir, { ontologyVersion: resolveOntologyVersion(args.ontologyVersion) });
+            return auditPersonalOsDirectory(dataDir, {
+                ontologyVersion: args.ontologyVersion === undefined
+                    ? undefined
+                    : resolveOntologyVersion(args.ontologyVersion)
+            });
         case 'ontology_impact':
             return getOntologyImpact(args.fromVersion);
     }
     const os = await loadPersonalOs(dataDir);
     switch (name) {
         case 'get_context':
-            return getContext(os);
+            return getContext(os, { project: args.project, asOf: args.as_of ?? args.asOf });
         case 'list_entities':
             return listEntities(os, args.type);
         case 'search':
             if (!args.query) {
                 throw new Error('search requires query');
             }
-            return { results: searchAll(os, args.query, args.limit) };
+            return { results: searchAll(os, args.query, args.limit, { project: args.project, asOf: args.as_of ?? args.asOf }) };
         case 'search_personal_kg':
             if (!args.query) {
                 throw new Error('search_personal_kg requires query');
@@ -341,12 +421,81 @@ export async function callBrainbaseTool(name, rawArgs = {}) {
         case 'infer_decisions':
             return inferPersonalOs(os, {
                 asOf: args.asOf,
-                ontologyVersion: resolveOntologyVersion(args.ontologyVersion)
+                ontologyVersion: args.ontologyVersion === undefined
+                    ? undefined
+                    : resolveOntologyVersion(args.ontologyVersion)
             });
         default:
             throw new Error(`Unknown tool: ${name}`);
     }
 }
+async function callResolveEntityTool(rawArgs) {
+    const args = resolveEntitySchema.parse(rawArgs ?? {});
+    const dataDir = resolveDataDir(args.dataDir);
+    const graphPath = join(dataDir, 'graph.json');
+    let serialized;
+    try {
+        serialized = await readFile(graphPath, 'utf8');
+    }
+    catch {
+        return blockedResolution(args, 'unavailable', 'graph_unavailable');
+    }
+    let graph;
+    try {
+        graph = JSON.parse(serialized);
+    }
+    catch {
+        return blockedResolution(args, 'invalid', 'graph_invalid');
+    }
+    try {
+        validateCanonicalGraph(graph);
+    }
+    catch {
+        return blockedResolution(args, 'invalid', 'graph_invalid');
+    }
+    if (isGraphVersion(graph, 1)) {
+        return {
+            status: 'migration_required',
+            graphSchemaVersion: 1,
+            requiredAction: 'migrate_graph_v2'
+        };
+    }
+    if (!isGraphVersion(graph, 2)) {
+        return blockedResolution(args, 'invalid', 'graph_invalid');
+    }
+    const receipt = resolveText({
+        text: args.text,
+        ...(args.mentionSpans ? { mentionSpans: args.mentionSpans } : {}),
+        ...(args.projectScope ? { projectScope: args.projectScope } : {}),
+        asOf: args.asOf,
+        ...(args.entityTypes ? { entityTypes: args.entityTypes } : {}),
+        source: {
+            authority: 'local_graph',
+            status: 'complete',
+            revision: createHash('sha256').update(serialized).digest('hex'),
+            graph: graph
+        }
+    }).receipt;
+    return { status: 'verified', receipt };
+}
+function blockedResolution(args, sourceStatus, issueCode) {
+    const receipt = resolveText({
+        text: args.text,
+        ...(args.mentionSpans ? { mentionSpans: args.mentionSpans } : {}),
+        ...(args.projectScope ? { projectScope: args.projectScope } : {}),
+        asOf: args.asOf,
+        ...(args.entityTypes ? { entityTypes: args.entityTypes } : {}),
+        source: {
+            authority: 'local_graph',
+            status: sourceStatus,
+            issues: [{ code: issueCode, message: issueCode }]
+        }
+    }).receipt;
+    return { status: 'unverified', receipt };
+}
+function isGraphVersion(graph, version) {
+    return Boolean(graph && typeof graph === 'object' && 'version' in graph && graph.version === version);
+}
 async function callConnectedOnboardingTool(name, rawArgs) {
     const schema = connectedSchemas[name];
     const args = schema.parse(rawArgs ?? {});

package/dist/skills.js

@@ -27,8 +27,8 @@ const SKILL_DEFINITIONS = {
             '2. `brainbase onboard:start --target codex|claude|codecode` を実行し、本人、プロジェクト、関係者、判断基準の最小候補を確認する。',
             '3. ユーザーが明示的に承認した事実だけを `brainbase onboard:seed` で保存する。',
             '4. `brainbase onboard:install --target codex|claude|codecode --dry-run` でMCP設定を確認し、承認後に実設定へ反映して対象エージェントを再起動する。',
-            '5. 新しい実際のエージェントで、Brainbaseの `get_context` と `search` を使うよう明示して最初の現実の依頼を実行する。',
-            '6. 実回答、使われた保存済み文脈、未確認事項をユーザーへ示し、本人に役立ったかを確認する。ここまでを10分以内の初回価値候補ジャーニーとして測る。',
+            '5. 新しい実際のエージェントで、Brainbaseの `resolve_entity`、`get_context`、`search` を使うよう明示して最初の現実の依頼を実行する。',
+            '6. 実回答、使われた正規IDと関係、保存済み文脈、未確認事項をユーザーへ示し、本人に役立ったかを確認する。ここまでを10分以内の初回価値候補ジャーニーとして測る。',
             '7. CLIの `onboard:demo` は必要なら接続前のプレビューに使えるが、CLIサンプルは初回価値の達成証拠にしない。',
             '8. 本人が役立つと確認した後だけ、必要に応じてsource診断、追加候補、Skills、ルーティンへ進む。',
             '9. 継続利用するプロジェクトの詳細が必要なら、本人確認後に `brainbase onboard:projects --write` で登録する。',
@@ -113,7 +113,7 @@ const SKILL_DEFINITIONS = {
             '3. どの候補idを承認、却下、修正するかをユーザーに確認する。',
             '4. まず `brainbase onboard:apply --from <candidate-file> --select <id>` でdry-runする。手入力の事実には `brainbase onboard:seed` を使う。',
             '5. `--write` は明示的な承認後にだけ使い、canonical filesへ書き込む。',
-            '6. `brainbase doctor` を実行し、必要に応じてBrainbase MCPの `get_context` または `search` で承認済み事実が見えることを確認する。',
+            '6. `brainbase doctor` を実行し、Brainbase MCPの `resolve_entity`、`get_context`、`search` で承認済み事実と正規ID接続が見えることを確認する。',
             '',
             '## 安全ルール',
             '',

package/dist/ssot.d.ts

@@ -1,3 +1,4 @@
+import { type CanonicalGraphMigrationPlan } from './ontology-migration.js';
 import type { PersonalOs } from './types.js';
 export declare function initializePersonalOs(dataDir: string): Promise<void>;
 export declare function loadPersonalOs(dataDir: string): Promise<PersonalOs>;
@@ -11,3 +12,18 @@ export declare function mutatePersonalOsWithSidecar<T>(dataDir: string, sidecarP
     sidecarContent: string;
     result: T;
 }>): Promise<T>;
+export type CanonicalGraphMigrationExecution = CanonicalGraphMigrationPlan & {
+    expectedInputDigest: string;
+    written: boolean;
+};
+/**
+ * Plans or atomically applies the canonical Graph migration.
+ *
+ * The input is always recovered, read, and planned while holding the same
+ * lock used by every canonical SSOT writer. Omitting `write` is a byte-safe
+ * preview; a blocked or already-current plan is never committed.
+ */
+export declare function migrateCanonicalGraph(dataDir: string, options?: {
+    write?: boolean;
+    expectedInputDigest?: string;
+}): Promise<CanonicalGraphMigrationExecution>;

package/dist/ssot.js

@@ -4,28 +4,14 @@ import { access, copyFile, mkdir, readFile, readdir, rename, rm, stat, writeFile
 import { hostname } from 'node:os';
 import { dirname, isAbsolute, join, relative, resolve, win32 } from 'node:path';
 import { z } from 'zod';
+import { validateCanonicalGraph } from './canonical-graph.js';
 import { assertOntologyValid } from './ontology.js';
+import { planCanonicalGraphMigration } from './ontology-migration.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']),
@@ -112,8 +98,56 @@ export async function mutatePersonalOsWithSidecar(dataDir, sidecarPath, mutator)
         return mutation.result;
     });
 }
+/**
+ * Plans or atomically applies the canonical Graph migration.
+ *
+ * The input is always recovered, read, and planned while holding the same
+ * lock used by every canonical SSOT writer. Omitting `write` is a byte-safe
+ * preview; a blocked or already-current plan is never committed.
+ */
+export async function migrateCanonicalGraph(dataDir, options = {}) {
+    return withSsotLock(dataDir, async () => {
+        await recoverTransactions(dataDir);
+        assertCompleteCanonicalSet(dataDir, await canonicalPresence(dataDir));
+        const current = await loadPersonalOsUnlocked(dataDir);
+        const plan = planCanonicalGraphMigration({
+            graph: current.graph,
+            relationships: current.relationships,
+            decisions: current.decisions
+        });
+        if (options.write && options.expectedInputDigest === undefined) {
+            return blockMigrationWrite(plan, {
+                code: 'expected_input_digest_required',
+                recordId: 'canonical-aggregate',
+                detail: 'MIGRATION-EXPECTED-INPUT-DIGEST-REQUIRED: preview first and pass its inputDigest before writing'
+            });
+        }
+        if (options.write && options.expectedInputDigest !== plan.inputDigest) {
+            return blockMigrationWrite(plan, {
+                code: 'input_digest_mismatch',
+                recordId: 'canonical-aggregate',
+                detail: `MIGRATION-INPUT-DIGEST-MISMATCH: expected ${options.expectedInputDigest}, replanned ${plan.inputDigest}`
+            });
+        }
+        if (!options.write || plan.status !== 'migration_required') {
+            return { ...plan, expectedInputDigest: plan.inputDigest, written: false };
+        }
+        const next = { ...current, graph: plan.graph };
+        await commitAggregate(dataDir, next, 'mutation');
+        return { ...plan, expectedInputDigest: plan.inputDigest, written: true };
+    });
+}
+function blockMigrationWrite(plan, issue) {
+    return {
+        ...plan,
+        status: 'blocked',
+        issues: [...plan.issues, issue].sort((left, right) => (`${left.recordId}\u0000${left.code}`.localeCompare(`${right.recordId}\u0000${right.code}`, 'en'))),
+        expectedInputDigest: plan.inputDigest,
+        written: false
+    };
+}
 async function loadPersonalOsUnlocked(dataDir) {
-    const graph = graphSchema.parse(await readJson(join(dataDir, 'graph.json')));
+    const graph = parseGraph(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');
@@ -229,11 +263,27 @@ async function writeAggregate(targetDir, os) {
     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);
+    validateCanonicalGraph(os.graph);
+}
+function parseGraph(value) {
+    try {
+        validateCanonicalGraph(value);
+    }
+    catch (error) {
+        // Duplicate entity IDs are a complete, readable snapshot whose ontology
+        // violation must remain available to audit/inference instead of being
+        // collapsed into a source-unavailable result. Writers still validate the
+        // aggregate strictly before commit.
+        if (!(error instanceof Error) || !error.message.startsWith('GRAPH-ENTITY-ID-UNIQUE')) {
+            throw error;
+        }
+        validateCanonicalGraph(value, { allowDuplicateEntityIds: true });
+    }
+    return value;
 }
 function serializeJsonl(values) {
     return values.length === 0 ? '' : `${values.map((value) => JSON.stringify(value)).join('\n')}\n`;