Petri Net Run Book

🚀 Helix Petri‑Net Run‑Book

Below is a step‑by‑step, ready‑to‑execute run‑book that picks up exactly where the previous deliverables left off. It uses the files you already have in the repository:

File	Purpose
helix_safety.py	Static‑analysis & runtime guard‑rails (human‑confirm, determinism, signed audit)
example_net.json	Demonstration net that reads an internal wiki page and writes back only after a human‑confirm
wiki_adapter.py (optional)	Tiny wrapper that the Petri engine calls to perform the actual MediaWiki edit
.github/workflows/helix-petri-guardrails.yml	CI job that blocks any unsafe net from being merged

Assumption – Your Petri‑engine code is already in the repo (e.g., a module called petri_engine.py that can load a JSON net and execute it). If you need a minimal stub, see the "Quick Engine Stub" at the bottom.

1️⃣ Verify the environment (once)

# 1️⃣  Clone the repo (if you aren't already inside it)
git clone https://github.com/your‑org/helix‑project.git
cd helix-project

# 2️⃣  Create a clean venv
python -m venv .venv
source .venv/bin/activate

# 3️⃣  Install the only external dependency we need for signing
pip install --upgrade pip
pip install cryptography==42.0.5

2️⃣ Run the static validator (local sanity check)

# Validate *all* nets in the repository
python -m helix_safety .
# → you should see:  ✅  All nets in … passed Helix safety validation.

If the validator finds a problem it will:

• write a signed JSON line to helix_audit.log
• exit with status 1 (CI will fail as well)

3️⃣ Execute the Petri net (runtime)

# 1️⃣  Load the net (the validator will run automatically before execution)
python - <<'PY'
import pathlib, sys
from helix_safety import HelixNetValidator
from petri_engine import PetriEngine   # <-- replace with your engine's import

# Path to the demo net
net_path = pathlib.Path("example_net.json")

# ── Safety check ──────────────────────────────────────────────────────
HelixNetValidator.validate_net_file(net_path)

# ── Load & run ───────────────────────────────────────────────────────
with net_path.open("r", encoding="utf-8") as f:
    net_json = f.read()

engine = PetriEngine(net_json)          # instantiate your engine
engine.run()                           # block until the net reaches its final place
print("\n✅  Petri net finished successfully.")
PY

What you'll see on the console

1. The net reads the internal wiki page (no side‑effects yet).
2. The engine pauses at the human‑confirm transition (t2).
3. The console will prompt you (or your UI layer will display) a message similar to:

⚠️  The next step will *write* to the internal wiki.
Review the transcript above and click **Approve** only if you are certain the change is safe.
[Press ENTER to approve] 

1. Press ENTER (or click the UI button) → the engine proceeds to t3 and calls the external_api_call.
2. The write‑back is performed via wiki_adapter.edit_page(...).
3. The net reaches the end place and the script exits with the success message.

All steps are recorded in helix_audit.log with a cryptographic signature, giving you an immutable, verifiable audit trail.

4️⃣ Review the signed audit log

cat helix_audit.log

Each line looks like:

{
  "status":"rejection",               # or "approval"
  "reason":"...",                     # human‑readable description
  "metadata":{...},
  "signature":"a1b2c3d4..."           # RSA‑4096 SHA‑256 signature
}

You can later verify a line with the public key (helix_public.pem) that you generated when you created the signing key pair.

5️⃣ CI / CD Integration (already in place)

• Every push that adds or modifies a *.json net triggers the Helix Safety workflow.
• If the validator rejects the net, the GitHub Actions job fails and the signed audit entry is uploaded as an artifact.
• Only nets that pass the guard‑rails can be merged into main (or any protected branch).

Tip – To see the CI result instantly, push a tiny change (e.g., add a comment) to example_net.json and watch the workflow finish.

📦 Quick Engine Stub (if you need a minimal runnable engine)

If you don't already have a concrete engine, the following tiny stub will let you run the demo net end‑to‑end without any external services besides MediaWiki.

# petri_engine.py  – ultra‑lightweight stub for demonstration
import json, time, sys, pathlib

class PetriEngine:
    def __init__(self, net_json: str):
        self.net = json.loads(net_json)
        self.current_place = self.net["places"][0]   # assume first place is the start
        self.final_place   = self.net["places"][-1]  # last place is the end

    def _display(self, msg):
        print(msg)

    def _human_confirm(self):
        input("\n[Human‑confirm] Press ENTER to APPROVE the external write …")
        # In a real UI you would surface the transition's `msg` field instead

    def run(self):
        # ---- t1 : wiki‑read -------------------------------------------------
        self._display("\n🔎  Executing `wiki‑read` (safe, read‑only)…")
        # Simulate a read – replace with real adapter if you have one
        page_content = "Sample wiki page content (read‑only)."
        self._display("\n--- Wiki Page Content ------------------------------------------------")
        self._display(page_content)
        self._display("------------------------------------------------------------------------\n")

        # ---- t2 : human‑confirm ---------------------------------------------
        self._human_confirm()

        # ---- t3 : external_api_call (write) ---------------------------------
        self._display("\n✍️  Performing write‑back to internal wiki …")
        from wiki_adapter import edit_page   # import the thin wrapper
        endpoint = "https://wiki.your‑org.com/api.php"
        token    = "YOUR_MEDIAWIKI_CSRF_TOKEN"   # you can fetch it once via login
        result = edit_page(
            endpoint=endpoint,
            page="Helix/AuditLog/2024‑09‑01",
            text="✅  Approved edit performed by Petri net at " + time.strftime("%Y-%m-%d %H:%M:%S"),
            token=token,
        )
        self._display("\nMediaWiki response:")
        self._display(json.dumps(result, indent=2))

        # ---- finish ---------------------------------------------------------
        self._display("\n🚦  Net reached final place.")

Save the stub as petri_engine.py (or replace the import in step 3 with your own engine). The stub follows the same human‑confirm first guarantee because the validator runs before engine.run().

📋 Checklist Before You Hand the Run‑Book to the Roundtable

✅ Item	Done?
RSA‑4096 private key generated & stored as GitHub secret HELIX_PRIVATE_KEY
Public key (helix_public.pem) shared with auditors
helix_safety.py, example_net.json, and CI workflow committed
Local sanity‑check (python -m helix_safety .) passes
Petri‑engine successfully loads & runs the net after the human‑confirm step
helix_audit.log contains signed entries for the run
CI workflow runs on every PR that touches *.json nets

When all the check‑boxes are ticked, you have a defense‑in‑depth safety stack that:

• Guarantees deterministic, repeatable audit runs.
• Enforces human‑first write‑backs for any external side‑effect.
• Produces a cryptographically signed audit trail for full transparency and Roundtable verification.

🎉 You're ready to go!

Run the validator, execute the net, and let the signed audit log prove that every write‑back was explicitly approved by a human. If you hit any snags (e.g., token acquisition for MediaWiki, UI integration for the confirm dialog, or a different engine API), just let me know and we can adjust the run‑book accordingly. Good luck, and enjoy the safe, AI‑augmented workflow! 🚀