@unson/brainbase-mcp 0.5.0 → 0.7.0

package/dist/streamable-http.js

@@ -0,0 +1,288 @@
+import { randomUUID } from 'node:crypto';
+import { createServer as createHttpServer } from 'node:http';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+const DEFAULT_BODY_LIMIT_BYTES = 1024 * 1024;
+const DEFAULT_MCP_PATH = '/mcp';
+const DEFAULT_HEALTH_PATH = '/health';
+class BodyLimitError extends Error {
+    constructor() {
+        super('Request body exceeds the configured limit');
+        this.name = 'BodyLimitError';
+    }
+}
+class InvalidJsonError extends Error {
+    constructor() {
+        super('Parse error: Invalid JSON');
+        this.name = 'InvalidJsonError';
+    }
+}
+function jsonRpcError(code, message) {
+    return {
+        jsonrpc: '2.0',
+        error: { code, message },
+        id: null
+    };
+}
+function writeJson(response, statusCode, body, headers = {}) {
+    if (response.headersSent)
+        return;
+    response.statusCode = statusCode;
+    response.setHeader('Content-Type', 'application/json');
+    for (const [name, value] of Object.entries(headers))
+        response.setHeader(name, value);
+    response.end(JSON.stringify(body));
+}
+function requestPath(request) {
+    try {
+        return new URL(request.url ?? '/', 'http://localhost').pathname;
+    }
+    catch {
+        return '/';
+    }
+}
+function headerValue(request, name) {
+    const value = request.headers[name.toLowerCase()];
+    return Array.isArray(value) ? value[0] : value;
+}
+async function readJsonBody(request, limitBytes) {
+    const contentLengthHeader = headerValue(request, 'content-length');
+    if (contentLengthHeader !== undefined) {
+        const contentLength = Number(contentLengthHeader);
+        if (Number.isFinite(contentLength) && contentLength > limitBytes) {
+            request.resume();
+            throw new BodyLimitError();
+        }
+    }
+    const chunks = [];
+    let totalBytes = 0;
+    await new Promise((resolve, reject) => {
+        let settled = false;
+        const cleanup = () => {
+            request.removeListener('data', onData);
+            request.removeListener('end', onEnd);
+            request.removeListener('error', onError);
+            request.removeListener('aborted', onAborted);
+        };
+        const finish = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            if (error)
+                reject(error);
+            else
+                resolve();
+        };
+        const onData = (chunk) => {
+            const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            totalBytes += buffer.byteLength;
+            if (totalBytes > limitBytes) {
+                request.resume();
+                finish(new BodyLimitError());
+                return;
+            }
+            chunks.push(buffer);
+        };
+        const onEnd = () => finish();
+        const onError = () => finish(new Error('Request body could not be read'));
+        const onAborted = () => finish(new Error('Request was aborted'));
+        request.on('data', onData);
+        request.once('end', onEnd);
+        request.once('error', onError);
+        request.once('aborted', onAborted);
+    });
+    if (chunks.length === 0)
+        throw new InvalidJsonError();
+    try {
+        return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+    }
+    catch {
+        throw new InvalidJsonError();
+    }
+}
+function assignAuth(request, auth) {
+    const authenticatedRequest = request;
+    if (auth !== undefined)
+        authenticatedRequest.auth = auth;
+    return authenticatedRequest;
+}
+export function createStreamableHttpHandler(dependencies) {
+    const bodyLimitBytes = dependencies.bodyLimitBytes ?? DEFAULT_BODY_LIMIT_BYTES;
+    const mcpPath = dependencies.mcpPath ?? DEFAULT_MCP_PATH;
+    const healthPath = dependencies.healthPath ?? DEFAULT_HEALTH_PATH;
+    if (!Number.isInteger(bodyLimitBytes) || bodyLimitBytes <= 0) {
+        throw new Error('bodyLimitBytes must be a positive integer');
+    }
+    const sessions = new Map();
+    const closeServer = async (session) => {
+        if (session.serverClosePromise)
+            return session.serverClosePromise;
+        session.serverCloseStarted = true;
+        session.serverClosePromise = session.server.close();
+        await session.serverClosePromise;
+    };
+    const disposeSession = async (session) => {
+        if (session.id)
+            sessions.delete(session.id);
+        if (session.closed && session.serverCloseStarted) {
+            await session.serverClosePromise;
+            return;
+        }
+        session.closed = true;
+        try {
+            await session.transport.close();
+        }
+        finally {
+            await closeServer(session);
+        }
+    };
+    const createSession = async (scope) => {
+        const server = await dependencies.createServer(scope);
+        let session;
+        const transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: randomUUID,
+            enableJsonResponse: true,
+            onsessioninitialized: (id) => {
+                session.id = id;
+                sessions.set(id, session);
+            },
+            onsessionclosed: (id) => {
+                sessions.delete(id);
+                session.closed = true;
+            }
+        });
+        session = {
+            server,
+            transport,
+            closed: false,
+            serverCloseStarted: false
+        };
+        transport.onclose = () => {
+            session.closed = true;
+            if (session.id)
+                sessions.delete(session.id);
+            void closeServer(session).catch(() => undefined);
+        };
+        await server.connect(transport);
+        return session;
+    };
+    const resolveScope = async (request, auth, sessionId, requestId) => {
+        const base = {
+            requestId,
+            method: request.method ?? 'GET',
+            path: requestPath(request),
+            ...(auth === undefined ? {} : { auth }),
+            ...(sessionId === undefined ? {} : { sessionId })
+        };
+        const custom = await dependencies.requestScope?.({ request, requestId, auth, sessionId });
+        return custom ? { ...base, ...custom } : base;
+    };
+    const handle = async (request, response) => {
+        const path = requestPath(request);
+        const requestId = randomUUID();
+        if (path === healthPath && request.method === 'GET') {
+            try {
+                const result = await dependencies.health?.({ request, requestId });
+                writeJson(response, 200, result ?? { status: 'ok' });
+            }
+            catch {
+                writeJson(response, 503, { status: 'unavailable' });
+            }
+            return;
+        }
+        if (path !== mcpPath) {
+            writeJson(response, 404, { error: 'Not Found' });
+            return;
+        }
+        if (request.method === 'GET') {
+            writeJson(response, 405, jsonRpcError(-32000, 'GET is not supported'), { Allow: 'POST, DELETE' });
+            return;
+        }
+        if (request.method !== 'POST' && request.method !== 'DELETE') {
+            writeJson(response, 405, jsonRpcError(-32000, 'Method not allowed'), { Allow: 'POST, DELETE' });
+            return;
+        }
+        let auth;
+        if (dependencies.authenticate) {
+            try {
+                const authenticated = await dependencies.authenticate(request);
+                if (authenticated === null) {
+                    writeJson(response, 401, jsonRpcError(-32000, 'Unauthorized'), { 'WWW-Authenticate': 'Bearer' });
+                    return;
+                }
+                auth = authenticated;
+            }
+            catch {
+                writeJson(response, 401, jsonRpcError(-32000, 'Unauthorized'), { 'WWW-Authenticate': 'Bearer' });
+                return;
+            }
+        }
+        const sessionId = headerValue(request, 'mcp-session-id');
+        let session = sessionId ? sessions.get(sessionId) : undefined;
+        if (sessionId && !session) {
+            writeJson(response, 404, jsonRpcError(-32001, 'Session not found'));
+            return;
+        }
+        try {
+            const body = request.method === 'POST' ? await readJsonBody(request, bodyLimitBytes) : undefined;
+            const scope = await resolveScope(request, auth, sessionId, requestId);
+            if (!session)
+                session = await createSession(scope);
+            let aborted = false;
+            const onClose = () => {
+                if (!response.writableFinished) {
+                    aborted = true;
+                    if (session)
+                        void disposeSession(session).catch(() => undefined);
+                }
+            };
+            response.once('close', onClose);
+            try {
+                await session.transport.handleRequest(assignAuth(request, auth), response, body);
+            }
+            finally {
+                response.removeListener('close', onClose);
+            }
+            // An uninitialized, stateless request creates no session and must not leak
+            // its server. Initialized sessions remain available for list/call/delete.
+            if (!session.transport.sessionId && !sessionId && !aborted)
+                await disposeSession(session);
+        }
+        catch (error) {
+            if (response.headersSent) {
+                if (!response.writableEnded)
+                    response.destroy();
+                return;
+            }
+            if (error instanceof BodyLimitError) {
+                writeJson(response, 413, jsonRpcError(-32013, error.message));
+                return;
+            }
+            if (error instanceof InvalidJsonError) {
+                writeJson(response, 400, jsonRpcError(-32700, error.message));
+                return;
+            }
+            writeJson(response, 500, jsonRpcError(-32603, 'Internal server error'));
+        }
+    };
+    return {
+        handle,
+        close: async () => {
+            await Promise.all([...sessions.values()].map((session) => disposeSession(session)));
+            sessions.clear();
+        },
+        get activeSessionCount() {
+            return sessions.size;
+        }
+    };
+}
+export function createStreamableHttpServer(dependencies) {
+    const handler = createStreamableHttpHandler(dependencies);
+    const server = createHttpServer((request, response) => {
+        void handler.handle(request, response);
+    });
+    server.once('close', () => {
+        void handler.close().catch(() => undefined);
+    });
+    return server;
+}

package/dist/types.d.ts

@@ -1,3 +1,4 @@
+import type { FoundationDefinition, FoundationRelationReference, FoundationRevision } from './ontology-foundation.js';
 export type EntityKind = 'person' | 'org' | 'project' | 'relationship' | 'decision';
 export type CanonicalEntityKind = 'person' | 'org' | 'project' | 'decision';
 export type CoreRelation = 'member_of' | 'participates_in' | 'accountable_for' | 'owned_by' | 'governs' | 'supersedes';
@@ -43,6 +44,24 @@ export interface CanonicalEdge {
         evidenceHash?: string;
     };
 }
+/**
+ * Versioned definitions that extend the historical Graph v2 contract.
+ *
+ * This is deliberately an extension of the canonical aggregate rather than a
+ * second objectives/world-model file.  The old Graph entities and edges keep
+ * their historical interpretation; foundation records are validated by their
+ * own shared ontology contract.
+ */
+export interface FoundationCatalogRecord {
+    definition: FoundationDefinition;
+    digest: string;
+}
+export interface FoundationCatalog {
+    version: 1;
+    records: FoundationCatalogRecord[];
+    latest: Record<string, FoundationRevision>;
+    relations: FoundationRelationReference[];
+}
 export interface GraphFileV2 {
     version: 2;
     ontology: {
@@ -57,6 +76,7 @@ export interface GraphFileV2 {
     };
     entities: CanonicalEntity[];
     edges: CanonicalEdge[];
+    foundation?: FoundationCatalog;
 }
 export type GraphFile = GraphFileV1 | GraphFileV2;
 export type CanonicalGraphFile = GraphFile;

package/dist/world-model.d.ts

@@ -0,0 +1,181 @@
+import { type FoundationDefinition, type FoundationAcl, type FoundationAdoptionState, type FoundationEpistemicState, type FoundationPeriod, type FoundationProvenance, type FoundationRevision, type FoundationUse, type FoundationValidationResult, type DecisionRevision, type ModelDefinition, type VariableDefinition } from './ontology-foundation.js';
+/**
+ * The world-model helpers are deliberately independent of storage.  Definitions
+ * belong to the shared foundation catalog; observations and adoption records are
+ * values that reference an exact definition revision. A caller can therefore
+ * pass these records through the canonical SSOT transaction without introducing
+ * a second lock or definition authority.
+ */
+export declare const WORLD_MODEL_CONTRACT_VERSION: "0.1.0";
+export declare const WORLD_MODEL_RECORD_CATALOG_VERSION: 1;
+/** Evidence records are sidecar data committed with the canonical aggregate. */
+export declare const WORLD_MODEL_EVIDENCE_SIDECAR: "evidence/world-model.json";
+export type WorldModelScalar = string | number | boolean;
+export type WorldModelValue = WorldModelScalar | readonly WorldModelValue[] | {
+    readonly [key: string]: WorldModelValue;
+};
+export interface WorldModelObservationInput {
+    id: string;
+    variableRef: FoundationRevision;
+    subjectId: string;
+    value: WorldModelValue;
+    /** When the observed event happened. */
+    occurredAt: string;
+    /** The interval for which the value is valid, which may differ from occurredAt. */
+    period: FoundationPeriod;
+    /** When Brainbase recorded the observation. */
+    recordedAt: string;
+    sourceRef: FoundationProvenance;
+    /** A correction creates a new observation and points at the old one. */
+    supersedes?: string;
+}
+export interface WorldModelObservation extends WorldModelObservationInput {
+    readonly id: string;
+    readonly variableRef: FoundationRevision;
+    readonly subjectId: string;
+    readonly value: WorldModelValue;
+    readonly occurredAt: string;
+    readonly period: FoundationPeriod;
+    readonly recordedAt: string;
+    readonly sourceRef: FoundationProvenance;
+    readonly supersedes?: string;
+}
+export type WorldModelValidationIssueCode = 'MISSING_FIELD' | 'INVALID_FIELD' | 'INVALID_TIMESTAMP' | 'INVALID_PERIOD' | 'INVALID_VARIABLE_REFERENCE' | 'VARIABLE_VALUE_KIND_MISMATCH' | 'OBSERVATION_SCOPE_MISMATCH' | 'OBSERVATION_PERIOD_MISMATCH' | 'RECORDED_BEFORE_OCCURRED' | 'INVALID_CORRECTION_REFERENCE' | 'MISSING_SOURCE' | 'MODEL_CONTRACT_INVALID';
+export interface WorldModelValidationIssue {
+    readonly code: WorldModelValidationIssueCode;
+    readonly path: string;
+    readonly message: string;
+}
+export interface WorldModelValidationResult {
+    readonly valid: boolean;
+    readonly status: 'valid' | 'invalid';
+    readonly issues: readonly WorldModelValidationIssue[];
+}
+/**
+ * A candidate snapshot is intentionally not a FoundationDefinition.  It
+ * captures the candidate-store state at the moment a model is proposed so that
+ * adopting a model never overwrites the original hypothesis or ACL.
+ */
+export interface CandidateModelSnapshot {
+    readonly candidateId: string;
+    readonly hypothesis: string;
+    readonly evidenceIds: readonly string[];
+    readonly acl: FoundationAcl;
+    readonly epistemicState: Extract<FoundationEpistemicState, 'unverified' | 'hypothesis'>;
+}
+export interface ModelAdoptionInput {
+    readonly adoptionId: string;
+    readonly modelRef: FoundationRevision;
+    readonly candidate: CandidateModelSnapshot;
+    readonly adoptionState: Extract<FoundationAdoptionState, 'proposed' | 'approved'>;
+    readonly authorizedUse: FoundationUse;
+    readonly adoptedAt: string;
+    readonly approvalRef?: DecisionRevision;
+}
+export interface ModelAdoptionRecord extends ModelAdoptionInput {
+    readonly modelRef: FoundationRevision;
+    readonly candidate: CandidateModelSnapshot;
+    readonly adoptionState: Extract<FoundationAdoptionState, 'proposed' | 'approved'>;
+    readonly authorizedUse: FoundationUse;
+    readonly adoptedAt: string;
+    readonly approvalRef?: DecisionRevision;
+}
+/**
+ * This is an evidence-sidecar catalog, not part of the canonical Graph
+ * aggregate. Variable and Model definitions continue to be resolved by the
+ * foundation catalog, while this catalog holds immutable observations and
+ * candidate adoption references that point back to exact definition revisions.
+ */
+export interface WorldModelRecordCatalog {
+    readonly version: typeof WORLD_MODEL_RECORD_CATALOG_VERSION;
+    readonly observations: readonly WorldModelObservation[];
+    readonly adoptions: readonly ModelAdoptionRecord[];
+}
+export interface WorldModelStoreContext {
+    /** Identity resolved by the trusted auth boundary. */
+    readonly principal: string;
+}
+export interface WorldModelFoundationRecord {
+    readonly definition: FoundationDefinition;
+    readonly digest: string;
+}
+/**
+ * Structural contract implemented by the shared FoundationRevisionStore. It
+ * is local to this module so world-model can depend on the small public store
+ * surface without introducing a second definition catalog. Transactional
+ * foundation resolution is implemented below from the aggregate already held
+ * by mutatePersonalOsWithSidecar; the normal read method must not be
+ * re-entered while that lock is held.
+ */
+export interface WorldModelFoundationStore {
+    create(definition: FoundationDefinition, context: WorldModelStoreContext): Promise<FoundationRevision & {
+        readonly digest: string;
+    }>;
+    read(reference: FoundationRevision, context: WorldModelStoreContext): Promise<WorldModelFoundationRecord | null>;
+}
+export interface WorldModelObservationQuery {
+    readonly variableRef?: FoundationRevision;
+    readonly subjectId?: string;
+    readonly supersedes?: string;
+}
+export type ModelAdoptionStoreInput = Omit<ModelAdoptionInput, 'candidate' | 'modelRef'>;
+export type WorldModelStoreErrorCode = 'invalid_input' | 'not_found' | 'revision_conflict' | 'authorization_denied' | 'unsupported_graph' | 'corrupt_record' | 'readback_mismatch';
+export declare class WorldModelStoreError extends Error {
+    readonly code: WorldModelStoreErrorCode;
+    constructor(code: WorldModelStoreErrorCode, message: string);
+}
+export interface WorldModelRecordStore {
+    createVariable(variable: VariableDefinition, context: WorldModelStoreContext): Promise<FoundationRevision & {
+        readonly digest: string;
+    }>;
+    createModel(model: ModelDefinition, context: WorldModelStoreContext): Promise<FoundationRevision & {
+        readonly digest: string;
+    }>;
+    readModel(reference: FoundationRevision, context: WorldModelStoreContext): Promise<ModelDefinition | null>;
+    saveObservation(input: WorldModelObservationInput, context: WorldModelStoreContext): Promise<WorldModelObservation>;
+    readObservation(id: string, context: WorldModelStoreContext): Promise<WorldModelObservation | null>;
+    listObservations(query: WorldModelObservationQuery | undefined, context: WorldModelStoreContext): Promise<readonly WorldModelObservation[]>;
+    saveModelAdoption(candidate: CandidateModelSnapshot, modelRef: FoundationRevision, adoption: ModelAdoptionStoreInput, context: WorldModelStoreContext): Promise<ModelAdoptionRecord>;
+    readModelAdoption(adoptionId: string, context: WorldModelStoreContext): Promise<ModelAdoptionRecord | null>;
+    listModelAdoptions(context: WorldModelStoreContext): Promise<readonly ModelAdoptionRecord[]>;
+}
+export declare class WorldModelValidationError extends Error {
+    readonly issues: readonly WorldModelValidationIssue[];
+    constructor(issues: readonly WorldModelValidationIssue[]);
+}
+/**
+ * Validates and clones an observation before it crosses a storage boundary.
+ * The returned value is deeply frozen, while the input remains untouched.
+ */
+export declare function normalizeWorldModelObservation(input: WorldModelObservationInput): WorldModelObservation;
+/**
+ * Checks whether an already normalized observation is compatible with the
+ * exact Variable definition it references.  This does not infer a value or
+ * upgrade an observation from inferred to observed.
+ */
+export declare function validateWorldModelObservation(observation: WorldModelObservation, variable: VariableDefinition): WorldModelValidationResult;
+/**
+ * Delegates Model validation to the shared ontology contract.  The wrapper
+ * keeps world-model callers from importing ontology internals while retaining
+ * the contract's distinction between draft, judgment, evaluation, and
+ * execution use.
+ */
+export declare function validateWorldModelModel(model: ModelDefinition, use?: FoundationUse): FoundationValidationResult;
+/**
+ * Creates a durable adoption record without mutating the candidate or Model.
+ * A candidate may only produce an unverified/hypothesis Model record; adopting
+ * it cannot silently turn it into a verified claim.
+ */
+export declare function retainCandidateModel(candidate: CandidateModelSnapshot, model: ModelDefinition, adoption: Omit<ModelAdoptionInput, 'candidate' | 'modelRef'> & {
+    modelRef?: FoundationRevision;
+}): ModelAdoptionRecord;
+/**
+ * Creates a world-model record store over the existing canonical aggregate.
+ * Foundation definitions are delegated to the shared revision store. The
+ * observation/adoption evidence catalog is committed as a sidecar in the same
+ * SSOT transaction, so the canonical Graph remains definition-only.
+ */
+export declare function createWorldModelStore(options: {
+    dataDir: string;
+    foundationStore: WorldModelFoundationStore;
+}): WorldModelRecordStore;