Repository navigation
refactor(store): consumers reach the store only through its interface contract - #490
Draft
eribertocz wants to merge 21 commits into
Draft
eribertocz wants to merge 21 commits into
eribertocz wants to merge 21 commits into
Conversation
The format, kits, bindings and manifest; the assembly check; the consumer boundaries; contract compatibility; the standalone job. Written before the code: every test fails without it (#486 step 1). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MFyANPkiUZYq6rvGD2sFLf
Step 1 of #486 (foundations): the interface-contract format, conformance kits with a recorded count and no skips, the in-process and serializing bindings, the module manifest, the assembly capability check at server start, the consumer boundaries in report mode, the compatibility check against the last release, the standalone job on orvex-contracts, and ADR-0033 (Proposed). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MFyANPkiUZYq6rvGD2sFLf
…ncy and adapters Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MFyANPkiUZYq6rvGD2sFLf
…est adapters Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MFyANPkiUZYq6rvGD2sFLf
…it exists Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MFyANPkiUZYq6rvGD2sFLf
…requires them tools/ci/protection.py compares the required checks with main's live rulesets, so a check becomes required only after the Owner adds it there. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MFyANPkiUZYq6rvGD2sFLf
… codec and assembly - only a binding creates a refusal; anything else an implementation raises is undeclared, and the kit counts no refusal found down a cause chain; - compatibility compares each operation's error codes and default values; - one import scanner serves the module and consumer rules and the dynamic-import note; - models cross field by field, Arrow tables as IPC (pyarrow declared); - assembly chooses among several implementations by configuration and checks construction, signatures (envelope included) and the operations of the provided version. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MFyANPkiUZYq6rvGD2sFLf
…break it select.select refuses a descriptor at or past FD_SETSIZE; CI's test part 9 reached it and the ctrl-c watcher thread raised. The scheduler's watcher had the same defect: both now use a selector, and each has a regression test with 1,100 open files. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MFyANPkiUZYq6rvGD2sFLf
…om one call context - AwareDatetime and constrained types are value types; IANA zones, datetime.timezone and pydantic's TzInfo each come back as themselves; a naive datetime is refused; every generated store type may now cross (pydantic-core declared); - CallContext holds the correlation id, actor, project and revision, refuses missing or placeholder values, and makes every envelope; the server builds one correlation id per HTTP request (a well-formed X-Request-Id is kept), CLI command or scheduled run. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MFyANPkiUZYq6rvGD2sFLf
…ependency of orvex-contracts Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MFyANPkiUZYq6rvGD2sFLf
…om its declared environment A case declares variables and an extension directory (copied with or without given extensions); the kit runs it in a child process built from that declaration alone and reads its result back through the serializing codec, so no kit patches an implementation's internals and production holds no switch for a test. One case's run moves to kit_case.py, shared by the kit and the child. Plant: a case whose declared environment is ignored fails. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MFyANPkiUZYq6rvGD2sFLf
eribertocz
force-pushed
the
refactor/486-store-contract
branch
from
November 15, 2026 12:49
9f69d60 to
b874e15
Compare
…-testing distribution `bounds`, `environment`, `fixtures`, `facade_interface` and `azurite` move from `tests/support` to `packages/testing` (`orvex.testing`), never shipped and depending on no module, and every test imports them from there. The boundaries check refuses them in product code and the consumer rule allows them in tests only; the product-name check knows the `orvex-testing` package; the standalone job installs its wheel beside a module whose tests declare it; the Windows job installs it for the tests it runs. Part of #486. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MFyANPkiUZYq6rvGD2sFLf
…s consumers The store's kit run in process and serialized with planted broken guarantees, the Arrow IPC transport, the codec's aliased models and fixed offsets, the ClickHouse scanner fuzzing as the store's own test, the refusal before attach, and the store's consumers' tests on the contract. Part of #486 (step 2, store). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MFyANPkiUZYq6rvGD2sFLf
… contract `orvex.contracts.store`: the interface contract (every operation consumers use, by capability), its kit (58 cases, no skips), its errors with their codes and builders, its values and handles, its Arrow IPC transport and its consumer client. `orvex.store.api.Store` implements it, with `module.toml`. `server`, the runners, `tools` and the repository tests call the contract; the boundaries report shows no store violation. The standalone store job is added. Part of #486 (step 2, store). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MFyANPkiUZYq6rvGD2sFLf
The time limit, the conflict and the other-writer faults of the run-record tests are injected through the store contract's binding (a helper's own calls pass the interception), and the canonical-bytes subprocess reaches the encoder through the store client. Part of #486 (step 2, store). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MFyANPkiUZYq6rvGD2sFLf
… Arrow table type The store contract's reads, loads and JSON encoding carry `pyarrow.Table` values, encoded by the foundations' codec; the store's own IPC module and its codec changes are dropped, and the standalone store job is optional like the other interface jobs until main requires them. Part of #486 (step 2, store). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MFyANPkiUZYq6rvGD2sFLf
…ct's files are counted Part of #486 (step 2, store). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MFyANPkiUZYq6rvGD2sFLf
…ugh its composition root The consumer rule allows `server.assembly`, and nothing else of the server, outside the server. Part of #486 (step 2, store). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MFyANPkiUZYq6rvGD2sFLf
…e kit proves every one The store contract's operations declare their own error codes; `kit_codes` holds one case per (operation, code), each making that operation refuse with that code, and the kit is refused when a declared code has no case or a case proves an undeclared code (KIT_CODE_UNPROVEN). The ClickHouse cases take a server from the environment and fail without one (`kit_services`); refusal-only cases the code cases now prove are removed from the kit (153 cases). Part of #486 (step 2, store). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MFyANPkiUZYq6rvGD2sFLf
… extras, CI installs the helpers The structure check's store façade becomes `orvex.store.api`, which the implementation's own modules may not import back; a test dependency may name its extras (`moto[server]`), compared by its name; the Windows job installs `orvex-testing`; the store tests import the contract's types from the contract; and the test helpers' docstring names no product. Part of #486 (step 2, store). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MFyANPkiUZYq6rvGD2sFLf
eribertocz
force-pushed
the
refactor/486-store-contract
branch
from
November 15, 2026 13:12
f778a76 to
5fbab76
Compare
…ven in a process of their own `open_lake` and `open_existing_lake` declare STORE_EXTENSION_UNAVAILABLE, proven with an empty extension directory and a proxy nothing answers on; `connect_clickhouse` declares ENGINE_VERSION_UNTESTED, proven against a ClickHouse 26.9 service the kit's CI jobs start. Each case declares its environment and runs in its own process (the foundations' kit_process), so no case patches the store; their checks live beside the kit, where that process finds them. Part of #486 (step 2, store). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MFyANPkiUZYq6rvGD2sFLf
eribertocz
force-pushed
the
refactor/486-contract-foundations
branch
from
November 15, 2026 13:29
6ba558b to
94bf619
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Part of #486 — step 2 (store); stacked on step 1, retarget to main after it merges.
Draft until local
fulland CI are green. Rebased on #489 (20f1330): aware datetimes cross, so the contract is declared and its kit runs.Size
About 5,000 counted lines, not split: #486 §5 makes step 2 one pull request for the store's contract, its kit, its
apiand every consumer moved onto it, because a consumer half-moved would import both the contract and the internals it replaces. Most lines are the mechanical move of ~75 consumer files and the kit's 153 cases.Files and their purposes
packages/contracts/src/orvex/contracts/store/interface.py…/store/errors.py(moved fromorvex/store/errors.py)StoreError, its codes, redaction and builders (source_not_found,separation_refused,SNAPSHOT_CHANGED,FILE_REFUSED)…/store/values.pyHeld,JsonFrame…/store/kit.py…/store/kit_codes.py…/store/kit_services.pypackages/testing/(orvex-testing)…/store/kit_support.py…/store/client.pyStoreClient,Lake,Transaction,ReadHandle, every call through a binding with its envelope…/store/client_sources.pypackages/store/src/orvex/store/api/__init__.pyStore…/store/api/service.pyStore, the implementation of the contract…/store/api/held.pypackages/store/src/orvex/store/module.tomlpackages/store/benchmarks/source_stream.py(moved fromtools/benchmarks/)packages/server/src/orvex/server/store_access.pypackages/server/src/orvex/server/assembly.pyprovider: the chosen implementation, built once per processserver,conformance/runners,tools,testsorvex.store.*onto the contractpackages/store/tests/test_contract_kit.py,contract_client.py,test_clickhouse_scanner_fuzzing.py,parquet_footer.py(moved)tests/propertiespackages/server/tests/store_faults.pyLaws touched
Law 7 (limits): unchanged, the kit refuses a lake without every limit. Exact values: the kit proves DECIMAL(38,10), HUGEINT, TIMESTAMPTZ and NULL through both bindings. Fail closed: forged or closed handles are refused (
STORE_PARAMETER_INVALID); undeclared errors never cross.Case matrix
test_contract_kit.py::test_the_store_passes_its_whole_kit_in_process_and_serializedexecute.idempotentfailstest_the_kit_fails_a_planted_broken_guaranteestart-read.exactfailsread-batch.endsfailsapi.Store, requires nonetest_the_manifest_provides_every_capability_from_the_api_packagetest_existing_lake_files.py::test_an_overlapping_declaration_is_refused_before_anything_is_attachedpackages/server/tests/test_run_records.pyorvex.storepython -m tools.checks.boundariesEvidence (before the rebase onto the updated #489)
python -m tools.checks.boundaries:boundaries: 0 finding(s); consumer report: nostorefinding.verify fast(timed out on the loaded machine), localfull, CI.Error codes
Each operation declares only the codes it raises (
interface.ERRORS_OF, 110 pairs) and the kit proves every one. Pending:STORE_EXTENSION_UNAVAILABLEand ClickHouseENGINE_VERSION_UNTESTEDneed the per-case process environments being added to the foundations; until then they are not declared (a raise of either is refused asINTERFACE_ERROR_UNDECLARED), and the check has no exemption for them. Defense-in-depth codes no environment can provoke without patching the store are not declared either: existing-lakeSOURCE_NOT_READ_ONLY(the store sets the read-only session itself) andSTORE_CATALOG_UNAVAILABLE(object-storage secret refused).Open, for the Owner
tests/support: bounds, environment, fixtures, facade_interface, azurite) are also used by server and repository tests: moving them would duplicate them. A shared home needs a decision; 6 store test imports remain, so the standalone store job still fails on them.project_idandrevisionare the server's own (instance,current) and the correlation id is new per client: carrying the request's real ones needs every server entry point to pass a caller.orvex.server.store_access, a server import.Shared files changed (append-only)
tools/ci/checks.toml(standalone-store job, regressions entry),tools/checks/materialization-allowlist.toml(kit entries),.github/workflows/interfaces.yml(standalone-store job),.github/workflows/property-nightly.yml(the moved fuzzing test),pyproject.toml(T20 for module benchmarks).Generated by Claude Code