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 behavior — 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.

Behavior

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. Earlier releases called it a model; see Model (compatibility name). See How Swamp Works.

Behavior definition

A YAML file that instantiates a behavior type with specific arguments. Created with swamp behavior 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 Behavior Definitions reference.

Behavior method

See Method.

Behavior output

The record of one method execution on a behavior: its status, logs, and the data artifacts it wrote. Inspected with swamp behavior output. See Create and Run a Behavior.

Behavior type

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

Brief

A markdown file that swamp start writes for each task, at tasks/<date>-<slug>.md in the workspace. Holds the task in the operative's own words and the context the agent reads first. See Start a task with swamp start.

CalVer

Calendar Versioning, the version format used by extensions: YYYY.MM.DD.MICRO. Also used for behavior 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 behavior execution. See The Data Layer.

Data layer

The versioned, immutable, queryable data produced by behavior 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 behavior 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, behavior 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 behavior — create, start, stop, destroy, sync, lookup, or whatever a type defines. Each execution produces versioned data. See Behaviors, Types, and Methods.

Model (compatibility name)

The name earlier Swamp releases gave a behavior. Behavior is the product term; "model" survives only as a literal identifier:

• the legacy swamp model … commands, each a spelling of a swamp behavior … command
• the models/ directory that holds behavior definitions
• serialized and protocol identifiers such as modelName, modelType, model_not_found and the model.method.run audit action
• the CEL model.* namespace and model.method(), and the data query function model(), which also accepts behavior()
• the TypeScript API context.runModel()

Authored files also accept behavior spellings for some model fields — workflow type: behavior with behavior, behaviorType and behaviorName, the behavior grant selector, behaviorName in data queries, extensions/behaviors/, export const behavior and a behaviors: manifest key. Swamp records the model form. See Compatibility with model commands.

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, behavior definitions, workflows. Manages all access control. Workers connect to it. See Remote Execution.

Output spec

A declaration on a behavior 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 behavior and workflow executions. Records who initiated each run (initiatedBy) and 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 behavior 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 behavior 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 behavior methods. Jobs execute in dependency order; independent jobs and steps run in parallel. Stored in workflows/. See Workflows reference.

Workspace

A Swamp repository that Swamp keeps track of in the workspace registry. Created or imported by swamp start or swamp workspace, and holds every brief given to it. Every other command works in a workspace unchanged. See Workspace Commands.