@unson/brainbase-mcp 0.5.0 → 0.7.0

package/dist/company-os-evaluation.d.ts

@@ -0,0 +1,193 @@
+import type { FoundationAcl, FoundationEvaluationDescriptor, FoundationScope, ObjectiveCriterion } from './ontology-foundation.js';
+import { type FoundationRef } from './foundation-catalog.js';
+import type { FoundationRevisionStore, FoundationStoreContext } from './foundation-store.js';
+import type { FoundationCatalogRecord } from './types.js';
+import { type JudgmentProblemReferenceProvider, type JudgmentProblemSnapshotAccessContext, type JudgmentProblemSnapshotAccessProvider } from './judgment-problem-snapshot.js';
+/**
+ * Evaluation is an evidence record over a pinned Problem.  It does not own
+ * Objective or Variable definitions and it does not close an OutcomeCase.
+ */
+export declare const COMPANY_OS_EVALUATION_CONTRACT_VERSION: "0.1.0";
+export declare const COMPANY_OS_EVALUATION_RECORD_CATALOG_VERSION: 1;
+export declare const COMPANY_OS_EVALUATION_SIDECAR: "evidence/company-os-evaluation.json";
+export type EvaluationMeasurementStatus = 'observed' | 'missing' | 'not_arrived';
+export type EvaluationJudgmentValidity = 'valid' | 'invalid' | 'indeterminate';
+export type EvaluationResultStatus = 'achieved' | 'not_achieved' | 'indeterminate';
+export type PredictionComparisonStatus = 'matched' | 'missed' | 'indeterminate';
+export type EvaluationScalar = string | number | boolean;
+export interface EvaluationMeasurementDescriptor extends Omit<FoundationEvaluationDescriptor, 'variableRef'> {
+}
+export interface EvaluationConversionProvenance {
+    /** Stable evidence or transformation identifier, not a free-form assertion. */
+    readonly id: string;
+    readonly description: string;
+}
+export interface EvaluationMeasurementConversion {
+    /** The input measurement's exact source definition. */
+    readonly sourceRef: FoundationRef;
+    /** The exact criterion definition used after the conversion. */
+    readonly targetRef: FoundationRef;
+    readonly provenance: EvaluationConversionProvenance;
+}
+export interface EvaluationMeasurementInput {
+    readonly variableRef: FoundationRef;
+    /** The descriptor describes the effective (possibly converted) definition. */
+    readonly descriptor: EvaluationMeasurementDescriptor;
+    readonly status: EvaluationMeasurementStatus;
+    readonly value?: EvaluationScalar;
+    readonly recordedAt: string;
+    readonly evidenceRef?: string;
+    readonly conversion?: EvaluationMeasurementConversion;
+}
+export interface EvaluationMeasurement extends EvaluationMeasurementInput {
+    readonly effectiveVariableRef: FoundationRef;
+}
+export interface JudgmentValidityInput {
+    readonly status: EvaluationJudgmentValidity;
+    readonly basis: string;
+    readonly evidenceRefs?: readonly string[];
+}
+export interface JudgmentValidity extends JudgmentValidityInput {
+}
+/**
+ * A port owned by OSS and implemented by an OutcomeCase provider.  The port
+ * deliberately has a read operation only: closure, approval, and case
+ * mutation remain outside this repository.
+ */
+export interface OutcomeCaseReference {
+    readonly id: string;
+    readonly revision?: string;
+    readonly digest?: string;
+}
+export interface OutcomeCaseCanonicalReference {
+    readonly id: string;
+    readonly revision: string;
+    readonly digest: string;
+}
+export type OutcomeCaseOwnerUnknownReason = 'not_recorded' | 'legacy_untyped' | 'source_unavailable';
+export interface OutcomeCaseEntityReference {
+    readonly id: string;
+    readonly type: string;
+    readonly revision?: string;
+    readonly digest?: string;
+}
+export type OutcomeCaseOwnerReference = {
+    readonly status: 'typed';
+    readonly ref: OutcomeCaseEntityReference;
+} | {
+    readonly status: 'unknown';
+    readonly reason: OutcomeCaseOwnerUnknownReason;
+};
+export type OutcomeCaseConditionValue = string | number | boolean | null | readonly OutcomeCaseConditionValue[] | {
+    readonly [key: string]: OutcomeCaseConditionValue;
+};
+export type OutcomeCaseConditions = Readonly<Record<string, OutcomeCaseConditionValue>>;
+/**
+ * Trusted source-owned metadata returned with an OutcomeCase read.  The
+ * adapter must use this projection when creating a receipt link; caller
+ * supplied receipt state, owners, or conditions are lookup input only.
+ */
+export interface OutcomeCaseCanonicalSource {
+    readonly state: string;
+    readonly owner_refs: readonly OutcomeCaseOwnerReference[];
+    readonly conditions?: OutcomeCaseConditions;
+}
+export interface OutcomeCaseRead {
+    readonly reference: OutcomeCaseCanonicalReference;
+    /** Current source-owned identity/state projection, checked at read time. */
+    readonly source: OutcomeCaseCanonicalSource;
+    /** Current ACL, evaluated at read time. */
+    readonly acl: FoundationAcl;
+    readonly scope: FoundationScope;
+}
+export interface EvaluationAccessContext extends JudgmentProblemSnapshotAccessContext {
+    readonly scope?: FoundationScope;
+}
+export interface OutcomeCasePort {
+    read(reference: OutcomeCaseReference, actor: EvaluationAccessContext): Promise<OutcomeCaseRead>;
+}
+/**
+ * Exact definition read used by evaluation.  A caller cannot supply an
+ * Objective or criterion body as an evaluation input; this port resolves the
+ * requested revision and verifies its digest from the canonical store.
+ */
+export interface FoundationDefinitionLoadPort {
+    readExact(reference: FoundationRef, context: FoundationStoreContext): Promise<FoundationCatalogRecord | null>;
+}
+export declare function createFoundationDefinitionLoadPort(store: Pick<FoundationRevisionStore, 'read'>): FoundationDefinitionLoadPort;
+export interface CriterionEvaluation {
+    readonly criterionIndex: number;
+    readonly variableRef: FoundationRef;
+    readonly operator: ObjectiveCriterion['operator'];
+    readonly target?: string | number | boolean;
+    readonly status: EvaluationResultStatus;
+    readonly reason: string;
+}
+export interface PredictionComparison {
+    readonly criterionIndex: number;
+    readonly variableRef: FoundationRef;
+    readonly status: PredictionComparisonStatus;
+    readonly reason: string;
+    readonly predictionStatus?: EvaluationMeasurementStatus;
+    readonly actualStatus?: EvaluationMeasurementStatus;
+    readonly predictionValue?: EvaluationScalar;
+    readonly actualValue?: EvaluationScalar;
+}
+export interface CompanyOsEvaluationRecord {
+    readonly version: typeof COMPANY_OS_EVALUATION_RECORD_CATALOG_VERSION;
+    readonly id: string;
+    readonly snapshot: {
+        readonly snapshotId: string;
+        readonly problemId: string;
+        readonly revision: string;
+        readonly digest: string;
+    };
+    readonly objectiveRef: FoundationRef;
+    readonly outcomeCaseRef: OutcomeCaseCanonicalReference;
+    readonly predictions: readonly EvaluationMeasurement[];
+    readonly actuals: readonly EvaluationMeasurement[];
+    readonly criteria: readonly CriterionEvaluation[];
+    readonly predictionComparisons: readonly PredictionComparison[];
+    readonly achievement: EvaluationResultStatus;
+    readonly judgmentAtTimeValidity: JudgmentValidity;
+    readonly evaluatedAt: string;
+}
+export interface EvaluateCompanyOsProblemRequest {
+    readonly id: string;
+    readonly snapshot: {
+        readonly root: string;
+        readonly snapshotId?: string;
+        readonly problemId?: string;
+        readonly revision?: string;
+        readonly accessProvider?: JudgmentProblemSnapshotAccessProvider;
+        readonly referenceProvider: JudgmentProblemReferenceProvider;
+    };
+    readonly access: EvaluationAccessContext;
+    readonly outcomeCase: OutcomeCaseReference;
+    readonly predictions: readonly EvaluationMeasurementInput[];
+    readonly actuals: readonly EvaluationMeasurementInput[];
+    readonly judgmentAtTimeValidity: JudgmentValidityInput;
+    readonly evaluatedAt: string;
+}
+export interface CompanyOsEvaluationStore {
+    evaluate(request: EvaluateCompanyOsProblemRequest): Promise<CompanyOsEvaluationRecord>;
+    read(id: string, access: EvaluationAccessContext): Promise<CompanyOsEvaluationRecord | null>;
+    list(access: EvaluationAccessContext): Promise<readonly CompanyOsEvaluationRecord[]>;
+}
+export interface CompanyOsEvaluationStoreOptions {
+    readonly dataDir: string;
+    readonly foundation: FoundationDefinitionLoadPort;
+    readonly outcomeCase: OutcomeCasePort;
+    /**
+     * Resolver used when a stored evaluation is read back.  The evaluation
+     * record only stores a snapshot reference, so reads must resolve that exact
+     * snapshot again under the provider's current ACL/digest checks.
+     */
+    readonly snapshotReferenceProvider: JudgmentProblemReferenceProvider;
+}
+export type CompanyOsEvaluationErrorCode = 'invalid_input' | 'not_found' | 'authorization_denied' | 'scope_violation' | 'integrity_mismatch' | 'incompatible_measurement' | 'revision_conflict' | 'unsupported_graph' | 'corrupt_record' | 'readback_mismatch';
+export declare class CompanyOsEvaluationError extends Error {
+    readonly code: CompanyOsEvaluationErrorCode;
+    constructor(code: CompanyOsEvaluationErrorCode, message: string);
+}
+export declare function createCompanyOsEvaluationStore(options: CompanyOsEvaluationStoreOptions): CompanyOsEvaluationStore;