# `mgf-apiprobe` — Federation conformance ack

This document is `mgf-apiprobe`'s acknowledgment of `mgf-common`'s
federation rules. It mirrors the shape of
[`mgf-common`'s `LIFT_CHECKLIST.md`](https://codeberg.org/magogi-admin/mgf-common/src/branch/main/docs/LIFT_CHECKLIST.md)
but is read in the OPPOSITE direction — `mgf-common`'s doc covers
**lifting** components INTO `mgf-common` from consumers; this doc
covers `mgf-apiprobe` **shipping AS** a federation sibling that
depends on `mgf-common`.

---

## 1. Federation rules `mgf-apiprobe` commits to

### 1.1 One-way dependency

`mgf-apiprobe` depends on `mgf-common`. It does NOT import from any
other federation sibling (`mgf.qt`, `mgf.cli`, etc., when those
materialize). Enforced by `.importlinter` contract
`mgf-apiprobe-only-imports-from-mgf-common`.

- [x] `pyproject.toml` declares `mgf-common>=0.12,<0.13` under `[project.dependencies]`.
- [x] `.importlinter` ships the federation-member contract.
- [x] No `import mgf.<other_sibling>` anywhere in `src/`.

### 1.2 Namespace shape

`mgf-apiprobe` distributes under the `mgf.*` PEP 420 namespace as
`mgf.apiprobe`. The wheel ships `src/mgf/` WITHOUT a top-level
`__init__.py` so the namespace stays open for future siblings.

- [x] `pyproject.toml` `[tool.hatch.build.targets.wheel]` packages
  `["src/mgf"]`.
- [x] No `src/mgf/__init__.py` exists.
- [x] `src/mgf/apiprobe/__init__.py` defines the public surface.

### 1.3 Closed-box invariant

Consumers of `mgf-apiprobe` import from `mgf.apiprobe` (the public
surface) — never from `mgf.apiprobe._*` private modules.

- [ ] `src/mgf/apiprobe/__init__.py` re-exports every public name.
- [ ] Every private module is underscore-prefixed.
- [ ] `tests/public_surface/` enforces the rule via AST pin
  (graduates with L2 conformance).

### 1.4 Standards conformance

L1 day-one, L2 graduation later. Per `HANDOFF.md` §3.3:

| Gate | L1 | L2 | Status |
|---|---|---|---|
| `BaseAppSettings` subclass | ✓ | ✓ | scaffolded |
| `AppError` hierarchy | ✓ | ✓ | scaffolded |
| Structured logging + redaction (via `mgf.common.observability`) | ✓ | ✓ | scaffolded |
| `__all__` discipline + py.typed | ✓ | ✓ | scaffolded |
| Semver | ✓ | ✓ | scaffolded |
| Mirrored test layout | ✓ | ✓ | scaffolded |
| Coverage | ≥80% | ≥85% | gate set in `pyproject.toml` |
| `mypy --strict` | ✓ | ✓ | configured |
| `ruff check` | ✓ | ✓ | configured |
| `lint-imports` | ✓ | ✓ | configured |
| Property tests on matchers / redactors / signing / diff | — | ✓ | future |
| `PUBLIC_API.md` + AP-10 sync test | — | ✓ | future |
| AST-pinned public surface (`tests/public_surface/`) | — | ✓ | future |
| OTel correlation on every span | — | ✓ | future |

### 1.5 Coverage tooling — `coverage run`, NOT `pytest --cov`

Per `HANDOFF.md` §9 foot-gun #7 + the `mgf-common` incident:
`pytest --cov` under-reports because pytest's collection imports
run before pytest-cov starts collection.

- [x] `pyproject.toml` `[tool.coverage.run]` configured.
- [x] CI (when configured) runs `coverage run -m pytest` then
  `coverage report --fail-under=80`.

### 1.6 Versioning

Pre-1.0 — minor bumps may include breaking changes. Pre-1.0 public
symbols are `experimental` per AP-* until the package graduates.

---

## 2. When this file gets updated

- A federation rule changes in `mgf-common` (e.g., a new contract
  in `mgf-common`'s `.importlinter` that siblings must mirror).
- `mgf-apiprobe` graduates a tier (L1 → L2 — flip the L2 checkboxes
  in §1.4).
- A new federation sibling appears (`mgf.cli`, `mgf.qt`, etc.) and
  the `mgf-apiprobe-only-imports-from-mgf-common` contract grows a
  new forbidden line.

---

## 3. References

- [`HANDOFF.md`](HANDOFF.md) — the integration plan; §3.5 covers
  the federation contract.
- [`DESIGN.md`](DESIGN.md) — the spec.
- [`mgf-common`'s `LIFT_CHECKLIST.md`](https://codeberg.org/magogi-admin/mgf-common/src/branch/main/docs/LIFT_CHECKLIST.md)
  — the reverse-direction document (lifting components INTO
  `mgf-common` from consumers).
- [`mgf-common`'s `docs/standards/SCOPE.md`](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/SCOPE.md)
  — the federation-wide scope policy.
