What's Changed

• fix: resolve vault expressions in readResource() (#712)

Closes #710

Summary

• Add resolveVaultRefsInData() to transparently resolve vault expression strings (${{ vault.get('...', '...') }}) back to their original secret values when reading resource data via readResource()
• Wire VaultService and SecretRedactor from the execution context into createResourceReader() in RawExecutionDriver
• Add runtime validation that JSON.parse returns a plain object (not an array or primitive), fixing a type safety gap where the Record<string, unknown> return type was not enforced

Why this is needed

When extension models write resource data with sensitive fields, processSensitiveResourceData() replaces actual values with vault expression strings like ${{ vault.get('vault-name', 'key') }}. Before this change, readResource() returned these as literal strings, which meant:

1. Leaked vault internals — extension authors had to know about and parse vault expression syntax
2. Confusing errors — code expecting an API key got a template string instead, causing opaque failures downstream
3. Broken round-trips — write a secret, read it back, get something completely different

How it works

• After JSON parsing, resolveVaultRefsInData() recursively walks all string values in the result object
• Strings matching the vault ref pattern (anchored regex — must be the entire string) are resolved via VaultService.get()
• Resolved secrets are registered with SecretRedactor.addSecret() to prevent log leakage
• Without a VaultService, behavior is unchanged (backward compatible)
• The JSON parse type safety fix ensures corrupted/manually-edited data files fail fast with a clear error instead of silently returning wrong types

Files changed

Test plan

• deno check — type checking passes
• deno lint — no lint errors
• deno fmt — properly formatted
• deno run test — all 2967 tests pass (48 in data_writer_test.ts)
• deno run compile — binary compiles successfully

🤖 Generated with Claude Code

Co-authored-by: Blake Irvin blakeirvin@me.com

Installation

macOS (Apple Silicon):

curl -L https://github.com/systeminit/swamp/releases/download/v20260315.000926.0-sha.aa09224f/swamp-darwin-aarch64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

macOS (Intel):

curl -L https://github.com/systeminit/swamp/releases/download/v20260315.000926.0-sha.aa09224f/swamp-darwin-x86_64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

Linux (x86_64):

curl -L https://github.com/systeminit/swamp/releases/download/v20260315.000926.0-sha.aa09224f/swamp-linux-x86_64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

Linux (aarch64):

curl -L https://github.com/systeminit/swamp/releases/download/v20260315.000926.0-sha.aa09224f/swamp-linux-aarch64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

What's Changed

• feat: add readResource() to MethodContext (#711)

Summary

• Add symmetric readResource(instanceName, version?) convenience method to MethodContext, eliminating the JSON.parse(new TextDecoder().decode(context.dataRepository.getContent(...))) boilerplate every extension model repeats when reading stored data
• Create createResourceReader() factory in data_writer.ts alongside the existing createResourceWriter() for symmetry
• Wire readResource into the raw execution driver and add a stub in the Docker runner (returns null with warning since containers lack host data access)
• Update all extension model docs (API reference, SKILL.md, examples, scenarios) to use readResource as the preferred read path

User impact

Extension model authors can now read stored resource data with one call:

// Before (every model repeated this)
const content = await context.dataRepository.getContent(
  context.modelType, context.modelId, "vpc");
if (!content) throw new Error("...");
const data = JSON.parse(new TextDecoder().decode(content));

// After
const data = await context.readResource!("vpc");
if (!data) throw new Error("...");

Vault reference expressions are returned as-is (not resolved). The low-level getContent() remains available for binary data.

Test plan

• 4 unit tests for createResourceReader (happy path, null for missing data, version passthrough, vault reference preservation)
• 1 test verifying readResource is available on context during method execution
• deno check passes
• deno lint passes
• deno fmt passes
• Full test suite passes (2957 tests, 0 failures)
• deno run compile succeeds

Closes #709
Closes #708

🤖 Generated with Claude Code

Co-authored-by: Blake Irvin blakeirvin@me.com

Installation

macOS (Apple Silicon):

curl -L https://github.com/systeminit/swamp/releases/download/v20260314.235538.0-sha.0cbfc0e8/swamp-darwin-aarch64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

macOS (Intel):

curl -L https://github.com/systeminit/swamp/releases/download/v20260314.235538.0-sha.0cbfc0e8/swamp-darwin-x86_64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

Linux (x86_64):

curl -L https://github.com/systeminit/swamp/releases/download/v20260314.235538.0-sha.0cbfc0e8/swamp-linux-x86_64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

Linux (aarch64):

curl -L https://github.com/systeminit/swamp/releases/download/v20260314.235538.0-sha.0cbfc0e8/swamp-linux-aarch64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

What's Changed

• fix: add 'install' as alias for 'extension pull' (#704)

Summary

• Add .alias("install") to the extension pull command so swamp extension install works as expected
• AI agents naturally try swamp extension install which previously failed with a confusing error

Closes #702

Test plan

• deno check passes
• deno lint passes
• swamp extension --help shows pull, install in the command list
• swamp extension install <ext> routes to the pull handler

🤖 Generated with Claude Code

Installation

macOS (Apple Silicon):

curl -L https://github.com/systeminit/swamp/releases/download/v20260313.235152.0-sha.bb94615c/swamp-darwin-aarch64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

macOS (Intel):

curl -L https://github.com/systeminit/swamp/releases/download/v20260313.235152.0-sha.bb94615c/swamp-darwin-x86_64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

Linux (x86_64):

curl -L https://github.com/systeminit/swamp/releases/download/v20260313.235152.0-sha.bb94615c/swamp-linux-x86_64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

Linux (aarch64):

curl -L https://github.com/systeminit/swamp/releases/download/v20260313.235152.0-sha.bb94615c/swamp-linux-aarch64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

What's Changed

• feat: pluggable execution drivers with Docker support (#703)

Fixes: #701

Summary

• Pluggable execution driver abstraction — a new ExecutionDriver interface that decouples where a model method runs from what it does. Two built-in drivers: raw (in-process, the default) and docker (containerized).
• Docker bundle mode — extension models (TypeScript) can now run inside Docker containers with no code changes. Swamp auto-generates a self-contained JavaScript bundle (zod inlined) and executes it via an embedded runner script inside the container.
• Comprehensive documentation — design doc (design/execution-drivers.md), skill reference files for swamp-model, swamp-workflow, and swamp-extension-model, all registered in BUNDLED_SKILLS for repo init/repo upgrade.

User Impact

New CLI flags

swamp model method run my-model execute --driver docker
swamp workflow run my-workflow --driver docker

Definition-level driver config

Models and workflows can declare their driver in YAML:

driver: docker
driverConfig:
  image: "alpine:latest"
  bundleImage: "denoland/deno:alpine"
  timeout: 30000
  memory: "512m"

Multi-level configuration

Driver config can be set at workflow, job, or step level. Resolution priority (first match wins): CLI flag > step > job > workflow > definition > raw default.

Podman / nerdctl support

Set command: "podman" (or nerdctl) in driverConfig to use alternative container runtimes.

Extension model Docker execution

TypeScript extension models work in Docker with zero changes — context.writeResource(), context.createFileWriter(), and context.logger all behave identically. The only limitation: getFilePath() throws in Docker mode.

No breaking changes

Existing models, workflows, and extensions continue to work unchanged. The default driver remains raw (in-process).

Commits

1. 6d24aed4 — feat: add pluggable execution driver abstraction
   Core ExecutionDriver interface, ExecutionRequest/DriverOutput/ExecutionResult types, raw and docker drivers, driver type registry, multi-level config resolution, CLI --driver flag, and integration with the method execution service.

2. 13bc6443 — feat: add Docker bundle mode for TypeScript extension models
   Self-contained bundling (bundleExtension({ selfContained: true })), embedded Docker runner script, bundleImage config field, ModelDefinition.bundleSource, dual-mode detection (command vs bundle), and full test coverage.

3. fb3ca28f — docs: add execution driver documentation and skill references
   Design doc with ASCII flow diagrams and implementation file tables, three skill reference files (model, workflow, extension-model), --driver rows in SKILL.md option tables, BUNDLED_SKILLS registration.

Test plan

• deno check — type checking passes
• deno lint — no lint errors
• deno fmt — all files formatted
• deno run test — 2952 tests pass
• deno run compile — binary compiles with new skill files embedded
• Manual: swamp model method run <model> <method> --driver docker with a command/shell model
• Manual: swamp model method run <model> <method> --driver docker with an extension model (bundle mode)
• Manual: verify --driver flag on swamp workflow run

🤖 Generated with Claude Code

Installation

macOS (Apple Silicon):

curl -L https://github.com/systeminit/swamp/releases/download/v20260313.230033.0-sha.9ad8cbad/swamp-darwin-aarch64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

macOS (Intel):

curl -L https://github.com/systeminit/swamp/releases/download/v20260313.230033.0-sha.9ad8cbad/swamp-darwin-x86_64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

Linux (x86_64):

curl -L https://github.com/systeminit/swamp/releases/download/v20260313.230033.0-sha.9ad8cbad/swamp-linux-x86_64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

Linux (aarch64):

curl -L https://github.com/systeminit/swamp/releases/download/v20260313.230033.0-sha.9ad8cbad/swamp-linux-aarch64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

What's Changed

• fix: warn when check has empty appliesTo array (#698)

Summary

• Adds validation warning when a check has appliesTo: [] (empty array), which silently disables the check since no method name can match
• The warning message tells the author to either remove appliesTo or populate it with method names

Addresses review feedback from #697.

Review comment #2 (execution order)

The second comment about non-deterministic check execution order across extension loads is acknowledged but not actioned. Checks are documented as stateless and independent — order should not matter. Object.entries preserves insertion order per spec, and extension merging via spread is deterministic for a given set of extensions.

Test plan

• New test: validateModel warns when appliesTo is empty array
• All 56 validation service tests pass

🤖 Generated with Claude Code

Installation

macOS (Apple Silicon):

curl -L https://github.com/systeminit/swamp/releases/download/v20260312.232506.0-sha.dfa7c4e9/swamp-darwin-aarch64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

macOS (Intel):

curl -L https://github.com/systeminit/swamp/releases/download/v20260312.232506.0-sha.dfa7c4e9/swamp-darwin-x86_64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

Linux (x86_64):

curl -L https://github.com/systeminit/swamp/releases/download/v20260312.232506.0-sha.dfa7c4e9/swamp-linux-x86_64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

Linux (aarch64):

curl -L https://github.com/systeminit/swamp/releases/download/v20260312.232506.0-sha.dfa7c4e9/swamp-linux-aarch64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

What's Changed

• feat: add pre-flight checks for model method execution (#697)

Summary

Adds pre-flight checks that run automatically before mutating model methods (create/update/delete/action), catching invalid inputs early with clear error messages instead of letting them fail as raw API errors.

Closes #619

Core Implementation

• CheckDefinition interface with description, labels, appliesTo, and execute(context) => CheckResult
• CheckResult with pass: boolean and optional errors: string[]
• Checks run automatically before mutating methods; read/list methods skip checks
• isMutatingKind() helper for method kind classification

Extension Checks

• ModelRegistry.extend() accepts optional third checks parameter
• Extension checks merge with model-type checks; conflicts throw at registration time
• Extension checks format matches methods: array of Record<string, CheckDefinition>

Definition-Level Check Selection

• CheckSelection type: { require?: string[]; skip?: string[] } on definitions
• skip always wins (even over require)
• require checks are immune to CLI skip flags (--skip-checks, --skip-check, --skip-check-label)
• Validation warns on nonexistent check names and require/skip overlap

CLI Flags

• model method run: --skip-checks, --skip-check <name>, --skip-check-label <label>
• model validate: --label <label>, --method <method> for check filtering

Validation Service

• Check results appear alongside schema validations in model validate output
• Label and method filtering for targeted check execution
• Definition-level skip lists honored during validation

Test plan

• 17 new unit tests covering all check behaviors (pass/fail, filtering, skip flags, extension merging, definition-level selection)
• Integration tests updated for new validation count
• All 2875 tests pass
• deno check, deno lint, deno fmt pass
• End-to-end tested with command/shell model extension checks:
  • Check pass/fail on method execution
  • Label-based filtering (--skip-check-label)
  • Named check skipping (--skip-check)
  • Skip all checks (--skip-checks)
  • Definition-level require (immune to skip flags)
  • Definition-level skip (overrides require)
  • model validate with --label and --method filtering
  • Invalid check selection validation warnings

🤖 Generated with Claude Code

Installation

macOS (Apple Silicon):

curl -L https://github.com/systeminit/swamp/releases/download/v20260312.231622.0-sha.27c95bb0/swamp-darwin-aarch64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

macOS (Intel):

curl -L https://github.com/systeminit/swamp/releases/download/v20260312.231622.0-sha.27c95bb0/swamp-darwin-x86_64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

Linux (x86_64):

curl -L https://github.com/systeminit/swamp/releases/download/v20260312.231622.0-sha.27c95bb0/swamp-linux-x86_64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

Linux (aarch64):

curl -L https://github.com/systeminit/swamp/releases/download/v20260312.231622.0-sha.27c95bb0/swamp-linux-aarch64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

What's Changed

• fix: use write lock for evaluate commands (#695)

Summary

Follow-up to #694 — model evaluate and workflow evaluate were incorrectly migrated to the read-only path, but both commands persist evaluated definitions/workflows via .save() that are consumed by subsequent run commands. They must hold the datastore lock.

Fixes the blocking review feedback from #694.

Test Plan

• deno check passes
• deno lint passes
• deno fmt --check passes
• deno run test — all 2839 tests pass

🤖 Generated with Claude Code

Installation

macOS (Apple Silicon):

curl -L https://github.com/systeminit/swamp/releases/download/v20260312.014128.0-sha.a040be69/swamp-darwin-aarch64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

macOS (Intel):

curl -L https://github.com/systeminit/swamp/releases/download/v20260312.014128.0-sha.a040be69/swamp-darwin-x86_64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

Linux (x86_64):

curl -L https://github.com/systeminit/swamp/releases/download/v20260312.014128.0-sha.a040be69/swamp-linux-x86_64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

Linux (aarch64):

curl -L https://github.com/systeminit/swamp/releases/download/v20260312.014128.0-sha.a040be69/swamp-linux-aarch64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

What's Changed

• fix: skip datastore lock for read-only CLI commands (#694)

Summary

Fixes #692 — read-only CLI commands no longer acquire the exclusive datastore lock, allowing them to run concurrently with write operations like workflow runs.

Previously, every CLI command went through requireInitializedRepo() which acquired an exclusive distributed lock. This meant that running swamp workflow search or swamp data list while a workflow was executing would block for ~60 seconds then fail with a lock timeout error.

Changes

• New function requireInitializedRepoReadOnly() in repo_context.ts — builds the full RepositoryContext but skips lock acquisition and datastore sync. This follows the existing pattern where breakglass commands (datastore lock status) already bypass locking via resolveDatastoreForRepo().
• 33 read-only commands migrated to use the new function: all search, get, list, validate, evaluate, describe, history, logs, data, schema, summarise, audit, telemetry stats, datastore status, and extension list/search commands.
• Write commands unchanged — create, edit, delete, run, gc, rename, setup, sync, pull, push, rm, update, fmt continue to acquire the lock via requireInitializedRepo().
• Updated design docs (design/datastores.md) and skills (.claude/skills/swamp-repo/SKILL.md) to document the read-only vs write distinction.
• 4 new tests including a concurrency test that proves the read-only path succeeds while the write lock is held.

Why this is safe

All file writes in the codebase use atomic write-to-temp-then-rename (atomicWriteTextFile), so concurrent reads never see partial or corrupt files. The lock's purpose is to prevent concurrent writes from corrupting state — concurrent reads are inherently safe.

Trade-offs

Filesystem datastores: No trade-off. Both read and write paths access the same .swamp/ directory, so reads see writes immediately.

S3 datastores: Read-only commands read from the local S3 cache without pulling latest from S3 first. This means during a running workflow, a concurrent read in another terminal sees the cache as it was before the workflow started. This is acceptable because:

• Write commands always call pullChanged() before executing, so data is fresh when it matters (during execution)
• Once a write command finishes, the next write in any terminal pulls the latest
• Users can run swamp datastore sync --pull to explicitly refresh the cache
• The alternative (blocking all reads for 60s+ during any write) is a much worse UX than slightly stale read results

Test Plan

• deno check — type checking passes
• deno lint — no lint errors
• deno fmt --check — formatting clean
• deno run test — all 2839 tests pass
• New test: requireInitializedRepoReadOnly - does not block concurrent access verifies read-only path succeeds while write lock is held
• Manual: run swamp workflow run <workflow> --json then concurrently run swamp workflow search <query> --json — search should return immediately instead of blocking

🤖 Generated with Claude Code

Installation

macOS (Apple Silicon):

curl -L https://github.com/systeminit/swamp/releases/download/v20260312.011512.0-sha.4fc37f53/swamp-darwin-aarch64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

macOS (Intel):

curl -L https://github.com/systeminit/swamp/releases/download/v20260312.011512.0-sha.4fc37f53/swamp-darwin-x86_64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

Linux (x86_64):

curl -L https://github.com/systeminit/swamp/releases/download/v20260312.011512.0-sha.4fc37f53/swamp-linux-x86_64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

Linux (aarch64):

curl -L https://github.com/systeminit/swamp/releases/download/v20260312.011512.0-sha.4fc37f53/swamp-linux-aarch64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

What's Changed

• docs: document instance name uniqueness constraint (#661) (#691)

Summary

• Documents that instance names must be unique across all specs within a method execution, since they map directly to storage paths on disk with no spec component
• Adds a "Duplicate data instance name" troubleshooting entry with the fix pattern (prefix instance names)
• Updates the writeResource API docs to call out the uniqueness constraint

This is a skills/docs-only change — no code changes. After investigating #661, we determined this is by-design behavior: instance names map to storage paths on disk (.swamp/data/{type}/{model}/{instanceName}/), and there's no spec component in the path. The duplicate name validation exists to catch collisions before they silently overwrite data. The gap was in our documentation, not the code.

Test plan

• Verify skill docs render correctly
• No code changes, no tests to run

🤖 Generated with Claude Code

Installation

macOS (Apple Silicon):

curl -L https://github.com/systeminit/swamp/releases/download/v20260311.230128.0-sha.9641c815/swamp-darwin-aarch64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

macOS (Intel):

curl -L https://github.com/systeminit/swamp/releases/download/v20260311.230128.0-sha.9641c815/swamp-darwin-x86_64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

Linux (x86_64):

curl -L https://github.com/systeminit/swamp/releases/download/v20260311.230128.0-sha.9641c815/swamp-linux-x86_64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

Linux (aarch64):

curl -L https://github.com/systeminit/swamp/releases/download/v20260311.230128.0-sha.9641c815/swamp-linux-aarch64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

What's Changed

• fix: add rollback and depth warning to data rename (#690)

Summary

Addresses two findings from the adversarial review of #689 (data rename feature):

• Non-atomic rename rollback: The rename operation has two write phases — save new data, then write tombstone. If the tombstone write fails (e.g., disk full, permission error), the system was left with both names pointing to valid active data and no forward reference. Now wraps the tombstone phase in try/catch and rolls back the newly saved data on failure, removing the version directory and cleaning up the data name directory if it was the only version.

• Deep rename chain warning: When forward-reference depth exceeds 5 (e.g., A→B→C→D→E→F), findByName was silently returning null. Now logs a warning: Rename chain depth exceeded for "<name>" (model <id>). Data exists but is unreachable — simplify the rename chain. This applies to both the async and sync code paths.

Test plan

• deno fmt — passed
• deno lint — passed
• deno check — passed
• deno run test — 2835 passed, 0 failed
• deno run compile — successful

🤖 Generated with Claude Code

Installation

macOS (Apple Silicon):

curl -L https://github.com/systeminit/swamp/releases/download/v20260311.215040.0-sha.719c1b5b/swamp-darwin-aarch64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

macOS (Intel):

curl -L https://github.com/systeminit/swamp/releases/download/v20260311.215040.0-sha.719c1b5b/swamp-darwin-x86_64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

Linux (x86_64):

curl -L https://github.com/systeminit/swamp/releases/download/v20260311.215040.0-sha.719c1b5b/swamp-linux-x86_64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/

Linux (aarch64):

curl -L https://github.com/systeminit/swamp/releases/download/v20260311.215040.0-sha.719c1b5b/swamp-linux-aarch64 -o swamp
chmod +x swamp && sudo mv swamp /usr/local/bin/