arete-interpreter 0.39.0

//! Bridge between explicit public artifacts and the current interpreter
//! generators. The compiled stack IR is constructed only in memory and is not
//! a published artifact.

use std::collections::{BTreeMap, BTreeSet};

use arete_artifacts::{
    resolve_stack_composition_v2, LiveSpecArtifact, LiveSpecArtifactV2, ProgramSpecArtifact,
    ResolvedLiveSpecV2, StackManifestArtifact, StackManifestArtifactV2,
};
use serde::de::DeserializeOwned;
use serde::Serialize;

use crate::ast::{InstructionDef, PdaDefinition, SerializableStackSpec, CURRENT_AST_VERSION};

/// The exact served version a generated stack definition targets: one live
/// alias of one StackManifest. Generated SDKs name it in their WebSocket
/// session request so the session endpoint can route each client to the
/// version it was generated for. Only StackManifest generation knows it;
/// AST-only generation never emits one.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct StackRelease {
    /// `arete:h1:stack-manifest:sha256:<64 hex>`.
    pub stack_manifest_hash: String,
    /// The StackManifest live alias the stack definition serves.
    pub live_alias: String,
}

impl StackRelease {
    /// The release of `alias` within `manifest`.
    pub fn for_alias(manifest: &StackManifestArtifactV2, alias: &str) -> Self {
        Self {
            stack_manifest_hash: manifest.artifact_hash.to_string(),
            live_alias: alias.to_string(),
        }
    }

    /// The release of a single-live manifest's only alias.
    pub fn for_single_live(manifest: &StackManifestArtifactV2) -> Option<Self> {
        match manifest.payload.live_specs.as_slice() {
            [live] => Some(Self::for_alias(manifest, &live.alias)),
            _ => None,
        }
    }
}

#[derive(Debug, Clone)]
pub struct AliasedStackSpecV2 {
    pub alias: String,
    pub live_spec_hash: String,
    pub stack_spec: SerializableStackSpec,
}

#[derive(Debug, Clone)]
pub struct ComposedStackSpecsV2 {
    pub name: String,
    pub live_specs: Vec<AliasedStackSpecV2>,
}

pub fn stack_spec_from_program_artifacts(
    name: impl Into<String>,
    programs: &[ProgramSpecArtifact],
) -> Result<SerializableStackSpec, String> {
    for program in programs {
        program.validate().map_err(|error| error.to_string())?;
    }
    let (program_ids, idls, program_specs, pdas, instructions) = program_inputs(programs)?;
    Ok(SerializableStackSpec {
        ast_version: CURRENT_AST_VERSION.to_string(),
        stack_name: name.into(),
        program_ids,
        idls,
        program_specs,
        entities: Vec::new(),
        pdas,
        instructions,
        content_hash: None,
    })
}

pub fn stack_spec_from_artifacts(
    programs: &[ProgramSpecArtifact],
    live_spec: &LiveSpecArtifact,
    manifest: &StackManifestArtifact,
) -> Result<SerializableStackSpec, String> {
    live_spec.validate().map_err(|error| error.to_string())?;
    manifest.validate().map_err(|error| error.to_string())?;
    let mut stack = stack_spec_from_program_artifacts(&manifest.payload.name, programs)?;

    let program_hashes = programs
        .iter()
        .map(|program| program.artifact_hash)
        .collect::<Vec<_>>();
    let live_program_hashes = live_spec
        .payload
        .programs
        .iter()
        .map(|program| program.program_spec_hash)
        .collect::<Vec<_>>();
    let manifest_program_hashes = manifest
        .payload
        .programs
        .iter()
        .map(|program| program.artifact_hash)
        .collect::<Vec<_>>();
    if program_hashes != live_program_hashes || program_hashes != manifest_program_hashes {
        return Err(
            "ProgramSpec order must match LiveSpec and StackManifest requirements".to_string(),
        );
    }
    if manifest.payload.live_specs.len() != 1
        || manifest.payload.live_specs[0].artifact_hash != live_spec.artifact_hash
    {
        return Err("StackManifest must reference the supplied LiveSpec exactly once".to_string());
    }

    stack.entities = transcode(&live_spec.payload.entities)?;
    if let Some(extensions) = &live_spec.payload.legacy_program_extensions {
        stack.pdas = transcode(&extensions.pdas)?;
        stack.instructions = transcode(&extensions.instructions)?;
    }
    Ok(stack)
}

/// Reconstruct the single-live generator input from typed V2 artifacts.
/// This compatibility wrapper deliberately rejects zero- and multi-live inputs.
///
/// The result carries every program the StackManifest groups: the programs
/// the LiveSpec requires, in LiveSpec order, followed by the manifest's
/// independent programs in manifest order. A single-live stack is a group of
/// one live view and its program SDKs, so an independent program is as much
/// a part of its generated SDK as one the view indexes.
pub fn stack_spec_from_artifacts_v2(
    programs: &[ProgramSpecArtifact],
    live_spec: &LiveSpecArtifactV2,
    manifest: &StackManifestArtifactV2,
) -> Result<SerializableStackSpec, String> {
    if manifest.payload.live_specs.len() != 1 {
        return Err("single-live compatibility requires exactly one aliased LiveSpec".to_string());
    }
    let alias = manifest.payload.live_specs[0].alias.clone();
    let lives = vec![(alias, live_spec.clone())];
    let mut composed = stack_specs_from_artifacts_v2(programs, &lives, manifest)?;
    let mut stack = composed.live_specs.remove(0).stack_spec;
    append_independent_programs(&mut stack, programs, live_spec, manifest)?;
    Ok(stack)
}

/// Append the manifest programs `live_spec` does not require, in manifest
/// order. The closure was already validated, so every manifest program is
/// among `programs`.
fn append_independent_programs(
    stack: &mut SerializableStackSpec,
    programs: &[ProgramSpecArtifact],
    live_spec: &LiveSpecArtifactV2,
    manifest: &StackManifestArtifactV2,
) -> Result<(), String> {
    let required = live_spec
        .payload
        .programs
        .iter()
        .map(|requirement| requirement.program_spec_hash.to_string())
        .collect::<BTreeSet<_>>();
    let independent = manifest
        .payload
        .programs
        .iter()
        .filter(|reference| !required.contains(&reference.artifact_hash.to_string()))
        .map(|reference| {
            programs
                .iter()
                .find(|program| program.artifact_hash == reference.artifact_hash)
                .cloned()
                .ok_or_else(|| {
                    format!(
                        "StackManifest program {} was not supplied",
                        reference.artifact_hash
                    )
                })
        })
        .collect::<Result<Vec<_>, String>>()?;
    if independent.is_empty() {
        return Ok(());
    }
    let (program_ids, idls, program_specs, pdas, instructions) = program_inputs(&independent)?;
    for idl in &idls {
        if stack.idls.iter().any(|existing| existing.name == idl.name) {
            return Err(format!(
                "StackManifest groups two programs named '{}'; rename one of them",
                idl.name
            ));
        }
    }
    stack.program_ids.extend(program_ids);
    stack.idls.extend(idls);
    stack.program_specs.extend(program_specs);
    for (name, program_pdas) in pdas {
        stack.pdas.entry(name).or_insert(program_pdas);
    }
    stack.instructions.extend(instructions);
    Ok(())
}

/// Build one fresh generator model per manifest alias. ProgramSpec lookup is
/// hash-keyed, adapters are applied only to that live's dependency subset, and
/// selected views are projected before language generation.
pub fn stack_specs_from_artifacts_v2(
    programs: &[ProgramSpecArtifact],
    live_specs: &[(String, LiveSpecArtifactV2)],
    manifest: &StackManifestArtifactV2,
) -> Result<ComposedStackSpecsV2, String> {
    let resolved = resolve_stack_composition_v2(manifest, live_specs, programs)
        .map_err(|error| error.to_string())?;
    let multiple = resolved.live_specs.len() > 1;
    let live_specs = resolved
        .live_specs
        .into_iter()
        .map(|live| {
            let stack_name = if multiple {
                format!(
                    "{}{}",
                    identifier_pascal_case(&manifest.payload.name),
                    identifier_pascal_case(&live.alias)
                )
            } else {
                manifest.payload.name.clone()
            };
            stack_spec_for_live(stack_name, live)
        })
        .collect::<Result<Vec<_>, String>>()?;
    Ok(ComposedStackSpecsV2 {
        name: manifest.payload.name.clone(),
        live_specs,
    })
}

#[cfg(test)]
pub(crate) fn ore_stack_spec_from_exact_artifacts() -> SerializableStackSpec {
    let root = std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
        .parent()
        .expect("interpreter crate lives beneath repository root")
        .join("stacks/ore/.arete");
    let manifest = arete_artifacts::load_stack_manifest_v2(
        &std::fs::read(root.join("OreStream.stack-manifest.json")).unwrap(),
    )
    .unwrap()
    .artifact;
    let live = arete_artifacts::load_live_spec_v2(
        &std::fs::read(root.join("OreStream.live-spec.json")).unwrap(),
    )
    .unwrap()
    .artifact;
    let candidates = [
        arete_artifacts::load_program_spec(
            &std::fs::read(root.join("ore.program-spec.json")).unwrap(),
        )
        .unwrap()
        .artifact,
        arete_artifacts::load_program_spec(
            &std::fs::read(root.join("entropy.program-spec.json")).unwrap(),
        )
        .unwrap()
        .artifact,
    ];
    let programs = manifest
        .payload
        .programs
        .iter()
        .map(|reference| {
            candidates
                .iter()
                .find(|program| program.artifact_hash == reference.artifact_hash)
                .unwrap()
                .clone()
        })
        .collect::<Vec<_>>();
    stack_spec_from_artifacts_v2(&programs, &live, &manifest).unwrap()
}

fn stack_spec_for_live(
    stack_name: String,
    live: ResolvedLiveSpecV2<'_>,
) -> Result<AliasedStackSpecV2, String> {
    let programs = live
        .program_specs
        .iter()
        .map(|program| (*program).clone())
        .collect::<Vec<_>>();
    let mut stack = stack_spec_from_program_artifacts(stack_name, &programs)?;
    stack.entities = transcode(&live.artifact.payload.entities)?;
    let selected = live.selected_views.iter().collect::<BTreeSet<_>>();
    for entity in &mut stack.entities {
        entity.views.retain(|view| selected.contains(&view.id));
    }

    for adapter in &live.artifact.payload.program_adapters {
        let program = programs
            .iter()
            .find(|program| program.artifact_hash == adapter.program_spec_hash)
            .ok_or_else(|| "program adapter references an unknown ProgramSpec".to_string())?;
        let program_name = &program.payload.idl_snapshot.snapshot.name;
        let pdas = stack.pdas.entry(program_name.clone()).or_default();
        for (name, pda) in &adapter.pdas {
            pdas.insert(name.clone(), transcode(pda)?);
        }
        for resolution in &adapter.instruction_resolutions {
            let instruction = stack
                .instructions
                .iter_mut()
                .find(|instruction| {
                    instruction.name == resolution.instruction
                        && instruction.program_id.as_deref()
                            == Some(program.payload.program_id.as_str())
                })
                .ok_or_else(|| {
                    format!(
                        "program adapter references unknown instruction '{}.{}'",
                        program_name, resolution.instruction
                    )
                })?;
            for (account_name, account_resolution) in &resolution.accounts {
                let account = instruction
                    .accounts
                    .iter_mut()
                    .find(|account| account.name == *account_name)
                    .ok_or_else(|| {
                        format!(
                            "program adapter references unknown account '{}.{}.{}'",
                            program_name, resolution.instruction, account_name
                        )
                    })?;
                account.resolution = transcode(account_resolution)?;
            }
        }
    }
    Ok(AliasedStackSpecV2 {
        alias: live.alias,
        live_spec_hash: live.artifact.artifact_hash.to_string(),
        stack_spec: stack,
    })
}

type ProgramInputs = (
    Vec<String>,
    Vec<arete_idl::snapshot::IdlSnapshot>,
    Vec<arete_hash::ProgramSpecV1>,
    BTreeMap<String, BTreeMap<String, PdaDefinition>>,
    Vec<InstructionDef>,
);

fn program_inputs(programs: &[ProgramSpecArtifact]) -> Result<ProgramInputs, String> {
    let mut program_ids = Vec::with_capacity(programs.len());
    let mut idls = Vec::with_capacity(programs.len());
    let mut program_specs = Vec::with_capacity(programs.len());
    let mut pdas = BTreeMap::new();
    let mut instructions = Vec::new();
    for program in programs {
        let payload = &program.payload;
        program_ids.push(payload.program_id.clone());
        idls.push(payload.idl_snapshot.snapshot.clone());
        program_specs.push(payload.clone());
        let program_pdas = transcode(&payload.pdas)?;
        pdas.insert(payload.idl_snapshot.snapshot.name.clone(), program_pdas);
        instructions.extend(transcode::<_, Vec<InstructionDef>>(&payload.instructions)?);
    }
    Ok((program_ids, idls, program_specs, pdas, instructions))
}

fn transcode<T: Serialize, U: DeserializeOwned>(value: &T) -> Result<U, String> {
    serde_json::from_value(serde_json::to_value(value).map_err(|error| error.to_string())?)
        .map_err(|error| error.to_string())
}

fn identifier_pascal_case(value: &str) -> String {
    let mut output = value
        .split(|character: char| !character.is_ascii_alphanumeric())
        .filter(|segment| !segment.is_empty())
        .map(|segment| {
            let mut characters = segment.chars();
            characters
                .next()
                .map(|first| first.to_ascii_uppercase().to_string() + characters.as_str())
                .unwrap_or_default()
        })
        .collect::<String>();
    if output
        .chars()
        .next()
        .is_some_and(|character| character.is_ascii_digit())
    {
        output.insert(0, 'A');
    }
    output
}

#[cfg(test)]
mod tests {
    use super::*;
    use arete_hash::{CanonicalIdlDocument, ProgramSpecV1};

    fn program() -> ProgramSpecArtifact {
        let idl = br#"{
          "address":"11111111111111111111111111111111",
          "metadata":{"name":"system","version":"1.0.0","spec":"0.1.0"},
          "instructions":[],"accounts":[],"types":[],"events":[],"errors":[]
        }"#;
        let document = CanonicalIdlDocument::parse(idl, None).unwrap();
        ProgramSpecArtifact::new(ProgramSpecV1::from_document(&document)).unwrap()
    }

    fn named_program(address: &str, name: &str) -> ProgramSpecArtifact {
        let idl = format!(
            r#"{{"address":"{address}","metadata":{{"name":"{name}","version":"1.0.0","spec":"0.1.0"}},"instructions":[],"accounts":[],"types":[],"events":[],"errors":[]}}"#
        );
        let document = CanonicalIdlDocument::parse(idl.as_bytes(), None).unwrap();
        ProgramSpecArtifact::new(ProgramSpecV1::from_document(&document)).unwrap()
    }

    #[test]
    fn a_single_live_stack_carries_its_independent_programs_after_the_live_programs() {
        let root = std::path::Path::new(env!("CARGO_MANIFEST_DIR"))
            .parent()
            .unwrap()
            .join("stacks/ore/.arete");
        let load = |name: &str| std::fs::read(root.join(name)).unwrap();
        let live = arete_artifacts::load_live_spec_v2(&load("OreStream.live-spec.json"))
            .unwrap()
            .artifact;
        let ore = arete_artifacts::load_program_spec(&load("ore.program-spec.json"))
            .unwrap()
            .artifact;
        let entropy = arete_artifacts::load_program_spec(&load("entropy.program-spec.json"))
            .unwrap()
            .artifact;
        let vote = named_program(
            "Vote111111111111111111111111111111111111111",
            "vote_program",
        );
        // The independent program sits between the live programs in manifest
        // order; generation still lists the live programs first.
        let programs = vec![ore.clone(), vote.clone(), entropy.clone()];
        let manifest = arete_artifacts::compose_stack_manifest_v2(
            "OreWithVote",
            &programs,
            vec![("live".to_string(), &live)],
            vec![arete_artifacts::SelectedViewV2 {
                live_alias: "live".to_string(),
                view_id: "OreRound/latest".to_string(),
            }],
        )
        .unwrap();

        let stack = stack_spec_from_artifacts_v2(&programs, &live, &manifest).unwrap();
        assert_eq!(
            stack.program_ids,
            vec![
                ore.payload.program_id.clone(),
                entropy.payload.program_id.clone(),
                vote.payload.program_id.clone(),
            ]
        );
        assert_eq!(stack.idls.len(), 3);
        assert_eq!(stack.program_specs.len(), 3);
        assert!(stack.pdas.contains_key("vote_program"));
        assert!(!stack.entities.is_empty());
    }

    #[test]
    fn program_artifacts_reconstruct_generator_input_without_hosted_release_state() {
        let program = program();
        let stack = stack_spec_from_program_artifacts("SystemProgram", &[program.clone()]).unwrap();
        assert_eq!(stack.program_ids, vec![program.payload.program_id]);
        assert_eq!(
            stack.program_specs[0].hash().unwrap(),
            program.artifact_hash
        );
        assert!(stack.entities.is_empty());
    }
}