# `mgf-apiprobe` — Scope policy

> **Propagation (DOC-18):** repo-local standard (independent of mgf-common's SCOPE.md; not part of the mgf-standard corpus). When a rule here changes, update its in-repo dependents — DESIGN.md, the docs/standards/README index, and any check/module it governs in this repo.

> **Audience:** anyone proposing a new module, check, or extension to `mgf-apiprobe`.

This document is `mgf-apiprobe`'s scope policy. It is INDEPENDENT of
`mgf-common`'s `SCOPE.md` (which governs what belongs in
`mgf-common`); it covers what belongs in this sibling.

For the WHAT (primitives, checks, full vision), see [`DESIGN.md`](../../DESIGN.md).
This document is the WHETHER — should a proposed addition exist in
this package at all.

---

## Rules box

- **SP-AP-01** — Every PR adding a new module MUST justify against §1
  (IN), §3 (Adjacent), or §2 (OUT) of this file.
- **SP-AP-02** — A module that crosses INTO `mgf-common`'s SCOPE.md §1
  (e.g., a generic settings layering helper, a new logging primitive)
  belongs in `mgf-common`, NOT here. File a `mgf-common` LIFT_CHECKLIST
  PR instead.
- **SP-AP-03** — A check whose `code` enters the public catalogue is a
  PUBLIC CONTRACT; renaming or deleting it post-publication is a
  breaking change (rule AP-04 mirror).

---

## §1 IN scope

The list below is what `mgf-apiprobe` IS. Items in §1 MUST satisfy:

> "Every consumer talking to or exposing a REST API needs this by the
> time they go to production, AND no single ecosystem alternative
> covers the curated, infrastructure-grade shape `mgf-apiprobe` ships."

- **Probes** — typed descriptions of an HTTP request + the expected
  response shape.
- **Checks** — verifiers that emit structured `Finding` objects (code,
  severity, root_cause, evidence, remediation, threat_refs, tags).
- **Suites** — collections of probes that run async and produce a
  `Report`.
- **Contexts** — request-shared state (variables, factories, auth).
- **AuthFlows** — bearer / basic / api-key / cookie / custom; OAuth2
  flows (client-credentials, auth-code, device-code) are a future add.
- **Matchers** — DSL for asserting response shape (primitives + format
  + semantic; IBAN / IMEI / E.164 because they're load-bearing for
  telecom-style APIs).
- **Factories** — built-ins (UUID, ISO 8601 timestamps, IBAN, IMEI,
  E.164); Faker integration is a future add.
- **Schema sources** — Pydantic; OpenAPI 3.0/3.1 and JSON Schema are
  future adds.
- **Replay / cassette subsystem** — record + replay with redaction +
  cassette signing.
- **Drift detection** — report diff, cassette diff, spec drift,
  spec-vs-spec, dual-target.
- **Mutation testing** — `Mutation` ABC + built-in mutations.
- **Plugin discovery via stdlib `importlib.metadata.entry_points`** —
  entry-point groups namespaced `mgf_apiprobe.<group>`.
- **CLI** — `apiprobe run`, `apiprobe checks`, `apiprobe doctor`;
  full set (`probe`, `diff`, `drift`, `cassette`, `snapshot`,
  `mutate`, `scaffold`, `bisect`, `report`) is a future add.
- **Report writers** — console + JSON; markdown / JUnit / SARIF /
  Slack / Discord / Teams / PagerDuty / GitHub PR / GitLab MR /
  Codeberg PR / CSV / Prometheus are future adds.
- **pytest plugin** — fixtures + per-finding test-case generation.
- **Observability** — uses `mgf.common.observability` (logging + OTel +
  redaction + crash reporter); explicit per-primitive OTel span
  hierarchy + Prometheus metrics are future adds.

---

## §2 OUT of scope

| OUT item | Reason | Ecosystem alternative |
|---|---|---|
| **Test runner / discovery / collection** | pytest is the ecosystem default. `mgf-apiprobe` produces `Finding` objects that pytest consumes via the v0.6 plugin; it does NOT replace pytest. | pytest |
| **Load testing** | Different concern (sustained load, percentiles, ramp) with mature tools. | locust, k6, Vegeta |
| **Full property-based fuzzing of OpenAPI specs** | Schemathesis covers this depth; we plug in (a Schemathesis-backed `Mutation` is on the post-v1.0 list). | schemathesis |
| **Browser automation / E2E UI testing** | Different concern entirely. | playwright, cypress, selenium |
| **GUI frontend** | Out of scope for now — likely Tauri + SvelteKit when it lands. | Bruno, Postman, Insomnia |
| **Generic plugin loader / framework** | stdlib `importlib.metadata.entry_points` is sufficient. We don't ship a custom plugin host. | `importlib.metadata.entry_points` |
| **Components that belong in `mgf-common`** | Settings layering, logging setup, crash reporter, vault, exception hierarchy. We REUSE `mgf-common`'s versions; we do NOT re-implement them. (HANDOFF §3.2 has the per-surface inversion table.) | `mgf-common` |
| **Cross-sibling imports** | `mgf-apiprobe` is a federation MEMBER, not a federation HUB. It MUST NOT import from `mgf.qt`, `mgf.cli`, etc. (enforced by `.importlinter`). | N/A — design constraint |
| **Postgres / S3 / OCI cassette stores** | Niche; file-backed store covers the common case. Revisit if real consumer demand surfaces. | consumer-side |
| **AWS SigV4 / Google JWT auth** | Niche; revisit if real consumer demand surfaces. Until then, custom AuthFlow + `boto3` / `google-auth` works. | boto3 / google-auth |

---

## §3 Adjacent

Work that is adjacent to `mgf-apiprobe` — could land here OR
elsewhere. Promotion to §1 requires explicit demand.

- **Domain-specific matchers** (Teltonika tracker payload, MapTiler
  tile URL shape, Stripe event envelope, etc.). Default: external;
  consumers ship their own. Promote here only when ≥2 unrelated
  consumers want the same one.
- **Cassettes for popular providers** (`[apiprobe-cassettes-stripe]`
  etc.). Default rejection; revisit if external demand surfaces.
- **Apiprobe-as-a-service** (long-running daemon with a web UI for
  scheduled runs). Currently out of scope; revisit if demand
  surfaces.

---

## §4 Decision flow for a new module

```
┌──────────────────────────────────────────────────────────────┐
│ Q: Is the new thing about VERIFYING REST APIs?               │
│   Yes → §1 IN candidate (continue)                           │
│   No  → STOP. Wrong package. Find the right home (mgf-common,│
│         a new sibling, a consumer) and propose there.        │
├──────────────────────────────────────────────────────────────┤
│ Q: Is it generic infrastructure (settings, logging, errors)? │
│   Yes → STOP. Lift to mgf-common via its LIFT_CHECKLIST.     │
│   No  → continue                                             │
├──────────────────────────────────────────────────────────────┤
│ Q: Does it duplicate an ecosystem default (pytest, k6,       │
│    schemathesis, browser automation)?                        │
│   Yes → STOP. §2 OUT. Defer to the ecosystem.                │
│   No  → continue                                             │
├──────────────────────────────────────────────────────────────┤
│ Q: Is it on DESIGN.md's roadmap?                             │
│   Yes → §1 IN                                                │
│   No  → §3 Adjacent; needs ≥2 consumer demand to promote     │
└──────────────────────────────────────────────────────────────┘
```

---

## §5 References

- [`mgf-common`'s `SCOPE.md`](https://codeberg.org/magogi-admin/mgf-standard/src/branch/main/docs/standards/SCOPE.md)
  — federation-wide scope policy. The "Testing framework" OUT bullet
  there pairs with §2 here.
- [`HANDOFF.md`](../../HANDOFF.md) §2 — why apiprobe is a sibling, not
  a subpackage.
- [`DESIGN.md`](../../DESIGN.md) — the WHAT.
