@unson/brainbase-mcp 0.6.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/foundation-store.d.ts

@@ -0,0 +1,132 @@
+import type { FoundationDefinition, FoundationAcl, FoundationRelationEndpoint, FoundationRelationReference, FoundationRevision, FoundationScope, FoundationType } from './ontology-foundation.js';
+import type { FoundationCatalogRecord, PersonalOs } from './types.js';
+import type { FoundationRef } from './foundation-catalog.js';
+export interface FoundationStoreContext {
+    /** Identity resolved by the caller's trusted auth boundary. */
+    principal: string;
+    /**
+     * Optional trusted subject scope.  The request body never supplies this
+     * value; organization adapters may inject it for the default policy.
+     */
+    scope?: FoundationScope;
+}
+export type FoundationStoreAction = 'create' | 'read' | 'update' | 'list' | 'link';
+/**
+ * Metadata returned for a non-foundation relation endpoint (for example a
+ * Story).  It deliberately contains no Story body or private projection.
+ * `acl` and `scope` are the current values used for authorization even when
+ * `revision` points at an older immutable revision.
+ */
+export interface FoundationEndpointResource {
+    id: string;
+    type: FoundationRelationEndpoint;
+    revision: string;
+    currentRevision: string;
+    acl: FoundationAcl;
+    scope: FoundationScope;
+}
+export type FoundationAuthorizationResource = FoundationDefinition | FoundationEndpointResource;
+export interface FoundationEndpointResolverRequest {
+    endpoint: {
+        id: string;
+        type: FoundationRelationEndpoint;
+        revision?: string;
+    };
+    context: FoundationStoreContext;
+    /** The current aggregate loaded while the canonical SSOT lock is held. */
+    current: PersonalOs;
+}
+/**
+ * Trusted adapter for endpoint types that are not stored by this foundation
+ * catalog.  A resolver is called only inside the canonical mutation lock and
+ * must return authorization metadata, never a private endpoint document.
+ */
+export interface FoundationEndpointResolver {
+    resolve(request: FoundationEndpointResolverRequest): FoundationEndpointResource | null | Promise<FoundationEndpointResource | null>;
+}
+/**
+ * Minimal metadata record used by the OSS standalone Story resolver.  This is
+ * an adapter input, not a second Story store: Story content and lifecycle stay
+ * owned by the consuming Story provider.
+ */
+export interface LocalStoryRevision {
+    id: string;
+    revision: string;
+    acl: FoundationAcl;
+    scope: FoundationScope;
+}
+export interface FoundationAuthorizationRequest {
+    action: FoundationStoreAction;
+    context: FoundationStoreContext;
+    reference?: FoundationRevision;
+    current?: FoundationDefinition;
+    next?: FoundationDefinition;
+    /**
+     * Foundation records resolved from relation endpoints while the canonical
+     * SSOT lock is held.  A link must never be authorized from an ID alone.
+     */
+    resources?: readonly FoundationAuthorizationResource[];
+    relation?: FoundationRelationReference;
+}
+export interface FoundationStorePolicy {
+    authorize(request: FoundationAuthorizationRequest): void | boolean | Promise<void | boolean>;
+}
+export interface FoundationUpdateInput {
+    reference: FoundationRevision;
+    next: FoundationDefinition;
+    /** Optional duplicate check for callers that carry an explicit CAS field. */
+    expectedRevision?: string;
+}
+export interface FoundationRevisionStore {
+    create(definition: FoundationDefinition, context: FoundationStoreContext): Promise<FoundationRef>;
+    read(reference: FoundationRevision, context: FoundationStoreContext): Promise<FoundationCatalogRecord | null>;
+    readLatest(type: FoundationType, id: string, context: FoundationStoreContext): Promise<FoundationCatalogRecord | null>;
+    update(input: FoundationUpdateInput, context: FoundationStoreContext): Promise<FoundationRef>;
+    list(type: FoundationType | undefined, context: FoundationStoreContext): Promise<FoundationCatalogRecord[]>;
+    addRelation(relation: FoundationRelationReference, context: FoundationStoreContext): Promise<void>;
+}
+export type FoundationStoreErrorCode = 'invalid_input' | 'not_found' | 'revision_conflict' | 'authorization_denied' | 'scope_violation' | 'unsupported_graph' | 'corrupt_catalog' | 'readback_mismatch';
+export declare class FoundationStoreError extends Error {
+    readonly code: FoundationStoreErrorCode;
+    readonly currentRevision?: string;
+    constructor(code: FoundationStoreErrorCode, message: string, options?: {
+        currentRevision?: string;
+    });
+}
+export interface FoundationRevisionStoreOptions {
+    dataDir: string;
+    policy?: FoundationStorePolicy;
+    /** Trusted resolver for Story and other external relation endpoints. */
+    endpointResolver?: FoundationEndpointResolver;
+}
+/**
+ * Canonical foundation persistence over the existing Graph SSOT aggregate.
+ * There is intentionally no separate objectives/world-model file or writer.
+ */
+export declare class GraphFoundationRevisionStore implements FoundationRevisionStore {
+    private readonly dataDir;
+    private readonly policy?;
+    private readonly endpointResolver?;
+    constructor(options: FoundationRevisionStoreOptions);
+    create(definition: FoundationDefinition, context: FoundationStoreContext): Promise<FoundationRef>;
+    read(reference: FoundationRevision, context: FoundationStoreContext): Promise<FoundationCatalogRecord | null>;
+    readLatest(type: FoundationType, id: string, context: FoundationStoreContext): Promise<FoundationCatalogRecord | null>;
+    update(input: FoundationUpdateInput, context: FoundationStoreContext): Promise<FoundationRef>;
+    list(type: FoundationType | undefined, context: FoundationStoreContext): Promise<FoundationCatalogRecord[]>;
+    addRelation(relation: FoundationRelationReference, context: FoundationStoreContext): Promise<void>;
+    private load;
+    private authorize;
+    private readback;
+}
+export declare function createFoundationRevisionStore(options: FoundationRevisionStoreOptions): FoundationRevisionStore;
+export declare const createFoundationStore: typeof createFoundationRevisionStore;
+/**
+ * Creates a concrete, in-memory Story endpoint adapter for OSS consumers.
+ * Only immutable revision/security metadata is supplied; no Story body is
+ * duplicated into the foundation catalog.  Current ACL and scope are taken
+ * from the greatest registered revision while the requested revision is only
+ * checked for existence and retained in the relation.
+ */
+export declare function createLocalStoryResolver(records: readonly LocalStoryRevision[]): FoundationEndpointResolver;
+/** Descriptive alias for consumers that use the generic endpoint terminology. */
+export declare const createStoryEndpointResolver: typeof createLocalStoryResolver;