APEX Atomic Transactions & Temporary ID Mapping

Transaction Execution Model

APEX dispatches all environment mutations inside atomic batches. Transactions success is binary: either every batched operation executes flawlessly, or the transaction fails as a whole and reverts. This ensures the live 3D engine is never left in an unstable, partially configured state.

Transaction Protocol Contracts

The communication schema defines exact request, response, and result structures for atomic commits:

export enum ApexTransactionStatus {
    SUCCESS = "success",
    INVALID = "invalid",
    FAILURE = "failure"
}

export interface ApexTransactionRequest {
    /** Explains the agent's goal. Vital for telemetry and RAG-ready KB logging. */
    intent: string;
    actions: ApexAction[
    ];
}

export interface ApexTransactionResponse {
    /** Strict atomic outcome. */
    status: ApexTransactionStatus;
    /** Maps the agent's tempIds to the Engine's true IDs */
    idMap: Record<string, string>;
    /** Cascade alerts, success confirmations, or exact schema failure reasons */
    message: string[];
}

export interface ApexActionResult {
    status: ApexTransactionStatus;
    message: string;
    idMap?: Record<string, string>;
    structures?: ApexInspectionTargetStructure[];
}

Client-Side Temporary ID Resolution (idMap)

One of the major hurdles in multi-step 3D environment generation is referencing an object before it is officially committed to the engine database. For example: creating a new SCENE_OBJECT and immediately adding an EFFECT to it inside the exact same batch transaction.

APEX resolves this via Temporary ID mapping:

1. The agent assigns a temporary ID when adding a scene object (e.g., "targetId": "temp_shoe_mesh").

2. In the same batch, the agent can reference that temporary ID inside dependent actions (e.g., setting the effect's "parentId": "temp_shoe_mesh").

3. The APEX transaction coordinator translates temp_shoe_mesh to the real engine UUID during execution, registers the correct database relation, and reports the final UUID translation table inside the transaction response idMap:

{

     "status": "success",

     "idMap": {

       "temp_shoe_mesh": "c502b4d2-fbfb-4f70-a8dc-6ef31c4b79b9"

     }

   }

4. This allows agents to seamlessly track constructed objects and coordinate highly complex, multi-layered operations within a single network round-trip.

The Importance of 'Intent' Telemetry

The intent string in ApexTransactionRequest is a semantic explanation of what the agent is attempting to achieve (e.g., "Bifurcating custom shoe material dataset configurations by registering two separate option sets for leather and suede textures").

This is recorded in the live engine telemetry logs to build a RAG-ready knowledge database, helping secondary agents track historical environment mutations and reconstruct past human-agent cooperation chains.