diff --git a/Examples/Package.swift b/Examples/Package.swift new file mode 100644 index 0000000..c0bfee5 --- /dev/null +++ b/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]) diff --git a/Examples/Sources/DioramaRandomUsage/main.swift b/Examples/Sources/DioramaRandomUsage/main.swift new file mode 100644 index 0000000..18dcc23 --- /dev/null +++ b/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() + 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 +} diff --git a/README.md b/README.md index 91dfef0..20fc2ef 100644 --- a/README.md +++ b/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 diff --git a/docs/README.md b/docs/README.md index f29a3f0..d2c949d 100644 --- a/docs/README.md +++ b/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 diff --git a/docs/evidence/003-B11-random-usage-example.md b/docs/evidence/003-B11-random-usage-example.md new file mode 100644 index 0000000..2cdca38 --- /dev/null +++ b/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. diff --git a/docs/plans/003-clean-slate-implementation.md b/docs/plans/003-clean-slate-implementation.md index d4b5bcb..01d1062 100644 --- a/docs/plans/003-clean-slate-implementation.md +++ b/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//` and `docs/evidence/.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 diff --git a/docs/quality-gates-and-ci.md b/docs/quality-gates-and-ci.md index abe97f9..1037c46 100644 --- a/docs/quality-gates-and-ci.md +++ b/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 diff --git a/scripts/test b/scripts/test index f9b660d..ab140cc 100755 --- a/scripts/test +++ b/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