Arxi Decision Gate Asset Core
Docs
Asset Core Docs

Deterministic world-state engine documentation and API references.

Decision Gate docs

AssetCore Action Reference

Generated from Operations Manifest v1.0.0 (API 0.1.0)

Auto-generated from operations manifest on 2026-01-22

AssetCore is a deterministic memory substrate. Containers are persistent memory regions. Operations are atomic memory transformations. Transactions are replayable memory commits.

The following operations modify structured memory regions in a domain-agnostic fashion.

This reference provides direct, action-first entry points for all 24 AssetCore operations. Each action maps 1:1 to a commit operation; switch between the SDK call and op payload tabs as needed. Preflight is opt-in via ActionOptions(preflight=True).

Overview

AssetCore actions are thin wrappers that build a single operation and submit it through the commit endpoint. If you need multi-operation transactions, use the commit helpers directly.

Preflight

Action methods accept an optional ActionOptions object. Set preflight=True to run the preflight pipeline before committing. Preflight-only calls are available through the action preflight helpers or the client preflight helpers.

Operations

CreateContainer

Creates a container (structured memory region) with the requested kind.

container create single targeted

Creates a persistent container of the requested kind (balance, grid, slots, continuous 1D/2D). Provide external_id to claim a stable external identifier; internal IDs are dense, auto-allocated, and never exposed. External IDs are namespace-scoped and must not already exist.

Errors:

  • ContainerAlreadyExists: A container with that ID already exists.

Commentary:

  • Allocate a balance container with 0.01 precision (quantization_inv=100).
  • Provide an external_id that the system maps to an internal container ID.

Examples:

await client.actions.create_container(
    external_id="container-1000",
    kind={"quantization_inv": 100, "type": "balance"},
)

RemoveContainer

Deletes a container after draining its contents.

container destroy single cascade

Removes a container after the transaction drains any balances, instances, and slot contents. This is irreversible for the container identifier and preserves surrounding memory regions.

Errors:

  • ContainerNotFound: The specified container does not exist.

Commentary:

  • Delete a container after draining its balances, instances, and slots.

Examples:

await client.actions.remove_container(
    container_id="container-1001",
)

AddFungible

Adds fungible quantity to a balance or an explicit grid cell.

balance create single targeted

Increases fungible quantity for a class/key pair. When targeting a balance container, quantity is added to the aggregate balance. When targeting a grid cell, the operation creates or grows a stack at the specified anchor, enforcing registered shapes and rotation for placement.

Errors:

  • InvalidQuantity: Quantity must be greater than zero.
  • WrongContainerKind: Slots containers cannot hold fungible assets.
  • ContainerNotFound: The target container does not exist.
  • UnregisteredClass: The class is not registered in the namespace.
  • UnregisteredClassShape: Grid additions require a registered shape for the class and key.
  • PositionOccupied: The requested grid anchor overlaps an existing placement.

Commentary:

  • Add 500 units of class 100 to a grid cell stack at anchor 5.
  • Rotation is applied to the registered class shape.

Examples:

await client.actions.add_fungible(
    class_id="class-100",
    key=1,
    location={
        "container_id": "container-2001",
        "kind": "grid_cell",
        "position": 5,
        "rotation": "none",
    },
    quantity="500",
)

Advanced examples: Example: balance top-up

  • Add quantity directly to the balance container aggregate.
await client.actions.add_fungible(
    class_id="class-100",
    key=1,
    location={"container_id": "container-1001", "kind": "balance"},
    quantity="1000",
)

RemoveFungible

Removes fungible quantity from a balance or an explicit grid cell.

balance destroy single targeted

Decreases fungible quantity for a class/key pair within a container. Supports burning from balances or clearing a grid stack at a specific anchor. When a stack reaches zero it may be removed, keeping the substrate deterministic.

Errors:

  • InvalidQuantity: Quantity must be greater than zero.
  • WrongContainerKind: Slots containers cannot hold fungible assets.
  • ContainerNotFound: The target container does not exist.
  • UnregisteredClass: The class is not registered in the namespace.
  • InsufficientBalance: The requested quantity exceeds the available balance.
  • PositionEmpty: No stack exists at the requested grid anchor.

Commentary:

  • Remove 100 units from a balance container for the class/key pair.

Examples:

await client.actions.remove_fungible(
    class_id="class-100",
    from_={"container_id": "container-1001", "kind": "balance"},
    key=1,
    quantity="100",
)

MoveFungible

Moves fungible quantity between balances or grid cells.

balance move multi targeted

Transfers fungible quantity from one location to another. Supports balance<->balance, balance<->grid, and grid<->grid moves while enforcing registered shapes for grid destinations and ensuring source quantities are sufficient.

Errors:

  • InvalidQuantity: Quantity must be greater than zero.
  • WrongContainerKind: Slots containers cannot participate in fungible moves.
  • ContainerNotFound: One of the containers does not exist.
  • UnregisteredClass: The class is not registered in the namespace.
  • InsufficientBalance: Source location lacks the requested quantity.
  • PositionEmpty: No stack exists at the requested grid anchor.
  • PositionOccupied: Destination grid anchor overlaps an existing placement.
  • UnregisteredClassShape: Grid destinations require a registered shape for the class and key.

Commentary:

  • Move quantity from a balance container into a grid placement.
  • Grid destinations enforce registered shape + rotation.

Examples:

await client.actions.move_fungible(
    class_id="class-100",
    from_={"container_id": "container-1001", "kind": "balance"},
    key=1,
    quantity="50",
    to={
        "container_id": "container-2001",
        "kind": "grid_cell",
        "position": 4,
        "rotation": "clockwise90",
    },
)

Advanced examples: Example: grid to grid

  • Move a small quantity between two grid anchors in the same container.
await client.actions.move_fungible(
    class_id="class-100",
    from_={
        "container_id": "container-2001",
        "kind": "grid_cell",
        "position": 5,
        "rotation": "none",
    },
    key=1,
    quantity="5",
    to={
        "container_id": "container-2001",
        "kind": "grid_cell",
        "position": 6,
        "rotation": "none",
    },
)

TransferFungible

Transfers fungible quantity between structured containers.

balance move multi targeted

Moves fungible quantity from one container to another in a single transaction. Both containers must exist, support balances for the class/key pair, and the source must contain the requested amount. Shape registration is enforced when grid placement is required.

Errors:

  • InvalidQuantity: Quantity must be greater than zero.
  • InvalidOperation: Identity transfers or arithmetic overflow are invalid.
  • ContainerNotFound: One of the containers does not exist.
  • WrongContainerKind: Slots containers cannot participate in fungible transfers.
  • UnregisteredClass: The class is not registered in the namespace.
  • InsufficientBalance: Source container lacks the requested quantity.
  • UnregisteredClassShape: Grid destinations require a registered shape for the class and key.

Commentary:

  • Transfer 250 units between two balance containers.

Examples:

await client.actions.transfer_fungible(
    class_id="class-100",
    from_container="container-1001",
    key=1,
    quantity="250",
    to_container="container-1002",
)

TransferMany

Transfers multiple fungible quantities between containers in one batch.

balance move multi fanout

Executes an ordered batch of container-to-container transfers with atomic all-or-nothing semantics. Each entry validates container kinds, class registration, and sufficient balances before any mutations occur.

Errors:

  • InvalidQuantity: Quantity must be greater than zero.
  • InvalidOperation: Identity transfers or invalid batch structure were rejected.
  • ContainerNotFound: One of the containers does not exist.
  • WrongContainerKind: Slots containers cannot participate in fungible transfers.
  • UnregisteredClass: The class is not registered in the namespace.
  • InsufficientBalance: Source container lacks the requested quantity.
  • UnregisteredClassShape: Grid destinations require a registered shape for the class and key.

Commentary:

  • Batch multiple balance transfers in one atomic transaction.

Examples:

await client.actions.transfer_many(
    transfers=[
        {
            "class_id": "class-100",
            "from_container": "container-1001",
            "key": 1,
            "quantity": "25",
            "to_container": "container-1002",
        },
        {
            "class_id": "class-101",
            "from_container": "container-1002",
            "quantity": "10",
            "to_container": "container-1003",
        },
    ],
)

Advanced examples: Example: three-way transfer

  • Rebalance multiple containers in a single transaction.
await client.actions.transfer_many(
    transfers=[
        {
            "class_id": "class-100",
            "from_container": "container-1001",
            "key": 1,
            "quantity": "5",
            "to_container": "container-1002",
        },
        {
            "class_id": "class-100",
            "from_container": "container-1002",
            "key": 1,
            "quantity": "7",
            "to_container": "container-1003",
        },
        {
            "class_id": "class-101",
            "from_container": "container-1003",
            "quantity": "2",
            "to_container": "container-1001",
        },
    ],
)

Distribute

Distributes fungible quantity from one source to multiple destinations.

balance move multi fanout

Splits a single source quantity across multiple destination containers in a single atomic batch. The source must contain the total quantity requested across all distribution entries.

Errors:

  • InvalidQuantity: Each distribution quantity must be greater than zero.
  • InvalidOperation: Totals must fit within balance limits for the source.
  • ContainerNotFound: One of the containers does not exist.
  • WrongContainerKind: Slots containers cannot participate in fungible distribution.
  • UnregisteredClass: The class is not registered in the namespace.
  • InsufficientBalance: Source container lacks the total quantity requested.
  • UnregisteredClassShape: Grid destinations require a registered shape for the class and key.

Commentary:

  • Split a balance into multiple destination containers in one commit.

Examples:

await client.actions.distribute(
    class_id="class-100",
    distributions=[
        {"quantity": "10", "to_container": "container-2001"},
        {"quantity": "15", "to_container": "container-2002"},
    ],
    from_container="container-1001",
    key=1,
)

MergeStacks

Merges one fungible stack into another within a container.

balance consolidate multi targeted

Combines the source stack into the destination stack in the same grid container. The stacks must share class and key identity. Quantities are summed deterministically and the source stack is removed.

Errors:

  • InvalidOperation: Self-merges, cross-container merges, or overflows are rejected.
  • ContainerNotFound: The grid container vanished before the merge completed.
  • WrongContainerKind: Only grid containers contain stack entities.
  • StackNotFound: One of the referenced stacks no longer exists.
  • IncompatibleStacks: Stacks must share the same class and key to merge.

Commentary:

  • Merge the source stack into the destination stack.

Examples:

await client.actions.merge_stacks(
    dst_stack="stack-5001",
    src_stack="stack-5002",
)

ConsolidateStacks

Consolidates all matching fungible stacks inside a container.

balance consolidate multi fanout

Finds every stack in a container that matches the class/key pair and collapses them into a single stack. Normalizes fragmented balances that accumulated across multiple operations while preserving totals.

Errors:

  • ContainerNotFound: The specified container does not exist.
  • WrongContainerKind: Only grid containers can hold stacks for consolidation.
  • UnregisteredClass: The class is not registered in the namespace.
  • InvalidOperation: No stacks were found or the total quantity overflowed u64.
  • StackNotFound: A stack disappeared during consolidation.

Commentary:

  • Combine stacks with the same class/key inside a container.

Examples:

await client.actions.consolidate_stacks(
    class_id="class-100",
    container_id="container-1001",
    key=1,
)

MoveMany

Moves multiple stacks between Grid containers in one batch.

balance move multi fanout

Executes a batch of stack moves across Grid containers. Each entry specifies a stack identifier, destination container, and quantity; partial moves split stacks while full moves relocate them.

Errors:

  • InvalidQuantity: Move quantity must be greater than zero.
  • InvalidOperation: Duplicate stacks or invalid destinations were rejected.
  • ContainerNotFound: One of the containers does not exist.
  • WrongContainerKind: Stacks can only move between Grid containers.
  • StackNotFound: One of the referenced stacks no longer exists.
  • InsufficientBalance: A stack lacks the quantity requested for the move.
  • StackLimitExceeded: Destination container exceeds stack limits.

Commentary:

  • Move multiple stacks in one operation to minimize commit overhead.

Examples:

await client.actions.move_many(
    moves=[
        {"quantity": "3", "stack": "stack-5001", "to_container": "container-2001"},
        {"quantity": "5", "stack": "stack-5002", "to_container": "container-2002"},
    ],
)

Advanced examples: Example: multi-container relocation

  • Relocate multiple stacks without multiple commit calls.
await client.actions.move_many(
    moves=[
        {"quantity": "1", "stack": "stack-5003", "to_container": "container-2003"},
        {"quantity": "2", "stack": "stack-5004", "to_container": "container-2004"},
    ],
)

AddInstance

Mints a new instance and places it at a target location.

instance create single targeted

Creates a unique instance for the specified class/variant and places it into a slot, grid anchor, or continuous coordinate. Validates container kind, shape/rotation rules, and collision before placement.

Errors:

  • ContainerNotFound: The target container does not exist.
  • UnregisteredClass: The class is not registered in the namespace.
  • WrongContainerKind: Grid placements require Grid containers; slot placements require Slots containers; continuous placements require Continuous containers.
  • SlotOutOfBounds: Slot index exceeds the container capacity.
  • SlotOccupied: The requested slot is already occupied.
  • PositionOccupied: The grid anchor overlaps an existing placement.
  • PositionOutOfBounds: Placement would exceed grid bounds.
  • ContinuousPlacementOutOfBounds: Continuous placement extends beyond container bounds.
  • UnregisteredClassShape: Grid placements require a registered shape for the class/key.

Commentary:

  • Mint a new instance and place it into a slot.

Examples:

await client.actions.add_instance(
    class_id="class-200",
    key=1,
    location={"container_id": "container-500", "kind": "slot", "slot_index": 1},
)

Advanced examples: Example: grid placement

  • Mint and place an instance directly into a grid container.
await client.actions.add_instance(
    class_id="class-200",
    key=1,
    location={
        "container_id": "container-2001",
        "kind": "grid_cell",
        "position": 8,
        "rotation": "none",
    },
)

MoveInstance

Moves an existing instance to a new location.

instance move single targeted

Repositions a previously minted instance into a slot, grid anchor, or continuous coordinate. Validates shape/rotation rules and prevents overlap in grid and continuous containers.

Errors:

  • InstanceNotFound: The instance does not exist.
  • WrongContainerKind: Destination container type does not support the requested move.
  • SlotOutOfBounds: Slot index exceeds the container capacity.
  • SlotOccupied: Destination slot is already occupied.
  • PositionOccupied: Destination grid anchor overlaps an existing placement.
  • PositionOutOfBounds: Destination grid anchor exceeds bounds.
  • ContinuousPlacementOutOfBounds: Continuous placement extends beyond container bounds.
  • UnregisteredClassShape: Grid destinations require a registered shape for the instance class/key.
  • ContinuousPlacementOverlap: Continuous destination overlaps an existing placement.

Commentary:

  • Move an existing instance to a grid cell placement.

Examples:

await client.actions.move_instance(
    instance="instance-9001",
    to={
        "container_id": "container-2001",
        "kind": "grid_cell",
        "position": 5,
        "rotation": "none",
    },
)

RemoveInstance

Burns an instance from the world.

instance destroy single targeted

Removes an instance regardless of current placement. The instance cannot have attached children. Grid or slot references are cleared as part of the burn.

Errors:

  • InstanceNotFound: The target instance ID does not exist.
  • HasChildren: Children must be detached before burning the instance.

Commentary:

  • Remove an instance and clear any placements.

Examples:

await client.actions.remove_instance(
    instance="instance-9001",
)

BurnInstance

Removes a unique instance permanently from the substrate.

instance destroy single targeted

Permanently deletes a unique instance. The instance must not be attached to other instances or placed in a slot. The identifier is never reused once burned.

Errors:

  • InstanceNotFound: The target instance ID does not exist.
  • HasChildren: Children must be detached before burning the instance.

Commentary:

  • Permanently delete an instance id; it will never be reused.

Examples:

await client.actions.burn_instance(
    instance_id="instance-9001",
)

Attach

Attaches a child instance to a parent for linked movement.

instance link multi targeted

Creates a parent-child relationship between two instances so they move together. The child can only have one parent, and cycles are rejected to keep the instance graph acyclic.

Errors:

  • InvalidOperation: Child and parent must differ and cycles are rejected.
  • InstanceNotFound: The child or parent instance does not exist.
  • AlreadyAttached: The child already has a parent.
  • WouldCreateCycle: Attachment would create a cycle in the hierarchy.

Commentary:

  • Attach a child instance to a parent instance.

Examples:

await client.actions.attach(
    child_instance="instance-9002",
    parent_instance="instance-9001",
)

Detach

Detaches a child instance from its parent instance.

instance link single targeted

Removes the parent-child relationship so the child becomes independent while remaining in the memory substrate. The child retains its ID and can be reattached elsewhere.

Errors:

  • InstanceNotFound: The specified instance does not exist.
  • NotAttached: The instance has no parent to detach from.

Commentary:

  • Detach a child instance from its parent instance.

Examples:

await client.actions.detach(
    child_instance="instance-9002",
)

PlaceInSlot

Positions an instance into an addressable slot within a container.

slot move single targeted

Places a unique instance into a specific slot in a container that supports slot layouts. The slot must be empty and the container kind must allow slot placement, preserving deterministic positioning.

Errors:

  • ContainerNotFound: The destination container does not exist.
  • WrongContainerKind: Only Slots containers support slot placement.
  • SlotOutOfBounds: Slot index exceeds the container capacity.
  • InstanceNotFound: The instance being placed does not exist.
  • SlotOccupied: The requested slot is already occupied.

Commentary:

  • Place an instance into a specific slot index.

Examples:

await client.actions.place_in_slot(
    container_id="container-1001",
    instance_id="instance-9001",
    slot_index=1,
)

RemoveFromSlot

Removes an instance from a container slot.

slot move single targeted

Clears a slot and leaves the instance unplaced. The instance remains in the memory substrate but no longer occupies that positional binding, enabling repositioning.

Errors:

  • ContainerNotFound: The container does not exist.
  • WrongContainerKind: Only Slots containers support slot removal.
  • SlotOutOfBounds: Slot index exceeds the container capacity.
  • SlotEmpty: The slot does not contain an instance to remove.

Commentary:

  • Clear a slot without destroying the instance itself.

Examples:

await client.actions.remove_from_slot(
    container_id="container-1001",
    slot_index=1,
)

SwapSlots

Swaps the contents of two occupied slots atomically.

slot move multi targeted

Atomically exchanges the contents of two slots, which can reside in the same or different containers. Both slots must exist and be occupied. The swap preserves positional invariants across containers.

Errors:

  • InvalidOperation: Cannot swap a slot with itself in the same container.
  • ContainerNotFound: One of the containers does not exist.
  • WrongContainerKind: Both containers must be Slots type.
  • SlotOutOfBounds: One of the slot indices exceeds the container capacity.
  • SlotEmpty: A slot is empty and cannot be swapped.

Commentary:

  • Swap the contents of two slots in a single atomic operation.

Examples:

await client.actions.swap_slots(
    container_a="container-1001",
    container_b="container-1001",
    slot_a=1,
    slot_b=5,
)

RegisterClass

Registers a class definition so future operations can reference it.

schema create single targeted

Registers a class external ID and name so transactions can reference the class and apply its validation rules. External IDs are namespace-scoped and immutable once registered; internal IDs are auto-assigned and never exposed.

Errors:

  • ClassAlreadyExists: The provided class_id (external identifier) is already in use.
  • ClassCapacityExceeded: The global class registry has reached its configured limit.

Commentary:

  • Register a class id with flags and a human-readable name.

Examples:

await client.actions.register_class(
    request={"class_id": "class-100", "flags": 2, "name": "ExampleClass"},
)

RegisterClassShape

Registers a grid shape footprint for a class or class variant.

schema create single targeted

Defines the width/height shape for a class_id (external identifier) and optional stack_key so grid placements can validate occupancy and rotation. Shapes are required before placing instances or stacks into grid containers for that class. Re-registering an identical shape is treated as a no-op.

Errors:

  • ClassNotFound: The referenced class_id (external identifier) has not been registered.
  • ShapeAlreadyDefined: The shape_id already exists for the class.

Commentary:

  • Register a grid shape for a class and optional stack key.

Examples:

await client.actions.register_class_shape(
    request={"class_id": "class-200", "shape": {"height": 3, "width": 2}},
)

RegisterClassContinuousShape2d

Registers a continuous 2D rectangle for a class or class variant.

schema create single targeted

Defines the fixed-point rectangle for a class_id (external identifier) and optional stack_key so continuous 2D placements can validate collisions and rotations. Required before placing into continuous_grid_2d containers for that class. Re-registering an identical rectangle is treated as a no-op.

Errors:

  • ClassNotFound: The referenced class_id (external identifier) has not been registered.
  • ContinuousShapeAlreadyDefined: The continuous shape is already registered for the class/key.

Commentary:

  • Register a continuous 2D rectangle shape for placements.

Examples:

await client.actions.register_class_continuous_shape2d(
    request={"class_id": "class-200", "rect": {"height": 8, "width": 10}},
)

RegisterClassContinuousShape1d

Registers a continuous 1D span for a class or class variant.

schema create single targeted

Defines the fixed-point span length for a class_id (external identifier) and optional stack_key so continuous 1D placements can validate collisions. Required before placing into continuous_line_1d containers for that class. Re-registering an identical span is treated as a no-op.

Errors:

  • ClassNotFound: The referenced class_id (external identifier) has not been registered.
  • ContinuousShapeAlreadyDefined: The continuous shape is already registered for the class/key.

Commentary:

  • Register a continuous 1D span shape for placements.

Examples:

await client.actions.register_class_continuous_shape1d(
    request={"class_id": "class-200", "span": {"length": 10}},
)