Swamp

Swamp

Core Concepts

• Models — typed resource definitions exposing methods (create, stop, destroy, sync).
• Data — versioned state snapshots produced by method runs; referenced via CEL expressions.
• Workflows — declarative DAGs chaining model methods with guard expressions for idempotent execution and assert steps for validation.
• Vaults — secret storage referenced by models at runtime.
• Extensions — TypeScript packages adding model types, vault backends, datastores, reports, and webhook handlers.
• Grants — authorization rules for swamp serve access control.
• Serve — exposes the repo over the network with TLS and authentication.

Routing Table

Route to the right guide based on what the user needs.

Common Commands

bashCopy code
# Models
swamp model create <type> <name>               # create a model definition
swamp model @<type> method run <method> <name> # run a method on a model
swamp model get <name> --json                  # inspect current model state
swamp model type search [query]                # find available model types
swamp model list                               # list all models in the repo

# Data
swamp data list <name>                         # list data versions for a model
swamp data query '<CEL predicate>'             # query data with CEL expressions
# read one item's latest content (`swamp data get` is deprecated)
swamp data query 'model("<model>") && name == "<data>"' --select content

# Workflows
swamp workflow create <name>                   # create a new workflow
swamp workflow validate <name>                 # validate DAG before running
swamp workflow run <name>                      # execute a workflow
swamp workflow run <name> --input key=value    # execute with inputs
swamp workflow resume <name>                   # resume a suspended workflow
swamp workflow resume <name> --run <id>        # retry a failed run's failed steps
swamp workflow resume <name> --from <step>     # re-enter failed run at step
swamp workflow history search --json           # search run history

# Run tracking
swamp run history                              # recent runs (last 24h)
swamp run history --active                     # what's running right now?
swamp run doctor                               # diagnose stale/orphaned runs
swamp run doctor --fix                         # auto-reap stale runs

# Vaults, Reports, Extensions
swamp vault create <type> <name>               # create a vault for secrets
swamp report run <name>                        # run a report
swamp extension init <name>                    # scaffold a new extension

Workflow

1. Route — match intent to a guide in the routing table.
2. Load — read the guide; load its reference.md if needed, deeper references/ only when the guide says to.
3. Validate — before running any workflow: swamp workflow validate <name>. Before destructive methods (delete, stop, destroy): swamp model get <name> --json to confirm the target exists and is in the expected state. Proceed only when validation passes.
4. Verify args — run swamp help <subcommand> (e.g. swamp help model method run) to confirm exact flags and arguments before executing. The output is structured JSON — the canonical CLI schema.
5. Execute — run the command.
6. On failure — load references/troubleshooting/guide.md and diagnose before retrying or changing definitions.

Rules

1. Use the routing table, not memory. Don't answer from cached knowledge about swamp commands — always load the current guide.
2. Consult the architecture guide for design decisions. Before choosing between primitives (model vs. workflow vs. extension vs. report) or explaining a design trade-off, load references/architecture/guide.md and cite the design doc you relied on.
3. Use swamp commands, don't go around them. Query data with swamp data query, not by grepping .swamp/ files. Interact with resources through model methods, not raw CLI tools when a model type already wraps the API — check with swamp model type search. Composing with --json output (e.g. piping through jq) is fine — the anti-pattern is bypassing swamp entirely.
4. Verify flags with swamp help before executing. swamp help <command> outputs the full CLI schema as structured JSON — every subcommand, argument, and option. Always run it to confirm exact flags before executing a swamp command (workflow step 4). Do not guess flags from memory.