api: settle semantic persistence API decisions

[gaelic-ghost]

Summary

• keep Core Data persistence lanes on XCTest and document why
• defer CoreDataVectorIndex.search optimization until real corpus scale earns it
• make deterministic in-memory defaults synchronous and non-throwing
• update README, maintainer docs, roadmap, and v0.2.0 release notes

Verification

• swift package dump-package
• swift test --filter 'KnowledgeBase|SwiftlyFetchLibrary'
• scripts/repo-maintenance/validate-all.sh

Summary by CodeRabbit

• Breaking Changes

  • hashingDefault() and default() now return immediately and no longer require try await.
  • Update call sites to remove async/throwing handling for these constructors.

• Documentation

  • Clarified which constructors are synchronous vs. async/throwing.
  • Added guidance on keeping Core Data-backed tests on XCTest and retaining the current search approach for now.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: d1f2f112-726c-4cb7-9ba1-f2311132d14c

📥 Commits

Reviewing files that changed from the base of the PR and between 82bff72 and ead4ca1.

📒 Files selected for processing (12)

• README.md
• ROADMAP.md
• Sources/RAGKit/KnowledgeBase+NaturalLanguage.swift
• Sources/SwiftlyFetch/SwiftlyFetchLibrary.swift
• Tests/FetchKitTests/CoreDataFetchDocumentStoreTests.swift
• Tests/RAGKitTests/CoreDataVectorIndexTests.swift
• Tests/RAGKitTests/KnowledgeBaseTests.swift
• Tests/SwiftlyFetchTests/SwiftlyFetchLibraryTests.swift
• docs/maintainers/hybrid-search-persistence-plan.md
• docs/maintainers/retrieval-package-plan.md
• docs/maintainers/swiftlyfetch-facade-plan.md
• docs/releases/v0.2.0.md

---

📝 Walkthrough

Walkthrough

KnowledgeBase.hashingDefault() and SwiftlyFetchLibrary.default() are converted from async throws factories to synchronous non-throwing factories. All test call sites remove try/await accordingly. README examples, maintainer docs, ROADMAP milestone tickets, and v0.2.0 release notes are updated to reflect the new API contract.

Changes

Sync/Non-throwing Factory Promotion

Layer / File(s)	Summary
Factory signature changes Sources/RAGKit/KnowledgeBase+NaturalLanguage.swift, Sources/SwiftlyFetch/SwiftlyFetchLibrary.swift	hashingDefault(dimension:) and SwiftlyFetchLibrary.default() signatures drop async throws; implementations remove try await from construction.
Test call-site updates and XCTest rationale Tests/RAGKitTests/KnowledgeBaseTests.swift, Tests/SwiftlyFetchTests/SwiftlyFetchLibraryTests.swift, Tests/RAGKitTests/CoreDataVectorIndexTests.swift, Tests/FetchKitTests/CoreDataFetchDocumentStoreTests.swift	try await removed from all hashingDefault() and SwiftlyFetchLibrary.default() call sites across four test files; explanatory comments added to Core Data XCTest files.
Docs, README, ROADMAP, and release notes README.md, ROADMAP.md, docs/releases/v0.2.0.md, docs/maintainers/hybrid-search-persistence-plan.md, docs/maintainers/retrieval-package-plan.md, docs/maintainers/swiftlyfetch-facade-plan.md	Code examples updated to synchronous form; "Current defaults" bullets clarify sync vs throwing semantics; three ROADMAP Milestone 5 tickets marked complete; v0.2.0 release notes add breaking-change and migration guidance.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• gaelic-ghost/SwiftlyFetch#20: Modifies ROADMAP.md around the same constructor-semantics decisions, specifically documenting KnowledgeBase.hashingDefault(dimension:) and Core Data vector-index review items in Milestone 5.

Suggested labels

docs

🐇 No more try await to fret,
The defaults just sync — no sweat!
hashingDefault leaps in-line,
SwiftlyFetch falls in line fine,
A simpler call, the best yet! 🎉

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title is concise and accurately reflects the PR’s main theme of finalizing semantic persistence API decisions.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/milestone-5-decisions

---

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.}