APEX Type System & Action Schema

Complete type specifications for APEX operations, target domains, and the BaseApexAction contract.
Published: 7/10/2026

Discriminated Unions & Spec Hosing

The APEX protocol relies on discriminated unions generated via Zod and TypeScript. These strictly enforced contracts reside in the external @aircada/spec package, ensuring that both client runtime layers and LLM agent schemas remain tightly coupled and immune to structural hallucination.

APEX Base Action Contract Reference#

The fundamental action layout and targetId resolution patterns in the APEX protocol.

The Base Action Contract

Every APEX action inherits from BaseApexAction. The contract mandates a flat targetId design, pointing directly to the specific entity undergoing mutation—never a parent or wrapping container:

typescript
export interface BaseApexAction {
    operation: ApexOperation;
    domain: ApexDomain;
    /** Existing Engine ID, or a temporary ID (e.g., "temp_shoe_1") when ADDing */
    targetId: string;
}

targetId Resolution Rule

- When EDITing or DELETEing: The targetId must be the exact, active engine UUID of the target entity retrieved via an inspection query.

- When ADDing: The client does not know the final engine UUID yet. The agent specifies a client-generated temporary ID (e.g., temp_shoe_1 or temp_row_5). The transaction runner constructs the entity, maps this temporary identifier to its real engine UUID, and returns this mapping in the transaction response.

APEX Protocol Enums Reference#

Discrete enum values for APEX operations (ADD, EDIT, DELETE) and domain targets.

Core Protocol Enums

All APEX transaction items require an exact operation and a flat domain category. These are defined by the following TypeScript enums:

typescript
export enum ApexOperation {
    ADD = "ADD",
    EDIT = "EDIT",
    DELETE = "DELETE"
}

export enum ApexDomain {
    SCENE_OBJECT = "SCENE_OBJECT",
    EFFECT = "EFFECT",
    OPERATOR = "OPERATOR",
    LINK = "LINK",
    SCENE = "SCENE",
    DATASET = "DATASET",
    DATASET_ROW = "DATASET_ROW",
    OPTION_MODEL = "OPTION_MODEL",
    OPTION_SET = "OPTION_SET"
}