harness-apd

use harness_apd;

pub mod driver;

pub mod inference;

pub mod local_planes;

pub mod patch;

pub mod spec;

pub use driver::{run, DriverError, RunArtifacts};

pub use spec::{ApdRunResult, ApdTaskSpec, SpecError, SPEC_SCHEMA};

#[derive(Debug)]
pub struct RunArtifacts {
/// The runner-facing result (`apd-harness-result/1`).

pub result: ApdRunResult,
/// The full HarnessSpec run record (`harness.run.v1`).

pub record: RunRecord
}

#[derive(Debug, thiserror::Error)]
pub enum DriverError {
    /// The spec could not be read or parsed.
    #[error("spec: {0}")]
    Spec(String),
    /// A plane could not be constructed.
    #[error("plane binding: {0}")]
    Binding(String),
    /// Admission denied the harness (denied runs never execute, §4.4).
    #[error("admission denied: {0}")]
    Admission(String),
    /// The run itself faulted outside the terminal-outcome contract.
    #[error("runtime: {0}")]
    Runtime(String),
    /// Writing an artifact failed.
    #[error("artifact write: {0}")]
    Artifact(String),
}

pub async fn run(spec: &ApdTaskSpec, events_path: PathBuf) -> Result<RunArtifacts, DriverError>;

pub struct OpenAiInferencePlane {

}

pub fn new(
        base_url: &str,
        api_key: Option<String>,
        model: impl Into<String>,
        temperature: Option<f64>,
        max_output_tokens: Option<u64>,
        price: SpecPrice,
        tools: Vec<String>,
    ) -> Result<Self, PlaneError>;

pub mod driver;

pub mod inference;

pub mod local_planes;

pub mod patch;

pub mod spec;

pub use driver::{run, DriverError, RunArtifacts};

pub use spec::{ApdRunResult, ApdTaskSpec, SpecError, SPEC_SCHEMA};

pub struct LocalIdentityPlane;

pub struct LocalPolicyPlane;

pub struct LocalContextPlane;

#[derive(Default)]
pub struct LocalMemoryPlane {

}

#[derive(Default)]
pub struct LocalEconomicsPlane {

}

pub struct LocalTelemetryPlane {

}

pub fn new(path: impl Into<PathBuf>) -> Self;

pub struct LocalSubstratePlane;

pub struct LocalToolsPlane {

}

pub fn new(root: impl Into<PathBuf>) -> Result<Self, PlaneError>;

pub struct LocalVerificationPlane {

}

pub fn new(root: impl Into<PathBuf>) -> Self;

pub fn extract_patch(completion: &str) -> Option<String>;

pub const SPEC_SCHEMA: &str;

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ApdTaskSpec {
/// Schema tag; must be [`SPEC_SCHEMA`].

pub schema: String,
/// Corpus task id (e.g. `json5-cve-2022-46175`).

pub task_id: String,
/// The task prompt from the corpus.

pub prompt: String,
/// The task's declared context files, in declared order.

pub context_files: Vec<SpecContextFile>,
/// Absolute path of the pristine workspace checkout (tools plane root).

pub workspace_dir: String,
/// Operator-supplied model identifier (never defaulted — live-catalog

/// discipline, L1F-16).

pub model: String,
/// OpenAI-compatible base URL of the model route (e.g. a Foundry

/// route or provider gateway).

pub base_url: String,
/// Environment variable holding the route's API key. The key value is

/// read from the process environment at run time; it is never written

/// to the spec, the result, or the run record.

#[serde(default)]
pub api_key_env: Option<String>,
/// Sampling temperature. `null` omits the parameter entirely — some

/// current flagship models accept only their default temperature and

/// reject an explicit value.

#[serde(default)]
pub temperature: Option<f64>,
/// Output-token cap per model call.

#[serde(default)]
pub max_output_tokens: Option<u64>,
/// ReAct loop step cap (`[loop].max_steps`).

#[serde(default = "default_max_steps")]
pub max_steps: u64,
/// Context frame cap (`[context].frame_budget_tokens`).

#[serde(default = "default_frame_budget_tokens")]
pub frame_budget_tokens: u64,
/// USD budget cap (`[inference].budget_usd`).

pub budget_usd: f64,
/// Token budget cap (`[inference].budget_tokens`).

pub budget_tokens: u64,
/// The model's current price entry (the runner's fail-loud price

/// table resolved it before any spend).

pub price: SpecPrice,
/// Enable the MARC `reasoning_task` decomposition section when the

/// MAP spine is configured. Ignored when it is not.

#[serde(default = "default_marc_decomposition")]
pub marc_decomposition: bool
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct SpecContextFile {
/// Repo-relative path.

pub path: String,
/// Current content at the pinned ref.

pub content: String
}

#[derive(Debug, Clone, Copy, PartialEq, Serialize, Deserialize)]
pub struct SpecPrice {
/// USD per 1M input tokens.

pub input_per_mtok: f64,
/// USD per 1M output tokens.

pub output_per_mtok: f64
}

pub fn from_json(source: &str) -> Result<Self, SpecError>;

#[derive(Debug, thiserror::Error)]
pub enum SpecError {
    /// The document is not valid JSON for the spec shape.
    #[error("malformed spec: {0}")]
    Malformed(serde_json::Error),
    /// The schema tag is not supported by this driver.
    #[error("unsupported spec schema {0:?} (expected {SPEC_SCHEMA:?})")]
    UnsupportedSchema(String),
    /// A required field is missing or invalid.
    #[error("missing or invalid field: {0}")]
    MissingField(&'static str),
}

#[derive(Debug, Clone, PartialEq, Serialize)]
pub struct ApdRunResult {
/// Schema tag.

pub schema: String,
/// Corpus task id.

pub task_id: String,
/// The harness run id minted at admission.

pub run_id: String,
/// The model route used.

pub model: String,
/// Terminal outcome kind (`verified` | `failed` | `halted`).

pub outcome: String,
/// The unified diff extracted from the run's final answer, when the

/// loop produced one. `null` is honest: no patch exists.

pub patch: Option<String>,
/// Real metered usage from the run record's usage totals.

pub usage: ApdUsage,
/// MAP spine dispatches made by the run's planes (empty when the

/// spine is unconfigured — local planes served the run).

pub map_spine: ApdMapSpine,
/// Terminal error detail (halt reason / verification failure), when

/// the run did not verify.

pub error: Option<String>
}

#[derive(Debug, Clone, Copy, PartialEq, Serialize)]
pub struct ApdUsage {
/// Total input tokens across all model calls.

pub prompt_tokens: u64,
/// Total output tokens across all model calls.

pub completion_tokens: u64,
/// Total USD charged against the budget ledger.

pub cost_usd: f64
}

#[derive(Debug, Clone, PartialEq, Serialize)]
pub struct ApdMapSpine {
/// Whether `MAP_BASE_URL` configured a spine for this run.

pub configured: bool,
/// Every dispatch the run's planes made, in order.

pub dispatches: Vec<harness_runtime::SpineDispatchRecord>
}