GLOSSARY

Agent

An AI coding agent that operates Swamp on behalf of an operative. Lowercase in prose. Swamp is designed to be operated by agents — the CLI, file formats, and skill system target agent consumption.

Assert step

A workflow step that evaluates a CEL expression and records a structured result with pass/fail, message, and severity (low, medium, high). Does not run a model — it checks a condition. See Workflows reference.

Audit timeline

Chronological record of every command executed in a Swamp repository. Swamp commands are recorded automatically; other CLI tools (aws, terraform, kubectl) are recorded via audit hooks configured by swamp repo init --tool. See The Audit System.

CalVer

Calendar Versioning, the version format used by extensions: YYYY.MM.DD.MICRO. Also used for model type versions. See Extension manifest reference.

CEL

Common Expression Language. Used throughout Swamp for data chaining, querying, conditional logic, and vault references. Expressions appear in YAML wrapped in ${{ }}. See CEL expressions reference.

Collective

An organization in Swamp. Extensions are published under a collective namespace (e.g. @myorg/widget). The @swamp collective is reserved and trusted by default. A collective can be personal (one operative) or shared. See Giga-Swamp and Namespaces.

Always use "collective" in prose — never "organization".

Collective API token

An API key tied to a collective rather than a person. Has explicit scopes (e.g. extensions:push, serve:*). Used for CI/CD, shared tooling, and service accounts. See API Key Scoping.

Data chaining

Using CEL expressions in a workflow to reference the output of one step as input to another. For example, data.latest("check-swamp-club", "result").attributes.status reads the HTTP status from a previous model execution. See The Data Layer.

Data layer

The versioned, immutable, queryable data produced by model executions. Also referred to as The Swamp (capital T). Stored in .swamp/data/. See The Data Layer.

Datastore

The single persistence layer behind the data layer. Three backend options: local .swamp/, external filesystem, or S3-compatible storage. See Datastore Architecture.

Drain

Graceful shutdown of a worker. The worker finishes in-flight work, then exits. Triggered by --max-dispatches, --idle-timeout, or SIGTERM. See Worker Fleets.

Enrollment token

Credential used by a worker to authenticate with the orchestrator on first connection. A fleet token is an enrollment token that allows multiple machines to bind. See Remote Execution.

Extension

A packaged, versioned, publishable unit. Can contain model types, vault providers, datastore providers, reports, and/or workflows. Published to the registry under a collective namespace. See Extensions reference.

File (output)

One of two output kinds from a method execution (the other is resource). An opaque binary or text artifact with a MIME type. Stored but not queryable by field. Supports line-oriented streaming. See Data reference.

Fleet

A group of workers enrolled under a single enrollment token. Eliminates per-machine provisioning — new machines bind with the same token. See Worker Fleets.

forEach

A workflow primitive that expands a step into concurrent iterations, each tracked independently. Iterates over a list produced by a CEL expression. See Workflows reference.

Giga-Swamp

The mode where multiple repositories share a datastore via namespaces. Enables cross-repo data composition. See Giga-Swamp and Namespaces.

Guard

A CEL expression on a workflow step. When the expression evaluates to truthy, the step is skipped. Used for idempotent workflows. See How to make workflows idempotent.

Job

A group of related steps within a workflow. Jobs are the unit of dependency — independent jobs run in parallel. Steps within a job also run in parallel by default. See The Workflow Execution Model.

Lifetime

Determines when data becomes eligible for garbage collection. Five levels: ephemeral (memory only), job (until the job completes), workflow (until the workflow completes), a duration (e.g. 7d), or infinite. See Data Lifetimes.

Manifest

The manifest.yaml file that declares an extension's contents — name, version, model types, workflows, dependencies, platforms, and labels. See Extension manifest reference.

manual_approval

A step type that suspends a workflow run until a human approves or rejects. The run ends and state is persisted to disk — no process stays alive. See Understanding Workflow Suspension.

Method

A named operation on a model — create, start, stop, destroy, sync, lookup, or whatever a type defines. Each execution produces versioned data. See Models, Types, and Methods.

Model

The unit of work in Swamp. Has two halves: a type (reusable TypeScript logic) and a definition (YAML configuration). The type defines methods and schemas; the definition fills in the specifics for one use. See How Swamp Works.

Model definition

A YAML file that instantiates a model type with specific arguments. Created with swamp model create and stored in models/. Definitions are data, not code — an agent produces them by writing YAML that conforms to the type's schema. See Model Definitions reference.

Model type

Reusable TypeScript logic that defines methods, input/output schemas, and execution behaviour for interacting with an external system. Published as part of an extension. See Model type reference.

Namespace

A bounded context identifier stamped onto data at write time in giga-swamp mode. Provides provenance, not isolation — it is an organizational label, not a security boundary. Cross-namespace queries use a prefix syntax: data.latest("infra:my-vpc", "result"). See Giga-Swamp and Namespaces.

Operative

A user of the Swamp platform. The domain entity representing a person's identity and profile.

Always use "operative" in prose — never "operator".

Orchestrator

The machine that owns the durable world: datastores, vault secrets, model definitions, workflows. Manages all access control. Workers connect to it. See Remote Execution.

Output spec

A declaration on a model type of what data it produces — resource or file, with a name, schema, lifetime, and garbage collection policy. Also called data output spec. See Data reference.

Personal API key

An API key tied to an operative's account. Carries full permissions. For interactive work and personal automation. See API Key Scoping.

Placement

Targeting a workflow step to a specific worker by name (target) or by key-value label match (labels). Unplaced steps run on the orchestrator's local loopback. See Workflows reference.

Quality score

A number out of 100, a letter grade (A–F), and a per-factor breakdown measuring extension quality. Not a publishing gate — extensions can publish with any score. See About the Extension Scorecard.

Registry

The distribution mechanism for published extensions. Not a quality guarantee — it tells you an extension exists, not whether it is safe to run. See Extension Trust and the Supply Chain.

Resource

One of two output kinds from a method execution (the other is file). Structured JSON data conforming to a schema. Queryable and composable via CEL expressions. See Data reference.

Run tracker

A local SQLite database (.swamp/run_tracker.db) that tracks in-flight model and workflow executions. Uses heartbeat-based liveness detection. Stale runs are reapable with swamp run doctor. See The Run Tracker.

Skill

A markdown document — not executable code — that teaches an agent how to work with Swamp. Loaded on demand via progressive disclosure: metadata is always visible, the body loads on match, references load on demand. See AI agent integration.

Solo mode

The default repository mode — no namespace, reading and writing at the top level of the datastore. Contrasts with giga-swamp. See Giga-Swamp and Namespaces.

Step

A single unit of work within a job. Runs a model method, an assert check, a manual_approval gate, or a nested workflow. See The Workflow Execution Model.

swamp serve

Turns a Swamp repository into a remote WebSocket API. Single process, single source of truth. Supports scheduled workflow execution via triggers, webhook-driven runs, and worker coordination. See swamp serve.

Trigger

A cron schedule or webhook endpoint attached to a workflow for automatic execution. Cron triggers use standard cron syntax. Webhook triggers accept external HTTP events with provider-specific verification (GitHub, Stripe, Linear, Slack, generic). See Workflows reference.

Trusted collective

A collective whose extensions auto-resolve during install without prompting. Managed per-repository with swamp extension trust add. Only the @swamp collective is trusted by default. See Extension Trust and the Supply Chain.

Vault

A named secret storage backend. Stores and retrieves sensitive values — API keys, passwords, tokens — used in model definitions and workflows. Referenced at runtime via vault.get() CEL expressions, so secrets are never frozen into YAML or stored in the data layer. See Vaults reference.

Vault provider

A swappable backend for vault storage. Built-in: local_encryption (AES-GCM, works out of the box). Extension-provided: AWS Secrets Manager, Azure Key Vault, 1Password, or custom. See Vaults reference.

Verified by Swamp

An editorial badge indicating the Swamp team has reviewed an extension. Separate from the quality score — a high score does not earn the badge, and the badge is not a numeric factor. First-party @swamp extensions earn it automatically. See Extension Trust and the Supply Chain.

Worker

Stateless compute that receives steps from the orchestrator, runs them, and streams results back. Holds no credentials, definitions, or persistent data. All vault resolution and data queries proxy back through the orchestrator. See Remote Execution.

Workflow

A directed acyclic graph (DAG) of jobs, where each job contains steps that run model methods. Jobs execute in dependency order; independent jobs and steps run in parallel. Stored in workflows/. See Workflows reference.