Everything that affects a run's outcome in Modulo is versioned, pinned, or snapshotted. Each entity below is pinned at run-start, so editing it does not affect runs already in progress. If any were mutable, you could not reproduce a run, audit a failure, or trust the history. The snapshot model is the foundation that makes governed automation possible.

The principle behind this: immutability of runs - a run executes against a frozen snapshot, so the run you inspect is the run that happened.

PipelineSnapshot

The entire run definition frozen at run-start: every agent version, schema pin, connector binding, model backend pin, prompt version hash, and environment profile. The run executes against this snapshot, not the current configuration, so a run paused for a week resumes with identical behavior.

Schema

An agent can declare a typed contract on its input and output boundaries, defined by a JSON Schema. Schemas are org-scoped, versioned with semver, reusable, and composable. Schema inference can generate drafts from connector data.

Connector

Connectors bridge Modulo and external systems - GitHub, GitLab, model providers, and anything with an API. Each instance is versioned, with credential bindings and configuration pinned.

ModelBackend

Every agent references a model backend: the provider (OpenAI, Anthropic, etc.), the model ID, and the default parameters. Swapping from GPT-4 to Claude does not change a run already in progress.

Agent

Agents are defined by their prompt template, model binding, schema bindings, and connector type references. Each run records exactly which agent configuration was used.

Prompt

Prompts are versioned and hash-pinned in snapshots. Editing a prompt creates a new version; existing runs keep the version they started with.

EnvironmentProfile

Environment profiles define the environment variables and secret references available to a run.

AuditEvent

Every state-changing action produces an immutable audit event: actor, action, resource, timestamp. Audit events are append-only at the database level and linked in a SHA-256 chain for verifiability. There is no edit or delete.

FeedbackRecord

When a gate catches a problem and spawns a correction run, the feedback record is immutable after creation. The original output stays as it was, and the correction is a new run with the feedback attached. You can always see what the original output was and what the gate caught.

Eval definition

Eval definitions specify the gate configuration: the check type (regex, JSON Schema, custom function, scored eval), the pass threshold, and the block-or-warn behavior.

Library primitive

Schemas, agents, and pipeline templates in the library are versioned with provenance tracking. Copying a community primitive records its origin. Edits to the copy do not affect the original, and the provenance chain is preserved.

Pipeline definition

The pipeline graph itself - nodes, edges, and their configurations - is versioned through the snapshot mechanism. Each run records which version it executed against, and you can diff two runs to see exactly what changed.