Blaze Inspect CLI

blaze inspect builds a read-only compiler-backed source/semantic index and emits bounded context packets for authoring agents. It parses, links, source-lowers, validates, and evaluates through the same compiler pipeline as check/build, but does not write generated world output, mutate source, fetch remote media, or generate assets.

Usage

blaze inspect <entry.blaze> [selectors] [--view mechanics|dialogue|tts|art] [--json] [--brief] [--budget <count>]

Selectors are explicit:

• --kind <kind> filters records by indexed kind such as room, choice, line, generated_tts, or media_companion.
• --character <id>, --room <id>, --conversation <id>, and --story-beat <id> resolve source/runtime records related by actual authored references.
• --module <name-or-path-suffix> filters to one Blaze module.
• --handle blaze://... selects an exact stable handle.
• --select <id-or-symbol-suffix> selects by stable ID, symbol name, identity label, or handle suffix.

Short --select values never silently choose the first match. Zero matches emit zero_match; multiple matches emit ambiguous with candidate handles, even when one candidate belongs to the requested view. Use an exact --handle or a typed selector such as --room, --character, --conversation, or --story-beat to select one phase record.

Packet Schema

JSON output is versioned as adventure-kit.blaze.inspect.v0.1 and includes:

• status: complete or partial. Partial packets include diagnostics and must not be treated as buildable runtime proof.
• selector and view: the requested phase and filters.
• revisions: SHA-256 source file fingerprints plus a deterministic dependency fingerprint.
• records: stable handles, canonical IDs, module/source spans, typed dependencies, consumers, owners, media slots, and view-specific fields.
• diagnostics: compiler diagnostics plus inspect diagnostics such as zero_match, ambiguous, unresolved_reference, missing_media, stale_media, unverified_media, budget_truncated, and budget_minimum_exceeded.
• omittedCounts, continuationHandles, and incomplete: budget disclosure for bounded packets.

Arrays are deterministic: module load/source order first, declaration order next, then stable handles for derived/runtime-only records.

Views

• mechanics: gates, blocked text, choices/actions/exits, effects, destinations, decisions, owners, consumers, and critical mechanics continuation handles. Choices, actions, and exits are retained even when the requested budget is smaller than the minimum safe mechanics context; only non-critical context is deferred.
• dialogue: lines, choices, nodes, speakers, menu text, captions, responses, line reuse, and nearby dialogue dependencies.
• tts: line IDs, source text fields, voice/audio references, generated TTS bindings, media companion freshness, and offline media brief fields.
• art: room description/narration, assets, scene visuals, visible presences, room media companion freshness, and offline media brief fields.

Inspection is static. It reports source/runtime references and does not prove runtime reachability; scenario behavior remains covered by reducer and parity tests.

Local Receipts

Representative commands used for this implementation:

npx tsx scripts/blaze.ts inspect examples/blaze/adirondack-mystery/main.blaze --view mechanics --room check_in_lobby --json
npx tsx scripts/blaze.ts inspect examples/blaze/adirondack-mystery/main.blaze --view dialogue --handle blaze://choice/cyberart.world.adirondack_mystery.dialogue.eliza_vale.check_in.choice.apology_with_whistle --json
npx tsx scripts/blaze.ts inspect examples/blaze/adirondack-mystery/main.blaze --view tts --handle blaze://generated_tts/voice.adventure_kit.dialogue.clara_mercer.checkin.apology_with_whistle.v1 --brief --json
npx tsx scripts/blaze.ts inspect examples/blaze/adirondack-mystery/main.blaze --view art --room check_in_lobby --brief --json

The Adirondack receipts report 15 source files in the dependency revision set and preserve the existing BLAZE_COMPANION warning plus unverified_media diagnostic for the legacy apologyWithWhistleAudio binding. A short --select apology_with_whistle reports ambiguous with generated-TTS, line, and choice candidate handles; the exact TTS handle resolves blaze://generated_tts/voice.adventure_kit.dialogue.clara_mercer.checkin.apology_with_whistle.v1, and the art room selector resolves check_in_lobby to blaze://room/cyberart.world.adirondack_mystery.room.check_in_lobby.