@unson/brainbase-mcp 0.33.0 → 0.34.0

package/dist/ontology-kernel.d.ts

@@ -0,0 +1,102 @@
+export declare const DECISION_STATUS_RULE_ID = "CON-DECISION-STATUS-001";
+export declare class OntologyError extends Error {
+    [key: string]: any;
+    constructor(code: any, message: any, details?: any);
+}
+export declare class OntologyKernel {
+    [key: string]: any;
+    constructor({ manifest, status }: any);
+    get version(): any;
+    describe(): any;
+    getType(type: any): any;
+    getRelation(relation: any): any;
+    validateEntity(entity: any, { deferRequiredRelations }?: any): {
+        valid: boolean;
+        ontology_version: any;
+        violations: any[];
+    };
+    validateEdge(edge: any): {
+        valid: any;
+        ontology_version: any;
+        violations: any[];
+    };
+    /**
+     * Which persisted edges validateSnapshot needs in order to judge a
+     * mutation. Only two rules read existing edges: relation cardinality
+     * (same relation, same constrained endpoint as a mutation edge) and
+     * required relations (the listed relations, in their direction, from a
+     * validated entity of the rule's target type). Every other persisted
+     * edge cannot change the verdict for this mutation.
+     *
+     * @returns {{ relation: string, endpoint: 'from_id'|'to_id', ids: string[] }[]}
+     */
+    mutationEdgeScope({ mutationEdges, validationEntities }?: any): any[];
+    validateSnapshot(snapshot: any, _adapters?: any): {
+        valid: boolean;
+        verification: string;
+        ontology_version: any;
+        violations: any;
+    };
+    inferDecisions(snapshot: any, { derivedAt }?: any): {
+        ontology_version: any;
+        as_of: any;
+        derived_at: any;
+        decisions: {
+            [k: string]: any;
+        };
+        evidence: ({
+            rule_id: any;
+            from_id: any;
+            to_id: any;
+            decision_ids?: undefined;
+        } | {
+            rule_id: string;
+            decision_ids: any[];
+            from_id?: undefined;
+            to_id?: undefined;
+        })[];
+        explanation: string;
+    };
+    impact({ change, snapshot }: any): {
+        ontology_version: any;
+        semver: any;
+        verification: string;
+        match_count: any;
+        representative_ids: any;
+        affected_apis: any;
+        affected_agents: any;
+        migration_required: boolean;
+        history_required: any;
+    };
+    planEvolution(change?: any): {
+        event_id: any;
+        event_type: string;
+        ontology_version: any;
+        canonical_id: any;
+        source_ids: unknown[];
+        aliases: unknown[];
+        provenance: any;
+        effective_at: any;
+        conflict_policy: any;
+    };
+    interpretHistory(snapshot?: any, { asOf }?: any): {
+        ontology_version: any;
+        as_of: any;
+        applied_event_ids: any;
+        entities: any;
+        edges: any;
+    };
+}
+/**
+ * Build an immutable Ontology release candidate from a base release and a
+ * change set. The result is a dry-run artifact: it is never written here and
+ * becomes current only through the RACI-authorized publisher (ADR-021).
+ */
+export declare function buildOntologyReleaseCandidate(baseManifest: any, proposal?: any): {
+    candidate: any;
+    required_bump: string;
+    declared_bump: string | null;
+    semver_ok: boolean;
+    change_classification: any[];
+    consistency_violations: any[];
+};

package/dist/ontology-kernel.js

@@ -0,0 +1,681 @@
+// Moved from brainbase-unson server/services/ontology-kernel.js without changing behavior.
+// Only type annotations were added; values stay open JSON objects as in the original.
+/* eslint-disable @typescript-eslint/no-explicit-any */
+const REQUIRED_MANIFEST_KEYS = [
+    'version',
+    'initial_status',
+    'effective_at',
+    'entity_types',
+    'relation_types',
+    'constraints',
+    'inference_rules',
+    'evolution_rules',
+    'previous_version',
+    'compatibility',
+    'migration',
+    'rollback',
+    'governance',
+    'impact_scope',
+    'changes'
+];
+const REQUIRED_TYPE_FIELDS = ['description', 'identity', 'usage', 'examples', 'counter_examples', 'owner'];
+const REQUIRED_RELATION_FIELDS = ['from', 'to', 'direction', 'cardinality', 'lifecycle', 'provenance'];
+export const DECISION_STATUS_RULE_ID = 'CON-DECISION-STATUS-001';
+export class OntologyError extends Error {
+    constructor(code, message, details = {}) {
+        super(message);
+        this.name = 'OntologyError';
+        this.code = code;
+        this.details = details;
+    }
+}
+function violation(ruleId, message, extra = {}) {
+    return { rule_id: ruleId, message, ...extra };
+}
+function matchesWhen(payload, when = {}) {
+    return Object.entries(when).every(([key, expected]) => {
+        const actual = payload?.[key];
+        return Array.isArray(expected) ? expected.includes(actual) : actual === expected;
+    });
+}
+function assertManifest(manifest) {
+    const missing = REQUIRED_MANIFEST_KEYS.filter((key) => !Object.hasOwn(manifest || {}, key));
+    if (missing.length) {
+        throw new OntologyError('ONTOLOGY_MANIFEST_INVALID', `Ontology manifest is missing: ${missing.join(', ')}`, { missing });
+    }
+    if (!Object.keys(manifest.entity_types).length || !Object.keys(manifest.relation_types).length) {
+        throw new OntologyError('ONTOLOGY_MANIFEST_INVALID', 'Ontology manifest vocabulary must not be empty');
+    }
+    const invalidTypes = Object.entries(manifest.entity_types)
+        .filter(([, definition]) => REQUIRED_TYPE_FIELDS.some((field) => definition[field] == null))
+        .map(([id]) => id);
+    const invalidRelations = Object.entries(manifest.relation_types)
+        .filter(([, definition]) => REQUIRED_RELATION_FIELDS.some((field) => definition[field] == null)
+        || (definition.inverse === undefined && definition.symmetric === undefined))
+        .map(([id]) => id);
+    if (invalidTypes.length || invalidRelations.length) {
+        throw new OntologyError('ONTOLOGY_MANIFEST_INVALID', 'Ontology vocabulary metadata is incomplete', {
+            invalid_types: invalidTypes,
+            invalid_relations: invalidRelations
+        });
+    }
+    if (!Array.isArray(manifest.changes)
+        || !['initial', 'backward_compatible', 'breaking'].includes(manifest.compatibility?.classification)
+        || typeof manifest.migration?.required !== 'boolean'
+        || typeof manifest.rollback?.strategy !== 'string'
+        || !manifest.governance || typeof manifest.governance !== 'object') {
+        throw new OntologyError('ONTOLOGY_MANIFEST_INVALID', 'Ontology release governance metadata is incomplete');
+    }
+}
+export class OntologyKernel {
+    constructor({ manifest, status = null }) {
+        assertManifest(manifest);
+        this.manifest = structuredClone(manifest);
+        this.status = status || manifest.initial_status;
+    }
+    get version() {
+        return this.manifest.version;
+    }
+    describe() {
+        return { ...structuredClone(this.manifest), effective_status: this.status };
+    }
+    getType(type) {
+        const definition = this.manifest.entity_types[type];
+        if (!definition) {
+            throw new OntologyError('ONTOLOGY_TYPE_UNKNOWN', `Unknown ontology type: ${type}`, { rule_id: 'entity-type-registered', type });
+        }
+        return structuredClone(definition);
+    }
+    getRelation(relation) {
+        const definition = this.manifest.relation_types[relation];
+        if (!definition) {
+            throw new OntologyError('ONTOLOGY_RELATION_UNKNOWN', `Unknown ontology relation: ${relation}`, { rule_id: 'relation-type-registered', relation });
+        }
+        return structuredClone(definition);
+    }
+    validateEntity(entity, { deferRequiredRelations = false } = {}) {
+        const violations = [];
+        if (!entity?.id)
+            violations.push(violation('entity-id-required', 'Entity id is required'));
+        const type = entity?.type || entity?.entity_type;
+        if (!this.manifest.entity_types[type]) {
+            violations.push(violation('entity-type-registered', `Unknown ontology type: ${type}`, { entity_id: entity?.id, type }));
+        }
+        // A Decision without an explicit status cannot be evaluated against the
+        // conditional relation constraints below. Keep this invariant in the
+        // kernel so every release, including older signed manifests, rejects a
+        // status omission instead of treating it as an inactive Decision.
+        if (type === 'decision') {
+            const status = entity?.payload?.status;
+            if (typeof status !== 'string' || status.trim() === '') {
+                violations.push(violation(DECISION_STATUS_RULE_ID, 'Decision requires an explicit status', { entity_id: entity?.id, missing_fields: ['status'] }));
+            }
+        }
+        for (const rule of this.manifest.constraints) {
+            if (rule.target !== type || rule.kind !== 'required_fields_when')
+                continue;
+            const matches = matchesWhen(entity?.payload, rule.when);
+            if (!matches)
+                continue;
+            const missingFields = rule.fields.filter((field) => {
+                const value = entity?.payload?.[field];
+                return value == null || value === '' || (Array.isArray(value) && value.length === 0);
+            });
+            if (missingFields.length) {
+                violations.push(violation(rule.id, `Missing required fields: ${missingFields.join(', ')}`, {
+                    entity_id: entity?.id,
+                    missing_fields: missingFields
+                }));
+            }
+        }
+        if (!deferRequiredRelations) {
+            for (const rule of this.manifest.constraints) {
+                if (rule.target !== type || !['required_relation', 'required_relation_when'].includes(rule.kind))
+                    continue;
+                if (rule.kind === 'required_relation_when' && !matchesWhen(entity?.payload, rule.when))
+                    continue;
+                violations.push(violation(rule.id, rule.message || `${type} requires relation evidence in an aggregate snapshot`, {
+                    entity_id: entity?.id,
+                    aggregate_required: true
+                }));
+            }
+        }
+        return { valid: violations.length === 0, ontology_version: this.version, violations };
+    }
+    validateEdge(edge) {
+        const relation = edge?.relation || edge?.rel_type;
+        const definition = this.manifest.relation_types[relation];
+        if (!definition) {
+            return {
+                valid: false,
+                ontology_version: this.version,
+                violations: [violation('relation-type-registered', `Unknown ontology relation: ${relation}`, { relation })]
+            };
+        }
+        const fromType = edge?.from_type;
+        const toType = edge?.to_type;
+        const validEndpoint = definition.from.includes(fromType) && definition.to.includes(toType);
+        return {
+            valid: validEndpoint,
+            ontology_version: this.version,
+            violations: validEndpoint ? [] : [violation(`relation-endpoint-${relation}`, `Invalid ${relation} endpoint`, {
+                    relation,
+                    from_type: fromType,
+                    to_type: toType
+                })]
+        };
+    }
+    /**
+     * Which persisted edges validateSnapshot needs in order to judge a
+     * mutation. Only two rules read existing edges: relation cardinality
+     * (same relation, same constrained endpoint as a mutation edge) and
+     * required relations (the listed relations, in their direction, from a
+     * validated entity of the rule's target type). Every other persisted
+     * edge cannot change the verdict for this mutation.
+     *
+     * @returns {{ relation: string, endpoint: 'from_id'|'to_id', ids: string[] }[]}
+     */
+    mutationEdgeScope({ mutationEdges = [], validationEntities = [] } = {}) {
+        const groups = new Map();
+        const add = (relation, endpoint, id) => {
+            if (!relation || !id)
+                return;
+            const key = `${relation}\u0000${endpoint}`;
+            if (!groups.has(key))
+                groups.set(key, { relation, endpoint, ids: new Set() });
+            groups.get(key).ids.add(id);
+        };
+        for (const edge of mutationEdges) {
+            const relation = edge?.relation || edge?.rel_type;
+            const cardinality = this.manifest.relation_types[relation]?.cardinality;
+            if (cardinality === 'many_to_one' || cardinality === 'one_to_one')
+                add(relation, 'from_id', edge.from_id);
+            if (cardinality === 'one_to_many' || cardinality === 'one_to_one')
+                add(relation, 'to_id', edge.to_id);
+        }
+        for (const rule of this.manifest.constraints) {
+            if (!['required_relation', 'required_relation_when'].includes(rule.kind))
+                continue;
+            const alternatives = rule.alternatives || [{ relation: rule.relation, direction: 'outgoing' }];
+            for (const entity of validationEntities) {
+                if ((entity?.type || entity?.entity_type) !== rule.target)
+                    continue;
+                for (const alternative of alternatives) {
+                    add(alternative.relation, alternative.direction === 'incoming' ? 'to_id' : 'from_id', entity.id);
+                }
+            }
+        }
+        return Array.from(groups.values(), (group) => ({ ...group, ids: Array.from(group.ids).sort() }));
+    }
+    validateSnapshot(snapshot, _adapters = {}) {
+        const entities = snapshot?.entities || [];
+        const edges = snapshot?.edges || [];
+        const byId = new Map(entities.map((entity) => [entity.id, entity]));
+        const validationEntityIds = Array.isArray(snapshot?.validation_entity_ids)
+            ? new Set(snapshot.validation_entity_ids)
+            : null;
+        const validationEntities = validationEntityIds
+            ? entities.filter((entity) => validationEntityIds.has(entity.id))
+            : entities;
+        const requiredRelationValidationEntityIds = Array.isArray(snapshot?.required_relation_validation_entity_ids)
+            ? new Set(snapshot.required_relation_validation_entity_ids)
+            : validationEntityIds;
+        const requiredRelationValidationEntities = requiredRelationValidationEntityIds
+            ? entities.filter((entity) => requiredRelationValidationEntityIds.has(entity.id))
+            : entities;
+        const violations = validationEntities.flatMap((entity) => this.validateEntity(entity, { deferRequiredRelations: true }).violations);
+        for (const edge of edges) {
+            const from = byId.get(edge.from_id);
+            const to = byId.get(edge.to_id);
+            if (!from || !to) {
+                violations.push(violation('edge-reference-integrity', 'Edge endpoints must reference entities in the snapshot', {
+                    edge_id: edge.id || null,
+                    missing_endpoint_ids: [!from ? edge.from_id : null, !to ? edge.to_id : null].filter(Boolean)
+                }));
+                continue;
+            }
+            violations.push(...this.validateEdge({ ...edge, from_type: edge.from_type || from?.type, to_type: edge.to_type || to?.type }).violations);
+        }
+        for (const [relation, definition] of Object.entries(this.manifest.relation_types)) {
+            if (!['many_to_one', 'one_to_many', 'one_to_one'].includes(definition.cardinality))
+                continue;
+            const relationEdges = edges.filter((edge) => (edge.relation || edge.rel_type) === relation);
+            const constrainedSides = definition.cardinality === 'many_to_one'
+                ? [['from_id', 'outgoing']]
+                : definition.cardinality === 'one_to_many'
+                    ? [['to_id', 'incoming']]
+                    : [['from_id', 'outgoing'], ['to_id', 'incoming']];
+            for (const [endpoint, direction] of constrainedSides) {
+                const counts = new Map();
+                for (const edge of relationEdges)
+                    counts.set(edge[endpoint], (counts.get(edge[endpoint]) || 0) + 1);
+                for (const [entityId, count] of counts) {
+                    if (count <= 1)
+                        continue;
+                    violations.push(violation(`relation-cardinality-${relation}`, `${relation} permits at most one ${direction} edge`, {
+                        relation,
+                        entity_id: entityId,
+                        direction,
+                        count,
+                        cardinality: definition.cardinality
+                    }));
+                }
+            }
+        }
+        for (const rule of this.manifest.constraints) {
+            if (!['required_relation', 'required_relation_when'].includes(rule.kind))
+                continue;
+            for (const entity of requiredRelationValidationEntities.filter((item) => (item.type || item.entity_type) === rule.target)) {
+                if (rule.kind === 'required_relation_when' && !matchesWhen(entity.payload, rule.when))
+                    continue;
+                const alternatives = rule.alternatives || [{ relation: rule.relation, direction: 'outgoing' }];
+                const hasRelation = alternatives.some((alternative) => edges.some((edge) => {
+                    const endpointId = alternative.direction === 'incoming' ? edge.to_id : edge.from_id;
+                    if (endpointId !== entity.id || (edge.relation || edge.rel_type) !== alternative.relation)
+                        return false;
+                    if (!Array.isArray(rule.related_types) || rule.related_types.length === 0)
+                        return true;
+                    const relatedId = alternative.direction === 'incoming' ? edge.from_id : edge.to_id;
+                    const related = byId.get(relatedId);
+                    return related && rule.related_types.includes(related.type || related.entity_type);
+                }));
+                if (!hasRelation) {
+                    violations.push(violation(rule.id, rule.message || `${rule.target} requires relation evidence`, { entity_id: entity.id }));
+                }
+            }
+        }
+        if (snapshot?.complete === false) {
+            violations.push(violation('snapshot-incomplete', 'Snapshot is incomplete; absence cannot be verified'));
+        }
+        return {
+            valid: violations.length === 0,
+            verification: snapshot?.complete === false ? 'unverified' : 'verified',
+            ontology_version: this.version,
+            violations
+        };
+    }
+    inferDecisions(snapshot, { derivedAt } = {}) {
+        const asOf = snapshot?.as_of || new Date().toISOString();
+        const derived_at = derivedAt || snapshot?.derived_at || new Date().toISOString();
+        const decisions = Object.fromEntries((snapshot?.entities || [])
+            .filter((entity) => (entity.type || entity.entity_type) === 'decision')
+            .map((entity) => [entity.id, { ...entity.payload, explicit: true, inferred: false }]));
+        const evidence = [];
+        const supersessionRule = this.manifest.inference_rules.find((rule) => rule.relation === 'supersedes');
+        const effectiveStatuses = new Set(supersessionRule?.effective_statuses || ['active']);
+        const isEffectiveSupersession = (edge) => {
+            if ((edge.relation || edge.rel_type) !== 'supersedes')
+                return false;
+            const replacement = decisions[edge.from_id];
+            if (!replacement || !decisions[edge.to_id] || !effectiveStatuses.has(replacement.status))
+                return false;
+            const asOfTime = Date.parse(asOf);
+            return [edge.effective_at, replacement.effective_at]
+                .filter(Boolean)
+                .every((effectiveAt) => Date.parse(effectiveAt) <= asOfTime);
+        };
+        for (const edge of snapshot?.edges || []) {
+            if (!isEffectiveSupersession(edge))
+                continue;
+            const replacement = decisions[edge.from_id];
+            decisions[edge.to_id] = { ...decisions[edge.to_id], status: 'superseded', inferred: true };
+            evidence.push({ rule_id: supersessionRule?.id || 'decision-supersession', from_id: edge.from_id, to_id: edge.to_id });
+        }
+        const explicitSupersessions = new Set((snapshot?.edges || [])
+            .filter(isEffectiveSupersession)
+            .flatMap((edge) => [`${edge.from_id}:${edge.to_id}`, `${edge.to_id}:${edge.from_id}`]));
+        const scopesByDecision = new Map(Object.entries(decisions).map(([id, decision]) => [
+            id,
+            new Set(Array.isArray(decision.scope_ids) ? decision.scope_ids : [])
+        ]));
+        const entitiesById = new Map((snapshot?.entities || []).map((entity) => [entity.id, entity]));
+        for (const edge of snapshot?.edges || []) {
+            if ((edge.relation || edge.rel_type) !== 'belongs_to_project' || !scopesByDecision.has(edge.from_id))
+                continue;
+            const scope = entitiesById.get(edge.to_id);
+            if (!scope || (scope.type || scope.entity_type) !== 'project')
+                continue;
+            scopesByDecision.get(edge.from_id).add(edge.to_id);
+        }
+        const activeIds = Object.entries(decisions)
+            .filter(([, decision]) => effectiveStatuses.has(decision.status))
+            .map(([id]) => id);
+        for (let leftIndex = 0; leftIndex < activeIds.length; leftIndex += 1) {
+            for (let rightIndex = leftIndex + 1; rightIndex < activeIds.length; rightIndex += 1) {
+                const leftId = activeIds[leftIndex];
+                const rightId = activeIds[rightIndex];
+                const leftScopes = scopesByDecision.get(leftId) || new Set();
+                const rightScopes = scopesByDecision.get(rightId) || new Set();
+                const overlaps = [...leftScopes].some((scope) => rightScopes.has(scope));
+                if (!overlaps || explicitSupersessions.has(`${leftId}:${rightId}`))
+                    continue;
+                decisions[leftId] = { ...decisions[leftId], status: 'conflict', inferred: true };
+                decisions[rightId] = { ...decisions[rightId], status: 'conflict', inferred: true };
+                evidence.push({ rule_id: 'decision-active-conflict', decision_ids: [leftId, rightId] });
+            }
+        }
+        const explanation = evidence.length
+            ? evidence.map((item) => item.decision_ids
+                ? `${item.decision_ids.join(' and ')} conflict`
+                : `${item.from_id} supersedes ${item.to_id}`).join('; ')
+            : 'No decision supersession was inferred';
+        return { ontology_version: this.version, as_of: asOf, derived_at, decisions, evidence, explanation };
+    }
+    impact({ change = {}, snapshot = null }) {
+        const kind = change.kind || 'editorial';
+        const semver = kind.startsWith('remove_') || kind === 'narrow_endpoint'
+            ? this.manifest.evolution_rules.breaking
+            : kind.startsWith('add_')
+                ? this.manifest.evolution_rules.additive
+                : this.manifest.evolution_rules.editorial;
+        if (!snapshot) {
+            return {
+                ontology_version: this.version,
+                semver,
+                verification: 'unverified',
+                match_count: null,
+                representative_ids: [],
+                affected_apis: change.affected_apis || [],
+                affected_agents: change.affected_agents || [],
+                migration_required: semver === 'major',
+                history_required: this.manifest.evolution_rules.history_required_for.includes(kind)
+            };
+        }
+        const entityIds = (snapshot.entities || [])
+            .filter((entity) => !change.type || (entity.type || entity.entity_type) === change.type)
+            .map((entity) => entity.id);
+        const edgeIds = (snapshot.edges || [])
+            .filter((edge) => !change.relation || (edge.relation || edge.rel_type) === change.relation)
+            .map((edge) => edge.id || `${edge.from_id}:${edge.relation || edge.rel_type}:${edge.to_id}`);
+        let ids = change.relation ? edgeIds : entityIds;
+        if (change.rule_id) {
+            const rule = [...this.manifest.constraints, ...this.manifest.inference_rules]
+                .find((candidate) => candidate.id === change.rule_id);
+            if (!rule) {
+                throw new OntologyError('ONTOLOGY_RULE_UNKNOWN', `Unknown ontology rule: ${change.rule_id}`);
+            }
+            ids = rule.relation
+                ? (snapshot.edges || []).filter((edge) => (edge.relation || edge.rel_type) === rule.relation)
+                    .map((edge) => edge.id || `${edge.from_id}:${edge.relation || edge.rel_type}:${edge.to_id}`)
+                : (snapshot.entities || []).filter((entity) => !rule.target || (entity.type || entity.entity_type) === rule.target)
+                    .map((entity) => entity.id);
+        }
+        return {
+            ontology_version: this.version,
+            semver,
+            verification: 'verified',
+            match_count: ids.length,
+            representative_ids: ids.slice(0, 10),
+            affected_apis: change.affected_apis || [],
+            affected_agents: change.affected_agents || [],
+            migration_required: semver === 'major',
+            history_required: this.manifest.evolution_rules.history_required_for.includes(kind)
+        };
+    }
+    planEvolution(change = {}) {
+        const kind = change.kind;
+        if (!this.manifest.evolution_rules.history_required_for.includes(kind)) {
+            throw new OntologyError('ONTOLOGY_EVOLUTION_KIND_INVALID', `Evolution kind does not require identity history: ${kind}`);
+        }
+        const required = ['canonical_id', 'source_ids', 'effective_at'];
+        const missing = required.filter((field) => !change[field]
+            || (field === 'source_ids' && (!Array.isArray(change[field]) || change[field].length === 0)));
+        if (missing.length) {
+            throw new OntologyError('ONTOLOGY_EVOLUTION_HISTORY_REQUIRED', `Evolution history is missing: ${missing.join(', ')}`, { missing });
+        }
+        return {
+            event_id: change.event_id || `ontology:${kind}:${change.canonical_id}:${change.effective_at}`,
+            event_type: `ontology_${kind}`,
+            ontology_version: this.version,
+            canonical_id: change.canonical_id,
+            source_ids: [...new Set(change.source_ids)],
+            aliases: kind === 'rename' ? [...new Set(change.source_ids)] : [],
+            provenance: change.provenance || [],
+            effective_at: change.effective_at,
+            conflict_policy: change.conflict_policy || 'explicit_decision_required'
+        };
+    }
+    interpretHistory(snapshot = {}, { asOf } = {}) {
+        const interpretationTime = asOf || snapshot.as_of;
+        if (!interpretationTime || !Number.isFinite(Date.parse(interpretationTime))) {
+            throw new OntologyError('ONTOLOGY_HISTORY_AS_OF_REQUIRED', 'A valid as_of timestamp is required for historical interpretation');
+        }
+        const events = (snapshot.evolution_events || [])
+            .filter((event) => Date.parse(event.effective_at) <= Date.parse(interpretationTime))
+            .sort((left, right) => Date.parse(left.effective_at) - Date.parse(right.effective_at));
+        const canonicalById = new Map();
+        const provenanceById = new Map();
+        for (const event of events) {
+            for (const sourceId of event.source_ids || []) {
+                if (canonicalById.has(sourceId) && canonicalById.get(sourceId) !== event.canonical_id) {
+                    throw new OntologyError('ONTOLOGY_EVOLUTION_CONFLICT', `Multiple active evolution targets exist for ${sourceId}`, {
+                        source_id: sourceId,
+                        canonical_ids: [canonicalById.get(sourceId), event.canonical_id]
+                    });
+                }
+                canonicalById.set(sourceId, event.canonical_id);
+                provenanceById.set(sourceId, [...(event.provenance || [])]);
+            }
+        }
+        const resolveId = (id) => {
+            const seen = new Set();
+            let current = id;
+            const provenance = [];
+            while (canonicalById.has(current)) {
+                if (seen.has(current)) {
+                    throw new OntologyError('ONTOLOGY_EVOLUTION_CYCLE', `Evolution history contains a cycle from ${id}`, {
+                        source_id: id,
+                        cycle_at: current
+                    });
+                }
+                seen.add(current);
+                provenance.push(...(provenanceById.get(current) || []));
+                current = canonicalById.get(current);
+            }
+            return { canonical_id: current, provenance: [...new Set(provenance)] };
+        };
+        return {
+            ontology_version: this.version,
+            as_of: interpretationTime,
+            applied_event_ids: events.map((event) => event.event_id),
+            entities: (snapshot.entities || []).map((entity) => {
+                const interpretation = resolveId(entity.id);
+                return {
+                    ...structuredClone(entity),
+                    historical_id: entity.id,
+                    canonical_id: interpretation.canonical_id,
+                    evolution_provenance: interpretation.provenance
+                };
+            }),
+            edges: (snapshot.edges || []).map((edge) => {
+                const from = resolveId(edge.from_id);
+                const to = resolveId(edge.to_id);
+                return {
+                    ...structuredClone(edge),
+                    historical_from_id: edge.from_id,
+                    historical_to_id: edge.to_id,
+                    from_id: from.canonical_id,
+                    to_id: to.canonical_id,
+                    evolution_provenance: [...new Set([...from.provenance, ...to.provenance])]
+                };
+            })
+        };
+    }
+}
+const SEMVER_PATTERN = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+const BUMP_RANK = { patch: 1, minor: 2, major: 3 };
+const CARDINALITY_ORDER = ['one_to_one', 'many_to_one', 'one_to_many', 'many_to_many'];
+function parseSemver(version) {
+    const match = SEMVER_PATTERN.exec(String(version || ''));
+    return match ? match.slice(1).map(Number) : null;
+}
+function declaredBump(baseVersion, nextVersion) {
+    const base = parseSemver(baseVersion);
+    const next = parseSemver(nextVersion);
+    if (!base || !next)
+        return null;
+    if (next[0] !== base[0])
+        return next[0] > base[0] && next[1] === 0 && next[2] === 0 ? 'major' : null;
+    if (next[1] !== base[1])
+        return next[1] > base[1] && next[2] === 0 ? 'minor' : null;
+    return next[2] > base[2] ? 'patch' : null;
+}
+function plainObject(value) {
+    return value && typeof value === 'object' && !Array.isArray(value);
+}
+function relationNarrows(before, after) {
+    const lost = (key) => (before[key] || []).some((type) => !(after[key] || []).includes(type));
+    const cardinalityTightened = CARDINALITY_ORDER.includes(before.cardinality)
+        && CARDINALITY_ORDER.includes(after.cardinality)
+        && CARDINALITY_ORDER.indexOf(after.cardinality) < CARDINALITY_ORDER.indexOf(before.cardinality);
+    return lost('from') || lost('to') || cardinalityTightened;
+}
+function applyVocabularyChanges(target, changeSet, kind, classify) {
+    const upsert = changeSet?.upsert ?? {};
+    const remove = changeSet?.remove ?? [];
+    if (!plainObject(upsert) || !Array.isArray(remove)) {
+        throw new OntologyError('ONTOLOGY_PROPOSAL_INVALID', `${kind} changes must be { upsert: object, remove: string[] }`, { http_status: 400 });
+    }
+    for (const id of remove) {
+        if (!Object.hasOwn(target, id)) {
+            throw new OntologyError('ONTOLOGY_PROPOSAL_INVALID', `Cannot remove unknown ${kind}: ${id}`, { http_status: 400 });
+        }
+        delete target[id];
+        classify('major', `remove ${kind} ${id}`);
+    }
+    for (const [id, definition] of Object.entries(upsert)) {
+        if (!plainObject(definition)) {
+            throw new OntologyError('ONTOLOGY_PROPOSAL_INVALID', `${kind} ${id} definition must be an object`, { http_status: 400 });
+        }
+        const previous = target[id];
+        target[id] = structuredClone(definition);
+        if (!previous)
+            classify('minor', `add ${kind} ${id}`);
+        else if (kind === 'relation' && relationNarrows(previous, definition))
+            classify('major', `narrow relation ${id}`);
+        else if (kind === 'relation' && (['from', 'to'].some((key) => (definition[key] || []).length > (previous[key] || []).length))) {
+            classify('minor', `widen relation ${id}`);
+        }
+        else
+            classify('patch', `update ${kind} ${id}`);
+    }
+}
+function applyRuleChanges(rules, changeSet, kind, classify) {
+    const upsert = changeSet?.upsert ?? [];
+    const remove = changeSet?.remove ?? [];
+    if (!Array.isArray(upsert) || !Array.isArray(remove)) {
+        throw new OntologyError('ONTOLOGY_PROPOSAL_INVALID', `${kind} changes must be { upsert: object[], remove: string[] }`, { http_status: 400 });
+    }
+    let next = rules.map((rule) => structuredClone(rule));
+    for (const id of remove) {
+        if (!next.some((rule) => rule.id === id)) {
+            throw new OntologyError('ONTOLOGY_PROPOSAL_INVALID', `Cannot remove unknown ${kind}: ${id}`, { http_status: 400 });
+        }
+        next = next.filter((rule) => rule.id !== id);
+        classify('minor', `remove ${kind} ${id}`);
+    }
+    for (const rule of upsert) {
+        if (!plainObject(rule) || typeof rule.id !== 'string' || !rule.id.trim()) {
+            throw new OntologyError('ONTOLOGY_PROPOSAL_INVALID', `${kind} entries require a string id`, { http_status: 400 });
+        }
+        const index = next.findIndex((candidate) => candidate.id === rule.id);
+        // A new or changed rule can reject existing data, so it is classified
+        // as additive here and the data impact decides whether migration is needed.
+        classify('minor', `${index === -1 ? 'add' : 'update'} ${kind} ${rule.id}`);
+        if (index === -1)
+            next.push(structuredClone(rule));
+        else
+            next[index] = structuredClone(rule);
+    }
+    return next;
+}
+function consistencyViolations(manifest) {
+    const types = new Set(Object.keys(manifest.entity_types));
+    const relations = new Set(Object.keys(manifest.relation_types));
+    const violations = [];
+    for (const [id, definition] of Object.entries(manifest.relation_types)) {
+        for (const side of ['from', 'to']) {
+            for (const type of definition[side] || []) {
+                if (!types.has(type))
+                    violations.push(violation('relation-endpoint-type-registered', `Relation ${id} ${side} references unknown type ${type}`, { relation: id, type }));
+            }
+        }
+        if (definition.inverse && !relations.has(definition.inverse)) {
+            violations.push(violation('relation-inverse-registered', `Relation ${id} inverse ${definition.inverse} is not registered`, { relation: id }));
+        }
+    }
+    for (const rule of [...manifest.constraints, ...manifest.inference_rules]) {
+        if (rule.target && !types.has(rule.target)) {
+            violations.push(violation('rule-target-registered', `Rule ${rule.id} targets unknown type ${rule.target}`, { rule_id_ref: rule.id }));
+        }
+        for (const type of rule.related_types || []) {
+            if (!types.has(type))
+                violations.push(violation('rule-related-type-registered', `Rule ${rule.id} references unknown type ${type}`, { rule_id_ref: rule.id }));
+        }
+        for (const relation of [rule.relation, ...(rule.alternatives || []).map((item) => item.relation)].filter(Boolean)) {
+            if (!relations.has(relation))
+                violations.push(violation('rule-relation-registered', `Rule ${rule.id} references unknown relation ${relation}`, { rule_id_ref: rule.id }));
+        }
+    }
+    const ruleIds = [...manifest.constraints, ...manifest.inference_rules].map((rule) => rule.id);
+    for (const id of ruleIds.filter((ruleId, index) => ruleIds.indexOf(ruleId) !== index)) {
+        violations.push(violation('rule-id-unique', `Rule id ${id} is duplicated`, { rule_id_ref: id }));
+    }
+    return violations;
+}
+/**
+ * Build an immutable Ontology release candidate from a base release and a
+ * change set. The result is a dry-run artifact: it is never written here and
+ * becomes current only through the RACI-authorized publisher (ADR-021).
+ */
+export function buildOntologyReleaseCandidate(baseManifest, proposal = {}) {
+    const nextVersion = String(proposal.next_version || '').trim();
+    const summary = Array.isArray(proposal.summary)
+        ? proposal.summary.filter((line) => typeof line === 'string' && line.trim()).map((line) => line.trim())
+        : [];
+    if (!parseSemver(nextVersion)) {
+        throw new OntologyError('ONTOLOGY_PROPOSAL_INVALID', 'next_version must be a semantic version', { http_status: 400 });
+    }
+    if (!summary.length) {
+        throw new OntologyError('ONTOLOGY_PROPOSAL_INVALID', 'summary must describe the change in at least one line', { http_status: 400 });
+    }
+    const changes = plainObject(proposal.changes) ? proposal.changes : {};
+    const reasons = [];
+    let requiredBump = 'patch';
+    const classify = (bump, reason) => {
+        reasons.push({ bump, reason });
+        if (BUMP_RANK[bump] > BUMP_RANK[requiredBump])
+            requiredBump = bump;
+    };
+    const candidate = structuredClone(baseManifest);
+    applyVocabularyChanges(candidate.entity_types, changes.entity_types, 'type', classify);
+    applyVocabularyChanges(candidate.relation_types, changes.relation_types, 'relation', classify);
+    candidate.constraints = applyRuleChanges(candidate.constraints, changes.constraints, 'constraint', classify);
+    candidate.inference_rules = applyRuleChanges(candidate.inference_rules, changes.inference_rules, 'inference_rule', classify);
+    if (!reasons.length) {
+        throw new OntologyError('ONTOLOGY_PROPOSAL_INVALID', 'The change set does not change the release', { http_status: 400 });
+    }
+    const breaking = requiredBump === 'major';
+    candidate.version = nextVersion;
+    candidate.previous_version = baseManifest.version;
+    candidate.initial_status = 'proposed';
+    candidate.effective_at = typeof proposal.effective_at === 'string' && proposal.effective_at.trim()
+        ? proposal.effective_at.trim()
+        : new Date().toISOString();
+    candidate.compatibility = breaking
+        ? { classification: 'breaking' }
+        : { classification: 'backward_compatible', compatible_from: baseManifest.version };
+    candidate.migration = { required: breaking, plan: typeof proposal.migration_plan === 'string' ? proposal.migration_plan : null };
+    candidate.rollback = { strategy: 'restore_previous_current', target_version: baseManifest.version };
+    candidate.governance = plainObject(proposal.governance) ? structuredClone(proposal.governance) : {};
+    candidate.changes = summary;
+    const declared = declaredBump(baseManifest.version, nextVersion);
+    return {
+        candidate,
+        required_bump: requiredBump,
+        declared_bump: declared,
+        semver_ok: declared !== null && BUMP_RANK[declared] >= BUMP_RANK[requiredBump],
+        change_classification: reasons,
+        consistency_violations: consistencyViolations(candidate)
+    };
+}

package/dist/ontology-publication.d.ts

@@ -0,0 +1,6 @@
+export declare const ONTOLOGY_PUBLICATION_RECEIPT_SCHEMA_VERSION = "1.0.0";
+export declare function sha256(bytes: any): string;
+export declare function canonicalize(value: any): any;
+export declare function canonicalJson(value: any): string;
+export declare function publicationReceiptContractErrors(receipt: any): string[];
+export declare function verifyPublicationReceipt(receipt: any, publicKeyPem: any): boolean;

package/dist/ontology-publication.js

@@ -0,0 +1,44 @@
+// Moved from brainbase-unson server/services/ontology-publication.js without changing behavior.
+// Only type annotations were added; values stay open JSON objects as in the original.
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { createHash, verify } from 'node:crypto';
+export const ONTOLOGY_PUBLICATION_RECEIPT_SCHEMA_VERSION = '1.0.0';
+export function sha256(bytes) {
+    return createHash('sha256').update(bytes).digest('hex');
+}
+export function canonicalize(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalize);
+    if (value && typeof value === 'object') {
+        return Object.fromEntries(Object.keys(value).sort().map((key) => [key, canonicalize(value[key])]));
+    }
+    return value;
+}
+export function canonicalJson(value) {
+    return JSON.stringify(canonicalize(value));
+}
+export function publicationReceiptContractErrors(receipt) {
+    const errors = [];
+    if (receipt?.payload?.schema_version !== ONTOLOGY_PUBLICATION_RECEIPT_SCHEMA_VERSION) {
+        errors.push('schema_version');
+    }
+    if (typeof receipt?.payload?.actor_entity_id !== 'string' || !receipt.payload.actor_entity_id.trim()) {
+        errors.push('actor_entity_id');
+    }
+    const issuedAt = receipt?.payload?.issued_at;
+    if (typeof issuedAt !== 'string'
+        || !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(issuedAt)
+        || Number.isNaN(Date.parse(issuedAt))
+        || new Date(issuedAt).toISOString() !== issuedAt) {
+        errors.push('issued_at');
+    }
+    return errors;
+}
+export function verifyPublicationReceipt(receipt, publicKeyPem) {
+    if (receipt?.signature_algorithm !== 'ed25519' || !receipt?.payload || !receipt?.signature || !receipt?.key_id) {
+        return false;
+    }
+    if (publicationReceiptContractErrors(receipt).length)
+        return false;
+    return verify(null, Buffer.from(canonicalJson(receipt.payload)), publicKeyPem, Buffer.from(receipt.signature, 'base64'));
+}

package/dist/ontology-registry.d.ts

@@ -0,0 +1,32 @@
+import { OntologyKernel } from './ontology-kernel.js';
+export declare class OntologyRegistry {
+    [key: string]: any;
+    constructor({ rootDir, configDir, publicKeyPem }?: {
+        rootDir?: string | undefined;
+        configDir?: string | undefined;
+        publicKeyPem?: string | undefined;
+    });
+    hasCurrent(): boolean;
+    resolve({ version, asOf }?: any): {
+        kernel: OntologyKernel;
+        digest: string;
+        entry: any;
+        publicationVerification: {
+            status: string;
+            key_id: any;
+            signature_algorithm: any;
+            trust_source: string;
+            receipt_digest: any;
+            reason?: undefined;
+        } | {
+            status: string;
+            reason: any;
+            key_id?: undefined;
+            signature_algorithm?: undefined;
+            trust_source?: undefined;
+            receipt_digest?: undefined;
+        };
+    };
+    interpretHistory(snapshot?: any, { version, asOf }?: any): any;
+    unverifiedHistory(snapshot: any, asOf: any, reason: any): any;
+}

package/dist/ontology-registry.js

@@ -0,0 +1,202 @@
+// Moved from brainbase-unson server/services/ontology-registry.js without changing behavior.
+// Only type annotations were added; values stay open JSON objects as in the original.
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { OntologyError, OntologyKernel } from './ontology-kernel.js';
+import { hasCompleteReceiptMetadata, hasReceiptMetadata, loadTrustedPublicKeys, verifyPublishedReceipt } from './ontology-release-trust.js';
+function parseJson(bytes, label) {
+    try {
+        return JSON.parse(bytes.toString('utf8'));
+    }
+    catch (error) {
+        throw new OntologyError('ONTOLOGY_MANIFEST_INVALID', `Invalid JSON in ${label}`, {
+            cause: error.message
+        });
+    }
+}
+function parseTime(value, label) {
+    const timestamp = Date.parse(value);
+    if (!Number.isFinite(timestamp)) {
+        throw new OntologyError('ONTOLOGY_MANIFEST_INVALID', `Invalid ${label}: ${value}`);
+    }
+    return timestamp;
+}
+export class OntologyRegistry {
+    constructor({ rootDir = process.cwd(), configDir = 'config/ontology', publicKeyPem = process.env.ONTOLOGY_PUBLICATION_SIGNING_PUBLIC_KEY || '' } = {}) {
+        this.configDir = path.resolve(rootDir, configDir);
+        this.releasesDir = path.resolve(this.configDir, 'releases');
+        this.publicKeyPem = publicKeyPem;
+        try {
+            this.trustedPublicKeys = loadTrustedPublicKeys(this.configDir);
+        }
+        catch (error) {
+            throw new OntologyError('ONTOLOGY_MANIFEST_INVALID', error.message);
+        }
+        this.index = parseJson(readFileSync(path.join(this.configDir, 'index.json')), 'ontology index');
+        if (!Array.isArray(this.index.releases)) {
+            throw new OntologyError('ONTOLOGY_MANIFEST_INVALID', 'Ontology index releases must be an array');
+        }
+    }
+    hasCurrent() {
+        return typeof this.index.current === 'string' && this.index.current.length > 0;
+    }
+    resolve({ version, asOf } = {}) {
+        let entry;
+        if (version) {
+            entry = this.index.releases.find((release) => release.version === version);
+        }
+        else if (asOf) {
+            const target = parseTime(asOf, 'asOf');
+            entry = this.index.releases
+                .filter((release) => (hasCompleteReceiptMetadata(release) || release.version === this.index.current)
+                && parseTime(release.effective_at, 'release effective_at') <= target)
+                .sort((left, right) => parseTime(right.effective_at, 'release effective_at') - parseTime(left.effective_at, 'release effective_at'))[0];
+        }
+        else {
+            if (!this.hasCurrent()) {
+                throw new OntologyError('ONTOLOGY_CURRENT_UNAVAILABLE', 'No current ontology release has been published');
+            }
+            entry = this.index.releases.find((release) => release.version === this.index.current);
+        }
+        if (!entry) {
+            throw new OntologyError('ONTOLOGY_VERSION_UNKNOWN', `Ontology release was not found: ${version || asOf}`, {
+                version: version || null,
+                as_of: asOf || null
+            });
+        }
+        const releasePath = path.resolve(this.configDir, entry.path);
+        const relativePath = path.relative(this.releasesDir, releasePath);
+        if (relativePath.startsWith('..') || path.isAbsolute(relativePath)) {
+            throw new OntologyError('ONTOLOGY_MANIFEST_INVALID', 'Ontology release path must stay inside releases/', {
+                path: entry.path
+            });
+        }
+        const bytes = readFileSync(releasePath);
+        const digest = createHash('sha256').update(bytes).digest('hex');
+        if (entry.content_digest_algorithm !== 'sha256' || digest !== entry.content_digest) {
+            throw new OntologyError('ONTOLOGY_DIGEST_MISMATCH', `Ontology release digest mismatch: ${entry.version}`, {
+                version: entry.version,
+                expected: entry.content_digest,
+                actual: digest
+            });
+        }
+        const manifest = parseJson(bytes, `ontology release ${entry.version}`);
+        if (manifest.version !== entry.version || manifest.effective_at !== entry.effective_at) {
+            throw new OntologyError('ONTOLOGY_MANIFEST_INVALID', 'Ontology index metadata does not match release manifest', {
+                index_version: entry.version,
+                manifest_version: manifest.version,
+                index_effective_at: entry.effective_at,
+                manifest_effective_at: manifest.effective_at
+            });
+        }
+        const receiptTrust = verifyPublishedReceipt({
+            configDir: this.configDir,
+            entry,
+            manifest,
+            publicKeyPem: this.publicKeyPem,
+            trustedPublicKeys: this.trustedPublicKeys
+        });
+        const claimsPublication = this.index.current === entry.version
+            || entry.status === 'retired'
+            || hasReceiptMetadata(entry);
+        if (claimsPublication && !receiptTrust.verified) {
+            throw new OntologyError('ONTOLOGY_PUBLICATION_UNVERIFIED', `Ontology publication receipt is not trusted: ${entry.version}`, {
+                http_status: 503,
+                version: entry.version,
+                reason: receiptTrust.reason,
+                ...receiptTrust.details
+            });
+        }
+        const effectiveStatus = receiptTrust.verified && this.index.current === entry.version
+            ? 'active'
+            : receiptTrust.verified && entry.status === 'retired'
+                ? 'retired'
+                : receiptTrust.verified
+                    ? 'approved'
+                    : 'proposed';
+        return {
+            kernel: new OntologyKernel({ manifest, status: effectiveStatus }),
+            digest,
+            entry: structuredClone(entry),
+            publicationVerification: receiptTrust.verified
+                ? {
+                    status: 'verified',
+                    key_id: receiptTrust.receipt.key_id,
+                    signature_algorithm: receiptTrust.receipt.signature_algorithm,
+                    trust_source: this.publicKeyPem ? 'environment_override' : 'git_trust_store',
+                    receipt_digest: receiptTrust.receipt_digest
+                }
+                : { status: 'unverified', reason: receiptTrust.reason }
+        };
+    }
+    interpretHistory(snapshot = {}, { version, asOf } = {}) {
+        const recordedVersion = snapshot.ontology_version || null;
+        if (version && recordedVersion && version !== recordedVersion) {
+            throw new OntologyError('ONTOLOGY_HISTORY_VERSION_MISMATCH', 'Requested ontology version does not match the recorded fact version', {
+                requested_version: version,
+                recorded_version: recordedVersion
+            });
+        }
+        let release;
+        try {
+            if (version || recordedVersion) {
+                release = this.resolve({ version: version || recordedVersion });
+            }
+            else if (asOf) {
+                release = this.resolve({ asOf });
+            }
+            else {
+                return this.unverifiedHistory(snapshot, asOf, {
+                    code: 'ONTOLOGY_HISTORY_VERSION_UNRESOLVED',
+                    message: 'Historical interpretation requires a recorded ontology version or resolvable as-of time'
+                });
+            }
+        }
+        catch (error) {
+            if (!version && !recordedVersion && error instanceof OntologyError
+                && ['ONTOLOGY_VERSION_UNKNOWN', 'ONTOLOGY_CURRENT_UNAVAILABLE', 'ONTOLOGY_PUBLICATION_UNVERIFIED'].includes(error.code)) {
+                return this.unverifiedHistory(snapshot, asOf, {
+                    code: error.code,
+                    message: error.message
+                });
+            }
+            throw error;
+        }
+        if (release.kernel.status === 'proposed') {
+            return this.unverifiedHistory(snapshot, asOf, {
+                code: 'ONTOLOGY_PUBLICATION_UNVERIFIED',
+                message: `Ontology release has not been published: ${release.entry.version}`
+            });
+        }
+        const resolvedVersion = release.entry.version;
+        const mismatchedEvents = (snapshot.evolution_events || [])
+            .filter((event) => event.ontology_version && event.ontology_version !== resolvedVersion)
+            .map((event) => event.event_id);
+        if (mismatchedEvents.length) {
+            throw new OntologyError('ONTOLOGY_HISTORY_VERSION_MISMATCH', 'Evolution events must use the recorded fact ontology version', {
+                recorded_version: recordedVersion,
+                resolved_version: resolvedVersion,
+                event_ids: mismatchedEvents
+            });
+        }
+        return {
+            ...release.kernel.interpretHistory(snapshot, { asOf }),
+            recorded_ontology_version: recordedVersion,
+            resolved_ontology_version: resolvedVersion,
+            verification: 'verified'
+        };
+    }
+    unverifiedHistory(snapshot, asOf, reason) {
+        return {
+            ...structuredClone(snapshot),
+            ontology_version: null,
+            recorded_ontology_version: snapshot.ontology_version || null,
+            resolved_ontology_version: null,
+            interpretation_as_of: asOf || null,
+            verification: 'unverified',
+            unverified_reason: reason
+        };
+    }
+}

package/dist/ontology-release-trust.d.ts

@@ -0,0 +1,4 @@
+export declare function hasReceiptMetadata(entry?: any): boolean;
+export declare function hasCompleteReceiptMetadata(entry?: any): boolean;
+export declare function loadTrustedPublicKeys(configDir: any): any;
+export declare function verifyPublishedReceipt({ configDir, entry, manifest, publicKeyPem, trustedPublicKeys }: any): any;

package/dist/ontology-release-trust.js

@@ -0,0 +1,121 @@
+// Moved from brainbase-unson server/services/ontology-release-trust.js without changing behavior.
+// Only type annotations were added; values stay open JSON objects as in the original.
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { canonicalJson, publicationReceiptContractErrors, sha256, verifyPublicationReceipt } from './ontology-publication.js';
+const SHA256_DIGEST = /^[a-f0-9]{64}$/;
+const RECEIPT_FIELDS = ['receipt_path', 'receipt_digest_algorithm', 'receipt_digest'];
+export function hasReceiptMetadata(entry = {}) {
+    return RECEIPT_FIELDS.some((field) => Object.prototype.hasOwnProperty.call(entry, field));
+}
+export function hasCompleteReceiptMetadata(entry = {}) {
+    return typeof entry.receipt_path === 'string'
+        && entry.receipt_path.trim().length > 0
+        && entry.receipt_digest_algorithm === 'sha256'
+        && typeof entry.receipt_digest === 'string'
+        && SHA256_DIGEST.test(entry.receipt_digest);
+}
+function invalid(reason, details = {}) {
+    return { verified: false, reason, details };
+}
+function isContained(parent, child) {
+    const relative = path.relative(parent, child);
+    return relative !== '' && !relative.startsWith('..') && !path.isAbsolute(relative);
+}
+export function loadTrustedPublicKeys(configDir) {
+    const trustStorePath = path.join(configDir, 'trusted-public-keys.json');
+    if (!existsSync(trustStorePath))
+        return {};
+    const trustStore = JSON.parse(readFileSync(trustStorePath, 'utf8'));
+    if (trustStore.schema_version !== '1.0.0'
+        || !trustStore.keys
+        || Array.isArray(trustStore.keys)
+        || typeof trustStore.keys !== 'object') {
+        throw new Error('Ontology trusted public keys must use the 1.0.0 key map schema');
+    }
+    for (const [keyId, key] of Object.entries(trustStore.keys)) {
+        if (!keyId
+            || key?.algorithm !== 'ed25519'
+            || typeof key.public_key_pem !== 'string'
+            || !key.public_key_pem.includes('-----BEGIN PUBLIC KEY-----')) {
+            throw new Error(`Invalid ontology trusted public key: ${keyId || '<empty>'}`);
+        }
+    }
+    return trustStore.keys;
+}
+export function verifyPublishedReceipt({ configDir, entry = {}, manifest, publicKeyPem = '', trustedPublicKeys = {} }) {
+    if (!hasCompleteReceiptMetadata(entry)) {
+        return invalid(hasReceiptMetadata(entry) ? 'incomplete_metadata' : 'missing_metadata');
+    }
+    const publicationsDir = path.resolve(configDir, 'publications');
+    const receiptPath = path.resolve(configDir, entry.receipt_path);
+    if (!isContained(publicationsDir, receiptPath)) {
+        return invalid('path_escape');
+    }
+    let realPublicationsDir;
+    let realReceiptPath;
+    let receiptBytes;
+    try {
+        realPublicationsDir = realpathSync(publicationsDir);
+        realReceiptPath = realpathSync(receiptPath);
+        if (!isContained(realPublicationsDir, realReceiptPath) || !statSync(realReceiptPath).isFile()) {
+            return invalid('path_escape_or_not_file');
+        }
+        receiptBytes = readFileSync(realReceiptPath);
+    }
+    catch {
+        return invalid('receipt_unavailable');
+    }
+    const actualDigest = sha256(receiptBytes);
+    if (actualDigest !== entry.receipt_digest) {
+        return invalid('digest_mismatch', { expected: entry.receipt_digest, actual: actualDigest });
+    }
+    let receipt;
+    try {
+        receipt = JSON.parse(receiptBytes.toString('utf8'));
+    }
+    catch {
+        return invalid('invalid_json');
+    }
+    const contractErrors = publicationReceiptContractErrors(receipt);
+    if (contractErrors.length) {
+        return invalid('contract_mismatch', { fields: contractErrors });
+    }
+    const trustedPublicKeyPem = publicKeyPem || trustedPublicKeys[receipt.key_id]?.public_key_pem || '';
+    if (!trustedPublicKeyPem) {
+        return invalid('public_key_unavailable');
+    }
+    try {
+        if (!verifyPublicationReceipt(receipt, trustedPublicKeyPem)) {
+            return invalid('signature_invalid');
+        }
+    }
+    catch {
+        return invalid('signature_invalid');
+    }
+    const governance = manifest?.governance || {};
+    const expectedBindings = {
+        release_version: entry.version,
+        release_digest: entry.content_digest,
+        source_commit_sha: entry.source_commit_sha,
+        decision_id: governance.decision_id,
+        scope_entity_id: governance.scope_entity_id,
+        proposer_entity_id: governance.proposer_entity_id,
+        decider_entity_id: governance.decider_entity_id,
+        applier_entity_id: governance.applier_entity_id,
+        actor_entity_id: governance.applier_entity_id
+    };
+    const mismatches = Object.entries(expectedBindings)
+        .filter(([key, value]) => !value || receipt.payload?.[key] !== value)
+        .map(([key]) => key);
+    const manifestImpactScope = canonicalJson(manifest?.impact_scope);
+    if (canonicalJson(receipt.payload?.impact_scope) !== manifestImpactScope
+        || (entry.impact_scope && canonicalJson(entry.impact_scope) !== manifestImpactScope)) {
+        mismatches.push('impact_scope');
+    }
+    if (mismatches.length) {
+        return invalid('binding_mismatch', { fields: mismatches });
+    }
+    return { verified: true, receipt, receipt_path: realReceiptPath, receipt_digest: actualDigest };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unson/brainbase-mcp",
-  "version": "0.33.0",
+  "version": "0.34.0",
   "description": "Local-first Brainbase judgment OS that lets supported AI agents reuse a user's approved goals, priorities, decisions, and judgment criteria.",
   "type": "module",
   "license": "MIT",
@@ -195,6 +195,22 @@
       "types": "./dist/memory-scope-policy.d.ts",
       "import": "./dist/memory-scope-policy.js"
     },
+    "./ontology-kernel": {
+      "types": "./dist/ontology-kernel.d.ts",
+      "import": "./dist/ontology-kernel.js"
+    },
+    "./ontology-registry": {
+      "types": "./dist/ontology-registry.d.ts",
+      "import": "./dist/ontology-registry.js"
+    },
+    "./ontology-publication": {
+      "types": "./dist/ontology-publication.d.ts",
+      "import": "./dist/ontology-publication.js"
+    },
+    "./ontology-release-trust": {
+      "types": "./dist/ontology-release-trust.d.ts",
+      "import": "./dist/ontology-release-trust.js"
+    },
     "./canonical-document-writer": {
       "types": "./dist/canonical-document-writer.d.ts",
       "import": "./dist/canonical-document-writer.js"
@@ -463,5 +479,5 @@
   "engines": {
     "node": ">=20"
   },
-  "gitHead": "c3c5a1b3e4d5de936ecebc7ab86346bfdd49faf8"
+  "gitHead": "9275d1ad54f053c85229a44b1c4cba811969cd29"
 }