deterministic-scenario-engine 3.0.1__tar.gz → 3.1.0__tar.gz

{deterministic_scenario_engine-3.0.1/src/deterministic_scenario_engine.egg-info → deterministic_scenario_engine-3.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deterministic-scenario-engine
-Version: 3.0.1
+Version: 3.1.0
 Summary: Reproducible, state-consistent business scenarios with deterministic ground truth
 License-Expression: Apache-2.0
 Project-URL: Homepage, https://github.com/imshahinul/deterministic-scenario-engine
@@ -63,6 +63,8 @@ make expected behavior explicit.
 - DSL 1 parsing, compilation, and deterministic execution
 - DSL 2 logical-actor execution with an explicit independent schedule seed
 - canonical Result/2, Manifest/2, and Schedule/1 evidence with exact replay
+- finite, ordered serial Engine 2 suites with strict offline aggregate verification
+- finite explicit schedule-seed sweeps over the Engine 2 suite runner
 - actor-aware inspect/explain and deterministic offline trace viewing
 - addressed randomness and logical IDs that do not depend on a shared stream
 - current state plus append-only committed history and artifacts
@@ -115,10 +117,11 @@ and observe the module location it actually imports:
 python3 -c 'from importlib.metadata import version; from pathlib import Path; import scenario_engine; print("DSE distribution:", version("deterministic-scenario-engine")); print("Imported module:", Path(scenario_engine.__file__).resolve())'
 ```
 
-For this release the distribution is `3.0.1`; a source-development editable
-install resolves the module under its `src/scenario_engine` directory. The DSE
-distribution version is distinct from Engine 1 (`1.0.0`) and Engine 2 (`2.0.0`)
-compatibility versions.
+The source distribution version is `3.1.0`. PyPI and GitHub Releases are
+authoritative for actual publication and release history. A source-development
+editable install resolves the module under its `src/scenario_engine` directory.
+The DSE distribution version is distinct from Engine 1 (`1.0.0`) and Engine 2
+(`2.0.0`) compatibility versions.
 
 Install only the named optional integrations you need:
 
@@ -181,15 +184,22 @@ self-contained offline HTML file from supported result/evidence.
 - [2.2.0 release notes](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/release-notes-2.2.0.md)
 - [3.0.0 release notes](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/release-notes-3.0.0.md)
 - [3.0.1 release notes](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/release-notes-3.0.1.md)
+- [3.1.0 release notes](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/release-notes-3.1.0.md)
+- [Engine 2 serial suites](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/engine2-suite.md)
+- [Engine 2 schedule-seed exploration](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/engine2-exploration.md)
 - [Phase 2 public contract, CLI, and hard bounds](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/phase2-public-contract.md)
 - [Phase 3 public contract and evidence interchange](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/phase3-public-contract.md)
 
 ## Status
 
 Distribution release identity and deterministic engine compatibility are
-separate contracts. This source tree reports published distribution version
-3.0.1 and public Engine 2.0.0. Engine 1 manifests remain exactly 1.0.0
-with integer DSL 1; Engine 2 manifests use 2.0.0 with integer DSL 2. Supported
-Python versions are 3.11–3.14. Suite Run/2 is reader/schema support only; Engine
-2 suite orchestration, cross-major promotion, remote URI input, and implicit
-schedule-seed derivation are unsupported. The project is Apache-2.0 licensed.
+separate contracts. This source tree reports distribution version 3.1.0 and
+public Engine 2.0.0. PyPI and GitHub Releases are authoritative for actual
+publication and release history. Engine 1 manifests remain exactly 1.0.0 with
+integer DSL 1; Engine 2 manifests use 2.0.0 with integer DSL 2. Supported Python
+versions are 3.11–3.14. Module-qualified Engine 2 APIs provide ordered serial
+suite execution, strict aggregate verification, exact native replay, and finite
+explicit schedule-seed sweeps. These additive contracts do not produce or
+reinterpret historical Suite Run/2. Exhaustive exploration, distributed or
+parallel execution, cross-major promotion, remote URI input, and implicit
+schedule-seed derivation remain unsupported. The project is Apache-2.0 licensed.

{deterministic_scenario_engine-3.0.1 → deterministic_scenario_engine-3.1.0}/README.md

@@ -26,6 +26,8 @@ make expected behavior explicit.
 - DSL 1 parsing, compilation, and deterministic execution
 - DSL 2 logical-actor execution with an explicit independent schedule seed
 - canonical Result/2, Manifest/2, and Schedule/1 evidence with exact replay
+- finite, ordered serial Engine 2 suites with strict offline aggregate verification
+- finite explicit schedule-seed sweeps over the Engine 2 suite runner
 - actor-aware inspect/explain and deterministic offline trace viewing
 - addressed randomness and logical IDs that do not depend on a shared stream
 - current state plus append-only committed history and artifacts
@@ -78,10 +80,11 @@ and observe the module location it actually imports:
 python3 -c 'from importlib.metadata import version; from pathlib import Path; import scenario_engine; print("DSE distribution:", version("deterministic-scenario-engine")); print("Imported module:", Path(scenario_engine.__file__).resolve())'
 ```
 
-For this release the distribution is `3.0.1`; a source-development editable
-install resolves the module under its `src/scenario_engine` directory. The DSE
-distribution version is distinct from Engine 1 (`1.0.0`) and Engine 2 (`2.0.0`)
-compatibility versions.
+The source distribution version is `3.1.0`. PyPI and GitHub Releases are
+authoritative for actual publication and release history. A source-development
+editable install resolves the module under its `src/scenario_engine` directory.
+The DSE distribution version is distinct from Engine 1 (`1.0.0`) and Engine 2
+(`2.0.0`) compatibility versions.
 
 Install only the named optional integrations you need:
 
@@ -144,15 +147,22 @@ self-contained offline HTML file from supported result/evidence.
 - [2.2.0 release notes](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/release-notes-2.2.0.md)
 - [3.0.0 release notes](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/release-notes-3.0.0.md)
 - [3.0.1 release notes](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/release-notes-3.0.1.md)
+- [3.1.0 release notes](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/release-notes-3.1.0.md)
+- [Engine 2 serial suites](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/engine2-suite.md)
+- [Engine 2 schedule-seed exploration](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/engine2-exploration.md)
 - [Phase 2 public contract, CLI, and hard bounds](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/phase2-public-contract.md)
 - [Phase 3 public contract and evidence interchange](https://github.com/imshahinul/deterministic-scenario-engine/blob/main/docs/phase3-public-contract.md)
 
 ## Status
 
 Distribution release identity and deterministic engine compatibility are
-separate contracts. This source tree reports published distribution version
-3.0.1 and public Engine 2.0.0. Engine 1 manifests remain exactly 1.0.0
-with integer DSL 1; Engine 2 manifests use 2.0.0 with integer DSL 2. Supported
-Python versions are 3.11–3.14. Suite Run/2 is reader/schema support only; Engine
-2 suite orchestration, cross-major promotion, remote URI input, and implicit
-schedule-seed derivation are unsupported. The project is Apache-2.0 licensed.
+separate contracts. This source tree reports distribution version 3.1.0 and
+public Engine 2.0.0. PyPI and GitHub Releases are authoritative for actual
+publication and release history. Engine 1 manifests remain exactly 1.0.0 with
+integer DSL 1; Engine 2 manifests use 2.0.0 with integer DSL 2. Supported Python
+versions are 3.11–3.14. Module-qualified Engine 2 APIs provide ordered serial
+suite execution, strict aggregate verification, exact native replay, and finite
+explicit schedule-seed sweeps. These additive contracts do not produce or
+reinterpret historical Suite Run/2. Exhaustive exploration, distributed or
+parallel execution, cross-major promotion, remote URI input, and implicit
+schedule-seed derivation remain unsupported. The project is Apache-2.0 licensed.

{deterministic_scenario_engine-3.0.1 → deterministic_scenario_engine-3.1.0}/docs/api.md

@@ -9,7 +9,7 @@ exports.
 ## Constants and value objects
 
 - `scenario_engine.ENGINE_VERSION` — public current Engine coordinate, `2.0.0`.
-- `scenario_engine._version.VERSION` — distribution coordinate, `3.0.0`.
+- `scenario_engine._version.VERSION` — source distribution coordinate, `3.1.0`.
 - `scenario_engine._version.ENGINE1_VERSION` — explicit historical Engine 1
   execution coordinate, `1.0.0`; not added to the frozen package-root exports.
 
@@ -86,6 +86,39 @@ observations, and returns the verified immutable Result/2. It never reconstructs
 missing schedule evidence. Compatibility classification is explicit and does not
 execute, migrate, or promote evidence. Existing Engine 1 functions are unchanged.
 
+### Engine 2 suites and finite seed sweeps
+
+The additive suite API is public only from `scenario_engine.engine2_suite`:
+
+```python
+Engine2CaseRequest(...)
+Engine2SuitePlan(cases)
+execute_engine2_suite(plan) -> Engine2SuiteOutcome
+read_engine2_suite(source) -> Engine2SuiteOutcome
+verify_engine2_suite(suite, child_evidence=None) -> Engine2SuiteOutcome
+```
+
+Suite execution is finite, serial, and exactly plan ordered. Every case uses
+explicit Engine 2 coordinates. The strict reader verifies canonical aggregate
+shape and identity; `verify_engine2_suite()` additionally verifies supplied
+native Result/2, Manifest/2, and Schedule/1 bytes and their cross-artifact
+coordinates. Offline aggregate verification does not execute or replay cases.
+Exact replay remains a separate `replay_engine2()` operation requiring the exact
+scenario, effective inputs, and trusted plugin registry.
+
+The finite exploration convenience API is public only from
+`scenario_engine.engine2_explore`:
+
+```python
+Engine2SeedSweepRequest(...)
+explore_engine2_seeds(request) -> Engine2SeedSweepOutcome
+```
+
+It accepts an explicit ordered collection of 1..64 unique schedule seeds and
+uses the suite runner serially. It does not derive seeds, exhaustively explore a
+state space, run in parallel, or distribute execution. Neither module adds
+package-root exports or creates historical Suite Run/2 artifacts.
+
 `schedule_seed` is a required independent unsigned 64-bit coordinate. It is not
 derived from `root_seed`. Engine 2 writes Result/2, Manifest/2, and Schedule/1;
 exact replay requires the matching result, schedule, scenario, and explicit

{deterministic_scenario_engine-3.0.1 → deterministic_scenario_engine-3.1.0}/docs/dsl-reference.md

@@ -3,8 +3,8 @@
 This reference describes the frozen Scenario Engine DSL 1 grammar and semantics.
 Unknown keys are rejected in every schema-defined mapping.
 
-DSL 1 remains bound to Engine 1.0.0, Result/1, Manifest/1, and Suite Run/1 in
-distribution 3.0.0. Public Engine 2.0.0 does not promote or reinterpret DSL 1.
+DSL 1 remains bound to Engine 1.0.0, Result/1, Manifest/1, and Suite Run/1 in the
+3.1.0 distribution. Public Engine 2.0.0 does not promote or reinterpret DSL 1.
 See [DSL 2](dsl2-reference.md) for logical actors.
 
 ## Root document

deterministic_scenario_engine-3.1.0/docs/engine2-exploration.md

@@ -0,0 +1,128 @@
+# Engine 2 deterministic schedule-seed exploration
+
+## Scope and module-qualified API
+
+`scenario_engine.engine2_explore` provides:
+
+* `Engine2SeedSweepRequest`;
+* `Engine2SeedSweepOutcome`; and
+* `explore_engine2_seeds(request)`.
+
+These names are deliberately not package-root exports. A sweep is a finite,
+serial convenience operation over the existing hardened Engine 2 suite runner.
+It is not systematic scheduler branching, exhaustive model checking, state-space
+coverage, race-detection completeness, minimization, shrinking, distributed
+execution, or actual parallel execution.
+
+## Request and deterministic coordinates
+
+`Engine2SeedSweepRequest` requires one validated `CompiledScenarioV2`, one
+explicit root seed, an explicit run index, and an exact `list` or `tuple` of
+schedule seeds. It optionally accepts one supplied-input mapping and one explicit
+trusted `PluginRegistry`. The common expectation is `SUCCESS`, or `FAILED` plus
+one common expected failure code.
+
+The seed collection must contain 1..64 unique integers in `0..2^64-1`.
+Booleans, strings, floats, duplicates, sets, mappings, generators, empty
+collections, and larger collections fail before execution. No seed is derived or
+randomly generated, and supplied order is preserved exactly.
+
+Each seed becomes one `Engine2CaseRequest`; that accepted type remains the
+validator for scenario, root seed, run index, resources, inputs, plugins,
+compatibility coordinates, and expectations. Case identifiers use the fixed
+zero-based format `seed-sweep-{position:02d}` (for example, `seed-sweep-00`).
+Position and schedule seed are identity-bearing, so seed reordering changes the
+plan identity. Across cases only schedule seed, position, case ID, and resulting
+case identity vary. Scenario, scenario identity, root seed, run index, inputs,
+effective resources, plugin registry identity, expectation, and native
+compatibility coordinates remain fixed. Each native execution receives a fresh
+thawed input value; mutable execution state is not shared between cases.
+
+## Outcome and authoritative evidence
+
+`explore_engine2_seeds` constructs one `Engine2SuitePlan` and calls the existing
+`execute_engine2_suite` once. Execution is serial and plan ordered. The immutable
+`Engine2SeedSweepOutcome` exposes its original `Engine2SuiteOutcome` as `suite`.
+The seed list, IDs, identities, plan identity, attempted count, four status
+counts, non-success case coordinates, and first-observed distinct native schedule
+artifact identities are derived only from that suite outcome. They are not a
+second canonical evidence contract or competing source of truth.
+
+Direct construction of `Engine2SeedSweepOutcome` validates, without executing or
+replaying the suite, that its authoritative suite has the seed-sweep shape. Case
+IDs and positions must exactly match their ordered `seed-sweep-{position:02d}`
+coordinates, schedule seeds must be unique native-range integers, and every
+other request coordinate must be identical across cases. Consequently an
+ordinary suite, or a suite heterogeneous in scenario, root seed, run index,
+inputs, resources, plugins, expectations, or native compatibility coordinates,
+cannot be silently presented as a seed sweep.
+
+Every `SUCCESS`, `EXPECTED_FAILURE`, `UNEXPECTED_FAILURE`, and `ERROR` remains in
+the suite. Expected failure changes only the suite-level status interpretation;
+the native Result/2 and Schedule/1 remain `FAILED`. Completed cases retain exact
+Result/2, Manifest/2, and Schedule/1 authority. An `ERROR` has no fabricated
+native children and cannot independently provide replayable native evidence. A
+runtime suite retention or selection limit remains a truthful `ERROR` according
+to the existing fail-closed suite contract.
+
+The `schedule_artifact_identities` field is useful for exact artifact comparison,
+but distinct hashes do **not** prove distinct logical interleavings: schedule
+artifact identity includes execution coordinates such as the schedule seed. No
+new scheduling-decision trace equivalence is inferred.
+
+## Offline verification and exact replay
+
+Canonical suite bytes continue to use `read_engine2_suite`, followed by
+`verify_engine2_suite(suite, child_evidence)` for aggregate integrity, exact
+native child bytes, native identities, and coordinate linkage. Aggregate
+verification is not replay and no second verifier is introduced.
+
+Each completed in-memory case can be replayed separately:
+
+```python
+from scenario_engine.engine2 import replay_engine2
+
+for case in outcome.suite.cases:
+    if case.result is not None and case.schedule is not None:
+        replay_engine2(
+            case.result,
+            case.schedule,
+            scenario,
+            inputs=original_inputs,
+            plugins=trusted_plugins,
+        )
+```
+
+Replay requires the exact scenario and may require the original effective
+supplied inputs. Plugin cases require the exact trusted registry. Plugins are
+unsandboxed Python, are not discovered, and are not a security boundary. Error
+records without native children are not independently replayable evidence.
+
+## Resource limits
+
+The operation inherits all accepted suite limits: at most 64 cases; 262,144
+canonical input bytes per case; 4,194,304 aggregate input bytes; 524,288 request
+bytes per case; 1,048,576 aggregate request bytes; nesting depth 32; 65,536
+native selections per case; 262,144 aggregate selections; 67,108,864 retained
+child bytes; and 2,097,152 canonical suite bytes. Seed validation is finite and
+occurs before execution. Plan validation does not invoke plugin callables.
+
+## Minimal consumer example
+
+```python
+from scenario_engine.engine2 import validate_engine2
+from scenario_engine.engine2_explore import Engine2SeedSweepRequest, explore_engine2_seeds
+
+scenario = validate_engine2(open("scenario.yaml", encoding="utf-8").read())
+outcome = explore_engine2_seeds(Engine2SeedSweepRequest(
+    scenario=scenario,
+    root_seed="release-17",
+    schedule_seeds=[0, 1, 9],
+    run_index=0,
+))
+print(outcome.plan_identity, outcome.suite.aggregate_hash, outcome.success_count)
+```
+
+The tested contract suite validates the same API workflow with inline supported
+DSL 2 scenarios; this file-dependent consumer snippet is illustrative and does
+not claim validation of an external `scenario.yaml`.

deterministic_scenario_engine-3.1.0/docs/engine2-suite.md

@@ -0,0 +1,233 @@
+# Engine 2 serial suite contract
+
+This document defines the accepted `scenario.engine2-case/1`,
+`scenario.engine2-suite-plan/1`, and `scenario.engine2-suite/1` contracts included
+in distribution 3.1.0. They are additive and module-qualified. Existing
+Result/2, Manifest/2, Schedule/1, Scheduler/1, historical Suite Run/2, Engine 1,
+Engine 2 compatibility version 2.0.0, and package-root exports are unchanged.
+
+## Scope and API
+
+The API is available only from `scenario_engine.engine2_suite`:
+
+* `Engine2CaseRequest`, `Engine2SuitePlan`, `Engine2CaseOutcome`, and
+  `Engine2SuiteOutcome`;
+* `execute_engine2_suite(plan)`;
+* `read_engine2_suite(source)`; and
+* `verify_engine2_suite(suite, child_evidence=None)`.
+
+Execution is finite, serial, and exactly plan ordered. It accepts only already
+validated `CompiledScenarioV2` values and explicit independent `root_seed` and
+`schedule_seed` coordinates. It does not explore schedules, execute remotely,
+run in parallel, discover plugins, access a network, or support cross-major
+execution. Plugins are explicit trusted, unsandboxed Python and are not a
+security boundary.
+
+## Limits
+
+The initial hard limits are deliberately smaller than the native per-run and
+older batch ceilings:
+
+| Limit | Value |
+| --- | ---: |
+| cases per plan | 64 |
+| canonical supplied inputs per case | 262,144 bytes |
+| aggregate canonical supplied inputs | 4,194,304 bytes |
+| canonical case request coordinates | 524,288 bytes |
+| aggregate canonical case request coordinates | 1,048,576 bytes |
+| input nesting depth | 32 |
+| native selections per case | 65,536 |
+| aggregate native selections | 262,144 |
+| retained Result/2 + Manifest/2 + Schedule/1 bytes | 67,108,864 bytes |
+| canonical suite aggregate | 2,097,152 bytes |
+| canonical error record | 512 bytes |
+| case identifier UTF-8 bytes | 128 bytes |
+
+The 64-case, 64 MiB retained-evidence, and 2 MiB aggregate limits keep a suite
+reviewable and prevent the architecture proposal's unqualified 1,000-case and
+4 GiB values from becoming accidental commitments. Bounds are checked before
+case execution when knowable and incrementally before evidence retention.
+Integers exclude booleans. Exceeding a plan/input bound rejects the entire plan;
+exceeding a runtime aggregate selection or retention bound records a redacted
+case `ERROR` and continues only when safe. Nothing is silently truncated or
+represented as success. Plans must be explicit ordered sequences; generators
+and unordered containers are rejected before materialization. Input nesting is
+checked before normalization and immutable copying. A native Result/2 or
+Schedule/1 construction/serialization defect aborts the suite rather than
+discarding authoritative evidence and continuing with a misleading case record.
+The aggregate supplied-input limit is enforced against the sum of every case
+request's declared `input_bytes` during plan construction, aggregate object
+construction, strict canonical reading, and independent offline verification.
+Each declaration remains subject to its per-case limit; an aggregate containing
+individually valid declarations is rejected when their sum exceeds 4,194,304.
+
+## `scenario.engine2-case/1`
+
+The canonical case identity payload has exactly these required fields:
+
+* `contract`: literal `scenario.engine2-case/1`;
+* `position`: nonnegative integer equal to the containing list index;
+* `case_id`: unique portable ASCII label matching
+  `[A-Za-z0-9][A-Za-z0-9._:@/-]{0,127}`;
+* `scenario_hash`: existing canonical scenario SHA-256;
+* `root_seed`: explicit string or integer, excluding boolean;
+* `schedule_seed`: explicit integer in `0..2^64-1`, excluding boolean;
+* `run_index`: explicit nonnegative integer, excluding boolean;
+* `input_hash`: SHA-256 of canonical bytes for the complete supplied input
+  mapping, including unused supplied inputs;
+* `input_bytes`: byte length of those canonical input bytes;
+* `input_resource_hashes`: authoritative hashes from existing resource
+  resolution for the effective inputs;
+* `plugin_versions`: sorted explicit registry name-to-version mapping;
+* `reference_clock_start`: canonical timezone-aware semantic datetime,
+  normalized to UTC by the existing native Engine 2 clock rule;
+* `generator_versions`: existing generator requirements, including declared
+  plugin requirements;
+* `domain_pack_versions`: explicit empty mapping;
+* `dsl_version`, `engine_version`, `result_contract`, `manifest_contract`,
+  `schedule_contract`, `scheduler_contract`, `execution_model`,
+  `rng_algorithm_version`, `id_algorithm_version`, and `locale`: the exact
+  supported tuple `2`, `2.0.0`, `scenario.result/2`, `scenario.manifest/2`,
+  `scenario.schedule/1`, `scenario.scheduler/1`, `logical-actors/1`, current
+  RNG/ID versions, and `C`; and
+* `expectation`: an exact object with `classification` (`SUCCESS` or `FAILED`)
+  and `failure_code` (null for `SUCCESS`, otherwise a nonempty stable code).
+
+`case_identity` is lowercase SHA-256 of canonical bytes for that complete
+payload. The in-memory request accepts convenience defaults for `run_index=0`,
+empty inputs, no plugin registry, and expected success; construction converts
+them into every explicit canonical coordinate above. Scenario and plugin Python
+objects are excluded from serialized evidence. Resource identities are resolved
+before execution; no pre-execution identity is fabricated. Registry entries
+must exactly satisfy every declared plugin name/version. Plugin callables are
+never invoked by plan validation.
+
+## Plan identity
+
+An `Engine2SuitePlan` contains 1..64 unique case IDs and unique case identities.
+It assigns positions in request order and validates every case before any case
+executes. Its exact canonical plan identity payload is:
+
+```text
+{"case_identities":[...],"contract":"scenario.engine2-suite-plan/1",
+ "limits":{"aggregate_input_bytes":4194304,"aggregate_selections":262144,
+ "canonical_suite_bytes":2097152,"cases":64,"error_bytes":512,
+ "input_bytes_per_case":262144,"request_bytes_per_case":524288,
+ "request_bytes_total":1048576,"retained_child_bytes":67108864,
+ "selections_per_case":65536}}
+```
+
+where the shown object is canonically encoded without whitespace and the
+identity list is plan ordered. `plan_hash` is SHA-256 of those canonical bytes.
+All limit fields are mandatory identity-bearing coordinates; there are no
+serialized implicit defaults.
+
+## `scenario.engine2-suite/1`
+
+The canonical suite object has exactly these required fields:
+
+* `contract`: literal `scenario.engine2-suite/1`;
+* `plan`: exact object containing `contract`, ordered `case_identities`, exact
+  `limits`, and `plan_hash`;
+* `cases`: ordered case outcome records;
+* `counts`: exact object containing integer `success`, `expected_failure`,
+  `unexpected_failure`, `error`, and `total`;
+* `status`: `SUCCESS` only when every case is `SUCCESS` or
+  `EXPECTED_FAILURE`, otherwise `FAILED`; and
+* `aggregate_hash`: SHA-256 of canonical bytes for all preceding fields.
+
+Each case outcome record has exactly `request`, `case_identity`, `status`,
+`observed`, `native`, and `error`. `request` is the complete case identity
+payload. `status` is one of `SUCCESS`, `EXPECTED_FAILURE`,
+`UNEXPECTED_FAILURE`, or `ERROR`. `observed` is exactly
+`{"classification": "SUCCESS"|"FAILED"|null, "failure_code": string|null}`.
+
+For a completed native execution, `native` is an object with `result`,
+`manifest`, and `schedule`. Every reference has exactly `contract`, `identity`,
+`sha256`, and `size`: `identity` is the native result/manifest/schedule hash,
+while `sha256` hashes the complete exact canonical artifact bytes. For an
+execution error without retained authoritative native evidence, `native` is
+null; child hashes are never invented.
+
+`error` is null unless status is `ERROR`. An error is exactly `stage`, `family`,
+`code`, and `message`. The complete accepted combinations are:
+
+| Stage | Family | Code | Fixed message |
+| --- | --- | --- | --- |
+| `preflight` | `VALIDATION` | `CASE_VALIDATION_FAILED` | `case validation failed` |
+| `execution` | `PLUGIN` | `PLUGIN_EXECUTION_FAILED` | `trusted plugin execution failed` |
+| `execution` | `INTERNAL` | `INTERNAL_EXECUTION_FAILED` | `case execution failed` |
+| `retention` | `LIMIT` | `CHILD_EVIDENCE_BOUND_EXCEEDED` | `retained child evidence bound exceeded` |
+| `retention` | `LIMIT` | `SELECTION_BOUND_EXCEEDED` | `aggregate scheduler selection bound exceeded` |
+
+No cross-combination is valid. Plan construction normally rejects validation
+defects before execution; the preflight row reserves the only stable redacted
+record shape for a safely isolated case-validation failure. Unknown fields,
+codes, stages, families, altered messages, child references on an `ERROR`, and
+non-null observations on an `ERROR` are invalid. Exception text, paths, supplied
+values, plugin arguments, private inputs, and secrets are never serialized.
+
+A normal successful Result/2 matches only a declared `SUCCESS`. A native failed
+Result/2 always remains classified `FAILED`. It becomes suite status
+`EXPECTED_FAILURE` only when the declaration is `FAILED`, its failure code
+exactly equals both Result/2 and Schedule/1 failure codes, and the raised error
+is a recognized deterministic `InvariantViolation` with the same authoritative
+`internal_outcome`. Every other native failure is `UNEXPECTED_FAILURE`.
+Validation, plugin, limit, and unrecognized exceptions can never satisfy an
+expected-failure declaration. The supported expected-failure code set contains
+only `InvariantViolation`; it is not expanded by a matching arbitrary string.
+Every completed native observation other than expected success or that one
+supported expected invariant failure is `UNEXPECTED_FAILURE`. The strict reader
+enforces this status matrix. Because exception objects are not serialized, an
+offline reader can validate the stable code and native linkage but cannot prove
+that Python exception provenance was truly `InvariantViolation`; that stronger
+claim belongs to trusted execution or exact replay.
+
+## Strict reading and verification
+
+`read_engine2_suite` accepts bounded UTF-8 canonical bytes only. It rejects
+duplicate JSON keys, noncanonical bytes, excess nesting, unknown or missing
+fields, unsupported contracts/versions, bool-as-int values, bad hashes,
+duplicate IDs/identities, positions not equal to list indexes, malformed status
+combinations, malformed or noncanonical datetime wrappers, naive or non-datetime
+reference clocks, aggregate declared-input overflow, and inconsistent
+counters/status. Unhashable or incorrectly typed status/error fields produce
+stable suite-validation errors rather than escaping lookup exceptions. It
+reconstructs no scenario or plugin objects.
+
+`verify_engine2_suite` independently rechecks suite identities and accepts
+bounded child bytes supplied in memory as
+`{case_id: {"result": bytes, "manifest": bytes, "schedule": bytes}}`. It uses
+the existing strict native readers, validates exact byte size/SHA-256/native
+identity, verifies Manifest/2 equals the manifest embedded by Result/2, and
+checks every scenario/resource/seed/run/version/classification/failure and
+Result/2-to-Schedule/1 relationship. Missing, swapped, duplicated, incompatible,
+or tampered evidence fails closed. No filesystem publication or resolver is
+introduced.
+
+The verification boundary has four distinct layers:
+
+1. **Canonical aggregate integrity:** strict shape, bounds, canonical bytes,
+   status/count semantics, plan identity, case identities, and aggregate hash.
+2. **Native child artifact integrity:** exact byte lengths and SHA-256 values,
+   strict native readers, and native Result/2, Manifest/2, and Schedule/1
+   identities.
+3. **Cross-artifact coordinate linkage:** scenario, effective-resource hashes,
+   explicit seeds, run index, clock, versions, classification, failure, and
+   Result/2-to-Schedule/1 references agree.
+4. **Actual scenario replay:** execution of the exact scenario with its effective
+   original inputs and trusted plugin registry through existing `replay_engine2`.
+
+`verify_engine2_suite` establishes A-C only; it never claims or performs D. It
+executes no scenario, plugin, network request, or external command. Supplied-input
+hash and byte length are identity coordinates for the complete supplied mapping,
+including unused values; effective-resource hashes separately link the resolved
+resource snapshot. The original supplied/effective inputs may therefore be
+required separately for exact replay. Plugin registry name/version identity does
+not prove correctness or safety of untrusted Python callables. Likewise, a
+canonical `ERROR` record proves only that the aggregate contains an allowed
+redacted claim; offline verification cannot prove an actual execution exception
+occurred. Exact replay is separate and requires the exact scenario, inputs, and
+trusted registry for each complete case. Suite Run/2 is neither produced nor
+reinterpreted because partial cases and duplicate native result identities cannot
+always satisfy its frozen uniqueness/completeness semantics.

{deterministic_scenario_engine-3.0.1 → deterministic_scenario_engine-3.1.0}/docs/quickstart.md

@@ -1,6 +1,9 @@
 # Canonical installed-package workflows
 
-**3.0.1 release documentation.** These commands apply to distribution 3.0.1.
+The source distribution version is 3.1.0. PyPI and GitHub Releases are
+authoritative for actual publication and release history. These commands apply
+when distribution 3.1.0 is installed; the generic package install command below
+resolves only the version actually available from the package index.
 
 This is the canonical DSE user workflow document. Every ordinary command below
 uses the installed package and portable files created here; no source checkout,
@@ -37,10 +40,11 @@ sed 's/{$literal: 1}/{$literal: 2}/' "$DSE_DEMO/scenario.yaml" > "$DSE_DEMO/scen
 scenario --help
 ```
 
-The identity check uses the same active Python interpreter as installation. It
-should report DSE distribution `3.0.1`; the resolved module path shows the code
-Python actually imports. This distribution version is distinct from Engine 1
-(`1.0.0`) and Engine 2 (`2.0.0`) compatibility versions.
+The identity check uses the same active Python interpreter as installation. An
+installation of distribution 3.1.0 should report DSE distribution `3.1.0`; the
+resolved module path shows the code Python actually imports. This distribution
+version is distinct from Engine 1 (`1.0.0`) and Engine 2 (`2.0.0`) compatibility
+versions.
 
 Installing a checkout with `python3 -m pip install .` is
 **source-development-only**. Installed-package workflows are primary.
@@ -118,6 +122,17 @@ canonical Result/2 bytes, while JSON written to terminal stdout has one trailing
 presentation newline; raw byte comparison between those two forms is therefore
 not claimed.
 
+For multiple Engine 2 cases, use the module-qualified
+`scenario_engine.engine2_suite` API documented in [Engine 2 serial suites](engine2-suite.md).
+It executes finite plans serially in declared order and can strictly verify the
+canonical aggregate plus supplied native Result/2, Manifest/2, and Schedule/1
+children offline. Verification is not replay; exact replay still requires each
+case's exact scenario, effective inputs, schedule, and trusted plugins. The
+separate module-qualified `scenario_engine.engine2_explore` API performs only
+finite explicit schedule-seed sweeps. It is not exhaustive exploration,
+parallelism, or distributed execution. Neither API produces or reinterprets the
+historical Suite Run/2 contract.
+
 Both outputs are constructed before publication. Each destination is published
 atomically as an absent file; if this command publishes one output and then the
 other publication fails, it removes the output created by this command. This is

deterministic_scenario_engine-3.1.0/docs/release-notes-3.1.0.md

@@ -0,0 +1,51 @@
+# Deterministic Scenario Engine 3.1.0
+
+The source distribution version is 3.1.0. PyPI and GitHub Releases are
+authoritative for actual publication and release history. These notes describe
+the distribution contents; they do not authorize tagging or publication.
+
+## Additive features
+
+- Ordered serial Engine 2 suite execution through the module-qualified
+  `scenario_engine.engine2_suite` API and accepted
+  `scenario.engine2-case/1`, `scenario.engine2-suite-plan/1`, and
+  `scenario.engine2-suite/1` contracts.
+- Strict canonical suite reading and offline aggregate verification, including
+  exact native Result/2, Manifest/2, and Schedule/1 child-byte integrity and
+  cross-artifact coordinate linkage.
+- Finite explicit schedule-seed sweeps through the module-qualified
+  `scenario_engine.engine2_explore` API, preserving supplied seed order and the
+  suite's authoritative native evidence.
+
+## Compatibility guarantees
+
+- The distribution coordinate advances from 3.0.1 to 3.1.0 only.
+- Engine 1 remains 1.0.0 with DSL 1, Result/1, Manifest/1, and Suite Run/1.
+- Engine 2 remains 2.0.0 with DSL 2, Result/2, Manifest/2, and Schedule/1.
+- Existing canonical bytes, compatibility fixtures, API export manifests,
+  historical release identities, and accepted golden vectors remain unchanged.
+- The new suite aggregate is distinct from and does not produce, promote, or
+  reinterpret historical Suite Run/2.
+
+## Python support
+
+Python 3.11, 3.12, 3.13, and 3.14 remain supported. Declared dependency and
+optional-extra constraints are unchanged.
+
+## Evidence integrity and security limitations
+
+Offline suite verification proves canonical aggregate integrity, exact supplied
+child bytes and native identities, and coordinate linkage. It does not prove that
+execution occurred and is not exact replay. Exact replay separately requires the
+exact scenario, effective inputs, recorded schedule, and trusted plugin registry.
+Plugin callables are trusted, unsandboxed Python and are not a security boundary.
+Canonical error records are bounded claims and do not independently prove the
+originating exception. No network or remote evidence resolver is introduced.
+
+## Explicit non-goals
+
+This distribution does not provide exhaustive state-space exploration,
+systematic scheduler branching, race-detection completeness, shrinking or
+minimization, parallel or distributed execution, remote URI inputs, hidden plugin
+discovery, implicit schedule-seed derivation, cross-major promotion, or automatic
+migration. It does not change package-root exports or authorize publication.