@unson/brainbase-mcp 0.7.0 → 0.8.0

package/dist/foundation-public-provider.js

@@ -0,0 +1,192 @@
+import { z } from 'zod';
+import { createJudgmentProblemPhilosophyReferenceResolver } from './philosophy-revision-reader.js';
+import { judgmentFoundationContract } from './ontology-foundation.js';
+import { digestFoundationDefinition } from './foundation-catalog.js';
+import { createJudgmentProblemFoundationReferenceProvider, validateJudgmentProblemSnapshot, JudgmentProblemSnapshotError } from './judgment-problem-snapshot.js';
+export const FOUNDATION_PUBLIC_CONTRACT_VERSION = 'foundation-public.v1';
+const revision = z.string().regex(/^[1-9]\d*$/u);
+const digest = z.string().regex(/^sha256:[0-9a-f]{64}$/u).transform((value) => value);
+const readSchema = z.object({
+    type: z.enum(['objective', 'variable', 'model', 'constraint', 'philosophy']),
+    id: z.string().min(1), revision, digest: digest.optional()
+}).strict();
+const referenceSchema = z.object({
+    kind: z.enum(['objective', 'variable', 'model', 'constraint', 'philosophy']),
+    id: z.string().min(1), revision, digest,
+    scope: z.object({ type: z.enum(['personal', 'project', 'organization']), id: z.string().min(1) }).strict(),
+    valid_from: z.string().datetime({ offset: true }),
+    valid_to: z.string().datetime({ offset: true }).nullable().optional()
+}).strict();
+const problemSchema = z.object({ snapshot: z.unknown() }).strict();
+const validateSchema = z.object({
+    reference: referenceSchema,
+    phase: z.enum(['read', 'historical_read']).default('read')
+}).strict();
+/** The host owns canonical storage and authentication. No body can supply either. */
+export function createFoundationPublicProvider(options) {
+    const resolvePhilosophy = options.philosophyReader
+        ? createJudgmentProblemPhilosophyReferenceResolver({ reader: options.philosophyReader })
+        : undefined;
+    function assertContext(context) {
+        if (!context || typeof context.principal !== 'string' || !context.principal.trim()) {
+            throw new Error('foundation_trusted_context_required');
+        }
+    }
+    function referenceProvider(context) {
+        const provider = createJudgmentProblemFoundationReferenceProvider({
+            store: { read: (reference) => options.store.read(reference, context) },
+            resolveOther: (input) => input.reference.kind === 'philosophy'
+                ? resolvePhilosophy?.(input) ?? { status: 'unresolved', message: 'Philosophy reader is not connected' }
+                : options.resolveOther?.(input) ?? { status: 'unresolved', message: `No provider is registered for ${input.reference.kind}` }
+        });
+        return { resolve(input) {
+                if (context.scope && !context.scope.subjectIds.includes(input.reference.scope.id)) {
+                    return { status: 'unauthorized', message: 'Reference is outside the trusted scope' };
+                }
+                return provider.resolve(input);
+            } };
+    }
+    return {
+        describe() {
+            return {
+                contractVersion: FOUNDATION_PUBLIC_CONTRACT_VERSION,
+                foundation: judgmentFoundationContract,
+                connection: 'configured',
+                storage: 'canonical-provider',
+                philosophy: { kind: 'philosophy', canonicalSource: 'host-provider', connected: Boolean(options.philosophyReader), immutableRevisionRequired: true },
+                historicalRead: 'current-acl-and-exact-digest',
+                executionPermission: 'none'
+            };
+        },
+        async read(raw, context) {
+            assertContext(context);
+            const args = readSchema.parse(raw);
+            if (args.type === 'philosophy') {
+                if (!options.philosophyReader?.readCanonical)
+                    throw new Error('foundation_provider_unconfigured');
+                const result = await options.philosophyReader.readCanonical({ id: args.id, revision: args.revision, context });
+                if (result.status !== 'resolved') {
+                    throw new Error(result.status === 'unauthorized' ? 'authorization_denied' : result.status === 'missing' ? 'foundation_revision_missing' : 'foundation_digest_or_identity_mismatch');
+                }
+                const record = result.record;
+                if (record.id !== args.id || record.revision !== args.revision || (args.digest && args.digest !== record.digest)) {
+                    throw new Error('foundation_digest_or_identity_mismatch');
+                }
+                if (context.scope && !context.scope.subjectIds.includes(record.applicability.scope.id))
+                    throw new Error('scope_violation');
+                const resolved = await createJudgmentProblemPhilosophyReferenceResolver({ reader: { read: () => result } })({
+                    reference: { kind: 'philosophy', id: record.id, revision: record.revision, digest: record.digest,
+                        scope: record.applicability.scope, valid_from: record.applicability.validFrom,
+                        ...(record.applicability.validUntil ? { valid_to: record.applicability.validUntil } : {}) },
+                    phase: 'historical_read', context
+                });
+                if (resolved.status !== 'resolved')
+                    throw new Error(resolved.status === 'unauthorized' ? 'authorization_denied' : 'foundation_digest_or_identity_mismatch');
+                return record;
+            }
+            const record = await options.store.read({ type: args.type, id: args.id, revision: args.revision }, context);
+            if (!record)
+                throw new Error('foundation_revision_missing');
+            if (record.definition.id !== args.id || record.definition.type !== args.type || record.definition.revision !== args.revision
+                || digestFoundationDefinition(record.definition) !== record.digest || (args.digest && args.digest !== record.digest)) {
+                throw new Error('foundation_digest_or_identity_mismatch');
+            }
+            return record;
+        },
+        async validate(raw, context) {
+            assertContext(context);
+            const args = validateSchema.parse(raw);
+            return referenceProvider(context).resolve({ reference: args.reference, phase: args.phase, context });
+        },
+        async validateProblem(raw, context) {
+            assertContext(context);
+            const args = problemSchema.parse(raw);
+            const owner = args.snapshot?.owner_scope;
+            if (context.scope && owner && !context.scope.subjectIds.includes(owner.id)) {
+                throw new JudgmentProblemSnapshotError('unauthorized', 'Snapshot owner is outside the trusted scope');
+            }
+            await validateJudgmentProblemSnapshot({
+                snapshot: args.snapshot,
+                access: context,
+                referenceProvider: referenceProvider(context)
+            });
+            return { status: 'resolved', executionPermission: 'none' };
+        }
+    };
+}
+export const foundationPublicToolDefinitions = [
+    { name: 'foundation_describe', description: 'Describe the connected versioned judgment foundation contract.', inputSchema: { type: 'object', properties: {}, additionalProperties: false } },
+    { name: 'foundation_read', description: 'Read an exact canonical foundation revision under current access rights.', inputSchema: {
+            type: 'object', required: ['type', 'id', 'revision'], additionalProperties: false,
+            properties: { type: { type: 'string', enum: ['objective', 'variable', 'model', 'constraint', 'philosophy'] }, id: { type: 'string' }, revision: { type: 'string' }, digest: { type: 'string' } }
+        } },
+    { name: 'foundation_validate_reference', description: 'Validate an exact foundation or philosophy reference for judgment, including its dependencies.', inputSchema: {
+            type: 'object', required: ['reference'], additionalProperties: false,
+            properties: { reference: { type: 'object', required: ['kind', 'id', 'revision', 'digest', 'scope', 'valid_from'], additionalProperties: false,
+                    properties: { kind: { type: 'string', enum: ['objective', 'variable', 'model', 'constraint', 'philosophy'] }, id: { type: 'string' }, revision: { type: 'string' }, digest: { type: 'string' }, scope: { type: 'object', required: ['type', 'id'], additionalProperties: false, properties: { type: { type: 'string', enum: ['personal', 'project', 'organization'] }, id: { type: 'string' } } }, valid_from: { type: 'string' }, valid_to: { type: ['string', 'null'] } } }, phase: { type: 'string', enum: ['read', 'historical_read'] } }
+        } },
+    { name: 'foundation_validate_problem', description: 'Validate a complete judgment snapshot and canonical observation measurement conditions. Grants no execution permission.', inputSchema: { type: 'object', required: ['snapshot'], properties: { snapshot: { type: 'object' } }, additionalProperties: false } }
+];
+export async function callFoundationPublicTool(name, args, connection) {
+    if (!connection)
+        throw new Error('foundation_provider_unconfigured');
+    const context = await connection.resolveContext();
+    if (!context?.principal?.trim())
+        throw new Error('foundation_trusted_context_required');
+    if (name === 'foundation_describe') {
+        z.object({}).strict().parse(args);
+        return connection.provider.describe();
+    }
+    if (name === 'foundation_read')
+        return connection.provider.read(args, context);
+    if (name === 'foundation_validate_problem')
+        return connection.provider.validateProblem(args, context);
+    if (name === 'foundation_validate_reference')
+        return connection.provider.validate(args, context);
+    throw new Error('foundation_tool_unknown');
+}
+/** Mounted with createFoundationHttpRouter, whose host resolves auth and CSRF. */
+export function createFoundationPublicRoute(provider) {
+    const prefix = '/api/foundation';
+    const matches = (request) => {
+        const pathname = new URL(request.url).pathname;
+        return pathname === `${prefix}/contract` || pathname === `${prefix}/judgment-references/validate` || pathname === `${prefix}/judgment-problems/validate`
+            || /^\/api\/foundation\/definitions\/[^/]+\/[^/]+$/u.test(pathname);
+    };
+    const json = (status, value) => new Response(JSON.stringify(value), { status, headers: { 'content-type': 'application/json' } });
+    return {
+        name: 'foundation-public', methods: ['GET', 'POST'], paths: [`${prefix}/contract`, `${prefix}/definitions/:type/:id`, `${prefix}/judgment-references/validate`, `${prefix}/judgment-problems/validate`], matches,
+        async handle(request, { context }) {
+            try {
+                const url = new URL(request.url);
+                for (const key of url.searchParams.keys())
+                    if (!['scope_id', 'revision', 'digest'].includes(key))
+                        return json(400, { error: { code: 'invalid_query' } });
+                if (url.pathname === `${prefix}/contract` && request.method === 'GET')
+                    return json(200, provider.describe());
+                if ([`${prefix}/judgment-references/validate`, `${prefix}/judgment-problems/validate`].includes(url.pathname) && request.method === 'POST') {
+                    if (Number(request.headers.get('content-length')) > 65_536)
+                        return json(413, { error: { code: 'body_too_large' } });
+                    const body = await request.text();
+                    if (new TextEncoder().encode(body).length > 65_536)
+                        return json(413, { error: { code: 'body_too_large' } });
+                    const result = url.pathname.endsWith('/judgment-problems/validate')
+                        ? await provider.validateProblem(JSON.parse(body), context)
+                        : await provider.validate(JSON.parse(body), context);
+                    return json(result.status === 'resolved' ? 200 : result.status === 'unauthorized' ? 403 : 422, result);
+                }
+                const parts = /^\/api\/foundation\/definitions\/([^/]+)\/([^/]+)$/u.exec(url.pathname);
+                if (parts && request.method === 'GET')
+                    return json(200, await provider.read({ type: decodeURIComponent(parts[1]), id: decodeURIComponent(parts[2]), revision: url.searchParams.get('revision'), ...(url.searchParams.has('digest') ? { digest: url.searchParams.get('digest') } : {}) }, context));
+                return json(405, { error: { code: 'method_not_allowed' } });
+            }
+            catch (error) {
+                const rawCode = error instanceof Error && 'code' in error ? String(error.code) : error instanceof Error ? error.message : '';
+                const knownCodes = ['foundation_provider_unconfigured', 'authorization_denied', 'scope_violation', 'foundation_revision_missing', 'foundation_digest_or_identity_mismatch', 'foundation_trusted_context_required', 'corrupt_catalog', 'unauthorized', 'invalid_request', 'unresolved_constraint', 'integrity_mismatch', 'missing_reference', 'not_applicable'];
+                const code = knownCodes.includes(rawCode) ? rawCode : 'foundation_read_failed';
+                const status = code === 'foundation_provider_unconfigured' ? 503 : ['authorization_denied', 'scope_violation', 'unauthorized'].includes(code) ? 403 : code === 'foundation_revision_missing' ? 404 : code === 'invalid_request' || error instanceof z.ZodError || error instanceof SyntaxError || error instanceof URIError ? 400 : 422;
+                return json(status, { error: { code: status === 400 ? 'invalid_request' : code, ...(error instanceof JudgmentProblemSnapshotError && error.reference ? { reference: { kind: error.reference.kind, id: error.reference.id, revision: error.reference.revision } } : {}) } });
+            }
+        }
+    };
+}

package/dist/graph-corrections.d.ts

@@ -0,0 +1,157 @@
+import type { CanonicalEdge, CanonicalEntity, RelationshipRecord } from './types.js';
+/**
+ * Owner corrections for the canonical local Graph v2.
+ *
+ * Graph entities and edges are stored without revisions, so every correction
+ * carries the digest of the record it was based on, a one-sentence reason and
+ * leaves an append-only history line. The history line, the Graph change and
+ * the relationships.json projection are committed in one SSOT transaction.
+ */
+export declare const GRAPH_CORRECTION_SCHEMA: "brainbase-graph-correction.v1";
+/** Relative to the data directory. Committed as a sidecar of the canonical SSOT transaction. */
+export declare const GRAPH_CORRECTIONS_FILE = "evidence/graph-corrections.jsonl";
+export declare const GRAPH_CORRECTION_ENTITY_FIELDS: readonly ["name", "aliases", "summary", "validFrom", "validTo"];
+export declare const GRAPH_CORRECTION_PROJECT_FIELDS: readonly ["goal", "status"];
+export declare const GRAPH_CORRECTION_EDGE_FIELDS: readonly ["role", "context", "validTo"];
+export declare const GRAPH_CORRECTION_NEW_EDGE_RELATIONS: readonly ["participates_in", "accountable_for", "member_of"];
+/** MCP tools that read the same graph.json on every call and therefore see a saved correction next time. */
+export declare const GRAPH_CORRECTION_APPLIES_TO: readonly ["search", "get_context", "resolve_entity"];
+export type GraphCorrectionKind = 'update_entity' | 'update_edge' | 'create_edge';
+export type GraphNewEdgeRelation = typeof GRAPH_CORRECTION_NEW_EDGE_RELATIONS[number];
+export interface GraphEntityCorrectionChanges {
+    name?: string;
+    aliases?: string[];
+    summary?: string | null;
+    validFrom?: string | null;
+    validTo?: string | null;
+    /** Projects only. Stored as `metadata.goal`. */
+    goal?: string | null;
+    /** Projects only. Stored as `metadata.status`. */
+    status?: string | null;
+}
+export interface GraphEdgeCorrectionChanges {
+    role?: string | null;
+    context?: string | null;
+    /** Ending a relation is expressed with an end date; relations are never deleted. */
+    validTo?: string | null;
+}
+export interface GraphEdgeCreation {
+    fromId: string;
+    relation: GraphNewEdgeRelation;
+    toId: string;
+    role?: string;
+    context?: string;
+    validFrom?: string;
+}
+export type GraphCorrectionInput = {
+    kind: 'update_entity';
+    entityId: string;
+    expectedDigest: string;
+    reason: string;
+    changes: GraphEntityCorrectionChanges;
+} | {
+    kind: 'update_edge';
+    edgeId: string;
+    expectedDigest: string;
+    reason: string;
+    changes: GraphEdgeCorrectionChanges;
+} | {
+    kind: 'create_edge';
+    reason: string;
+    edge: GraphEdgeCreation;
+};
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export interface GraphProjectionChange {
+    edgeId: string;
+    relationshipId: string | null;
+    action: 'created' | 'updated' | 'removed' | 'shared_unchanged';
+    beforeDigest: string | null;
+    afterDigest: string | null;
+    /** The projection record as it was before this correction, so a removal stays recoverable. */
+    before: RelationshipRecord | null;
+}
+export interface GraphCorrectionRecord {
+    schema: typeof GRAPH_CORRECTION_SCHEMA;
+    id: string;
+    at: string;
+    kind: GraphCorrectionKind;
+    target: {
+        recordType: 'entity' | 'edge';
+        id: string;
+    };
+    reason: string;
+    changedFields: string[];
+    changes: Record<string, {
+        before: JsonValue;
+        after: JsonValue;
+    }>;
+    beforeDigest: string | null;
+    afterDigest: string;
+    projections: GraphProjectionChange[];
+}
+export interface GraphCorrectionResult {
+    status: 'saved';
+    correction: GraphCorrectionRecord;
+    recordType: 'entity' | 'edge';
+    /** The record as read back from graph.json after the commit. */
+    record: CanonicalEntity | CanonicalEdge;
+    digest: string;
+    readback: {
+        verified: true;
+        digest: string;
+        historyRecorded: true;
+    };
+    appliesTo: readonly string[];
+}
+export type GraphCorrectionErrorKind = 'invalid' | 'not_found' | 'conflict' | 'migration_required' | 'readback_mismatch';
+export declare class GraphCorrectionError extends Error {
+    readonly kind: GraphCorrectionErrorKind;
+    readonly code: string;
+    readonly current?: {
+        recordType: "entity" | "edge";
+        record: CanonicalEntity | CanonicalEdge;
+        digest: string;
+    } | undefined;
+    readonly name = "GraphCorrectionError";
+    constructor(kind: GraphCorrectionErrorKind, code: string, message: string, current?: {
+        recordType: "entity" | "edge";
+        record: CanonicalEntity | CanonicalEdge;
+        digest: string;
+    } | undefined);
+}
+/** SHA-256 over canonical JSON (recursively sorted keys) of one stored record. */
+export declare function graphRecordDigest(record: CanonicalEntity | CanonicalEdge | RelationshipRecord): string;
+/**
+ * Validates an untrusted correction request. Only the fields listed in the
+ * correction contract are accepted; ids, types, relation types, provenance and
+ * deletions are rejected with a specific code.
+ */
+export declare function parseGraphCorrectionInput(value: unknown): GraphCorrectionInput;
+/**
+ * Applies one owner correction to the canonical Graph v2 in `dataDir`.
+ *
+ * The Graph write, the relationships.json projection and the history line in
+ * `evidence/graph-corrections.jsonl` are committed together through
+ * `mutatePersonalOsWithSidecar`, so a crash never leaves a Graph change without
+ * its history line (or the reverse). After the commit the record is read back
+ * and its digest must equal the digest computed before saving.
+ */
+export declare function applyGraphCorrection(dataDir: string, input: unknown, options?: {
+    now?: Date;
+}): Promise<GraphCorrectionResult>;
+export interface GraphCorrectionHistoryIssue {
+    file: typeof GRAPH_CORRECTIONS_FILE;
+    line?: number;
+    reason: string;
+}
+/**
+ * Reads the correction history in append order. A missing file means no
+ * correction has been saved; an unreadable line is reported as an issue and
+ * never silently dropped.
+ */
+export declare function readGraphCorrectionHistory(dataDir: string): Promise<{
+    records: GraphCorrectionRecord[];
+    issues: GraphCorrectionHistoryIssue[];
+}>;