Support pre-flight validate method on models before method execution

[stack72]

Problem

When a model method like create is executed, it goes straight to the API call with no pre-flight checks. If the inputs are invalid (e.g. a VPC CIDR range that overlaps with existing VPCs, or a region that doesn't support a given droplet size), the user only finds out via a raw API error response that is difficult to interpret.

Real-world scenario encountered:

1. User configures a VPC with CIDR 10.116.0.0/24
2. Runs create method
3. DigitalOcean API returns a 422 with a JSON blob about overlapping ranges
4. User has to parse the raw error to understand the problem
5. This could have been caught before the API call by listing existing VPCs and checking for CIDR overlap

Proposed Solution

If a model defines a validate method, swamp should automatically call it before executing the requested method (e.g. create, update). This gives models a hook to run pre-flight checks against live API state.

How it would work:

• Model authors define an optional validate method on their model
• Before executing any other method, swamp checks if validate exists and runs it first
• If validate fails (throws an error or returns validation errors), the method execution is aborted with a clear error message
• If validate succeeds, the requested method proceeds as normal

Example use cases for validate:

• VPC: Check existing VPCs for CIDR overlap before creating
• Droplet: Verify the image slug and size are available in the target region
• Load Balancer: Verify the target tag exists and has matching droplets
• Firewall: Verify referenced load_balancer_uids exist

Scope of Changes

• Model execution engine — Add a pre-execution phase that checks for and runs a validate method before the target method
• Extension model contract — Document the validate method convention and what it should return (pass/fail with messages)
• Workflow engine — Ensure validation errors are surfaced clearly in workflow step output, distinct from execution errors
• Code generation — Auto-generated models could include common validation patterns (e.g. "does this resource name already exist")

This would catch configuration errors early with clear messages, rather than relying on raw API error responses after the fact.

[stack72]

Implementation Plan: Pre-flight Checks for Model Execution

Design

Add checks to ModelDefinition — a Record<string, CheckDefinition> following the same pattern as methods, resources, and files. Checks use a uniform interface with free-form labels for filtering and optional appliesTo for method scoping.

The API is intentionally open — the same execute(context) => CheckResult signature supports value validation, cross-model checks, live API checks, OPA policy evaluation, or any future check type without framework changes.

Core Interfaces

export interface CheckResult {
  pass: boolean;
  errors?: string[];
}

export interface CheckDefinition {
  description: string;
  labels?: string[];       // free-form, for filtering (e.g., ["offline", "api", "cross-model"])
  appliesTo?: string[];    // method names; omit = all mutating methods
  execute(context: MethodContext): Promise<CheckResult>;
}

ModelDefinition gets a new optional field:

checks?: Record<string, CheckDefinition>;

Example: aws/ec2-subnet model

export const model = {
  type: "aws/ec2-subnet",
  version: "2026.03.12.1",
  globalArguments: SubnetSchema,

  checks: {
    "valid-cidr-range": {
      description: "CIDR prefix must be between /16 and /28",
      labels: ["offline", "fast"],
      appliesTo: ["create", "update"],
      execute: async (context) => {
        const prefix = parseInt((context.globalArgs.cidrBlock as string).split("/")[1]);
        if (prefix < 16 || prefix > 28) {
          return { pass: false, errors: [`CIDR prefix /${prefix} is outside /16-/28`] };
        }
        return { pass: true };
      },
    },

    "no-cidr-overlap-definitions": {
      description: "CIDR must not overlap with other subnet definitions in repo",
      labels: ["offline", "cross-model"],
      appliesTo: ["create"],
      execute: async (context) => {
        const allSubnets = await context.definitionRepository.findAll(
          ModelType.create("aws/ec2-subnet"),
        );
        const errors = allSubnets
          .filter(s => s.id !== context.definition.id)
          .filter(s => cidrsOverlap(context.globalArgs.cidrBlock, s.globalArguments.cidrBlock))
          .map(s => `Overlaps with "${s.name}" (${s.globalArguments.cidrBlock})`);
        return errors.length > 0 ? { pass: false, errors } : { pass: true };
      },
    },

    "no-cidr-overlap-aws": {
      description: "CIDR must not overlap with existing AWS subnets",
      labels: ["api", "slow"],
      appliesTo: ["create"],
      execute: async (context) => {
        const ec2 = new EC2Client({});
        const response = await ec2.send(new DescribeSubnetsCommand({
          Filters: [{ Name: "vpc-id", Values: [context.globalArgs.vpcId] }],
        }));
        const errors = (response.Subnets ?? [])
          .filter(s => cidrsOverlap(context.globalArgs.cidrBlock, s.CidrBlock))
          .map(s => `Overlaps with ${s.SubnetId} (${s.CidrBlock})`);
        return errors.length > 0 ? { pass: false, errors } : { pass: true };
      },
    },

    "no-attached-enis": {
      description: "No network interfaces attached to this subnet",
      labels: ["api"],
      appliesTo: ["delete"],
      execute: async (context) => {
        // Check for attached ENIs before allowing delete
        return { pass: true };
      },
    },
  },

  resources: { /* ... */ },
  methods: {
    create: { /* only runs if all applicable checks pass */ },
    delete: { /* only runs if "no-attached-enis" passes */ },
  },
};

CLI Experience

# Checks run automatically before method execution
swamp model method run my-subnet create

# Skip specific checks
swamp model method run my-subnet create --skip-check no-cidr-overlap-aws
swamp model method run my-subnet create --skip-check-label slow
swamp model method run my-subnet create --skip-checks

# Standalone validation (dry-run)
swamp model validate my-subnet
swamp model validate my-subnet --label offline    # only offline checks
swamp model validate my-subnet --method create    # only create-applicable checks
swamp model validate                              # all models

Engine Behavior

In DefaultMethodExecutionService.executeWorkflow(), after arg validation/upgrade and before method.execute():

1. If modelDef.checks exists and method kind is mutating (create/update/delete/action)
2. Filter checks by appliesTo (must match current method or be unset)
3. Filter by --skip-check-label / --skip-check flags
4. Run remaining checks, collect all failures
5. If any fail → abort with UserError listing each check name and errors

Three Check Types Supported

Type	What it does	Example labels	I/O
Value/policy	Pure logic against globalArgs	["offline", "fast"]	None
Cross-model	Queries definitionRepository.findAll()	["offline", "cross-model"]	Repo reads
Live API	Calls cloud APIs to verify state	["api", "slow"]	Network

All three use the identical CheckDefinition interface. Labels are conventions, not enforced categories.

Extensibility

The execute(context: MethodContext) => Promise<CheckResult> signature is deliberately open. MethodContext provides repoDir (filesystem), definitionRepository, dataRepository, and logger. This means checks can also:

• Read policy files (JSON/YAML) from the repo and evaluate them
• Load OPA WASM bundles and evaluate Rego policies
• Call external policy servers
• Use CEL expressions against definitions

None require framework changes — they are implementation details inside execute(). Helper functions like opaCheck() can be built as utilities that return CheckDefinition.

Implementation Steps

Step	File	Change
1	src/domain/models/model.ts	Add CheckResult, CheckDefinition interfaces, checks? on ModelDefinition, skip fields on MethodContext
2	src/domain/models/method_execution_service.ts	Run checks in executeWorkflow() before method execution
3	src/domain/models/validation_service.ts	Run checks during validateModel() for standalone dry-run
4	src/domain/models/user_model_loader.ts	Add checks to UserModelSchema and convertToModelDefinition()
5	src/cli/commands/model_method_run.ts	Add --skip-check, --skip-check-label, --skip-checks flags
6	src/cli/commands/model_validate.ts	Add --label, --method flags
7	src/presentation/output/model_validate_output.ts	Verify existing rendering handles check results (no changes expected)
8	src/domain/workflows/execution_service.ts	Verify checks run automatically via executeWorkflow() (no changes needed)
9	.claude/skills/swamp-{extension-model,model,troubleshooting}/	Document checks in skills
10	design/models.md, design/workflow.md	Document checks in design docs

Why This Design

• No fixed check categories — free-form labels, not hardcoded buckets
• appliesTo scoping — each check declares which methods it protects without nesting
• Full MethodContext — checks have same repo/data access as methods
• Backwards compatible — all changes are additive (optional fields)
• Zero workflow YAML changes — checks run transparently in workflows
• Extensible — OPA, policy files, remote servers all work without framework changes