Lattice Composition

Overview

Big jobs are usually too big for one workflow. Lattice composition is how aDNA snaps smaller workflows together to make bigger ones — the same way a dinner recipe is built from smaller recipes for the sauce, the vegetables, and the main. A lattice is a directed graph of nodes (modules, datasets, processes) connected by edges (data flow); composition combines lattices through two patterns — inline merging and external referencing — which is what makes them reusable, shareable, and scalable.

Why This Matters

Think of it like cooking. A recipe for a full dinner isn’t one monolithic instruction — it’s composed from sub-recipes. The salad dressing is its own recipe. The roasted vegetables are their own recipe. The dinner recipe combines them, specifying how the salad dressing goes on the salad and the vegetables go alongside the main course.

Lattices work the same way. A protein drug discovery pipeline might involve structure prediction, binding analysis, and ranking — each a complex workflow in its own right. Rather than writing one enormous pipeline from scratch, you compose it from smaller, tested lattices. The structure prediction team maintains their lattice. The binding analysis team maintains theirs. The pipeline team composes them, specifying how data flows between them.

This is powerful for three reasons. First, each piece can be developed, tested, and improved independently. Second, pieces can be shared across projects — a structure prediction lattice is useful in many pipelines, not just one. Third, composition makes complexity manageable — you can understand a 50-node workflow as 5 composed lattices of 10 nodes each, not as one flat graph.

How It Works

The Lattice YAML Structure

Every lattice is declared in a .lattice.yaml file that validates against the schema at what/lattices/lattice_yaml_schema.json. The core elements (§5.1):

Seven Lattice Types

Two Composition Patterns

When combining lattices, you choose between two patterns (§11):

Inline composition — child nodes merge into the parent with namespace prefixes.

External reference — child appears as a single opaque node with a lattice:// URI.

Default recommendation: External reference. It minimizes token cost while preserving composability. Use inline only when the parent genuinely needs to inspect or modify child internals.

Seam Edges

Seam edges are the connectors between composed lattices. They require explicit data mapping — no implicit pass-through:

edges:
  - from: parent_design_step
    to: docking_assessment          # opaque child node
    label: "designed sequences for validation"
    data_mapping:
      sequences: input_sequences    # explicit field mapping
    port: structure_prediction      # child entry node

Rules: at least one edge into the child’s entry and one out of its exit. Every seam edge needs data_mapping. External references need port to identify which child node receives the data.

Federation Readiness

For a lattice to be composable across aDNA instances (not just within one project), it must pass six readiness checks (§11):

See It In Action

This vault contains the full lattice infrastructure at what/lattices/:

Schema: what/lattices/lattice_yaml_schema.json — the JSON Schema that all lattice files validate against. Open it to see the nodes, edges, federation, and fair block definitions.

Examples: what/lattices/examples/ contains validated lattice files covering all types and composition patterns. The docking_assessment example demonstrates external reference federation — it was extracted from a larger protein_binder_design pipeline and carries federation.parent_lattice provenance.

Validation tools: what/lattices/tools/lattice_validate.py checks schema compliance, node ID uniqueness, edge reference validity, and federation property consistency. Run it against any .lattice.yaml to verify composition correctness.

The vault itself is a context graph: The knowledge structure you’re navigating — concepts linking to concepts, AGENTS.md routing agents through directories — is a context_graph lattice. The nodes are files. The edges are wikilinks and AGENTS.md references. The execution mode is agent-driven graph traversal.

Related

• Ontology — the entity types (module, dataset, lattice) that serve as lattice building blocks
• Knowledge Graph — the broader connected structure that lattices formalize as declarative YAML
• FAIR Metadata — the metadata envelope that makes lattices findable, shareable, and reusable
• Open Standard — how federation enables lattice composition across independent aDNA instances