@unson/brainbase-mcp 0.6.0 → 0.8.0

package/dist/world-model.d.ts

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