From b53bb458443d9f866efe4325c7555cbfe4898ae8 Mon Sep 17 00:00:00 2001 From: Libby Date: Tue, 17 Nov 2026 02:00:21 +0000 Subject: [PATCH 1/3] cultcache-py: export CultCacheError from the package root (py-cultcacheerror-not-exported) Co-Authored-By: Claude Sonnet 5.5 --- packages/cultcache-py/CHANGELOG.md | 1 + packages/cultcache-py/README.md | 1 + .../cultcache-py/src/cultcache_py/__init__.py | 3 ++- packages/cultcache-py/tests/test_first_call.py | 15 +++++++++++++++ 4 files changed, 19 insertions(+), 1 deletion(-) diff --git a/packages/cultcache-py/CHANGELOG.md b/packages/cultcache-py/CHANGELOG.md index 30b60850..70ee23db 100644 --- a/packages/cultcache-py/CHANGELOG.md +++ b/packages/cultcache-py/CHANGELOG.md @@ -8,6 +8,7 @@ ### Added +- `CultCacheError` is exported from the package root (`from cultcache_py import CultCacheError`); it was reachable only from the private `cultcache_py.cache` module. - `CultCache.update` and `update_global` return `UpdateResult(outcome, document)`; `UpdateOutcome` is `UPDATED`, `DECLINED` or `LOST_RACE`. The single-file store gains `read(key)` (the record and its content version, the SHA-256 C# computes) and `commit_if(envelope, expected)`, the version is the SHA-256 of the record re-encoded as `[key, schemaId, storedAt, payload]` with minimal MessagePack encodings, which is the SHA-256 of the record's stored bytes exactly when the writer encoded it minimally (every writer in this library does; a record another writer encoded with a wider-than-needed length or integer has the version of its minimal form, not of its bytes). Both looked up by the cache and not `BackingStore` protocol members (variants:cut_spec:cut-update-with-retry-py). - `read_payload_tree(type_name, payload, decoder=None)`: the exported owner of the one-value, depth-first payload read that `decode_payload` uses, for payloads read outside a definition (`cultnet-py`'s witness bundle decode needs it, so `cultnet-py` now requires `cultcache-py>=0.4.0`). The manifest version is 0.4.0, the minor these Unreleased breaking changes imply, set in this change so the workspace install resolves the new bound; the `## Unreleased` heading becomes `## [0.4.0]` when it is tagged. diff --git a/packages/cultcache-py/README.md b/packages/cultcache-py/README.md index 0a03a671..f320bd97 100644 --- a/packages/cultcache-py/README.md +++ b/packages/cultcache-py/README.md @@ -69,6 +69,7 @@ store. ## Public Surface +- `CultCacheError` (a `RuntimeError`, exported from the package root): the cache's refusals (a duplicate registration, a unique-index violation, a key held by two types). Import it from `cultcache_py`, not from the private `cache` module. Any `convert` refusal raised as a `CultCacheError` is caught by it too, once `convert` lands. - `define_document_type(...)` - `define_database_entry_type(...)` - `database_entry_field(...)` diff --git a/packages/cultcache-py/src/cultcache_py/__init__.py b/packages/cultcache-py/src/cultcache_py/__init__.py index 0c26cb25..2016c817 100644 --- a/packages/cultcache-py/src/cultcache_py/__init__.py +++ b/packages/cultcache-py/src/cultcache_py/__init__.py @@ -1,7 +1,7 @@ from .backing_store import BackingStore, CultCacheEnvelope from .backing_store import CultCacheSchemaCatalogEntry, CultCacheSchemaCatalogMember from . import leaves -from .cache import CultCache, CultCacheBuilder, ForeignRecord, UpdateOutcome, UpdateResult +from .cache import CultCache, CultCacheBuilder, CultCacheError, ForeignRecord, UpdateOutcome, UpdateResult from .documents import ( MAX_PAYLOAD_DEPTH, MAX_SLOT_KEY, @@ -25,6 +25,7 @@ __all__ = [ "BackingStore", "CultCache", "CultCacheBuilder", + "CultCacheError", "CultCachePayloadDepthError", "CultCacheEnvelope", "CultCacheSchemaCatalogEntry", diff --git a/packages/cultcache-py/tests/test_first_call.py b/packages/cultcache-py/tests/test_first_call.py index 232f6c7d..9b6b65dc 100644 --- a/packages/cultcache-py/tests/test_first_call.py +++ b/packages/cultcache-py/tests/test_first_call.py @@ -93,5 +93,20 @@ class FirstCallTests(unittest.TestCase): self.assertIn("```python\n" + snippet + "```", docs) +class RootExportTests(unittest.TestCase): + def test_cultcacheerror_is_importable_from_the_root_and_catches_a_cache_refusal(self) -> None: + import cultcache_py + from cultcache_py import CultCache, CultCacheError, define_document_type + from cultcache_py.cache import CultCacheError as private + + self.assertIs(CultCacheError, private) + self.assertIn("CultCacheError", cultcache_py.__all__) + document = define_document_type("tests.root_export") + cache = CultCache.builder().register_document_type(document).build() + with self.assertRaises(CultCacheError): + cache.get_required(document, "absent") + + if __name__ == "__main__": unittest.main() + -- 2.47.3 From 562d318b480430f0f7218b3f4fa14d52c20b7789 Mon Sep 17 00:00:00 2001 From: Libby Date: Tue, 17 Nov 2026 03:28:55 +0000 Subject: [PATCH 2/3] cultcache-py: pin CultCacheError on a convert refusal; state that store push does not judge payload bytes and the cache write path does The store holds no definition, so it cannot judge a JSON- or custom-codec payload; put_envelope decodes under the definition before any store is touched. Co-Authored-By: Claude Sonnet 5.5 --- packages/cultcache-py/README.md | 9 +++-- .../cultcache-py/tests/test_first_call.py | 34 +++++++++++++++---- 2 files changed, 34 insertions(+), 9 deletions(-) diff --git a/packages/cultcache-py/README.md b/packages/cultcache-py/README.md index 61b90341..02982c47 100644 --- a/packages/cultcache-py/README.md +++ b/packages/cultcache-py/README.md @@ -69,7 +69,7 @@ store. ## Public Surface -- `CultCacheError` (a `RuntimeError`, exported from the package root): the cache's refusals (a duplicate registration, a unique-index violation, a key held by two types). Import it from `cultcache_py`, not from the private `cache` module. Any `convert` refusal raised as a `CultCacheError` is caught by it too, once `convert` lands. +- `CultCacheError` (a `RuntimeError`, exported from the package root): the cache's refusals (a unique-index violation, a key held by two types) and `convert`'s (`source_missing`, `destination_exists`, a refused record). Import it from `cultcache_py`, not from the private `cache` module. - `define_document_type(...)` - `define_database_entry_type(...)` - `database_entry_field(...)` @@ -185,9 +185,14 @@ digit (`0` to `9`), below. rewritten under the definitions' own codec, records of other types keep their bytes, and the new file is fsynced before the call returns. Open it with the default definitions, then swap it in yourself. The source is never written. A - refused record raises `CultCacheError` naming the type, record key and code, and + refused record raises `CultCacheError` (importable from `cultcache_py`) naming the type, record key and code, and leaves no destination; a killed run leaves the source as it was and a partial destination, so delete the destination and run again. +- A store's `push` does not validate payload bytes: a store holds no definition, so it cannot know a record's codec (a JSON or + custom-codec payload is not one MessagePack value) and carries the bytes it is given, as it carries a foreign record. The + cache write path judges them: `put_envelope(s)` decodes the payload under the definition before any store is touched, so a + payload with bytes after its first value is refused (`ValueError`, "bytes after its first MessagePack value (refused on read)") + and nothing is written. A tail pushed straight through a store is refused at the next load. - A JSON payload that is a single digit (`0` to `9`) is also a valid one-byte MessagePack integer and reads as 48 to 57 under the default, with no refusal. Only a document whose whole value is such a digit meets this; objects, lists and diff --git a/packages/cultcache-py/tests/test_first_call.py b/packages/cultcache-py/tests/test_first_call.py index 9b6b65dc..32bafa56 100644 --- a/packages/cultcache-py/tests/test_first_call.py +++ b/packages/cultcache-py/tests/test_first_call.py @@ -1,10 +1,12 @@ """The Python CultCache first call from docs/start/README.md. The docs show the region between the `snippet` markers verbatim, and test_docs_show_the_tested_snippet fails when they differ.""" +import tempfile import unittest from pathlib import Path -from cultcache_py import UpdateOutcome +import cultcache_py +from cultcache_py import CultCacheEnvelope, JsonLinesBackingStore, UpdateOutcome # snippet:begin import tempfile @@ -94,17 +96,35 @@ class FirstCallTests(unittest.TestCase): class RootExportTests(unittest.TestCase): - def test_cultcacheerror_is_importable_from_the_root_and_catches_a_cache_refusal(self) -> None: - import cultcache_py - from cultcache_py import CultCache, CultCacheError, define_document_type + def test_cultcacheerror_from_the_root_catches_a_convert_refusal(self) -> None: + from cultcache_py import CultCacheError, convert from cultcache_py.cache import CultCacheError as private self.assertIs(CultCacheError, private) self.assertIn("CultCacheError", cultcache_py.__all__) document = define_document_type("tests.root_export") - cache = CultCache.builder().register_document_type(document).build() - with self.assertRaises(CultCacheError): - cache.get_required(document, "absent") + with tempfile.TemporaryDirectory() as directory: + source = SingleFileMessagePackBackingStore(Path(directory) / "source.cc") + source.push(CultCacheEnvelope.create(key="k", type=document.type, payload=document.encode_payload({"a": 1}))) + destination = Path(directory) / "destination.cc" + destination.write_bytes(b"in the way") + with self.assertRaises(CultCacheError) as caught: + convert(source, destination, [document]) + self.assertIn("destination_exists", str(caught.exception)) + self.assertEqual(destination.read_bytes(), b"in the way") + + def test_the_cache_write_path_refuses_a_payload_tail_and_writes_nothing(self) -> None: + document = define_document_type("tests.tail") + with tempfile.TemporaryDirectory() as directory: + for store in ( + SingleFileMessagePackBackingStore(Path(directory) / "tail.cc"), + JsonLinesBackingStore(Path(directory) / "tail.jsonl"), + ): + cache = CultCache.builder().register_document_type(document).add_generic_store(store).build() + tailed = document.encode_payload({"a": 1}) + b"\xc0" + with self.assertRaisesRegex(ValueError, r"1 bytes after its first MessagePack value \(refused on read\)"): + cache.put_envelope(document, CultCacheEnvelope.create(key="k", type=document.type, payload=tailed)) + self.assertEqual(store.pull_all(), [], type(store).__name__) if __name__ == "__main__": -- 2.47.3 From e8fa1c4d8fd2f2c2dd2c76c159d0c960c9b1c529 Mon Sep 17 00:00:00 2001 From: Libby Date: Tue, 17 Nov 2026 03:32:01 +0000 Subject: [PATCH 3/3] cultcache-py: pin the put_envelopes tail refusal; README says a held-by-two-types conflict is CultCacheError on load, SchemaConflictError on write Co-Authored-By: Claude Sonnet 5.5 --- packages/cultcache-py/README.md | 2 +- .../cultcache-py/tests/test_first_call.py | 24 +++++++++++++++++++ 2 files changed, 25 insertions(+), 1 deletion(-) diff --git a/packages/cultcache-py/README.md b/packages/cultcache-py/README.md index 02982c47..f6574618 100644 --- a/packages/cultcache-py/README.md +++ b/packages/cultcache-py/README.md @@ -69,7 +69,7 @@ store. ## Public Surface -- `CultCacheError` (a `RuntimeError`, exported from the package root): the cache's refusals (a unique-index violation, a key held by two types) and `convert`'s (`source_missing`, `destination_exists`, a refused record). Import it from `cultcache_py`, not from the private `cache` module. +- `CultCacheError` (a `RuntimeError`, exported from the package root): the cache's refusals (a unique-index violation; a key held by two types on load, while the same conflict on a write is a `SchemaConflictError`, a `ValueError`) and `convert`'s (`source_missing`, `destination_exists`, a refused record). Import it from `cultcache_py`, not from the private `cache` module. - `define_document_type(...)` - `define_database_entry_type(...)` - `database_entry_field(...)` diff --git a/packages/cultcache-py/tests/test_first_call.py b/packages/cultcache-py/tests/test_first_call.py index 32bafa56..42cc5aa8 100644 --- a/packages/cultcache-py/tests/test_first_call.py +++ b/packages/cultcache-py/tests/test_first_call.py @@ -126,6 +126,30 @@ class RootExportTests(unittest.TestCase): cache.put_envelope(document, CultCacheEnvelope.create(key="k", type=document.type, payload=tailed)) self.assertEqual(store.pull_all(), [], type(store).__name__) + def test_a_batch_with_one_tailed_envelope_is_refused_whole_and_earlier_records_stay(self) -> None: + document = define_document_type("tests.tail_batch") + with tempfile.TemporaryDirectory() as directory: + for store in ( + SingleFileMessagePackBackingStore(Path(directory) / "batch.cc"), + JsonLinesBackingStore(Path(directory) / "batch.jsonl"), + ): + name = type(store).__name__ + cache = CultCache.builder().register_document_type(document).add_generic_store(store).build() + cache.put(document, "early", {"a": 0}) + before = store.pull_all() + good = document.encode_payload({"a": 1}) + with self.assertRaisesRegex(ValueError, r"1 bytes after its first MessagePack value \(refused on read\)"): + cache.put_envelopes( + document, + [ + CultCacheEnvelope.create(key="good", type=document.type, payload=good), + CultCacheEnvelope.create(key="bad", type=document.type, payload=good + b"\xc0"), + ], + ) + self.assertEqual(store.pull_all(), before, name) + self.assertEqual([item.key for item in before], ["early"], name) + self.assertIsNone(cache.get(document, "good"), name) + if __name__ == "__main__": unittest.main() -- 2.47.3