Skip to content

refactor(contracts): interface-contract foundations (#486 step 1) - #489

Draft
eribertocz wants to merge 11 commits into
mainfrom
refactor/486-contract-foundations
Draft

eribertocz wants to merge 11 commits into
mainfrom
refactor/486-contract-foundations

Conversation

@eribertocz

@eribertocz eribertocz commented Nov 15, 2026 •

Copy link
Copy Markdown
Owner

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:

  • Interface-contract format in orvex.contracts: operations, inputs, outputs, errors, capabilities, state changes and the MAJOR.MINOR version each operation exists from; only values may cross a contract.
  • Call envelope (§2 item 6): contract_name, contract_version, correlation_id, actor, project_id, revision, and an idempotency_key required on every operation that changes state. Every binding validates it before the implementation runs and fails closed with a typed ContractCallRefused (CONTRACT_ENVELOPE_INVALID, CONTRACT_VERSION_UNSUPPORTED).
  • Conformance kits: cases with a recorded count and no skip list; an idempotency case is mandatory for every operation that changes state (same key, one effect); every run also sends the envelope cases the contract implies. Kits run in process and serialized, by consumers at N-1 and N; a provider at N-1 runs the kit of N and must pass its own cases and pass or refuse (CONTRACT_VERSION_UNSUPPORTED) the newer ones, never answer wrongly.
  • Module manifest module.toml and the assembly capability check in server/assembly.py, run before the server starts.
  • Consumer boundaries (server, runners, tools/, tests/) in report mode; the server exemption of the module check stays until step 7.
  • G3 compatibility check against the last release, including that every addition exists only from a later version.
  • G4 standalone job (script tools/ci/standalone.py, exercised on orvex-contracts), with public test adapters so a module runs its own operations with only the contracts it requires.
  • G5 serializing binding.
  • ADR-0033 (Proposed), amending ADR-0004 rules 2-4.

Files and their purposes

File Purpose
packages/contracts/src/orvex/contracts/interface.py (new) The interface-contract format: operations, inputs, outputs, errors, capabilities and version
.../contracts/version.py (new) A contract version, MAJOR.MINOR
.../contracts/context.py (new) The call context: correlation id, actor, project, revision; real values only; makes every envelope
.../contracts/envelope.py (new) The call envelope and why a binding refuses one before the implementation runs
.../contracts/interface_errors.py (new) The errors of the interface-contract machinery (adds ContractCallRefused)
.../contracts/serializable.py (new) Which annotated types may cross a contract
.../contracts/aware.py (new) Aware datetimes only: a naive value never crosses either binding
.../contracts/codec.py (new) The serializing codec: a value to bytes and back, exactly
.../contracts/binding.py (new) The two bindings (in process, serialized), with envelope and version checks
.../contracts/kit.py (new) The conformance-kit format: cases, recorded count, idempotency cases
.../contracts/kit_client.py (new) What a kit case calls an implementation through: a fresh envelope per call
.../contracts/kit_case.py (new) Running one kit case on a fresh implementation, with its outcome
.../contracts/kit_process.py (new) Running one kit case in a process of its own, built from its declared environment
.../contracts/kit_run.py (new) Running a kit: every case, both bindings, consumers N-1 and N, envelope cases
.../contracts/adapter.py (new) Public test adapters and the adapters a module's manifest requires
.../contracts/manifest.py (new) The module manifest module.toml
.../contracts/registry.py (new) Finding contracts, kits and adapters by their place
.../contracts/module.toml (new) This module's manifest
.../contracts/__init__.py, packages/contracts/pyproject.toml, README.md Package description and the manifest as package data
packages/contracts/interface-record.json (new) The record of every interface contract (empty: none exists yet)
packages/server/src/orvex/server/assembly.py (new) The assembly check before the server composes the modules
packages/server/src/orvex/server/assembly_settings.py (new) Which implementation the instance chooses per contract (assembly.toml or <SLUG>_ASSEMBLY_CONFIG)
pyproject.toml pydantic-core pinned in the runtime group
packages/server/src/orvex/server/cli.py Runs the assembly check, with the instance's choices, before startup (exit 3 when refused)
tools/checks/imports.py (new) The absolute imports a file makes (static and constant dynamic), shared by the module and consumer rules and the dynamic-import note
tools/checks/envelopes.py (new) ENVELOPE_BUILT_BY_HAND: only contracts/context.py builds an envelope (blocking)
tools/checks/consumers.py (new) Consumer boundaries (G2), report mode
tools/checks/boundaries.py Module rule now reads imports through imports.py (constant dynamic imports included); prints the consumer report
tools/checks/structure.py Its dynamic-import note uses the shared test of imports.py
tools/checks/module_dependencies.py (new) In the clean environment: imports equal declared dependencies, no repository helper in tests, adapters for every required contract
tools/ci/standalone.py (new) The standalone job (G4)
tools/contracts/interface_record.py (new) Writes and checks the interface record
tools/contracts/interface_compat.py (new) Compatibility with the last release (G3)
.github/workflows/interfaces.yml (new) Runs the record, compatibility and standalone checks
docs/adr/0033-...md, docs/adr/README.md The ADR (Proposed) and its index entry
docs/process/git-workflow.md Lists the hand-written files under packages/contracts/src/orvex/contracts/ as counted in a size
tests: packages/contracts/tests/*, packages/server/tests/test_assembly.py, tests/tools/test_{consumer_boundaries,interface_compat,standalone}.py The case matrix below
tests/contracts/test_http_api_v1.py (moved from packages/contracts/tests/) Unchanged test of the generated HTTP API types against contracts/http-api/v1/examples. Moved because it reads repository files and imports yaml, so it cannot run in the standalone environment (G4); tests/contracts is in the critical set, so it runs in pr and full as before

Shared 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 of required_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.
  • Two governed edits that are not appends: in docs/adr/README.md the existing ADR-0004 row gains "rules 2-4 amended by 0033 once accepted"; in docs/process/git-workflow.md the hand-written files of packages/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.md and docs/roadmap.md §2: not changed.

Coordinator decisions (added on this PR)

  • Aware datetimes: AwareDatetime and constrained (Annotated) types are value types; an IANA zone, a datetime.timezone and pydantic's TzInfo each come back as themselves; a naive datetime is refused (standalone, in tuples and inside models). Every generated store v1 type may now cross (test_every_generated_store_type_may_cross). Generated types of other contracts that use Any (receipt, semantic_explain, security_policies, http_api) remain refused: their steps give those fields a value type.

  • One call-context mechanism: CallContext in orvex.contracts.context refuses 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 KitCase may declare a CaseEnvironment (variables, and an ExtensionDirectory copied with or without given extensions). The case then runs in a child process built from that declaration alone and its CaseResult returns 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)

  • B6: the child gets the kit as module:NAME, checks kit.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.
  • B7: the request id is server-generated again; app.py and server_app.py are unchanged from main.
  • B8: request_context and command_context (and server/call_context.py) are removed; entry points build their CallContext in the step that wires them (ADR-0033 rule 2).
  • One envelope builder by rule: tools/checks/envelopes.py (ENVELOPE_BUILT_BY_HAND, blocking, run by boundaries) flags CallEnvelope(...) and dataclasses.replace in files naming CallEnvelope, in product code, runners and tools; kit_client plants broken envelopes through context.planted_envelope. Plants: tests/tools/test_envelope_check.py (5 planted, 5 allowed).
  • binding.py docstring states exactly who raises ContractCallRefused: a binding, and CallContext.
  • Naive datetimes are a format rule: a plain datetime annotation 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.
  • ADR-0033 writes the PLACEHOLDERS convention.
  • The select to selectors fix 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-9 can fail here on test_the_heartbeat_holds_no_secret, as it did before.
  • N2: server/assembly_settings.py reads the instance's choices ([implementations] of assembly.toml, or the file <SLUG>_ASSEMBLY_CONFIG names), and the CLI passes them to check_installed_assembly. Tests: test_assembly_settings.py, test_the_server_assembles_with_the_instance_s_configured_choice.
  • Rebased on main after docs(repo): the STRIDE threat model and the rule that keeps it current (#244) #487.

Owner action

interface-contracts and standalone are required = true in tools/ci/checks.toml, and both contexts are appended to tools/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)

  • B1: only the binding creates ContractCallRefused; any other error an implementation raises, a refusal or machinery error included, is INTERFACE_ERROR_UNDECLARED in both bindings; the kit counts only a top-level refusal of the binding. Plants: FakeRefusal, LeakedMachineryError (both bindings), FakingV10 and a cause-chain refusal (kit).
  • B2: compatibility compares each operation's error codes (INTERFACE_OPERATION_ERRORS_CHANGED) and default values. Plants: a code added, a code removed, a changed default.
  • B3: one scanner, tools/checks/imports.py, used by the module rule, the consumer rule and the dynamic-import note; the module rule catches constant import_module/__import__ (3 plants). module_dependencies.py states why it keeps its own reader.
  • B4: the repository report test asserts 0 < files <= ceiling per area (server 80, of which 48 sources as in refactor(repo): modules talk only by contract, shown by tests (G1–G5) #486 §1; runners 10; tools 7; tests 66).
  • B5: models cross field by field through the codec and are validated on rebuild; an IANA datetime inside a model is in VALUES; a tampered model is refused.
  • N1: Arrow tables cross as IPC; the format expresses the G1 result cache (get, put, size_bytes, len, Use, Stored with a table).
  • N2: assembly chooses one implementation by configuration (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.
  • N3: required operations are those with since <= provided.version.
  • N4: ADR-0033 rule 5 explains contracts.toml (data contracts, vN) beside module.toml (interface contracts, MAJOR.MINOR).
  • N6, N7: reworded purpose; defaults recorded; envelope.py uses Version.parse; required_adapters checks the contract name; every new file marked new.

Case matrix

Criterion / rejection case Test Result
Format declares operations, inputs, outputs, errors, capabilities, version, state changes, since test_interface.py::TestDescription pass
Inconsistent declaration refused (INTERFACE_CONTRACT_INVALID), incl. since outside the contract's version test_interface.py::TestRefusals::test_an_inconsistent_declaration_is_refused pass
UNSUPPORTED_OPERATION can never be declared TestRefusals::test_unsupported_operation_can_never_be_declared pass
An operation without envelope: CallEnvelope first is refused TestEnvelopeParameter (4 plants) pass
A live object cannot be declared to cross (G5) TestCrossingTypes::test_a_live_object_may_never_cross (14 types) pass
Envelope: each required field absent, empty, blank or not a string is refused before the implementation, both bindings test_envelope.py::test_a_call_missing_a_required_field_is_refused (48 cases) pass
Envelope: idempotency key required on a state-changing operation, not on a read test_an_operation_that_changes_state_needs_an_idempotency_key pass
Envelope: not an envelope, another contract, a malformed version → CONTRACT_ENVELOPE_INVALID test_anything_but_an_envelope_is_refused, test_an_envelope_for_another_contract_is_refused, test_a_version_that_is_not_major_minor_is_refused pass
Incompatible major version → CONTRACT_VERSION_UNSUPPORTED test_an_incompatible_major_version_is_refused_explicitly pass
Operation newer than the provider or the caller → CONTRACT_VERSION_UNSUPPORTED test_an_operation_newer_than_the_provider_is_refused, ..._caller_s_version_is_refused pass
Consumer N served by provider N-1 for what it has; consumer N-1 served by provider N test_a_newer_caller_is_served_by_an_older_provider_for_what_it_has, test_an_older_caller_is_served_by_a_newer_provider pass
The implementation receives the envelope (propagation) test_binding.py::TestBound::test_the_implementation_receives_the_envelope pass
Undeclared error code or any other exception → INTERFACE_ERROR_UNDECLARED TestBound::test_an_undeclared_error_is_refused_in_both_bindings pass
Kit: a correct implementation passes every case, both bindings, consumers 1.0 and 1.1 test_kit.py::TestRun::test_a_correct_implementation_passes_every_case_both_ways_by_n_and_n_1 pass
G1 plant: an implementation that fails one kit case fails TestRun::test_a_planted_implementation_failing_one_case_fails_the_kit pass
Kit: a run with one case fewer (declared or envelope) fails; a skip is a failure TestRun::test_a_run_with_one_case_fewer_fails, ..._a_skip_is_a_failure... pass
Kit refused: count differs, operation uncovered, state change without idempotency case, invalid case TestDeclarationRefusals pass
G3 plant: an operation that changes state twice for one key fails TestIdempotency::test_an_operation_that_changes_state_twice_for_one_key_fails pass
Idempotency case that observes no effect fails (proves nothing) TestIdempotency::test_a_call_without_effect_proves_nothing_and_fails pass
G3 plant: a binding that accepts an incompatible major silently fails the kit TestEnvelopeCases::test_a_binding_that_accepts_an_incompatible_major_silently_fails pass
G3 plant: a call missing an envelope field that reaches the implementation fails the kit TestEnvelopeCases::test_a_binding_that_accepts_a_call_missing_a_field_fails pass
G3 plant: a consumer at N-1 broken by an additive change fails TestVersions::test_a_consumer_at_n_1_broken_by_an_additive_change_fails pass
N-1 provider against the kit of N: newer case refused, never answered TestVersions::test_a_provider_at_n_1_passes_the_kit_of_n, ..._that_answers_a_newer_operation_is_still_refused, ..._with_a_wrong_answer_fails pass
G5 plant: an operation returning a live object fails the serializing run test_binding.py::TestPlantedLiveObject pass
Codec: every value back exactly (DECIMAL scale, HUGEINT-wide ints, zones, fold, envelope) TestCodec pass
G3 plants: removed operation, renamed error code, changed kit expectation, changed signature, moved operation, removed contract, lowered version tests/tools/test_interface_compat.py::TestPlantedViolations pass
G3: addition claiming the released version; operation that starts changing state TestCompatibleChanges::test_an_addition_claiming_the_released_version_fails, ..._starts_changing_state_fails pass
G3: no release tag fails closed; stale record fails TestRelease, TestRecord pass
G1 plant: implementation missing a required capability refused at assembly; omitted operation refused packages/server/tests/test_assembly.py pass
Server does not start when assembly is refused (exit 3) test_the_server_does_not_start_when_assembly_is_refused pass
Manifest: valid read; every invalid form refused test_manifest.py pass
G2 plants: internal imports from server, a runner, a tool and a repository test each reported; report mode does not fail; module boundary still fails tests/tools/test_consumer_boundaries.py pass
G4 plants: undeclared dependency, test import of a repository helper, required contract without adapter tests/tools/test_standalone.py pass
G4: a module runs its own operations with only its adapters; an adapter passes its whole kit; a planted failing adapter is caught test_adapter.py, test_registry.py::test_a_planted_adapter_that_fails_its_kit_is_caught pass
B1 plants: implementation fakes a refusal or leaks a machinery error; older provider fakes a refusal; refusal down a cause chain test_binding.py::TestBound::test_an_undeclared_error_is_refused_in_both_bindings, test_kit.py::TestFakedRefusals pass
B2 plants: error code added to / removed from an operation; changed default test_interface_compat.py::TestPlantedViolations pass
Module rule catches constant dynamic imports tests/tools/test_checks.py::...::test_a_constant_dynamic_import_is_reported pass
Model with IANA zone, Arrow table (decimal128, timestamp with zone, NULLs) cross exactly; tampered model refused test_binding.py::TestCodec pass
Assembly: choice among implementations, unknown choice, signature mismatch (envelope dropped, result retyped), construction invalid, operations of the provided version only packages/server/tests/test_assembly.py pass
G4: orvex-contracts installs alone outside the repository and passes its own tests python -m tools.ci.standalone contracts (job standalone) pass, 456 tests, 0 skipped

How it was verified

  • Local full verification: 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 mandatory full gate runs; it is marked ready only when a local full and CI are both green.
  • CI on the previous head 6ba558b: green. 56 checks succeeded, 6 skipped by design; one governance run was cancelled by a newer run for the same body edit, which succeeded. The successes include python-tests-3.15 and python-tests-3.14 (the full gate), python-coverage-3.15 and -3.14, interface-contracts, standalone, boundaries, governance and governance-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.
  • Tests first: at the previous implementation commit the new tests fail (9 collection errors).

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, then adapter.py, manifest.py, assembly.py, and the tools.

Time and CI-first errors

About 3.5 hours (including two interrupted local full runs). CI-first errors: 2 (python-tests-3.15-part-9: the select.select defect 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

  • G3 "producer at N-1 against consumer at N" on a released implementation: the mechanism is in place (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.
  • G2 "a consumer that names a module's storage paths or schemas": belongs to each module's step, where its storage paths are known; not in step 1.
  • N5, the standalone job running a module's contract kit: belongs to step 2, where the first module with a contract and kit exists (the contracts module has no kit of its own).
  • Wiring the assembly choice to the server configuration file: the mechanism (chosen) is in place; the configuration key arrives with the first interface that has two implementations (step 5).
  • The document corrections of refactor(repo): modules talk only by contract, shown by tests (G1–G5) #486 §6 (overview.md, AGENTS.md §5, engineering.md §2/§8, conformance pack): when ADR-0033 is accepted.

Laws touched

  • Law 3 (security by design): every call is refused before the implementation runs when its envelope is incomplete or its version unsupported (fail closed); nothing undeclared crosses a binding.
  • Law 5 (layer separation): consumers move toward contracts only; the boundary check reports every remaining internal import.
  • Law 11 (demonstrable exactness): the serializing codec keeps DECIMAL scale, integers of any width, zones and fold; tested value by value.
  • Law 10 (controlled extensibility): an implementation replaces a module only by passing its contract's whole kit.

Contracts touched

No language-neutral contract under contracts/. orvex-contracts gains 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 of orvex-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 exchanges

problem: 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 by orvex-contracts and pinned in the runtime group) · license: MIT · governance: Pydantic Services · alternative: rebuild as datetime.timezone (changes the type) · reason: exact round trip of what pydantic validates

Security (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

  • Every operation now takes the envelope as its first argument: later steps must thread it through each module's api. That is the intent of §2 item 6.
  • project_id and revision are 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

  • The pr local verification passed on a clean checkout of the commit (full runs in CI; tier A: full locally too) — pending, see "How it was verified"
  • Tests were written first and fail without the change; no existing test or criterion was lowered
  • No decisions outside the issue's specification (any open question is on the issue)
  • Tests protect this change from regression, including rejection cases
  • No TODO, dead code or commented-out code
  • No hard-coded product name; no secrets; no real company data
  • User-facing text internationalized (es, en) — not applicable, no UI text
  • UI: accessibility checks and keyboard walkthrough — not applicable

https://claude.ai/code/session_01MFyANPkiUZYq6rvGD2sFLf


Generated by Claude Code

Claude Code and others added 10 commits November 15, 2026 09:16
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
eribertocz force-pushed the refactor/486-contract-foundations branch from 6ba558b to 94bf619 Compare November 15, 2026 13:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

module:contracts module:repo module:server owner-merge Touches governed paths; only the Owner merges risk:A type:refactor Internal restructuring without behavior change

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant