feat: add durable bridge ledger scaffold

HANDOFF.md

@@ -4,10 +4,10 @@
 
 - GitHub: `https://github.com/Jdelg718/BotFucker`
 - Default branch: `main`
-- Latest merged milestone: Phase 12 real n8n import/dry-run validation (`docs: validate n8n import dry run`, PR #13)
-- Current working branch: `phase-13-reviewed-action-bridge-promotion-plan`
-- Current PR target: Phase 13 Reviewed Action Bridge Promotion Plan — docs/tests only, no OAuth/live provider mutation
-- Current local demo target: demonstrate deterministic local review, optional mocked LLM classifier fallback/validation, approved-action export, dry-run n8n bridge contract, fail-closed YOLO policy checks, real n8n import validation results, and reviewed bridge-promotion gate
+- Latest merged milestone: Phase 13 Reviewed Action Bridge Promotion Plan (`docs: plan reviewed action bridge promotion`, main at 4619bf5)
+- Current working branch: `phase-14-durable-bridge-ledger`
+- Current PR target: Phase 14 Durable Bridge Ledger Scaffold — code/docs/tests only, no OAuth/live provider mutation
+- Current local demo target: demonstrate deterministic local review, optional mocked LLM classifier fallback/validation, approved-action export, dry-run n8n bridge contract, fail-closed YOLO policy checks, real n8n import validation results, reviewed bridge-promotion gate, and durable bridge ledger dedupe scaffold
 - Current promo artifact: `promo/botfucker-animated-explainer/renders/botfucker-animated-explainer_narrated-final.mp4`
 
 ## What BotFucker Is
@@ -35,13 +35,15 @@ docs/n8n-approved-action-bridge.json # importable n8n approved-action dry-run br
 docs/n8n-approved-action-bridge.md   # approved-action bridge operator guide
 docs/provider-auth-plan.md    # provider auth/action boundary plan
 docs/reviewed-action-bridge-promotion-plan.md # Phase 13 reviewed live-bridge gate; no OAuth/live mutation
+docs/bridge-ledger-scaffold.md # Phase 14 durable processed-audit ledger scaffold; no OAuth/live mutation
 README.md                     # user-facing setup and project overview
 outreach_filter.py            # compatibility CLI wrapper
 botfucker/models.py           # normalized email/classification/review models
 botfucker/classifier.py       # deterministic classifier
 botfucker/history.py          # SQLite sender history + strike state
 botfucker/review_queue.py     # review item/audit models and sample data helpers
 botfucker/review_store.py     # durable SQLite review queue and audit store
+botfucker/bridge_ledger.py    # durable bridge processed-audit ledger scaffold
 botfucker/review_cli.py       # durable local review CLI
 botfucker/webhook_contract.py # n8n/webhook payload sanitizer/import adapter
 botfucker/local_ui.py         # local browser review UI server
@@ -64,6 +66,7 @@ These are non-negotiable:
 - n8n/provider credentials stay in n8n or the provider layer, not BotFucker core.
 - Local UI and review CLI actions affect SQLite review state only.
 - Provider-side actions are future bridge work, not local UI behavior.
+- The Phase 14 durable bridge ledger records `audit_id` state only (`bridge_ledger_state_only`) before provider mutation; it is not a provider action engine.
 
 ## Current Test Commands
 
@@ -267,15 +270,15 @@ python3 -m unittest discover -s tests -v
 
 ## Next PR Recommendation
 
-After Phase 13, keep OAuth on hold. The next safe step is either documentation review cleanup for the promotion gate or a mocked/sandbox-only processed-audit state prototype that still performs no live provider mutation.
+After Phase 14, keep OAuth on hold. The next safe step is emergency-stop proof or a sandbox-only bridge rehearsal that uses the durable bridge ledger and still performs no production provider mutation.
 
 Do **not** add real OAuth, provider credentials, or live n8n provider mutation nodes until the Phase 13 gate has Rex/Gus review and provider-specific sandbox evidence.
 
 Suggested follow-up scope:
 
-1. Review Phase 13 plan with Rex/Gus.
-2. Decide the first provider/action pair for sandbox review, likely `approve_warning` only.
-3. Prototype processed-`audit_id` state with fake/sample data only.
+1. Review Phase 14 ledger scaffold with Rex/Gus.
+2. Keep the first provider/action pair to `approve_warning` only.
+3. Use processed-`audit_id` state before any provider mutation attempt.
 4. Keep credentials in n8n only.
 5. Require rollback and emergency-stop proof before any live provider action node is connected.
 
@@ -284,28 +287,28 @@ Suggested follow-up scope:
 ```text
 You are working on BotFucker, an AI-era inbox defense app.
 
-Read DESIGN.md, ROADMAP.md, HANDOFF.md, README.md, docs/webhook-contract.md, docs/n8n-workflow.md, docs/n8n-approved-action-bridge.md, docs/n8n-import-validation.md, and docs/provider-auth-plan.md.
+Read DESIGN.md, ROADMAP.md, HANDOFF.md, README.md, docs/webhook-contract.md, docs/n8n-workflow.md, docs/n8n-approved-action-bridge.md, docs/n8n-import-validation.md, docs/provider-auth-plan.md, docs/reviewed-action-bridge-promotion-plan.md, and docs/bridge-ledger-scaffold.md.
 
-First, verify the current Phase 12 branch without changing behavior:
+First, verify the current Phase 14 branch without changing behavior:
 - run python3 scripts/validate_n8n_workflow_exports.py
 - run python3 -m py_compile outreach_filter.py botfucker/*.py scripts/validate_n8n_workflow_exports.py
 - run python3 -m unittest discover -s tests -v
-- inspect docs/n8n-import-validation.md and samples/approved-actions.sample.json
-- confirm n8n workflows include explicit ids, are inactive, and use /home/node/.n8n-files for Read/Write Files paths
+- inspect docs/bridge-ledger-scaffold.md and botfucker/bridge_ledger.py
+- confirm the ledger stores durable audit_id/status data only and has no provider calls or credential fields
 
-Then review Phase 12 only: Real n8n Import/Dry-Run Validation.
+Then review Phase 14 only: Durable Bridge Ledger Scaffold.
 
-Check that both workflows imported into n8n-vps as inactive/manual, approved-action bridge executed sample-only dry-run, final output was provider_execution:not_performed, and cleanup removed validation rows/temp files.
+Check that claim_action records pending state before provider mutation, duplicate audit_id claims fail closed, unsafe approved-action exports are rejected, and no OAuth/provider credentials/live provider mutation nodes were added.
 
 Do not add real OAuth. Do not add provider credentials. Do not attach Gmail/Microsoft/IMAP/SMTP mutation credentials. Do not enable live n8n provider actions. Preserve the provider boundary: live provider execution remains separately reviewed and guarded.
 ```
 
 ## Team Plan
 
 - **Amy**: orchestration and scope control. She keeps the product from wandering into OAuth swamp country before bridge promotion is reviewed.
-- **Chip**: owns reviewed action bridge promotion docs/tests if Phase 12 review passes.
+- **Chip**: owns durable bridge ledger scaffold and bridge promotion safety docs/tests.
 - **Rex**: security veto on processed-audit dedupe, credential absence, live-action safety gates, provider-boundary isolation, and XSS regressions.
-- **Gus**: n8n operator verification, dry-run bridge observability, cleanup steps, CI, and operator docs.
+- **Gus**: n8n operator verification, dry-run bridge observability, cleanup steps, CI, ledger operability, and operator docs.
 - **Fred**: provider sandbox/action-limit research only; no direct OAuth implementation yet.
 
 ## Known Follow-Up Issues
@@ -315,13 +318,14 @@ Do not add real OAuth. Do not add provider credentials. Do not attach Gmail/Micr
 - No production OAuth yet.
 - Real n8n import validation passed on n8n-vps with sample-only dry-run and cleanup; do not activate those workflows without a separate reviewed bridge-promotion plan.
 - n8n approved action bridge is dry-run only; live provider actions still need a separate explicit reviewed workflow.
+- Phase 14 durable bridge ledger scaffold exists for processed-`audit_id` dedupe, but it is not connected to live provider mutation.
 - YOLO guardrails exist but live provider actions still require explicit operator configuration and must not be casually enabled.
 
 ## Tomorrow Restart
 
-- PR #13 is open and CI green: `https://github.com/Jdelg718/BotFucker/pull/13`.
-- First move tomorrow: re-check PR #13, merge if green, pull `main`, branch Phase 13.
-- Phase 13 target: **Reviewed Action Bridge Promotion Plan**.
+- Phase 14 branch is local: `phase-14-durable-bridge-ledger`.
+- First move next: re-check tests, review diff, and open/squash Phase 14 if green.
+- Phase 15 target should be emergency-stop proof or sandbox-only bridge rehearsal using the durable ledger.
 - Do **not** add OAuth, provider credentials, or live n8n provider mutation nodes.
 - Keep live provider execution separate, reviewed, audited, deduped by processed `audit_id`, rollback-ready, and security/ops-reviewed.
 

README.md

@@ -18,6 +18,7 @@ The current core is split into reusable modules under `botfucker/`:
 - `classifier.py` returns structured deterministic classifications with reasons.
 - `history.py` tracks sender history, warning counts, and strike levels in SQLite.
 - `review_store.py` persists local review queue items and audit events in SQLite.
+- `bridge_ledger.py` provides a durable bridge ledger scaffold keyed by approved-action `audit_id` values.
 - `webhook_contract.py` normalizes bounded n8n/webhook email JSON into local review items.
 - `review_cli.py` provides a provider-safe local review workflow around seeded/imported items.
 - `responses.py` contains human-reviewable warning templates.
@@ -37,6 +38,7 @@ See [DESIGN.md](DESIGN.md) for the proposed architecture and roadmap.
 - Imports bounded n8n/webhook JSON after the provider layer has already fetched mail.
 - Exports approved local audit events as an idempotent JSON bundle for an n8n/provider bridge.
 - Provides an inactive n8n approved-action bridge starter that validates/dedupes actions in dry-run mode.
+- Provides a Phase 14 durable bridge ledger scaffold for recording processed `audit_id` state before provider mutation.
 - Keeps provider credentials and live mailbox side effects outside the local UI and review queue.
 
 ## Safety First
@@ -487,6 +489,23 @@ Artifact:
 
 The plan requires persistent processed-`audit_id` state, rollback and emergency-stop procedures, provider-specific sandbox/manual tests, and Rex/Gus review before any live mutation node is connected.
 
+## Phase 14 Durable Bridge Ledger Scaffold
+
+Phase 14 adds a durable bridge ledger scaffold for future reviewed provider bridges. It is not OAuth, not provider auth, and not live mailbox automation. The scaffold records approved-action `audit_id` state before provider mutation so a future bridge can fail closed on duplicates.
+
+Artifacts:
+
+- [`botfucker/bridge_ledger.py`](botfucker/bridge_ledger.py) — standard-library SQLite ledger keyed by `audit_id`, with `pending`, `processed`, `failed`, and `rolled_back` states.
+- [`docs/bridge-ledger-scaffold.md`](docs/bridge-ledger-scaffold.md) — operator/security notes for using the ledger before any provider mutation.
+
+Safety constraints:
+
+- effect scope is `bridge_ledger_state_only`
+- validates `botfucker.approved_actions.v1`, `provider_action_export_only`, and `provider_execution: not_performed`
+- stores IDs/status only, not subject, snippet, body, headers, OAuth tokens, API keys, passwords, cookies, or private provider headers
+- no OAuth, no provider credentials, and no live provider mutation nodes are added
+- checked-in n8n workflows remain inactive/dry-run starters
+
 ## Test Before Going Live
 
 Compile-check the script and package:

ROADMAP.md

@@ -28,7 +28,9 @@ Merged through PR #8:
 - provider auth boundary plan
 - FF2K-branded local browser UI and hero art
 - HyperFrames animated/narrated product explainer under `promo/botfucker-animated-explainer/`
-- tests for classifier/history/safety/review/webhook/docs/branding behavior
+- reviewed live-bridge promotion gate
+- durable bridge ledger scaffold for processed `audit_id` state before provider mutation
+- tests for classifier/history/safety/review/webhook/docs/branding/bridge-ledger behavior
 
 The repo is ready to pull locally into Kodex/Codex and demonstrate the local cockpit without connecting to any live mail provider.
 
@@ -317,6 +319,28 @@ Acceptance criteria:
 - No live provider credentials are committed or exported.
 - No OAuth, live provider mutation nodes, or provider behavior changes are added by this phase.
 
+### Phase 14 — Durable Bridge Ledger Scaffold ✅
+
+Status: implemented on `phase-14-durable-bridge-ledger`.
+
+Goal: provide a durable processed-`audit_id` ledger scaffold that a future reviewed bridge can use before any provider mutation, without adding OAuth, credentials, or live mutation nodes.
+
+Delivered:
+
+- `botfucker.bridge_ledger.DurableBridgeLedger` SQLite scaffold keyed by `audit_id`
+- `pending`, `processed`, `failed`, and `rolled_back` statuses
+- `claim_action()` flow that inserts durable `pending` state before provider mutation
+- validation for `botfucker.approved_actions.v1`, `provider_action_export_only`, and `provider_execution: not_performed`
+- docs in `docs/bridge-ledger-scaffold.md`
+- tests proving dedupe, status transitions, unsafe export rejection, and no message-content/secret columns
+
+Acceptance criteria:
+
+- Durable state is keyed by `audit_id`.
+- Repeated claims of an `audit_id` do not acquire a second mutation slot.
+- Ledger stores IDs/status only, not message body/header/credential material.
+- No OAuth, no provider credentials, no live provider mutation nodes, and no checked-in n8n activation changes are added.
+
 ## Local Kodex/Codex Demo Plan
 
 Kent is pulling this locally onto Kodex/Codex next. The demo should show what exists now, not pretend Phase 8 is already done. Revolutionary concept, apparently.
@@ -363,27 +387,27 @@ Use fake or sanitized JSON only. Real mailbox payloads stay out of the repo.
 
 ## Near-Term Recommendation
 
-After Phase 13 is reviewed and merged, the next PR should be **Phase 14: durable bridge ledger design or sandbox-only live bridge scaffold**, not broad OAuth implementation.
+After Phase 14 is reviewed and merged, the next PR should be **Phase 15: emergency-stop proof or sandbox-only bridge rehearsal**, not broad OAuth implementation.
 
 Recommended scope:
 
-- choose one provider/action pair only
-- implement or document the durable processed-`audit_id` ledger before any provider mutation
+- keep one provider/action pair only (`approve_warning`)
+- use the durable bridge ledger before any provider mutation
 - keep credentials in n8n only
 - keep dry-run as the default path
 - prove emergency stop exits before provider mutation
 - require provider-specific sandbox/manual tests
 - require Rex/Gus security/ops review before any live mutation node is connected
 
-OAuth can still wait. We proved the n8n package imports and dry-runs in the real beast, and Phase 13 defines the promotion gate. Next is one tiny, reviewed step toward a provider bridge — not a live-mail fireworks show.
+OAuth can still wait. Phase 14 gives the bridge a seatbelt: durable dedupe before action. Next is proving the brakes, not flooring it into a live inbox.
 
-### Restart checklist after Phase 13
+### Restart checklist after Phase 14
 
-1. Re-check Phase 13 PR CI and mergeability.
-2. Squash-merge Phase 13 into `main` if still green.
-3. Pull updated `main` and create a Phase 14 branch.
-4. Pick exactly one sandbox provider/action pair, likely `approve_warning` only if Kent explicitly wants reply-send tested.
-5. Build durable dedupe/ledger scaffolding and emergency-stop proof before wiring any provider mutation.
+1. Re-check Phase 14 branch CI and mergeability.
+2. Squash-merge Phase 14 into `main` if still green.
+3. Pull updated `main` and create a Phase 15 branch.
+4. Keep exactly one sandbox provider/action pair, likely `approve_warning` only if Kent explicitly wants reply-send tested.
+5. Prove emergency-stop and dry-run behavior against the durable ledger before wiring any provider mutation.
 
 ## Team Utilization