Skip to content

feat: add Bridge v2 reliability foundation - #2

Merged
camaragon merged 6 commits into
mainfrom
feat/bridge-v2-reliability
Jul 26, 2026
Merged

camaragon merged 6 commits into
mainfrom
feat/bridge-v2-reliability

Conversation

@camaragon

@camaragon camaragon commented Jul 26, 2026 •

Copy link
Copy Markdown
Owner

Summary

  • add versioned handoff and lifecycle-event contracts with optimistic revisions and correlation metadata
  • make creation idempotent and filesystem persistence crash-safe using canonical records, locks, atomic writes, reconciliation, and transaction recovery
  • add durable outbox retry/dead-letter/replay behavior and role-specific lifecycle authorization
  • extend API, CLI, wrappers, patrol diagnostics, migration/deployment/rollback docs, and regression coverage
  • retain the pending broken-pipe suppression fix and its missing regression test

Review follow-ups

  • require exact revision and status agreement before automatic prepared-event recovery
  • process outbox batches without repeatedly rescanning the event directory
  • recognize byte-identical v1 mirrors as unambiguous legacy state and migrate them without false conflict evidence
  • recover a missing idempotency index from canonical state after the canonical-write/index-write crash window
  • provide explicit, audited host-operator resolution for stale prepared transactions while rejecting path traversal, control-character IDs, and payload event-ID substitution
  • refuse destructive discard of a still-recoverable transaction unless the operator supplies an explicit force flag
  • prevent stale concurrent-deliverer failures from regressing delivered or dead_letter state
  • align transaction-ordering documentation with the implementation
  • remove unrecoverable prepared create events when repository conflicts occur
  • update API-triggered delivery from already-loaded events without per-event outbox rescans
  • document the single-deliverer deployment requirement and recipient archival of sender-cancelled handoffs
  • add a minimal GitHub Actions test gate

Delivery 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/*.py
  • git diff --check and staged added-line credential scan passed
  • two read-only Codex review passes completed; all actionable findings were addressed with regression coverage
  • GitHub Actions pytest check passed
  • isolated temporary-directory lifecycle smoke test passed

Deployment

No live Bridge root, config, token, systemd service, or deployment glue was changed. Deployment remains separately approval-gated.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread bridge_core/file_repository.py Resolved
Comment thread bridge_core/service.py Resolved

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 26 out of 26 changed files in this pull request and generated 2 comments.

Comment thread bridge_core/service.py Resolved
Comment thread scripts/bridge_api_server.py Resolved
@camaragon
camaragon merged commit 28adff0 into main Jul 26, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants