Skip to content

Add public server_core API surface and enforce no-private-imports#402

Open
mikemol wants to merge 1 commit intostagefrom
codex/refactor-server-module-for-public-api
Open

Add public server_core API surface and enforce no-private-imports#402
mikemol wants to merge 1 commit intostagefrom
codex/refactor-server-module-for-public-api

Conversation

@mikemol
Copy link
Copy Markdown
Owner

@mikemol mikemol commented Mar 6, 2026

Motivation

  • Remove server-level reliance on underscore-prefixed server_core internals and provide a stable public contract grouped by concern (ingress, timeout, progress, report serialization) for clearer boundaries.
  • Prevent non-owning modules from importing private server_core symbols by adding a policy scanner rule and tests to lock the new contract surface.

Description

  • Introduced a public API layer in src/gabion/server_core/command_orchestrator_primitives.py (e.g. ingress_*, timeout_*, progress_*, report_*, plan_materialize_execution_plan, deps_default_execute_command) and exported those names via __all__.
  • Added public aliases/constants in src/gabion/server_core/dataflow_runtime_contract.py (e.g. PROGRESS_*, INGRESS_*, TIMEOUT_*, REPORT_*) to surface runtime contract values and callables.
  • Rewired src/gabion/server.py to call the new public primitives and collapsed trivial pass-through wrappers into direct alias bindings while retaining boundary-normalization and command registration responsibilities.
  • Updated CLI wiring in src/gabion/cli.py and corresponding tests to use the new public response normalization/serialization symbols instead of private imports.
  • Extended policy scanner scripts/policy/private_symbol_import_guard.py to detect private gabion.server_core symbol usage via aliased module attributes and to exempt owner-module usage; added focused tests to validate detection and owner exemptions.
  • Added targeted tests tests/gabion/commands/test_server_core_public_api.py and adjustments in existing CLI and policy tests to lock the new public contract and prevent regressions.

Testing

  • Ran the repo policy checks with PYTHONPATH=src:. python scripts/policy/policy_check.py --workflows and --ambiguity-contract, both completed successfully.
  • Ran the private-import scanner with PYTHONPATH=src:. python scripts/policy/private_symbol_import_guard.py --check --out out/private_symbol_import_report.json and iteratively fixed findings until new=0 (no new non-exempt private imports reported).
  • Ran targeted pytest invocations with PYTHONPATH=src:. python -m pytest -o addopts='' against the modified test files and related parity suites, and the selected test set passed (all targeted tests passed across the CLI, policy, server_core parity and new public-api tests).
  • No automated tests failed after the final changes; the focused test runs completed successfully.

Codex Task

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

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant