harn-stdlib 0.10.70

/** Closed request and result contracts for the portable hypothesis workflow. */
import { VersionedContract, versioned_contract } from "std/artifacts/typed"
import { AssignmentPlan } from "std/eval/experiment/assignment"
import { HypothesisPlan } from "std/eval/hypothesis/contracts"
import {
  HypothesisLedgerAppendReceipt,
  HypothesisLedgerSnapshotRead,
} from "std/eval/hypothesis/ledger_contracts"
import { HypothesisReport } from "std/eval/hypothesis/report"
import { schema_contract } from "std/schema"

pub type HypothesisWorkflowAction = "start" \
  | "advance" \
  | "pause" \
  | "resume" \
  | "inspect" \
  | "stand_down"

pub type HypothesisWorkflowStart = {kind: "start", plan: HypothesisPlan, run_id: string}

pub type HypothesisWorkflowResume = {kind: "resume", hypothesis_id: string}

pub type HypothesisWorkflowAdvance = {
  kind: "advance",
  hypothesis_id: string,
  blocking_values: dict<string, string>,
}

pub type HypothesisWorkflowPause = {kind: "pause", hypothesis_id: string, reason: string}

pub type HypothesisWorkflowInspect = {kind: "inspect", hypothesis_id: string}

pub type HypothesisWorkflowStandDown = {kind: "stand_down", hypothesis_id: string, reason: string}

pub type HypothesisWorkflowRequest = HypothesisWorkflowStart \
  | HypothesisWorkflowAdvance \
  | HypothesisWorkflowPause \
  | HypothesisWorkflowResume \
  | HypothesisWorkflowInspect \
  | HypothesisWorkflowStandDown

pub type HypothesisWorkflowState = "unregistered" \
  | "registered" \
  | "scheduled" \
  | "running" \
  | "paused" \
  | "completed" \
  | "cancelled" \
  | "failed" \
  | "invalid"

pub type HypothesisWorkflowNotActionableReason = "not_started" \
  | "observe_only" \
  | "already_started" \
  | "already_terminal" \
  | "not_running" \
  | "not_paused"

pub type HypothesisNativeApprovalResult = {decision: "approved" | "denied", rationale: string}

pub type HypothesisNativeOperationRequest = {
  schema: "harn.hypothesis.operation_request.v1",
  action: "start" | "advance" | "pause" | "resume" | "stand_down",
  operation_receipt_id: string,
  hypothesis_id: string,
  plan_fingerprint: string,
  run_id: string,
  state: HypothesisWorkflowState,
  plan?: HypothesisPlan,
  reason?: string,
  assignment_plan?: AssignmentPlan,
}

pub type HypothesisNativeArmObservation = {
  arm_id: string,
  metrics: dict<string, float>,
  spend_delta_usd: float,
  compute_delta_ms: int,
  token_delta: int,
  api_call_delta: int,
  telemetry_status: "observed" | "unavailable" | "not_observable",
  capability_degradations: list<string>,
}

pub type HypothesisNativeOperationAccepted = {
  schema: "harn.hypothesis.operation_result.v1",
  kind: "accepted",
  action: "start" | "advance" | "pause" | "resume" | "stand_down",
  operation_receipt_id: string,
  occurred_at: string,
  actor: string,
  source: string,
  approval?: HypothesisNativeApprovalResult,
  assignment_plan_id?: string,
  observed_blocking_values?: dict<string, string>,
  arm_observations?: list<HypothesisNativeArmObservation>,
  elapsed_ms?: int,
}

pub type HypothesisNativeOperationDenied = {
  schema: "harn.hypothesis.operation_result.v1",
  kind: "denied",
  action: "start" | "advance" | "pause" | "resume" | "stand_down",
  operation_receipt_id: string,
  code: string,
  message: string,
}

pub type HypothesisNativeOperationResult = HypothesisNativeOperationAccepted \
  | HypothesisNativeOperationDenied

/**
 * Return the versioned boundary contract for native hypothesis operation results.
 *
 * @effects: []
 * @errors: []
 * @api_stability: experimental
 */
pub fn hypothesis_native_operation_result_contract() -> VersionedContract<
  HypothesisNativeOperationResult
> {
  return versioned_contract(
    "harn.hypothesis.operation_result",
    1,
    schema_contract(schema_of(HypothesisNativeOperationResult), []),
  )
}

pub type HypothesisWorkflowInspection = {
  schema: "harn.hypothesis.workflow_result.v1",
  kind: "inspection",
  action: "inspect",
  hypothesis_id: string,
  state: HypothesisWorkflowState,
  ledger: HypothesisLedgerSnapshotRead,
  report: HypothesisReport,
}

pub type HypothesisWorkflowAdapterUnavailable = {
  schema: "harn.hypothesis.workflow_result.v1",
  kind: "adapter_unavailable",
  action: "start" | "advance" | "pause" | "resume" | "stand_down",
  hypothesis_id: string,
  state: HypothesisWorkflowState,
  required_adapter: "hypothesis.operation",
  message: string,
  ledger: HypothesisLedgerSnapshotRead,
  report: HypothesisReport,
}

pub type HypothesisWorkflowApplied = {
  schema: "harn.hypothesis.workflow_result.v1",
  kind: "applied",
  action: "start" | "advance" | "pause" | "resume" | "stand_down",
  hypothesis_id: string,
  state: HypothesisWorkflowState,
  operation_receipt_id: string,
  appends: list<HypothesisLedgerAppendReceipt>,
  ledger: HypothesisLedgerSnapshotRead,
  report: HypothesisReport,
}

pub type HypothesisWorkflowDenied = {
  schema: "harn.hypothesis.workflow_result.v1",
  kind: "denied",
  action: "start" | "advance" | "pause" | "resume" | "stand_down",
  hypothesis_id: string,
  state: HypothesisWorkflowState,
  operation_receipt_id: string,
  code: string,
  message: string,
  ledger: HypothesisLedgerSnapshotRead,
  report: HypothesisReport,
}

pub type HypothesisWorkflowNotActionable = {
  schema: "harn.hypothesis.workflow_result.v1",
  kind: "not_actionable",
  action: "start" | "advance" | "pause" | "resume" | "stand_down",
  hypothesis_id: string,
  state: HypothesisWorkflowState,
  reason: HypothesisWorkflowNotActionableReason,
  ledger: HypothesisLedgerSnapshotRead,
  report: HypothesisReport,
}

pub type HypothesisWorkflowResult = HypothesisWorkflowInspection \
  | HypothesisWorkflowAdapterUnavailable \
  | HypothesisWorkflowApplied \
  | HypothesisWorkflowDenied \
  | HypothesisWorkflowNotActionable