003-B11: add random usage package

Examples/Package.swift

@@ -0,0 +1,26 @@
+// swift-tools-version: 6.4
+
+import PackageDescription
+
+let package = Package(
+    name: "DioramaExamples",
+    platforms: [
+        .macOS(.v15),
+    ],
+    dependencies: [
+        .package(name: "Diorama", path: ".."),
+    ],
+    targets: [
+        .executableTarget(
+            name: "DioramaRandomUsage",
+            dependencies: [
+                .product(name: "DioramaCore", package: "Diorama"),
+                .product(name: "DioramaRandom", package: "Diorama"),
+            ],
+            swiftSettings: [
+                .defaultIsolation(nil),
+                .enableUpcomingFeature("NonisolatedNonsendingByDefault"),
+                .enableUpcomingFeature("InferIsolatedConformances"),
+            ]),
+    ],
+    swiftLanguageModes: [.v6])

Examples/Sources/DioramaRandomUsage/main.swift

@@ -0,0 +1,77 @@
+import DioramaCore
+import DioramaRandom
+
+@main
+struct DioramaRandomUsage {
+    static func main() async throws {
+        let randomKey = AttachmentKey(rawValue: "example-random")
+        let recordingSystem = try DioramaRandomSystem.instance(for: randomKey)
+        let recordingDefinition = try ScenarioDefinition(
+            id: ScenarioID(rawValue: "random-recording-example"),
+            defaultMode: .record,
+            attachments: [recordingSystem.attachment])
+
+        let recording = try await recordingDefinition.execute(with: recordingSystem) { generator in
+            var generator = generator
+            return Array(0..<5).map { _ in
+                generator.next()
+            }
+        }
+        let recordedValues = recording.body.get()
+        try requireCleanFinalization(recording.finalization)
+
+        let replaySystem = try DioramaRandomSystem.instance(for: randomKey)
+        let replayDefinition = try makeReplayDefinition(
+            randomKey: randomKey,
+            values: recordedValues)
+        let replay = try await replayDefinition.execute(with: replaySystem) { generator in
+            var generator = generator
+            return Array(0..<5).map { _ in
+                generator.next()
+            }
+        }
+        let replayedValues = replay.body.get()
+        try requireCleanFinalization(replay.finalization)
+
+        print("recorded: \(recordedValues)")
+        print("replayed: \(replayedValues)")
+    }
+
+    private static func makeReplayDefinition(
+        randomKey: AttachmentKey,
+        values: [UInt64]) throws -> ScenarioDefinition
+    {
+        let preparationDefinition = try ScenarioDefinition(
+            id: ScenarioID(rawValue: "random-replay-preparation-example"),
+            defaultMode: .replay)
+        let reporter = DiagnosticReporter(definition: preparationDefinition)
+        let preparation = ValuePreparation<UInt64>()
+        let preparedValues = try values.map { value in
+            try preparation.prepare(
+                capturing: { value },
+                purpose: .replay,
+                reporter: reporter)
+        }
+        let attachmentID = DioramaRandomSystem.attachmentID(for: randomKey)
+        let attachment = try ScenarioAttachment(id: attachmentID).adding(
+            SequentialTrack(
+                id: DioramaRandomSystem.trackID(for: randomKey),
+                values: preparedValues))
+        return try ScenarioDefinition(
+            id: ScenarioID(rawValue: "random-replay-example"),
+            defaultMode: .replay,
+            attachments: [attachment])
+    }
+
+    private static func requireCleanFinalization(
+        _ finalization: ScenarioFinalizationResult) throws
+    {
+        guard finalization.report.diagnostics.isEmpty else {
+            throw ExampleError.unexpectedDiagnostics
+        }
+    }
+}
+
+private enum ExampleError: Error {
+    case unexpectedDiagnostics
+}

README.md

@@ -40,6 +40,21 @@ Dependency adoption is governed by
 platform CI, strict concurrency, and coverage expectations are defined by
 [the quality gates and CI policy](docs/quality-gates-and-ci.md).
 
+## Usage example
+
+The repository includes a compiled, in-memory random record/replay example:
+
+```sh
+swift run --package-path Examples DioramaRandomUsage
+```
+
+It prints matching recorded and replayed values. The example uses only
+`DioramaCore` and `DioramaRandom` public APIs, always finalizes each scoped
+execution, and explicitly supplies prepared in-memory replay values.
+It lives in a separate examples package that depends on Diorama by a relative
+path, so the Diorama library package remains library-only. Persistence and
+record-to-replay transfer arrive in a later implementation phase.
+
 ## Development
 
 Development currently uses Xcode 27.0 beta 6 and its Swift 6.4 toolchain under

docs/README.md

@@ -99,6 +99,9 @@ lifecycle composition.
 - [First production coverage baseline](evidence/003-B10-first-production-coverage-baseline.md)
   records the owner-confirmed baseline-relative project tolerance, patch target,
   platform evidence, and retained upload requirements.
+- [In-memory random usage example](evidence/003-B11-random-usage-example.md)
+  records the public-only executable example, its explicit replay-baseline
+  boundary, and compilation evidence.
 
 ## Historical boundary
 

docs/evidence/003-B11-random-usage-example.md

@@ -0,0 +1,48 @@
+# 003-B11: In-memory random usage example
+
+- Date: 2026-09-16
+- Plan: [003-B11](../plans/003-clean-slate-implementation.md#003-b11--in-memory-random-usage-example)
+- Status: Complete locally; owner review is the next checkpoint.
+- Authority: [Decision 10](../design-decisions/10-lifecycle-and-ownership.md),
+  [Decision 13](../design-decisions/13-random-proving-system.md), the
+  [quality gates and CI policy](../quality-gates-and-ci.md), and the owner's
+  2026-09-16 scope confirmation.
+
+## Delivered example
+
+`DioramaRandomUsage` is an executable product in the separate examples package,
+with source at `Examples/Sources/DioramaRandomUsage/main.swift`. Its
+`Examples/Package.swift` depends on its parent Diorama package by an explicitly
+named relative path.
+Diorama's main `Package.swift` therefore retains only library products.
+
+The example imports only `DioramaCore` and `DioramaRandom`. It creates one
+named random system with its default live source, records five values through
+the variadic scoped-execution API, explicitly prepares those stable values into
+a fresh in-memory replay definition, then replays the same sequence. Both
+scoped executions finalize before the result is printed.
+
+The example does not represent a record-to-replay transfer API. Phase B has no
+persistence or public candidate export; Phase C owns that vertical path. The
+explicit preparation step is therefore both a valid in-memory replay input and
+a visible boundary rather than a persistence substitute.
+
+## Verification
+
+- `swift build --package-path Examples -c release -Xswiftc -warnings-as-errors`
+  passes.
+- `swift run --package-path Examples DioramaRandomUsage` prints identical
+  recorded and replayed sequences.
+- `scripts/test` compiles the examples package with warnings as errors after its
+  normal test and release-build gate, so the macOS and Linux coverage paths
+  build it through the same canonical entry point.
+- `scripts/coverage ios` remains the main library package's iOS 18 release
+  build, simulator test, and LCOV gate; it passes. The standalone command-line
+  example is not an iOS executable product.
+- The canonical Apple Container Linux reproduction copies `Examples` alongside
+  the root package inputs so its `scripts/test` stage builds the examples
+  package; the final Linux run passes all 85 tests, both release builds, and
+  LCOV export.
+
+No test-framework integration, persistence behavior, third-party dependency,
+or executable product in Diorama's main package is introduced.

docs/plans/003-clean-slate-implementation.md

@@ -17,7 +17,8 @@ owner accepted the review unit and authorized pull request creation on
 2026-09-16. 003-B09's implementation and local platform verification are
 complete and awaiting owner review. 003-B10's owner-confirmed coverage
 baseline and local platform verification are complete; owner review is the next
-checkpoint. Later units have not started.
+checkpoint. 003-B11's implementation and local platform verification are
+complete; owner review is the next checkpoint. Later units have not started.
 Plan approval establishes the implementation sequence and review boundaries; each selected unit still requires owner scope confirmation under protocol R before work begins.
 The gates below require their own recorded resolution where they affect a unit; plan approval alone does not approve dependencies or amend an accepted decision.
 
@@ -255,7 +256,7 @@ Use completed units to calibrate later recommendations with the owner while reta
 | Phase | Review units | Milestone                                                                    |
 | ----- | ------------ | ---------------------------------------------------------------------------- |
 | A     | 003-A01–003-A04      | Toolchain/approval evidence, minimal package, complete quality bootstrap.    |
-| B     | 003-B01–003-B10 plus 003-B07A | Public sequential core and an in-memory random system.                |
+| B     | 003-B01–003-B11 plus 003-B07A | Public sequential core, an in-memory random system, and a compiled usage example. |
 | C     | 003-C01–003-C07 plus 003-C04A | Persisted random and consumer-defined systems; first complete vertical path. |
 | D     | 003-D01–003-D05      | Isolated URLProtocol evidence and reviewed native capability boundaries.     |
 | E     | 003-E01–003-E08      | Shared real-time scheduler and reusable grouped behavior services.           |
@@ -545,6 +546,39 @@ Use `Spikes/<topic>/` and `docs/evidence/<topic>.md` for isolated experiments; n
 - Exclusions: Invented coverage targets, disabling failing tests/uploads, generated assertions to inflate coverage.
 - Checkpoint: R; stop for threshold confirmation before wider feature coverage.
 
+### 003-B11 — In-memory random usage example
+
+- Status: Complete locally; the owner confirmed the separate examples-package
+  scope and GPT-5.6 Terra at `medium` reasoning on 2026-09-16. Owner review is
+  the next checkpoint.
+- Evidence: [In-memory random usage example](../evidence/003-B11-random-usage-example.md).
+- Recommended model: GPT-5.6 Terra; reasoning: `medium`. A compiled public-only
+  example must make the current lifecycle and in-memory replay boundary clear
+  while retaining the library package's product boundary.
+- Prerequisites: 003-B05, 003-B07–003-B10; DD10, DD13, quality policy.
+- Scope: Add a separate `Examples` package with a relative path dependency on
+  Diorama. Its executable uses only `DioramaCore` and `DioramaRandom` public
+  products to show a scoped recording run and a separately authored in-memory
+  replay run. Compile it through the canonical macOS/Linux quality paths.
+- Expected files/modules: `Examples/Package.swift`,
+  `Examples/Sources/DioramaRandomUsage`, canonical build checks, concise README
+  guidance, and B11 evidence.
+- Public behavior: The example demonstrates named random setup, explicit
+  record/replay modes, typed scoped finalization, and the fact that replay
+  consumes supplied stable in-memory values. Diorama itself remains a
+  library-only package; the example does not claim record-to-replay transfer or
+  persistence before Phase C.
+- Tests/verification: V-code and V-doc; compile/run the examples package
+  through macOS/Linux canonical quality paths and verify that it imports only
+  the public core and random products. The main iOS package path remains a
+  library compile/test check.
+- Exclusions: An executable target or product in Diorama's main package,
+  dependencies beyond the relative Diorama package, persistence, test-framework
+  integration, sample-only runtime APIs, or a claim that this is final delivery
+  documentation.
+- Checkpoint: R; review the public API clarity and packaging boundary before
+  Phase C.
+
 ## Phase C — Optional persistence and the first complete vertical path
 
 ### 003-C01 — Persistent-system registration and version dispatch

docs/quality-gates-and-ci.md

@@ -74,7 +74,7 @@ container run --rm --arch x86_64 --cpus 2 --memory 4G \
   --mount type=bind,source="$PWD",target=/source,readonly \
   --workdir /work \
   swiftlang/swift@sha256:15ae709b1d8eb1f8691b300f5721499d007e944694f2c0e9929a55580c9bf1a5 \
-  bash -lc 'mkdir -p /work && cp -R /source/Package.swift /source/Sources /source/Tests /source/scripts /work/ && scripts/coverage swiftpm linux'
+  bash -lc 'mkdir -p /work && cp -R /source/Package.swift /source/Sources /source/Tests /source/scripts /source/Examples /work/ && scripts/coverage swiftpm linux'
 ```
 
 This command makes a local Linux result meaningful for the hosted job while

scripts/test

@@ -5,3 +5,4 @@ source "$(dirname "$0")/_common"
 cd "$repository_root"
 run swift test -Xswiftc -warnings-as-errors "$@"
 run swift build -c release -Xswiftc -warnings-as-errors
+run swift build --package-path Examples -c release -Xswiftc -warnings-as-errors