[yordis]

• Source updates need explicit identity and ownership boundaries so reconciliation preserves unrelated model intent.
• Retained provenance and complete inventories must distinguish source removal from partial input.
• Exact selectors and recovery evidence must remain inspectable across version, incarnation and publication changes.

[cursor]

PR Summary

Low Risk
Documentation-only change with no production code, APIs, or storage behavior modified.

Overview
Adds proposed reference documentation for Atlas source integration—no runtime, RPC, or storage implementation in this PR.

source-integration-contracts.md defines a native-first boundary for immutable supplied manifest/file bundles (supplied-native-v1 digests), proposed control records (SourceRegistration, SourceSnapshot, SourceOverlay, SourceMapping, ReconciliationRun), exact typed native mappings, field ownership and merge-base rules, partial vs complete inventory semantics, preview/apply lifecycle, and a new backend requirement for coordinated native publication markers plus recovery evidence. Remote connectors, portable migration rebinding, and similar work stay deferred.

source-integration-acceptance.md lists future executable acceptance cases tied to existing native fixtures (Specification, DataProduct, Responsibility, Decision/Document, Ecommerce), covering identity pins, conflicts, branches, budgets, retention, and export/reapply fidelity—with explicit note that documentation does not prove an implemented source runtime.

docs/README.md and architecture-resource-roadmap.md link the new references and clarify that contracts are proposed while source records and reconciliation operations remain unimplemented.

^{Reviewed by Cursor Bugbot for commit 9bae6e0. Bugbot is set up for automated code reviews on this repo. Configure here.}

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Source mode: Auto
• Repository: Unavailable
• Branch: Unavailable
• File: No configuration file from this repository applied
• Commit: Unavailable
• Layers: Organization UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: 7478e4ba-5653-4cba-b688-85a86511db5b

📥 Commits

Reviewing files that changed from the base of the PR and between 2090152 and 9bae6e0.

📒 Files selected for processing: 4

• docs/README.md
• docs/explanation/architecture-resource-roadmap.md
• docs/reference/source-integration-acceptance.md
• docs/reference/source-integration-contracts.md

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

Walkthrough

This documentation-only change adds proposed source integration contracts and acceptance requirements, links them from the reference section, and updates the roadmap. The documents state that source registration, reconciliation, persistence, and executable acceptance are not implemented.

Changes

Source Integration Proposal

Layer / File(s)	Summary
Scope, inputs, and identity docs/reference/source-integration-contracts.md, docs/reference/source-integration-acceptance.md, docs/explanation/architecture-resource-roadmap.md, docs/README.md	The proposal defines supplied bundle inputs, identity and mapping rules, and native authority boundaries. The roadmap describes its scope, and the README adds reference links.
Reconciliation and guarded apply docs/reference/source-integration-contracts.md, docs/reference/source-integration-acceptance.md	The documents specify ownership, inventory, conflict, deletion, preview, and apply requirements, with corresponding proposed acceptance cases.
Publication, recovery, and limits docs/reference/source-integration-contracts.md, docs/reference/source-integration-acceptance.md	The documents define proposed publication and recovery behavior, authorization, operational limits, retention, and related acceptance requirements.
Reapply fidelity and acceptance evidence docs/reference/source-integration-contracts.md, docs/reference/source-integration-acceptance.md	The documents define export and reapply fidelity claims and specify evidence for future executable acceptance. They distinguish the proposal from existing native behavior.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Other

Possibly related PRs

• TrogonStack/atlas#233: Its Decision/Document contract and fixture are cited as native foundations in this PR’s source integration documentation.

Merge Risk: ⚪ Minimal · up to 9bae6

No actionable merge-blocking risk was identified in this documentation-only change.

Pre-merge checks: 5

Check name	Status	Explanation
Title check		The title "chore(docs): keep source synchronization traceable" matches the changeset, which adds proposed source integration contract and acceptance documents. Those documents cover identity, provenan…
Description check		The description lists three goals: explicit identity and ownership boundaries for reconciliation, distinguishing source removal from partial input with provenance and complete inventories, and inspect…
Docstring Coverage		No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

Full details: Title check

Explanation

The title "chore(docs): keep source synchronization traceable" matches the changeset, which adds proposed source integration contract and acceptance documents. Those documents cover identity, provenance, inventories, and recovery evidence for source synchronization. The title names the documentation scope, but it does not name the new contract or acceptance documents specifically. It is a specific, descriptive title, so it passes.

Full details: Description check

Explanation

The description lists three goals: explicit identity and ownership boundaries for reconciliation, distinguishing source removal from partial input with provenance and complete inventories, and inspectable exact selectors and recovery evidence across version, incarnation, and publication changes. These goals match the proposed source integration contract and acceptance requirements in the changeset. The description is related to the changes, so it passes.

Full details: Docstring Coverage

Explanation

No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0 files. (4 skipped: 4 unsupported.)

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

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

_{A rabbit reads the contract page,
And marks each source and mapping stage.
“No runtime yet,” the footnotes say,
So nibble docs and hop away.
With bytes and bounds in tidy rows,
The rabbit tucks the links and goes.}

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