# Intent Petri V2｜Implementation Report

Status: implemented on Pi 0.80.6; V2 shipped as `0.2.0`, Herdr/checkpoint/live-progress changes shipped in `0.2.1`, and npm-bin symlink execution was fixed in `0.2.2`.

## Delivered

### Certain current execution stack

- WorkflowState schema 2.
- One Execution Token with one executable active leaf.
- Multiple active ancestor shells constrained to one linear nested-refinement chain.
- Arbitrarily nested `refine_transition` scopes with explicit entry, success exit, and optional failure exit.
- Atomic deepening of an already-active executable leaf into a shell, plus active-refinement replacement without false completion/failure.
- Deterministic recursive success/failure unwinding.
- Fixed `(opIndex, eventIndex)` DomainEvent order, including derived parent-shell and token-movement events.
- Active-leaf supersession without falsifying completion or failure.

### Provisional future paths

- `committed / provisional / directional` planning commitment.
- Structured Place, Gate, transition-outcome, and Evidence dependencies.
- Dedicated exact Evidence selector tags; no natural-language substring inference.
- Provisional paths require `dependsOn` or `reconsiderWhen`.
- Directional-origin transitions retain `requiresRefinement` and cannot activate directly as leaves.
- Planning changes require a reason, reject semantic no-ops, and derive Human provenance only from runtime-bound exact statements in real Pi user entries; caller-declared claims are downgraded.

### Migration and branch authority

- Schema-1 snapshot hashing retained for legacy verification.
- Deterministic schema-1 → schema-2 in-memory migration.
- Migration-safe provisional and directional defaults.
- Reservation, token marking, shell/leaf, planning, topology, and refinement invariants validated during reconstruction.
- Checkpoint details, state, batch, AppliedPatchRecord, revision, snapshot hash, request hash, event order, and base revision are bound together.
- Schema-2 batches are replayed from the previous verified state and compared with the stored snapshot and events.
- A broken checkpoint chain stops at the last verified state; later non-descendant snapshots are not accepted.
- SQLite and projection side effects are deferred until Pi has persisted the real tool-result entry and emitted `message_end`.

### Graph and history projections

- Current Stack and Future Planning Cone attention projection.
- Full, causal-spine, and bounded-local Mermaid TD projections.
- Typed place/action labels, explicit success/failure/condition edges, and automatic 18-column label wrapping.
- Unicode/ASCII rendering through `beautiful-mermaid`.
- Event-based NodeChange history, including derived shell/refinement/token changes.
- Immutable projection generations and revision cache.
- Atomic root `current.json` commit marker.
- Branch switching rebuilds the active lineage without mixing events or revision files.
- State files remain private (`0700` directories, `0600` files).

### Local multi-session web hub (current primary UI)

- Singleton local process: `intent-petri-hub` on `127.0.0.1` (default port `7731`).
- Serves every `sessions/<session-id>/active` projection at once; no project-cwd single-instance collapse.
- HTTP API: `/api/health`, `/api/sessions`, `/api/sessions/:id`, SSE `/api/sessions/:id/stream`.
- Embedded SPA lists sessions and renders structured graph + attention panels in the browser.
- Extension `session_start` ensures the hub in the background; `/intent-petri viewer` opens the session URL.
- Ephemeral `activity.json` carries tool heartbeat for the hub (sparse writes; 5s ticker while tools run).
- Terminal `intent-petri-viewer` remains an offline/debug ASCII fallback, not the primary UI.
- Herdr graph plugin (`herdr-plugin.toml` / pane scripts) removed.

### Pi surface

- Pi retains the `update_action_path` tool, branch reconstruction, persistence, and diagnostic commands.
- Intent Petri never calls `setStatus`, `setWidget`, `ui.custom`, or `showOverlay`.
- `STACK / NOW / WHY / NEXT / WATCH`, graph rendering, and RUN heartbeat are absent from the Pi input area.
- `/intent-petri` points the user to the local web hub; `status`, `doctor`, and `viewer` remain text diagnostics.

## User commands

```text
/intent-petri status
/intent-petri doctor
/intent-petri viewer
```

```bash
nubx intent-petri-hub ensure --open
# or: nub run hub
```

## Packaging

- V2 initially shipped as `0.2.0`; `0.2.1` adds Herdr visualization, live progress, and compatibility recovery; `0.2.2` fixes direct npm `.bin` symlink execution.
- Package is publishable with public access.
- `beautiful-mermaid@1.1.3` is a runtime dependency.
- Pi libraries remain peer dependencies.
- The tarball includes the extension, source, design and implementation docs, Herdr plugin manifest/scripts, root development viewer, and plain ESM viewer bin.
- `prepublishOnly` runs typecheck, tests, package validation, and Pi smoke loading.

## Verification

Required verification:

```text
nub run typecheck          PASS
nub run test               PASS — 22 files, 66 tests
nub run package:check      PASS
nub run smoke:extension    PASS
nub pack --dry-run         PASS
```

The qualifying 45-tool-result / 15-revision acceptance replay is recorded in [V2_ACCEPTANCE.md](V2_ACCEPTANCE.md).

Additional acceptance coverage includes:

- nested two-level success and failure unwinding;
- failure contained inside a subnet without a failure exit;
- active-leaf supersession;
- invalid/empty refinement rejection;
- directional direct-activation rejection;
- exact Evidence selector matching;
- schema-1 planned/retired/superseded migration;
- legacy event-index normalization;
- reservation/marking mismatch rejection;
- forged batch, duplicate revision, and reordered event rejection;
- deferred side effects before persisted tool result;
- immutable projection generations and branch replacement;
- event-based derived NodeChange history;
- installed viewer CLI execution;
- Herdr manifest validation, linked action invocation, and managed graph-pane startup;
- proof that lifecycle and commands do not mount Pi status, widget, modal, or overlay UI.