Processor pipeline
The Lagom processor transforms raw .lagom.md and .lagom.json files into validated, enriched, renderable, and agent-ready artifacts through a deterministic 7-step pipeline.
Pipeline at a glance
Every Lagom document passes through the same pipeline regardless of input format. Each stage is pure: it takes an input, produces an output, and can be run independently.
Pipeline stages
Parse
Extract structure from raw source files.
The parser accepts .lagom.md or .lagom.json. For Markdown, it splits YAML frontmatter from body content, identifies fenced blocks with lagom.* language tags, and builds a raw AST of sections and elements. For JSON, it directly deserializes to the intermediate representation. The output is a RawLagomDocument that has not yet been validated.
Validate
Verify schema compliance and structural integrity.
The validator checks the raw document against the Lagom JSON Schema. It enforces required fields (id, documentType, status, sections), validates element type discriminators, checks cross-references between elements (e.g. a step referencing a declared connector), and produces a list of LagomDiagnostic objects for any violations. Validation is strict: unknown element types are rejected, not ignored.
Normalize
Canonicalize structure and resolve aliases.
Normalization ensures consistency across documents. It assigns stable IDs where missing (slug-based from titles), resolves document aliases and entity references, normalizes owner strings to canonical role identifiers, flattens nested section hierarchies to a consistent depth, and ensures all elements have explicit type tags. The result is a NormalizedLagomDocument that can be reliably compared and merged.
Enrich
Add computed metadata and cross-document links.
The enrichment stage decorates the document with computed properties that aren't authored directly. This includes word count, estimated reading time, element type distribution, system dependency graph edges, action summaries, variable resolution status, and freshness calculations from governance metadata. Enrichment can also resolve references to produce inline summaries of linked documents.
Render
Generate output artifacts for display and consumption.
The renderer produces multiple output formats from a single enriched document. Outputs include: structured HTML for the Lagom UI, canonical JSON for APIs and storage, searchable plain text for indexing, and agent-ready context chunks optimized for LLM consumption. Each output is deterministic and reproducible from the same enriched input.
Govern
Evaluate freshness, ownership, and compliance.
The governance stage evaluates the document against its declared governance metadata. It checks staleness (days since last verification vs. staleAfterDays), validates ownership (owner and reviewer fields reference known entities), computes confidence signals, and flags documents that need review. Governance results surface in dashboards and filter agent context retrieval.
Assist
Package for AI agent consumption and action execution.
The final stage transforms the enriched document into agent-ready artifacts. It extracts agent actions with their tool bindings and approval requirements, builds a variable resolution map, generates a structured context payload optimized for LLM retrieval, and produces an action manifest that runtime systems can use to offer, approve, and execute declared actions safely.
Custom pipeline stages
The pipeline is designed for extension. Each stage implements a LagomPipelineStage interface with name, input type, output type, and a process() function. Custom stages can be inserted between any two built-in stages. Common extensions include custom enrichment (adding domain-specific metadata), custom renderers (generating Confluence, Notion, or Slack-formatted output), and custom governance rules (enforcing organization-specific compliance checks).
interface LagomPipelineStage<TIn, TOut> { name: string; process(input: TIn, context: PipelineContext): Promise<TOut>; }