feat(core): persist the record catalog and commit catalog changes through the root (#445) - #946
Conversation
…ough the root (#445) Gate 3 slice 3C part 3c-2a: catalog pages are stored under the root directory, sealed under the root key route, with a page's generation equal to the root generation that publishes it. load_catalog and list_records trust only pages that hash to the committed root's catalog and marker set digests; commit_catalog_change applies descriptor changes, relocates leftover pages of an uncommitted change, writes the affected shard pages (an emptied shard keeps a zero-descriptor page) and commits the next root through commit_root.
🤖 CodeAnt AI — Review Status
|
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
@codex review |
Thanks for using CodeAnt! 🎉We're free for open-source projects. if you're enjoying it, help us grow by sharing. Share on X · |
Reviewer's GuideAdds headless persistence for the record catalog: catalog pages are durably sealed under the root authority, verified against the committed root’s catalog and marker digests, and changed through an atomic catalog-plus-root commit flow with interrupted writes quarantined. Empty-shard semantics, contract/status documentation, and cross-platform recovery tests are included; production authority and record write integration remain out of scope. Sequence diagram for root-verified catalog loadingsequenceDiagram
participant Caller
participant load_catalog
participant load_committed_root
participant CatalogPages
participant verify_catalog
Caller->>load_catalog: load_catalog()
load_catalog->>load_committed_root: load_committed_root()
load_committed_root-->>load_catalog: committed root
load_catalog->>CatalogPages: scan_catalog()
CatalogPages-->>load_catalog: newest page at or below root_generation
load_catalog->>CatalogPages: open_page()
CatalogPages-->>load_catalog: verified catalog pages
load_catalog->>verify_catalog: verify_catalog(root, pages)
alt digests match
verify_catalog-->>load_catalog: verified catalog
load_catalog-->>Caller: LoadedCatalog
else page or marker mismatch
verify_catalog-->>load_catalog: RECOVERY_REQUIRED
load_catalog-->>Caller: AuthorityError
end
Sequence diagram for catalog change and root commitsequenceDiagram
participant Caller
participant commit_catalog_change
participant load_catalog
participant CatalogPages
participant DurableFs
participant commit_root
Caller->>commit_catalog_change: commit_catalog_change(change, commit)
commit_catalog_change->>load_catalog: load_catalog()
load_catalog-->>commit_catalog_change: current catalog
commit_catalog_change->>CatalogPages: apply_change()
alt invalid or duplicate change
CatalogPages-->>commit_catalog_change: refusal
commit_catalog_change-->>Caller: AuthorityError
else valid change
commit_catalog_change->>CatalogPages: scan_catalog()
CatalogPages-->>commit_catalog_change: interrupted pages
commit_catalog_change->>DurableFs: relocate(leftover pages)
commit_catalog_change->>DurableFs: stage_and_promote(page)
DurableFs-->>commit_catalog_change: promoted pages
commit_catalog_change->>commit_root: commit_root(new catalog and marker digests)
commit_root-->>commit_catalog_change: RootCommitted
commit_catalog_change-->>Caller: RootCommitted
end
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
 |
|
Overall Grade |
Security Reliability Complexity Hygiene |
Code Review Summary
| Analyzer | Status | Updated (UTC) | Details |
|---|---|---|---|
| Docker |  |
Oct 2, 2026 5:07a.m. | Review ↗ |
| Python | |
Oct 2, 2026 5:07a.m. | Review ↗ |
| Rust | |
Oct 2, 2026 5:07a.m. | Review ↗ |
| Shell | |
Oct 2, 2026 5:07a.m. | Review ↗ |
Important
AI Review is run only on demand for your team. We're only showing results of static analysis review right now. To trigger AI Review, comment @deepsourcebot review on this thread.
codeant-ai
Bot
added
the
size:XXL
🏁 CodeAnt Quality Gate ResultsCommit: ✅ Overall Status: PASSEDQuality Gate Details
|
![codescene-access[bot]](https://avatars.githubusercontent.com/in/3755875?s=60&v=4){kind=small}
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
|
[check-pr-size] PR size is over the hard tier (normal profile): 12 files, 1325 meaningful lines, 4 commits — limit ≤20 files / ≤1200 lines / ≤10 commits. Consider splitting into smaller, independently reviewable PRs. |
|
Navigate logical layers of code changes, visualize relationships, and explore their blast radius. Warning Review limit reachedEnable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. Next included review available in 29 minutes. View limit detailsLimit details: You’ve used the included review currently available. Your 82 included PR review attempts over the past 7 days set your current allowance at 1 review per hour. Review configuration: ⚙️ Run configurationConfiguration used: Repository: qnbs/WorldScript-Studio/.coderabbit.yaml Review profile: CHILL Plan: Essentials Run ID: 📒 Files selected for processing (8)
📝 WalkthroughWalkthroughThe secure-storage crate adds persisted record-catalog loading, listing, and commit operations tied to the committed root. Catalog pages and marker digests are verified. Empty shard pages are supported, and tests cover catalog changes and recovery cases. ChangesRecord Catalog Authority
Priority: ➖ Normal Merge Risk: 🔵 Low · up to Catalog loading still needs to report a missing committed page as requiring recovery. This narrow error-handling gap should be fixed, but does not otherwise block the headless catalog workflow.
Comment |
![codeant-ai[bot]](https://avatars.githubusercontent.com/in/646884?s=60&v=4){kind=small}
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository: qnbs/WorldScript-Studio/.coderabbit.yaml
Review profile: CHILL
Plan: Essentials
Run ID: 2155d4cd-e964-4450-8df5-e3f7c412962a
📒 Files selected for processing (11)
.github/workflows/ci.ymlCHANGELOG.mdcrates/worldscript-secure-storage/src/authority.rscrates/worldscript-secure-storage/src/catalog.rscrates/worldscript-secure-storage/src/lib.rscrates/worldscript-secure-storage/src/root.rscrates/worldscript-secure-storage/src/root_store.rscrates/worldscript-secure-storage/tests/gate3c_authority_test.rscrates/worldscript-secure-storage/tests/gate3c_catalog_test.rsdocs/native/CORE-MIGRATION-LEDGER.mddocs/native/R15-SECURE-STORAGE-CONTRACT.md
Included review availability: This review used your included allowance. 0 included reviews remain after this review. Your included PR review attempts over the past 7 days set your current allowance at 1 review per hour.
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
All reported issues were addressed across 11 files
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
…mmitted root's epoch (#445) Review wave on #946: commit_catalog_change checks the operation ID and the active epoch's binding before relocating leftovers or writing a page; load_catalog opens pages under the scope and route from the same anchor read that selected the root, refuses a page under another key epoch, and treats a missing committed page or a file named as a shard as RECOVERY_REQUIRED. The commit inputs move into CatalogCommit, the catalog codec tests also run on macOS and Windows, and the contract status enumerations name part 3c-2a.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
|
@CodeAnt-AI review |
|
@codex review |
CodeAnt NitpicksNo threshold-suppressed suggestions found in the latest review. |
There was a problem hiding this comment.
All reported issues were addressed across 7 files (changes from recent commits).
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
#445) Pages a change does not touch stay sealed under the committed epoch, so commit_catalog_change now refuses a different route or active_key_epoch (KeyRotationNotAdmitted); a rotation that rewrites every page is Gate 5. CatalogPage::new refuses an oversized input before sorting, and the contract states the one-writer assumption until Gate 4.
|
@CodeAnt-AI review |
There was a problem hiding this comment.
Gates Passed
See analysis details in CodeScene
Quality Gate Profile: The Bare Minimum
Install CodeScene MCP: safeguard and uplift AI-generated code. Catch issues early with our IDE extension and CLI tool.
1 participant
User description
Part of #445 / #921 (Gate 3, slice 3C, part 3c-2a). No production authority switch:
PRODUCTION_AUTHORITY_SWITCH_ALLOWED = NO.What lands (
authority)<root_dir>/catalog/<shard>/generation-<n>.wsr1.active_key_epoch, as control records of the root.catalog_generationis theroot_generationof the root that publishes it. This is the one stated exception to the consecutive-counter rule, now written into contract §5.5.1. It is what tells a leftover page from an interrupted change (newer than the committed root) apart from a committed page.load_catalog/list_recordscatalog_set_digest, and their descriptors' markers must hash to itsmarker_set_digest(via the newMarkerSetEntry::from_descriptor).RECOVERY_REQUIRED.commit_catalog_changecommit_root.catalog_set_digest. An absent shard could not be told apart from a replayed older page.0..=MAXdescriptors, and contract §5.5.1 is amended to match.CatalogDescriptor::new_unverified), which failedcargo docwith-D warnings.Proof
tests/gate3c_authority_test.rshas 12 tests, and they run on all three OS runners. They cover:Locally, clippy is clean, the full crate suite passes,
cargo docwith-D warningspasses, andpnpm docs:checkpasses.Docs
R15_GATE3=SLICE_3C_CATALOG_COMMITis set in the block and in ledger row 10. The CHANGELOG is updated.Known open item, tracked
A key-epoch record whose root never commits is still read as its epoch's newest generation. This fails closed with
RECOVERY_REQUIRED. Resolving that crash window belongs to the Gate 4 journal that admits key-epoch changes, as recorded in §20.Next: 3c-2b, which wires
commit_writethrough catalog and root commits at each marker transition (dropping a rolled-back first write), plus retention. Then Gate 3 closure with #357 and the asset-pair boundary.Summary by Sourcery
Persist and root-verify the record catalog so catalog changes become authoritative only through committed roots.
New Features:
Bug Fixes:
Enhancements:
CI:
Documentation:
Tests:
Chores:
Summary by cubic
Persists the record catalog under the authority root and commits catalog changes through the root, so
list_recordsonly returns records from pages the committed root names.commit_catalog_changepreflights the operation ID, the active key epoch's route binding, and refuses a change that would rotate the key route or epoch (KeyRotationNotAdmitted) before relocating leftovers or writing any page; the commit inputs move into aCatalogCommitstruct.load_catalogopens pages under the scope and key route from the same anchor read that selects the root, refuses a page sealed under another key epoch, and treats a missing committed page or a file named as a shard asRECOVERY_REQUIRED.catalog_generationis the root generation that publishes it; pages live at<root_dir>/catalog/<shard>/generation-<n>.wsr1.catalog_set_digestandmarker_set_digest; an emptied shard keeps a zero-descriptor page, and leftover pages of an uncommitted change are relocated, never deleted.CatalogPage::newrefuses an oversized descriptor list before sorting.cargo docwith-D warnings.RECOVERY_REQUIRED; closing that window is tracked for Gate 4. The change assumes one writer until Gate 4'sroot_commit_mutexand exclusive admission. No production authority switch; nothing reads or writes user data through it yet.12 new tests in
tests/gate3c_authority_test.rscover the first commit, unchanged shards, replacement, emptied shards, refused changes, interrupted-change relocation, tampered/replayed/removed pages, pages under another epoch, unexpected entries, preflighted refusals, key-epoch rotation refusal, and marker-set mismatch; they run on all three OS runners. Contract, ledger and CHANGELOG are updated.Written for commit 98e6ca3. Summary will update on new commits.
Summary by CodeRabbit
CodeAnt-AI Description
Persist and verify the protected record catalog through the authority root
What Changed
list_recordsand catalog loading use only pages named by the committed root; tampered, missing, replayed, incorrectly sealed, or unexpected catalog entries require recovery instead of being trusted.Impact
✅ Verified record listings✅ Fewer silent catalog corruption risks✅ Safer recovery after interrupted catalog changes💡 Usage Guide
Checking Your Pull Request
Every time you make a pull request, our system automatically looks through it. We check for security issues, mistakes in how you're setting up your infrastructure, and common code problems. We do this to make sure your changes are solid and won't cause any trouble later.
Talking to CodeAnt AI
Got a question or need a hand with something in your pull request? You can easily get in touch with CodeAnt AI right here. Just type the following in a comment on your pull request, and replace "Your question here" with whatever you want to ask:
This lets you have a chat with CodeAnt AI about your pull request, making it easier to understand and improve your code.
Example
Preserve Org Learnings with CodeAnt
You can record team preferences so CodeAnt AI applies them in future reviews. Reply directly to the specific CodeAnt AI suggestion (in the same thread) and replace "Your feedback here" with your input:
This helps CodeAnt AI learn and adapt to your team's coding style and standards.
Example
Retrigger review
Ask CodeAnt AI to review the PR again, by typing:
Check Your Repository Health
To analyze the health of your code repository, visit our dashboard at https://app.codeant.ai. This tool helps you identify potential issues and areas for improvement in your codebase, ensuring your repository maintains high standards of code health.