fix: v0.2.0 release hardening — security, code quality, docs accuracy

Security:
- Docker: restrict network mode to bridge/none (prevent host network escape)
- Docker: drop all capabilities, set no-new-privileges, PID limit 512
- Docker: block dangerous mount targets (/proc, /sys, /dev, docker.sock)
- CEL: bound split() to 10k parts, flatten() to 100k elements
- CEL: cap jsonDecode input to 1MB
- CEL: bound program cache to 10k entries (prevent unbounded growth)
- Engine: use os.Lstat for artifact stat (symlink defense-in-depth)

Code quality:
- Docker: replace log.Printf with structured slog throughout
- Docker: document limitWriter drain semantics (io.Writer contract)
- Engine: replace defer-in-retry-loop with explicit cleanup
- Engine: fix %v → %w for proper error chain wrapping
- Artifact store: wrap rows.Err() with context, add ErrNotFound sentinel
- Artifact reaper: handle os.ErrNotExist (force-delete orphaned metadata)
- Artifact reaper: wire into server.go with periodic sweep goroutine

Documentation:
- Fix broken example YAMLs (inputs format, field names, CEL variables)
- Add tmp block to configuration full example
- Add cross-links between artifacts and docker-workflows docs
- Document registry_credential as step-level field
- Document container security hardening in connector reference
- Clarify toString() vs string() in expressions reference
- Update Slack channel param to document both ID and name formats

Testing:
- Add CI-aware fatal guards to all 8 testcontainers helpers
- Add TestDockerRun_RejectsHostNetwork
- Add -race flag to Makefile test target

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: michaelmcnees

Makefile

@@ -11,7 +11,7 @@ build:
 	go build -ldflags "$(LDFLAGS)" -o mantle ./cmd/mantle
 
 test:
-	go test ./...
+	go test -race ./...
 
 lint:
 	golangci-lint run

examples/ai-tool-use.yaml

@@ -2,7 +2,7 @@ name: research-assistant
 description: AI agent that searches the web and summarizes findings
 
 inputs:
-  - name: topic
+  topic:
     type: string
     description: Research topic
 

examples/db-backup.yaml

@@ -9,7 +9,7 @@ inputs:
   database_url:
     type: string
     description: Postgres connection URL to back up
-    default: "{{ env.MANTLE_DATABASE_URL }}"
+    default: "{{ env.DATABASE_URL }}"
   s3_bucket:
     type: string
     description: S3 bucket for backup storage
@@ -75,7 +75,7 @@ steps:
         Today's date is {{ env.MANTLE_ENV_DATE }}.
 
         Files:
-        {{ steps.list-backups.output.keys }}
+        {{ steps.list-backups.output.objects }}
 
         Return an empty array [] if nothing should be deleted.
       output_schema:

examples/docker-volume-backup.yaml

@@ -32,25 +32,14 @@ steps:
     timeout: "5m"
     params:
       bucket: my-backups
-      key: "volumes/my-app-data/{{ date }}/backup.tar.gz"
+      key: "volumes/my-app-data/backup.tar.gz"
       content: "{{ artifacts['backup-archive'].url }}"
       content_type: "application/gzip"
 
   - name: notify-success
     action: slack/send
     credential: slack-token
-    if: "steps['upload-to-s3'].error == null && steps['upload-to-s3'].output.size > 0"
+    depends_on: [upload-to-s3]
     params:
       channel: "#ops-alerts"
       text: "Volume backup completed — {{ artifacts['backup-archive'].size }} bytes uploaded to s3://my-backups/volumes/my-app-data/"
-
-  # NOTE: notify-failure requires continue_on_error support (see issue #29).
-  # Without it, the engine halts on the first failed step and this step
-  # will not execute. This is included to show the intended pattern.
-  - name: notify-failure
-    action: slack/send
-    credential: slack-token
-    if: "steps['upload-to-s3'].error != null || steps['backup-volume'].error != null"
-    params:
-      channel: "#ops-alerts"
-      text: "Volume backup FAILED"

examples/s3-backup.yaml

@@ -32,4 +32,4 @@ steps:
       bucket: "mantle-backups"
       key: "daily-export/posts-{{ steps['fetch-data'].output.json[0].id }}.json"
       content_type: "application/json"
-      body: "{{ steps['fetch-data'].output.body }}"
+      content: "{{ steps['fetch-data'].output.body }}"

examples/webhook-processor.yaml

@@ -23,8 +23,8 @@ steps:
         Content-Type: "application/json"
       body:
         title: "Webhook payload received"
-        body: "{{ inputs.trigger.payload }}"
-        source_path: "{{ inputs.trigger.path }}"
+        body: "{{ trigger.payload }}"
+        source_path: "{{ trigger.path }}"
 
   - name: log-success
     action: http/request

internal/artifact/reaper.go

@@ -2,8 +2,10 @@ package artifact
 
 import (
 	"context"
+	"errors"
 	"fmt"
 	"log/slog"
+	"os"
 	"time"
 )
 
@@ -40,9 +42,14 @@ func (r *Reaper) Sweep(ctx context.Context) (int, error) {
 	for _, a := range expired {
 		// Delete file from tmp storage.
 		if delErr := r.TmpStorage.Delete(ctx, a.URL); delErr != nil {
-			logger.Error("failed to delete artifact file",
-				"artifact", a.Name, "url", a.URL, "error", delErr)
-			continue // skip metadata deletion if file delete failed
+			// If the blob is already gone, still clean up the metadata.
+			if !errors.Is(delErr, os.ErrNotExist) {
+				logger.Error("failed to delete artifact file",
+					"artifact", a.Name, "url", a.URL, "error", delErr)
+				continue // skip metadata deletion if file delete genuinely failed
+			}
+			logger.Warn("artifact file already missing, cleaning metadata",
+				"artifact", a.Name, "url", a.URL)
 		}
 
 		// Delete metadata from database.

internal/artifact/store.go

@@ -3,10 +3,14 @@ package artifact
 import (
 	"context"
 	"database/sql"
+	"errors"
 	"fmt"
 	"time"
 )
 
+// ErrNotFound is returned when an artifact does not exist.
+var ErrNotFound = errors.New("artifact not found")
+
 // Artifact represents metadata for a persisted artifact.
 type Artifact struct {
 	ID          string
@@ -45,7 +49,7 @@ func (s *Store) GetByName(ctx context.Context, executionID, name string) (*Artif
 		WHERE execution_id = $1 AND name = $2
 	`, executionID, name).Scan(&a.ID, &a.ExecutionID, &a.StepName, &a.Name, &a.URL, &a.Size, &a.CreatedAt)
 	if err == sql.ErrNoRows {
-		return nil, fmt.Errorf("artifact %q not found for execution %s", name, executionID)
+		return nil, fmt.Errorf("artifact %q not found for execution %s: %w", name, executionID, ErrNotFound)
 	}
 	if err != nil {
 		return nil, fmt.Errorf("artifact get: %w", err)
@@ -74,7 +78,10 @@ func (s *Store) ListByExecution(ctx context.Context, executionID string) ([]Arti
 		}
 		artifacts = append(artifacts, a)
 	}
-	return artifacts, rows.Err()
+	if err := rows.Err(); err != nil {
+		return nil, fmt.Errorf("artifact list: %w", err)
+	}
+	return artifacts, nil
 }
 
 // DeleteByExecution removes all artifact metadata for an execution.
@@ -120,5 +127,8 @@ func (s *Store) ListExpired(ctx context.Context, olderThan time.Duration) ([]Art
 		}
 		artifacts = append(artifacts, a)
 	}
-	return artifacts, rows.Err()
+	if err := rows.Err(); err != nil {
+		return nil, fmt.Errorf("artifact list expired: %w", err)
+	}
+	return artifacts, nil
 }

internal/auth/auth_test.go

@@ -5,6 +5,7 @@ import (
 	"database/sql"
 	"net/http"
 	"net/http/httptest"
+	"os"
 	"testing"
 	"time"
 
@@ -32,6 +33,9 @@ func setupTestStore(t *testing.T) *Store {
 		),
 	)
 	if err != nil {
+		if os.Getenv("CI") != "" {
+			t.Fatalf("Could not start Postgres container (CI): %v", err)
+		}
 		t.Skipf("Could not start Postgres container: %v", err)
 	}
 	t.Cleanup(func() { pgContainer.Terminate(ctx) })

internal/budget/store_test.go

@@ -3,6 +3,7 @@ package budget_test
 import (
 	"context"
 	"database/sql"
+	"os"
 	"testing"
 	"time"
 
@@ -32,6 +33,9 @@ func setupTestDB(t *testing.T) *sql.DB {
 		),
 	)
 	if err != nil {
+		if os.Getenv("CI") != "" {
+			t.Fatalf("Could not start Postgres container (CI): %v", err)
+		}
 		t.Skipf("Could not start Postgres container: %v", err)
 	}
 	t.Cleanup(func() {