@unson/brainbase-mcp 0.6.0 → 0.7.0

package/dist/problem-selection.d.ts

@@ -0,0 +1,238 @@
+/**
+ * Problem selection is the comparison boundary between evidence-sidecar
+ * candidates and a future JudgmentProblem.
+ *
+ * The module deliberately does not rank candidates, reserve resources, grant
+ * authority, or mutate an Objective. A caller supplies a versioned DAG
+ * composition evaluator. This module freezes the selection inputs, checks
+ * current candidate access and exact digests, validates the evaluator result,
+ * and stores an immutable SelectionRecord.
+ */
+import type { FoundationAcl, FoundationRevision, FoundationScope } from './ontology-foundation.js';
+import type { ProblemCandidateRecord, ProblemCandidateStore, ProblemCandidateStoreContext } from './problem-candidates.js';
+import { type JudgmentDAGCompositionDefinition, type JudgmentDAGCompositionRunRequest, type JudgmentDAGProblemSnapshotReference } from './judgment-dag-composition.js';
+export declare const PROBLEM_SELECTION_CONTRACT_VERSION: "problem-selection.v1";
+export declare const PROBLEM_SELECTION_RECORD_VERSION: "problem-selection-record.v1";
+export declare const PROBLEM_SELECTION_DIRECTORY: "problem-selections";
+export type ProblemSelectionAction = 'start' | 'continue' | 'observe' | 'hold' | 'stop';
+export type ProblemSelectionStatus = 'selected' | 'human_review_required';
+export type ProblemSelectionAssessmentStatus = 'eligible' | 'incomparable' | 'unavailable' | 'unknown';
+export interface ProblemSelectionKnown<T> {
+    readonly status: 'known';
+    readonly value: T;
+}
+export interface ProblemSelectionUnknown {
+    readonly status: 'unknown';
+    readonly reason: string;
+}
+/** Unknown is preserved; it is never converted to zero or an empty value. */
+export type ProblemSelectionField<T> = ProblemSelectionKnown<T> | ProblemSelectionUnknown;
+export interface ProblemSelectionCostTerms {
+    readonly switching: ProblemSelectionField<number>;
+    readonly opportunity: ProblemSelectionField<number>;
+    readonly exploration: ProblemSelectionField<number>;
+}
+export interface ProblemSelectionExplorationLimit {
+    readonly maxCandidates: number;
+    readonly maxExplorationCost: ProblemSelectionField<number>;
+}
+export interface ProblemSelectionFoundationReference extends FoundationRevision {
+    readonly digest: string;
+}
+export interface ProblemSelectionConditionalPreference {
+    readonly id: string;
+    readonly condition: string;
+    readonly preference: string;
+}
+export interface ProblemSelectionDelegatedJudgment {
+    readonly id: string;
+    readonly question: string;
+    readonly ownerId: string;
+}
+/** Conditions fixed by the selection meta Problem before comparison begins. */
+export interface ProblemSelectionFixedConditions {
+    readonly objectiveRefs: readonly ProblemSelectionFoundationReference[];
+    readonly constraintRefs: readonly ProblemSelectionFoundationReference[];
+    readonly conditionalPreferences: readonly ProblemSelectionConditionalPreference[];
+    readonly delegatedJudgments: readonly ProblemSelectionDelegatedJudgment[];
+    readonly costs: ProblemSelectionCostTerms;
+    readonly explorationLimit: ProblemSelectionExplorationLimit;
+    readonly evaluatedAt: string;
+}
+export interface ProblemSelectionCandidateReference {
+    readonly candidateId: string;
+    /** Exact candidate payload identity, excluding mutable review status. */
+    readonly payloadDigest: string;
+    readonly ownerScope: FoundationScope;
+}
+export interface ProblemSelectionObjectiveConflict {
+    readonly objectiveIds: readonly string[];
+    readonly reason: string;
+}
+export interface ProblemSelectionCandidateInput {
+    readonly reference: ProblemSelectionCandidateReference;
+    readonly record: ProblemCandidateRecord;
+}
+export interface ProblemSelectionCandidateAssessment {
+    readonly reference: ProblemSelectionCandidateReference;
+    readonly status: ProblemSelectionAssessmentStatus;
+    readonly action?: ProblemSelectionAction;
+    readonly rationale: string;
+    readonly ownerId?: string;
+    readonly conditions: readonly string[];
+    readonly reviewAt?: string;
+    readonly costs: ProblemSelectionCostTerms;
+    readonly unknowns: readonly ProblemSelectionUnknown[];
+    readonly objectiveConflicts: readonly ProblemSelectionObjectiveConflict[];
+}
+/** Result returned by the versioned DAG composition evaluator. */
+export interface ProblemSelectionEvaluationResult {
+    readonly status: ProblemSelectionStatus;
+    readonly selectedCandidateId?: string;
+    readonly action?: ProblemSelectionAction;
+    readonly reason: string;
+    readonly ownerId?: string;
+    readonly conditions?: readonly string[];
+    readonly reviewAt?: string;
+    readonly assessments?: readonly ProblemSelectionCandidateAssessment[];
+    readonly unknowns?: readonly ProblemSelectionUnknown[];
+    readonly objectiveConflicts?: readonly ProblemSelectionObjectiveConflict[];
+}
+export interface ProblemSelectionEvaluationRequest {
+    readonly selectionId: string;
+    readonly selectionProblem: JudgmentDAGProblemSnapshotReference;
+    readonly composition: JudgmentDAGCompositionDefinition;
+    readonly candidates: readonly ProblemSelectionCandidateInput[];
+    readonly fixedConditions: ProblemSelectionFixedConditions;
+}
+export interface ProblemSelectionEvaluationPort {
+    /** The port may call executeJudgmentDAGComposition; it owns DAG adapters. */
+    readonly evaluate: (request: ProblemSelectionEvaluationRequest) => ProblemSelectionEvaluationResult | Promise<ProblemSelectionEvaluationResult>;
+}
+export interface ProblemSelectionProblemCreationRequest {
+    readonly status: 'required';
+    readonly candidate: ProblemSelectionCandidateReference;
+    readonly action: 'start' | 'continue';
+    readonly requiredConditions: readonly string[];
+    /** The future Problem must complete its own exact snapshot before execution. */
+    readonly completeSnapshotRequired: true;
+}
+export interface ProblemSelectionDecision {
+    readonly status: ProblemSelectionStatus;
+    readonly candidate?: ProblemSelectionCandidateReference;
+    readonly action?: ProblemSelectionAction;
+    readonly reason: string;
+    readonly ownerId?: string;
+    readonly conditions: readonly string[];
+    readonly reviewAt?: string;
+}
+/** Immutable output of one meta-Problem selection run. */
+export interface ProblemSelectionRecord {
+    readonly recordVersion: typeof PROBLEM_SELECTION_RECORD_VERSION;
+    readonly contractVersion: typeof PROBLEM_SELECTION_CONTRACT_VERSION;
+    readonly selectionId: string;
+    readonly selectionProblem: JudgmentDAGProblemSnapshotReference;
+    readonly selectionComposition: JudgmentDAGCompositionDefinition;
+    readonly ownerScope: FoundationScope;
+    readonly readPolicy: FoundationAcl;
+    readonly fixedConditions: ProblemSelectionFixedConditions;
+    readonly candidateRefs: readonly ProblemSelectionCandidateReference[];
+    readonly assessments: readonly ProblemSelectionCandidateAssessment[];
+    /** Conflicts are retained at record level even when the evaluator did not attach them to an assessment. */
+    readonly objectiveConflicts: readonly ProblemSelectionObjectiveConflict[];
+    /** All unresolved inputs are retained instead of being collapsed into a status string. */
+    readonly unknowns: readonly ProblemSelectionUnknown[];
+    readonly status: ProblemSelectionStatus;
+    readonly decision: ProblemSelectionDecision;
+    readonly problemCreationRequest?: ProblemSelectionProblemCreationRequest;
+    /** Selection never grants an execution or resource authority. */
+    readonly executionPermission: 'none';
+    readonly resourceAuthority: 'none';
+    /** Selection never changes the Objective definition. */
+    readonly objectiveChange: 'none';
+    readonly createdAt: string;
+}
+export type ProblemSelectionRecordId = `sha256:${string}`;
+export interface ProblemSelectionRequest {
+    readonly selectionId: string;
+    readonly selectionProblem: JudgmentDAGProblemSnapshotReference;
+    readonly selectionComposition: JudgmentDAGCompositionDefinition;
+    readonly ownerScope: FoundationScope;
+    readonly readPolicy: FoundationAcl;
+    readonly fixedConditions: ProblemSelectionFixedConditions;
+    readonly candidateRefs: readonly ProblemSelectionCandidateReference[];
+    readonly candidateStore: ProblemCandidateStore;
+    readonly candidateContext: ProblemCandidateStoreContext;
+    readonly evaluator: ProblemSelectionEvaluationPort;
+    readonly createdAt?: string;
+}
+export interface ProblemSelectionAccessContext {
+    readonly principal: string;
+    readonly scope?: FoundationScope;
+}
+export type ProblemSelectionAccessOperation = 'save' | 'read';
+export interface ProblemSelectionAccessProvider {
+    authorize(input: {
+        readonly operation: ProblemSelectionAccessOperation;
+        readonly context: ProblemSelectionAccessContext;
+        readonly record: ProblemSelectionRecord;
+    }): boolean | void | Promise<boolean | void>;
+}
+export interface SaveProblemSelectionRecordRequest {
+    readonly root: string;
+    readonly record: ProblemSelectionRecord;
+    readonly access?: ProblemSelectionAccessContext;
+    readonly accessProvider?: ProblemSelectionAccessProvider;
+}
+export interface LoadProblemSelectionRecordRequest {
+    readonly root: string;
+    readonly recordId: string;
+    readonly access: ProblemSelectionAccessContext;
+    readonly accessProvider?: ProblemSelectionAccessProvider;
+}
+export interface ProblemSelectionRecordReceipt {
+    readonly recordId: ProblemSelectionRecordId;
+    readonly recordVersion: typeof PROBLEM_SELECTION_RECORD_VERSION;
+    readonly selectionId: string;
+    readonly status: 'created' | 'existing';
+}
+export interface ProblemSelectionRecordStore {
+    save(record: ProblemSelectionRecord, access: ProblemSelectionAccessContext): Promise<ProblemSelectionRecordReceipt>;
+    read(recordId: string, access: ProblemSelectionAccessContext): Promise<ProblemSelectionRecord>;
+}
+export type ProblemSelectionErrorCode = 'invalid_request' | 'candidate_unavailable' | 'candidate_scope_violation' | 'candidate_revision_conflict' | 'comparison_unavailable' | 'access_denied' | 'not_found' | 'invalid_record' | 'integrity_mismatch' | 'storage_io_error';
+export declare class ProblemSelectionError extends Error {
+    readonly code: ProblemSelectionErrorCode;
+    constructor(code: ProblemSelectionErrorCode, message: string);
+}
+/**
+ * Resolve candidates and create one immutable selection record. Candidate
+ * bodies are used only inside the evaluator call and are never copied into
+ * the record; the record keeps exact candidate references and digests.
+ */
+export declare function createProblemSelection(request: ProblemSelectionRequest): Promise<ProblemSelectionRecord>;
+/** Alias for callers that name the operation as a run. */
+export declare const runProblemSelection: typeof createProblemSelection;
+/** Alias for callers that name the operation as a selection. */
+export declare const selectProblem: typeof createProblemSelection;
+/**
+ * Adapter helper for a composition whose designated child returns the
+ * selection contract in its conclusion. The meta Problem remains the exact
+ * snapshot supplied to the composition request; a selected candidate still
+ * requires a later Problem creation request.
+ */
+export declare function evaluateProblemSelectionWithComposition(input: {
+    readonly compositionRequest: JudgmentDAGCompositionRunRequest;
+    readonly resultInvocationId?: string;
+}): Promise<ProblemSelectionEvaluationResult>;
+export declare function computeProblemSelectionRecordId(record: ProblemSelectionRecord): ProblemSelectionRecordId;
+export declare function saveProblemSelectionRecord(request: SaveProblemSelectionRecordRequest): Promise<ProblemSelectionRecordReceipt>;
+export declare function loadProblemSelectionRecord(request: LoadProblemSelectionRecordRequest): Promise<ProblemSelectionRecord>;
+export declare function createProblemSelectionRecordStore(options: {
+    readonly root: string;
+    readonly accessProvider?: ProblemSelectionAccessProvider;
+}): ProblemSelectionRecordStore;
+/** Compatibility aliases for consumers that use SelectionRecord terminology. */
+export declare const saveSelectionRecord: typeof saveProblemSelectionRecord;
+export declare const loadSelectionRecord: typeof loadProblemSelectionRecord;
+export declare const computeSelectionRecordId: typeof computeProblemSelectionRecordId;