Skip to content
PETROVA

Boundary diagram

The single most load-bearing mental model. PETROVA is a capability boundary between agent fleets and the repos they govern. Reads flow freely; writes go through the verb layer.

The diagram

Section titled “The diagram”
%%{init: {'sequence': {'wrap': true, 'mirrorActors': false, 'boxMargin': 12, 'noteMargin': 12, 'messageMargin': 36, 'actorMargin': 80}}}%%
sequenceDiagram
    autonumber
    participant F as Ring 2 — Agent fleet
    participant P as Ring 0 — Petrova
    participant R as Ring 1 — Consumer repo

    F->>P: verb call — typed JSON
    Note over P: schema-validate · check registry + fleets_allowed · NO_PRIVILEGED_PATHS · dry-run
    P-->>F: dry-run preview (diff + envelope)

    F->>P: verb call — apply
    P->>R: open PR (Contents API, audit body)
    Note over R: branch protection · CODEOWNERS · CI gates · review
    R-->>P: merged (human or auto-merge label)
    P-->>F: output envelope · idempotency key · MR cites

    Note over F,R: Forbidden — Ring 2 may never write to Ring 1 directly

What crosses each arrow

Section titled “What crosses each arrow”
ArrowDirectionCarriesFormat
Ring 2 → Ring 0downVerb invocationTyped JSON conforming to spec/verbs/<verb>.schema.json
Ring 0 → Ring 2upOutput envelope{ verb, status, idempotency_key, mr_citations[], errors[] }
Ring 0 → Ring 1downPull requestGitHub PR with petrova metadata block in body
Ring 1 → Ring 0upRead-only stateLocal clone walk OR GitHub API read
Ring 2 → Ring 1downNOTHING (forbidden)—

The forbidden arrow is the load-bearing one. A fleet that bypasses Ring 0 and writes directly to Ring 1 invalidates the entire audit chain — no idempotency, no MR citation, no schema validation, no fleets_allowed gate.

What is forbidden to cross

Section titled “What is forbidden to cross”
  • Fleet writing files directly to a consumer repo’s working tree.
  • Fleet pushing branches to a consumer repo.
  • Fleet merging PRs (auto-merge happens via GitHub’s machinery, not the fleet’s hand).
  • Fleet editing .github/workflows/, *.env, secrets/, deploy/credentials/ — even via verbs. NO_PRIVILEGED_PATHS refuses these unconditionally.
  • Fleet creating registry entries (onboarding is a human PR).
  • Control plane editing project intent in any consumer repo unsolicited (would violate MR-12).

How this maps to the conventional capability-boundary pattern

Section titled “How this maps to the conventional capability-boundary pattern”

This is the same shape as a kernel/userspace boundary, an HTTP gateway in front of microservices, or a database with stored procedures: reads cheap, writes narrow and authenticated.

What’s distinctive here is that the boundary is enforced between agents and repositories that an agent operator already owns. Ring 0 isn’t protecting the repos from a hostile fleet — it’s protecting the audit trail and methodology discipline from honest fleets that would otherwise drift.

See also

Section titled “See also”