@unson/brainbase-mcp 0.2.3 → 0.3.0

package/README.md

@@ -4,7 +4,7 @@ Brainbaseは、自分が承認した仕事の前提をCodex、Claude Code、Code
 
 最初の目標は情報源をすべて接続することではありません。自分、仕事、関係者、判断基準の最小文脈を保存し、10分以内に「同じ前提を説明し直さず役立つ出力」を確認することです。
 
-Ontology 1.0.0は、ローカルファイルへ持ち運べる意味契約を追加します。ホスト型Brainbaseを必要とせず、型、関係語彙、検証制約、決定論的な判断推論、バージョン移行を定義します。
+Ontology 2.0.0は、ローカルファイルへ持ち運べる意味契約に、Relation Registryで管理する正規エンティティ間のIDエッジを追加します。ホスト型Brainbaseを必要とせず、型、関係語彙、検証制約、決定論的な判断推論、バージョン移行を定義します。履歴解釈として0.0.0と1.0.0も選択できます。
 
 このリポジトリに、社内BrainbaseのUI、セッション実行基盤、xterm転送、ワークフロー管制、SNS運用、ホスト型バックエンド、Infisical設定、雲孫の社内データは含みません。それらは社内版`brainbase-unson`の範囲です。
 
@@ -35,12 +35,12 @@ brainbase onboard:start --target codex
 # 表示された onboard:seed を確認して実行
 brainbase onboard:install --target codex --dry-run
 # 設定を承認・反映し、Codexを再起動
-# 新しいCodexでBrainbaseのget_context/searchを使って実際の依頼を試す
+# 新しいCodexでBrainbaseのresolve_entity/get_context/searchを使って実際の依頼を試す
 ```
 
 リポジトリをcloneした場合も、`npm run onboard:start -- --target codex`から同じ順序で進めます。
 
-利用者がBrainbaseの導入を依頼したら、エージェントはチェックリストを返すだけでなく、この公開CLIを実行します。承認された最小文脈を保存し、MCP設定を反映した新しい実エージェントで`get_context`と`search`を使って現実の依頼へ回答します。その実回答を見た本人が「役立った」と判断して初めて初回価値です。`ready: true`、`cli_sample_ready`、CLIの処理時間、合成ペルソナ評価、Skillsやルーティンの生成、`onboard:install --dry-run`だけでは導入完了ではありません。
+利用者がBrainbaseの導入を依頼したら、エージェントはチェックリストを返すだけでなく、この公開CLIを実行します。承認された最小文脈を保存し、MCP設定を反映した新しい実エージェントで`resolve_entity`、`get_context`、`search`を使って現実の依頼へ回答します。その実回答を見た本人が「役立った」と判断して初めて初回価値です。`ready: true`、`cli_sample_ready`、CLIの処理時間、合成ペルソナ評価、Skillsやルーティンの生成、`onboard:install --dry-run`だけでは導入完了ではありません。
 
 For a Google Workspace / Google Drive / local-notes setup, pass the known answers and let the command surface what still needs approval:
 
@@ -91,7 +91,7 @@ Optionally preview the saved context locally. This is not an onboarding completi
 brainbase onboard:demo --scenario "Draft the first note I should send to Key Partner about Current project"
 ```
 
-`onboard:demo` reads only locally saved, approved facts. It does not call an LLM, an agent, or a hosted backend. Its result is only a preview. Continue through MCP installation, restart the selected agent, make a real request using `get_context` and `search`, and ask the user whether that actual answer was useful.
+`onboard:demo` reads only locally saved, approved facts. It does not call an LLM, an agent, or a hosted backend. Its result is only a preview. Continue through MCP installation, restart the selected agent, make a real request using `resolve_entity`, `get_context`, and `search`, and ask the user whether that actual answer was useful.
 
 After the demo, keep onboarding open: the preview is not the first-value gate. Continue until a real agent uses Brainbase and the human user confirms that the result was useful.
 
@@ -100,10 +100,10 @@ After seed, install and verify MCP before asking for the human value judgment:
 ```bash
 brainbase onboard:install --target codex --dry-run
 brainbase doctor
-# restart Codex, use get_context/search for the real request, then ask whether it was useful
+# restart Codex, use resolve_entity/get_context/search for the real request, then ask whether it was useful
 ```
 
-The recommended order is public skills, `ohayo` / `oyasumi` / `retro` routines registered paused or confirmation-gated, real MCP config merge after approving the dry-run snippet, source allowlist / import / candidate review decisions, then `doctor` plus MCP `get_context` / `search` verification from a fresh agent session.
+The recommended order is public skills, `ohayo` / `oyasumi` / `retro` routines registered paused or confirmation-gated, real MCP config merge after approving the dry-run snippet, source allowlist / import / candidate review decisions, then `doctor` plus MCP `resolve_entity` / `get_context` / `search` verification from a fresh agent session.
 
 The commands above are still safe by default. `onboard:skills` and `onboard:routines` generate output unless you provide an explicit `--out`, and `onboard:install --dry-run` is only a preview. Do not treat those generated artifacts as installed until the user approves file writes, scheduler registration, and live config changes.
 
@@ -290,7 +290,7 @@ The default data directory is:
 
 It contains the canonical local SSOT:
 
-- `graph.json`: people, organizations, projects, and relationship entities.
+- `graph.json`: canonical people, organizations, projects, and decisions, plus typed stable-ID edges between them.
 - `personal-kg.jsonl`: values, judgment criteria, experiences, and personal context.
 - `relationships.json`: relationship context that should survive across tools.
 - `decisions.jsonl`: decision records and principles.
@@ -319,14 +319,15 @@ BRAINBASE_PERSONAL_OS_DIR=/path/to/personal-os brainbase-mcp
 - `get_context`: returns initial AI context from the local Graph and Personal KG.
 - `list_entities`: lists `person`, `org`, `project`, `relationship`, and `decision` entities.
 - `search`: searches canonical Graph and Personal KG data.
+- `resolve_entity`: resolves mentions in text to canonical Graph v2 IDs and returns a privacy-safe evidence receipt.
 - `search_personal_kg`: searches owner-local Personal KG only.
 - `onboarding_status`: reports seeded areas, first value demo readiness, missing setup, and local connection status.
-- `get_ontology`: returns the immutable bundled Ontology 1.0.0 release without reading Personal OS files.
+- `get_ontology`: returns the immutable bundled active Ontology 2.0.0 release without reading Personal OS files.
 - `audit_ontology`: audits canonical local files and distinguishes verified violations from unavailable input.
 - `infer_decisions`: derives active, superseded, and conflicting decisions from explicit rules.
 - `ontology_impact`: explains compatibility, migration, and rollback from an earlier ontology version.
 
-## Portable Ontology 1.0.0
+## Portable Ontology 2.0.0
 
 Inspect the semantic contract and audit your local canonical files:
 
@@ -334,14 +335,18 @@ Inspect the semantic contract and audit your local canonical files:
 brainbase ontology:show
 brainbase ontology:audit
 brainbase ontology:audit --ontology-version 0.0.0
+brainbase ontology:audit --ontology-version 1.0.0
+brainbase ontology:migrate
+# previewのexpectedInputDigestを確認してから適用
+brainbase ontology:migrate --write --expected-input-digest '<previewの値>'
 ```
 
 `ontology:audit` exits non-zero when an error-level violation exists or when a canonical file cannot be verified. It never reports an unavailable or malformed source as zero violations. Warnings, such as a relationship whose person is not yet present in the Graph, remain visible but do not block approved writes.
-Use `--ontology-version 0.0.0` to interpret a pre-kernel snapshot without retroactively applying the 1.0.0 `effectiveAt`, supersession, conflict, or validation rules. The selected version is included in audit and inference results; unsupported versions fail explicitly.
+Use `--ontology-version 0.0.0` to interpret a pre-kernel snapshot without retroactively applying the later `effectiveAt`, supersession, conflict, or validation rules. Use `--ontology-version 1.0.0` for the immutable first portable release. When the flag is omitted, Graph v2 uses its recorded ontology binding; legacy Graph data uses the active 2.0.0 release. The selected version is included in audit and inference results; unsupported versions fail explicitly.
 
 Decision evolution is opt-in, read-compatible, and write-gated. Existing decision rows remain readable. New rows may add `topic`, `supersedes`, and `effectiveAt`; only an explicit `supersedes` reference makes an older decision inactive. Multiple active decisions with the same explicit `topic` are reported as a conflict instead of being silently resolved.
 
-Before enabling 1.0.0 writes, back up the Personal OS directory, capture the current MCP client configuration and launch command, and run the read-only `brainbase ontology:audit --ontology-version 1.0.0`. Existing rows remain readable, but error-level semantic violations must be reviewed before `onboard:seed`, `onboard:projects --write`, or `onboard:apply --write` can change canonical files. For the first npm release, rollback means running `npm uninstall -g @unson/brainbase-mcp`, restoring the captured MCP client configuration and launch command, and restarting the client. For later upgrades, reinstall the last known working package version instead. Restore the pre-upgrade Personal OS backup only if reviewed repairs changed canonical files.
+Before enabling 2.0.0 writes, back up the Personal OS directory, run the read-only historical audit when upgrading from 1.0.0, and preview `brainbase ontology:migrate`. Apply the migration only with the preview's `expectedInputDigest`; a concurrent input change blocks the write. Existing rows remain readable, but error-level semantic violations must be reviewed before a canonical write. Roll back by restoring the pre-migration backup and reinstalling the recorded last known working package version.
 
 ## CLI
 
@@ -505,7 +510,7 @@ Keep or pin the internal `brainbase-unson` system when you need:
 - Legacy Graph API MCP tools such as `get_entity`.
 - VibePro runtime or internal 31013 operation surfaces.
 
-The v1 MCP surface contains the five original context/onboarding tools plus the additive Ontology 1.0.0 tools: `get_ontology`, `audit_ontology`, `infer_decisions`, and `ontology_impact`.
+The original MCP surface remains compatible and adds the Ontology tools plus `resolve_entity`. The active Ontology release is 2.0.0; 0.0.0 and 1.0.0 remain available for historical interpretation.
 
 ## Hosted Backends
 

package/dist/canonical-edge-builder.d.ts

@@ -0,0 +1,11 @@
+import type { CanonicalEdge, CanonicalEntity, CanonicalGraphFile, GraphFileV2 } from './types.js';
+export interface CanonicalWriteSet {
+    entities: CanonicalEntity[];
+    edges: CanonicalEdge[];
+}
+/**
+ * Apply explicit canonical writes without deriving relations from labels or free text.
+ * Existing records with other IDs keep their order and content; matching IDs are updated in place.
+ */
+export declare function applyCanonicalWrites(graph: CanonicalGraphFile, writes: CanonicalWriteSet): GraphFileV2;
+export declare function buildCanonicalEdge(edge: Omit<CanonicalEdge, 'id'>): CanonicalEdge;

package/dist/canonical-edge-builder.js

@@ -0,0 +1,35 @@
+import { canonicalEdgeId, validateCanonicalGraph } from './canonical-graph.js';
+/**
+ * Apply explicit canonical writes without deriving relations from labels or free text.
+ * Existing records with other IDs keep their order and content; matching IDs are updated in place.
+ */
+export function applyCanonicalWrites(graph, writes) {
+    if (graph.version !== 2) {
+        throw new Error('migration_required: Graph v1 cannot store canonical ID edges; migrate graph.json to Graph v2 before writing');
+    }
+    const next = {
+        ...graph,
+        entities: upsertById(graph.entities, writes.entities),
+        edges: upsertById(graph.edges, writes.edges)
+    };
+    validateCanonicalGraph(next);
+    return next;
+}
+export function buildCanonicalEdge(edge) {
+    return { ...edge, id: canonicalEdgeId(edge) };
+}
+function upsertById(existing, additions) {
+    const result = [...existing];
+    const indexById = new Map(result.map((record, index) => [record.id, index]));
+    for (const addition of additions) {
+        const index = indexById.get(addition.id);
+        if (index === undefined) {
+            indexById.set(addition.id, result.length);
+            result.push(addition);
+        }
+        else {
+            result[index] = addition;
+        }
+    }
+    return result;
+}

package/dist/canonical-graph.d.ts

@@ -0,0 +1,9 @@
+import type { CanonicalEdge, CanonicalGraphFile } from './types.js';
+export declare function canonicalEdgeId(edge: Pick<CanonicalEdge, 'fromId' | 'relation' | 'toId'>): string;
+export declare function validateCanonicalGraph(graph: unknown, options?: {
+    allowDuplicateEntityIds?: boolean;
+}): asserts graph is CanonicalGraphFile;
+export declare function isActiveAt(record: {
+    validFrom?: string;
+    validTo?: string;
+}, asOf: string): boolean;

package/dist/canonical-graph.js

@@ -0,0 +1,174 @@
+import { createHash } from 'node:crypto';
+import { getCanonicalRelation } from './relation-registry.js';
+export function canonicalEdgeId(edge) {
+    return `edge-${createHash('sha256').update(JSON.stringify([edge.fromId, edge.relation, edge.toId])).digest('hex').slice(0, 24)}`;
+}
+const v1EntityKinds = new Set(['person', 'org', 'project', 'relationship']);
+const canonicalEntityKinds = new Set(['person', 'org', 'project', 'decision']);
+export function validateCanonicalGraph(graph, options = {}) {
+    if (!graph || typeof graph !== 'object' || !('version' in graph) || !('entities' in graph)) {
+        throw new Error('GRAPH-SHAPE-VALID: graph must be an object with version and entities');
+    }
+    const candidate = graph;
+    if (candidate.version !== 1 && candidate.version !== 2) {
+        throw new Error(`GRAPH-VERSION-SUPPORTED: unsupported graph version ${String(candidate.version)}`);
+    }
+    if (!Array.isArray(candidate.entities)) {
+        throw new Error('GRAPH-SHAPE-VALID: entities must be an array');
+    }
+    const entityIds = new Set();
+    for (const [index, entityValue] of candidate.entities.entries()) {
+        if (!entityValue || typeof entityValue !== 'object') {
+            throw new Error(`GRAPH-ENTITY-SHAPE at entities[${index}]: entity must be an object`);
+        }
+        const entity = entityValue;
+        assertNonEmptyString(entity.id, `entities[${index}].id`);
+        assertNonEmptyString(entity.name, `entities[${index}].name`);
+        const allowedKinds = candidate.version === 1 ? v1EntityKinds : canonicalEntityKinds;
+        if (typeof entity.type !== 'string' || !allowedKinds.has(entity.type)) {
+            throw new Error(`GRAPH-ENTITY-TYPE at entities[${index}].type: unsupported entity type ${String(entity.type)}`);
+        }
+        if (entity.aliases !== undefined && (!Array.isArray(entity.aliases) || entity.aliases.some((alias) => typeof alias !== 'string' || alias.trim() === ''))) {
+            throw new Error(`GRAPH-ENTITY-ALIASES at entities[${index}].aliases: aliases must be non-empty strings`);
+        }
+        assertOptionalString(entity.summary, `entities[${index}].summary`);
+        assertOptionalStringArray(entity.tags, `entities[${index}].tags`);
+        assertOptionalRecord(entity.metadata, `entities[${index}].metadata`);
+        if (entityIds.has(entity.id)) {
+            if (!options.allowDuplicateEntityIds) {
+                throw new Error(`GRAPH-ENTITY-ID-UNIQUE at entities[${index}].id: duplicate canonical entity ID ${entity.id}`);
+            }
+        }
+        entityIds.add(entity.id);
+    }
+    if (candidate.owner !== undefined) {
+        assertOptionalRecord(candidate.owner, 'owner');
+        const owner = candidate.owner;
+        assertOptionalString(owner.id, 'owner.id');
+        assertOptionalString(owner.name, 'owner.name');
+        assertOptionalString(owner.summary, 'owner.summary');
+    }
+    if (candidate.version === 1)
+        return;
+    if (!candidate.ontology || typeof candidate.ontology !== 'object') {
+        throw new Error('GRAPH-ONTOLOGY-REQUIRED: Graph v2 requires ontology binding');
+    }
+    const ontology = candidate.ontology;
+    if (ontology.id !== 'brainbase-personal-os') {
+        throw new Error('GRAPH-ONTOLOGY-ID: Graph v2 ontology.id must be brainbase-personal-os');
+    }
+    assertNonEmptyString(ontology.version, 'ontology.version');
+    assertNonEmptyString(ontology.releaseDigest, 'ontology.releaseDigest');
+    if (!Array.isArray(candidate.edges)) {
+        throw new Error('GRAPH-SHAPE-VALID: Graph v2 edges must be an array');
+    }
+    const typedGraph = graph;
+    const entities = new Map();
+    for (const [index, entity] of typedGraph.entities.entries()) {
+        assertInterval(entity.validFrom, entity.validTo, `entities[${index}]`);
+        entities.set(entity.id, entity);
+    }
+    const edgeIds = new Set();
+    const tuples = new Set();
+    for (const [index, edge] of typedGraph.edges.entries()) {
+        if (!edge || typeof edge !== 'object') {
+            throw new Error(`GRAPH-EDGE-SHAPE at edges[${index}]: edge must be an object`);
+        }
+        assertNonEmptyString(edge.id, `edges[${index}].id`);
+        assertNonEmptyString(edge.fromId, `edges[${index}].fromId`);
+        assertNonEmptyString(edge.relation, `edges[${index}].relation`);
+        assertNonEmptyString(edge.toId, `edges[${index}].toId`);
+        assertOptionalString(edge.role, `edges[${index}].role`);
+        assertOptionalString(edge.context, `edges[${index}].context`);
+        if (edge.provenance !== undefined) {
+            assertOptionalRecord(edge.provenance, `edges[${index}].provenance`);
+            if (!['user_approved', 'migration', 'import', 'onboarding'].includes(String(edge.provenance.sourceKind))) {
+                throw new Error(`GRAPH-EDGE-PROVENANCE at edges[${index}].provenance.sourceKind: unsupported source kind`);
+            }
+            assertOptionalString(edge.provenance.sourceId, `edges[${index}].provenance.sourceId`);
+            assertOptionalString(edge.provenance.evidenceHash, `edges[${index}].provenance.evidenceHash`);
+        }
+        if (edgeIds.has(edge.id)) {
+            throw new Error(`GRAPH-EDGE-ID-UNIQUE at edges[${index}].id: duplicate canonical edge ID ${edge.id}`);
+        }
+        edgeIds.add(edge.id);
+        const tuple = JSON.stringify([edge.fromId, edge.relation, edge.toId]);
+        if (tuples.has(tuple)) {
+            throw new Error(`GRAPH-EDGE-TUPLE-UNIQUE at edges[${index}]: duplicate canonical edge ${tuple}`);
+        }
+        tuples.add(tuple);
+        const from = entities.get(edge.fromId);
+        const to = entities.get(edge.toId);
+        if (!from || !to) {
+            throw new Error(`GRAPH-EDGE-ENDPOINT-EXISTS at edges[${index}]: missing endpoint for ${tuple}`);
+        }
+        const expected = getCanonicalRelation(edge.relation);
+        if (from.type !== expected.from || to.type !== expected.to) {
+            throw new Error(`GRAPH-EDGE-ENDPOINT-TYPE at edges[${index}]: ${edge.relation} requires ${expected.from} -> ${expected.to}`);
+        }
+        if (edge.id !== canonicalEdgeId(edge)) {
+            throw new Error(`GRAPH-EDGE-ID-STABLE at edges[${index}].id: expected ${canonicalEdgeId(edge)}`);
+        }
+        assertInterval(edge.validFrom, edge.validTo, `edges[${index}]`);
+    }
+}
+export function isActiveAt(record, asOf) {
+    const instant = parseRfc3339(asOf, 'asOf');
+    const from = record.validFrom === undefined ? undefined : parseRfc3339(record.validFrom, 'validFrom');
+    const to = record.validTo === undefined ? undefined : parseRfc3339(record.validTo, 'validTo');
+    return (from === undefined || from <= instant) && (to === undefined || instant < to);
+}
+function assertInterval(validFrom, validTo, path) {
+    const from = validFrom === undefined ? undefined : parseRfc3339(validFrom, `${path}.validFrom`);
+    const to = validTo === undefined ? undefined : parseRfc3339(validTo, `${path}.validTo`);
+    if (from !== undefined && to !== undefined && from > to) {
+        throw new Error(`GRAPH-VALIDITY-ORDER at ${path}: validFrom must not be after validTo`);
+    }
+}
+function parseRfc3339(value, path) {
+    if (typeof value !== 'string') {
+        throw new Error(`GRAPH-VALIDITY-DATETIME at ${path}: validity must use RFC 3339 date-time values`);
+    }
+    const match = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.\d+)?(?:Z|[+-](\d{2}):(\d{2}))$/u.exec(value);
+    if (!match) {
+        throw new Error(`GRAPH-VALIDITY-DATETIME at ${path}: validity must use RFC 3339 date-time values`);
+    }
+    const [, yearText, monthText, dayText, hourText, minuteText, secondText, offsetHourText, offsetMinuteText] = match;
+    const year = Number(yearText);
+    const month = Number(monthText);
+    const day = Number(dayText);
+    const hour = Number(hourText);
+    const minute = Number(minuteText);
+    const second = Number(secondText);
+    const offsetHour = Number(offsetHourText ?? 0);
+    const offsetMinute = Number(offsetMinuteText ?? 0);
+    const daysInMonth = month >= 1 && month <= 12 ? new Date(Date.UTC(year, month, 0)).getUTCDate() : 0;
+    if (day < 1 || day > daysInMonth || hour > 23 || minute > 59 || second > 59 || offsetHour > 23 || offsetMinute > 59) {
+        throw new Error(`GRAPH-VALIDITY-DATETIME at ${path}: validity must use a real RFC 3339 date-time value`);
+    }
+    const parsed = Date.parse(value);
+    if (!Number.isFinite(parsed)) {
+        throw new Error(`GRAPH-VALIDITY-DATETIME at ${path}: validity must use RFC 3339 date-time values`);
+    }
+    return parsed;
+}
+function assertNonEmptyString(value, path) {
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw new Error(`GRAPH-NONEMPTY-STRING at ${path}: value must be a non-empty string`);
+    }
+}
+function assertOptionalString(value, path) {
+    if (value !== undefined && typeof value !== 'string') {
+        throw new Error(`GRAPH-OPTIONAL-STRING at ${path}: value must be a string when present`);
+    }
+}
+function assertOptionalStringArray(value, path) {
+    if (value !== undefined && (!Array.isArray(value) || value.some((item) => typeof item !== 'string'))) {
+        throw new Error(`GRAPH-STRING-ARRAY at ${path}: value must be an array of strings when present`);
+    }
+}
+function assertOptionalRecord(value, path) {
+    if (value !== undefined && (!value || typeof value !== 'object' || Array.isArray(value))) {
+        throw new Error(`GRAPH-OBJECT at ${path}: value must be an object when present`);
+    }
+}

package/dist/cli.js

@@ -3,7 +3,8 @@ import { constants, realpathSync } from 'node:fs';
 import { access, mkdir, readFile, writeFile } from 'node:fs/promises';
 import { delimiter, dirname, isAbsolute, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { initializePersonalOs, loadPersonalOs, mutatePersonalOs } from './ssot.js';
+import { initializePersonalOs, loadPersonalOs, migrateCanonicalGraph, mutatePersonalOs } from './ssot.js';
+import { diagnoseGraph } from './graph-diagnosis.js';
 import { resolveDataDir } from './paths.js';
 import { auditPersonalOsDirectory } from './ontology-ssot.js';
 import { portableOntology, resolveOntologyVersion } from './ontology.js';
@@ -15,6 +16,7 @@ import { assertPublicSafeSkillBundle, buildSkillBundle, parseSkillIds, parseSkil
 import { buildProjectRegistrationPlan, parseProjectSource, parseProjectStakeholder, renderProjectRegistrationMarkdown } from './projects.js';
 import { renderGuidedFirstRun } from './guided-onboarding.js';
 import { blockedJudgmentOutput, processJudgmentHook } from './judgment-host.js';
+import { applyCanonicalWrites, buildCanonicalEdge } from './canonical-edge-builder.js';
 export async function runCli(argv = process.argv.slice(2), io = process) {
     const parsed = parseArgs(argv);
     try {
@@ -60,6 +62,8 @@ export async function runCli(argv = process.argv.slice(2), io = process) {
                 return 0;
             case 'ontology:audit':
                 return await ontologyAudit(parsed, io);
+            case 'ontology:migrate':
+                return await ontologyMigrate(parsed, io);
             case 'judgment:hook':
                 return await judgmentHook(io);
             case 'judgment:install':
@@ -166,10 +170,9 @@ async function onboardSeed(parsed, io) {
         const personalEntries = [...os.personalKg];
         const decisions = [...os.decisions];
         const relationships = [...os.relationships.relationships];
-        const graphEntities = [...os.graph.entities];
+        const canonicalEntities = [];
         if (name) {
-            os.graph.owner = { ...os.graph.owner, name };
-            upsertGraphEntity(graphEntities, {
+            canonicalEntities.push({
                 id: 'self',
                 type: 'person',
                 name,
@@ -194,7 +197,7 @@ async function onboardSeed(parsed, io) {
             });
         }
         for (const project of parsed.values.get('project') ?? []) {
-            upsertGraphEntity(graphEntities, {
+            canonicalEntities.push({
                 id: `project-${hash(project)}`,
                 type: 'project',
                 name: project,
@@ -210,12 +213,20 @@ async function onboardSeed(parsed, io) {
             });
         }
         for (const value of parsed.values.get('decision-principle') ?? []) {
-            upsertById(decisions, {
+            const decision = {
                 id: `decision-${hash(value)}`,
                 title: 'オンボーディングで登録した判断基準',
                 decision: value,
                 tags: ['principle', 'onboarding'],
                 updatedAt: now
+            };
+            upsertById(decisions, decision);
+            canonicalEntities.push({
+                id: decision.id,
+                type: 'decision',
+                name: decision.title,
+                summary: decision.decision,
+                tags: decision.tags
             });
         }
         for (const encoded of encodedRelationships) {
@@ -228,7 +239,7 @@ async function onboardSeed(parsed, io) {
                 tags: ['relationship'],
                 updatedAt: now
             });
-            upsertGraphEntity(graphEntities, {
+            canonicalEntities.push({
                 id: `person-${hash(person)}`,
                 type: 'person',
                 name: person,
@@ -236,8 +247,53 @@ async function onboardSeed(parsed, io) {
                 tags: ['relationship']
             });
         }
+        const projects = (parsed.values.get('project') ?? []).map((project) => ({
+            id: `project-${hash(project)}`,
+            name: project
+        }));
+        const people = encodedRelationships.map((encoded) => {
+            const [person, role, context] = encoded.split('|').map((part) => part.trim());
+            return {
+                id: `person-${hash(person)}`,
+                relationshipId: `relationship-${hash(encoded)}`,
+                role: role || undefined,
+                context
+            };
+        });
+        const seedDecisions = (parsed.values.get('decision-principle') ?? []).map((decision) => ({
+            id: `decision-${hash(decision)}`,
+            decision
+        }));
+        const canonicalEdges = projects.flatMap((project) => [
+            ...(name ? [buildCanonicalEdge({
+                    fromId: 'self',
+                    relation: 'participates_in',
+                    toId: project.id,
+                    context: 'Registered together during onboarding.',
+                    provenance: { sourceKind: 'onboarding', sourceId: project.id }
+                })] : []),
+            ...people.map((person) => buildCanonicalEdge({
+                fromId: person.id,
+                relation: 'participates_in',
+                toId: project.id,
+                role: person.role,
+                context: person.context,
+                provenance: { sourceKind: 'onboarding', sourceId: person.relationshipId }
+            })),
+            ...seedDecisions.map((decision) => buildCanonicalEdge({
+                fromId: decision.id,
+                relation: 'governs',
+                toId: project.id,
+                context: decision.decision,
+                provenance: { sourceKind: 'onboarding', sourceId: decision.id }
+            }))
+        ]);
+        const graph = applyCanonicalWrites(os.graph, { entities: canonicalEntities, edges: canonicalEdges });
         return proposedPersonalOs(os, {
-            graph: { ...os.graph, entities: graphEntities },
+            graph: {
+                ...graph,
+                owner: { ...graph.owner, ...(name ? { id: 'self', name } : {}) }
+            },
             relationships: { version: 1, relationships },
             personalKg: personalEntries,
             decisions
@@ -257,7 +313,7 @@ async function onboardSeed(parsed, io) {
         '',
         '次に実行:',
         `brainbase onboard:install --target codex --dir ${shellArg(dataDir)} --dry-run`,
-        '設定を承認・反映してエージェントを再起動した後、実際の依頼でBrainbaseのget_contextとsearchを使います。',
+        '設定を承認・反映してエージェントを再起動した後、実際の依頼でBrainbaseのresolve_entity、get_context、searchを使います。',
         ''
     ];
     write(io, summary.join('\n'));
@@ -464,21 +520,27 @@ async function onboardProjects(parsed, io) {
 }
 async function applyProjectRegistrationPlan(dataDir, plan) {
     await mutatePersonalOs(dataDir, (os) => {
-        const graphEntities = [...os.graph.entities];
-        for (const entity of plan.writes.graphEntities) {
-            upsertGraphEntity(graphEntities, entity);
-        }
+        const graph = applyCanonicalWrites(os.graph, {
+            entities: plan.writes.canonicalEntities,
+            edges: plan.writes.canonicalEdges
+        });
         const relationships = [...os.relationships.relationships];
         for (const relationship of plan.writes.relationships) {
-            if (!relationships.some((existing) => existing.id === relationship.id)) {
-                relationships.push(relationship);
-            }
+            upsertById(relationships, relationship);
+        }
+        const personalKg = [...os.personalKg];
+        for (const entry of plan.writes.personalKg) {
+            upsertById(personalKg, entry);
+        }
+        const decisions = [...os.decisions];
+        for (const decision of plan.writes.decisions) {
+            upsertById(decisions, decision);
         }
         return proposedPersonalOs(os, {
-            graph: { ...os.graph, entities: graphEntities },
+            graph,
             relationships: { version: 1, relationships },
-            personalKg: [...os.personalKg, ...plan.writes.personalKg],
-            decisions: [...os.decisions, ...plan.writes.decisions]
+            personalKg,
+            decisions
         });
     });
 }
@@ -558,25 +620,40 @@ async function onboardApply(parsed, io) {
     let result;
     if (willWrite) {
         await mutatePersonalOs(dataDir, (os) => {
+            if (os.graph.version !== 2) {
+                throw new Error('migration_required: Graph v1 cannot store canonical ID edges; migrate graph.json to Graph v2 before writing');
+            }
             result = planApply(candidates, { ids: selectedIds, all }, {
                 graphEntities: [...os.graph.entities],
+                graphEdges: [...os.graph.edges],
                 relationships: [...os.relationships.relationships],
                 personalKg: os.personalKg,
                 decisions: os.decisions,
                 ownerName: os.graph.owner?.name
             }, now);
+            const personalKg = [...os.personalKg];
+            for (const entry of result.personalKgAdditions)
+                upsertById(personalKg, entry);
+            const decisions = [...os.decisions];
+            for (const decision of result.decisionAdditions)
+                upsertById(decisions, decision);
+            const graph = applyCanonicalWrites(os.graph, result.canonicalWrites);
             return proposedPersonalOs(os, {
-                graph: { ...os.graph, owner: result.ownerName ? { ...os.graph.owner, name: result.ownerName } : os.graph.owner, entities: result.graphEntities },
+                graph: { ...graph, owner: result.ownerName ? { ...graph.owner, name: result.ownerName } : graph.owner },
                 relationships: { version: 1, relationships: result.relationships },
-                personalKg: [...os.personalKg, ...result.personalKgAdditions],
-                decisions: [...os.decisions, ...result.decisionAdditions]
+                personalKg,
+                decisions
             });
         });
     }
     else {
         const os = await loadPersonalOs(dataDir);
+        if (os.graph.version !== 2) {
+            throw new Error('migration_required: Graph v1 cannot store canonical ID edges; migrate graph.json to Graph v2 before writing');
+        }
         result = planApply(candidates, { ids: selectedIds, all }, {
             graphEntities: [...os.graph.entities],
+            graphEdges: [...os.graph.edges],
             relationships: [...os.relationships.relationships],
             personalKg: os.personalKg,
             decisions: os.decisions,
@@ -819,12 +896,23 @@ async function writeConfigSnippet(outputPath, payload) {
 }
 async function doctor(parsed, io) {
     const dataDir = resolveDataDir(first(parsed, 'dir'));
-    const os = await loadPersonalOs(dataDir);
-    const status = onboardingStatus(os);
+    const graphDiagnosis = await diagnoseGraph(dataDir);
+    let status;
+    try {
+        status = onboardingStatus(await loadPersonalOs(dataDir));
+    }
+    catch (error) {
+        write(io, `${JSON.stringify({
+            graphDiagnosis,
+            localBackend: { connected: false, backend: 'local' },
+            issue: error instanceof Error ? error.message : String(error)
+        }, null, 2)}\n`);
+        return graphDiagnosisExitCode(graphDiagnosis.status) || 1;
+    }
     const judgmentHooksPath = first(parsed, 'judgment-hooks');
     if (!judgmentHooksPath) {
-        write(io, `${JSON.stringify(status, null, 2)}\n`);
-        return 0;
+        write(io, `${JSON.stringify({ ...status, graphDiagnosis }, null, 2)}\n`);
+        return graphDiagnosisExitCode(graphDiagnosis.status);
     }
     const config = JSON.parse(await readFile(judgmentHooksPath, 'utf8'));
     const hooks = config.hooks;
@@ -841,9 +929,13 @@ async function doctor(parsed, io) {
         throw new Error('judgment_hooks_invalid');
     write(io, `${JSON.stringify({
         ...status,
+        graphDiagnosis,
         judgment_hooks: { status: 'ready', events: requiredEvents, source: judgmentHooksPath }
     }, null, 2)}\n`);
-    return 0;
+    return graphDiagnosisExitCode(graphDiagnosis.status);
+}
+function graphDiagnosisExitCode(status) {
+    return status === 'invalid' || status === 'unavailable' || status === 'migration_required' ? 1 : 0;
 }
 function parseArgs(argv) {
     const [firstToken, ...remaining] = argv;
@@ -905,9 +997,6 @@ function upsertById(entries, entry) {
         entries.push(entry);
     }
 }
-function upsertGraphEntity(entities, entity) {
-    upsertById(entities, entity);
-}
 function hash(value) {
     let hashValue = 0;
     for (const char of value) {
@@ -923,7 +1012,10 @@ function writeError(io, text) {
 }
 async function ontologyAudit(parsed, io) {
     const dataDir = resolveDataDir(first(parsed, 'dir'));
-    const ontologyVersion = resolveOntologyVersion(first(parsed, 'ontology-version'));
+    const requestedVersion = first(parsed, 'ontology-version');
+    const ontologyVersion = requestedVersion === undefined
+        ? undefined
+        : resolveOntologyVersion(requestedVersion);
     const result = await auditPersonalOsDirectory(dataDir, { ontologyVersion });
     write(io, `${JSON.stringify(result, null, 2)}\n`);
     if (result.status === 'unverified') {
@@ -931,6 +1023,15 @@ async function ontologyAudit(parsed, io) {
     }
     return result.violations.some((violation) => violation.severity === 'error') ? 1 : 0;
 }
+async function ontologyMigrate(parsed, io) {
+    const dataDir = resolveDataDir(first(parsed, 'dir'));
+    const result = await migrateCanonicalGraph(dataDir, {
+        write: parsed.flags.has('write'),
+        expectedInputDigest: first(parsed, 'expected-input-digest')
+    });
+    write(io, `${JSON.stringify(result, null, 2)}\n`);
+    return result.status === 'blocked' ? 1 : 0;
+}
 function proposedPersonalOs(os, proposed) {
     return { ...os, ...proposed };
 }
@@ -962,7 +1063,8 @@ function usage() {
   brainbase onboard:routines --target codex|claude [--routines ohayo,oyasumi,retro] [--ohayo-hour n] [--oyasumi-hour n] [--retro-dow MON-SUN] [--retro-hour n] [--cwd path] [--out path] [--format markdown|json]
   brainbase onboard:skills --target codex|claude|portable [--skills id,id] [--out dir] [--format markdown|json]
   brainbase ontology:show
-  brainbase ontology:audit [--dir path] [--ontology-version 0.0.0|1.0.0]
+  brainbase ontology:audit [--dir path] [--ontology-version 0.0.0|1.0.0|2.0.0]
+  brainbase ontology:migrate [--dir path] [--write --expected-input-digest digest]
   brainbase judgment:install --target codex [--dry-run] [--output path]
   brainbase judgment:hook
   brainbase doctor [--dir path] [--judgment-hooks path]