@unson/brainbase-mcp 0.5.0 → 0.7.0

package/dist/judgment-dag-composition.d.ts

@@ -0,0 +1,224 @@
+/**
+ * Contract for composing versioned Judgment DAGs into one parent judgment.
+ *
+ * This module intentionally has no persistence or host adapter dependency.
+ * It validates the composition, freezes the evaluation boundary, and records
+ * the result of each child without changing the J0 single-DAG run artifact.
+ */
+import { type JudgmentDAGScope } from './judgment-dag-core.js';
+import type { JudgmentDAGRunArtifactId } from './judgment-dag-artifact-store.js';
+import type { JudgmentDAGJSONValue } from './judgment-dag-runner.js';
+export declare const JUDGMENT_DAG_COMPOSITION_VERSION: "judgment-dag-composition.v1";
+export declare const JUDGMENT_DAG_COMPOSITION_STATUSES: readonly ["completed", "failed", "held"];
+export type JudgmentDAGCompositionStatus = (typeof JUDGMENT_DAG_COMPOSITION_STATUSES)[number];
+export declare const JUDGMENT_DAG_SUBDAG_STATUSES: readonly ["completed", "failed", "held"];
+export type JudgmentDAGSubDAGStatus = (typeof JUDGMENT_DAG_SUBDAG_STATUSES)[number];
+export interface JudgmentDAGVersionReference {
+    readonly id: string;
+    readonly version: string;
+}
+/**
+ * The immutable JudgmentProblem snapshot selected for this composition.
+ *
+ * The snapshot itself remains owned by Story05's store. Composition records
+ * carry this exact locator so a later read cannot silently follow a newer
+ * problem revision.
+ */
+export type JudgmentDAGProblemSnapshotId = `sha256:${string}`;
+export interface JudgmentDAGProblemSnapshotReference {
+    readonly snapshot_id: JudgmentDAGProblemSnapshotId;
+    readonly problem_id: string;
+    readonly revision: string;
+}
+export interface JudgmentDAGProblemSnapshotReadRequest {
+    readonly mode: 'read';
+    /** Composition execution must revalidate canonical references at read time. */
+    readonly reference_resolution: 'current';
+    readonly reference: JudgmentDAGProblemSnapshotReference;
+}
+/**
+ * A Story05 adapter used by a new composition run must return a snapshot
+ * validated with `reference_resolution: 'current'` and a canonical reference
+ * provider. The coordinator checks the locator and identity fields; the
+ * adapter owns the actual store lookup and current authorization/existence
+ * check. `historical` resolution is for audit/replay only and cannot satisfy
+ * this execution reader contract.
+ */
+export interface JudgmentDAGProblemSnapshotReadResult {
+    readonly status: 'resolved';
+    /** Historical snapshot replay is an audit path, not an execution input. */
+    readonly reference_resolution: 'current';
+    readonly reference: JudgmentDAGProblemSnapshotReference;
+    readonly snapshot: JudgmentDAGJSONValue;
+}
+export interface JudgmentDAGProblemSnapshotReader {
+    readonly read: (request: JudgmentDAGProblemSnapshotReadRequest) => JudgmentDAGProblemSnapshotReadResult | Promise<JudgmentDAGProblemSnapshotReadResult>;
+}
+export interface JudgmentDAGVersionResolution {
+    readonly dag: JudgmentDAGVersionReference;
+    readonly input_contract: string;
+    readonly output_contract: string;
+}
+export interface JudgmentDAGVersionResolverRequest {
+    readonly role: 'parent' | 'child';
+    readonly invocation_id?: string;
+    readonly dag: JudgmentDAGVersionReference;
+}
+export interface JudgmentDAGVersionResolver {
+    readonly resolve: (request: JudgmentDAGVersionResolverRequest) => JudgmentDAGVersionResolution | Promise<JudgmentDAGVersionResolution>;
+}
+export interface JudgmentDAGInputOutputContractValidationRequest {
+    readonly role: 'child';
+    readonly invocation_id: string;
+    readonly dag: JudgmentDAGVersionReference;
+    readonly input_contract: string;
+    readonly output_contract: string;
+}
+export interface JudgmentDAGInputOutputContractValidator {
+    readonly validate: (request: JudgmentDAGInputOutputContractValidationRequest) => void | Promise<void>;
+}
+export interface JudgmentDAGRunArtifactReadRequest {
+    readonly artifact_id: JudgmentDAGRunArtifactId;
+    readonly expected_run_id: string;
+    readonly expected_dag: JudgmentDAGVersionReference;
+}
+/**
+ * The adapter should delegate to loadJudgmentDAGRunArtifact (or an equivalent
+ * integrity-checking reader). The coordinator only checks identity fields
+ * after that readback; it never treats an artifact id as proof by itself.
+ */
+export interface JudgmentDAGRunArtifactReader {
+    readonly read: (request: JudgmentDAGRunArtifactReadRequest) => unknown | Promise<unknown>;
+}
+export interface JudgmentDAGSubDAGDefinition {
+    readonly invocation_id: string;
+    readonly dag: JudgmentDAGVersionReference;
+    readonly question: string;
+    readonly input_contract: string;
+    readonly output_contract: string;
+    readonly required_capabilities: readonly string[];
+    readonly depends_on: readonly string[];
+}
+export interface JudgmentDAGCompositionDefinition {
+    readonly composition_id: string;
+    readonly composition_version: string;
+    readonly scope: JudgmentDAGScope;
+    readonly parent_dag: JudgmentDAGVersionReference;
+    readonly children: readonly JudgmentDAGSubDAGDefinition[];
+}
+export interface JudgmentDAGDelegationScope {
+    readonly scope: JudgmentDAGScope;
+    readonly capabilities: readonly string[];
+}
+export interface JudgmentDAGRunReference {
+    readonly run_id: string;
+    readonly dag: JudgmentDAGVersionReference;
+    readonly artifact_id?: JudgmentDAGRunArtifactId;
+}
+export interface JudgmentDAGEvidenceReference {
+    readonly kind: string;
+    readonly id: string;
+    readonly revision?: string;
+}
+export interface JudgmentDAGSubDAGResult {
+    readonly status: JudgmentDAGSubDAGStatus;
+    readonly input_contract: string;
+    readonly output_contract: string;
+    readonly run_reference: JudgmentDAGRunReference | null;
+    readonly conclusion: JudgmentDAGJSONValue;
+    readonly evidence: readonly JudgmentDAGEvidenceReference[];
+    readonly applicability: JudgmentDAGJSONValue;
+    readonly uncertainty: JudgmentDAGJSONValue;
+    readonly reason?: string;
+}
+export interface JudgmentDAGCompositionChildRunSource {
+    readonly invocation_id: string;
+    readonly result: JudgmentDAGSubDAGResult;
+}
+export interface JudgmentDAGSubDAGRunRecord {
+    readonly invocation_id: string;
+    readonly dag: JudgmentDAGVersionReference;
+    readonly question: string;
+    readonly input_contract: string;
+    readonly output_contract: string;
+    readonly input: JudgmentDAGJSONValue;
+    readonly problem_snapshot: JudgmentDAGProblemSnapshotReference;
+    readonly fixed_conditions: JudgmentDAGJSONValue;
+    readonly delegation: JudgmentDAGDelegationScope;
+    readonly dependency_invocation_ids: readonly string[];
+    readonly dependency_results: readonly JudgmentDAGCompositionChildRunSource[];
+    readonly result: JudgmentDAGSubDAGResult;
+}
+export interface JudgmentDAGCompositionRunRecord {
+    readonly run_id: string;
+    readonly composition: JudgmentDAGVersionReference;
+    readonly parent_dag: JudgmentDAGVersionReference;
+    readonly question: string;
+    readonly input: JudgmentDAGJSONValue;
+    readonly problem_snapshot: JudgmentDAGProblemSnapshotReference;
+    readonly fixed_conditions: JudgmentDAGJSONValue;
+    readonly delegation: JudgmentDAGDelegationScope;
+    readonly execution_order: readonly string[];
+    readonly status: JudgmentDAGCompositionStatus;
+    readonly children: readonly JudgmentDAGSubDAGRunRecord[];
+}
+export interface JudgmentDAGSubDAGExecutionRequest {
+    readonly mode: 'evaluation';
+    readonly parent_run_id: string;
+    readonly composition: JudgmentDAGVersionReference;
+    readonly invocation_id: string;
+    readonly dag: JudgmentDAGVersionReference;
+    readonly question: string;
+    readonly input: JudgmentDAGJSONValue;
+    readonly problem_snapshot: JudgmentDAGProblemSnapshotReference;
+    readonly fixed_conditions: JudgmentDAGJSONValue;
+    readonly delegation: JudgmentDAGDelegationScope;
+    readonly dependency_results: readonly JudgmentDAGCompositionChildRunSource[];
+}
+export interface JudgmentDAGSubDAGEvaluationPort {
+    readonly execute: (request: JudgmentDAGSubDAGExecutionRequest) => JudgmentDAGSubDAGResult | Promise<JudgmentDAGSubDAGResult>;
+}
+/** Alias kept for callers that model the boundary as an execution port. */
+export type JudgmentDAGSubDAGExecutionPort = JudgmentDAGSubDAGEvaluationPort;
+export interface JudgmentDAGCompositionRunRequest {
+    readonly run_id: string;
+    readonly composition: JudgmentDAGCompositionDefinition;
+    readonly question: string;
+    readonly input: JudgmentDAGJSONValue;
+    readonly problem_snapshot: JudgmentDAGProblemSnapshotReference;
+    readonly fixed_conditions: JudgmentDAGJSONValue;
+    readonly delegation: JudgmentDAGDelegationScope;
+    readonly snapshot_reader: JudgmentDAGProblemSnapshotReader;
+    readonly dag_resolver: JudgmentDAGVersionResolver;
+    readonly contract_validator: JudgmentDAGInputOutputContractValidator;
+    readonly artifact_reader?: JudgmentDAGRunArtifactReader;
+    readonly port: JudgmentDAGSubDAGEvaluationPort;
+}
+export type JudgmentDAGCompositionErrorCode = 'invalid_contract' | 'duplicate_invocation' | 'missing_dependency' | 'cycle' | 'scope_mismatch' | 'capability_violation' | 'dag_mismatch' | 'dag_unavailable' | 'contract_mismatch' | 'snapshot_unavailable' | 'artifact_readback_failed' | 'invalid_child_result' | 'executor_failed';
+export interface JudgmentDAGCompositionErrorDetails {
+    readonly invocation_id?: string;
+    readonly dependency_id?: string;
+    readonly cycle?: readonly string[];
+}
+export declare class JudgmentDAGCompositionError extends Error {
+    readonly code: JudgmentDAGCompositionErrorCode;
+    readonly invocation_id?: string;
+    readonly dependency_id?: string;
+    readonly cycle?: readonly string[];
+    constructor(code: JudgmentDAGCompositionErrorCode, message: string, details?: JudgmentDAGCompositionErrorDetails);
+}
+export interface JudgmentDAGCompositionValidationResult {
+    readonly valid: true;
+    readonly composition_id: string;
+    readonly composition_version: string;
+    readonly execution_order: readonly string[];
+}
+export declare function validateJudgmentDAGComposition(value: unknown): JudgmentDAGCompositionValidationResult;
+export declare function assertValidJudgmentDAGComposition(value: unknown): asserts value is JudgmentDAGCompositionDefinition;
+export declare function createJudgmentDAGCompositionDefinition(value: unknown): JudgmentDAGCompositionDefinition;
+/**
+ * Execute only the explicitly declared evaluation port for each child.
+ * Resource reservation, deploys, external sends, and arbitrary host-code
+ * isolation remain outside this OSS boundary.
+ */
+export declare function executeJudgmentDAGComposition(request: JudgmentDAGCompositionRunRequest): Promise<JudgmentDAGCompositionRunRecord>;