Reference: Action Catalog

The Action Catalog is Gessa's canonical verb registry: every authoritative change to a workspace, project, environment, or the Project Graph is expressed as an action with a stable id, a domain, a lifecycle, an owner, declared exposure surfaces, and audit events. This page is a thin pointer, it tells you where the catalog lives, how to read it, and the contract its action ids enforce. It does not restate the generated table.

Canonical source

The catalog is a Tier-2 generated artifact. Read it directly; do not hand-edit it.

• docs/spec/generated/action-catalog.md: the generated verb registry and HTTP/tool surface mappings.

The Tier-1 source of truth is code: packages/action-catalog/src/index.ts. The generated reference is produced by the scripts/gen-action-catalog-docs.ts generator (run via npm run gen-docs) and verified by npm run gen-docs:check, which fails the build if the committed file drifts from the catalog. The MCP-vs-catalog parity gate (npm run check:mcp-action-catalog-parity) keeps the agent-facing tool surface aligned with the catalog.

What the file contains

The generated file opens with catalog version and hash, then two tables.

• Actions table. One row per verb. Columns: Action (the action id, e.g. project.world.create), Title, Domain (e.g. control-plane, project-graph, generation, world-factory, publish), Kind (command, job_start, workflow_step, admin), Lifecycle (active, planned, internal), Owner (the subsystem that owns the verb), Exposure (which surfaces may invoke it: ui, mcp, ai, sdk, workflow, cli, admin), and Audit Events (the canonical events the action emits).
• Surface Mappings table. How each action binds to a concrete surface: Surface (e.g. http), Method, Path, Tool, and the Action it maps to. This is where you see, for instance, that workspace.create is reachable at POST /api/workspaces.

The current count of actions and surface mappings, and the full inventory, live in the generated action catalog. Representative entries (verified ids from the file): actionproject.world.create project.world.create, actionproject.entity.component.set project.entity.component.set, actionproject.script.patch.apply project.script.patch.apply (Apply Script Semantic Patch), actiongeneration.job.create generation.job.create, actionworld.build.from_prompt world.build.from_prompt (Build World From Prompt), and actionpublish.dev publish.dev. For the full list, read the generated file.

The contract action ids enforce

An action id is a public contract, not an internal route name. The catalog enforces several invariants you can rely on:

• Actions are the only mutation verbs. Editing a world means invoking an action: never writing the Project Graph directly. This is what gives Gessa one mutation authority over world state. See Explanation: Backend Authority.
• Exposure is declared, not assumed. Each verb lists the surfaces allowed to invoke it. A verb exposed to ui and sdk only (for example game.update) is not callable from an agent surface; a verb exposed to mcp/ai (for example project.entity.create) is. The MCP tool surface and the SDK are projections over this same exposure model, not bypasses of it.
• Idempotency and ownership. Each action declares an Owner (the subsystem authority) and a Kind. command verbs are point mutations; job_start verbs (for example generation.job.create, spatial.asset.import) begin a tracked job lifecycle; workflow_step verbs participate in a workflow. The catalog's owner/kind split is what lets retry-safety and idempotency policy be reasoned about per verb rather than per call site.
• Auditability. Each action lists the canonical audit events it emits (for example CreateProjectWorld, GenerationJobCreated). Every authoritative mutation is therefore observable as a named event, not an opaque write.

Version pinning

The generated file pins the catalog to immutable coordinates:

• Catalog version: action-catalog.v1.ecs-contract-surface-closure.
• Catalog hash: a sha256 over the full catalog.
• Action count and surface mapping count: the exact shape of the registry at this snapshot.

These trace back to packages/engine-version and the generated docs export manifest. Cite the catalog version and hash for an exact contract snapshot; see Versioning Policy.

Related

• Explanation: Backend Authority: one mutation authority, expressed as actions.
• Reference: ECS Components: the component state that component actions mutate.
• Reference: MCP Tools: the agent-facing projection over these verbs.

Status: stable orientation page. The catalog itself is generated and version-pinned; trust the generated file over any prose here.