Repository navigation
refactor(contracts): interface-contract foundations (#486 step 1) - #489
Draft
eribertocz wants to merge 11 commits into
Draft
eribertocz wants to merge 11 commits into
eribertocz wants to merge 11 commits into
Conversation
This was referenced Nov 15, 2026
Draft
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
…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
…pe builder, aware types - the child process finds the kit by module:NAME and checks its description and the case's check, so it never runs another case in its place; - the request id stays server-generated and the unused context builders are gone; - only contracts/context.py builds an envelope (ENVELOPE_BUILT_BY_HAND, blocking); the kit plants broken envelopes through it; - a contract declares AwareDatetime, a plain datetime is refused at declaration, and the in-process binding refuses naive values too; - the instance configuration (assembly.toml) chooses among several implementations; - interface-contracts and standalone are required, and main's ruleset lists them. 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 1 of §5, "Foundations", as of revision 7).
What changed
The foundations every later step of #486 builds on, with no consumer moved yet:
orvex.contracts: operations, inputs, outputs, errors, capabilities, state changes and theMAJOR.MINORversion each operation exists from; only values may cross a contract.contract_name,contract_version,correlation_id,actor,project_id,revision, and anidempotency_keyrequired on every operation that changes state. Every binding validates it before the implementation runs and fails closed with a typedContractCallRefused(CONTRACT_ENVELOPE_INVALID,CONTRACT_VERSION_UNSUPPORTED).CONTRACT_VERSION_UNSUPPORTED) the newer ones, never answer wrongly.module.tomland the assembly capability check inserver/assembly.py, run before the server starts.server, runners,tools/,tests/) in report mode; theserverexemption of the module check stays until step 7.tools/ci/standalone.py, exercised onorvex-contracts), with public test adapters so a module runs its own operations with only the contracts it requires.Files and their purposes
packages/contracts/src/orvex/contracts/interface.py(new).../contracts/version.py(new)MAJOR.MINOR.../contracts/context.py(new).../contracts/envelope.py(new).../contracts/interface_errors.py(new)ContractCallRefused).../contracts/serializable.py(new).../contracts/aware.py(new).../contracts/codec.py(new).../contracts/binding.py(new).../contracts/kit.py(new).../contracts/kit_client.py(new).../contracts/kit_case.py(new).../contracts/kit_process.py(new).../contracts/kit_run.py(new).../contracts/adapter.py(new).../contracts/manifest.py(new)module.toml.../contracts/registry.py(new).../contracts/module.toml(new).../contracts/__init__.py,packages/contracts/pyproject.toml,README.mdpackages/contracts/interface-record.json(new)packages/server/src/orvex/server/assembly.py(new)packages/server/src/orvex/server/assembly_settings.py(new)assembly.tomlor<SLUG>_ASSEMBLY_CONFIG)pyproject.tomlpydantic-corepinned in the runtime grouppackages/server/src/orvex/server/cli.pytools/checks/imports.py(new)tools/checks/envelopes.py(new)contracts/context.pybuilds an envelope (blocking)tools/checks/consumers.py(new)tools/checks/boundaries.pyimports.py(constant dynamic imports included); prints the consumer reporttools/checks/structure.pyimports.pytools/checks/module_dependencies.py(new)tools/ci/standalone.py(new)tools/contracts/interface_record.py(new)tools/contracts/interface_compat.py(new).github/workflows/interfaces.yml(new)docs/adr/0033-...md,docs/adr/README.mddocs/process/git-workflow.mdpackages/contracts/src/orvex/contracts/as counted in a sizepackages/contracts/tests/*,packages/server/tests/test_assembly.py,tests/tools/test_{consumer_boundaries,interface_compat,standalone}.pytests/contracts/test_http_api_v1.py(moved frompackages/contracts/tests/)contracts/http-api/v1/examples. Moved because it reads repository files and importsyaml, so it cannot run in the standalone environment (G4);tests/contractsis in the critical set, so it runs inprandfullas beforeShared governance files changed (append-only, coordination with #244)
tools/ci/checks.toml: two[[job]]entries at the end (interface-contracts,standalone),required = true.tools/repo/main-ruleset.json: the two contexts appended at the end ofrequired_status_checks(see "Owner action")..github/workflows/scripts/ci_alerts.toml: one[[watch]]at the end;.github/workflows/ci-alerts.yml: one workflow name at the end of its list.docs/adr/README.mdthe existing ADR-0004 row gains "rules 2-4 amended by 0033 once accepted"; indocs/process/git-workflow.mdthe hand-written files ofpackages/contracts/src/orvex/contracts/are inserted into the "Not counted in a pull request's size" block, after the existing exclusions of that directory..github/pull_request_template.md: not changed.docs/architecture/security.mdanddocs/roadmap.md§2: not changed.Coordinator decisions (added on this PR)
Aware datetimes:
AwareDatetimeand constrained (Annotated) types are value types; an IANA zone, adatetime.timezoneand pydantic'sTzInfoeach come back as themselves; a naive datetime is refused (standalone, in tuples and inside models). Every generatedstorev1 type may now cross (test_every_generated_store_type_may_cross). Generated types of other contracts that useAny(receipt, semantic_explain, security_policies, http_api) remain refused: their steps give those fields a value type.One call-context mechanism:
CallContextinorvex.contracts.contextrefuses missing or placeholder values (CONTRACT_CONTEXT_INVALID) and is the one way to make an envelope; the binding also refuses placeholders in any envelope. The entry points build it, with the server-generated correlation id, in the step that wires their first contract call.Case environments: a
KitCasemay declare aCaseEnvironment(variables, and anExtensionDirectorycopied with or without given extensions). The case then runs in a child process built from that declaration alone and itsCaseResultreturns through the serializing codec; the environment is part of the kit's description (G3). Plant: a case whose declared environment is ignored fails (test_kit_process.py::test_a_case_whose_declared_environment_is_ignored_fails); also tested: nothing inherited, a missing extension source, a factory the child cannot import, a child that fails.Second review fixes (Reviewer on 6ba558b)
module:NAME, checkskit.describe()and the case's check reference, and otherwise answers KIT_CASE_NOT_IMPORTABLE. Plants:test_kit_process.py::test_a_derived_kit_s_failing_case_fails_in_its_own_process_too(would pass under the old lookup) and..._not_a_top_level_name_cannot_run_in_its_own_process.app.pyandserver_app.pyare unchanged frommain.request_contextandcommand_context(andserver/call_context.py) are removed; entry points build theirCallContextin the step that wires them (ADR-0033 rule 2).tools/checks/envelopes.py(ENVELOPE_BUILT_BY_HAND, blocking, run byboundaries) flagsCallEnvelope(...)anddataclasses.replacein files namingCallEnvelope, in product code, runners and tools;kit_clientplants broken envelopes throughcontext.planted_envelope. Plants:tests/tools/test_envelope_check.py(5 planted, 5 allowed).binding.pydocstring states exactly who raisesContractCallRefused: a binding, andCallContext.datetimeannotation is refused at declaration ("declare pydantic.AwareDatetime"), and the in-process binding refuses naive arguments and results (aware.py). Tests:test_a_plain_datetime_is_refused_with_the_type_to_declare,test_a_naive_datetime_is_refused_in_both_bindings,test_a_naive_datetime_in_a_result_is_refused_in_process.PLACEHOLDERSconvention.selecttoselectorsfix moved to its own PR, fix(store): watch signals with a selector, so 1,024 open files never break it #494, with its regression tests. The root cause is not this PR's tests: a per-test descriptor trace over all of refactor(contracts): interface-contract foundations (#486 step 1) #489's tests stays at 14 descriptors. Until fix(store): watch signals with a selector, so 1,024 open files never break it #494 merges,python-tests-3.15-part-9can fail here ontest_the_heartbeat_holds_no_secret, as it did before.server/assembly_settings.pyreads the instance's choices ([implementations]ofassembly.toml, or the file<SLUG>_ASSEMBLY_CONFIGnames), and the CLI passes them tocheck_installed_assembly. Tests:test_assembly_settings.py,test_the_server_assembles_with_the_instance_s_configured_choice.mainafter docs(repo): the STRIDE threat model and the rule that keeps it current (#244) #487.Owner action
interface-contractsandstandalonearerequired = trueintools/ci/checks.toml, and both contexts are appended totools/repo/main-ruleset.json. When merging, the Owner applies the ruleset in GitHub. Until then,governance-scripts(tools/ci/protection.py) reports that main does not yet require them: the expected failure of this PR's CI.Review fixes (Reviewer on 0a9183b)
ContractCallRefused; any other error an implementation raises, a refusal or machinery error included, isINTERFACE_ERROR_UNDECLAREDin both bindings; the kit counts only a top-level refusal of the binding. Plants:FakeRefusal,LeakedMachineryError(both bindings),FakingV10and a cause-chain refusal (kit).INTERFACE_OPERATION_ERRORS_CHANGED) and default values. Plants: a code added, a code removed, a changed default.tools/checks/imports.py, used by the module rule, the consumer rule and the dynamic-import note; the module rule catches constantimport_module/__import__(3 plants).module_dependencies.pystates why it keeps its own reader.VALUES; a tampered model is refused.get,put,size_bytes,len,Use,Storedwith a table).chosen), reads a chosen alternative's manifest by its module path, checks the construction protocol (a class built by keyword) and each method's signature, envelope included; fixtures fixed.since <= provided.version.contracts.toml(data contracts,vN) besidemodule.toml(interface contracts,MAJOR.MINOR).envelope.pyusesVersion.parse;required_adapterschecks the contract name; every new file marked new.Case matrix
sincetest_interface.py::TestDescriptionINTERFACE_CONTRACT_INVALID), incl.sinceoutside the contract's versiontest_interface.py::TestRefusals::test_an_inconsistent_declaration_is_refusedUNSUPPORTED_OPERATIONcan never be declaredTestRefusals::test_unsupported_operation_can_never_be_declaredenvelope: CallEnvelopefirst is refusedTestEnvelopeParameter(4 plants)TestCrossingTypes::test_a_live_object_may_never_cross(14 types)test_envelope.py::test_a_call_missing_a_required_field_is_refused(48 cases)test_an_operation_that_changes_state_needs_an_idempotency_keyCONTRACT_ENVELOPE_INVALIDtest_anything_but_an_envelope_is_refused,test_an_envelope_for_another_contract_is_refused,test_a_version_that_is_not_major_minor_is_refusedCONTRACT_VERSION_UNSUPPORTEDtest_an_incompatible_major_version_is_refused_explicitlyCONTRACT_VERSION_UNSUPPORTEDtest_an_operation_newer_than_the_provider_is_refused,..._caller_s_version_is_refusedtest_a_newer_caller_is_served_by_an_older_provider_for_what_it_has,test_an_older_caller_is_served_by_a_newer_providertest_binding.py::TestBound::test_the_implementation_receives_the_envelopeINTERFACE_ERROR_UNDECLAREDTestBound::test_an_undeclared_error_is_refused_in_both_bindingstest_kit.py::TestRun::test_a_correct_implementation_passes_every_case_both_ways_by_n_and_n_1TestRun::test_a_planted_implementation_failing_one_case_fails_the_kitTestRun::test_a_run_with_one_case_fewer_fails,..._a_skip_is_a_failure...TestDeclarationRefusalsTestIdempotency::test_an_operation_that_changes_state_twice_for_one_key_failsTestIdempotency::test_a_call_without_effect_proves_nothing_and_failsTestEnvelopeCases::test_a_binding_that_accepts_an_incompatible_major_silently_failsTestEnvelopeCases::test_a_binding_that_accepts_a_call_missing_a_field_failsTestVersions::test_a_consumer_at_n_1_broken_by_an_additive_change_failsTestVersions::test_a_provider_at_n_1_passes_the_kit_of_n,..._that_answers_a_newer_operation_is_still_refused,..._with_a_wrong_answer_failstest_binding.py::TestPlantedLiveObjectTestCodectests/tools/test_interface_compat.py::TestPlantedViolationsTestCompatibleChanges::test_an_addition_claiming_the_released_version_fails,..._starts_changing_state_failsTestRelease,TestRecordpackages/server/tests/test_assembly.pytest_the_server_does_not_start_when_assembly_is_refusedtest_manifest.pyserver, a runner, a tool and a repository test each reported; report mode does not fail; module boundary still failstests/tools/test_consumer_boundaries.pytests/tools/test_standalone.pytest_adapter.py,test_registry.py::test_a_planted_adapter_that_fails_its_kit_is_caughttest_binding.py::TestBound::test_an_undeclared_error_is_refused_in_both_bindings,test_kit.py::TestFakedRefusalstest_interface_compat.py::TestPlantedViolationstests/tools/test_checks.py::...::test_a_constant_dynamic_import_is_reportedtest_binding.py::TestCodecpackages/server/tests/test_assembly.pyorvex-contractsinstalls alone outside the repository and passes its own testspython -m tools.ci.standalone contracts(jobstandalone)How it was verified
fullverification: not completed. Two runs were stopped by time limits (50 min and 2 h) while the test phase was still running on a shared machine at load 37-48 on 2 CPUs; no failure was reported before they stopped. Per the coordinator, this PR is opened as a draft so CI's mandatoryfullgate runs; it is marked ready only when a localfulland CI are both green.6ba558b: green. 56 checks succeeded, 6 skipped by design; onegovernancerun was cancelled by a newer run for the same body edit, which succeeded. The successes includepython-tests-3.15andpython-tests-3.14(thefullgate),python-coverage-3.15and-3.14,interface-contracts,standalone,boundaries,governanceandgovernance-scripts.ruff format --check,ruff check: clean on every changed path.mypy -p orvex.contracts -p orvex.server: no issues (118 files).pytest packages/contracts packages/server/tests/test_assembly.py tests/tools/test_{interface_compat,standalone,consumer_boundaries,checks,structure,ci_checks}.py: 574 passed.pytest tests/tools/test_ci_checks.py tests/tools/test_checks.py tests/tools/test_ci_alert_workflows.py: 181 passed (checks.toml drift, uncounted files, CI alerts).python -m tools.ci.standalone contracts: "orvex-contracts installs alone and passes its 456 tests", 0 skipped, 0 dependency problems.Size
Over the guide (about 5,600 lines, roughly half tests). Not split because every part is one coherent foundation that the checks verify against each other: the format, the envelope, the kit runner and the bindings are exercised by the same kits; the compatibility check reads the kit's description; the standalone job runs the kits; the planted violations need all of them. Review order:
version.py,envelope.py,interface.py,binding.py,kit.py,kit_client.py,kit_run.py, thenadapter.py,manifest.py,assembly.py, and the tools.Time and CI-first errors
About 3.5 hours (including two interrupted local
fullruns). CI-first errors: 2 (python-tests-3.15-part-9: theselect.selectdefect above, fixed for its class;governance-scripts: the new checks were marked required before main requires them; fixed by keeping them optional, see "Risks").Not done here
verify_kit(kit, make, provided=N-1), tested with a 1.0 implementation against the 1.1 kit), but no interface contract has been released, so there is no released implementation to build. The job that builds a module at its last release and runs the current kit arrives with the first released contract (step 2). Stated in ADR-0033 rule 6.chosen) is in place; the configuration key arrives with the first interface that has two implementations (step 5).overview.md,AGENTS.md§5,engineering.md§2/§8, conformance pack): when ADR-0033 is accepted.Laws touched
DECIMALscale, integers of any width, zones andfold; tested value by value.Contracts touched
No language-neutral contract under
contracts/.orvex-contractsgains the interface-contract format (no interface contract exists yet; the record is empty).Dependencies added
problem: an Arrow table must cross a contract exactly (G1 result cache, G5 serialization) · package:
pyarrow· version: 26.0.1 (already pinned in the lock; now a declared dependency oforvex-contracts) · license: Apache-2.0 · governance: Apache Software Foundation · alternative: tagged JSON of rows (loses Arrow types and violates ADR-0025 materialization rules) · reason: Arrow IPC keeps every type, NULL and zone, and is the format every module already exchangesproblem: a fixed offset parsed by pydantic must come back as the same
TzInfo· package:pydantic-core· version: 2.50.4 (already locked as pydantic's own dependency; now declared byorvex-contractsand pinned in the runtime group) · license: MIT · governance: Pydantic Services · alternative: rebuild asdatetime.timezone(changes the type) · reason: exact round trip of what pydantic validatesSecurity (if applicable)
Protected: the guarantee that a call reaching an implementation is complete (actor, project, revision, correlation) and of a version the implementation serves. From: a consumer or a binding that omits or forges fields, or silently accepts another major version. Tested by the envelope tests and by the planted lax bindings, which the kit catches.
Risks
api. That is the intent of §2 item 6.project_idandrevisionare required on every call, as §2 item 6 lists them; a later contract whose operations act on no project would need a product decision.Checklist
prlocal verification passed on a clean checkout of the commit (fullruns in CI; tier A:fulllocally too) — pending, see "How it was verified"TODO, dead code or commented-out codehttps://claude.ai/code/session_01MFyANPkiUZYq6rvGD2sFLf
Generated by Claude Code