acture-command-record-shape

name

acture-command-record-shape

description

Load the canonical CommandRecord shape and the closed-metadata-surface principle. Use when defining, modifying, reviewing, or extending the CommandRecord interface, when adding a new field, when removing/renaming a field, or when asked about command identity, schema, when-clauses, kind (atomic/handoff), tier, keybindings, or the Result<R> shape. Triggers on "CommandRecord", "defineCommand", "command metadata", "what fields does a command have", "add a field to commands", "the dispatch signature". Do NOT use for palette/UI behavior (load `acture-palette-design`) or migration helpers (load `acture-migration-package`).

The acture CommandRecord shape

The CommandRecord is acture's central type. It is closed — fields cannot be added without three-caller validation. This skill is the canonical spec.

The spec

type CommandRecord<P = unknown, R = unknown> = {
  /** Stable namespaced ID. Convention: 'app.domain.action' (verb-noun).
   *  Examples: 'app.graph.addNode', 'app.view.zoomToFit', 'app.data.applyFilter'. */
  id: string;

  /** Human-readable label for palette, menus, tooltips. */
  title: string;

  /** One-sentence description. ALSO the LLM-facing tool description.
   *  IMPORTANT: per research-5 §6.2, description changes are MAJOR-by-default in compare-schemas. */
  description?: string;

  /** Discovery aid only. Palettes group by this. NOT part of dispatch semantics. */
  category?: string;

  /** Discovery aid only. */
  icon?: string;

  /** Parameter schema. Standard Schema accepted at boundary: Zod (default),
   *  JSON Schema as const, Valibot. Registry normalizes to JSON Schema.
   *  HARD CONSTRAINT: param schemas must be in JSON-Schema-representable subset.
   *  No z.transform, z.date, z.bigint, z.set, z.map, z.custom in params. Coercion
   *  belongs in the handler, not the schema. Validate at registration time. */
  params?: StandardSchema<P>;

  /** Availability predicate. DSL string OR (ctx) => boolean.
   *  Function escape hatch is flagged "not exposable to AI/MCP" — the registry's
   *  toMCPServer/toAITools projections omit when-as-function commands from
   *  description-time availability metadata. */
  when?: string | ((ctx: Context) => boolean);

  /** Keybinding(s) as tinykeys DSL: "$mod+K", "g i", "$mod+([0-9])".
   *  First-class field per research-1 (convergent across Obsidian/Raycast/Linear). */
  keybinding?: string | string[];

  /** Search aliases for palette. */
  aliases?: string[];

  /** Atomic vs. handoff (research-2). Auto-derived if omitted; explicit override here.
   *  - "atomic": palette collects params in-place via picker chain.
   *  - "handoff": palette closes; opens a dedicated form view derived from same schema.
   *  Auto-derivation heuristic (research-2 §9.3):
   *    - 0 params: atomic
   *    - 1-2 params, all picker-typed: atomic
   *    - 3 params, all picker-typed AND all with defaults: atomic
   *    - otherwise: handoff
   */
  kind?: "atomic" | "handoff";

  /** Tier (research-5). Authoritative source is the JSDoc tag on the defineCommand
   *  call site (@stable / @experimental / @internal / @deprecated). The build step
   *  (acture-build-tier) mirrors the tag into this field. Authors normally do NOT
   *  write this field manually — they write the JSDoc tag. */
  tier?: "stable" | "experimental" | "internal" | "deprecated";

  /** Free-text reason injected by the build step from @deprecated <reason>.
   *  Adapter packages (acture-mcp-server, acture-ai-vercel) prepend
   *  `[DEPRECATED — <reason>]` to the description; acture-devtools surfaces
   *  it in the inspector. Added in v1.0 (Phase 4) once three concrete
   *  consumers (mcp, ai-vercel, devtools) needed it. */
  deprecationReason?: string;

  /** Module-scoped Symbol attached by the build step when a command is tagged
   *  @internal. The runtime checks identity at dispatch — cross-module callers
   *  cannot see the token because it lives in the registering module's closure.
   *  Authors do NOT write this manually. Added in v1.0 (Phase 4). */
  internalToken?: symbol;

  /** Default ranking score in palette (optional). */
  defaultScore?: number | ((ctx: Context) => number);

  /** Suggested follow-up command IDs for palette hints (optional). */
  follow?: string[];

  /** The handler. Receives validated params and execution context.
   *  Returns a discriminated-union Result. Throwing is fine inside execute;
   *  the dispatcher catches and converts to {ok: false, error}. */
  execute: (params: P, ctx: Context) => Result<R> | Promise<Result<R>>;
};

Result shape

type Result<R> =
  | { ok: true; value: R; patches?: Patch[]; effects?: Effect[] }
  | { ok: false; error: { code: string; message: string; details?: unknown } };

The patches? and effects? fields are the runtime contract consumed by acture-undo (shipped v1.11). Core itself ignores them — they're forwarded to the undo subsystem when one is installed. The pre-v1.11 framing ("reserved hooks for a future undo") is outdated.

Fields that are deliberately NOT on this record

These were proposed at various points and rejected. Do not add them.

Field	Why not
inputComponent?: unknown	UI components live in palette adapter config, not on commands.
metadata: PolicyMetadata (readOnly, idempotent, riskLevel, requiresConfirmation)	The wrapex implementation had this bag. Rejected: too many ad-hoc fields, none load-bearing. readOnly/requiresConfirmation may return as top-level fields if three callers demand them.
tags?: string[]	category + tier cover the use cases.
isVisible?, isEnabled? callbacks	Folded into when. Use the function escape hatch.
requiresConfirmation: boolean at top level	Confirmation is a middleware concern, gated by kind and tier.
version?: string per-command	Pinned to consumer package version; per-tool semver deferred until SEP-1575 lands (research-5 §3).

defineCommand helper

export function defineCommand<TParams, TResult>(
  spec: CommandRecord<TParams, TResult>
): Readonly<CommandRecord<TParams, TResult>> {
  validateAtRegistration(spec); // throws if schema uses unsupported features, ID is malformed, etc.
  return Object.freeze(spec);
}

Registration-time validation MUST check:

• id matches /^[a-z][a-zA-Z0-9]*(\.[a-z][a-zA-Z0-9]*)*$/ (namespaced dot-separated).
• params (if present) is in the JSON-Schema-representable subset (no transform, date, bigint, set, map, custom).
• when (if string) is parseable as DSL.
• kind (if explicit) is one of the two enum values.
• tier (if explicit) is one of the four enum values.

ID naming conventions

• Namespaced dots: app.domain.action.
• app. prefix configurable; default app.
• Action is camelCase, verb-first: addNode, zoomToFit, applyFilter.
• One word per segment. app.graph.addNode, not app.graph_model.add_node.
• Avoid abbreviations except universally known (png, csv, sql).

Adding a new field

Before adding ANY new field:

1. Name the concrete consumer(s) that need it — a specific command, adapter, or consumer surface. "What if someone wanted…" is not enough; a real named need is. (One named consumer can be enough if the use case is irreducible; more is fine but the test is concrete, not a count — see docs/redesign_takeaways.md §6 on why a numeric callers gate is the wrong framing.)
2. Confirm it cannot be done by composition (a wrapper function like palettable(cmd, ...) or toolCallable(cmd, ...)).
3. Confirm it doesn't introduce conditional logic into metadata (inner platform effect).
4. Write the migration story: how does v1 code adopt the new field without breaking?

If any of these fails: do not add the field. Use composition.

Why the surface is closed

Per docs/redesign_takeaways.md §1.2 and the central paper §6.1. The Inner Platform Effect is the most dangerous risk: command metadata growing toward a mini-language with conditionals, inheritance, and dynamic composition. The guardrail is structural: keep the interface minimal and resist additions. If a use case requires conditional logic, it belongs in the handler, not the metadata.

See also

• acture-schema-bridge — how params becomes JSON Schema / MCP tool / AI tool
• acture-palette-design — how kind drives palette UX
• acture-tier-system — how tier is enforced at runtime
• docs/v1_plan.md §4 — same spec, with research-citation trail