MODEL

A model is a TypeScript module that automates resource lifecycle operations. Models declare arguments, output specifications, and methods. Each method receives a context object with access to data repositories, vault secrets, and output writers. The file lives in extensions/models/ and exports a model object.

For the YAML definition layer that configures model instances, see Model Definitions.

Export Shape

import { z } from "npm:zod@4";

export const model = {
  type: "@mycollective/my-model",
  version: "2026.05.14.1",

  globalArguments: z.object({
    region: z.string().describe("Target region"),
  }),

  resources: {
    instance: {
      description: "Managed instance",
      schema: z.object({
        id: z.string(),
        status: z.string(),
      }),
      lifetime: "infinite",
      garbageCollection: 3,
    },
  },

  methods: {
    create: {
      description: "Create a new instance",
      arguments: z.object({
        name: z.string(),
      }),
      async execute(args, context) {
        // implementation
      },
    },
  },
};

Top-Level Fields

MethodDefinition

Each method defines its arguments and an execute function.

MethodContext

The context parameter passed to every execute call. The most commonly used fields are listed below.

Identity

Definition Metadata

Data Operations

readModelData returns the latest version of each matching data item, or an empty array when the model has no data or does not exist. Each DataRecord carries the parsed JSON in attributes, plus name, version, specName, modelId, modelType and tags.

const records = await context.readModelData!("my-vpc", "state");
const vpc = records[0]?.attributes as { VpcId: string } | undefined;

queryData uses the same predicate language as swamp data query and returns latest versions only, unless the predicate references version or isLatest. Without select it returns DataRecord[]; with select it returns the projected values.

const subnets = await context.queryData!(
  'modelType == "@myorg/subnet" && attributes.vpcId == "vpc-123"',
);

Model Invocation

RunModelOptions takes one of two forms:

// An existing definition, by name
{ definition: string; method: string; arguments?: Record<string, unknown> }

// Direct type execution — auto-creates the definition if it does not exist
{
  modelType: string;
  name: string;
  method: string;
  arguments?: Record<string, unknown>;
}

In the direct type form, name is the definition name. When no definition with that name exists, one is auto-created in .swamp/auto-definitions/. When one exists with a different model type, the invocation fails.

arguments is split between the target's global arguments and method arguments by their schemas. Method arguments win on ambiguous keys; unknown keys fail the invocation.

RunModelResult is a discriminated union on ok:

// Success
{ ok: true, resources: DataHandle[] }

// Failure
{ ok: false, error: { message: string; stack?: string } }

runModel reports failure in the returned value and does not throw. Check ok on every result:

const result = await context.runModel!({
  definition: "my-vpc",
  method: "read",
});

const created = await context.runModel!({
  modelType: "@myorg/vpc",
  name: "my-new-vpc",
  method: "create",
  arguments: { cidrBlock: "10.0.0.0/16" },
});

for (const r of [result, created]) {
  if (!r.ok) throw new Error(r.error.message);
}

The caller's extension must declare the target model's extension in its manifest dependencies — see the manifest reference. Invocations from extensions not listed in dependencies are rejected at runtime. Same-extension calls, built-in model types and user-authored model types need no declaration.

Safety limits apply to all runModel calls within a single top-level execution: maximum call depth of 10, cycle detection (a model cannot invoke itself directly or transitively), and a ceiling of 100 total invocations. Vault secrets are isolated per extension — the invoked model cannot access the caller's vault bindings.

Data written by the invoked model is owned by the target model's definition, not the caller's. The returned DataHandle array references the target's data.

Availability by Context

On a remote worker, runModel returns a failure result whose error.message reads:

context.runModel() is not available in remote execution — move the runModel call to a local orchestrator model or workflow.

To orchestrate models on workers, chain model_method steps in a workflow. See Remote Execution for the capability proxying model.

Extension Files

Services

dataRepository Methods

The dataRepository field on MethodContext provides low-level data access. Most methods should use writeResource, readResource, and queryData instead — dataRepository is for operations those helpers don't cover.

Author-facing methods:

Pass context.modelType and context.modelId for the first two parameters when operating on the current model's own data.

await context.dataRepository.delete(
  context.modelType,
  context.modelId,
  "error-target-a",
);

Runtime-internal methods (save, append, rename, removeLatestMarker, collectGarbage) are used by the framework to manage data lifecycle. They are not intended for direct use in model methods.

MethodResult

Returned by execute to report what the method produced.

DataHandle

ResourceOutputSpec

Declares a named resource output that methods can write to.

FileOutputSpec

Declares a named file output.

Checks

Pre-flight checks run before method execution and can prevent it.

checks: {
  credentials: {
    description: "Verify API credentials are valid",
    labels: ["auth"],
    async execute(context) {
      // validate credentials
      return { pass: true };
    },
  },
},

Version Upgrades

Declare a migration chain for schema changes between versions.

upgrades: [
  {
    toVersion: "2026.05.14.2",
    description: "Rename 'instanceId' to 'id'",
    upgradeAttributes(old) {
      return { ...old, id: old.instanceId };
    },
  },
],

Entries are ordered by toVersion, and the last entry's toVersion must equal the model's version. For a version bump with no schema change, add an entry with upgradeAttributes: (old) => old; without one, existing instances are never advanced to the new version.

Upgrades run before a method executes, against each instance's recorded typeVersion:

An instance whose typeVersion is behind with no entry covering the gap is reported by swamp model get as stranded, and nothing migrates it. See Staleness.

Packaging

Declare the model in your extension's manifest:

models:
  - my_model.ts

The file path is relative to the extensions/models/ directory within the extension root.

Runtime Permissions

Extension model methods run in-process with individually scoped Deno permissions. The following flags are granted:

--allow-all and --allow-ffi are not granted.

Device Node Limitation

Deno.open() on character or block device nodes (e.g. /dev/ttyUSB0) does not work in the compiled binary. This is a Deno compiled-binary behavior, not a Swamp restriction.

Subprocess Workaround

Deno.Command spawns subprocesses for device I/O under the granted --allow-run permission.

const command = new Deno.Command("cat", {
  args: ["/dev/ttyUSB0"],
  stdout: "piped",
});
const { stdout } = await command.output();
const data = new TextDecoder().decode(stdout);

const stty = new Deno.Command("stty", {
  args: ["-F", "/dev/ttyUSB0", "9600", "cs8", "-cstopb", "-parenb"],
});
await stty.output();

Docker Execution Driver

The Docker execution driver uses --allow-all. Deno.open() on device nodes works when using Docker placement.