@unson/brainbase-mcp 0.2.4 → 0.3.0

package/dist/ontology-migration.js

@@ -0,0 +1,339 @@
+import { createHash } from 'node:crypto';
+import { canonicalEdgeId, validateCanonicalGraph } from './canonical-graph.js';
+import { canonicalGraphOntologyRelease } from './templates.js';
+/**
+ * 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 function planCanonicalGraphMigration(input) {
+    validateCanonicalGraph(input.graph);
+    validateRelationshipIds(input.relationships?.relationships ?? []);
+    validateDecisionRecordIds(input.decisions ?? []);
+    const inputDigest = digest(normalizeMigrationInput(input));
+    const issues = [];
+    if (input.graph.version === 2) {
+        const graph = structuredClone(input.graph);
+        validateGraphSupersession(graph, issues);
+        return {
+            status: issues.length === 0 ? 'up_to_date' : 'blocked',
+            graph,
+            issues: issues.sort(compareIssues),
+            inputDigest,
+            outputDigest: digest(graph),
+            changes: { entitiesAdded: 0, edgesAdded: 0 }
+        };
+    }
+    validateDecisionEntityIds(input.graph, input.decisions ?? []);
+    reportUnsupportedLegacyEntities(input.graph, issues);
+    const invalidSupersessionSources = validateDecisionSupersession(input.decisions ?? [], issues);
+    const entities = migrateEntities(input.graph, input.decisions ?? []);
+    const entityById = new Map(entities.map((entity) => [entity.id, entity]));
+    const edges = new Map();
+    addExplicitProjectMembershipEdges(input.graph, entityById, edges, issues);
+    validateRelationshipEvidence(input.relationships?.relationships ?? [], entities, entityById, issues);
+    addDecisionEdges(input.graph, input.decisions ?? [], entityById, edges, issues, invalidSupersessionSources);
+    const owner = migrateOwner(input.graph, entities);
+    const graph = {
+        version: 2,
+        ontology: { ...canonicalGraphOntologyRelease.binding },
+        ...(owner ? { owner } : {}),
+        entities: [...entities].sort((left, right) => left.id.localeCompare(right.id, 'en')),
+        edges: [...edges.values()].sort((left, right) => left.id.localeCompare(right.id, 'en'))
+    };
+    validateCanonicalGraph(graph);
+    return {
+        status: issues.length === 0 ? 'migration_required' : 'blocked',
+        graph,
+        issues: issues.sort(compareIssues),
+        inputDigest,
+        outputDigest: digest(graph),
+        changes: {
+            entitiesAdded: (input.decisions ?? []).filter((decision) => !input.graph.entities.some((entity) => entity.id === decision.id)).length,
+            edgesAdded: graph.edges.length
+        }
+    };
+}
+function validateRelationshipIds(relationships) {
+    const ids = new Set();
+    for (const relationship of relationships) {
+        if (ids.has(relationship.id)) {
+            throw new Error(`ONT-RELATIONSHIP-ID-UNIQUE: duplicate relationship ID ${relationship.id}`);
+        }
+        ids.add(relationship.id);
+    }
+}
+function reportUnsupportedLegacyEntities(graph, issues) {
+    for (const entity of graph.entities) {
+        if (entity.type !== 'relationship')
+            continue;
+        issues.push({
+            code: 'unsupported_relationship_entity',
+            recordId: entity.id,
+            detail: 'Legacy relationship entities have no lossless canonical v2 representation; resolve them before writing migration output'
+        });
+    }
+}
+function validateDecisionSupersession(decisions, issues) {
+    const decisionIds = new Set(decisions.map((decision) => decision.id));
+    const adjacency = new Map();
+    const invalidSources = new Set();
+    for (const decision of decisions) {
+        const targets = [...new Set(decision.supersedes ?? [])].sort((left, right) => left.localeCompare(right, 'en'));
+        if (targets.includes(decision.id)) {
+            invalidSources.add(decision.id);
+            issues.push({
+                code: 'decision_supersedes_self',
+                recordId: decision.id,
+                detail: 'ONT-DECISION-SUPERSEDES-SELF: a decision cannot supersede itself'
+            });
+        }
+        adjacency.set(decision.id, targets.filter((target) => target !== decision.id && decisionIds.has(target)));
+    }
+    for (const decisionId of [...decisionIds].sort((left, right) => left.localeCompare(right, 'en'))) {
+        if (!canReach(adjacency, decisionId, decisionId, new Set()))
+            continue;
+        invalidSources.add(decisionId);
+        issues.push({
+            code: 'decision_supersedes_cycle',
+            recordId: decisionId,
+            detail: 'ONT-DECISION-SUPERSEDES-CYCLE: decision supersession must be acyclic'
+        });
+    }
+    return invalidSources;
+}
+function validateGraphSupersession(graph, issues) {
+    const decisionIds = new Set(graph.entities.filter((entity) => entity.type === 'decision').map((entity) => entity.id));
+    const adjacency = new Map([...decisionIds].map((id) => [id, []]));
+    for (const edge of graph.edges) {
+        if (edge.relation !== 'supersedes')
+            continue;
+        if (edge.fromId === edge.toId) {
+            issues.push({
+                code: 'decision_supersedes_self',
+                recordId: edge.fromId,
+                detail: 'ONT-DECISION-SUPERSEDES-SELF: a decision cannot supersede itself'
+            });
+            continue;
+        }
+        adjacency.get(edge.fromId)?.push(edge.toId);
+    }
+    for (const targets of adjacency.values())
+        targets.sort((left, right) => left.localeCompare(right, 'en'));
+    for (const decisionId of [...decisionIds].sort((left, right) => left.localeCompare(right, 'en'))) {
+        if (!canReach(adjacency, decisionId, decisionId, new Set()))
+            continue;
+        issues.push({
+            code: 'decision_supersedes_cycle',
+            recordId: decisionId,
+            detail: 'ONT-DECISION-SUPERSEDES-CYCLE: decision supersession must be acyclic'
+        });
+    }
+}
+function canReach(adjacency, start, current, visited) {
+    if (visited.has(current))
+        return false;
+    visited.add(current);
+    for (const target of adjacency.get(current) ?? []) {
+        if (target === start)
+            return true;
+        if (canReach(adjacency, start, target, visited))
+            return true;
+    }
+    return false;
+}
+function migrateEntities(graph, decisions) {
+    const migrated = new Map();
+    for (const entity of graph.entities) {
+        if (entity.type === 'relationship')
+            continue;
+        migrated.set(entity.id, {
+            id: entity.id,
+            type: entity.type,
+            name: entity.name,
+            ...(entity.summary === undefined ? {} : { summary: entity.summary }),
+            ...(entity.tags === undefined ? {} : { tags: [...entity.tags] }),
+            ...(entity.metadata === undefined ? {} : { metadata: structuredClone(entity.metadata) })
+        });
+    }
+    for (const decision of decisions) {
+        migrated.set(decision.id, {
+            id: decision.id,
+            type: 'decision',
+            name: decision.title,
+            ...(decision.decision === decision.title ? {} : { aliases: [decision.decision] }),
+            summary: decision.decision,
+            ...(decision.effectiveAt === undefined ? {} : { validFrom: decision.effectiveAt }),
+            ...(decision.tags === undefined ? {} : { tags: [...decision.tags] }),
+            metadata: {
+                ...(decision.topic === undefined ? {} : { topic: decision.topic }),
+                ...(decision.rationale === undefined ? {} : { rationale: decision.rationale })
+            }
+        });
+    }
+    return [...migrated.values()];
+}
+function addExplicitProjectMembershipEdges(graph, entityById, edges, issues) {
+    for (const entity of graph.entities) {
+        if (entity.type !== 'person')
+            continue;
+        const projectId = stringMetadata(entity.metadata, 'projectId');
+        if (!projectId)
+            continue;
+        if (entityById.get(projectId)?.type !== 'project') {
+            issues.push({
+                code: 'missing_project_endpoint',
+                recordId: entity.id,
+                detail: `Explicit project ID ${projectId} does not identify a canonical project`
+            });
+            continue;
+        }
+        addEdge(edges, {
+            fromId: entity.id,
+            relation: 'participates_in',
+            toId: projectId,
+            provenance: { sourceKind: 'migration', sourceId: entity.id }
+        });
+    }
+}
+function validateRelationshipEvidence(relationships, entities, entityById, issues) {
+    for (const relationship of relationships) {
+        const people = entities.filter((entity) => entity.type === 'person' && entity.name === relationship.person);
+        if (people.length === 0) {
+            issues.push({ code: 'unresolved_person', recordId: relationship.id, detail: `No canonical person exactly matches ${relationship.person}` });
+            continue;
+        }
+        if (people.length > 1) {
+            issues.push({ code: 'ambiguous_person', recordId: relationship.id, detail: `${relationship.person} matches ${people.length} canonical people` });
+            continue;
+        }
+        const person = people[0];
+        const projectId = stringMetadata(person.metadata, 'projectId');
+        if (!projectId || entityById.get(projectId)?.type !== 'project') {
+            issues.push({
+                code: 'missing_project_evidence',
+                recordId: relationship.id,
+                detail: 'Free-form relationship context cannot be promoted without an explicit canonical project ID'
+            });
+            continue;
+        }
+        // `role` and `context` are legacy display text, not typed relation evidence.
+        // The explicit person.metadata.projectId edge above is the only safe
+        // relationship promotion available in Graph v1.
+    }
+}
+function validateDecisionEntityIds(graph, decisions) {
+    const occupied = new Set(graph.entities.map((entity) => entity.id));
+    for (const decision of decisions) {
+        if (occupied.has(decision.id)) {
+            throw new Error(`MIGRATION-ENTITY-ID-COLLISION: decision ${decision.id} conflicts with an existing canonical entity`);
+        }
+    }
+}
+function validateDecisionRecordIds(decisions) {
+    const ids = new Set();
+    for (const decision of decisions) {
+        if (ids.has(decision.id)) {
+            throw new Error(`ONT-DECISION-ID-UNIQUE: duplicate decision ID ${decision.id}`);
+        }
+        ids.add(decision.id);
+    }
+}
+function addDecisionEdges(graph, decisions, entityById, edges, issues, invalidSupersessionSources) {
+    const projects = graph.entities.filter((entity) => entity.type === 'project');
+    for (const decision of decisions) {
+        const matchingProjects = projects.filter((project) => stringArrayMetadata(project.metadata, 'decisionPrinciples').includes(decision.decision));
+        if (matchingProjects.length === 1) {
+            addEdge(edges, {
+                fromId: decision.id,
+                relation: 'governs',
+                toId: matchingProjects[0].id,
+                ...(decision.effectiveAt === undefined ? {} : { validFrom: decision.effectiveAt }),
+                provenance: { sourceKind: 'migration', sourceId: decision.id }
+            });
+        }
+        else if (matchingProjects.length > 1) {
+            issues.push({
+                code: 'ambiguous_decision_project',
+                recordId: decision.id,
+                detail: `Decision text exactly matches ${matchingProjects.length} project principles`
+            });
+        }
+        for (const supersededId of decision.supersedes ?? []) {
+            if (invalidSupersessionSources.has(decision.id))
+                continue;
+            if (entityById.get(supersededId)?.type !== 'decision') {
+                issues.push({ code: 'missing_decision_endpoint', recordId: decision.id, detail: `Missing superseded decision ${supersededId}` });
+                continue;
+            }
+            addEdge(edges, {
+                fromId: decision.id,
+                relation: 'supersedes',
+                toId: supersededId,
+                ...(decision.effectiveAt === undefined ? {} : { validFrom: decision.effectiveAt }),
+                provenance: { sourceKind: 'migration', sourceId: decision.id }
+            });
+        }
+    }
+}
+function addEdge(edges, edge) {
+    const complete = { ...edge, id: canonicalEdgeId(edge) };
+    edges.set(JSON.stringify([edge.fromId, edge.relation, edge.toId]), complete);
+}
+function migrateOwner(graph, entities) {
+    if (!graph.owner)
+        return undefined;
+    const matches = graph.owner.name
+        ? entities.filter((entity) => entity.type === 'person' && entity.name === graph.owner.name)
+        : [];
+    return {
+        ...(matches.length === 1 ? { id: matches[0].id } : {}),
+        ...(graph.owner.name === undefined ? {} : { name: graph.owner.name }),
+        ...(graph.owner.summary === undefined ? {} : { summary: graph.owner.summary })
+    };
+}
+function stringMetadata(metadata, key) {
+    const value = metadata?.[key];
+    return typeof value === 'string' && value.trim() !== '' ? value : undefined;
+}
+function stringArrayMetadata(metadata, key) {
+    const value = metadata?.[key];
+    return Array.isArray(value) ? value.filter((item) => typeof item === 'string') : [];
+}
+function digest(value) {
+    return createHash('sha256').update(JSON.stringify(canonicalize(value))).digest('hex');
+}
+function normalizeMigrationInput(input) {
+    return {
+        ...structuredClone(input),
+        graph: {
+            ...structuredClone(input.graph),
+            entities: [...input.graph.entities].sort((left, right) => left.id.localeCompare(right.id, 'en')),
+            ...(input.graph.version === 2
+                ? { edges: [...input.graph.edges].sort((left, right) => left.id.localeCompare(right.id, 'en')) }
+                : {})
+        },
+        ...(input.relationships === undefined ? {} : {
+            relationships: {
+                ...structuredClone(input.relationships),
+                relationships: [...input.relationships.relationships].sort((left, right) => left.id.localeCompare(right.id, 'en'))
+            }
+        }),
+        ...(input.decisions === undefined ? {} : {
+            decisions: [...input.decisions].sort((left, right) => left.id.localeCompare(right.id, 'en'))
+        })
+    };
+}
+function canonicalize(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalize);
+    if (!value || typeof value !== 'object')
+        return value;
+    return Object.fromEntries(Object.entries(value)
+        .sort(([left], [right]) => left.localeCompare(right, 'en'))
+        .map(([key, nested]) => [key, canonicalize(nested)]));
+}
+function compareIssues(left, right) {
+    return `${left.recordId}\u0000${left.code}`.localeCompare(`${right.recordId}\u0000${right.code}`, 'en');
+}

package/dist/ontology-ssot.js

@@ -1,11 +1,11 @@
 import { auditOntology, resolveOntologyVersion } from './ontology.js';
 import { loadPersonalOs } from './ssot.js';
 export async function auditPersonalOsDirectory(dataDir, options = {}) {
-    const ontologyVersion = resolveOntologyVersion(options.ontologyVersion);
     try {
-        return auditOntology(await loadPersonalOs(dataDir), { ontologyVersion });
+        return auditOntology(await loadPersonalOs(dataDir), options);
     }
     catch (error) {
+        const ontologyVersion = resolveOntologyVersion(options.ontologyVersion);
         const message = error instanceof Error ? error.message : String(error);
         return {
             status: 'unverified',

package/dist/ontology.d.ts

@@ -1,6 +1,7 @@
 import type { DecisionRecord, PersonalOs } from './types.js';
-export declare const ONTOLOGY_VERSION: "1.0.0";
-export declare const SUPPORTED_ONTOLOGY_VERSIONS: readonly ["0.0.0", "1.0.0"];
+export declare const ONTOLOGY_V1_VERSION: "1.0.0";
+export declare const ONTOLOGY_VERSION: "2.0.0";
+export declare const SUPPORTED_ONTOLOGY_VERSIONS: readonly ["0.0.0", "1.0.0", "2.0.0"];
 export type OntologyVersion = typeof SUPPORTED_ONTOLOGY_VERSIONS[number];
 export type OntologySeverity = 'error' | 'warning';
 export interface OntologyViolation {
@@ -39,7 +40,8 @@ export interface UnverifiedOntologyAuditResult {
     issues: OntologyViolation[];
 }
 export type PersonalOsOntologyAudit = OntologyAuditResult | UnverifiedOntologyAuditResult;
-export declare const portableOntology: {
+/** Historical public release. Never derive it from the active release. */
+export declare const portableOntologyV1: {
     readonly version: "1.0.0";
     readonly effectiveAt: "2026-08-03T00:00:00.000Z";
     readonly compatibility: "read-compatible-write-gated";
@@ -136,6 +138,102 @@ export declare const portableOntology: {
         };
     };
 };
+export declare const portableOntology: {
+    readonly version: "2.0.0";
+    readonly effectiveAt: "2026-08-17T00:00:00.000Z";
+    readonly compatibility: "read-compatible-write-gated";
+    readonly name: "Brainbase Portable Ontology Kernel";
+    readonly description: "A local-first semantic contract for canonical Graph entities and ID-based edges.";
+    readonly domains: {
+        readonly types: {
+            readonly concepts: readonly [{
+                readonly id: "person";
+                readonly meaning: "A human represented in the local Graph.";
+                readonly usageConditions: readonly ["Use only for a human identity approved for the canonical local SSOT."];
+            }, {
+                readonly id: "org";
+                readonly meaning: "An organization represented in the local Graph.";
+                readonly usageConditions: readonly ["Use for a named organizational actor, not for a project or product."];
+            }, {
+                readonly id: "project";
+                readonly meaning: "A bounded body of work represented in the local Graph.";
+                readonly usageConditions: readonly ["Use when the entity has a bounded work objective; do not use it as an organization alias."];
+            }, {
+                readonly id: "relationship";
+                readonly meaning: "A contextual connection to a person.";
+                readonly usageConditions: readonly ["The person field must resolve to a canonical person entity by name."];
+            }, {
+                readonly id: "decision";
+                readonly meaning: "A durable choice that may explicitly supersede another choice.";
+                readonly usageConditions: readonly ["Use for an explicit durable choice; replacement requires a supersedes Decision ID."];
+            }];
+        };
+        readonly relations: {
+            readonly vocabulary: {
+                id: import("./types.js").CoreRelation;
+                source: import("./types.js").CanonicalEntityKind;
+                target: import("./types.js").CanonicalEntityKind;
+            }[];
+        };
+        readonly constraints: {
+            readonly rules: readonly [{
+                readonly id: "ONT-ENTITY-ID-UNIQUE";
+                readonly severity: "error";
+                readonly meaning: "Graph entity IDs must be unique.";
+            }, {
+                readonly id: "ONT-RELATIONSHIP-ID-UNIQUE";
+                readonly severity: "error";
+                readonly meaning: "Relationship IDs must be unique.";
+            }, {
+                readonly id: "ONT-DECISION-ID-UNIQUE";
+                readonly severity: "error";
+                readonly meaning: "Decision IDs must be unique.";
+            }, {
+                readonly id: "ONT-RELATIONSHIP-PERSON-RESOLVES";
+                readonly severity: "warning";
+                readonly meaning: "A relationship person should resolve to a canonical person entity by name.";
+            }, {
+                readonly id: "ONT-DECISION-SUPERSEDES-EXISTS";
+                readonly severity: "error";
+                readonly meaning: "A supersedes reference must resolve to an existing decision.";
+            }, {
+                readonly id: "ONT-DECISION-SUPERSEDES-SELF";
+                readonly severity: "error";
+                readonly meaning: "A decision must not supersede itself.";
+            }, {
+                readonly id: "ONT-DECISION-SUPERSEDES-CYCLE";
+                readonly severity: "error";
+                readonly meaning: "Decision supersession edges must not form a cycle.";
+            }];
+        };
+        readonly inference: {
+            readonly rules: readonly [{
+                readonly id: "ONT-INFER-EXPLICIT-SUPERSESSION";
+                readonly meaning: "Only an explicit supersedes edge makes an older decision inactive.";
+            }, {
+                readonly id: "ONT-INFER-SAME-TOPIC-CONFLICT";
+                readonly meaning: "Multiple active decisions on the same explicit topic are reported as a conflict.";
+            }];
+        };
+        readonly evolution: {
+            readonly compatibility: readonly [{
+                readonly fromVersion: "0.0.0";
+                readonly toVersion: "2.0.0";
+                readonly level: "read-compatible-write-gated";
+                readonly changes: readonly ["Adds a versioned public semantic contract.", "Adds canonical Graph v2 entities and ID-based edges governed by the Relation Registry."];
+                readonly migration: "Before enabling 2.0.0 writes, back up the Personal OS directory, run ontology:audit, preview ontology:migrate, then write using the preview expectedInputDigest.";
+                readonly rollback: "For an installation without a prior package, run npm uninstall -g @unson/brainbase-mcp, restore the captured MCP client configuration, and restart the client. Otherwise restore the pre-migration Personal OS backup and reinstall the recorded last known working package version.";
+            }, {
+                readonly fromVersion: "1.0.0";
+                readonly toVersion: "2.0.0";
+                readonly level: "read-compatible-write-gated";
+                readonly changes: readonly ["Adds canonical Graph v2 entities and ID-based edges.", "Binds the portable ontology release to the canonical Relation Registry."];
+                readonly migration: "Run ontology:audit --ontology-version 1.0.0, preview ontology:migrate, then write using the preview expectedInputDigest.";
+                readonly rollback: "Restore the pre-migration Personal OS backup; the immutable 1.0.0 interpretation remains available for historical reads.";
+            }];
+        };
+    };
+};
 export declare function auditOntology(os: PersonalOs, options?: {
     ontologyVersion?: OntologyVersion;
 }): OntologyAuditResult;

package/dist/ontology.js

@@ -1,7 +1,9 @@
-export const ONTOLOGY_VERSION = '1.0.0';
-export const SUPPORTED_ONTOLOGY_VERSIONS = ['0.0.0', ONTOLOGY_VERSION];
-const release = {
-    version: ONTOLOGY_VERSION,
+import { canonicalRelationRegistry } from './relation-registry.js';
+export const ONTOLOGY_V1_VERSION = '1.0.0';
+export const ONTOLOGY_VERSION = '2.0.0';
+export const SUPPORTED_ONTOLOGY_VERSIONS = ['0.0.0', ONTOLOGY_V1_VERSION, ONTOLOGY_VERSION];
+const releaseV1 = {
+    version: ONTOLOGY_V1_VERSION,
     effectiveAt: '2026-08-03T00:00:00.000Z',
     compatibility: 'read-compatible-write-gated',
     name: 'Brainbase Portable Ontology Kernel',
@@ -70,7 +72,7 @@ const release = {
             compatibility: [
                 {
                     fromVersion: '0.0.0',
-                    toVersion: ONTOLOGY_VERSION,
+                    toVersion: ONTOLOGY_V1_VERSION,
                     level: 'read-compatible-write-gated',
                     changes: [
                         'Adds a versioned public semantic contract.',
@@ -83,9 +85,56 @@ const release = {
         }
     }
 };
-export const portableOntology = deepFreeze(release);
+/** Historical public release. Never derive it from the active release. */
+export const portableOntologyV1 = deepFreeze(releaseV1);
+const releaseV2 = {
+    version: ONTOLOGY_VERSION,
+    effectiveAt: '2026-08-17T00:00:00.000Z',
+    compatibility: 'read-compatible-write-gated',
+    name: 'Brainbase Portable Ontology Kernel',
+    description: 'A local-first semantic contract for canonical Graph entities and ID-based edges.',
+    domains: {
+        types: portableOntologyV1.domains.types,
+        relations: {
+            vocabulary: Object.values(canonicalRelationRegistry).map((definition) => ({
+                id: definition.id,
+                source: definition.from,
+                target: definition.to
+            }))
+        },
+        constraints: portableOntologyV1.domains.constraints,
+        inference: portableOntologyV1.domains.inference,
+        evolution: {
+            compatibility: [
+                {
+                    fromVersion: '0.0.0',
+                    toVersion: ONTOLOGY_VERSION,
+                    level: 'read-compatible-write-gated',
+                    changes: [
+                        'Adds a versioned public semantic contract.',
+                        'Adds canonical Graph v2 entities and ID-based edges governed by the Relation Registry.'
+                    ],
+                    migration: 'Before enabling 2.0.0 writes, back up the Personal OS directory, run ontology:audit, preview ontology:migrate, then write using the preview expectedInputDigest.',
+                    rollback: 'For an installation without a prior package, run npm uninstall -g @unson/brainbase-mcp, restore the captured MCP client configuration, and restart the client. Otherwise restore the pre-migration Personal OS backup and reinstall the recorded last known working package version.'
+                },
+                {
+                    fromVersion: ONTOLOGY_V1_VERSION,
+                    toVersion: ONTOLOGY_VERSION,
+                    level: 'read-compatible-write-gated',
+                    changes: [
+                        'Adds canonical Graph v2 entities and ID-based edges.',
+                        'Binds the portable ontology release to the canonical Relation Registry.'
+                    ],
+                    migration: 'Run ontology:audit --ontology-version 1.0.0, preview ontology:migrate, then write using the preview expectedInputDigest.',
+                    rollback: 'Restore the pre-migration Personal OS backup; the immutable 1.0.0 interpretation remains available for historical reads.'
+                }
+            ]
+        }
+    }
+};
+export const portableOntology = deepFreeze(releaseV2);
 export function auditOntology(os, options = {}) {
-    const ontologyVersion = resolveOntologyVersion(options.ontologyVersion);
+    const ontologyVersion = resolvePersonalOsOntologyVersion(os, options.ontologyVersion);
     const violations = [];
     // 0.0.0 names the pre-kernel legacy semantics. Canonical shape validation is
     // still performed by the SSOT reader, but no 1.0.0 semantic rules are
@@ -118,7 +167,7 @@ export function assertOntologyValid(os) {
     }
 }
 export function inferPersonalOs(os, options = {}) {
-    const ontologyVersion = resolveOntologyVersion(options.ontologyVersion);
+    const ontologyVersion = resolvePersonalOsOntologyVersion(os, options.ontologyVersion);
     const audit = auditOntology(os, { ontologyVersion });
     const errors = audit.violations.filter((violation) => violation.severity === 'error');
     if (errors.length > 0) {
@@ -311,6 +360,13 @@ export function resolveOntologyVersion(version) {
     }
     return requested;
 }
+function resolvePersonalOsOntologyVersion(os, requestedVersion) {
+    if (requestedVersion !== undefined)
+        return resolveOntologyVersion(requestedVersion);
+    if (os.graph.version === 2)
+        return resolveOntologyVersion(os.graph.ontology.version);
+    return resolveOntologyVersion(undefined);
+}
 function auditDecisionSupersession(decisions, violations) {
     const ids = new Set(decisions.map((decision) => decision.id));
     const edges = new Map(decisions.map((decision) => [decision.id, decision.supersedes ?? []]));

package/dist/operationalization.js

@@ -51,21 +51,21 @@ export function buildOperationalizationPlan(input = {}) {
             },
             {
                 id: 'verification',
-                title: 'doctorとMCP get_context / searchで確認する',
+                title: 'doctorとMCP resolve_entity / get_context / searchで確認する',
                 status: 'pending',
                 command: `brainbase doctor --dir ${commandArg(dataDir)}`,
                 why: '新しいエージェントセッションでdoctorとMCPツールが承認済み文脈を示して初めて運用可能です。',
-                safety: 'コマンド生成だけで完了扱いせず、設定反映後にget_context/searchを確認します。'
+                safety: 'コマンド生成だけで完了扱いせず、設定反映後にresolve_entity/get_context/searchを確認します。'
             }
         ],
         recommendedOrder: [
             'Brainbase MCP設定を実際のCodex / Claude / CodeCode設定へ反映し、エージェントを再起動する。',
-            '新しいエージェントで現実の依頼を送り、MCP get_contextとsearchを使った実回答を確認する。',
+            '新しいエージェントで現実の依頼を送り、MCP resolve_entity、get_context、searchを使った実回答を確認する。',
             '利用者本人に役立ったかを確認する。役立たなければ不足文脈だけを追加して再試行する。',
             '対象エージェントへ公開スキルを配置する。',
             '必要になった時だけohayo / oyasumi / retroを確認付きで登録する。',
             '追加文脈が必要な場合だけ参照許可範囲を決め、取込と候補レビューを行う。',
-            'doctorを実行し、新しいエージェントセッションでMCP get_contextとsearchを確認する。'
+            'doctorを実行し、新しいエージェントセッションでMCP resolve_entity、get_context、searchを確認する。'
         ],
         safetyRules: [
             '利用者の承認なしに実設定、スケジュール、正本ファクトを書き込みません。',
@@ -74,10 +74,10 @@ export function buildOperationalizationPlan(input = {}) {
             '参照元の取込はローカル優先とし、正本化前にレビューします。'
         ],
         completionCheck: [
-            '実際のエージェントがBrainbase MCP get_context/searchを使って現実の依頼へ回答済み。',
+            '実際のエージェントがBrainbase MCP resolve_entity/get_context/searchを使って現実の依頼へ回答済み。',
             '利用者本人がその回答を役立つと確認済み。',
             '完了報告に残っている運用設定をすべて記載済み。',
-            '実設定反映後、対象エージェントからBrainbase MCP get_context/searchを呼び出せる。',
+            '実設定反映後、対象エージェントからBrainbase MCP resolve_entity/get_context/searchを呼び出せる。',
             '参照許可範囲と候補レビューを完了、または明示的に延期済み。'
         ]
     };

package/dist/projects.d.ts

@@ -1,4 +1,4 @@
-import type { DecisionRecord, GraphEntity, PersonalKgEntry, RelationshipRecord } from './types.js';
+import type { CanonicalEdge, CanonicalEntity, DecisionRecord, GraphEntity, PersonalKgEntry, RelationshipRecord } from './types.js';
 export type ProjectSourceArea = 'mail' | 'calendar' | 'drive' | 'tasks' | 'local' | 'other';
 export interface ProjectSourceReference {
     area: ProjectSourceArea;
@@ -38,6 +38,8 @@ export interface ProjectRegistrationPlan {
     stakeholders: ProjectStakeholder[];
     writes: {
         graphEntities: GraphEntity[];
+        canonicalEntities: CanonicalEntity[];
+        canonicalEdges: CanonicalEdge[];
         relationships: RelationshipRecord[];
         personalKg: PersonalKgEntry[];
         decisions: DecisionRecord[];