buildlang 1.15.0

BuildLang (buildc): an effects-oriented compiler with a verified C path, shader output, experimental backends, opt-in linear types, and re-checkable accountability + scientific-runtime receipts
Documentation
// ===============================================================================
// BUILDLANG COMPILER - FLAGSHIP-ACTION <-> BDF BRIDGE
// ===============================================================================
// SPDX-License-Identifier: AGPL-3.0-only
// Copyright (c) 2022-2026 Zain Dana Harper.
// ===============================================================================

//! A lossless bridge between the ecosystem interop envelope
//! `project-telos.flagship-action/v1` and a [`BdfMessage`].
//!
//! The flagships (gather, index, forum, crucible, telos) interoperate through a
//! plain-JSON `project-telos.flagship-action/v1` envelope. This bridge proves
//! BDF can carry that real interop format with nothing lost: a flagship-action
//! JSON round-trips through a [`BdfMessage`] and back, semantically identical,
//! through both the JSON and the canonical-binary forms.
//!
//! ## Mapping (flagship-action field -> BdfMessage)
//!
//! | flagship-action/v1                 | BdfMessage                              |
//! |------------------------------------|-----------------------------------------|
//! | `tool`, `tool_version`             | `produced_by.{tool, tool_version}`      |
//! | `next_actions[]` (projected)       | `next[]` (`tool`, `action`, `reason`)   |
//! | `receipts[].sha256`                | `receipt.derived_from[]` (lineage)      |
//! | *(carrier exercises no effect)*    | `effects = []`                          |
//! | **the whole envelope, verbatim**   | `payload` (a `BdfValue`), under         |
//! |                                    | `payload_schema = flagship-action/v1`   |
//!
//! The full envelope - `command`, `status`, `inputs`, `outputs`, the complete
//! `receipts` (with `kind` / `ref` / `method` / `derived_from`), `native`, the
//! complete `next_actions` (with `inputs` / `priority`), `diagnostics`, and any
//! unknown or extra fields - is carried verbatim in `payload`, so reconstruction
//! drops nothing. The projected `produced_by` / `next` / `receipt` fields are a
//! typed convenience view over that payload, not the source of truth.
//!
//! ## Verdict is not admission
//!
//! `status` (MATCH / DRIFT / UNVERIFIABLE) is a *native verdict*. It is carried
//! verbatim inside `payload` and is **never** collapsed into BDF-level
//! admission: BDF effects and the receipt record what was produced; a separate
//! gate, and Crucible's verdict, remain independent axes. The bridge claims no
//! effects (`effects = []`) and never reinterprets the verdict.

use crate::bdf::json::{bdf_to_plain_json, bdf_to_plain_json_pretty, plain_json_to_bdf};
use crate::bdf::{BdfError, BdfMessage, BdfResult, BdfValue, NextAction, ProducedBy};

/// Schema id of the ecosystem flagship-action interop envelope (v1).
pub const FLAGSHIP_ACTION_SCHEMA: &str = "project-telos.flagship-action/v1";

/// Convert a `project-telos.flagship-action/v1` JSON envelope into a
/// [`BdfMessage`], carrying the entire envelope losslessly in the payload.
///
/// Fails closed if the JSON is malformed, is not an object, or does not carry
/// the flagship-action/v1 schema string.
pub fn flagship_action_to_bdf(json: &str) -> BdfResult<BdfMessage> {
    let value = plain_json_to_bdf(json)?;
    let map = match &value {
        BdfValue::Map(m) => m,
        _ => {
            return Err(BdfError::Json(
                "flagship-action envelope must be a JSON object".to_string(),
            ))
        }
    };

    // Fail closed on a wrong / missing schema. The verdict is NOT collapsed into
    // admission; only the carrier format is validated here.
    match map.get("schema") {
        Some(BdfValue::Str(s)) if s == FLAGSHIP_ACTION_SCHEMA => {}
        Some(BdfValue::Str(other)) => {
            return Err(BdfError::UnsupportedSchema {
                found: other.clone(),
                expected: FLAGSHIP_ACTION_SCHEMA,
            })
        }
        _ => {
            return Err(BdfError::UnsupportedSchema {
                found: "<missing>".to_string(),
                expected: FLAGSHIP_ACTION_SCHEMA,
            })
        }
    }

    let produced_by = ProducedBy {
        tool: string_field(map, "tool"),
        tool_version: string_field(map, "tool_version"),
    };
    let next = project_next_actions(map);
    let derived_from = project_receipt_lineage(map);

    // The whole envelope is the payload, verbatim. `BdfMessage::new` stamps the
    // BDF-level receipt: a sha256 over the canonical-binary payload, with the
    // flagship receipts' digests recorded as `derived_from` lineage. The
    // flagship's own receipts remain inside the payload untouched.
    Ok(BdfMessage::new(
        produced_by,
        Vec::new(), // the carrier bridge exercises no capability effect
        FLAGSHIP_ACTION_SCHEMA,
        value.clone(),
        derived_from,
        next,
    ))
}

/// Reconstruct the `project-telos.flagship-action/v1` JSON envelope from a
/// [`BdfMessage`] produced by [`flagship_action_to_bdf`], byte/structure
/// identical to the original (compact JSON).
///
/// Fails closed if the message does not carry the flagship-action payload schema
/// or if the payload is not a flagship-action object.
pub fn bdf_to_flagship_action(message: &BdfMessage) -> BdfResult<String> {
    let value = validated_payload(message)?;
    bdf_to_plain_json(value)
}

/// As [`bdf_to_flagship_action`], but pretty-printed.
pub fn bdf_to_flagship_action_pretty(message: &BdfMessage) -> BdfResult<String> {
    let value = validated_payload(message)?;
    bdf_to_plain_json_pretty(value)
}

/// Validate that a message carries a flagship-action payload and return it.
fn validated_payload(message: &BdfMessage) -> BdfResult<&BdfValue> {
    if message.payload_schema != FLAGSHIP_ACTION_SCHEMA {
        return Err(BdfError::UnsupportedSchema {
            found: message.payload_schema.clone(),
            expected: FLAGSHIP_ACTION_SCHEMA,
        });
    }
    match &message.payload {
        BdfValue::Map(m) => match m.get("schema") {
            Some(BdfValue::Str(s)) if s == FLAGSHIP_ACTION_SCHEMA => Ok(&message.payload),
            Some(BdfValue::Str(other)) => Err(BdfError::UnsupportedSchema {
                found: other.clone(),
                expected: FLAGSHIP_ACTION_SCHEMA,
            }),
            _ => Err(BdfError::UnsupportedSchema {
                found: "<missing>".to_string(),
                expected: FLAGSHIP_ACTION_SCHEMA,
            }),
        },
        _ => Err(BdfError::Json(
            "flagship-action payload must be a JSON object".to_string(),
        )),
    }
}

/// Read a string field from an envelope map, defaulting to empty if absent or
/// not a string. (The projected fields are a convenience view; the verbatim
/// copy in the payload is the source of truth, so a missing optional here never
/// loses data.)
fn string_field(map: &indexmap::IndexMap<String, BdfValue>, key: &str) -> String {
    match map.get(key) {
        Some(BdfValue::Str(s)) => s.clone(),
        _ => String::new(),
    }
}

/// Project `next_actions[]` into the typed [`NextAction`] view (`tool`,
/// `action`, `reason`). The flagship `action` field is named `action`; its
/// extra fields (`inputs`, `priority`) stay in the payload.
fn project_next_actions(map: &indexmap::IndexMap<String, BdfValue>) -> Vec<NextAction> {
    let Some(BdfValue::Array(items)) = map.get("next_actions") else {
        return Vec::new();
    };
    items
        .iter()
        .filter_map(|item| {
            let BdfValue::Map(na) = item else {
                return None;
            };
            Some(NextAction {
                tool: na_string(na, "tool"),
                action: na_string(na, "action"),
                reason: na_string(na, "reason"),
            })
        })
        .collect()
}

fn na_string(map: &indexmap::IndexMap<String, BdfValue>, key: &str) -> String {
    match map.get(key) {
        Some(BdfValue::Str(s)) => s.clone(),
        _ => String::new(),
    }
}

/// Collect every `receipts[].sha256` as the BDF receipt's `derived_from`
/// lineage. The full receipts (kind, ref, method, derived_from) stay verbatim
/// in the payload.
fn project_receipt_lineage(map: &indexmap::IndexMap<String, BdfValue>) -> Vec<String> {
    let Some(BdfValue::Array(items)) = map.get("receipts") else {
        return Vec::new();
    };
    items
        .iter()
        .filter_map(|item| match item {
            BdfValue::Map(r) => match r.get("sha256") {
                Some(BdfValue::Str(s)) => Some(s.clone()),
                _ => None,
            },
            _ => None,
        })
        .collect()
}

#[cfg(test)]
mod tests {
    use super::*;

    /// A doctor-style envelope: minimal, empty collections, no native block.
    fn doctor_fixture() -> &'static str {
        r#"{"schema":"project-telos.flagship-action/v1","tool":"buildc","tool_version":"1.0.0","command":"doctor","status":"MATCH","inputs":[],"outputs":[],"receipts":[],"native":{"checks":[{"name":"toolchain","ok":true},{"name":"effects-db","ok":true}],"summary":"all green"},"next_actions":[],"diagnostics":[]}"#
    }

    /// A status envelope with a nested `native` block and a DRIFT verdict.
    fn status_fixture() -> &'static str {
        r#"{"schema":"project-telos.flagship-action/v1","tool":"index","tool_version":"2.8.0","command":"status","status":"DRIFT","inputs":["src/"],"outputs":[],"receipts":[{"kind":"document","ref":"index.json","method":"file-read","sha256":"aa11bb22","derived_from":[]}],"native":{"graph":{"nodes":42,"edges":117,"density":0.5},"drift":{"added":["mod-x"],"removed":[],"changed":["mod-y"]},"verdict":"DRIFT"},"next_actions":[{"tool":"forum","action":"route","reason":"drift needs review","inputs":[],"priority":"high"}],"diagnostics":["module mod-y changed signature"]}"#
    }

    /// A workflow envelope with multiple receipts (lineage) and next_actions.
    fn workflow_fixture() -> &'static str {
        r#"{"schema":"project-telos.flagship-action/v1","tool":"forum","tool_version":"1.12.0","command":"run","status":"UNVERIFIABLE","inputs":["plan.json"],"outputs":["result.json"],"receipts":[{"kind":"document","ref":"plan.json","method":"file-read","sha256":"deadbeef01","derived_from":[]},{"kind":"transcript","ref":"run.log","method":"witnessed-ledger","sha256":"cafe1234","derived_from":["deadbeef01"]}],"native":{"agents":["planner","critic"],"steps":3,"ledger_root":"abc999"},"next_actions":[{"tool":"crucible","action":"measure","reason":"verify the artifact","inputs":["result.json"],"priority":"normal"},{"tool":"gather","action":"intake","reason":"archive the run","inputs":[],"priority":"low"}],"diagnostics":[]}"#
    }

    fn fixtures() -> Vec<&'static str> {
        vec![doctor_fixture(), status_fixture(), workflow_fixture()]
    }

    /// Compare two JSON texts by *semantic* equality (order-insensitive,
    /// whitespace-insensitive) - the standard "canonical JSON equality".
    fn json_eq(a: &str, b: &str) -> bool {
        let va: serde_json::Value = serde_json::from_str(a).expect("a is json");
        let vb: serde_json::Value = serde_json::from_str(b).expect("b is json");
        va == vb
    }

    // ---- LOSSLESS ROUND-TRIP (through JSON) ----

    #[test]
    fn round_trip_through_json_is_lossless() {
        for fx in fixtures() {
            let message = flagship_action_to_bdf(fx).expect("to bdf");
            let back = bdf_to_flagship_action(&message).expect("to fa");
            assert!(
                json_eq(fx, &back),
                "json round-trip mismatch\n original: {fx}\n returned: {back}"
            );
        }
    }

    // ---- LOSSLESS ROUND-TRIP (through the binary form) ----

    #[test]
    fn round_trip_through_binary_is_lossless() {
        for fx in fixtures() {
            let message = flagship_action_to_bdf(fx).expect("to bdf");
            let bytes = message.to_bytes();
            let decoded = BdfMessage::from_bytes(&bytes).expect("from bytes");
            assert_eq!(message, decoded, "message changed across binary form");
            let back = bdf_to_flagship_action(&decoded).expect("to fa");
            assert!(
                json_eq(fx, &back),
                "binary round-trip mismatch\n original: {fx}\n returned: {back}"
            );
        }
    }

    // ---- FIELD PROJECTION ----

    #[test]
    fn produced_by_maps_tool_and_version() {
        let m = flagship_action_to_bdf(status_fixture()).expect("to bdf");
        assert_eq!(m.produced_by.tool, "index");
        assert_eq!(m.produced_by.tool_version, "2.8.0");
        assert_eq!(m.payload_schema, FLAGSHIP_ACTION_SCHEMA);
    }

    #[test]
    fn next_actions_project_into_next() {
        let m = flagship_action_to_bdf(workflow_fixture()).expect("to bdf");
        assert_eq!(m.next.len(), 2);
        assert_eq!(m.next[0].tool, "crucible");
        assert_eq!(m.next[0].action, "measure");
        assert_eq!(m.next[1].tool, "gather");
    }

    #[test]
    fn receipt_lineage_collects_flagship_sha256s() {
        let m = flagship_action_to_bdf(workflow_fixture()).expect("to bdf");
        // Both flagship receipt digests become the BDF receipt's derived_from.
        assert_eq!(m.receipt.derived_from, vec!["deadbeef01", "cafe1234"]);
        // The BDF-level receipt sha256 is a fresh digest over the BDF payload,
        // NOT one of the flagship digests (admission anchor is separate).
        assert_eq!(m.receipt.sha256.len(), 64);
        assert_ne!(m.receipt.sha256, "deadbeef01");
    }

    #[test]
    fn carrier_claims_no_effects() {
        let m = flagship_action_to_bdf(doctor_fixture()).expect("to bdf");
        assert!(m.effects.is_empty(), "bridge must not invent effects");
    }

    #[test]
    fn status_verdict_is_preserved_verbatim_not_collapsed() {
        // The verdict survives as a payload field and is NOT turned into
        // BDF-level admission or an effect.
        for (fx, want) in [
            (doctor_fixture(), "MATCH"),
            (status_fixture(), "DRIFT"),
            (workflow_fixture(), "UNVERIFIABLE"),
        ] {
            let m = flagship_action_to_bdf(fx).expect("to bdf");
            let BdfValue::Map(payload) = &m.payload else {
                panic!("payload must be a map");
            };
            assert_eq!(
                payload.get("status"),
                Some(&BdfValue::Str(want.to_string())),
                "status verdict must round-trip verbatim"
            );
        }
    }

    // ---- LOSSLESSNESS OF UNKNOWN / EXTRA FIELDS ----

    #[test]
    fn unknown_extra_fields_survive_round_trip() {
        let fx = r#"{"schema":"project-telos.flagship-action/v1","tool":"telos","tool_version":"0.9.0","command":"perceive","status":"MATCH","inputs":[],"outputs":[],"receipts":[],"native":{},"next_actions":[],"diagnostics":[],"experimental_field":{"weird":[1,2,3],"flag":true},"trace_id":"xyz-123"}"#;
        let m = flagship_action_to_bdf(fx).expect("to bdf");
        let back = bdf_to_flagship_action(&m).expect("to fa");
        assert!(json_eq(fx, &back), "unknown fields dropped:\n{fx}\n{back}");
    }

    // ---- NEGATIVE (fail closed) ----

    #[test]
    fn rejects_unknown_schema() {
        let fx = r#"{"schema":"project-telos.flagship-action/v999","tool":"x","tool_version":"1"}"#;
        assert!(matches!(
            flagship_action_to_bdf(fx),
            Err(BdfError::UnsupportedSchema { .. })
        ));
    }

    #[test]
    fn rejects_missing_schema() {
        let fx = r#"{"tool":"x","tool_version":"1","command":"y"}"#;
        assert!(matches!(
            flagship_action_to_bdf(fx),
            Err(BdfError::UnsupportedSchema { .. })
        ));
    }

    #[test]
    fn rejects_non_object_envelope() {
        assert!(flagship_action_to_bdf("[1,2,3]").is_err());
        assert!(flagship_action_to_bdf("\"just a string\"").is_err());
    }

    #[test]
    fn rejects_malformed_json() {
        assert!(flagship_action_to_bdf("{not json").is_err());
    }

    #[test]
    fn to_flagship_rejects_wrong_payload_schema() {
        // A BdfMessage whose payload_schema is not flagship-action is refused.
        let m = BdfMessage::new(
            ProducedBy {
                tool: "x".to_string(),
                tool_version: "1".to_string(),
            },
            Vec::new(),
            "buildlang.demo/v0",
            BdfValue::Null,
            Vec::new(),
            Vec::new(),
        );
        assert!(matches!(
            bdf_to_flagship_action(&m),
            Err(BdfError::UnsupportedSchema { .. })
        ));
    }
}