MetaCrate/docs/live-grid-smoke.md

Live-grid program smoke gate

The final programs gate has two credential-free modes and one explicitly gated live mode. None of these tests silently skip. --audit-only fails unless the pinned source manifest maps to all nine original native Rust programs and every TestClient source command maps to the generated, implemented, and runtime registries. --fake executes every smoke stage against the deterministic backend and writes the same JSONL evidence shape as a live run.

cargo run -p libremetaverse-programs --bin live-grid-smoke -- --audit-only
cargo run -p libremetaverse-programs --bin live-grid-smoke -- \
  --fake --evidence /tmp/metacrate-smoke-fake.jsonl

Credential and side-effect boundary

Live mode is intended for a dedicated test account on OpenSim or another protocol-compatible grid. It loads these values from the process environment, falling back to the workspace .env file:

GRID_USER=First Last
GRID_PASSWORD=...
GRID_LOGIN_URL=https://compatible-grid.example/login

The 19 compatibility cases require an additional explicit opt-in and never infer consent merely because credentials exist:

RUN_LIVE_TESTS=1 cargo test --locked -p libremetaverse-compat-tests \
  --test inventory_live_semantics \
  --test appearance_live_semantics \
  --test world_live_semantics \
  --test network_semantics -- --nocapture

With the opt-in and all three .env values present, every live case is compiled without #[ignore]. The test run must report zero ignored cases. Test bodies do not print-and-return on missing OpenSim data: a missing inventory item, outfit link, appearance update, covenant response, current-region lookup, capability, or object packet is a real failure. Login uses the account's OpenSim last location instead of a hardcoded Second Life region.

GRID_LOGIN_URL is used directly as the LLSD login endpoint; the harness does not substitute a Second Life login host or path. The login request includes the OpenSim response options for avatar search, classified fee, currency label, destination guide, profile service, and search, in addition to the standard inventory and viewer options. Capability readiness is evaluated using OpenSim core surfaces (EventQueueGet, inventory descendants, simulator features, viewer assets, textures, and avatar search); Second Life voice capabilities are not required. Agent, object, inventory, and asset packet consumers are installed before authentication so the harness captures OpenSim's one-time login and scene bootstrap packets instead of treating a late subscription as an empty region. After the event queue is live, the harness repeats OpenSim's idempotent CompleteAgentMovement transition request reliably before waiting for the scene cache. Simulator identity is validated directly from the transport-decoded OpenSim region handshake, and the return teleport uses its numeric region handle instead of assuming the mutable Second Life-style simulator-name cache exists.

The complete command deliberately requires a separate flag and literal confirmation for each permitted side effect:

cargo run -p libremetaverse-programs --bin live-grid-smoke -- \
  --evidence /tmp/metacrate-smoke-live.jsonl \
  --allow-live-login --confirm-live-login LOGIN \
  --allow-public-chat --confirm-public-chat CHAT \
  --allow-agent-movement --confirm-agent-movement MOVE \
  --allow-reversible-inventory \
  --confirm-reversible-inventory CREATE-MOVE-TO-TRASH

This sends one self instant message and one clearly marked local-chat message, pulses forward movement for 250 milliseconds, teleports back to the starting simulator and position, and creates one uniquely named folder before moving it to Trash. The folder is not permanently deleted. The harness has no flags or code paths for currency spending, asset upload, permanent deletion, estate/parcel changes, or actions aimed at another user.

OpenSim does not necessarily route a self-addressed instant message back to the sending avatar. The IM gate therefore requires the encoded ImprovedInstantMessage datagram to cross the client's live UDP packet-sent boundary and records any inbound self echo as an additional metric. The local chat gate still requires an exact inbound simulator echo, so both operations are executed and neither is silently skipped.

Sanitized evidence

The newly created JSONL file contains exactly nine ordered records:

1. source/program/command completeness;
2. login;
3. event queue, capabilities, simulator, and object cache readiness;
4. self-IM and local-chat echo;
5. movement stop and return teleport;
6. folder creation and move to Trash;
7. object discovery and properties;
8. bounded texture download;
9. clean logout and zero active tasks.

The texture transfer is performed against the live grid and counted in the sanitized evidence, but the harness disables the library's on-disk asset cache before login. Asset bytes are held only in memory for validation and are not retained after the process exits.

Each record contains schema and sequence numbers, a Unix timestamp, the Rust package version, the source commit embedded at build time, a static status, and numeric metrics. It contains no account name, password, login/capability URL, session identifier, simulator name, object or asset UUID, or message text. The writer scans every serialized record for configured credential values and secret-bearing URL/token/password markers, flushes each stage, synchronizes at completion, and refuses to overwrite an existing evidence file.

If an operational stage fails, the harness records that failure and still attempts and records logout. A successful live gate requires all nine records to have status: "ok"; fake success is evidence for deterministic behavior, not evidence of a live login.