Skip to content

fix(OMN-12725): preflight runtime projection schema - #1875

Merged
jonahgabriel merged 2 commits into
devfrom
jonah/omn-12725-runtime-projection-schema-preflight
Jun 6, 2026
Merged

jonahgabriel merged 2 commits into
devfrom
jonah/omn-12725-runtime-projection-schema-preflight

Conversation

@jonahgabriel

@jonahgabriel jonahgabriel commented Jun 5, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

  • Apply node-owned forward migrations to the runtime projection database omnidash_analytics instead of only omnibase_infra.
  • Require delegation_events and node_service_registry in the migration gate and runtime deploy preflight before runtime startup.
  • Preserve migration-gate dependencies in stability/prod runtime overlays and vendor missing savings projection base migrations for clean projection DB application.

Verification

  • bash -n scripts/deploy-runtime.sh && sh -n scripts/run-forward-migrations.sh && sh -n scripts/check_migrations_complete.sh
  • uv run ruff check on changed Python source and test files: passed
  • OMNI_HOME=/Users/jonah/Code/omni_home uv run pytest focused migration/runtime deploy suite: 65 passed

Notes

  • No live .201 mutation was performed in this PR. This is the durable fix for the dev projection schema blocker discovered during delegation integration.

Evidence-Source: fa346609063f237721566746f2168c4890122091
Evidence-Ticket: OMN-12725

Summary by CodeRabbit

  • New Features

    • Added migration gate health checks to ensure all required projection tables are validated before runtime services start.
    • Introduced savings estimates tracking capability with automatic timestamp management.
  • Bug Fixes

    • Made uptime seconds column nullable in node service registry.
  • Chores

    • Enhanced migration validation to support separate node projection database.
    • Updated runtime service startup dependencies to wait for migration completion.
    • Improved migration preflight verification for required projection tables.

@coderabbitai

coderabbitai Bot commented Jun 5, 2026 •

Copy link
Copy Markdown

Lost in the diff? Review this PR in Change Stack to follow the change map from intent to exact ranges.

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 880abcf2-cdfb-4abf-a6dc-dead6f0490ee

📥 Commits

Reviewing files that changed from the base of the PR and between 187dcfc and b431c5e.

📒 Files selected for processing (21)
  • docker/catalog/services/forward-migration.yaml
  • docker/catalog/services/migration-gate.yaml
  • docker/docker-compose.infra.yml
  • docker/docker-compose.prod.yml
  • docker/docker-compose.stability-test.yml
  • docker/migrations/forward/nodes/.synced-nodes
  • docker/migrations/forward/nodes/node_projection_registration/0000_create_node_service_registry.sql
  • docker/migrations/forward/nodes/node_projection_savings/074_create_savings_estimates.sql
  • docker/migrations/forward/nodes/node_projection_savings/075_add_savings_estimates_updated_at.sql
  • scripts/check_migrations_complete.sh
  • scripts/deploy-agent/deploy_agent/executor.py
  • scripts/deploy-agent/tests/unit/test_executor_lane_selection.py
  • scripts/deploy-agent/tests/unit/test_executor_runtime_health_verify.py
  • scripts/deploy-agent/tests/unit/test_executor_runtime_scope.py
  • scripts/deploy-runtime.sh
  • scripts/run-forward-migrations.sh
  • tests/integration/infra/test_stability_test_runtime_compose_render.py
  • tests/unit/infra/test_catalog_generator.py
  • tests/unit/infra/test_stability_test_runtime_lane.py
  • tests/unit/migrations/test_node_migration_discovery.py
  • tests/unit/runtime/test_migration_sentinel.py

📝 Walkthrough

Walkthrough

The PR establishes a gated runtime startup pattern by introducing a separate node projection database, extending the migration infrastructure to populate it, verifying projection table availability via health checks, and wiring runtime service startup dependencies on those checks.

Changes

Runtime Startup Gating on Projection Table Availability

Layer / File(s) Summary
Projection schema and migrations
docker/migrations/forward/nodes/node_projection_savings/074_create_savings_estimates.sql, 075_add_savings_estimates_updated_at.sql, docker/migrations/forward/nodes/node_projection_registration/0000_create_node_service_registry.sql, docker/migrations/forward/nodes/.synced-nodes, tests/unit/migrations/test_node_migration_discovery.py
Creates savings_estimates table with UUID, audit timestamps, cost/savings columns, unique identity index, and auto-updated updated_at trigger. Removes NOT NULL from node_service_registry.uptime_seconds. Broadens vendoring to include all node projection migrations.
Node projection database migration execution
scripts/run-forward-migrations.sh, docker/catalog/services/forward-migration.yaml, docker/docker-compose.infra.yml, tests/unit/migrations/test_node_migration_discovery.py
Introduces NODE_POSTGRES_DB environment variable (default omnidash_analytics) and applies node-owned migrations to a separate projection database via NODE_PGDB while maintaining infra database migrations in public schema.
Migration completeness and projection table health checks
scripts/check_migrations_complete.sh, docker/catalog/services/migration-gate.yaml, docker/docker-compose.infra.yml, tests/unit/runtime/test_migration_sentinel.py
Extends check_migrations_complete sentinel to validate required projection tables (delegation_events, node_service_registry) exist in omnidash_analytics via Postgres to_regclass checks after confirming infra migrations are complete.
Runtime service startup gating and preflight orchestration
docker/docker-compose.prod.yml, docker/docker-compose.stability-test.yml, scripts/deploy-agent/deploy_agent/executor.py, scripts/deploy-runtime.sh, tests/integration/infra/test_stability_test_runtime_compose_render.py, tests/unit/infra/test_catalog_generator.py, tests/unit/infra/test_stability_test_runtime_lane.py
Wires runtime services (omninode-runtime, runtime-effects, runtime-worker) to depend on migration-gate becoming healthy in both prod and stability-test overlays. Adds deploy-agent executor preflight (_ensure_runtime_migrations_ready) and deploy-runtime script preflight (run_runtime_migration_preflight) that run one-shot migration services and validate projection tables before spawning runtime.
Test coverage for gating and health verification
scripts/deploy-agent/tests/unit/test_executor_lane_selection.py, scripts/deploy-agent/tests/unit/test_executor_runtime_health_verify.py, scripts/deploy-agent/tests/unit/test_executor_runtime_scope.py
Updates lane selection and health verification tests to mock the new preflight method, use generic projection table detection helpers, and verify runtime-scoped compose operations include the migration preflight sequence before targeting runtime services.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

  • OmniNode-ai/omnibase_infra#1593: Adds the omnimarket-projection-delegation consumer that populates omnidash_analytics.delegation_events, one of the required projection tables that the main PR now validates during startup.
  • OmniNode-ai/omnibase_infra#1843: Vendors node projection registration migrations that create node_service_registry, which the main PR updates with nullable uptime_seconds and gates runtime startup on.
  • OmniNode-ai/omnibase_infra#1820: Introduces namespaced auto-discovery of node-owned migrations; the main PR extends that execution to target the dedicated projection database and add preflight validation.

🐰 Runtime gates now stand guard,
Projection tables checked and barred,
Migrations flow through dashboards bright,
Before the services see the light! ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 24.00% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title 'fix(OMN-12725): preflight runtime projection schema' clearly and specifically summarizes the main change: adding a preflight check for runtime projection schema migrations.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch jonah/omn-12725-runtime-projection-schema-preflight

Comment @coderabbitai help to get the list of available commands and usage tips.

@jonahgabriel
jonahgabriel changed the base branch from main to dev June 5, 2026 22:51
@jonahgabriel

Copy link
Copy Markdown
Collaborator Author

Central OCC evidence for OMN-12725 is now in onex_change_control PR #2209: OmniNode-ai/onex_change_control#2209. This should unblock the Receipt Gate after OCC evidence merges and the downstream gate is rerun.

@jonahgabriel
jonahgabriel enabled auto-merge June 5, 2026 23:31
@jonahgabriel
jonahgabriel added this pull request to the merge queue Jun 6, 2026
Merged via the queue into dev with commit 9e2af41 Jun 6, 2026
94 of 95 checks passed
@jonahgabriel
jonahgabriel deleted the jonah/omn-12725-runtime-projection-schema-preflight branch June 6, 2026 00:21
jonahgabriel added a commit that referenced this pull request Jul 10, 2026
Add 'onex occ' command group (stamp + validate) as an onex.cli entrypoint
(omnibase_infra.cli.cli_occ), the local/pre-commit shift-left of CI's
receipt-gate. Owns ZERO stamp logic: parsing/rendering is delegated to the
canonical OCC stamp schema in omnibase_compat.contracts.pr_occ_stamp (relocated
there from omnibase_core under OMN-14223); this is click plumbing + fail-closed
assertions + idempotent-insert glue.

- 'onex occ validate [FILES|--stdin]': fail-closed — missing/malformed
  Evidence-Source or Evidence-Ticket exits non-zero with an actionable message.
- 'onex occ stamp [FILE] --ticket OMN-N --evidence-source OCC#N|sha [--in-place]':
  idempotent insert of the canonical Evidence block (stamp(stamp(x))==stamp(x)).
- Accepted token shapes validated by round-tripping through the compat parser.

Adds omnibase-compat==0.5.6 as a new dependency (project deps + [tool.uv]
override). No omnibase-core bump.

Paired with omniclaude PR #1875 (thin pre-commit hook calling 'onex occ validate').

BLOCKED ON: omnibase-compat 0.5.6 release to PyPI (compat OMN-14223 / PR#173).
Until then uv sync/CI cannot resolve the pin; local gates verified against the
0.5.6 build. uv.lock update to PyPI 0.5.6 is a post-release follow-up.

OCC companion: pending independent verifier (implementer does not self-author evidence).
jonahgabriel added a commit that referenced this pull request Jul 10, 2026
* feat(OMN-14190): onex occ stamp/validate CLI for OCC PR metadata

Add 'onex occ' command group (stamp + validate) as an onex.cli entrypoint
(omnibase_infra.cli.cli_occ), the local/pre-commit shift-left of CI's
receipt-gate. Owns ZERO stamp logic: parsing/rendering is delegated to the
canonical OCC stamp schema in omnibase_compat.contracts.pr_occ_stamp (relocated
there from omnibase_core under OMN-14223); this is click plumbing + fail-closed
assertions + idempotent-insert glue.

- 'onex occ validate [FILES|--stdin]': fail-closed — missing/malformed
  Evidence-Source or Evidence-Ticket exits non-zero with an actionable message.
- 'onex occ stamp [FILE] --ticket OMN-N --evidence-source OCC#N|sha [--in-place]':
  idempotent insert of the canonical Evidence block (stamp(stamp(x))==stamp(x)).
- Accepted token shapes validated by round-tripping through the compat parser.

Adds omnibase-compat==0.5.6 as a new dependency (project deps + [tool.uv]
override). No omnibase-core bump.

Paired with omniclaude PR #1875 (thin pre-commit hook calling 'onex occ validate').

BLOCKED ON: omnibase-compat 0.5.6 release to PyPI (compat OMN-14223 / PR#173).
Until then uv sync/CI cannot resolve the pin; local gates verified against the
0.5.6 build. uv.lock update to PyPI 0.5.6 is a post-release follow-up.

OCC companion: pending independent verifier (implementer does not self-author evidence).

* chore(OMN-14190): regen uv.lock for omnibase-compat 0.5.6

pyproject.toml added omnibase-compat==0.5.6 as a new dependency
(canonical home of the OCC stamp schema, OMN-14223) but uv.lock had
never been regenerated to include it. compat 0.5.6 is now live on
PyPI — add it to the lock so frozen sync resolves cleanly.

* ci(OMN-14190): re-trigger occ-preflight against stamped body (edited-trigger gap OMN-14241)

* fix(ci): refresh runner image identity lock
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant