Lab Location & Asset Mapping

An auditor does not ask whether your centrifuge exists — they ask where it was on the day a grant was charged for its use. Spatial ambiguity is the failure mode that turns a routine federal property review into a finding: an instrument whose room of record is a stale sticker, a regulated reagent whose storage zone cannot be tied to a permitted hazard class, a fume-hood monitor that the registry places in a building that was decommissioned two years ago. Lab location and asset mapping is the layer that closes that gap. It binds every physical asset to a validated campus → building → floor → room coordinate, records each move as a timestamped, cryptographically chained event, and refuses to silently relocate an asset whose target zone cannot be authorized. This guide is one of the spatial layers anchored to the parent guide on Equipment Calibration & Lab Inventory Tracking.

University administrators, research compliance officers, Python automation developers, and laboratory managers rely on this subsystem to make location a hard, auditable attribute rather than tribal knowledge. By normalizing heterogeneous source records — procurement ERP exports, departmental spreadsheets, RFID walkthrough scans, and legacy room registries — against a single authorized facility schema, applying a deterministic idempotency key, and appending every spatial decision to an immutable ledger, the layer produces evidence that survives a 2 CFR §200.313 property reconciliation and an OSHA chemical-inventory inspection without manual reconstruction.

Problem framing #

The naive model treats location as a free-text column: a technician types “Eng 1, rm 123” and a spreadsheet calls it done. That model collapses the moment institutional reality accumulates. A procurement record imports an asset with a building code that no longer exists. A departmental spreadsheet spells the same room four different ways. An RFID walkthrough double-reads a tag in a high-density storage rack and reports the instrument in two rooms within the same second. A reagent is moved between two satellite buildings, but the move is never written, so an emergency responder pulls a hazard map that is silently wrong.

The job of this layer is to make spatial registration a policy enforcement step, not a data-entry convenience. Three contracts, implemented across the rest of this page, hold the line:

• Determinism. A given asset and a given resolved location always produce the same idempotency key and the same ledger outcome, independent of arrival order or which source system emitted the record.
• Idempotency. Each spatial assignment is fingerprinted with SHA-256 over the canonical asset_id + campus_id + building_id + room_code tuple. Re-processing the same assignment — a cron overlap, a re-uploaded export, an RFID re-scan — returns the cached decision and writes no duplicate ledger entry.
• Quarantine over silent correction. An asset whose target campus, building, or room is not present in the authorized facility registry is routed to a quarantine queue, not auto-assigned to a default room. It is held for principal-investigator sign-off before it can reach the master ledger.

These are the same guarantees the rest of the equipment platform inherits from the Grant Lifecycle Architecture Design; here they are specialized to the hierarchical, jurisdiction-bound nature of physical space.

Policy constraints #

Compliance is the architectural constraint that bounds which spatial assignments are legal, not a report generated after the fact. The regulatory matrix codified in the University Policy Mapping Frameworks governs every move event: which assets must be anchored to a room, which storage zones carry hazard restrictions, and how long location history must be retained. Treat the mapping engine as the enforcement layer for that matrix — it validates each assignment against authorized zones and escalates anything that cannot be resolved, so institutional audit trails stay immutable and no asset drifts into an unpermitted space.

Operational boundary. Policy dictates which assets must be anchored, which hazard classes a zone may hold, and how long location history is retained; implementation handles the mechanical resolution, hashing, and dispatch. The engine must never invent a location to avoid a quarantine — a record that cannot be resolved to an authorized zone is escalated through formal change control. Credential scoping for the mapping workers, including who may reassign a restricted asset, is governed by the Security Boundary Configuration so that role-based access controls prevent unauthorized spatial reassignment.

Data schema & field mapping #

A location payload is a versioned policy artifact, not a convenience record. Source rows arrive with mixed building codes, free-text room labels, and optional hazard tags; before any record is registered, those fields map to a single canonical schema whose constraints encode the regulatory rules above. The facility hierarchy is itself authoritative — a room is only valid if its parent floor, building, and campus all resolve — so the schema enforces referential integrity against the registry rather than trusting the inbound string.

The hierarchy that every asset is bound to:

Figure: the campus to building to floor to room hierarchy binds every asset to a jurisdictional zone (e.g., BSL-2, EPA-regulated exhaust).

The idempotency_key and move_status are the only system-owned fields; everything else maps from the source payload. Stamping the resolved outcome onto every move event is what lets an auditor later prove which zone an asset occupied — and under which hazard classification — at a given moment, which is essential when a room’s permitted hazard class changes mid-grant.

Implementation #

The implementation validates each inbound record with Pydantic, resolves it against the authorized facility hierarchy, computes a deterministic idempotency key, and performs an idempotent upsert with SQLAlchemy. A record that fails zone resolution is routed to a quarantine queue rather than written to the master table, and any genuine change of room appends one entry to the append-only ledger. The same validation contract used here is shared with portal and spreadsheet imports through the Schema Validation Pipelines, so an asset is validated identically however it enters the platform.

import hashlib
import logging
from datetime import datetime, timezone
from enum import Enum
from typing import Optional

from pydantic import BaseModel, EmailStr, Field, ValidationError
from sqlalchemy import String, DateTime, select
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, Session
from sqlalchemy.dialects.postgresql import insert as pg_insert

logger = logging.getLogger("lab_location_mapping")


class MoveStatus(str, Enum):
    REGISTERED = "REGISTERED"          # location confirmed at an authorized zone
    UNCHANGED = "UNCHANGED"            # idempotent replay; no state change
    QUARANTINED = "QUARANTINED"        # zone/hazard could not be authorized


class AssetLocationPayload(BaseModel):
    """Canonical, validated location record. Construction enforces the schema rules."""
    asset_id: str = Field(..., min_length=8, description="Unique institutional asset tag")
    campus_id: str = Field(..., min_length=2, description="Primary campus identifier")
    building_id: str = Field(..., min_length=2, description="Campus building code")
    room_code: str = Field(..., pattern=r"^[A-Z]{2}-\d{3}$", description="Standardized room identifier")
    custodian_email: EmailStr  # install pydantic[email]; validates RFC-5322 at construction
    hazard_class: Optional[str] = Field(None, description="OSHA/EPA hazard classification if applicable")

    def idempotency_key(self) -> str:
        """Deterministic fingerprint over the identity + location tuple."""
        raw = f"{self.asset_id}:{self.campus_id}:{self.building_id}:{self.room_code}"
        return hashlib.sha256(raw.encode("utf-8")).hexdigest()

The persistence model carries the system-owned fields and an append-only ledger entry per genuine move. The upsert is guarded by an idempotency_key conflict target and a room_code comparison, so a replay of an already-registered location is a no-op rather than a duplicate write.

class Base(DeclarativeBase):
    pass


class AssetLocation(Base):
    __tablename__ = "asset_locations"
    idempotency_key: Mapped[str] = mapped_column(String(64), primary_key=True)
    asset_id: Mapped[str] = mapped_column(String, index=True)
    campus_id: Mapped[str] = mapped_column(String)
    building_id: Mapped[str] = mapped_column(String)
    room_code: Mapped[str] = mapped_column(String)
    custodian_email: Mapped[str] = mapped_column(String)
    hazard_class: Mapped[Optional[str]] = mapped_column(String, nullable=True)
    updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True))


def register_location(session: Session, payload: AssetLocationPayload,
                      registry: "FacilityRegistry") -> MoveStatus:
    """
    Idempotently registers an asset's location after authorizing the zone.
    Returns the resolved MoveStatus; QUARANTINED records are never written to the master table.
    """
    # 1. Authorize the target zone against the facility hierarchy + hazard rules.
    if not registry.zone_is_authorized(payload.campus_id, payload.building_id, payload.room_code):
        registry.quarantine(payload, reason="zone_not_in_registry")
        logger.warning("Quarantined %s: unauthorized zone %s/%s/%s",
                       payload.asset_id, payload.campus_id, payload.building_id, payload.room_code)
        return MoveStatus.QUARANTINED
    if payload.hazard_class and not registry.zone_permits_hazard(payload.room_code, payload.hazard_class):
        registry.quarantine(payload, reason="hazard_class_not_permitted")
        return MoveStatus.QUARANTINED

    key = payload.idempotency_key()
    now = datetime.now(timezone.utc)

    # 2. Detect a genuine room change for the same asset (drives the ledger append).
    prior = session.scalars(
        select(AssetLocation).where(AssetLocation.asset_id == payload.asset_id)
    ).first()
    moved = prior is not None and prior.room_code != payload.room_code

    # 3. Idempotent upsert keyed on the SHA-256 fingerprint.
    stmt = pg_insert(AssetLocation).values(
        idempotency_key=key, asset_id=payload.asset_id, campus_id=payload.campus_id,
        building_id=payload.building_id, room_code=payload.room_code,
        custodian_email=str(payload.custodian_email), hazard_class=payload.hazard_class,
        updated_at=now,
    ).on_conflict_do_nothing(index_elements=["idempotency_key"])
    result = session.execute(stmt)

    if result.rowcount == 0:
        return MoveStatus.UNCHANGED  # exact assignment already on record — replay no-op

    # 4. Append one immutable, hash-chained ledger entry for the move.
    append_ledger_entry(session, payload, prior_room=(prior.room_code if prior else None),
                        digest=key, recorded_at=now)
    return MoveStatus.REGISTERED


def ingest_batch(session: Session, rows: list[dict], registry: "FacilityRegistry") -> dict:
    """Validate, register, and route a batch; malformed rows go to the dead-letter queue."""
    summary = {s: 0 for s in MoveStatus}
    for row in rows:
        try:
            payload = AssetLocationPayload(**row)
        except ValidationError as exc:
            registry.dead_letter(row, errors=exc.errors())  # quarantine malformed payloads
            continue
        summary[register_location(session, payload, registry)] += 1
    session.commit()
    logger.info("Location ingest summary: %s", summary)
    return summary

The ledger entry is the audit artifact: it records the prior room, the new room, the SHA-256 digest, and a UTC timestamp, and it is written to WORM-compliant storage so it cannot be rewritten after the fact. Because the digest is folded into each entry, two batches that assign the same asset to the same room produce identical keys and therefore exactly one ledger row.

Integration points #

Lab location mapping is a consumer and a producer. Upstream, it ingests device manifests, coordinates, and custody metadata from the procurement ERP, the laboratory information management system (LIMS), and RFID walkthrough hardware; downstream, it publishes a resolved spatial context that the rest of the equipment platform reads.

• RFID and barcode telemetry. Handheld and fixed readers emit raw tag payloads during walkthroughs; serial numbers and MAC addresses are normalized, deduplicated within a temporal window, and folded into AssetLocationPayload records before registration. The detailed offline-tolerant resolution path lives in Mapping Equipment Locations Across Multi-Building Campuses, which handles coordinate drift and network-partition fallback.
• Calibration routing. Validated room context feeds Calibration Due Date Routing so technician dispatch is scheduled against the asset’s confirmed building and floor, not a stale address.
• Usage logging. Shared-core utilization signals in Equipment Usage Logging Systems are attributed to the room of record, enabling per-space cost allocation.
• Inventory thresholds. Hazard-zone placement constrains how much regulated consumable a room may hold, which Inventory Threshold Tuning reads to enforce EPA accumulation limits per location.
• Building management systems. Bidirectional sync with HVAC and fume-hood airflow monitors flags any high-risk asset whose room ventilation falls below an OSHA/EPA threshold.

A resolved location export — the payload other systems consume — looks like this:

{
  "asset_id": "ENG-AX91-0042",
  "campus_id": "MAIN",
  "building_id": "ENG-01",
  "room_code": "AA-123",
  "hazard_class": "BSL-2",
  "custodian_email": "pi.lab@university.edu",
  "move_status": "REGISTERED",
  "idempotency_key": "9f2c...c4e1",
  "recorded_at": "2026-06-28T14:08:33Z"
}

Verification & audit #

A run is not “done” because the script exited zero; it is done when the ledger proves it. Three checks confirm correctness and reproduce the audit trail:

1. Count parity. The sum of REGISTERED, UNCHANGED, and QUARANTINED outcomes returned by ingest_batch must equal the inbound row count minus dead-lettered rows. A shortfall means a record was silently dropped — a defect, never an acceptable state.
2. Idempotent replay. Re-running the identical batch must return all UNCHANGED and append zero ledger rows. Run the batch twice in a staging transaction and assert the ledger row count is unchanged on the second pass.
3. Hash reproduction. For any asset, recompute sha256(asset_id:campus_id:building_id:room_code) and confirm it matches the idempotency_key stored on its latest ledger entry. This is the audit-trail verification an inspector can repeat independently, tying a physical location to a tamper-evident digest.

def verify_run(session: Session, asset_id: str, expected: AssetLocationPayload) -> bool:
    row = session.scalars(
        select(AssetLocation).where(AssetLocation.asset_id == asset_id)
    ).one()
    return row.idempotency_key == expected.idempotency_key()

Every quarantined asset must reconcile against an open dead-letter or quarantine record awaiting PI sign-off; an asset that is neither registered nor quarantined is an integrity violation that blocks closeout.

Failure modes & recovery #

1. Orphaned asset IDs. A procurement record imports an asset with no resolvable room. Root cause: the source export predates the room’s creation, or the building code was retired. Recovery: the record is quarantined, not defaulted; run the reconciliation routine against the dead-letter queue, apply the registry’s fuzzy-match suggestion for the building code, and require PI sign-off before the corrected payload is re-ingested. Because registration is idempotent, re-ingesting after correction is safe.
2. RFID collision / false positives. A high-density storage rack reports the same tag in two rooms within one second. Root cause: overlapping reader fields. Recovery: apply signal-strength filtering and a temporal deduplication window (e.g. 30-second aggregation) upstream so only the strongest read becomes a payload; duplicates that survive collapse to the same idempotency key and write once.
3. BMS telemetry drift. An HVAC sensor reports a legacy zone ID that no longer matches a room code. Root cause: stale firmware on the building management system. Recovery: maintain a versioned translation table from legacy BMS zone IDs to current room codes, refreshed by facilities on a fixed cadence; resolution reads the table before authorizing the zone, so an unmapped legacy ID quarantines rather than mis-assigns.
4. Idempotency-key reuse. A manually constructed payload reuses a key for a different location. Root cause: a client computing keys outside the model. Recovery: enforce server-side key generation for all production payloads, reject any inbound idempotency_key, and audit move-event logs for keys whose stored tuple does not reproduce the digest. When a downstream sink is unreachable for an extended window, defer to the Fallback Routing Protocols rather than bypassing quarantine.

Role boundaries. Compliance officers own the authorized-zone and hazard-class policy and approve registry changes; they do not modify mapping code. Python automation developers own idempotency, zone resolution, and the quarantine path; they do not alter regulatory windows. Laboratory managers own location accuracy at the source and correct quarantined payloads before resubmission. University administrators own retention and audit uptime.

Frequently asked questions #

Related #

• Parent guide: Equipment Calibration & Lab Inventory Tracking
• Mapping Equipment Locations Across Multi-Building Campuses — offline-tolerant resolution and coordinate-drift fallback
• Calibration Due Date Routing — technician dispatch scheduled against confirmed room context
• Equipment Usage Logging Systems — per-space utilization and cost allocation
• Inventory Threshold Tuning — hazard-zone accumulation limits per location
• Security Boundary Configuration — role-based access for restricted-asset reassignment