Agent-Native Virtual Lab Requirements

Status: Mandatory software/simulated Rehearsal gate implemented; physical substitution is outside current scope Updated: 2026-08-11 Primary owner: RIGOR platform / ASCEND Scope: Rehearsal, surrogate execution, plan promotion, scene projection, evidence authority, visualization, and physical substitution

This is the current human-readable PRD for the virtual laboratory. Exact fields and enums come from the linked JSON Schemas, typed contracts, OpenAPI, code, and tests. The earlier detailed implementation snapshot is retained in the repository at docs/archive/prds/agent-native-virtual-lab-prd-2026-08-03-detailed.md for historical traceability; Completed Designs explains why that mixed-language source is not part of the public documentation build.

1. Product Decision

RIGOR provides two isolated environments that share laboratory semantics but have different authority:

1. Rehearsal Lab — an Agent may fork, reset, accelerate, compare, and inject failures while testing a plan.
2. Execution Lab — a selected plan runs formally under device-like locks, timeout, cancellation, safe-stop, verification, and evidence rules.

Today, SimFleet supplies constrained surrogate devices in the Execution Lab. Future qualified physical controllers may replace them one at a time without changing Agent intent, reviewed Procedures, Policy, PlanRevision, or RunSpec semantics; that physical substitution work is outside the current scope.

Rehearsal is mandatory whenever formal experiment delivery would issue a side-effecting LabBridge capability. It is a first-class subsystem coordinated by ASCEND and executed/enforced by LabBridge, not a Composer module, a user lifecycle step, or a seventh domain module. Composer may supply the immutable package that is compiled into rehearsal intents, but it does not own the gate.

The user experience is:

A researcher can see the Agent try workflows, understand failures, and revise a plan. Only the selected PlanRevision is revalidated against current execution state and run formally. Verified results return as evidence for the next scientific iteration.

2. Why Separate Rehearsal from Execution

RIGOR already has simulated devices, semantic Capabilities, Operations, artifacts, evidence, plans, policy, Attention, workflows, packages, spatial resources, and a researcher workspace. Without an explicit environment model, however, several facts become ambiguous:

• whether a simulated device is a rewindable rehearsal copy or the durable formal execution substitute;
• whether an output is predicted, simulated evidence, physical evidence, human evidence, algorithm evidence, or unverified;
• whether a branch can change execution state;
• what is allowed to move from a branch into formal execution;
• whether a visualization is showing current state or a historical prediction;
• what a physical controller must prove before replacing a surrogate.

Three-dimensional animation does not solve these authority problems. The environment, isolation, promotion, provenance, and read-only scene contracts must exist first.

3. Goals

• Distinguish Rehearsal, Surrogate Execution, and Physical Execution.
• Run multiple isolated branches from one immutable ExecutionSnapshot.
• Let an Agent create, compare, and revise branches within declared budgets.
• Promote only a PlanRevision and explicit resource-binding proposal.
• Revalidate schema, Policy, capabilities, resources, and current state before creating a RunSpec.
• Prevent rehearsal from overwriting execution state, Operations, evidence, or audit.
• Keep predicted, simulated, physical, human, algorithm, and unverified provenance explicit.
• Let Web 2D and Web 3D consume the same read-only scene and event stream.
• Preserve the normal user journey: set a goal, observe progress, handle Needs you, Pause, Stop, or Take over.
• Prove future physical substitution without introducing protocol details into Agent tools or Procedures.

4. Non-Goals

• Rehearsal is not a general physics engine, molecular simulator, or chemistry prediction platform.
• It does not simulate human-like button pressing or vial handling when the real capability would use a fixture, autosampler, reviewed robot mode, or Human Task.
• Predicted output cannot become PACE scientific evidence.
• A branch cannot call a Surrogate or Physical Execution Device directly.
• Copying rehearsal state cannot complete formal execution.
• Agent count is not an acceptance metric.
• Users are not required to click Compose, Start, Promote, Refresh, or Replay in sequence.
• A renderer never owns Device, Policy, Plan, Operation, or Evidence authority.
• Unreal Engine is optional; browser-native 3D is the primary immersive client.

5. Terms

Term	Meaning
DeviceModel	Versioned device capabilities, constraints, state transitions, visual metadata, and optional bounded simulation behavior
Environment	Isolated device instances, resources, spatial state, and time semantics
Rehearsal Lab	environment_role=rehearsal; rewindable, simulated, and prediction-only
Execution Lab	environment_role=execution; formal and durable
Surrogate Device	A simulated execution device with formal Operation and evidence behavior
Physical Device	A real instrument or robot behind a qualified controller
ExecutionSnapshot	Immutable, checksummed view of execution state at one time
RehearsalSession	Branch collection for one Goal/Plan and one snapshot
RehearsalBranch	One isolated plan and environment branch
RehearsalFinding	Predicted feasibility, conflict, duration, failure, or candidate outcome—not evidence
PlanPromotion	Immutable revalidation of a selected PlanRevision for execution
SceneProjection	Read-only scene snapshot and ordered events for any renderer

6. Environment and Evidence Model

Environment role and reality are independent dimensions:

Environment	Reality	Meaning
rehearsal	simulated	Branchable Agent rehearsal
execution	simulated	Formal SimFleet surrogate execution
execution	physical	Formal physical instrument or robot execution
execution	mixed	Formal environment containing separately identified surrogate and physical devices

rehearsal + physical and rehearsal + mixed are invalid. Every individual Capability, Operation, artifact, and result retains its own provenance even in a mixed execution environment. Unclassified legacy controllers remain unknown + unverified; they do not gain physical provenance by default.

Authority class	What it may represent
predicted	Rehearsal findings, conflicts, duration estimates, and candidate outcomes
simulated_evidence	Verified surrogate Operations and artifacts
physical_evidence	Observed results from a qualified physical controller
human_evidence	Schema-valid Human Task submissions with actor and required artifacts
algorithm_evidence	Versioned algorithm output with input provenance and result schema
unverified	An output whose source or verification is incomplete

Predicted output cannot satisfy an evidence requirement. Simulated evidence cannot satisfy a physical-measurement requirement. Unverified output cannot be silently upgraded.

7. Core Invariants

7.1 State isolation

• An ExecutionSnapshot is read-only.
• Every branch has an independent state store and deterministic seed.
• Calls, reset, fault injection, and time advancement in one branch cannot change another branch or the Execution Lab.
• Selected-branch summaries, findings, and plan lineage remain durable after large temporary branch state is reclaimed.

7.2 Promotion copies plans, not world state

A PlanPromotion may reference the selected branch, PlanRevision, source snapshot, findings, target environment, binding proposal, Policy decision, and validation report. It cannot copy device state, sample custody, predicted artifacts, terminal results, or scientific measurements into execution.

7.3 Execution uses current state

Before producing a RunSpec, promotion rechecks snapshot freshness, device availability, capability/schema compatibility, unique resource bindings, spatial and custody constraints, Policy, risk, timeout, cancellation, safe-stop, Human Tasks, and expected evidence.

A successful rehearsal is neither Policy approval nor proof that the current Execution Lab can still run the plan.

7.4 Formal execution fails closed

• Every formal experimental capability input is covered by the selected, completed branch for one immutable PlanRevision and ExecutionSnapshot.
• ASCEND validates lineage before preparation and start; PACE rejects an experiment RunSpec without it; LabFlow transports it in a signed workflow context; LabBridge validates it again at the capability boundary.
• A changed registry or capability catalog makes the lineage stale and requires bounded automatic re-snapshot/rehearsal rather than an execution bypass.
• Read-only discovery is outside the write gate. Cancellation, stop, emergency, and safe-stop bypass the Rehearsal requirement so safety cannot be blocked.

7.5 Execution remains durable

Policy
  -> immutable RunSpec
  -> PACE and LabFlow
  -> LabBridge Capability call
  -> Operation
  -> verification
  -> Evidence

Browser refresh, scene reconnection, playback, or branch reset cannot repeat an execution action.

8. User Journey and Human Decisions

Goal + Constraints + Policy
  -> automatic ExecutionSnapshot
  -> bounded Agent rehearsal branches
  -> findings and PlanRevision
  -> ALLOW | ASK | DENY
  -> current-state revalidation and immutable RunSpec
  -> formal Execution Lab
  -> committed evidence and PRISM analysis
  -> ASCEND continues, asks, or stops

Normal phases remain Working, Needs you, Paused, Completed, and Problem. Branching, replaying, rebinding, snapshotting, and promotion are internal activities—not required lifecycle buttons.

One typed Attention is appropriate when branches have a material scientific tradeoff, promotion expands scope/risk/cost, a high-risk binding is selected, a real Human Task is required, resources or space are missing, the snapshot is too stale for bounded recovery, or all branches fail.

Attention shows the recommendation, alternatives, Plan diff, findings, current execution state, selected resources, resulting RunSpec impact, and expected evidence.

9. Agent and Domain Boundaries

The Rehearsal Agent receives the goal, constraints, Policy, bounded snapshot, semantic capabilities, spatial/resources view, current PlanRevision, completed findings, and budgets. It does not receive raw protocols, renderer objects, other branches' writable state, execution credentials, or hidden chain-of-thought.

Tools use typed input/results, profile allowlists, budgets, traces, and parent/child AgentRun lineage. No tool parameter may let a branch declare itself “validated.”

Owner	Responsibility
ASCEND	Goal, Policy, PlanRevision, session selection, Attention, promotion, user projection
Composer	Compile the selected plan and current bindings into an immutable package/RunSpec; does not own the Rehearsal gate
PACE	Formal run, scientific iteration, delivery, evidence archive, and required Rehearsal lineage check
LabFlow	Deterministic Procedure scheduling, signed lineage transport, locks, waits, cancellation, and safe-stop
LabBridge	DeviceModels, environments, snapshots, mandatory capability-boundary Rehearsal validation, capabilities, Operations, artifacts, and scene device facts
SimFleet	Bounded behavior reused by isolated rehearsal and formal surrogate instances
PRISM	Analysis of committed execution evidence, not predicted findings
Renderer	Read-only SceneProjection consumer with no domain authority

The four normal deployment units remain unchanged. A future high-load simulation worker requires a deployment ADR rather than becoming an accidental fifth unit.

10. Current Contracts

Machine-readable contracts are authoritative:

• contracts/environment-v1.schema.json
• contracts/execution-snapshot-v1.schema.json
• contracts/rehearsal-session-v1.schema.json
• contracts/rehearsal-attestation-v1.schema.json
• contracts/rehearsal-branch-v1.schema.json
• contracts/rehearsal-finding-v1.schema.json
• contracts/rehearsal-branch-comparison-v1.schema.json
• contracts/rehearsal-plan-resolution-v1.schema.json
• contracts/plan-promotion-v1.schema.json
• contracts/direct-plan-run-spec-v1.schema.json
• contracts/scene-projection-v1.schema.json
• contracts/scene-event-v1.schema.json
• contracts/spatial-map-v1.schema.json
• contracts/navigation-path-v1.schema.json
• contracts/capability-spec-v2.schema.json

Important rules:

• ExecutionSnapshots freeze registry, capability, DeviceModel, state, spatial, custody, and active-operation references behind a checksum.
• A historical rehearsal uses its frozen spatial map; it does not drift when the current map changes.
• A stale promotion must be rejected or trigger bounded re-snapshot/rehearsal.
• Capability discovery is filtered to the task environment and does not expose same-named writable rehearsal and execution instances together.
• Scene entities use stable business identifiers, never renderer object ids.
• Only devices explicitly requiring a spatial placement become missing-layout issues; non-spatial/human-assisted devices remain visible without invented coordinates.
• ASCEND's typed sdlx.lab-showcase/v1 read projection selects the newest eligible execution or rehearsal by recorded time and falls back to the live layout. A formal execution without recorded motion uses current layout context and never receives a fabricated replay path.

11. Scene and Renderer Requirements

The scene is reconstructed from a snapshot and ordered events. Raw events remain append-only audit. Renderer-neutral action segments combine one intent's started/terminal events for human playback without turning branch lifecycle, finding, promotion, or Attention into fake device animation.

A renderer may switch or compare branches, pause local playback, seek by action, inspect bounded summaries, show Agent-to-device flow, and link to Attention, evidence, or trace. It may not change authoritative time, submit a device command, treat local playback pause as system Pause, create business records, or infer success from animation.

Device appearance belongs to versioned DeviceModel YAML. The frontend interprets generic geometry or asset fields and uses one fallback; it does not branch on device id, friendly name, template, or category.

ASCEND current-lab observation, LabBridge layout configuration, and Experiment replay use the same renderer and sdlx.spatial-map/v1, but each receives only its own context-pure scene. 2D Y and 3D horizontal Z project one coordinate system.

11.1 Motion and Showcase Mode

Mobile device projection includes a stable device id plus current pose, target pose, motion state, progress, and route/path when the controller can supply them. SimFleet publishes the same shape while a navigation Operation runs. A renderer may interpolate between received poses for continuity; arrived still comes only from controller or replay state.

Rehearsal global navigation uses the frozen sdlx.spatial-map/v1, the mobile unit's DeviceModel collision footprint, configured clearance, fixed equipment, obstacles, and walls. It computes one deterministic collision-free path before the predicted action starts and stores that bounded path as sdlx.navigation-path/v1. The record identifies the map checksum, planner version, footprint, clearance, path checksum, and collision scope. Rehearsal treats every other mobile unit's frozen snapshot pose as a collision body, so the recorded animation cannot pass through another unit. It does not pretend that this solves live traffic: dynamic avoidance and reservations remain controller-owned and must be qualified during physical substitution. If static geometry has a route but parked mobile units close it, preflight reports typed dynamic_traffic_blocked guidance rather than mislabeling the walls or work point.

Plans use navigate_to_device for equipment service rather than embedding a derived station, approach, route, coordinate, or mobile id. Before a branch is created, LabBridge resolves every semantic target against the frozen snapshot, checks every role-compatible mobile capability and sequential path candidate, and returns one sdlx.rehearsal-plan-resolution/v1 containing every blocker and a suggested map action. Ready results become a new immutable materialized PlanRevision; branches and later attestations refer only to that exact revision. A carrier delivered to fixed equipment becomes custody of that equipment work area. A later mobile may collect it from a pickup-capable work position and continue processing; no robot-to-robot handoff is invented. The materialized plan records deterministic collect/deliver custody transitions.

When an intent selects a fixed device that requires robot service, LabBridge resolves its revision-bound role-compatible Access Points and selects a feasible mobile unit by collision-checked collect-and-deliver route cost. A small mobile-change penalty prevents churn without pinning the carrier when another mobile has a materially better route. The user never authors a route or maintains the derived device-access station. Before activation, deterministic qualification verifies fixed placements, revision-only mobile validation starts, local work-position clearance, and start-to-target connectivity. Validation starts never become live placements. At rehearsal/runtime, directional A* computes a collision-free path from the controller-frozen authoritative start to that private target. A bounded comfort cost prefers wider corridors and a turn cost avoids grid zig-zags; line-of-sight simplification and rounded corners are accepted only after collision checks. These are deterministic preferences, not extra feasibility gates, so a safe narrow passage remains usable. Browser code cannot repair the path or infer arrival, and the recorded goal preserves the user-defined final orientation.

Replay never plans again. Both 2D and 3D interpolate the same recorded waypoints. A legacy action without a path, or an earlier static_map path that excluded frozen mobile obstacles, remains stationary and is labelled as unavailable instead of receiving a fabricated or visibly unsafe route. A blocked start, blocked Access Point, or disconnected layout produces a typed Rehearsal finding and no navigation animation.

ASCEND Showcase Mode is a presentation policy over a selected scene. It may automatically play and loop a replay, guide the camera toward the active device, and render an Agent activity core, capability pulse, workflow handoff, and evidence-return animation. These effects consume typed summaries and events and have no device, Plan, Operation, Policy, finding, or Evidence authority.

The UI always preserves the source boundary:

• rehearsal playback is predicted;
• formal surrogate execution is simulated_evidence only after its evidence gate succeeds;
• physical claims require qualified controller observations;
• local animation, camera motion, and playback timing are visual state only.

11.2 Rehearsal-only Demonstrations

A maintained rehearsal_only preset may exercise a larger, curated sequence of semantic devices without constructing a Composer package or starting formal execution and analysis. ASCEND still owns the Coordination, immutable PlanRevision, policy snapshot, decision record, and scene lineage; LabBridge still owns the snapshot, branch, DeviceModels, predicted state transitions, and path calculation.

This path is deliberately narrow:

• only versioned repository presets may provide the ordered capability intents;
• intent count, schema, device, capability, input, branch, and time budgets are validated before the branch runs;
• auto_promote is always false;
• Composer, PACE, LabFlow, and PRISM are recorded as skipped, not completed;
• completion means the predicted rehearsal and replay were produced; it does not mean the scientific goal was executed or analyzed;
• no Operation, execution artifact, or scientific evidence is created from the predicted branch.

12. Safety and Provenance

• Rehearsal workers have no Execution Lab write credentials.
• Environment tokens bind both environment id and role.
• Rehearsal tokens cannot call execution devices.
• Promotion carries no device write credential; execution obtains bounded authority after validation.
• APIs, traces, UI, and exports preserve provenance.
• Transport acknowledgement is not verified effect.
• Surrogate execution retains Operation, timeout, cancellation, safe-stop, and verification contracts.
• Physical interlocks, watchdogs, and emergency protection are never replaced by rehearsal.
• Human Tasks require schema and evidence validation.
• Take over continues through governed ASCEND/LabBridge capabilities.

13. Primary API Surface

Control exposes session, branch, promotion, scene, and event reads plus governed cancel. Routine create/run/select/promote/rebind work advances automatically. Engineering APIs may expose explicit branch controls for testing, but they are not the normal product flow.

LabBridge owns execution snapshot and isolated rehearsal environment create, fork, reset, close, capability, and state APIs. Cross-deployment calls use versioned typed clients, timeout, idempotency, and service authentication.

14. Acceptance Criteria

Isolation and evidence

• Every Agent-visible device exposes environment, reality, and authority.
• Checksummed snapshots and model/catalog revisions reproduce branch input.
• Branches remain isolated across calls, faults, reset, and process restart.
• Rehearsal credentials deterministically fail against execution devices.
• Findings are rejected by PACE/PRISM evidence boundaries.

Rehearsal and promotion

• The Agent can compare at least two bounded branches and create a PlanRevision.
• ALLOW advances automatically; ASK creates one complete typed Attention; DENY cannot create execution.
• Promotion copies only plan and binding lineage.
• Changed execution state or catalog revision makes an old promotion stale.
• Successful promotion creates a new immutable RunSpec with full lineage.

Formal execution

• Missing, stale, mismatched, or input-incomplete Rehearsal lineage is rejected before an experimental LabBridge Operation is created.
• PACE start and direct/promoted execution cannot bypass the same gate.
• The automatic gate remains Working; no normal-user Rehearse or Promote lifecycle button is required.
• Surrogate execution uses existing Policy, lock, Operation, timeout, cancellation, safe-stop, verification, and evidence paths.
• All surrogate results remain simulated_evidence.
• Rehearsal success cannot overwrite execution failure.
• Committed execution results may feed the next snapshot and decision.

Human-observable 2D/3D

• Both renderers reconstruct the same selected branch, PlanRevision, Operation state, provenance, and final scene from the same inputs.
• Refresh, reconnect, failed assets, or WebGL failure do not change lifecycle state; 2D remains available.
• Stable business ids and DeviceModel visuals replace renderer-specific domain mappings.
• Animation cannot create findings, Operations, evidence, or success.
• Historical playback retains its map; unplaced devices remain explicit.
• Take over remains a governed capability path.
• A running mobile Operation exposes a target and monotonic display progress; 2D and 3D consume the same coordinates, and 3D motion is visually continuous.
• A selected robot-served device resolves its revision-bound Access Point; blocked starts, work positions, or connectivity prevent layout activation.
• Smoothed replay keeps collision clearance, follows path-tangent heading, and contains no browser-generated shortcuts.
• Showcase Mode can guide the camera and visualize bounded Agent activity, device handoff, and evidence return without changing authoritative state.
• A curated rehearsal-only showcase can involve at least six devices while proving that Composer, PACE, LabFlow, and PRISM were not called.

Future physical substitution

• A matching physical controller can replace a surrogate without protocol changes in prompts or Procedures.
• Physical binding repeats Policy, precondition, risk, safe-stop, and evidence qualification.
• Simulated evidence is never relabeled as physical evidence.

15. Delivery Status

Phase	Outcome	Status
Phase 0	Environment identity and evidence authority	Implemented
Phase 1	Isolated rehearsal, branching, findings, PlanRevision, promotion, and surrogate execution	Implemented
Phase 2	Durable SceneProjection, shared map, Web 2D, comparison, Attention, and replay	Implemented
Phase 3	Browser-native Web 3D, DeviceModel-owned visuals, 2D fallback, and renderer parity	Implemented
Phase 3 showcase	Semantic equipment navigation, clearance/turn-weighted and smoothed recorded paths; typed mobile motion; pre-branch compatibility; direct multi-device rehearsal; guided camera; and Agent/work/evidence presentation effects	Implemented
Phase 3.5	Optional Unreal showcase client	Optional; not required
Mandatory execution gate	Exact-intent lineage from ASCEND through PACE/LabFlow to LabBridge, with stale-state rejection and safety exceptions	Implemented
Phase 4	Qualified physical substitution, calibrated models, dynamic traffic, and predicted/surrogate/physical comparison	Outside current scope

Phase 0-3 software completion does not certify a production deployment or any physical device. If a later accepted PRD reopens Phase 4, it must name at least one real path and require Capability, Operation, observed verification, safe-stop, evidence, analysis, and restart-recovery proof.

16. Current Implementation Sources

• LabBridge: core/environments.py, virtual_lab/, simfleet/device_models/, config/maps/, and environment/spatial tests.
• ASCEND: virtual_lab.py, scene contracts/projection, PlanRevision and promotion services, workspace APIs, and primary Web lab/replay features.
• PACE: result-contract provenance and predicted-output rejection.
• Shared rendering: packages/ui-lab-map/.
• Qualification: virtual-lab contract, architecture, browser, and generated client tests.

Release claims must always say whether evidence is predicted, simulated, physical, human, algorithmic, or unverified.