Skip to main content

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

Field Type Required Description
type string Yes Unique identifier in @collective/name format.
version string Yes CalVer format: YYYY.MM.DD.MICRO.
globalArguments z.ZodTypeAny No Zod schema for arguments shared across all methods.
resources Record<string, ResourceOutputSpec> No Named resource output specifications.
files Record<string, FileOutputSpec> No Named file output specifications.
methods Record<string, MethodDefinition> Yes Named methods the model exposes.
checks Record<string, CheckDefinition> No Pre-flight checks that run before methods.
reports string[] No Report names to run by default after method execution.
upgrades VersionUpgrade[] No Version migration chain for schema changes.

MethodDefinition

Each method defines its arguments and an execute function.

Field Type Required Description
description string Yes What the method does.
kind "create" | "read" | "update" | "delete" | "list" | "action" No Semantic intent of the method.
arguments z.ZodTypeAny Yes Zod schema for method-specific arguments.
execute (args, context) => Promise<MethodResult> Yes Implementation function.

MethodContext

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

Identity

Field Type Description
modelType string The model's type identifier.
modelId string Instance ID of the model definition.
methodName string Name of the currently executing method.
globalArgs Record<string, unknown> Resolved global arguments.
repoDir string Absolute path to the repository root.
signal AbortSignal Cancellation signal.

Definition Metadata

Field Type Description
definition { id, name, version, tags } Model definition metadata.

Data Operations

Field Signature Description
writeResource (specName, name, data, overrides?) => Promise<DataHandle> Write a resource — validates against schema, returns a handle.
readResource (instanceName, version?) => Promise<Record<string, unknown> | null> Read a previously stored resource by instance name.
readModelData (modelName, specName?) => Promise<DataRecord[]> Read data from another model by name.
queryData (predicate, select?) => Promise<DataRecord[] | unknown[]> Query data artifacts across all models using a CEL predicate.
createFileWriter (specName, name, overrides?) => DataWriter Create a file writer for binary or streaming content.

Extension Files

Field Signature Description
extensionFile (relPath: string) => string Resolve a path relative to the extension root.

Services

Field Type Description
logger Logger Structured logger (LogTape).
dataRepository UnifiedDataRepository Low-level data access.
vaultService VaultService (optional) Access to vault secrets.

MethodResult

Returned by execute to report what the method produced.

Field Type Required Description
dataHandles DataHandle[] No Handles to resources or files written.
followUpActions FollowUpAction[] No Actions to execute after the method returns.

DataHandle

Field Type Description
name string Instance name of the output.
specName string Name of the resource or file spec.
kind "resource" | "file" Whether this is structured data or a file.
version number Version number of this output.
size number Size in bytes.
tags Record<string, string> Output tags.

ResourceOutputSpec

Declares a named resource output that methods can write to.

Field Type Required Description
description string No What this resource represents.
schema z.ZodTypeAny Yes Zod schema that validates written data.
lifetime "infinite" | "session" Yes How long the data persists.
garbageCollection number Yes Number of versions to keep.
tags Record<string, string> No Default tags for this output.
sensitiveOutput boolean No Auto-vault sensitive fields on write.
vaultName string No Vault name for sensitive field storage.

FileOutputSpec

Declares a named file output.

Field Type Required Description
description string No What this file represents.
contentType string Yes MIME type (e.g., application/gzip).
lifetime "infinite" | "session" Yes How long the data persists.
garbageCollection number Yes Number of versions to keep.
streaming boolean No Whether the file supports streaming writes.
tags Record<string, string> No Default tags for this 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 };
    },
  },
},
Field Type Required Description
description string Yes What the check verifies.
labels string[] No Tags for filtering checks.
appliesTo string[] No Method names this check applies to.
execute (context) => Promise<{ pass, errors? }> Yes Run the check. Return pass: false with errors to block execution.

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 };
    },
  },
],
Field Type Description
toVersion string Target version (CalVer).
description string What the upgrade does.
upgradeAttributes (old: Record<string, unknown>) => Record<string, unknown> Transform stored attributes to the new schema.

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.

← PreviousDriverNext →Report