Metadata-Version: 2.5
Name: omnibase-compat
Version: 0.5.7
Summary: Thin shared structural package for cross-repo enums, wire DTOs, event envelopes, primitives, and experimental schemas.
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: pydantic>=2.11.7
Requires-Dist: typing-extensions>=4.5.0
Provides-Extra: dev
Requires-Dist: mypy>=1.9; extra == 'dev'
Requires-Dist: pre-commit; extra == 'dev'
Requires-Dist: pytest-cov; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/brand/omninode-inline-white.png">
    <source media="(prefers-color-scheme: light)" srcset="docs/assets/brand/omninode-inline-full-color.svg">
    <img alt="omninode" src="docs/assets/brand/omninode-inline-full-color.svg" width="420">
  </picture>
</p>

# omnibase_compat

`omnibase_compat` is the thin shared structural package for cross-repo enums,
wire DTOs, event envelopes, concurrency helpers, and compatibility primitives.

It has zero OmniNode upstream runtime dependencies. Runtime dependencies are
limited to third-party structural support packages listed in `pyproject.toml`.

[![CI](https://github.com/OmniNode-ai/omnibase_compat/actions/workflows/ci.yml/badge.svg)](https://github.com/OmniNode-ai/omnibase_compat/actions/workflows/ci.yml)
[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Who Uses It

Use this package when two or more OmniNode repos need to share stable structural
types without creating an import cycle through `omnibase_core`,
`omnibase_spi`, or `omnibase_infra`.

Common consumers include dashboard, intelligence, memory, market, infrastructure,
and governance repos that need shared event envelopes, status enums, routing
DTOs, or transitional compatibility shims.

## What This Repo Owns

- Cross-repo structural DTOs and wire models
- Minimal event envelopes intended for cross-repo transport compatibility
- Minimal enum copies with explicit source provenance
- Concurrency and environment primitives that do not depend on OmniNode runtime packages
- Experimental artifacts with ticket and review milestone metadata
- Temporary migration shims with `COMPAT_MIGRATION_TARGET` and `COMPAT_REMOVAL_DATE`

## What This Repo Does Not Own

- Runtime execution, node behavior, validators, and implementation helpers. Those belong in `omnibase_core`.
- Protocol interfaces that implementations satisfy. Those belong in `omnibase_spi`.
- Concrete infrastructure, clients, storage, registration operations, or runtime host behavior. Those belong in `omnibase_infra`.
- Domain-specific workflow ownership. That belongs in the relevant domain repo, such as `omnimarket`, `omnimemory`, or `omniintelligence`.

## Install

```bash
uv add omnibase-compat
```

For local development:

```bash
uv sync --dev --frozen
```

## Usage

```python
from omnibase_compat.enums.enum_message_category import EnumMessageCategory
from omnibase_compat.enums.enum_node_kind import EnumNodeKind
from omnibase_compat.models.event_envelope import EventEnvelopeV1Minimal
```

Import from explicit submodules. Treat package-root exports as convenience
exports only, not the stable compatibility surface.

## Dependency Boundary

`omnibase_compat` must not import these packages at runtime:

- `omnibase_core`
- `omnibase_spi`
- `omnibase_infra`

CI enforces this with:

```bash
uv run python scripts/validate_no_upstream_deps.py
```

Do not add `omnibase_core` only to make documentation validation convenient.
Docs validation should run through standalone CI tooling or from the repo that
owns the validator entrypoint. If this repo adopts `onex-validate-links`, it
must remain dev-only tooling and must not change runtime dependencies.

## Role vs `omnibase_spi`

| Layer | Purpose |
|-------|---------|
| `omnibase_spi` | Protocols and abstract interfaces that service implementations must satisfy |
| `omnibase_compat` | Shared enums, wire DTOs, event envelopes, and structural types across repo boundaries |

Rule of thumb: protocols go in `omnibase_spi`; structural data that crosses repo
boundaries goes in `omnibase_compat`.

## Common Workflows

```bash
uv run python scripts/validate_no_upstream_deps.py
uv run python scripts/check_compat_retention.py
uv run ruff check src/
uv run mypy src/omnibase_compat --strict
uv run pytest -m unit --tb=short
uv build
```

Release workflow:

```bash
git tag vX.Y.Z
git push origin vX.Y.Z
```

The tag must match `[project].version` in `pyproject.toml`. On a successful
non-`rc` release the workflow fast-forwards `main` to the released tag — there
is no separate promotion pull request. See the
[release runbook](https://github.com/OmniNode-ai/knowledge-base/blob/main/runbooks/omnibase-compat-release.md)
for the full procedure, the workflow's guarantees, and failure handling.

## Key Features

- Zero dependency on `omnibase_core`, `omnibase_spi`, or `omnibase_infra` (CI-enforced)
- Experimental artifact registry with lifecycle governance (`ticket` + `review_milestone` required)
- Provenance-tracked enum seeding from upstream canonical sources
- Strict mypy + ruff + AST-based import validation

## Documentation

This repository holds no documentation directory. Every prose document about
`omnibase_compat` — architecture, structural inventory, runbooks, guides — lives
in the OmniNode knowledge base, which is its single home.

Full documentation → https://github.com/OmniNode-ai/knowledge-base

| Topic | Where |
|---|---|
| Structural inventory — subpackages, wire DTOs, enums, dependency boundary, validation scripts | [reference/omnibase-compat-structural-inventory.md](https://github.com/OmniNode-ai/knowledge-base/blob/main/reference/omnibase-compat-structural-inventory.md) |
| Release procedure — tag, dispatch, workflow guarantees, failure handling | [runbooks/omnibase-compat-release.md](https://github.com/OmniNode-ai/knowledge-base/blob/main/runbooks/omnibase-compat-release.md) |

Internal-only material — anything the public knowledge base excludes by
taxonomy (our own cloud deployment topology, restricted operational notes) —
lives in the internal knowledge base:
https://github.com/OmniNode-ai/knowledge-base-internal

What remains in this repository is only what must physically ship beside the
code, and the [KB doc gate](.github/workflows/kb-doc-gate.yml) enforces that set
in `strict` mode:

- [CLAUDE.md](CLAUDE.md) — agent operating context and repo conventions
- [.github/CONTRIBUTING.md](.github/CONTRIBUTING.md) — contribution flow
- [CHANGELOG.md](CHANGELOG.md)
- [SECURITY.md](SECURITY.md)

## License

See [LICENSE](LICENSE).
