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

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 };
    },
  },
],

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.