Retain external facts and harden protocol delivery recovery

[patrickleet]

Summary

This extends the existing protocol-manifest cache and live-stream recovery work with authenticated external facts. An external ledger or webhook can now retain its own source identity and position without pretending to be an event-sourced aggregate.

• Cache immutable selected protocol manifests per export; authorization, actor scopes, issuance and visibility remain per request.
• Recover a live receiver blocked by a retired page owner without accepting stale frames or weakening active-owner fences.
• Classify application reload admission as retryable retain-and-stop, preserving the delivery for bounded host retry.
• Add explicit external occurrence provenance and source-ordered snapshots, preserving existing aggregate APIs and wire behavior.
• Preserve permanent content fingerprints while accepting identical logical messages at new broker positions. Advance the delivery checkpoint without repeating projection effects; conflicting content and cursor substitution still fail closed.
• Share strict live/archive identity and kind validation. Malformed reserved headers remain visible permanent failures without automatic acknowledgement.
• Rebuild source snapshots with origin-distinct identities: sparse external positions and multi-member facts no longer collide at empty aggregate fields.
• Keep public-archive aggregate-prefix validation fail-closed. Explicit bounded original-log coverage can qualify authored private records without publishing them, with declared head, exact public fingerprints and single-publication contract checks.

Compatibility and migration

Migration 0009 adds delivery aliases while preserving the canonical unique message binding. A replay into a new projection generation still applies the event once. External facts participate in durable transport archival and replay; source position and broker delivery position remain distinct.

No global authority cache, new inbox subsystem, cursor reset, forced poison acknowledgement, or application polling workaround is introduced. See docs/external-facts.md, docs/protocol-manifest-reuse.md, and docs/live-retired-owner-handoff.md.

Original-log coverage is an offline operator/source-adapter trust boundary, not authentication of arbitrary private payloads. Retain and review original export provenance/digests; missing public occurrences, changed identity/content, unknown private contracts and truncated streams remain errors. No generic one-to-many publication completeness is inferred.

Validation

• Framework library with GraphQL, SQLite, NATS and PostgreSQL: 1,061 passed, 0 failed, 3 explicitly ignored.
• Final real NATS transport suite: 12 passed, including malformed live/archive identity, duplicate headers, kind validation and fail-closed settlement.
• Real PostgreSQL protocol conformance and concurrent delivery-identity/cursor race tests passed.
• Memory/SQLite new-generation and duplicate-delivery regressions passed.
• JavaScript: 403 tests passed; TypeScript/generated-contract checks passed.
• Existing HTTP GraphQL protocol, identity and causal transport coverage: 43 passed.
• Focused offline rebuild regressions: 5 passed (memory/SQLite, external and original private-log coverage); separately configured real PostgreSQL rebuild passed. Existing CLI lifecycle suite passed 20 repeated runs (240 tests); added caller-location diagnostics for a non-reproduced CI fixture wait timeout without changing its semantics.
• Changed Rust formatting and git diff --check passed.

Earlier application measurements demonstrated authenticated-query latency declining from roughly 1.1 seconds to 14–22 milliseconds after manifest reuse; these observations are not SLA assertions. Application-wide migration and end-to-end adoption are outside this framework PR's completion claim.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: 598748a8-9f75-47d7-83d0-e71ce23c03fd

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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