Trajectory logging (CLI / RuntimeEngine)

Optional structured step traces for ainl run: each executed step appends one JSON line to <source-stem>.trajectory.jsonl beside the .ainl file (same directory as the source path passed to the CLI).

Enable

• Flag: ainl run path/to/script.ainl --log-trajectory
• Environment: AINL_LOG_TRAJECTORY=1 (or true / yes / on, case-insensitive after trim)

Works with --json and other normal ainl run flags.

Optional sandbox metadata

When the optional sandbox shim is connected, trajectory rows can include additive fields:

• avm_event_hash - hash-chained event digest for AVM-style integrity linking.
• sandbox_session_id - per-session runtime identifier.
• sandbox_provider - detected runtime class (avm or general).
• isolation_hash - rolling sandbox-side chain state when available.

If no sandbox runtime is detected, these fields are omitted and behavior is unchanged.

Examples

ainl run examples/hello.ainl --log-trajectory --json
# creates examples/hello.trajectory.jsonl

Hyperspace emitted agents: python3 scripts/validate_ainl.py … --emit hyperspace -o agent.py embeds IR and uses RuntimeEngine; trajectory files are written relative to the process current working directory, using the stem of the original .ainl source. Set AINL_LOG_TRAJECTORY when running the emitted script if you do not pass CLI flags through a wrapper.

Relation to other logging

• Runner HTTP audit (ainl.runner logger, /run on the runner service) is separate; see AUDIT_LOGGING.md.
• Runtime / compiler contract: optional trace is an implementation surface on RuntimeEngine; it does not change graph semantics. See RUNTIME_COMPILER_CONTRACT.md.

See also

• modules/common: guard.ainl, session_budget.ainl, reflect.ainl — optional gates that pair well with traced runs (modules/common/README.md).
• Hyperspace emitter: emitters/README.md — --emit hyperspace, examples/hyperspace_demo.ainl, root README.md (Emitters / happy path).