Skip to content

refactor(contracts): move runtime-fact exports into their own manifest #1418

Description

@doublewhy

Gap Claim

implementations/python/packages/raes_contracts/contracts/_exports.py is 499 lines. Files under implementations/python/packages are capped at 500 lines (tools/policy/adr_policy.yaml oversized_source_files), and tools/policy/oversized_allowlist.yaml is empty and may only shrink. Publishing another contract family through the raes_contracts.contracts facade adds one import and one spread entry to this manifest. The inject-trigger and occurrence contracts for #1366 would therefore take the file to 501 lines and fail the repository policy.

Earlier families avoided the cap by keeping their names in their own manifest modules: _backend_operation_exports.py (#1388), _mixed_composition_exports.py (#1336) and _execution_policy_exports.py (#1413).

Existing Surface Audit

  • _exports.py lines 420–437 hold one contiguous family: RUNTIME_FACT_BINDING_PLANE_V1_SCHEMA_VERSION and the 17 RuntimeFact* names defined in contracts/runtime_facts.py. No other family member sits elsewhere in the manifest.
  • contracts/__init__.py imports these symbols explicitly from .runtime_facts and ._version_exports. It does not need to change.
  • implementations/python/tests/test_contracts_facade_exports.py requires contracts.__all__ == PUBLIC_EXPORTS, unique names, and a resolvable attribute for every name. test_conformance_facade_parity.py checks the facade's exported set.
  • The API reference documents individual modules with automodule, not the facade's __all__.

Alternatives

  1. Add the Publish inject-trigger and occurrence contracts #1366 names to an existing family manifest such as _backend_operation_exports.py: rejected, because it mixes unrelated families.
  2. Add _exports.py to the oversized allowlist: rejected, because the allowlist may only shrink.
  3. Move the contiguous runtime-fact family into _runtime_fact_exports.py and spread it at the same position: selected.

Chosen Architecture

Add _runtime_fact_exports.py defining RUNTIME_FACT_EXPORTS with the same 18 names in the same order, following _mixed_composition_exports.py. _exports.py imports it and spreads it where the names were. PUBLIC_EXPORTS keeps identical membership and order, so no public name, schema, fixture or runtime behavior changes. _exports.py drops to 483 lines.

Verification Plan

  • Compare PUBLIC_EXPORTS before and after the change for identical order and membership.
  • Run test_contracts_facade_exports.py and test_conformance_facade_parity.py.
  • Run repository fast feedback against origin/dev.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions