@unson/brainbase-mcp 0.6.0 → 0.8.0

package/dist/foundation-authenticated-tools.js

@@ -0,0 +1,347 @@
+import { randomUUID } from 'node:crypto';
+import { foundationPublicToolDefinitions } from './foundation-public-provider.js';
+import { philosophyRevisionDigest, } from './philosophy-revision-reader.js';
+const FOUNDATION_READ_TYPES = new Set(['objective', 'variable', 'model', 'constraint', 'philosophy']);
+const FOUNDATION_TOOL_NAMES = new Set([
+    'foundation_describe',
+    'foundation_read',
+    'foundation_validate_reference',
+    'foundation_validate_problem',
+]);
+const REVISION_PATTERN = /^[1-9]\d*$/u;
+const DIGEST_PATTERN = /^sha256:[0-9a-f]{64}$/u;
+const MAX_SCOPE_ID_LENGTH = 256;
+/**
+ * The public provider owns the contract and schemas.  The Host adds the
+ * authenticated Graph scope to every public tool because a provider cannot
+ * select a tenant on behalf of the caller.
+ */
+function withScopeSchema(definition) {
+    const inputSchema = definition.inputSchema;
+    const properties = inputSchema.properties && typeof inputSchema.properties === 'object'
+        ? inputSchema.properties
+        : {};
+    const required = Array.isArray(inputSchema.required)
+        ? inputSchema.required.filter((value) => typeof value === 'string')
+        : [];
+    return {
+        ...definition,
+        inputSchema: {
+            ...inputSchema,
+            properties: {
+                ...properties,
+                scope_id: {
+                    type: 'string',
+                    minLength: 1,
+                    maxLength: MAX_SCOPE_ID_LENGTH,
+                    description: 'Authenticated project scope used for this read or validation.',
+                },
+            },
+            required: [...new Set([...required, 'scope_id'])],
+            additionalProperties: inputSchema.additionalProperties ?? false,
+        },
+    };
+}
+export const foundationPublicTools = foundationPublicToolDefinitions.map(withScopeSchema);
+export function isFoundationPublicToolName(name) {
+    return FOUNDATION_TOOL_NAMES.has(name);
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+/**
+ * Scope IDs are copied into x-brainbase-projects.  Reject delimiters and
+ * control characters before authentication so a caller cannot turn one
+ * selected project into an arbitrary project list.
+ */
+function readScopeId(args) {
+    if (typeof args.scope_id !== 'string')
+        return null;
+    const scopeId = args.scope_id.trim();
+    if (!scopeId || scopeId.length > MAX_SCOPE_ID_LENGTH)
+        return null;
+    if (/[\u0000-\u001f\u007f,]/u.test(scopeId))
+        return null;
+    return scopeId;
+}
+function invalidInput(message, dependencies) {
+    return dependencies.auth.toolError('error', 'foundation_request_invalid', message, []);
+}
+function rejectUnexpectedKeys(args, allowed, dependencies) {
+    const allowedKeys = new Set(allowed);
+    const unexpected = Object.keys(args).find((key) => !allowedKeys.has(key));
+    return unexpected ? invalidInput(`unexpected Foundation argument: ${unexpected}`, dependencies) : null;
+}
+function readRequiredString(args, key) {
+    return isNonEmptyString(args[key]) ? String(args[key]).trim() : null;
+}
+function validateReadArgs(args, dependencies) {
+    const type = readRequiredString(args, 'type');
+    const id = readRequiredString(args, 'id');
+    const revision = readRequiredString(args, 'revision');
+    if (!type || !FOUNDATION_READ_TYPES.has(type))
+        return invalidInput('foundation type is invalid', dependencies);
+    if (!id)
+        return invalidInput('foundation id is required', dependencies);
+    if (!revision || !REVISION_PATTERN.test(revision))
+        return invalidInput('foundation revision is invalid', dependencies);
+    if (args.digest !== undefined && (!isNonEmptyString(args.digest) || !DIGEST_PATTERN.test(String(args.digest)))) {
+        return invalidInput('foundation digest is invalid', dependencies);
+    }
+    return null;
+}
+function validateReferenceArgs(args, dependencies) {
+    if (!isRecord(args.reference))
+        return invalidInput('foundation reference is required', dependencies);
+    const reference = args.reference;
+    if (!isNonEmptyString(reference.kind) || !['objective', 'variable', 'model', 'constraint', 'philosophy'].includes(reference.kind)) {
+        return invalidInput('foundation reference kind is invalid', dependencies);
+    }
+    if (!isNonEmptyString(reference.id) || !isNonEmptyString(reference.revision) || !REVISION_PATTERN.test(String(reference.revision))) {
+        return invalidInput('foundation reference identity is invalid', dependencies);
+    }
+    if (!isNonEmptyString(reference.digest) || !DIGEST_PATTERN.test(String(reference.digest))) {
+        return invalidInput('foundation reference digest is invalid', dependencies);
+    }
+    if (!isRecord(reference.scope) || !isNonEmptyString(reference.scope.type) || !isNonEmptyString(reference.scope.id)) {
+        return invalidInput('foundation reference scope is invalid', dependencies);
+    }
+    if (!['personal', 'project', 'organization'].includes(reference.scope.type)) {
+        return invalidInput('foundation reference scope type is invalid', dependencies);
+    }
+    if (!isNonEmptyString(reference.valid_from))
+        return invalidInput('foundation reference valid_from is required', dependencies);
+    if (args.phase !== undefined && args.phase !== 'read' && args.phase !== 'historical_read') {
+        return invalidInput('foundation validation phase is invalid', dependencies);
+    }
+    return null;
+}
+function validateProblemArgs(args, dependencies) {
+    if (!isRecord(args.snapshot))
+        return invalidInput('foundation snapshot is required', dependencies);
+    return null;
+}
+function selectedContext(context, scopeId) {
+    // authenticateProject proves membership against both the token and the
+    // configured allow-list.  Restrict the outbound header to the selected
+    // project instead of forwarding every project in the token.
+    return { token: context.token, scope: [scopeId] };
+}
+function requestFor(name, args, scopeId) {
+    const query = new URLSearchParams({ scope_id: scopeId });
+    if (name === 'foundation_describe') {
+        return { path: `/api/foundation/contract?${query.toString()}`, method: 'GET' };
+    }
+    if (name === 'foundation_read') {
+        const type = String(args.type);
+        const id = String(args.id);
+        query.set('revision', String(args.revision));
+        if (args.digest !== undefined)
+            query.set('digest', String(args.digest));
+        return {
+            path: `/api/foundation/definitions/${encodeURIComponent(type)}/${encodeURIComponent(id)}?${query.toString()}`,
+            method: 'GET',
+        };
+    }
+    if (name === 'foundation_validate_reference') {
+        const { scope_id: _scopeId, ...body } = args;
+        return {
+            path: `/api/foundation/judgment-references/validate?${query.toString()}`,
+            method: 'POST',
+            body,
+        };
+    }
+    const { scope_id: _scopeId, ...body } = args;
+    return {
+        path: `/api/foundation/judgment-problems/validate?${query.toString()}`,
+        method: 'POST',
+        body,
+    };
+}
+async function fetchFoundationCsrfToken(dependencies, context) {
+    const sessionId = `brainbase-mcp-foundation-${randomUUID()}`;
+    let response;
+    try {
+        response = await (dependencies.fetch || globalThis.fetch)(`${dependencies.apiUrl.replace(/\/+$/, '')}/api/csrf-token`, {
+            method: 'GET',
+            headers: {
+                Authorization: `Bearer ${context.token}`,
+                'x-brainbase-projects': context.scope.join(','),
+                'x-session-id': sessionId,
+            },
+        });
+    }
+    catch (error) {
+        return {
+            ok: false,
+            result: dependencies.auth.toolError('unavailable', 'foundation_csrf_unavailable', error instanceof Error ? error.message : String(error), context.scope),
+        };
+    }
+    let payload = null;
+    let payloadParsed = false;
+    try {
+        payload = await response.json();
+        payloadParsed = true;
+    }
+    catch {
+        // Keep the response fail-closed below; a 200 without a token is not a
+        // usable CSRF handshake.
+    }
+    if (!response.ok) {
+        return { ok: false, result: errorFromResponse(response, payload, context.scope, dependencies) };
+    }
+    const token = isRecord(payload) && typeof payload.token === 'string' ? payload.token.trim() : '';
+    if (!payloadParsed || !token) {
+        return {
+            ok: false,
+            result: dependencies.auth.toolError('error', 'foundation_csrf_response_invalid', 'Brainbase API returned an invalid CSRF response', context.scope, response.status),
+        };
+    }
+    return { ok: true, sessionId, token };
+}
+async function fetchFoundationRequest(dependencies, context, request) {
+    if (request.method !== 'POST') {
+        return dependencies.auth.fetchAuthenticatedJson(context, request);
+    }
+    const csrf = await fetchFoundationCsrfToken(dependencies, context);
+    if (!csrf.ok)
+        return csrf;
+    return dependencies.auth.fetchAuthenticatedJson(context, {
+        ...request,
+        headers: {
+            'x-session-id': csrf.sessionId,
+            'x-csrf-token': csrf.token,
+        },
+    });
+}
+function errorFromResponse(response, payload, scope, dependencies) {
+    const error = isRecord(payload) && isRecord(payload.error) ? payload.error : null;
+    const code = typeof error?.code === 'string' && error.code.trim()
+        ? error.code
+        : response.status === 404
+            ? 'foundation_api_unavailable'
+            : response.status >= 500
+                ? 'foundation_api_unavailable'
+                : 'foundation_api_error';
+    const message = typeof error?.message === 'string' && error.message.trim()
+        ? error.message
+        : `${response.status} ${response.statusText}`.trim();
+    const status = response.status === 404 || response.status >= 500 ? 'unavailable' : 'error';
+    return dependencies.auth.toolError(status, code, message, scope, response.status, error?.details);
+}
+function isFoundationScope(value) {
+    return isRecord(value)
+        && (value.type === 'personal' || value.type === 'project' || value.type === 'organization')
+        && isNonEmptyString(value.id);
+}
+function isFoundationAcl(value) {
+    return isRecord(value)
+        && isNonEmptyString(value.ownerId)
+        && (value.visibility === 'private'
+            || value.visibility === 'project'
+            || value.visibility === 'organization'
+            || value.visibility === 'public')
+        && Array.isArray(value.readerIds)
+        && value.readerIds.every((readerId) => isNonEmptyString(readerId))
+        && new Set(value.readerIds).size === value.readerIds.length
+        && Array.isArray(value.writerIds)
+        && value.writerIds.every((writerId) => isNonEmptyString(writerId))
+        && new Set(value.writerIds).size === value.writerIds.length;
+}
+function isValidPhilosophyRevisionPayload(args, payload) {
+    if (payload.kind !== 'philosophy'
+        || payload.id !== args.id
+        || payload.revision !== args.revision
+        || !isNonEmptyString(payload.digest)
+        || !DIGEST_PATTERN.test(payload.digest)
+        || !Object.prototype.hasOwnProperty.call(payload, 'payload')
+        || !isRecord(payload.applicability)
+        || !isFoundationScope(payload.applicability.scope)
+        || !isFoundationAcl(payload.currentAcl)
+        || !isFoundationScope(payload.currentScope)
+        || (args.digest !== undefined && payload.digest !== args.digest)) {
+        return false;
+    }
+    try {
+        // The canonical helper validates the JSON payload and applicability, and
+        // excludes read-time ACL/scope metadata from the immutable digest.
+        return philosophyRevisionDigest(payload) === payload.digest;
+    }
+    catch {
+        return false;
+    }
+}
+function isValidSuccessPayload(name, args, payload) {
+    if (!isRecord(payload))
+        return false;
+    if (name === 'foundation_describe') {
+        return payload.contractVersion === 'foundation-public.v1'
+            && payload.connection === 'configured'
+            && isRecord(payload.foundation)
+            && payload.executionPermission === 'none';
+    }
+    if (name === 'foundation_read') {
+        if (args.type === 'philosophy') {
+            return isValidPhilosophyRevisionPayload(args, payload);
+        }
+        const definition = isRecord(payload.definition) ? payload.definition : null;
+        return definition !== null
+            && isNonEmptyString(payload.digest)
+            && DIGEST_PATTERN.test(payload.digest)
+            && definition.id === args.id
+            && definition.type === args.type
+            && definition.revision === args.revision
+            && (args.digest === undefined || payload.digest === args.digest);
+    }
+    // The canonical HTTP route returns 200 only for a resolved validation.  A
+    // non-resolved result must remain an error/unavailable response even if an
+    // incorrectly connected upstream serializes it with HTTP 200.
+    return payload.status === 'resolved';
+}
+export async function handleFoundationPublicToolCall(name, args, dependencies) {
+    if (!isFoundationPublicToolName(name))
+        return null;
+    const scopeId = readScopeId(args);
+    if (!scopeId)
+        return invalidInput('scope_id is required and must be a safe project identifier', dependencies);
+    const unexpected = rejectUnexpectedKeys(args, name === 'foundation_describe'
+        ? ['scope_id']
+        : name === 'foundation_read'
+            ? ['scope_id', 'type', 'id', 'revision', 'digest']
+            : name === 'foundation_validate_reference'
+                ? ['scope_id', 'reference', 'phase']
+                : ['scope_id', 'snapshot'], dependencies);
+    if (unexpected)
+        return unexpected;
+    if (name === 'foundation_read') {
+        const invalid = validateReadArgs(args, dependencies);
+        if (invalid)
+            return invalid;
+    }
+    else if (name === 'foundation_validate_reference') {
+        const invalid = validateReferenceArgs(args, dependencies);
+        if (invalid)
+            return invalid;
+    }
+    else if (name === 'foundation_validate_problem') {
+        const invalid = validateProblemArgs(args, dependencies);
+        if (invalid)
+            return invalid;
+    }
+    const authenticated = await dependencies.auth.authenticateProject({ project_code: scopeId }, { requireProject: true });
+    if ('status' in authenticated)
+        return authenticated;
+    const context = selectedContext(authenticated, scopeId);
+    const fetched = await fetchFoundationRequest(dependencies, context, requestFor(name, args, scopeId));
+    if (!fetched.ok)
+        return fetched.result;
+    if (!fetched.response.ok)
+        return errorFromResponse(fetched.response, fetched.payload, context.scope, dependencies);
+    if (!fetched.payloadParsed || !isValidSuccessPayload(name, args, fetched.payload)) {
+        return dependencies.auth.toolError('error', 'foundation_api_response_invalid', 'Brainbase API returned an invalid Foundation response', context.scope, fetched.response.status);
+    }
+    return { status: 'ok', scope: { project_codes: context.scope }, data: fetched.payload };
+}

package/dist/foundation-catalog.d.ts

@@ -0,0 +1,26 @@
+import type { FoundationDefinition, FoundationRevision, FoundationType } from './ontology-foundation.js';
+import type { FoundationCatalog, FoundationCatalogRecord } from './types.js';
+/**
+ * The key is an encoded tuple rather than `${type}:${id}` so IDs containing a
+ * colon cannot alias another logical resource.
+ */
+export declare function foundationKey(reference: Pick<FoundationRevision, 'type' | 'id'>): string;
+export declare function createEmptyFoundationCatalog(): FoundationCatalog;
+export declare function cloneFoundationCatalog(catalog: FoundationCatalog): FoundationCatalog;
+export declare function cloneFoundationDefinition<T extends FoundationDefinition>(definition: T): T;
+export interface FoundationRef extends FoundationRevision {
+    digest: string;
+}
+export declare function foundationRef(record: FoundationCatalogRecord): FoundationRef;
+/**
+ * Hashes the complete definition, with object keys sorted recursively. Array
+ * order remains significant because criteria, provenance, and authorized uses
+ * are ordered contracts in the shared ontology.
+ */
+export declare function digestFoundationDefinition(definition: FoundationDefinition): string;
+export declare function nextFoundationRevision(revision: string): string;
+export declare function assertFoundationRevision(value: unknown, label?: string): asserts value is FoundationRevision;
+export declare function assertFoundationCatalog(value: unknown): asserts value is FoundationCatalog | undefined;
+export declare function foundationCatalogOrEmpty(value: FoundationCatalog | undefined): FoundationCatalog;
+export declare function findFoundationRecord(catalog: FoundationCatalog, reference: FoundationRevision): FoundationCatalogRecord | undefined;
+export declare function findLatestFoundationRecord(catalog: FoundationCatalog, type: FoundationType, id: string): FoundationCatalogRecord | undefined;

package/dist/foundation-catalog.js

@@ -0,0 +1,206 @@
+import { createHash } from 'node:crypto';
+import { validateFoundationDefinition, validateFoundationRelation } from './ontology-foundation.js';
+const revisionPattern = /^[1-9]\d*$/;
+const digestPattern = /^sha256:[0-9a-f]{64}$/;
+/**
+ * The key is an encoded tuple rather than `${type}:${id}` so IDs containing a
+ * colon cannot alias another logical resource.
+ */
+export function foundationKey(reference) {
+    return JSON.stringify([reference.type, reference.id]);
+}
+export function createEmptyFoundationCatalog() {
+    return {
+        version: 1,
+        records: [],
+        latest: {},
+        relations: []
+    };
+}
+export function cloneFoundationCatalog(catalog) {
+    return JSON.parse(JSON.stringify(catalog));
+}
+export function cloneFoundationDefinition(definition) {
+    return JSON.parse(JSON.stringify(definition));
+}
+export function foundationRef(record) {
+    return {
+        id: record.definition.id,
+        type: record.definition.type,
+        revision: record.definition.revision,
+        digest: record.digest
+    };
+}
+/**
+ * Hashes the complete definition, with object keys sorted recursively. Array
+ * order remains significant because criteria, provenance, and authorized uses
+ * are ordered contracts in the shared ontology.
+ */
+export function digestFoundationDefinition(definition) {
+    const canonical = canonicalJson(definition);
+    return `sha256:${createHash('sha256').update(canonical, 'utf8').digest('hex')}`;
+}
+export function nextFoundationRevision(revision) {
+    assertRevision(revision, 'revision');
+    return (BigInt(revision) + 1n).toString();
+}
+export function assertFoundationRevision(value, label = 'revision') {
+    if (!isRecord(value)
+        || typeof value.id !== 'string'
+        || value.id.length === 0
+        || !isFoundationType(value.type)
+        || typeof value.revision !== 'string') {
+        throw new Error(`FOUNDATION-INVALID-REFERENCE: ${label} must contain id, type, and revision`);
+    }
+    assertRevision(value.revision, `${label}.revision`);
+}
+export function assertFoundationCatalog(value) {
+    if (value === undefined)
+        return;
+    if (!isRecord(value) || value.version !== 1 || !Array.isArray(value.records) || !Array.isArray(value.relations) || !isRecord(value.latest)) {
+        throw new Error('FOUNDATION-CATALOG-CORRUPT: version, records, latest, and relations are required');
+    }
+    const recordsByRevision = new Map();
+    const latestByLogical = new Map();
+    for (const [index, item] of value.records.entries()) {
+        if (!isRecord(item) || !isRecord(item.definition) || typeof item.digest !== 'string') {
+            throw new Error(`FOUNDATION-CATALOG-CORRUPT: records[${index}] must contain a definition and digest`);
+        }
+        const definition = item.definition;
+        assertDefinitionShape(definition, `records[${index}].definition`);
+        const revisionKey = `${foundationKey(definition)}@${definition.revision}`;
+        if (recordsByRevision.has(revisionKey)) {
+            throw new Error(`FOUNDATION-CATALOG-CORRUPT: duplicate revision ${revisionKey}`);
+        }
+        if (!digestPattern.test(item.digest) || item.digest !== digestFoundationDefinition(definition)) {
+            throw new Error(`FOUNDATION-CATALOG-CORRUPT: digest mismatch for ${revisionKey}`);
+        }
+        const record = item;
+        recordsByRevision.set(revisionKey, record);
+        const logicalKey = foundationKey(definition);
+        const previous = latestByLogical.get(logicalKey);
+        if (!previous || compareRevisions(definition.revision, previous.definition.revision) > 0) {
+            latestByLogical.set(logicalKey, record);
+        }
+    }
+    const latest = value.latest;
+    const latestKeys = Object.keys(latest);
+    if (latestKeys.length !== latestByLogical.size) {
+        throw new Error('FOUNDATION-CATALOG-CORRUPT: latest pointers do not match records');
+    }
+    for (const [logicalKey, record] of latestByLogical) {
+        const pointer = latest[logicalKey];
+        assertFoundationRevision(pointer, `latest[${logicalKey}]`);
+        if (foundationKey(pointer) !== logicalKey || pointer.revision !== record.definition.revision) {
+            throw new Error(`FOUNDATION-CATALOG-CORRUPT: latest pointer mismatch for ${logicalKey}`);
+        }
+        if (!recordsByRevision.has(`${logicalKey}@${pointer.revision}`)) {
+            throw new Error(`FOUNDATION-CATALOG-CORRUPT: latest pointer has no record for ${logicalKey}@${pointer.revision}`);
+        }
+    }
+    for (const [index, relation] of value.relations.entries()) {
+        if (!isRecord(relation))
+            throw new Error(`FOUNDATION-CATALOG-CORRUPT: relations[${index}] is not an object`);
+        const result = safeValidateRelation(relation);
+        if (!result.valid) {
+            throw new Error(`FOUNDATION-CATALOG-CORRUPT: relations[${index}] ${result.issues.map((issue) => issue.message).join('; ')}`);
+        }
+        for (const endpoint of [relation.source, relation.target]) {
+            if (!isRecord(endpoint) || typeof endpoint.id !== 'string' || !isFoundationType(endpoint.type) || typeof endpoint.revision !== 'string')
+                continue;
+            assertRevision(endpoint.revision, `relations[${index}] endpoint.revision`);
+            const endpointKey = `${foundationKey({ id: endpoint.id, type: endpoint.type })}@${endpoint.revision}`;
+            if (!recordsByRevision.has(endpointKey)) {
+                throw new Error(`FOUNDATION-CATALOG-CORRUPT: relation endpoint ${endpointKey} has no record`);
+            }
+        }
+    }
+}
+export function foundationCatalogOrEmpty(value) {
+    if (value === undefined)
+        return createEmptyFoundationCatalog();
+    assertFoundationCatalog(value);
+    return cloneFoundationCatalog(value);
+}
+export function findFoundationRecord(catalog, reference) {
+    assertFoundationRevision(reference);
+    return catalog.records.find((record) => (record.definition.id === reference.id
+        && record.definition.type === reference.type
+        && record.definition.revision === reference.revision));
+}
+export function findLatestFoundationRecord(catalog, type, id) {
+    const pointer = catalog.latest[foundationKey({ type, id })];
+    return pointer ? findFoundationRecord(catalog, pointer) : undefined;
+}
+function assertDefinitionShape(definition, label) {
+    if (!isRecord(definition)
+        || typeof definition.id !== 'string'
+        || definition.id.length === 0
+        || !isFoundationType(definition.type)
+        || typeof definition.revision !== 'string') {
+        throw new Error(`FOUNDATION-CATALOG-CORRUPT: ${label} has an invalid identity`);
+    }
+    assertRevision(definition.revision, `${label}.revision`);
+    if (!isRecord(definition.acl)
+        || typeof definition.acl.ownerId !== 'string'
+        || definition.acl.ownerId.length === 0
+        || !Array.isArray(definition.acl.readerIds)
+        || !Array.isArray(definition.acl.writerIds)
+        || !['private', 'project', 'organization', 'public'].includes(definition.acl.visibility)) {
+        throw new Error(`FOUNDATION-CATALOG-CORRUPT: ${label}.acl is invalid`);
+    }
+    const result = safeValidateDefinition(definition);
+    if (!result.valid) {
+        throw new Error(`FOUNDATION-CATALOG-CORRUPT: ${label} ${result.issues.map((issue) => issue.message).join('; ')}`);
+    }
+}
+function safeValidateDefinition(definition) {
+    try {
+        return validateFoundationDefinition(definition, { use: 'draft' });
+    }
+    catch (error) {
+        throw new Error(`invalid definition: ${formatError(error)}`);
+    }
+}
+function safeValidateRelation(relation) {
+    try {
+        return validateFoundationRelation(relation);
+    }
+    catch (error) {
+        throw new Error(`invalid relation: ${formatError(error)}`);
+    }
+}
+function assertRevision(value, label) {
+    if (!revisionPattern.test(value)) {
+        throw new Error(`FOUNDATION-INVALID-REVISION: ${label} must be a positive canonical decimal`);
+    }
+}
+function compareRevisions(left, right) {
+    const leftValue = BigInt(left);
+    const rightValue = BigInt(right);
+    return leftValue < rightValue ? -1 : leftValue > rightValue ? 1 : 0;
+}
+function isFoundationType(value) {
+    return value === 'objective' || value === 'variable' || value === 'model' || value === 'constraint';
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function canonicalJson(value) {
+    const canonical = canonicalize(value);
+    const serialized = JSON.stringify(canonical);
+    if (serialized === undefined)
+        throw new Error('FOUNDATION-DIGEST-INVALID: definition is not JSON serializable');
+    return serialized;
+}
+function canonicalize(value) {
+    if (Array.isArray(value))
+        return value.map((item) => canonicalize(item));
+    if (isRecord(value)) {
+        return Object.fromEntries(Object.keys(value).sort().flatMap((key) => (value[key] === undefined ? [] : [[key, canonicalize(value[key])]])));
+    }
+    return value;
+}
+function formatError(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/foundation-constraint-store.d.ts

@@ -0,0 +1,50 @@
+import type { FoundationRevisionStore } from './foundation-store.js';
+import { type ConstraintAuthorizationContext, type ConstraintExceptionQuery, type ConstraintExceptionRecord, type ConstraintProjection, type ConstraintStore, type ConstraintStoreQuery } from './constraint-resolution.js';
+/**
+ * Exception records are deliberately a host supplied boundary.  The shared
+ * foundation catalog currently stores the ontology-level exception reference
+ * (Decision revision and scope), while Story04 also needs approval metadata,
+ * expiry, and rationale.  A host must therefore provide the canonical
+ * evidence/execution adapter for that record until the shared contract grows
+ * those fields; this module never creates a private sidecar file.
+ */
+export interface ConstraintExceptionStore {
+    append(exception: ConstraintExceptionRecord, context: ConstraintAuthorizationContext): Promise<ConstraintExceptionRecord>;
+    list(query: ConstraintExceptionQuery, context: ConstraintAuthorizationContext): Promise<readonly ConstraintExceptionRecord[]>;
+}
+export interface FoundationConstraintStoreOptions {
+    foundationStore: FoundationRevisionStore;
+    exceptionStore: ConstraintExceptionStore;
+}
+/**
+ * Adapts the Objective Story's GraphFoundationRevisionStore to the resolver's
+ * ConstraintStore port.  Definitions are persisted in the existing PersonalOs
+ * aggregate through FoundationRevisionStore; no second Graph or file is
+ * created here.
+ */
+export declare class FoundationConstraintStore<TConstraint extends ConstraintProjection = ConstraintProjection> implements ConstraintStore<TConstraint> {
+    private readonly foundationStore;
+    private readonly exceptionStore;
+    constructor(options: FoundationConstraintStoreOptions);
+    append(input: {
+        record: TConstraint;
+        expectedPreviousRevision?: string | null;
+    }, context?: ConstraintAuthorizationContext): Promise<TConstraint>;
+    get(ref: {
+        id: string;
+        revision: string;
+    }, context?: ConstraintAuthorizationContext): Promise<TConstraint | null>;
+    getLatest(id: string, context?: ConstraintAuthorizationContext): Promise<TConstraint | null>;
+    list(query: ConstraintStoreQuery, context?: ConstraintAuthorizationContext): Promise<readonly TConstraint[]>;
+    appendException(exception: ConstraintExceptionRecord, context?: ConstraintAuthorizationContext): Promise<ConstraintExceptionRecord>;
+    listExceptions(query: ConstraintExceptionQuery, context?: ConstraintAuthorizationContext): Promise<readonly ConstraintExceptionRecord[]>;
+    /**
+     * The injected exception boundary is intentionally persistence-only and may
+     * not enforce Foundation ACLs itself.  Resolve the referenced Constraint at
+     * this adapter boundary before allowing exception evidence to cross it.
+     * Current ACL controls access even when an exception points at an older
+     * revision; the exact revision is still read to reject dangling references.
+     */
+    private authorizeExceptionTarget;
+}
+export declare function createFoundationConstraintStore(options: FoundationConstraintStoreOptions): ConstraintStore;