Repository navigation
feat: add Bridge v2 reliability foundation - #2
Merged
Merged
Conversation
camaragon
force-pushed
the
feat/bridge-v2-reliability
branch
from
July 26, 2026 03:24
87a8d45 to
15ee36c
Compare
There was a problem hiding this comment.
Pull request overview
This PR introduces the Bridge v2 reliability foundation: versioned canonical handoff records plus durable lifecycle events (outbox) with idempotent creation and optimistic concurrency, while retaining backward-compatible queue views and notify behavior.
Changes:
- Add v2 record + event contracts (schema/revision/correlation metadata) with idempotent create and optimistic lifecycle updates.
- Implement crash-safe filesystem persistence, reconciliation/diagnostics, and durable outbox retry/dead-letter/replay behavior.
- Extend API/CLI/wrappers/patrol and add targeted regression coverage + documentation for migration/deployment/rollback.
Reviewed changes
Copilot reviewed 23 out of 23 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| tests/test_bridge_wrappers.py | Validates wrapper passthrough of idempotency key to API/CLI and returned payload fields. |
| tests/test_bridge_v2_reliability.py | Adds regression coverage for concurrency, idempotency conflicts, crash recovery, outbox retry/replay, auth roles, and v1→v2 transition. |
| tests/test_bridge_patrol.py | Extends patrol tests to cover v2 drift detection (mirrors/outbox/idempotency). |
| tests/test_bridge_intake_watch.py | Adds regression test for ignoring client disconnects during notify JSON responses. |
| tests/test_bridge_api.py | Adds API coverage for idempotency conflicts (409), stale If-Match revisions (409), and role-based authorization (403/200). |
| scripts/bridge_wrapper_common.py | Surfaces revision fields in wrapper JSON results. |
| scripts/bridge_rotate_tokens.py | Ensures scripts can import repo modules when run from different working directories. |
| scripts/bridge_patrol.py | Adds v2 repository diagnostics to patrol output and a configurable outbox pending threshold. |
| scripts/bridge_intake_watch.py | Suppresses noisy BrokenPipe/connection reset errors when writing notify responses. |
| scripts/bridge_cli.py | Adds idempotency/correlation/causation inputs, optimistic revision support, and outbox + reconcile + recovery subcommands. |
| scripts/bridge_api_server.py | Adds idempotency + If-Match/expected_revision support, cancel endpoint, durable outbox-driven notify delivery, and transaction recovery on startup. |
| scripts/bridge_agent.py | Extends agent wrapper CLI to support idempotency/correlation/causation, cancel, and expected-revision. |
| README.md | Updates high-level behavior/quickstart/API docs for v2 reliability semantics and new commands. |
| pyproject.toml | Declares setuptools packaging for bridge_core. |
| docs/README.md | Links new v2 reliability documentation. |
| docs/bridge-v2-reliability.md | Adds detailed v2 reliability design, contracts, operational procedures, and risks. |
| docs/architecture.md | Updates architecture/data-flow narrative to reflect canonical records + durable outbox + compatibility notify. |
| bridge_core/service.py | Implements service-layer idempotent create, optimistic lifecycle updates, and outbox processing helpers. |
| bridge_core/repository.py | Extends repository interface for locks, idempotency, and outbox event operations. |
| bridge_core/policy.py | Adds cancel transitions and lifecycle role authorization matrix enforcement. |
| bridge_core/models.py | Adds schema versioning, revisions, correlation metadata, and canonical request hashing. |
| bridge_core/file_repository.py | Implements crash-safe canonical storage, idempotency index, locks, outbox/transactions, reconciliation, diagnostics, and recovery. |
| bridge_core/events.py | Introduces the durable lifecycle event envelope and due/backoff scheduling helpers. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Review follow-ups
deliveredordead_letterstateDelivery semantics
At-least-once delivery with stable event IDs and idempotent consumer processing; this does not claim exactly-once delivery. Bridge core remains independent of Hermes and Kanban.
Verification
.venv/bin/python -m pytest -q— 86 passed.venv/bin/python -m py_compile bridge_core/*.py scripts/*.pygit diff --checkand staged added-line credential scan passedpytestcheck passedDeployment
No live Bridge root, config, token, systemd service, or deployment glue was changed. Deployment remains separately approval-gated.