@unson/brainbase-mcp 0.2.4 → 0.3.1

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`;

package/dist/templates.d.ts

@@ -1,4 +1,112 @@
-import type { GraphFile, RelationshipsFile } from './types.js';
-export declare const emptyGraph: GraphFile;
+import type { GraphFileV2, RelationshipsFile } from './types.js';
+export declare const canonicalGraphOntologyRelease: {
+    manifest: {
+        id: "brainbase-personal-os";
+        version: "2.0.0";
+        ontology: {
+            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.";
+                    }];
+                };
+            };
+        };
+        relationRegistry: Readonly<Record<import("./types.js").CoreRelation, Readonly<import("./relation-registry.js").CanonicalRelationDefinition>>>;
+    };
+    binding: {
+        id: "brainbase-personal-os";
+        version: "2.0.0";
+        releaseDigest: string;
+    };
+};
+export declare const emptyGraph: GraphFileV2;
 export declare const emptyRelationships: RelationshipsFile;
 export declare const schemaTemplates: Record<string, unknown>;

package/dist/templates.js

@@ -1,21 +1,61 @@
+import { createHash } from 'node:crypto';
+import { portableOntology } from './ontology.js';
+import { canonicalRelationRegistry } from './relation-registry.js';
+const ontologyReleaseManifest = deepFreeze({
+    id: 'brainbase-personal-os',
+    version: portableOntology.version,
+    ontology: portableOntology,
+    relationRegistry: canonicalRelationRegistry
+});
+const ontologyReleaseDigest = `sha256:${createHash('sha256')
+    .update(JSON.stringify(ontologyReleaseManifest))
+    .digest('hex')}`;
+export const canonicalGraphOntologyRelease = deepFreeze({
+    manifest: ontologyReleaseManifest,
+    binding: {
+        id: ontologyReleaseManifest.id,
+        version: ontologyReleaseManifest.version,
+        releaseDigest: ontologyReleaseDigest
+    }
+});
 export const emptyGraph = {
-    version: 1,
+    version: 2,
+    ontology: canonicalGraphOntologyRelease.binding,
     owner: {},
-    entities: []
+    entities: [],
+    edges: []
 };
 export const emptyRelationships = {
     version: 1,
     relationships: []
 };
+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;
+}
 export const schemaTemplates = {
     'graph.schema.json': {
         type: 'object',
-        required: ['version', 'entities'],
+        required: ['version', 'ontology', 'entities', 'edges'],
         properties: {
-            version: { const: 1 },
+            version: { const: 2 },
+            ontology: {
+                type: 'object',
+                required: ['id', 'version', 'releaseDigest'],
+                properties: {
+                    id: { const: 'brainbase-personal-os' },
+                    version: { type: 'string', minLength: 1 },
+                    releaseDigest: { type: 'string', minLength: 1 }
+                }
+            },
             owner: {
                 type: 'object',
                 properties: {
+                    id: { type: 'string' },
                     name: { type: 'string' },
                     summary: { type: 'string' }
                 }
@@ -27,13 +67,42 @@ export const schemaTemplates = {
                     required: ['id', 'type', 'name'],
                     properties: {
                         id: { type: 'string', minLength: 1 },
-                        type: { enum: ['person', 'org', 'project', 'relationship'] },
+                        type: { enum: ['person', 'org', 'project', 'decision'] },
                         name: { type: 'string', minLength: 1 },
+                        aliases: { type: 'array', items: { type: 'string', minLength: 1 } },
                         summary: { type: 'string' },
                         tags: { type: 'array', items: { type: 'string' } },
                         metadata: { type: 'object' }
                     }
                 }
+            },
+            edges: {
+                type: 'array',
+                items: {
+                    type: 'object',
+                    required: ['id', 'fromId', 'relation', 'toId'],
+                    properties: {
+                        id: { type: 'string', minLength: 1 },
+                        fromId: { type: 'string', minLength: 1 },
+                        relation: {
+                            enum: ['member_of', 'participates_in', 'accountable_for', 'owned_by', 'governs', 'supersedes']
+                        },
+                        toId: { type: 'string', minLength: 1 },
+                        role: { type: 'string' },
+                        context: { type: 'string' },
+                        validFrom: { type: 'string', format: 'date-time' },
+                        validTo: { type: 'string', format: 'date-time' },
+                        provenance: {
+                            type: 'object',
+                            required: ['sourceKind'],
+                            properties: {
+                                sourceKind: { enum: ['user_approved', 'migration', 'import', 'onboarding'] },
+                                sourceId: { type: 'string' },
+                                evidenceHash: { type: 'string' }
+                            }
+                        }
+                    }
+                }
             }
         }
     },

package/dist/tools.d.ts

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