feat(simulate): PR-flow, repo-flow, course-flow scenarios and flow-model rows B1-B7 (Refs #5511)

README.md

@@ -114,7 +114,7 @@ publishing — all backed by YAML provable contracts that fail CI on drift.
 | Metric | Count | Source of truth |
 |-------:|------:|---|
 | Workspace crates | **81** workspace crates | `cargo metadata --no-deps` (NOT `ls crates/` — 4 are `exclude`d, 1 has no Cargo.toml) |
-| Provable contracts | **<!-- CONTRACT_COUNT_START -->1983<!-- CONTRACT_COUNT_END -->** provable contracts | `contracts/census.json` `.n_files` — the set `pv lint` walks (`pv census`, ONT-001 ONT-1; regenerated by `make contracts`, written by `make readme-sync`, guarded by `scripts/check_readme_claims.sh`) |
+| Provable contracts | **<!-- CONTRACT_COUNT_START -->1984<!-- CONTRACT_COUNT_END -->** provable contracts | `contracts/census.json` `.n_files` — the set `pv lint` walks (`pv census`, ONT-001 ONT-1; regenerated by `make contracts`, written by `make readme-sync`, guarded by `scripts/check_readme_claims.sh`) |
 | CLI commands | **113** CLI commands | `contracts/apr-cli-commands-v1.yaml` §`commands` (parse the list; `apr --help` also lists `help` itself, and `grep -c '^  - name:'` gives 119 — other same-indent `name:` keys exist in the file) |
 | Book CLI chapters | **114** chapters | `ls book/src/cli/*.md` |
 | Book lib chapters | **73** chapters | `ls book/src/lib/*.md` (parity with `pub mod`) |
@@ -403,7 +403,7 @@ falsification_tests:
   prediction: apr validate bad-model.apr exits non-zero
 ```
 
-The tree carries <!-- CONTRACT_COUNT_START -->1983<!-- CONTRACT_COUNT_END --> contracts across inference, training, quantization, attention, FFN,
+The tree carries <!-- CONTRACT_COUNT_START -->1984<!-- CONTRACT_COUNT_END --> contracts across inference, training, quantization, attention, FFN,
 tokenization, model formats, CLI safety — and this README itself.
 
 ## Migration from old crates

ci/explicit-test-commands.d/763-aprender-simulate-pr-flow-contract.cmd

@@ -0,0 +1 @@
+cargo test -p aprender-simulate --test pr_flow_contract

contracts/apr-cli-commands-v1.yaml

@@ -901,7 +901,7 @@ commands:
     side_effects: [filesystem]
     # `version` comes from #2527's simular clap conversion, which the batch
     # takes over #2493's. FALSIFY-CLI-006 caught the omission.
-    subcommands: [emc-check, emc-validate, list-emc, render, run, validate, verify, version]
+    subcommands: [course-flow, emc-check, emc-validate, list-emc, pr-flow, render, repo-flow, run, validate, verify, version]
 
   - name: cgp
     category: tools

contracts/bin-aprender-simulate--aprender-simulate-v1.yaml

@@ -69,14 +69,17 @@ shapes:
       # G0.1 — a violation since batch/ont-10 2026-09-27 (build.rs embeds APR_GIT_SHA); was a warning while RED
       - {path: "bin:versionString", minCount: 1, maxCount: 1, pattern: "[0-9a-f]{9}"}
       - path: bin:command
-        minCount: 9
-        maxCount: 9
+        minCount: 12
+        maxCount: 12
         in:
+          - "course-flow"
           - "emc-check"
           - "emc-validate"
           - "help"
           - "list-emc"
+          - "pr-flow"
           - "render"
+          - "repo-flow"
           - "run"
           - "validate"
           - "verify"

contracts/contracts.nt

@@ -9709,6 +9709,13 @@
 <https://ont.paiml.dev/v1alpha1/contract/corpus-merge-v3-v1> <https://ont.paiml.dev/v1alpha1/kind> "corpus-assembly"^^<http://www.w3.org/2001/XMLSchema#string> .
 <https://ont.paiml.dev/v1alpha1/contract/corpus-merge-v3-v1> <https://ont.paiml.dev/v1alpha1/status> "PROPOSED"^^<http://www.w3.org/2001/XMLSchema#string> .
 <https://ont.paiml.dev/v1alpha1/contract/corpus-merge-v3-v1> <https://ont.paiml.dev/v1alpha1/version> "1.0.0"^^<http://www.w3.org/2001/XMLSchema#string> .
+<https://ont.paiml.dev/v1alpha1/contract/course-flow-batch-wip-v1> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://www.w3.org/ns/prov#Entity> .
+<https://ont.paiml.dev/v1alpha1/contract/course-flow-batch-wip-v1> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <https://ont.paiml.dev/v1alpha1/Contract> .
+<https://ont.paiml.dev/v1alpha1/contract/course-flow-batch-wip-v1> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <https://ont.paiml.dev/v1alpha1/Kernel> .
+<https://ont.paiml.dev/v1alpha1/contract/course-flow-batch-wip-v1> <https://ont.paiml.dev/v1alpha1/file> "contracts/course-flow-batch-wip-v1.yaml"^^<http://www.w3.org/2001/XMLSchema#string> .
+<https://ont.paiml.dev/v1alpha1/contract/course-flow-batch-wip-v1> <https://ont.paiml.dev/v1alpha1/id> "course-flow-batch-wip-v1"^^<http://www.w3.org/2001/XMLSchema#string> .
+<https://ont.paiml.dev/v1alpha1/contract/course-flow-batch-wip-v1> <https://ont.paiml.dev/v1alpha1/name> "course-flow-batch-wip"^^<http://www.w3.org/2001/XMLSchema#string> .
+<https://ont.paiml.dev/v1alpha1/contract/course-flow-batch-wip-v1> <https://ont.paiml.dev/v1alpha1/version> "1.0.0"^^<http://www.w3.org/2001/XMLSchema#string> .
 <https://ont.paiml.dev/v1alpha1/contract/cpp-type-preservation-v1> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://www.w3.org/ns/prov#Entity> .
 <https://ont.paiml.dev/v1alpha1/contract/cpp-type-preservation-v1> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <https://ont.paiml.dev/v1alpha1/Contract> .
 <https://ont.paiml.dev/v1alpha1/contract/cpp-type-preservation-v1> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <https://ont.paiml.dev/v1alpha1/Kernel> .

contracts/course-flow-batch-wip-v1.yaml

@@ -0,0 +1,47 @@
+metadata:
+  version: "1.0.0"
+  created: "2026-10-18"
+  author: PAIML Engineering
+  registry: true
+  references:
+    - "Little, J.D.C. (1961), A Proof for the Queuing Formula L = lambda W."
+    - "flow model spec, internal (eq 1)"
+  description: "course_flow counts the daily human batch gate inside WIP and reports its mean wait"
+
+name: course-flow-batch-wip
+version: "1.0.0"
+scope: "crates/aprender-simulate/src/scenarios/course_flow.rs"
+
+description: |
+  A daily human batch gate holds finished items until its next release. With
+  batch_in_wip set, an item holds its WIP slot while it waits there, so Little's
+  law L = lambda W closes on a window that includes the gate. The mean time an item
+  spends at the gate is reported as mean_batch_wait_h.
+
+equations:
+  little_with_gate:
+    description: "|lambda W - L| / L <= 0.005 with WIP including the batch wait"
+    formula: "|lambda * W - L| / L <= 0.005"
+
+  gate_wait_bounded:
+    description: "mean batch wait lies inside one gate interval"
+    formula: "0 < mean_batch_wait_h < 24"
+
+falsification_tests:
+  - id: FALSIFY-001
+    description: "Little's law holds within 0.5% with the batch wait inside WIP"
+    test: "cargo test -p aprender-simulate --lib littles_law_holds_with_batch_wait_inside_wip"
+    prediction: "the test passes"
+    if_fails: "the batch gate is not counted inside WIP as the contract states"
+
+  - id: FALSIFY-002
+    description: "mean_batch_wait_h is reported and lies inside one day"
+    test: "cargo test -p aprender-simulate --lib mean_batch_wait_is_reported_and_inside_a_day"
+    prediction: "the test passes"
+    if_fails: "the batch gate is not counted inside WIP as the contract states"
+
+  - id: FALSIFY-003
+    description: "counting the batch inside WIP changes the result (not a no-op)"
+    test: "cargo test -p aprender-simulate --lib batch_in_wip_is_not_a_no_op"
+    prediction: "the test passes"
+    if_fails: "the batch gate is not counted inside WIP as the contract states"

contracts/shapes.ttl

@@ -908,9 +908,9 @@
     ] ;
     sh:property [
         sh:path <https://ont.paiml.dev/v1alpha1/bin/command> ;
-        sh:minCount 9 ;
-        sh:maxCount 9 ;
-        sh:in ( "emc-check" "emc-validate" "help" "list-emc" "render" "run" "validate" "verify" "version" ) ;
+        sh:minCount 12 ;
+        sh:maxCount 12 ;
+        sh:in ( "course-flow" "emc-check" "emc-validate" "help" "list-emc" "pr-flow" "render" "repo-flow" "run" "validate" "verify" "version" ) ;
     ] ;
     sh:property [
         sh:path <https://ont.paiml.dev/v1alpha1/bin/route> ;

contracts/witness/811c78184eb2609244c59534f015f0be2f90923120a3027c176ad56723d0d850.json

@@ -1,7 +1,7 @@
 {
-  "census_id_set_sha256": "021e98642f5a6c17b5389d388a0d4b18df2707f513fda99ae35b661dca0b03c3",
+  "census_id_set_sha256": "7597b4ad189f534dd58cda55c9b1fe29e6339ddb77fd5f40969b4a028eed8f88",
   "relations_sha256": "811c78184eb2609244c59534f015f0be2f90923120a3027c176ad56723d0d850",
-  "reasoner_git_sha": "a56c47b937da11a6c94132b89c28d9420a84f372",
+  "reasoner_git_sha": "461bf9ef1921a8fbea4bc338f21b566ec342a95e",
   "checkable_n": 87,
   "result": {
     "kind": "model",

crates/aprender-simulate/src/cli/args.rs

@@ -62,6 +62,7 @@ impl Cli {
 
 /// Available CLI commands.
 #[derive(Debug, Clone, PartialEq, Subcommand)]
+#[allow(clippy::large_enum_variant)] // PrFlow carries the measured-input overrides; parsed once at startup
 pub enum Commands {
     /// Run an experiment
     Run {
@@ -95,6 +96,99 @@ pub enum Commands {
         #[arg(long, default_value_t = 42)]
         seed: u64,
     },
+    /// Run the aprender PR-flow scenario (FLOW-005) for a named design
+    PrFlow {
+        /// Design: D, A, G or E.
+        #[arg(long, default_value = "D", value_parser = ["D", "A", "G", "E"])]
+        design: String,
+        /// Print the cycle-record "sim" block as one JSON line.
+        #[arg(long)]
+        json: bool,
+        /// Override the PR-check runner pool (measured input).
+        #[arg(long)]
+        r_pr: Option<usize>,
+        /// Override the merge-queue runner pool (measured input).
+        #[arg(long)]
+        r_mq: Option<usize>,
+        /// Override the WIP cap (measured input).
+        #[arg(long)]
+        cap: Option<usize>,
+        /// Override concurrent merge-queue groups (measured input).
+        #[arg(long)]
+        builds: Option<usize>,
+        /// Override the merge-group flake rate (measured input).
+        #[arg(long)]
+        f: Option<f64>,
+        /// Override mean concurrent authors (may be fractional).
+        #[arg(long)]
+        n: Option<f64>,
+        /// Measured PR-check runner-minutes per run.
+        #[arg(long)]
+        pr_min: Option<f64>,
+        /// Measured merge-queue runner-minutes per run.
+        #[arg(long)]
+        mq_min: Option<f64>,
+        /// Measured share of PR runs that go red.
+        #[arg(long)]
+        p_red: Option<f64>,
+        /// Measured queue wait per PR run, minutes.
+        #[arg(long)]
+        pr_setup: Option<f64>,
+        /// Review wait per PR after green checks, minutes (default 0).
+        #[arg(long)]
+        t_rev: Option<f64>,
+        /// Run the review alongside the checks instead of after them.
+        #[arg(long)]
+        rev_concurrent: bool,
+        /// Parallel reviewers (0 = unlimited).
+        #[arg(long)]
+        rev_lanes: Option<usize>,
+        /// Merged PRs in the last 24 h, from git (for drift_pct_24h).
+        #[arg(long)]
+        observed_24h: Option<f64>,
+        /// Comma-separated run ids the measured inputs came from.
+        #[arg(long)]
+        src_runs: Option<String>,
+        /// Arbiter params file for one repo (ARB-SOT-001 §3); prints {actual, one_change, optimum}.
+        #[arg(long)]
+        params: Option<PathBuf>,
+        /// Seeds 1..=N for `--params`.
+        #[arg(long, default_value_t = 5)]
+        seeds: u64,
+        /// Simulated hours per seed for `--params`.
+        #[arg(long, default_value_t = 400.0)]
+        hours: f64,
+        /// Warm-up hours discarded for `--params`.
+        #[arg(long, default_value_t = 20.0)]
+        warmup: f64,
+        /// Commit the sim block is stamped with.
+        #[arg(long, default_value = "unknown")]
+        sha: String,
+    },
+    /// Run a FLOW-006 repo case (conflict step, optional merge queue); --json prints the sim block
+    RepoFlow {
+        /// Case name, for example rmedia-design or infra-rule.
+        #[arg(long)]
+        case: String,
+        /// JSON file of measured inputs from the ledger; overrides the case.
+        #[arg(long)]
+        inputs: Option<std::path::PathBuf>,
+        /// Print the sim block as JSON.
+        #[arg(long)]
+        json: bool,
+    },
+    /// Run a FLOW-006 course-factory case; --json prints the sim block
+    CourseFlow {
+        /// Case: cal-today, design, nine-builders, coursera-24h or render-300.
+        #[arg(long)]
+        case: String,
+        /// JSON file of measured inputs from the ledger; overrides the case.
+        #[arg(long)]
+        inputs: Option<std::path::PathBuf>,
+        /// Print the sim block as JSON.
+        #[arg(long)]
+        json: bool,
+    },
     /// Validate experiment YAML against EDD v2 schema
     Validate {
         /// Path to the experiment YAML file.