The command catalog

There is exactly one place where a Chorus primitive’s behavior lives: a Command in the catalog. Validation, business logic, and side effects all sit behind one execute(). Every transport — HTTP, JSON-RPC, MCP — is a thin shim that frames a request around the same call. This is the architectural keystone (ADR-0001), and it’s why the same operation behaves identically no matter which wire you reach it on.

The Command interface

A command is a small record (src/commands/catalog.ts:64-70):

interface Command<TSchema extends z.ZodType = z.ZodType, TOutput = unknown> {
  id: string;                    // e.g. "tasks.create", "memory.store"
  description: string;
  schema: TSchema;               // zod schema for the input
  validationErrorCode?: string;  // error code on schema failure
  execute(input: any, ctx: CommandContext): Promise<TOutput>;
}

executeCommand is the single entry point (catalog.ts:93-114). It looks the command up by id, zod-validates the input, and only then calls execute(parsed, ctx):

const command = commandCatalog[args.id];
if (!command) throw new ChorusError("COMMAND_NOT_FOUND", ..., 404);

const parsed = command.schema.safeParse(args.input);
if (!parsed.success) {
  throw new ChorusError(command.validationErrorCode ?? SIGNAL_EMIT_VALIDATION_FAILED, ..., 400, parsed.error.issues);
}
return command.execute(parsed.data, args.ctx);

Validation failure is a single 400 with the per-command code (or the signal-emit default); an unknown id is a single 404 COMMAND_NOT_FOUND. Transports never re-implement either.

How the catalog is assembled

commandCatalog is a frozen map built from 14 handler groups (catalog.ts:72-89): signals, memory, memory-admin, workspace, tasks, circles, admin, workstreams, webhooks, artifacts, approvals, org, identity, workflow. The audit counted 136 command ids plus 8 generated signals.emit.<foundation> entries (gap-4 §2.3).

export const commandCatalog = Object.freeze(
  Object.fromEntries([...signalCommands, ...memoryCommands, /* …14 groups */ ]
    .map((command) => [command.id, command])),
);

The handler logic lives in src/commands/handlers/*.ts. Directories like src/tasks, src/execution, src/best-of, and src/workspace hold route shims, zod types, and pure policy helpers — not the business logic (gap-3 §1.1).

Transports frame; they don’t decide

Each transport’s job is to turn its wire envelope into {id, input, ctx} and call executeCommand. The context is built once per transport (gap-3 §1.1, gap-4 §2.3):

Transport	Builder	Role
HTTP	commandContextFromHono (catalog.ts:125)	parse envelope → executeCommand → frame {data, meta}
JSON-RPC	passthrough via executeCatalogCommand	method name → catalog id
MCP	task/workspace tools	server.tool(name, …) → executeCommand
Internal	commandContextFromRpc (catalog.ts:148)	catalog-to-catalog passthrough

Two RPC spellings, one command

The JSON-RPC registry carries both a dot-form (memory.store) and a legacy slash-form (memory/store) for many ops (src/rpc/methods.ts:1203-1204), both resolving to the same catalog command. Dot-form is canonical (post-#416); slash-form is back-compat and not always 1:1 — some names also changed, e.g. workspace/create_text → workspace.create_file (gap-4 §2.2). Note this is per-op, not universal: the tasks.* execution primitives are dot-form only (methods.ts:1311-1316 — no tasks/* slash keys); dispatch is exact-match.

The non-catalog holdouts

The catalog is the rule, not yet the whole map. A few surfaces still bypass it — document and trust these carefully.

Signal read/claim/ack routes are bespoke handlers

Only the 8 foundation signal types (pulse, sense, query, alert, artifact, approval_request, proposal, shift) route through the catalog as signals.emit.<type>. On HTTP, /emit sends those to executeCommand but falls back to a direct signalService.emit for anything else (src/signals/routes.ts:457-465). Every other signal/inbox route — list, inbox, claim, ack, thread, cancel, extend-claim — is a bespoke service handler with no executeCommand (src/signals/routes.ts:1522). Their validation and error codes are service-layer, not catalog-layer.

signals.emit.task exists only to reject

There is a catalog entry signals.emit.task, but its execute() does nothing except throw LEGACY_TASK_EMIT_REMOVED (422) — signal(type=task) was removed in RFC-291 Phase 4 (src/commands/handlers/signals.ts:48-59). Use the native task API (tasks.create). See the core loop.

The RFC-291 “shim” is dead code

isRfc291ShimActive / RFC291_SHIM_ACTIVE_PHASES (src/signals/rfc291-shim.ts) have zero callers. There is no live signal→task dual-write at emit time — the translation only runs as an operator-triggered batch rehydration, not an always-on layer (gap-3 F3).

The /admin/* RFC-291 repair endpoints are scaffolds, not catalog commands

Ten admin execution-repair operations (reclaim_run_attempt, reassign_task, unblock_task, cleanup_checkout, repair_primary_delivery, clear_invalid_completion, cancel_orphan_gate, diagnose, reconcile_best_of_group, reset_failure_counter) are not in the catalog — they are HTTP-only RouteMeta entries (POST /admin/{command}, src/admin/rfc291-rollout.ts:93-104,334-369). Each checks admin policy, writes one audit event, then throws RFC291_ADMIN_NOT_IMPLEMENTED and answers 501. Nothing is repaired (this was flagged in gap-3 F1, where they still returned a misleading {status: "accepted"}; the code now answers 501 honestly). Don’t build flows on them.