@unson/brainbase-mcp 0.6.0 → 0.7.0

package/dist/company-os-learning-adoption.d.ts

@@ -0,0 +1,288 @@
+import type { CompanyOsEvaluationRecord, EvaluationAccessContext, CompanyOsEvaluationStore } from './company-os-evaluation.js';
+import type { FoundationDefinition, FoundationScope, ModelDefinition, FoundationAcl } from './ontology-foundation.js';
+import type { FoundationStoreContext } from './foundation-store.js';
+import type { PersonalOs } from './types.js';
+/**
+ * Learning adoption is an append-only ledger over the existing canonical
+ * aggregate.  It does not promote a candidate to truth and it does not
+ * mutate a running judgment.  Foundation target revisions are appended to
+ * Graph v2; the ledger stores only the references and decision evidence.
+ */
+export declare const COMPANY_OS_LEARNING_ADOPTION_CONTRACT_VERSION: "0.1.0";
+export declare const COMPANY_OS_LEARNING_ADOPTION_RECORD_CATALOG_VERSION: 1;
+/**
+ * Stable identity for a canonical adoption record when it crosses a
+ * knowledge boundary. This is deliberately separate from the catalog
+ * version and from the adopted foundation target revision.
+ */
+export declare const COMPANY_OS_LEARNING_ADOPTION_LOCATOR_SCHEMA: "company-os-learning-adoption-record.v1";
+export declare const COMPANY_OS_LEARNING_ADOPTION_SIDECAR: "evidence/company-os-learning-adoption.json";
+export type LearningTargetKind = 'world_model' | 'judgment_method' | 'execution_method' | 'objective';
+export type LearningFindingKind = 'measurement_error' | 'execution_difference' | 'external_change' | 'other';
+export type LearningValidationConclusion = 'supported' | 'partially_supported' | 'indeterminate' | 'rejected';
+export type LearningModelDisposition = 'unchanged' | 'revise' | 'refuted' | 'indeterminate';
+export interface LearningTargetReference {
+    readonly kind: LearningTargetKind;
+    readonly id: string;
+    readonly revision: string;
+    readonly digest: string;
+    /** Foundation targets identify the canonical Graph type explicitly. */
+    readonly foundationType?: FoundationDefinition['type'];
+}
+export interface LearningTargetVersion {
+    readonly target: LearningTargetReference;
+    readonly reference: LearningTargetReference;
+    readonly definition: unknown;
+    readonly acl: FoundationAcl;
+    readonly scope: FoundationScope;
+}
+export interface LearningCandidateReference {
+    readonly id: string;
+    readonly digest: string;
+}
+/**
+ * Stable locator for a canonical adoption record. `contentDigest` is the
+ * digest of the complete adoption record; it is not a catalog version and it
+ * is not the revision of the target adopted by that record.
+ */
+export interface LearningAdoptionLocator {
+    readonly id: string;
+    readonly schema: typeof COMPANY_OS_LEARNING_ADOPTION_LOCATOR_SCHEMA;
+    readonly contentDigest: string;
+}
+export interface LearningEvaluationReference {
+    readonly id: string;
+    readonly digest: string;
+}
+export interface LearningCandidateInput {
+    readonly id: string;
+    readonly sourceEvaluationRef: LearningEvaluationReference;
+    readonly target: LearningTargetReference;
+    /** Opaque proposed change. Target providers validate and materialize it. */
+    readonly proposedChange: unknown;
+    readonly grounds: readonly string[];
+    readonly counterexamples: readonly string[];
+    readonly uncertainty: readonly string[];
+    readonly applicability: FoundationScope;
+    readonly createdAt: string;
+}
+export interface LearningCandidate extends LearningCandidateInput {
+    readonly version: typeof COMPANY_OS_LEARNING_ADOPTION_RECORD_CATALOG_VERSION;
+    readonly digest: string;
+}
+export interface LearningFinding {
+    readonly kind: LearningFindingKind;
+    readonly description: string;
+    readonly evidenceRefs: readonly string[];
+}
+export interface LearningValidationInput {
+    readonly id: string;
+    readonly candidateRef: LearningCandidateReference;
+    readonly findings: readonly LearningFinding[];
+    readonly conclusion: LearningValidationConclusion;
+    readonly modelDisposition: LearningModelDisposition;
+    readonly basis: string;
+    readonly validatedAt: string;
+}
+export interface LearningValidation extends LearningValidationInput {
+    readonly version: typeof COMPANY_OS_LEARNING_ADOPTION_RECORD_CATALOG_VERSION;
+    readonly sourceEvaluationRef: LearningEvaluationReference;
+    readonly digest: string;
+}
+export interface LearningAuthorizationRequest {
+    readonly candidate: LearningCandidate;
+    readonly validation: LearningValidation;
+    readonly target: LearningTargetVersion;
+    readonly access: LearningAccessContext;
+}
+export interface LearningAuthorizationDecision {
+    readonly status: 'authorized' | 'denied';
+    readonly authorizationId: string;
+    readonly authorizedBy: string;
+    readonly reason?: string;
+    readonly decidedAt: string;
+}
+export interface LearningAdoptionAuthorizationPort {
+    authorize(request: LearningAuthorizationRequest): Promise<LearningAuthorizationDecision> | LearningAuthorizationDecision;
+}
+/**
+ * A host adapter can expose this port to a knowledge reader. Implementations
+ * must re-read the canonical adoption record before returning its locator.
+ */
+export interface LearningAdoptionLocatorReadPort {
+    read(input: {
+        readonly locator: LearningAdoptionLocator;
+        readonly access: LearningAccessContext;
+    }): Promise<LearningAdoptionLocator | null>;
+}
+export interface LearningTargetRevisionPreparationInput {
+    readonly candidate: LearningCandidate;
+    readonly validation: LearningValidation;
+    readonly current: LearningTargetVersion;
+}
+export interface LearningTargetRevisionPreparation {
+    readonly target: LearningTargetReference;
+    readonly reference: LearningTargetReference;
+    readonly definition: unknown;
+    readonly acl: FoundationAcl;
+    readonly scope: FoundationScope;
+}
+/**
+ * Target providers perform external reads and authorization before the SSOT
+ * lock.  `commitRevision` is deliberately synchronous and pure: it receives
+ * the aggregate held by the lock and must fail closed when the expected
+ * revision no longer matches.  It must not call a network or re-enter SSOT.
+ */
+export interface LearningTargetPort {
+    readCurrent(reference: LearningTargetReference, access: LearningAccessContext): Promise<LearningTargetVersion | null>;
+    read(reference: LearningTargetReference, access: LearningAccessContext): Promise<LearningTargetVersion | null>;
+    prepareRevision(input: LearningTargetRevisionPreparationInput): Promise<LearningTargetRevisionPreparation> | LearningTargetRevisionPreparation;
+    commitRevision(input: {
+        readonly currentAggregate: PersonalOs;
+        readonly expectedCurrent: LearningTargetVersion;
+        readonly prepared: LearningTargetRevisionPreparation;
+    }): {
+        readonly nextAggregate: PersonalOs;
+        readonly adopted: LearningTargetVersion;
+    };
+}
+export interface LearningAccessContext extends FoundationStoreContext {
+    readonly principal: string;
+}
+export interface LearningEvaluationPort {
+    read(id: string, access: EvaluationAccessContext): Promise<CompanyOsEvaluationRecord | null>;
+}
+/**
+ * The execution host owns run receipts.  The adoption ledger stores only the
+ * exact receipt reference; it never accepts a caller-supplied receipt body.
+ * A host must re-read the receipt with its current authorization boundary and
+ * return the exact target version that the run actually used.
+ */
+export interface LearningRunReceiptReference {
+    readonly id: string;
+    readonly digest: string;
+}
+export interface LearningRunReceipt {
+    readonly id: string;
+    readonly runId: string;
+    readonly runPhase: 'actual';
+    readonly adoptedTarget: LearningTargetReference;
+    readonly digest: string;
+}
+export interface LearningRunReceiptPort {
+    read(reference: LearningRunReceiptReference, access: LearningAccessContext): Promise<LearningRunReceipt | null>;
+}
+export interface LearningAdoptionStoreOptions {
+    readonly dataDir: string;
+    readonly evaluation: LearningEvaluationPort;
+    readonly target: LearningTargetPort;
+    /** Optional for planned-only consumers; required to record/read actual use. */
+    readonly runReceipt?: LearningRunReceiptPort;
+    readonly authorization?: LearningAdoptionAuthorizationPort;
+    readonly now?: () => string;
+}
+export interface CreateLearningCandidateRequest extends LearningCandidateInput {
+    readonly access: LearningAccessContext;
+}
+export interface CreateLearningValidationRequest extends LearningValidationInput {
+    readonly access: LearningAccessContext;
+}
+export interface AdoptLearningCandidateRequest {
+    readonly id: string;
+    readonly idempotencyKey: string;
+    readonly candidateRef: LearningCandidateReference;
+    readonly validationRef: LearningCandidateReference;
+    readonly access: LearningAccessContext;
+}
+export interface LearningAdoptionRecord {
+    readonly version: typeof COMPANY_OS_LEARNING_ADOPTION_RECORD_CATALOG_VERSION;
+    readonly id: string;
+    readonly idempotencyKey: string;
+    readonly requestDigest: string;
+    readonly candidateRef: LearningCandidateReference;
+    readonly validationRef: LearningCandidateReference;
+    readonly previousTarget: LearningTargetReference;
+    readonly adoptedTarget: LearningTargetReference;
+    readonly authorization: LearningAuthorizationDecision;
+    /** Adoption does not change the epistemic state of the target. */
+    readonly targetValidationState?: ModelDefinition['validationState'];
+    readonly adoptedAt: string;
+    readonly digest: string;
+}
+/**
+ * Project a canonical adoption record into the locator contract used by
+ * knowledge adapters.  The full record digest is the content identity; the
+ * catalog version and adopted target revision have different meanings.
+ */
+export declare function createLearningAdoptionLocator(record: Pick<LearningAdoptionRecord, 'id' | 'digest'>): LearningAdoptionLocator;
+export interface RecordLearningRunUseRequest {
+    readonly id: string;
+    readonly runId: string;
+    readonly adoptionId: string;
+    /** planned selects a version; actual proves the running host used it. */
+    readonly runPhase: 'planned' | 'actual';
+    /** Required for actual; it is read from the host-owned receipt port. */
+    readonly receiptRef?: LearningRunReceiptReference;
+    readonly access: LearningAccessContext;
+}
+export interface LearningRunUseRecord {
+    readonly version: typeof COMPANY_OS_LEARNING_ADOPTION_RECORD_CATALOG_VERSION;
+    readonly id: string;
+    readonly runId: string;
+    readonly adoptionId: string;
+    readonly requestDigest: string;
+    readonly adoptedTarget: LearningTargetReference;
+    readonly runPhase: 'planned' | 'actual';
+    readonly receiptRef?: LearningRunReceiptReference;
+    readonly usedAt: string;
+    readonly digest: string;
+}
+export interface CompanyOsLearningAdoptionStore {
+    createCandidate(request: CreateLearningCandidateRequest): Promise<LearningCandidate>;
+    readCandidate(id: string, access: LearningAccessContext): Promise<LearningCandidate | null>;
+    createValidation(request: CreateLearningValidationRequest): Promise<LearningValidation>;
+    readValidation(id: string, access: LearningAccessContext): Promise<LearningValidation | null>;
+    adopt(request: AdoptLearningCandidateRequest): Promise<LearningAdoptionRecord>;
+    readAdoption(id: string, access: LearningAccessContext): Promise<LearningAdoptionRecord | null>;
+    /** Read the stable locator after the canonical record and its target are revalidated. */
+    readAdoptionLocator(id: string, access: LearningAccessContext): Promise<LearningAdoptionLocator | null>;
+    /** Resolve an exact locator through the current canonical ACL/target read boundary. */
+    readAdoptionByLocator(locator: LearningAdoptionLocator, access: LearningAccessContext): Promise<LearningAdoptionRecord | null>;
+    recordRunUse(request: RecordLearningRunUseRequest): Promise<LearningRunUseRecord>;
+    readRunUse(id: string, access: LearningAccessContext): Promise<LearningRunUseRecord | null>;
+}
+export type CompanyOsLearningAdoptionErrorCode = 'invalid_input' | 'not_found' | 'authorization_denied' | 'scope_violation' | 'revision_conflict' | 'integrity_mismatch' | 'invalid_validation' | 'unsupported_target' | 'corrupt_record' | 'readback_mismatch';
+export declare class CompanyOsLearningAdoptionError extends Error {
+    readonly code: CompanyOsLearningAdoptionErrorCode;
+    constructor(code: CompanyOsLearningAdoptionErrorCode, message: string);
+}
+export declare function createCompanyOsLearningEvaluationPort(store: Pick<CompanyOsEvaluationStore, 'read'>): LearningEvaluationPort;
+export declare function createLocalLearningAdoptionAuthorizationPort(): LearningAdoptionAuthorizationPort;
+export declare function createCompanyOsLearningAdoptionStore(options: LearningAdoptionStoreOptions): CompanyOsLearningAdoptionStore;
+/**
+ * Expose only the exact adoption locator after the store has performed its
+ * current ACL, candidate, validation, and canonical target checks.
+ */
+export declare function createLearningAdoptionLocatorReadPort(store: Pick<CompanyOsLearningAdoptionStore, 'readAdoptionByLocator'>): LearningAdoptionLocatorReadPort;
+/**
+ * Foundation-backed target provider.  It is the concrete OSS path for
+ * Objective and world-model revisions.  Judgment/execution method registries
+ * belong to a consuming provider and are intentionally unsupported here.
+ */
+export declare function createFoundationLearningTargetPort(options: {
+    readonly foundationStore: {
+        read(reference: {
+            id: string;
+            type: FoundationDefinition['type'];
+            revision: string;
+        }, context: FoundationStoreContext): Promise<{
+            definition: FoundationDefinition;
+            digest: string;
+        } | null>;
+        readLatest(type: FoundationDefinition['type'], id: string, context: FoundationStoreContext): Promise<{
+            definition: FoundationDefinition;
+            digest: string;
+        } | null>;
+    };
+}): LearningTargetPort;
+export declare function digestEvaluationRecord(record: CompanyOsEvaluationRecord): string;