Container Examples & Demonstrations

Concrete, runnable-in-spirit examples of Asset Core's container shapes—demonstrating deterministic world-state coordination across robotics, games, simulations, and automation.

0D Balance

A shared pool of compute credits or energy units. Transactions debit or credit a fixed-point scalar value—no positions, only quantity.

This example is intentionally small. It shows how deterministic balances work when the only question is “how much,” not “where.” Use it as a template for any pooled resource with strict audit requirements.

What this shows

0D algebraic quantities (fixed-point), no spatial coordinates
Atomic balance adjustments (debit/credit)
Deterministic replay of transaction history
Multi-actor shared resource pools

Example operations

{
  "operations": [
    {
      "op": "CreateContainer",
      "args": {
        "container_id": 1001,
        "kind": { "type": "balance" },
        "owner": null,
        "policies": null
      }
    },
    {
      "op": "AddFungible",
      "args": {
        "class_id": 5001,
        "key": 1,
        "location": { "container_id": 1001, "kind": "balance" },
        "quantity": "100"
      }
    },
    {
      "op": "RemoveFungible",
      "args": {
        "class_id": 5001,
        "key": 1,
        "from": { "container_id": 1001, "kind": "balance" },
        "quantity": "50"
      }
    }
  ]
}

This creates balance container 1001, credits 100 units of class_id 5001 (energy_unit), then burns 50 units, leaving 50 in the pool.

Diagram legend: before = 100 units, after = 50 units in container 1001 (energy_pool).

Use a 0D balance when only “how much” matters, not “where” it is held.

Deterministic guarantee: Identical sequences yield identical results.

Example scenario: An automation service or agent managing compute credits for a cluster. Operation calls:

check_balance() → query current credits
reserve_credits(job_id, amount) → atomic deduction
release_credits(job_id) → refund on job completion

Asset Core enforces the balance rules you define—floors, ceilings, and optional negative balances—with a full audit trail of every credit transaction.

0D Slots

An entity exposes 8 tool slots. Tools like a camera or gripper occupy exactly one slot; slots have no geometry—just labeled positions.

Slots are about exclusivity and intent, not coordinates. This example shows how to guarantee that a slot is either occupied or empty, with no ambiguous intermediate state.

What this shows

Discrete positions without geometric relationships
Tool/equipment management with slot exclusivity
Deterministic equipment state
Semantic positioning (not spatial coordinates)

Example operations

{
  "operations": [
    {
      "op": "CreateContainer",
      "args": {
        "container_id": 2001,
        "kind": { "type": "slots", "count": 8 },
        "owner": null,
        "policies": null
      }
    },
    {
      "op": "AddInstance",
      "args": {
        "class_id": 5201,
        "key": 1,
        "location": {
          "container_id": 2001,
          "kind": "slot",
          "slot_index": 3
        }
      }
    }
  ]
}

This creates slots container 2001 and places class_id 5201 (camera_head) into slot_index 3.

Diagram legend: slot 3 holds camera_head.

Use slots when you need mutually exclusive positions with labels, but no spatial geometry.

Deterministic guarantee: Identical sequences produce identical slot configurations.

Example scenario: A robot controller or agent managing 8 tool slots. Operation calls:

list_equipped_tools() → query current equipment
equip_tool(slot_id, tool_name) → atomic slot assignment
swap_tools(slot_a, slot_b) → transactional exchange

Asset Core enforces slot exclusivity—no phantom tools, no double-equip, and full provenance of every equipment change.

1D Grid

A conveyor lane with positions 1..5. Systems place and move packages along a single axis; two items can’t occupy the same position.

The point here is sequencing and collision prevention along a single axis. It’s the simplest spatial case where ordering matters and invalid moves must be rejected deterministically.

What this shows

Linear spatial semantics (single-axis positioning)
Collision detection and position exclusivity
Sequential move operations
Deterministic placement and move ordering

Example operations

{
  "operations": [
    {
      "op": "CreateContainer",
      "args": {
        "container_id": 3001,
        "kind": {
          "type": "grid",
          "capacity": 5,
          "grid_width": null
        },
        "owner": null,
        "policies": null
      }
    },
    {
      "op": "AddInstance",
      "args": {
        "class_id": 5301,
        "key": 1,
        "location": {
          "container_id": 3001,
          "kind": "grid_cell",
          "position": 3,
          "rotation": "none"
        }
      }
    }
  ]
}

This creates grid container 3001 with 5 positions and places class_id 5301 (package_42) at position 3.

Diagram legend: P42 marks class_id 5301 (package_42) at position 3.

Use a 1D grid when order along a single lane matters and collisions must be prevented.

Deterministic guarantee: Identical sequences yield identical results.

Example scenario: A conveyor controller managing a belt. Operation calls:

get_item_position(item_id) → query location on belt
move_item(item_id, target_position) → collision-safe movement
remove_item(item_id) → atomic removal from belt

Asset Core prevents double-occupancy, tracks item order, and enables perfect replay of conveyor operations.

1D Continuous

A calibrated rail with millimeter resolution. A robot carriage moves along a continuous axis using fixed-point coordinates.

Continuous containers are fixed-point, not floating-point. That choice makes replay deterministic and removes rounding drift across long sequences of moves.

What this shows

Fixed-point coordinates with deterministic rounding
Bounds-checked placement along a single axis
Continuous collision checks for overlapping spans
Commit/replay semantics identical to discrete containers

Example operations

{
  "operations": [
    {
      "op": "CreateContainer",
      "args": {
        "container_id": 4001,
        "kind": {
          "type": "continuous_line_1d",
          "min_x": 0,
          "max_x": 200000,
          "quantization_inv": 1000,
          "bucket_cell_size": 10000
        },
        "owner": null,
        "policies": null
      }
    },
    {
      "op": "AddInstance",
      "args": {
        "class_id": 5401,
        "key": 1,
        "location": {
          "container_id": 4001,
          "kind": "continuous_1d",
          "coord": { "x": 25000 }
        }
      }
    }
  ]
}

This creates continuous_line_1d container 4001 and places class_id 5401 at x=25.000 (quantization_inv=1000).

Diagram legend: C = carriage_A.

Use a 1D continuous line when real-world distances along a single axis must be preserved.

Deterministic guarantee: Identical sequences yield identical results.

Example scenario: A linear rail controller managing a single axis. Operation calls:

get_carriage_position(carriage_id) → query current coordinate
move_carriage(carriage_id, target_x) → collision-safe movement
reserve_span(start_x, end_x) → ensure exclusive travel window

Asset Core enforces deterministic placement, prevents overlap, and provides exact replay of rail motion.

2D Grid

A small warehouse grid (5×5). Robots and packages occupy discrete coordinates; committed moves are serialized to prevent collisions.

This example demonstrates multi-actor coordination in a shared grid where every placement is authoritative. It is a good template for warehouses, lab plates, and tactical board layouts.

What this shows

Two-dimensional spatial semantics (x, y coordinates)
Multi-entity collision detection
Coordinate-based placement and movement
Authoritative grid state for multi-actor coordination

Example operations

{
  "operations": [
    {
      "op": "CreateContainer",
      "args": {
        "container_id": 5001,
        "kind": {
          "type": "grid",
          "capacity": 25,
          "grid_width": 5
        },
        "owner": null,
        "policies": null
      }
    },
    {
      "op": "AddInstance",
      "args": {
        "class_id": 5501,
        "key": 1,
        "location": {
          "container_id": 5001,
          "kind": "grid_cell",
          "position": 21,
          "rotation": "none"
        }
      }
    },
    {
      "op": "AddInstance",
      "args": {
        "class_id": 5502,
        "key": 1,
        "location": {
          "container_id": 5001,
          "kind": "grid_cell",
          "position": 22,
          "rotation": "none"
        }
      }
    }
  ]
}

This creates 5×5 grid container 5001 and places class_id 5501 (robot_A) at position 21 and class_id 5502 (package_12) at position 22.

Diagram legend: R = class_id 5501 (robot_A), P = class_id 5502 (package_12).

Use a 2D grid when systems need shared coordinates, neighborhood awareness, and collision-safe movement.

Deterministic guarantee: Identical sequences produce identical world states.

Example scenario: Multiple autonomous actors (robots, services, or agents) navigating a shared warehouse floor. Operation calls:

get_robot_position(robot_id) → query current coordinates
plan_path(start, goal) → collision-aware pathfinding
move_robot(robot_id, target_coords) → atomic, collision-safe movement

Asset Core provides authoritative spatial state—no ghost positions, no collisions, and full coordination history across all participants.

2D Continuous

A bounded workcell for pick-and-place robotics. Placements use fixed-point x/y coordinates with deterministic rotation in millidegrees.

Continuous 2D is where deterministic geometry matters most. This example highlights how fixed-point coordinates and rotation rules keep replay exact, even in dense workcells.

What this shows

Fixed-point x/y coordinates with explicit quantization
Oriented-rectangle collision checks (OBB)
Bounds-checked placements, moves, and rotations
Deterministic replay of multi-actor motion plans

Example operations

{
  "operations": [
    {
      "op": "CreateContainer",
      "args": {
        "container_id": 6001,
        "kind": {
          "type": "continuous_grid_2d",
          "min_x": 0,
          "min_y": 0,
          "max_x": 200000,
          "max_y": 120000,
          "quantization_inv": 1000,
          "bucket_cell_size": 10000
        },
        "owner": null,
        "policies": null
      }
    },
    {
      "op": "AddInstance",
      "args": {
        "class_id": 5601,
        "key": 1,
        "location": {
          "container_id": 6001,
          "kind": "continuous_2d",
          "coord": { "x": 25000, "y": 40000 },
          "rotation_millideg": 0
        }
      }
    },
    {
      "op": "AddInstance",
      "args": {
        "class_id": 5602,
        "key": 1,
        "location": {
          "container_id": 6001,
          "kind": "continuous_2d",
          "coord": { "x": 110000, "y": 30000 },
          "rotation_millideg": 90000
        }
      }
    }
  ]
}

This creates continuous_grid_2d container 6001, places class_id 5601 (gripper_A) at (25.000, 40.000), and places class_id 5602 (part_17) at (110.000, 30.000).

Diagram legend: G = class_id 5601 (gripper_A), P = class_id 5602 (part_17).

Use a 2D continuous container when physical coordinates and rotation must be preserved.

Deterministic guarantee: Identical sequences produce identical world states.

Example scenario: A robot planner coordinating picks in a shared workcell. Operation calls:

preflight_commit(pick_plan) → validate the sequence without mutation
commit(pick_plan) → execute once preflight succeeds
read_workcell_region(bounds) → query nearby placements for collision checks

Asset Core ensures preflight and commit stay in lockstep while preserving a deterministic audit trail.

Universal Transfer

Asset Core’s operations work consistently across container types. The same grammar applies whether transferring between balances, slots, or grids—demonstrating the universal operation model.

This section is useful when you need to explain the system to stakeholders who assume separate APIs for each container type. The point is that operations stay stable while the geometry changes.

What this shows

Unified operation semantics across dimensions
Cross-container state transitions
Consistent commit log for multi-container workflows
Composable world-state transformations

Example: Balance → 2D Grid Transfer

{
  "operations": [
    {
      "op": "CreateContainer",
      "args": {
        "container_id": 7001,
        "kind": { "type": "balance" },
        "owner": null,
        "policies": null
      }
    },
    {
      "op": "CreateContainer",
      "args": {
        "container_id": 7002,
        "kind": {
          "type": "grid",
          "capacity": 25,
          "grid_width": 5
        },
        "owner": null,
        "policies": null
      }
    },
    {
      "op": "MoveFungible",
      "args": {
        "class_id": 5701,
        "key": 1,
        "quantity": "1",
        "from": { "container_id": 7001, "kind": "balance" },
        "to": {
          "container_id": 7002,
          "kind": "grid_cell",
          "position": 13,
          "rotation": "none"
        }
      }
    }
  ]
}

This moves quantity for class_id 5701 (widget) from balance container 7001 into a grid placement in container 7002—same operation grammar, different container types.

Same grammar (class_id, locations, quantities) across container types; deterministic ordering ties both changes to one commit history.

Example scenario: A workcell controller transferring parts from a pool (0D balance) to assembly positions (2D grid). Operation calls:

check_parts_available() → query balance
reserve_and_place(part_type, grid_coords) → atomic cross-container operation

Asset Core commits both changes atomically—no phantom inventory, no lost parts, and a unified audit trail across container types.

Learn More

For technical details, see Basics for architecture and container types, or the Docs for deeper technical documentation. For an end-to-end workflow with real calls and logs, see the Robotic Arm Continuous scenario.