---
title: "Reference: Action Catalog"
description: "Thin pointer to the generated Action Catalog, the canonical verb registry for mutating platform surfaces, and the contract its action ids enforce."
engineVersion: v1.0.234
date: 2026-09-28
license: "(c) Gessa, proprietary. Cite with attribution to https://gessa.ai/docs/. Terms: https://gessa.ai/terms/."
canonical: https://gessa.ai/docs/reference/action-catalog/
---

# 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`](../../../spec/generated/action-catalog.md): the generated verb registry and HTTP/tool surface mappings.

{% generated-reference file="docs/spec/generated/action-catalog.md" label="Action Catalog" /%}

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): {% action name="project.world.create" /%} `project.world.create`, {% action name="project.entity.component.set" /%} `project.entity.component.set`, {% action name="project.script.patch.apply" /%} `project.script.patch.apply` (Apply Script Semantic Patch), {% action name="generation.job.create" /%} `generation.job.create`, {% action name="world.build.from_prompt" /%} `world.build.from_prompt` (Build World From Prompt), and {% action name="publish.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](../explanation/backend-authority.md).
- **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.

{% warning severity="critical" title="Do not mutate the Project Graph directly" %}
Use the Action Catalog (or semantic authoring that lowers into it); raw graph mutations bypass authority, validation, exposure rules, and audit. The `project.transaction.apply` verb is owned by the project-graph authority and exposed to `workflow` only, application code calls the higher-level component/entity/world verbs.
{% /warning %}

## 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](../explanation/versioning-policy.md).

## Related

- [Explanation: Backend Authority](../explanation/backend-authority.md): one mutation authority, expressed as actions.
- [Reference: ECS Components](./ecs-components.md): the component state that component actions mutate.
- [Reference: MCP Tools](./mcp-tools.md): 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.