Arxi Decision Gate Asset Core
Docs
Asset Core Docs

Deterministic world-state engine documentation and API references.

Decision Gate docs

Lab Chain-of-Custody: Reconciliation Under Audit

Seed a lab rack from a declarative manifest, trigger a deterministic preflight failure, and reconcile via grid-free placement.

If you are reading this cold, this is a lab reconciliation workflow: deterministic custody tracking, preflight conflict detection, and a verified remediation move. Every custody change is an auditable commit so investigators can replay, verify, and explain what happened without inference.

The Problem: Custody Breaks Under Audit

Clinical chains of custody fail when physical inventory, scanner logs, and operational systems disagree. When a placement fails, you need deterministic evidence that the system detected the conflict before any state change.

This scenario demonstrates a production-grade pattern: a forced preflight failure, a read-guided remediation, and a replayable audit trail.

Why this matters

Regulated labs need traceable custody and deterministic remediation when conflicts appear. Asset Core makes custody authoritative by treating every change as a deterministic, replayable transaction.

System model

  • Racks: grid containers enforcing occupancy rules per lab.
  • Scanner bay: slot container for in-flight custody checks.
  • Reagent pools: balance containers with fixed-point quantization.
  • Classes and shapes: registered so placement rules stay consistent.
  • Units: cells (fixed_point_scale=1000).

Workflow at a glance

  1. Setup - Register classes and create lab containers.
  2. Seed - Seed initial tubes and balances.
  3. Preflight Blocked - Preflight fails when placing into an occupied cell.
  4. Grid Free - Select the next available grid anchor.
  5. Reconcile - Move the scanner tube into a verified free anchor.
  6. Verify Grid - Confirm reconciled placement in read projection.

How to read the walkthrough

  • Single-operation steps use action helpers for readability.
  • Multi-operation steps stay as commit calls to preserve atomicity.
  • Rust HTTP always uses the commit endpoint with one or more operations.

Scenario artifacts

Latest verification

  • Run ID: 2026-01-19T18-52-12Z-lab_chain_of_custody
  • Status: Passed
  • Integrity root hash: efcb02df86d0dd2bb9ffd14d8a7403e52bd06b7c5f56fb4fc4f04703dc9f542f
  • Checks:
    • {'kind': 'structural_invariants'}: passed
    • {'kind': 'world_seq_monotonic'}: passed
    • {'kind': 'global_seq_monotonic'}: passed
    • {'kind': 'owner_scope', 'allowed_owners': [1, 2]}: passed
    • {'kind': 'quantity_conservation', 'container_id': 4, 'class_id': 2, 'stack_key': None, 'expected': 250000}: passed
    • {'kind': 'replay_idempotent'}: passed
    • {'kind': 'commit_log_integrity', 'expected_chain_hash': 'aa3301e51d32150b30281395b68f6df815eaff8416260789832c06259e84a30c', 'expected_prev_chain_hash': 'c387f5f5a7fec5ce1223fa9dcbc8d564a5221e50a7afa1fba498c625d693f064', 'expected_start_offset': 1, 'expected_end_offset': 3, 'expected_entry_count': 3, 'expected_last_global_seq': 38}: passed
    • {'kind': 'runpack_integrity'}: passed

Runpack downloads

Scenario snapshot

{
  "scenario_id": "lab_chain_of_custody",
  "version": "0.1.0",
  "namespace_id": 2,
  "containers": {
    "rack_lab_a": "container-32001",
    "rack_lab_b": "container-32002",
    "reagent_pool_lab_a": "container-32004",
    "reagent_pool_lab_b": "container-32005",
    "scanner_bay_lab_a": "container-32003"
  },
  "classes": {
    "reagent_buffer": "class-42002",
    "sample_tube": "class-42001"
  },
  "units": {
    "fixed_point_scale": 1000,
    "length_unit": "cells",
    "time_unit": "ms"
  }
}

Failure branch

POSITION_OCCUPIED -> grid_free -> reconcile move

Audit trail (optional)

The transcript captures the exact request and response pairs emitted during the run. Here is a compact excerpt you can use to validate determinism and metadata propagation:

{
  "kind": "commit",
  "name": "setup",
  "request": {
    "path": "/v1/write/namespaces/2/commit",
    "idempotency_key": "lab-chain-setup",
    "actor_id": "lab-chain",
    "metadata": {
      "phase": "setup",
      "scenario": "lab_chain_of_custody"
    },
    "operations": [
      "RegisterClass",
      "RegisterClassShape",
      "RegisterClass",
      "CreateContainer",
      "CreateContainer",
      "CreateContainer",
      "CreateContainer",
      "CreateContainer"
    ]
  },
  "response": {
    "commit_id": "00000000000000000000000000000003",
    "world_seq_start": 1,
    "world_seq_end": 8,
    "event_count": 8
  }
}

Preflight note

  • Action calls submit commits by default.
  • Set ActionOptions(preflight=True) or call assetcore_commit_preflight for validation.

SDK setup

from assetcore_sdk import AssetCoreClient
from assetcore_sdk.actions import ActionOptions
from assetcore_sdk.operations import (
    AddFungible,
    AddInstance,
    CreateContainer,
    MoveInstance,
    RegisterClass,
    RegisterClassShape,
)

# Snippets assume an async context (e.g., inside async def main()).
write_client = AssetCoreClient(
    base_url="http://localhost:8080",
    api_key="WRITE_API_KEY",
)
read_client = AssetCoreClient(
    base_url="http://localhost:8081",
    api_key="READ_API_KEY",
)

Walkthrough

Step 1: Setup

Register classes and create lab containers.

Operations

  • RegisterClass (x2) - Registers a class definition so future operations can reference it.
  • RegisterClassShape - Registers a grid shape footprint for a class or class variant.
  • CreateContainer (x5) - Creates a container (structured memory region) with the requested kind.
await write_client.commit_operations(
    [
        RegisterClass(
            request={
                "behavior": {"balance_scale": 1},
                "class_id": "class-42001",
                "flags": 0,
                "name": "sample_tube",
            },
        ),
        RegisterClassShape(
            request={"class_id": "class-42001", "shape": {"height": 1, "width": 1}},
        ),
        RegisterClass(
            request={
                "behavior": {"balance_scale": 1000},
                "class_id": "class-42002",
                "flags": 0,
                "name": "reagent_buffer",
            },
        ),
        CreateContainer(
            client_tag="rack_lab_a",
            external_id="container-32001",
            kind={"capacity": 96, "grid_width": 12, "type": "grid"},
            owner_external_id="owner-101",
            policies=None,
        ),
        CreateContainer(
            client_tag="rack_lab_b",
            external_id="container-32002",
            kind={"capacity": 96, "grid_width": 12, "type": "grid"},
            owner_external_id="owner-102",
            policies=None,
        ),
        CreateContainer(
            client_tag="scanner_bay_lab_a",
            external_id="container-32003",
            kind={"count": 2, "type": "slots"},
            owner_external_id="owner-101",
            policies=None,
        ),
        CreateContainer(
            client_tag="reagent_pool_lab_a",
            external_id="container-32004",
            kind={"quantization_inv": 1000, "type": "balance"},
            owner_external_id="owner-101",
            policies=None,
        ),
        CreateContainer(
            client_tag="reagent_pool_lab_b",
            external_id="container-32005",
            kind={"quantization_inv": 1000, "type": "balance"},
            owner_external_id="owner-102",
            policies=None,
        ),
    ],
    namespace_id=2,
    idempotency_key="lab-chain-setup",
    actor_id="lab-chain",
    metadata={"phase": "setup", "scenario": "lab_chain_of_custody"},
)

Step 2: Seed

Seed initial tubes and balances.

Operations

  • AddInstance (x25) - Mints a new instance and places it at a target location.
  • AddFungible (x2) - Adds fungible quantity to a balance or an explicit grid cell.
await write_client.commit_operations(
    [
        AddInstance(
            class_id="class-42001",
            client_tag="tube-001",
            key=None,
            location={
                "container_id": "container-32001",
                "kind": "grid_cell",
                "position": 1,
                "rotation": None,
            },
        ),
        AddInstance(
            class_id="class-42001",
            client_tag="tube-002",
            key=None,
            location={
                "container_id": "container-32001",
                "kind": "grid_cell",
                "position": 2,
                "rotation": None,
            },
        ),
        AddInstance(
            class_id="class-42001",
            client_tag="tube-003",
            key=None,
            location={
                "container_id": "container-32001",
                "kind": "grid_cell",
                "position": 3,
                "rotation": None,
            },
        ),
        AddInstance(
            class_id="class-42001",
            client_tag="tube-004",
            key=None,
            location={
                "container_id": "container-32001",
                "kind": "grid_cell",
                "position": 4,
                "rotation": None,
            },
        ),
        AddInstance(
            class_id="class-42001",
            client_tag="tube-005",
            key=None,
            location={
                "container_id": "container-32001",
                "kind": "grid_cell",
                "position": 5,
                "rotation": None,
            },
        ),
        AddInstance(
            class_id="class-42001",
            client_tag="tube-006",
            key=None,
            location={
                "container_id": "container-32001",
                "kind": "grid_cell",
                "position": 6,
                "rotation": None,
            },
        ),
        AddInstance(
            class_id="class-42001",
            client_tag="tube-007",
            key=None,
            location={
                "container_id": "container-32001",
                "kind": "grid_cell",
                "position": 7,
                "rotation": None,
            },
        ),
        AddInstance(
            class_id="class-42001",
            client_tag="tube-008",
            key=None,
            location={
                "container_id": "container-32001",
                "kind": "grid_cell",
                "position": 8,
                "rotation": None,
            },
        ),
        AddInstance(
            class_id="class-42001",
            client_tag="tube-009",
            key=None,
            location={
                "container_id": "container-32001",
                "kind": "grid_cell",
                "position": 9,
                "rotation": None,
            },
        ),
        AddInstance(
            class_id="class-42001",
            client_tag="tube-010",
            key=None,
            location={
                "container_id": "container-32001",
                "kind": "grid_cell",
                "position": 10,
                "rotation": None,
            },
        ),
        AddInstance(
            class_id="class-42001",
            client_tag="tube-011",
            key=None,
            location={
                "container_id": "container-32001",
                "kind": "grid_cell",
                "position": 11,
                "rotation": None,
            },
        ),
        AddInstance(
            class_id="class-42001",
            client_tag="tube-012",
            key=None,
            location={
                "container_id": "container-32001",
                "kind": "grid_cell",
                "position": 12,
                "rotation": None,
            },
        ),
        AddInstance(
            class_id="class-42001",
            client_tag="tube-013",
            key=None,
            location={
                "container_id": "container-32001",
                "kind": "grid_cell",
                "position": 13,
                "rotation": None,
            },
        ),
        AddInstance(
            class_id="class-42001",
            client_tag="tube-014",
            key=None,
            location={
                "container_id": "container-32001",
                "kind": "grid_cell",
                "position": 14,
                "rotation": None,
            },
        ),
        AddInstance(
            class_id="class-42001",
            client_tag="tube-015",
            key=None,
            location={
                "container_id": "container-32001",
                "kind": "grid_cell",
                "position": 15,
                "rotation": None,
            },
        ),
        AddInstance(
            class_id="class-42001",
            client_tag="tube-016",
            key=None,
            location={
                "container_id": "container-32001",
                "kind": "grid_cell",
                "position": 16,
                "rotation": None,
            },
        ),
        AddInstance(
            class_id="class-42001",
            client_tag="tube-017",
            key=None,
            location={
                "container_id": "container-32001",
                "kind": "grid_cell",
                "position": 17,
                "rotation": None,
            },
        ),
        AddInstance(
            class_id="class-42001",
            client_tag="tube-018",
            key=None,
            location={
                "container_id": "container-32001",
                "kind": "grid_cell",
                "position": 18,
                "rotation": None,
            },
        ),
        AddInstance(
            class_id="class-42001",
            client_tag="tube-019",
            key=None,
            location={
                "container_id": "container-32001",
                "kind": "grid_cell",
                "position": 19,
                "rotation": None,
            },
        ),
        AddInstance(
            class_id="class-42001",
            client_tag="tube-020",
            key=None,
            location={
                "container_id": "container-32001",
                "kind": "grid_cell",
                "position": 20,
                "rotation": None,
            },
        ),
        AddInstance(
            class_id="class-42001",
            client_tag="tube-021",
            key=None,
            location={
                "container_id": "container-32001",
                "kind": "grid_cell",
                "position": 21,
                "rotation": None,
            },
        ),
        AddInstance(
            class_id="class-42001",
            client_tag="tube-022",
            key=None,
            location={
                "container_id": "container-32001",
                "kind": "grid_cell",
                "position": 22,
                "rotation": None,
            },
        ),
        AddInstance(
            class_id="class-42001",
            client_tag="tube-023",
            key=None,
            location={
                "container_id": "container-32001",
                "kind": "grid_cell",
                "position": 23,
                "rotation": None,
            },
        ),
        AddInstance(
            class_id="class-42001",
            client_tag="tube-024",
            key=None,
            location={
                "container_id": "container-32001",
                "kind": "grid_cell",
                "position": 24,
                "rotation": None,
            },
        ),
        AddInstance(
            class_id="class-42001",
            client_tag="scanner-tube",
            key=None,
            location={
                "container_id": "container-32003",
                "kind": "slot",
                "slot_index": 1,
            },
        ),
        AddFungible(
            class_id="class-42002",
            client_tag="reagent-a",
            key=None,
            location={"container_id": "container-32004", "kind": "balance"},
            quantity="250",
        ),
        AddFungible(
            class_id="class-42002",
            client_tag="reagent-b",
            key=None,
            location={"container_id": "container-32005", "kind": "balance"},
            quantity="125",
        ),
    ],
    namespace_id=2,
    idempotency_key="lab-chain-seed",
    actor_id="lab-chain",
    metadata={"phase": "seed", "scenario": "lab_chain_of_custody"},
)

Step 3: Preflight Blocked (Expected error)

Preflight fails when placing into an occupied cell.

Operations

  • MoveInstance - Moves an existing instance to a new location.

Expected error

{
  "code": "POSITION_OCCUPIED",
  "detail": "Position 6 in container 1 is occupied by item at anchor 6",
  "hint": "Select an unoccupied position or move the existing item first.",
  "retryable": false,
  "status": 409,
  "title": "ConflictError",
  "type": "urn:assetcore:error:POSITION_OCCUPIED"
}

await write_client.actions.move_instance(
    instance="inst-25",
    to={
        "container_id": "container-32001",
        "kind": "grid_cell",
        "position": 6,
        "rotation": None,
    },
    options=ActionOptions(
        namespace_id=2,
        idempotency_key="lab-chain-blocked",
        actor_id="lab-chain",
        metadata={"phase": "exception", "scenario": "lab_chain_of_custody"},
    ),
)

Step 4: Grid Free

Select the next available grid anchor.

await read_client.get_container_grid_free(
    container_id="container-32001",
    namespace_id=2,
    height=1,
    width=1,
)

Step 5: Reconcile

Move the scanner tube into a verified free anchor.

Operations

  • MoveInstance - Moves an existing instance to a new location.
await write_client.actions.move_instance(
    instance="inst-25",
    to={
        "container_id": "container-32001",
        "kind": "grid_cell",
        "position": 25,
        "rotation": None,
    },
    options=ActionOptions(
        namespace_id=2,
        idempotency_key="lab-chain-reconcile",
        actor_id="lab-chain",
        metadata={
            "phase": "reconcile",
            "scenario": "lab_chain_of_custody",
            "target_anchor": 25,
        },
    ),
)

Step 6: Verify Grid

Confirm reconciled placement in read projection.

await read_client.get_container_grid(
    container_id="container-32001",
    namespace_id=2,
)