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 catalog declares 64 actions and 76 surface mappings. Representative entries (verified ids from the file): project.world.create project.world.create, project.entity.component.set project.entity.component.set, project.script.patch.apply project.script.patch.apply (Apply Script Semantic Patch), generation.job.create generation.job.create, world.build.from_prompt world.build.from_prompt (Build World From Prompt), and 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.
• 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.