dry_run Mode

dry_run=True on story() puts the runtime into skeleton mode: stage bodies are executed, but any exception raised inside a stage is silently suppressed. The stage is reported as StageCompleted and the story completes with success=True. No FailureOccurred event is emitted.

What it does and does not do

• Stage bodies run — code up to the exception executes normally.
• Exceptions do not propagate out of the stage() block.
• No FailureOccurred is emitted; no LLM analysis is triggered.
• StageCompleted is emitted for every stage.
• The story ends with StoryCompleted(success=True).

When to use it

dry_run is designed for smoke-testing instrumentation without side effects:

• Verify that all expected stages are wired up before running the real pipeline.
• CI checks that confirm instrumentation coverage without a database, S3, or external API.
• Generating an HTML report or SQLite schema from a "dry" run.

Before and after comparison

from runtime_narrative import story, stage

# Without dry_run: ValueError propagates
try:
    with story("Import Pipeline"):
        with stage("Fetch from DB"):
            raise ValueError("no DB configured")
        with stage("Write to S3"):
            pass  # never reached
except ValueError:
    pass

# With dry_run=True: exceptions suppressed, all stages complete
with story("Import Pipeline", dry_run=True):
    with stage("Fetch from DB"):
        raise ValueError("no DB configured")  # suppressed
    with stage("Write to S3"):
        raise RuntimeError("no S3 in test")   # suppressed
# Story ends: SUCCESS — both stages show as completed

dry_run works identically for async with stage(...).

import asyncio
from runtime_narrative import story, stage

async def main():
    async with story("Pipeline", dry_run=True):
        async with stage("Fetch"):
            raise IOError("network unavailable")  # suppressed
        async with stage("Process"):
            raise TypeError("schema mismatch")    # suppressed

asyncio.run(main())