RALPH consumption v2: refresh against rocky-hq's real phase, re-scope the deferred HTTP source

Date: 2026-09-22 Status: open Supersedes: docs/decisions/2026-07-07-consumption-v1-ralph-http-source-modality.md Superseded-by: none — current

Context

2026-07-07-consumption-v1-ralph-http-source-modality.md described RALPH (rocky-hq/ralph) at “Phase 3c” — the read-only HTTP API (GET /runs, /runs/{id}, /runs/{id}/events, Bearer auth) had just landed, and the decision split N2 into a contract-promotion step (done then) and a deferred HTTP-source-modality step (never built — host/src/sources/ remains file-based today, OBSERVED this session, no ralph.ts or kahn.ts under host/src/sources/).

Rocky-hq is not at Phase 3c anymore. Read directly this session from ~/code/workspace/rocky-hq/MILESTONES.md (OBSERVED, not carried from a prior survey):

Phase 7 (“Agentic layer + Polar.sh”) row: `7a closed; 7b producer wiring
- 7c hatch consumer queued— but every individual 7b-* and 7c-* sub-row in the same table (7b-ralph, 7b-ralph-2, 7c-a through 7c-c-c) is markedclosed`, contradicting the parent row’s own “queued” language. The table itself is stale at the summary-row level even though its own detail rows are current — OBSERVED inconsistency, not fixed here (out of scope: this doc corrects petrova-codes’ consumption decision, not rocky-hq’s own milestones ledger).
P1a (KAHN agent-transition producer wiring) and its four sub-phases (P1a-1..P1a-4) are all closed, including P1a-1: RALPH vendors kahn_agent_emit.py — RALPH now emits directly to KAHN’s journal shape, a capability that didn’t exist in the July doc.
Phase 8 (KILN federation) is not-started, blocked-by Phases 5–7 close-out — the next real unstarted milestone.

Net: RALPH is materially past Phase 3c. This session’s own prior audit (docs/audit/state.md, “Dead weight” section) said “rocky-hq is now at Phase 7a” — DECLARED there, and now correctable: OBSERVED here that 7a specifically is one of several already-closed phases, not the current edge. The audit’s own imprecision is itself worth naming so the next reader doesn’t cite “Phase 7a” as current either.

The read-surface itself (ralph/src/rocky/serve/app.py, ralph/src/rocky/serve/auth.py) still matches the July doc’s description exactly — Bearer-authed endpoints, require_bearer dependency on every route, /healthz unauthenticated — OBSERVED, re-read this session. The HTTP API’s shape has not drifted; RALPH’s phase has, substantially.

Decision

Re-affirm, not re-litigate, the July split. The contract-vs-source split (contract promotion now, HTTP source modality as its own design phase) remains correct reasoning independent of RALPH’s phase number — nothing about Phase 7/8 progress changes the argument that host/src should not bolt on its first network I/O modality without a dedicated design pass. Not re-opened here.
Correct what petrova-codes’ contract pin should say RALPH offers. contracts/petrova.host.consumption.v1.yaml’s rocky_ralph entry was written against Phase 3c’s read surface only (runs/events). It should be re-checked against what P1a’s KAHN-emit wiring changed: RALPH now also writes to KAHN’s journal (a separate edge, E2, already production-grade per the July doc) — this doesn’t add a new endpoint to rocky_ralph’s own contract, but confirms the “petrova reads what rocky already emits, not what rocky is asked to add” principle held. No new host code follows from this doc; it is a re-scoping of what the next HTTP-source-modality design pass should assume as ground truth, not a new obligation.
Mark the July doc’s own Phase 3c framing as stale, superseded by this doc, without touching its Decision or Consequences sections — they still hold. Only the phase-number framing in its Context needed correction, which is why this is a refresh, not a reversal.

Alternatives considered

Silently let the July doc keep describing Phase 3c — rejected: this is exactly the class of drift docs/audit/graph.md’s refresh-ralph-consumption-decision node was scoped to close, and the new docs-invariants.yml CI gate (2026-09-22) now checks decision-doc hygiene on every PR touching docs/decisions/** — leaving a doc that cites a since-superseded phase number as “current” undermines the same gate that was just wired to catch drift like this.
Rewrite the July doc in place — rejected: MR-7 requires decision docs stay append-only. A new doc, superseding the old, is the only compliant path.
Wait for the full registry-vs-contract sweep (checkpoint 3, running in parallel) before refreshing this doc — rejected: the two are independent (this doc concerns rocky-hq’s phase state and the RALPH contract entry specifically; the sweep concerns .petrova/contract.yaml presence across all 44 registry rows). No shared file, no ordering dependency — matches docs/audit/graph.md’s own parallel_safe: true tag on this node.

Consequences

For code: None. host/src remains file-based; no source-modality work is unblocked or required by this doc. contracts/petrova.host.consumption.v1.yaml is not edited here — flagged as needing its own re-check pass, not performed in this doc (scope: decision-doc refresh, not contract editing).

For docs: 2026-07-07-consumption-v1-ralph-http-source-modality.md gets a Superseded-by line pointing here; its Status: becomes superseded. This doc is open, not ratified — it needs human countersign before its re-scoping (item 2 above) is acted on by any future contract edit; no ## Sign-off block is required at open status per cli/src/verbs/validate.ts’s PROPOSED_STATUS/RATIFIED_STATUS/ CLOSED_EQUIVALENT_STATUS checks (only closed-equivalent statuses require one).

For invariants: No new MR. Reinforces MR-7 (append-only decision docs) and the same “federation trails, never leads” discipline the July doc cited (no new MR number, carried forward).

For phases: Does not unblock or start any petrova-codes phase. Names Phase 8 (KILN federation) as rocky-hq’s actual next milestone, for anyone scoping a future cross-repo consumption update — informational, not a commitment made by petrova-codes here.

References

docs/decisions/2026-07-07-consumption-v1-ralph-http-source-modality.md — the doc this supersedes.
~/code/workspace/rocky-hq/MILESTONES.md lines 79, 81-98, 103 — Phase 7/P1a/Phase 8 status, read directly this session.
~/code/workspace/rocky-hq/ralph/src/rocky/serve/app.py, ralph/src/rocky/serve/auth.py — read-surface shape, unchanged from July, re-verified this session.
docs/audit/state.md (“Dead weight” section) — prior audit’s own “Phase 7a” framing, corrected by this doc.
docs/audit/graph.md (refresh-ralph-consumption-decision node) — the work-graph node this doc executes.
.github/workflows/docs-invariants.yml — the gate this doc’s own hygiene is checked against.