fix(proof): bound filtered mailbox preflights

[bizzybee90]

Purpose

Repair the fail-closed product-proof policy mismatch exposed by governed staging proof run 31439834363: tenant-A needs-action desktop emitted a second exact mailbox-current-inbound-options preflight while its already-required base request contract is exactly two occurrences.

Included scope

• Add one frozen primitive contract for the exact tenant-A needs-action and unread mailbox-current inbound request identity.
• Permit at most two exact matching OPTIONS lifecycles on those two routes only.
• Independently re-prove the dynamic workspace-bound request identity in the policy compiler and live recorder.
• Bind repeatable preflight debt to fully completed matching dual-adapter base requests.
• Add exact lifecycle, route, alternate-workspace, occurrence-cap, debt, route-wide one-shot, counter and redaction tests.

Explicit exclusions

• No generic CORS or OPTIONS cardinality propagation.
• No change to request acceptance, base minimums/maximums, timeouts, global limits, diagnostics, evidence schema, app behavior, authentication, database, credentials, provider configuration, staging data, or production.
• sent and every unrelated route remain one-shot unless covered by an existing separately reviewed exact contract.

Architecture placement

Current owner / directory: existing product-proof network compiler and live evidence recorder under scripts/.

Dependencies and duplicate-system check: extends the existing frozen-contract, exact matcher, browser-managed preflight and completion-debt mechanisms; no new subsystem or dependency.

Security and tenancy impact

• Authentication / authorization: no auth or grant change; proof request classification only.
• Tenant isolation: exact tenant-A context plus dynamic expected-workspace RPC body; alternate, wrong-route and cross-pair identities fail closed.
• Service-role impact: none.
• Provider / webhook impact: none.
• Secrets impact: none; fixed diagnostics and redaction tests retain no raw URL, headers, body, IDs, workspace values or credentials.

Data impact

• Schema / migration / RLS / grant impact: none.
• Backfill, retention, or rollback: none; one-commit code rollback restores the prior fail-closed proof blocker.

Verification

• Behavioural tests: proof-first reproduction failed exact OPTIONS cardinality 1 !== 2; repaired network+live focused suites 324/324; broader cloud+network+live 514/514; full Vitest 871/871; exact debt, completed/in-flight cap, alternate-workspace, route-wide one-shot and redaction cases.
• CI / security review: full ESLint with zero warnings, TypeScript, four source/test syntax checks and git diff --check pass; local security review reports zero findings. Fresh hosted exact-head gates and CodeRabbit approval are mandatory.

Release safety

• Deployment scope: proof-harness source only; private no-index preview after protected exact-head merge.
• Monitoring / stop conditions: stop on any hosted gate or review failure, any head/base drift, third occurrence, changed identity/diagnostic, cleanup/postflight/recovery failure, evidence writer/readback failure, or any new governed-proof blocker.
• Rollback or containment: revert commit 67a3afb4; predecessor exact main 4f7534ad533f46e3d9593fa02b4e2144a10bdfad, preview manifest c2700cefa1e572911e2709b1cea39f3ac123840421a3ff41577d7ccfd9275a73.

Documentation and generated files

• Docs / diagrams / ADR updates: none; no architecture, schema, workflow or release-gate change.
• Generated-file or lockfile justification: none.

Completion check

• Starts from current origin/main.
• No valuable work remains only in a dirty worktree, stash, or local-only branch.
• Source branch will be retired under the branch policy after merge.
• Any PR-size or branch-retention exception is documented below, or neither applies.

Policy exceptions (leave blank when none apply)

PR-size exception rationale:

Retained branch reason / owner / review date / maximum retention date:

Exact evidence

• Governed proof 31439834363 on exact 4f7534ad533f46e3d9593fa02b4e2144a10bdfad failed only at tenant-A needs-action desktop with fixed diagnostic live_browser_managed_preflight_invalid / cdp / request / mailbox-current-inbound-options / policy_occurrence_exhausted.
• Receipt/source/immutable asset binding, protected tenant-A login, aggregate preflight and tenant-B provisioning passed before browser execution.
• Exact cleanup, aggregate postflight and independent recovery passed; writer/reader were skipped and no failed evidence was published.
• The unchanged source was first proven to generate an exact base pair with OPTIONS max 1; this change raises only the exact reviewed pair to max 2 and keeps the existing completion-debt relation.

Summary by CodeRabbit

• New Features

  • Added support for filtered mailbox inbound activity on the Needs action and Unread routes.
  • Network and evidence tracking now recognize filtered mailbox requests, including their associated preflight activity.
  • Filtered mailbox activity is included in workload completion and validation across desktop and mobile views.

• Bug Fixes

  • Improved handling of repeatable preflight requests while preventing excess duplicate requests.
  • Preserved workspace identity and route-specific behavior for filtered mailbox activity.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 4290384f-4d34-45b5-9e92-f738f024348b

📥 Commits

Reviewing files that changed from the base of the PR and between 4f7534a and 67a3afb.

📒 Files selected for processing (4)

• scripts/product-proof-live-evidence.mjs
• scripts/product-proof-live-evidence.test.mjs
• scripts/product-proof-network-policy.mjs
• scripts/product-proof-network-policy.test.mjs

---

📝 Walkthrough

Walkthrough

The product-proof system now supports a filtered mailbox current-inbound contract for needs-action and unread routes. Policy validation, canonical request recognition, bounded preflight handling, completion tracking, and lifecycle tests were added.

Changes

Filtered mailbox inbound contract

Layer / File(s)	Summary
Filtered mailbox contract and policy validation scripts/product-proof-network-policy.mjs, scripts/product-proof-network-policy.test.mjs	The network policy defines and validates filtered mailbox requests, applies route-specific occurrence limits, labels preflights, and tests workspace binding and sent behavior.
Live evidence recognition and lifecycle coverage scripts/product-proof-live-evidence.mjs, scripts/product-proof-live-evidence.test.mjs	The recorder recognizes canonical filtered mailbox requests, tracks bounded managed preflights, counts completed requests, and tests routes, viewports, completion debt, and alternate workspaces.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant FilteredMailboxRoute
  participant RequestCollector
  participant LiveEvidenceRecorder
  FilteredMailboxRoute->>RequestCollector: Send needs-action or unread inbound request
  RequestCollector->>LiveEvidenceRecorder: Provide validated canonical request
  LiveEvidenceRecorder->>LiveEvidenceRecorder: Track bounded preflight and completion

Loading

Possibly related PRs

• bizzybee90/bizzybee-app#475: Extends the same mailbox inbound contract and preflight handling from /inbox to filtered routes.
• bizzybee90/bizzybee-app#461: Introduces related repeatable-preflight and completion-tracking mechanisms.
• bizzybee90/bizzybee-app#380: Establishes the broader product-proof evidence and network-recorder framework.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the change that bounds filtered mailbox preflights.
Description check	✅ Passed	The description covers the required sections, scope, security, data, verification, release safety, and completion status.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/fix-product-proof-mailbox-current-inbound-needs-action-preflight-20260810

---

_{Comment @coderabbitai help to get the list of available commands.}