feat(storage): complete ordinal reverse identity authority

[DecisionNerd]

Closes #967.

Outcome

• completes the generation-authenticated v4 node_id -> node_uuid/live-state authority introduced through feat(storage): publish and recover v4 ordinal identity construction #977/feat(storage): append and compact v4 ordinal identity runs #978;
• exposes bounded/coalesced lookup and sanitized typed failure evidence for reusable generation-pinned consumers;
• provides an explicit canonical-topology v4 rebuild disposition that never interprets v3 reverse state;
• records storage-owned build, artifact, block, buffer, fsync, and total coexisting scratch evidence;
• documents the generation-handle reuse contract required by fix(exec): make fixed-hop expansion projection-aware #966.

Recovery and scale proof

• subprocess migration matrix covers all eight durable rewrite boundaries;
• pre-recovery inspection authenticates the prior v3 authority, exact installed participant identities, durable journal, and generation-last selection without triggering recovery;
• retry proves journal cleanup, exact receipt/manifest binding, committed auxiliary reconciliation, and authenticated v4 open;
• real 1x/2x/4x rebuilds account both sorted projections, original immutable artifacts, every retained staged copy, and manifest/receipt controls with checked overflow;
• v4 reverse identity suite 23/23, broad v4 suite 20/20, explicit rebuild 2/2, focused crash and scratch regressions green;
• storage library clippy with warnings denied, formatting/diff checks, and public-surface gate 12/12 green.

Boundaries

Projection planning and relationship/node column pruning remain #966. No Fly resources were created.

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}

Summary by CodeRabbit

• New Features
  • Added detailed reporting for v4 ordinal identity rebuilds, including completion status, record counts, write metrics, and temporary storage usage.
  • Added sanitized failure classifications and authentication-failure indicators without exposing sensitive details.
  • Added stronger crash-recovery and publication-state handling during rebuilds.
• Bug Fixes
  • Improved temporary storage accounting with overflow protection and bounded resource usage.
  • Improved authority selection and consistency when rebuilding identity data.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: ae547d88-4c37-4347-b7bf-f5fe17953e80

📥 Commits

Reviewing files that changed from the base of the PR and between 08d980d and 5060a84.

⛔ Files ignored due to path filters (2)

• docs/book/architecture/storage.md is excluded by !**/*.md, !**/docs/**
• docs/book/architecture/uuid-membership-index.md is excluded by !**/*.md, !**/docs/**

📒 Files selected for processing (3)

• crates/graphforge-storage/src/lib.rs
• crates/graphforge-storage/src/ordinal_identity_v4.rs
• crates/graphforge-storage/src/uuid_membership.rs

Included review availability: 1 review is currently available. Your included PR review attempts over the past 7 days set your current allowance at 3 reviews per hour.

---

Walkthrough

The storage crate adds sanitized ordinal failure evidence and a structured v4 rebuild evidence API. Rebuild staging now tracks artifact, write, fsync, buffer, and temporary-space metrics with overflow checks. Tests cover publication recovery, authority selection, and accounting boundaries.

Changes

V4 ordinal observability

Layer / File(s)	Summary
Sanitized failure evidence crates/graphforge-storage/src/ordinal_identity_v4.rs	V4OrdinalIdentityError now exposes a non-sensitive failure kind and authentication-failure count. Tests cover authentication, request-limit, and sanitized debug evidence.
Rebuild evidence and scratch accounting crates/graphforge-storage/src/uuid_membership.rs	V4 rebuild staging now returns disposition, generation, identity and range counts, artifact and write metrics, fsync counts, buffer peaks, and temporary-space metrics. Checked accounting covers projections, artifacts, controls, and scratch release.
Evidence-returning publication flow crates/graphforge-storage/src/uuid_membership.rs, crates/graphforge-storage/src/lib.rs	The evidence-returning rebuild API drives the existing metrics wrapper. Publication stages artifacts and manifests, then validates crash recovery, authority selection, complete and incomplete generations, and overflow failures. New evidence and failure types are publicly re-exported.

Estimated code review effort: 4 (Complex) | ~45 minutes

Merge Risk: ⚪ Minimal · up to 5060a

This change completes the storage identity-authority and rebuild behavior with documented bounds and reported passing validation; no actionable merge-blocking risk remains beyond normal checks and review.

Sequence Diagram(s)

sequenceDiagram
  participant RebuildAPI
  participant StagedV4OrdinalRebuild
  participant V4Manifest
  participant RecoveryAuthority

  RebuildAPI->>StagedV4OrdinalRebuild: stage v4 artifacts and collect scratch metrics
  StagedV4OrdinalRebuild->>V4Manifest: record artifacts and manifest controls
  V4Manifest->>RecoveryAuthority: publish generation
  RecoveryAuthority-->>RebuildAPI: return disposition and rebuild evidence

Loading

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (1 warning, 1 inconclusive)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 22 functions across 3 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.
Linked Issues check	❓ Inconclusive	The reviewable changes align with #967 through authenticated failure evidence, explicit v4 rebuild disposition, canonical topology sourcing, bounded scratch accounting, crash-recovery coverage, and pu…	Review the excluded documentation files or provide their contents to verify the documentation requirements for v4 authority format, migration, recovery invariants, and generation-handle reuse.

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the main change: completing the storage ordinal reverse identity authority.
Description check	✅ Passed	The description identifies issue #967, summarizes the implementation, defines scope boundaries, and reports detailed recovery, scale, and CI validation. It does not reproduce every template checkbox o…
Out of Scope Changes check	✅ Passed	The summarized changes are focused on the generation-authenticated v4 reverse identity authority, rebuild evidence, recovery behavior, bounded storage accounting, and related tests. They match the lin…

Full details: Description check

Explanation

The description identifies issue #967, summarizes the implementation, defines scope boundaries, and reports detailed recovery, scale, and CI validation. It does not reproduce every template checkbox or section, but it provides the critical information needed for review.

Full details: Linked Issues check

Explanation

The reviewable changes align with #967 through authenticated failure evidence, explicit v4 rebuild disposition, canonical topology sourcing, bounded scratch accounting, crash-recovery coverage, and public APIs. The required architecture and UUID-authority documentation cannot be verified because docs/book/architecture/storage.md and docs/book/architecture/uuid-membership-index.md were excluded by !/*.md and !/docs/**.

Full details: Out of Scope Changes check

Explanation

The summarized changes are focused on the generation-authenticated v4 reverse identity authority, rebuild evidence, recovery behavior, bounded storage accounting, and related tests. They match the linked issue and stated boundaries; no unrelated changes are evident.

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/967-ordinal-reverse-identity

Warning

Some tools did not complete. Review the errors below.

🔧 Clippy (1.97.1)

Clippy execution timed out

Warning

Billing warning: we have not been able to collect payment for this subscription for more than 72 hours. Please update the payment method or pay any pending invoices in Billing to avoid service interruption.

---

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

[DecisionNerd]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.