# Performance & Capacity

> **Status:** initial — opened 2026-06-14 (Pass 1 scaffold). **No
> items yet.**
> A federation-sibling-scoped performance tracker for `mgf-cloud`.
> The repo is new at **0.1.0**; the core abstraction, the
> Infomaniak adapter, the CLI, and the web GUI land in Passes 2–5,
> so there is **no performance surface to audit yet**. This file
> establishes the canonical tracker shape; items get opened as the
> surface lands.
>
> **Scope (when populated):** mgf-cloud's OWN performance
> footprint — keeping `import mgf.cloud` light (no provider SDK at
> import time), live-query latency against the provider, list /
> pagination cost, and the bootstrap cost the CLI pays per
> invocation. NOT a re-audit of mgf-common's PC items. NOT an audit
> of the provider SDKs or the cloud platform.
>
> **Audience:** the maintainer + future AI agents doing
> performance work on this sibling.
> **Cross-references:**
> [`RELIABILITY_AND_ACCURACY.md`](RELIABILITY_AND_ACCURACY.md),
> [`SECURITY_HARDENING.md`](SECURITY_HARDENING.md),
> [`../design/DESIGN.md`](../design/DESIGN.md) (the architecture +
> the core-light invariant),
> [`mgf-common/docs/inprogress/PERFORMANCE_AND_CAPACITY.md`](https://codeberg.org/magogi-admin/mgf-common/src/branch/main/docs/inprogress/PERFORMANCE_AND_CAPACITY.md)
> (cornerstone tracker — its PC items apply to consumers who pull
> mgf-common transitively).

---

## §1 You are here

`mgf-cloud` is at 0.1.0 (Pass 1 — the conformant scaffold). The
only code today is the `__init__` + `__main__` CLI dispatch
skeleton; there is no provider adapter, no live-query path, and no
web GUI to measure. **No performance data exists yet, and no items
are open.**

The first performance-relevant surfaces arrive with:

- **Pass 2** — the provider abstraction (`models`, `config`,
  `providers.base`). The load-bearing invariant to protect is
  **core-light**: `import mgf.cloud` MUST NOT pull a provider SDK
  (enforced by the import-linter contract; see DESIGN §3.2).
- **Pass 3** — the Infomaniak adapter on openstacksdk: live-query
  latency, list/pagination cost, the cost of `mgf:owner` tag
  filtering.
- **Pass 4 / 5** — the CLI per-invocation startup cost and the
  local web GUI's per-request overhead.

**Counts (2026-06-14):**

| Priority | Open | Closed | Total |
|---|---|---|---|
| P0 — blockers | 0 | 0 | 0 |
| P1 — should land before/with 1.0 | 0 | 0 | 0 |
| P2 — hardening | 0 | 0 | 0 |
| **Total** | **0** | **0** | **0** |

**Do first:** nothing yet — open the first PC item when Pass 2
gives it a surface to measure.

---

## §2 Priority table

_No items yet._ Each item, when opened, carries a falsifiable
budget + the pinned test that locks it in.

| ID | Theme | One-liner | Effort | Status |
|---|---|---|---|---|
| _(none)_ | — | — | — | — |

Effort scale: XS (≤ 15 min); S (≤ 1 h); M (≤ 1 session).

---

## §3 Invariants we hold

The list of "closed elsewhere; do not re-open" — populated as the
surface lands. The first one is already a design commitment:

- **PC-INV-1 (design intent)** — `import mgf.cloud` is **light**:
  it pulls no provider SDK and no web framework. Adapters load
  lazily behind their extras (`get_provider(name)` does an
  `importlib`-style lazy import). Enforced by the `.importlinter`
  contract (tightened in Pass 2). See
  [`../design/DESIGN.md`](../design/DESIGN.md) §3.2.

---

## §4 Work units

_No work units yet._ When the first item opens, follow the
canonical shape: **Why** (with `file:line` evidence) → **Concrete
output** (the falsifiable budget + the test that pins it) →
**Locked in by** → **Cross-references** → **Status**.

---

## §5 Closed items

_None yet._

---

## §6 Notes on methodology

When the surface lands, the audit method mirrors mgf-common's PC
tracker:

1. Read each source file end-to-end identifying per-call work,
   per-process work, and allocation patterns.
2. For every concern surfaced, write a falsifiable budget + the
   test shape that pins it (generous budgets — current × 2-3 —
   to catch order-of-magnitude drift, not noise).
3. Cross-reference mgf-common's PC tracker — invariants inherited;
   the sibling-side perf tax is what THIS tracker measures.

The first pass should look at the core-light import budget (Pass
2), then the adapter's live-query + list/pagination cost (Pass 3),
then the CLI startup + web per-request cost (Pass 4 / 5).
