If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/JohnEstropia/CoreStore shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Stale — last commit 2y ago

• 5 active contributors
• MIT licensed
• Tests present
• ⚠ Stale — last commit 2y ago
• ⚠ Single-maintainer risk — top contributor 93% of recent commits
• ⚠ No CI workflows detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live JohnEstropia/CoreStore repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/JohnEstropia/CoreStore.

What it runs against: a local clone of JohnEstropia/CoreStore — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in JohnEstropia/CoreStore | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch develop exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 586 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of JohnEstropia/CoreStore. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/JohnEstropia/CoreStore.git
#   cd CoreStore
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of JohnEstropia/CoreStore and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "JohnEstropia/CoreStore(\\.git)?\\b" \\
  && ok "origin remote is JohnEstropia/CoreStore" \\
  || miss "origin remote is not JohnEstropia/CoreStore (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify develop >/dev/null 2>&1 \\
  && ok "default branch develop exists" \\
  || miss "default branch develop no longer exists"

# 4. Critical files exist
test -f "CoreStore.xcodeproj/project.pbxproj" \\
  && ok "CoreStore.xcodeproj/project.pbxproj" \\
  || miss "missing critical file: CoreStore.xcodeproj/project.pbxproj"
test -f "CoreStore.podspec" \\
  && ok "CoreStore.podspec" \\
  || miss "missing critical file: CoreStore.podspec"
test -f ".swiftpm/xcode/package.xcworkspace/contents.xcworkspacedata" \\
  && ok ".swiftpm/xcode/package.xcworkspace/contents.xcworkspacedata" \\
  || miss "missing critical file: .swiftpm/xcode/package.xcworkspace/contents.xcworkspacedata"
test -f "CoreStoreTests/Model.xcdatamodeld/Model.xcdatamodel/contents" \\
  && ok "CoreStoreTests/Model.xcdatamodeld/Model.xcdatamodel/contents" \\
  || miss "missing critical file: CoreStoreTests/Model.xcdatamodeld/Model.xcdatamodel/contents"
test -f "Demo/Sources/Demos/Advanced/EvolutionDemo/Advanced.EvolutionDemo.Migrator.swift" \\
  && ok "Demo/Sources/Demos/Advanced/EvolutionDemo/Advanced.EvolutionDemo.Migrator.swift" \\
  || miss "missing critical file: Demo/Sources/Demos/Advanced/EvolutionDemo/Advanced.EvolutionDemo.Migrator.swift"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 586 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~556d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/JohnEstropia/CoreStore"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

CoreStore is a Swift wrapper around Apple's Core Data framework that provides type-safe, chainable query DSL and reactive observation patterns. It eliminates Core Data's boilerplate and safety issues by offering a modern Swift API for defining, migrating, and querying SQLite-backed entity stores with compile-time validation. Single-package monorepo structure: CoreStore.xcworkspace integrates the main framework with test bundle (CoreStoreTests/). Source code organized by domain (fetch, query, observation, migration, dynamic models). Test data defined in Model.xcdatamodeld/. SwiftPM support via .swiftpm/xcode/package.xcworkspace alongside CocoaPods (CoreStore.podspec) and Carthage.

iOS/macOS/tvOS/watchOS developers building apps with persistent data who want Core Data's power without manual NSFetchRequest construction, thread safety headaches, or runtime crashes from type mismatches.

Production-ready and actively maintained. The repo shows Swift 5.9 support with iOS 16.0+ minimum, multiple build schemes (iOS/macOS/tvOS/watchOS), comprehensive test suite in CoreStoreTests/, CI via Bitrise, and recent commits visible from the repo metadata. CoreStore is part of Swift's official Source Compatibility projects.

Low risk for active projects. Single maintainer (JohnEstropia) is a moderate concern, but the framework is stable with established APIs—breaking changes are infrequent (versioned at major Swift releases like Swift 5.9). Watch for: major Core Data deprecations in new iOS releases since this wraps Apple's framework directly.

Currently targets Swift 5.9 with iOS 16.0+ minimum. Maintains test coverage across FetchTests, QueryTests, ObjectObserverTests, ListPublisherTests, and MigrationChainTests. No visible active PR list in provided data, but commit history indicates steady maintenance and occasional API refinements.

Clone and open in Xcode: git clone https://github.com/JohnEstropia/CoreStore.git && cd CoreStore && open CoreStore.xcworkspace. For SPM integration: add to Package.swift or Xcode's 'Add Package Dependency' pointing to this repo URL. CocoaPods: pod install CoreStore.

Daily commands: Open CoreStore.xcworkspace in Xcode and run schemes: 'CoreStore iOS', 'CoreStore macOS', 'CoreStore tvOS', or 'CoreStore watchOS' (found in CoreStore.xcodeproj/xcshareddata/xcschemes/). Tests: cmd+U in Xcode or xcodebuild test -workspace CoreStore.xcworkspace -scheme 'CoreStore iOS' -destination 'platform=iOS Simulator,name=iPhone 15'.

• CoreStore.xcodeproj/project.pbxproj — Master Xcode project configuration defining build targets, schemes, and dependencies for iOS, tvOS, watchOS, and macOS platforms.
• CoreStore.podspec — CocoaPods specification defining the library's public API, version, dependencies, and platform requirements—essential for understanding versioning and external dependencies.
• .swiftpm/xcode/package.xcworkspace/contents.xcworkspacedata — Swift Package Manager workspace configuration enabling cross-platform support and integration with Xcode's native build system.
• CoreStoreTests/Model.xcdatamodeld/Model.xcdatamodel/contents — Core Data model definition used across all tests; defines the schema for understanding how entities, relationships, and attributes are structured.
• Demo/Sources/Demos/Advanced/EvolutionDemo/Advanced.EvolutionDemo.Migrator.swift — Demonstrates migration patterns and schema evolution—critical for understanding CoreStore's approach to Core Data migrations and versioning.
• Demo/Sources/AppDelegate.swift — Application entry point showing CoreStore initialization, stack setup, and integration with UIKit/SwiftUI lifecycle.
• CoreStoreTests/BaseTestCase.swift — Base test infrastructure providing common setup, teardown, and utility methods; foundation for understanding how to test CoreStore code.

Add a New Core Data Entity

1. Open the Core Data model editor at CoreStoreTests/Model.xcdatamodeld/Model.xcdatamodel/contents and add a new entity with attributes (CoreStoreTests/Model.xcdatamodeld/Model.xcdatamodel/contents)
2. Create a Swift class conforming to NSManagedObject in CoreStoreTests/ directory (e.g., TestEntity3.swift) with @NSManaged properties matching the model (CoreStoreTests/TestEntity1.swift)
3. Add unit test in CoreStoreTests/ to verify entity creation, persistence, and fetching behavior (CoreStoreTests/FetchTests.swift)
4. If adding to demo, create a new EvolutionDemo version file and migration mapping model to handle schema evolution (Demo/Sources/Demos/Advanced/EvolutionDemo/Advanced.EvolutionDemo.V1.xcdatamodeld)

Implement a Data Migration Chain

1. Add a new xcdatamodel version file to the versioned model directory (e.g., EvolutionDemo.V3.xcdatamodel) (Demo/Sources/Demos/Advanced/EvolutionDemo/Advanced.EvolutionDemo.V1.xcdatamodeld)
2. Create a .xcmappingmodel between consecutive versions defining entity/attribute transformations (Demo/Sources/Demos/Advanced/EvolutionDemo/Advanced.EvolutionDemo.V1.FromV2.xcmappingmodel/xcmapping.xml)
3. Update the Migrator.swift to register the new migration step and define any custom transformation logic (Demo/Sources/Demos/Advanced/EvolutionDemo/Advanced.EvolutionDemo.Migrator.swift)
4. Add migration chain tests to MigrationChainTests.swift verifying data integrity through all versions (CoreStoreTests/MigrationChainTests.swift)

Create Observable Data Source for SwiftUI View

1. Create a new ViewModel/DataSource class in Demo/Sources/Demos/ extending BaseTestDataTestCase to manage transactions and state (Demo/Sources/Demos/Advanced/EvolutionDemo/Advanced.EvolutionDemo.CreaturesDataSource.swift)
2. Use CoreStore's @ObservedRealmResults or ListObserver to bind fetch queries to SwiftUI @State/@Published properties (Demo/Sources/Demos/Advanced/EvolutionDemo/Advanced.EvolutionDemo.CreaturesDataSource.swift)
3. Implement CRUD methods using CoreStore transactions (beginAsynchronous / beginSynchronous) in the DataSource (CoreStoreTests/TransactionTests.swift)
4. Create SwiftUI View files referencing the DataSource and reactively updating when observed data changes (Demo/Sources/Demos/Advanced/EvolutionDemo/Advanced.EvolutionDemo.MainView.swift)

Add Complex Fetch Query with Filtering and Grouping

1. Create a new query test file in CoreStoreTests/ (e.g., CustomQueryTests.swift) or extend QueryTests.swift with your fetch pattern (CoreStoreTests/QueryTests.swift)
2. Use Where clauses for filtering, OrderBy for sorting, and GroupBy for aggregation in your fetch query chain (CoreStoreTests/WhereTests.swift)
3. Verify the fetch returns correct results and test edge cases (empty results, large datasets, complex predicates) (CoreStoreTests/FetchTests.swift)
4. Integrate the query into a DataSource observing results with ListObserver for real-time UI updates (CoreStoreTests/ListObserverTests.swift)

No obvious environment variable requirements visible. Gotchas: (1) Model.xcdatamodeld must be embedded in test bundle and kept in sync—test failures often stem from schema mismatches, not code bugs. (2) Thread safety is enforced by transaction-based API; breaking this pattern via raw NSManagedObject access bypasses CoreStore's safety guarantees. (3) iOS 16.0+ minimum enforces use of modern Core Data features; older device support requires forking to an older Swift version branch (8.0.1 for Swift 5.4, etc.).

• Chainable Query DSL (fluent builder pattern) — CoreStore's signature feature—From/Into/Where/OrderBy/Select/GroupBy chain instead of NSPredicate strings; understanding this fluent pattern is essential to using the library effectively
• Thread-confined persistence contexts (write transactions) — CoreStore enforces transaction-based writes to prevent deadlocks and race conditions; Core Data's default threading model is error-prone and CoreStore's abstraction is the core safety guarantee
• Reactive observation via Combine Publishers — ObjectPublisher and ListPublisher integrate with Swift's async/await and Combine; modern iOS apps expect reactive updates, not manual KVO or notification polling
• Schema versioning and lightweight migrations — CoreStore wraps Core Data's migration chain; understanding xcdatamodeld versioning is critical for shipping app updates without data loss (MigrationChainTests.swift validates this)
• Core Data stack initialization and store coordination — CoreStore abstracts NSPersistentStoreCoordinator, NSManagedObjectContext, and NSPersistentContainer initialization; the 'Setting up' tutorial section suggests this is a primary pain point CoreStore solves
• In-memory vs. persistent (SQLite) stores — CoreStore supports both backends; understanding when to use in-memory (testing, caching) vs. persistent (durable app data) is essential for architecture decisions mentioned in the README's 'Setting up' section

• realm/realm-swift — Alternative ORM with similar type-safe query API and reactive observation; direct competitor for the same use case
• groue/GRDB.swift — Pure Swift SQLite wrapper with query builder DSL; lighter-weight alternative if Core Data overhead is undesired
• firebase/firebase-ios-sdk — Cloud-backed persistence alternative; many apps using CoreStore also integrate Firestore for sync
• apple/swift-data — Apple's modern SwiftData framework (iOS 17+); future replacement for Core Data; CoreStore maintainers may need to bridge or transition users

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive tests for ListPublisher and ObjectPublisher

The repo has ListPublisherTests.swift and ObjectPublisherTests.swift in the test suite, but given CoreStore's emphasis on reactive programming patterns, these publishers likely need more edge-case coverage. With the growing adoption of Combine in Swift, robust publisher tests covering cancellation, backpressure, multiple subscribers, and error propagation would increase confidence in reactive workflows.

• [ ] Review existing ListPublisherTests.swift and ObjectPublisherTests.swift for coverage gaps
• [ ] Add tests for publisher behavior under concurrent access patterns
• [ ] Add tests for cancellation and memory management in publisher subscriptions
• [ ] Add tests for error propagation through publisher chains
• [ ] Add integration tests combining ListPublisher with filtering/sorting operations

Add GitHub Actions workflow for Swift Package Manager (SPM) validation

The repo supports SPM via .swiftpm/xcode/package.xcworkspace but only has Bitrise CI configured (seen in README badge). GitHub Actions is now the standard for open-source Swift projects and would provide faster feedback for PRs without external dependencies. This would catch SPM-specific build issues earlier.

• [ ] Create .github/workflows/spm-build.yml to build with swift build and swift test
• [ ] Test across multiple Swift versions (current stable and one prior version)
• [ ] Include separate build steps for iOS, macOS, tvOS, and watchOS targets
• [ ] Configure workflow to run on push to develop/master and all PRs
• [ ] Add workflow badge to README.md for visibility

Add integration tests for migration chain scenarios in MigrationChainTests.swift

MigrationChainTests.swift exists but migration is one of CoreStore's most complex features. The test file likely needs comprehensive scenarios covering edge cases like version skipping, failed migrations, and rollback behavior. This is critical given Core Data migrations can cause data loss if handled incorrectly.

• [ ] Review current MigrationChainTests.swift and identify missing scenarios
• [ ] Add tests for non-sequential version migrations (skipping intermediate versions)
• [ ] Add tests for migration failure recovery and rollback behavior
• [ ] Add tests for concurrent migration attempts on the same store
• [ ] Add tests for custom migration logic with complex transformations
• [ ] Document migration testing patterns in a MIGRATION_TESTING.md guide

• Add observable Combine Publisher tests for tvOS and watchOS platforms (ListPublisherTests.swift and ObjectPublisherTests.swift exist but may lack platform-specific coverage given the four scheme files)
• Expand ErrorTests.swift with migration failure scenarios—MigrationChainTests.swift exists but error propagation edge cases are prime territory for new contributors
• Add documentation comments to From/Into/Where/OrderBy/Select/GroupBy clause files (inferred from test imports like FromTests.swift, OrderByTests.swift) following Jazzy format (.jazzy.yaml present, suggesting automated docs generation)

The CoreStore codebase demonstrates good security posture overall. It is a well-maintained Swift/iOS framework with proper project structure and no obvious injection risks, hardcoded secrets, or critical vulnerabilities visible in the file structure. Minor concerns include token/ID exposure in public documentation and inability to verify dependencies without manifest files. The project follows standard iOS development practices with proper separation of test and demo code. Recommendations: (1) Remove or rotate any exposed CI/CD tokens, (2) Provide complete dependency manifests for vulnerability scanning, (3) Implement automated security scanning in CI/CD pipeline, (4) Add SECURITY.md with responsible disclosure policy.

• Low · Build Configuration Token Exposure in README — README.md - Build Status badge URL. The README contains a Bitrise build badge with what appears to be a token parameter (token=vhgAmaiF3tWZoQyFLkKM7g) embedded in the badge URL. While this may be a public CI/CD token, embedding tokens in publicly visible documentation is a security anti-pattern. Fix: Verify if this is a public token. If sensitive, remove the token parameter from the badge URL or use a token-less badge endpoint. Implement CI/CD token rotation policies.
• Low · Hardcoded Bitrise App ID — README.md - Build Status badge URL. The Bitrise app ID (e736852157296019) is publicly exposed in the README badge. While app IDs are typically non-sensitive, this enables potential enumeration of the project's CI/CD infrastructure. Fix: Consider using a more generic badge endpoint if possible. Document CI/CD infrastructure separately in a private wiki rather than public README.
• Low · Missing Dependency Manifest Analysis — Package.swift / Podfile / Cartfile (not provided). The provided dependency file content is empty. Unable to assess for known vulnerable package versions, supply chain risks, or insecure dependencies in Package.swift, Podfile, or CocoaPods specifications. Fix: Provide complete dependency manifests. Regularly audit dependencies using tools like: CocoaPods Pod Security Audit, OWASP Dependency-Check, or Snyk. Implement automated dependency scanning in CI/CD pipeline.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.