Struct CompositionBuilder 

pub struct CompositionBuilder { /* private fields */ }

Builds shape-checked recipes by delegating every graph operation to Adam.

Fallible boundaries reject unregistered shapes before constructing adapters. Factories must return fresh segments and fresh segment-local mutable owners. Emitters run during checking and instance construction, but their expressions run only during initialization or ordinary native execution. See the module example.

Implementations

impl CompositionBuilder

pub fn new(types: TypeRegistry) -> Self

Owns a registry and starts an empty source-free recipe.

Examples

See the module example.

pub fn set_label(&mut self, label: SourceLabel)

Retains a definition label without synthesizing source locations.

Examples

let mut builder = adam_lang::CompositionBuilder::new(adam_lang::TypeRegistry::new());
builder.set_label(adam_lang::SourceLabel { location: None, label: "host".into() });

pub fn parameter( &mut self, name: &str, shape: TypeShape, ) -> Result<CellSlot, ModuleDiagnostic>

Declares a named parameter with its complete concrete shape.

Errors

Rejects unregistered shapes and native declaration errors without mutation.

• Complexity: Expected amortized O(n + l) shape nodes and name bytes.

Examples

See the module example.

pub fn cell<F>( &mut self, name: &str, shape: TypeShape, emit: F, ) -> Result<CellSlot, ModuleDiagnostic>

where F: Fn() -> Result<DynSegment> + 'static,

Declares a fresh private ordinary cell initialized at instantiation.

Errors

Rejects unknown shapes, incompatible emitted signatures, missing capabilities, or native declaration errors. Initializer execution errors occur at instantiation.

• Complexity: O(n + e + l) shape nodes, emitted reads and name bytes, excluding emitter costs.

Examples

use adam_lang::{CompositionBuilder, TypeRegistry};
use adam_lang::type_registry::TypeShape;
let mut builder = CompositionBuilder::new(TypeRegistry::new());
builder.cell("x", TypeShape::Named(std::any::TypeId::of::<i32>()), || {
    let mut body = cel_runtime::DynSegment::new::<()>();
    body.op0(|| 1i32);
    Ok(body)
})?;

pub fn source<F>( &mut self, name: &str, shape: TypeShape, emit: F, ) -> Result<CellSlot, ModuleDiagnostic>

where F: Fn() -> Result<DynSegment> + 'static,

Declares a fresh private source initialized at instantiation.

Errors

Returns the same definition errors as Self::cell.

• Complexity: The same as Self::cell.

Examples

See Self::cell; use source instead of cell.

pub fn default_cell( &mut self, name: &str, shape: TypeShape, ) -> Result<CellSlot, ModuleDiagnostic>

Declares a private cell using the registry’s canonical default emitter.

No default value is constructed until instantiation.

Errors

Rejects unknown shapes, missing defaults/capabilities, or native declaration errors.

• Complexity: O(n + l) shape nodes and name bytes.

Examples

let mut b = adam_lang::CompositionBuilder::new(adam_lang::TypeRegistry::new());
b.default_cell("empty", adam_lang::type_registry::TypeShape::Tuple(vec![]))?;

pub fn method<F>( &self, inputs: &[CellSlot], outputs: &[CellSlot], emit: F, ) -> Result<MethodRecipe, ModuleDiagnostic>

where F: Fn() -> Result<DynSegment> + 'static,

Constructs a repeatable, complete-shape method without executing its expression.

Inputs use positional push_arg indices. A single output receives the whole result; two or more outputs destructure the result’s source-ordered tuple. Callbacks obey native method purity and self-reference idempotence contracts.

Errors

Rejects foreign handles, malformed edges, incompatible bodies, or unknown shapes.

• Complexity: O(n + e + o²) descriptor nodes n, emitted reads e and outputs o.

Examples

use adam_lang::{CompositionBuilder, TypeRegistry};
use adam_lang::type_registry::TypeShape;
let mut b = CompositionBuilder::new(TypeRegistry::new());
let x = b.parameter("x", TypeShape::Named(std::any::TypeId::of::<i32>()))?;
let recipe = b.method(std::slice::from_ref(&x), std::slice::from_ref(&x), || {
    let mut body = cel_runtime::DynSegment::new::<()>();
    body.push_arg::<i32>(0);
    Ok(body)
})?;
assert_eq!(recipe.input_shapes(), recipe.output_shapes());
b.relationship(vec![recipe])?;

pub fn relationship( &mut self, methods: Vec<MethodRecipe>, ) -> Result<RelationshipSlot, ModuleDiagnostic>

Appends a native relationship, preserving its alternative method ordering.

Errors

Returns native ownership and relationship validation errors before mutation.

• Complexity: O(m² × e) for m methods of at most e edges.

Examples

See Self::method.

pub fn out( &mut self, writer: MethodRecipe, ) -> Result<RelationshipSlot, ModuleDiagnostic>

Promotes a private ordinary cell through its single sole-writer method.

Errors

Rejects formal, source, multi-output, foreign, or previously written targets.

• Complexity: O(i + r) inputs and prior output summaries.

Examples

See Self::method; pass a private single-output recipe to out.

pub fn filter<F>( &mut self, cell: &CellSlot, inputs: &[CellSlot], emit: F, ) -> Result<(), ModuleDiagnostic>

where F: Fn() -> Result<DynSegment> + 'static,

Attaches a value-returning or numeric-range filter with a fresh frame per instance.

Argument zero is the candidate; subsequent arguments are the declared inputs. The callback obeys the native filter’s purity contract.

Errors

Rejects foreign/formal targets, invalid dependencies, unknown shapes or mismatched bodies.

• Complexity: O(n + e + i) shape nodes, emitted reads and inputs.

Examples

See Self::cell; a filter emitter may use push_arg::<i32>(0) for its candidate.

pub fn require<F>( &mut self, cell: &CellSlot, inputs: &[CellSlot], emit: F, ) -> Result<(), ModuleDiagnostic>

where F: Fn() -> Result<DynSegment> + 'static,

Attaches a bool-returning requirement with a fresh frame per instance.

The callback obeys the native requirement’s purity contract.

Errors

Rejects foreign/formal targets, unknown shapes and incompatible emitted signatures. Ordinary/source requirement execution errors occur during native attachment.

• Complexity: O(n + e + i) descriptor nodes, reads and inputs.

Examples

See Self::cell; a nullary requirement may emit body.op0(|| true).

pub fn conditional<T, F>( &mut self, inputs: &[CellSlot], emit: F, branches: Vec<(Vec<T>, Vec<RelationshipSlot>)>, default: Vec<RelationshipSlot>, ) -> Result<(), ModuleDiagnostic>

where T: Any + Clone + PartialEq, F: Fn() -> Result<DynSegment> + 'static,

Registers conditional groups using a registered host leaf as the match key.

Each included group must be transitively relationship-only. Keys and emitted results have exactly type T; callbacks obey native match-expression purity.

Errors

Rejects unknown key/input shapes, incompatible bodies or native group errors.

• Complexity: O(n + e + i + g + k) descriptors, reads, inputs, groups and keys.

Examples

let mut b = adam_lang::CompositionBuilder::new(adam_lang::TypeRegistry::new());
b.conditional(&[], || {
    let mut body = cel_runtime::DynSegment::new::<()>();
    body.op0(|| true);
    Ok(body)
}, vec![(vec![true], vec![])], vec![])?;

pub fn conditional_compound<R, F>( &mut self, inputs: &[CellSlot], emit: F, branches: Vec<(Vec<R::Value>, Vec<RelationshipSlot>)>, default: Vec<RelationshipSlot>, ) -> Result<(), ModuleDiagnostic>

where R: ValueRepr, F: Fn() -> Result<DynSegment> + 'static,

Registers conditional groups using complete canonical compound keys.

The witness supplies both key and result identity. Compound equality and cloning must be available; callable keys without equality are rejected.

Errors

Rejects unknown shapes, non-compound witnesses, missing capabilities, incompatible emitted results, or native group errors before recipe mutation.

• Complexity: O(n + e + i + g + k) descriptors, reads, inputs, groups and key values.

Examples

use cel_runtime::{Array, ArrayOf, Leaf, DynSegment};
let mut b = adam_lang::CompositionBuilder::new(adam_lang::TypeRegistry::new());
b.conditional_compound::<ArrayOf<Leaf<bool>>, _>(&[], || {
    let mut body = DynSegment::new::<()>();
    body.op0_repr::<ArrayOf<Leaf<bool>>, _>(|| Array::from_vec(vec![true]))?;
    Ok(body)
}, vec![(vec![Array::from_vec(vec![true])], vec![])], vec![])?;

pub fn include( &mut self, child: &TypedTemplate, bindings: &[(&str, CellSlot)], ) -> Result<TemplateInclusion, ModuleDiagnostic>

Includes a typed child using complete named bindings before native mutation.

Errors

Rejects foreign handles, unknown/missing/duplicate names, aliases, full-shape mismatches and native kind/structural errors. Rejection leaves the recipe unchanged.

• Complexity: O(b + n) bindings and compared shape nodes, plus native local preflight.

Examples

let types = adam_lang::TypeRegistry::new();
let child = adam_lang::CompositionBuilder::new(types.clone()).finish()?;
let mut parent = adam_lang::CompositionBuilder::new(types);
parent.include(&child, &[])?;

pub fn finish(self) -> Result<TypedTemplate, ModuleDiagnostic>

Finalizes an immutable native recipe and its complete local metadata.

Errors

Rejects included parameters that became private outputs after inclusion.

• Complexity: O(n + a + e) local declarations, authored records and edges, without DAG expansion.

Examples

See the module example.