Add snapshot file locking - #2
Conversation
There was a problem hiding this comment.
Pull request overview
Adds cooperative, cross-process snapshot file locking via a .lock sidecar file, and introduces an opt-in require_lock mode to enforce “save only while locked” for manual/persisted models—backed by new tests and updated documentation.
Changes:
- Add
Snapshot.locked(reload=True)and OS-level per-file locking (Windows/POSIX) via new_locks.py. - Add
require_lockconfiguration throughsnapclass,Model.Meta,create_model, andsync, and enforce it on snapshot writes. - Add/extend tests and docs (README + fluency skill docs), and bump version to
0.1.3.
Reviewed changes
Copilot reviewed 10 out of 11 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| tests/test_sync.py | Verifies sync(..., require_lock=True) enforces locked saves for manual snapshots. |
| tests/test_snapshot_locking.py | New test suite covering reload-under-lock, cross-process coordination, and lock release behavior. |
| tests/test_model_meta.py | Ensures Model.Meta.snapshot_require_lock wiring and enforcement works, plus create_model(..., require_lock=True) support. |
| src/snapclass/skills/snapclass-fluency/SKILL.md | Documents the intended snapshot.locked(reload=True) + require_lock=True shared-file pattern. |
| src/snapclass/schemas.py | Implements require_lock, adds Snapshot.locked(), and routes write locking through the new lock module. |
| src/snapclass/collections.py | Updates get_or_create to use snapshot locking when require_lock is enabled. |
| src/snapclass/_locks.py | New locking implementation combining per-path re-entrant thread locks and OS-level file locks. |
| skills/snapclass-fluency/SKILL.md | Duplicates the fluency guidance update in the non-packaged skills path. |
| README.md | Adds shared-file coordination documentation and recommended usage pattern. |
| pyproject.toml | Bumps package version to 0.1.3. |
| .gitignore | Adds .todo/ ignore entry. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 4e4c5118e4
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 6c7f0dc263
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 379b9cf214
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 57ae8c542c
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: d5a5911df3
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Summary
Adds cooperative per-file snapshot locking for local cross-process writers.
snapshot.locked(reload=True)using a sidecar.lockfile and OS-level locking on Windows/POSIX.require_lock=Truefor manual persisted models so saves must happen inside a snapshot lock.Model.Meta,create_model, andsyncsurfaces to respect the lock requirement.0.1.3.Why
Shared snapclass instances can lose updates when multiple local processes load the same stale file, mutate independently, and save. The new pattern gives writers an explicit critical section: acquire the file lock, reload, mutate, save, and release.
Validation
python.exe -m pytest tests/test_snapshot_locking.pypython.exe -m pytestFull suite result:
333 passed.