Consumption v1: promote RALPH queue; defer the HTTP source modality

Date: 2026-07-07 Status: open Supersedes: none Superseded-by: none — current

Context

Neverland phase N2 (docs/neverland/03-implementation-cycle.md) calls to “let PETROVA see ROCKY” by federating the RALPH queue (edge E8). The consumption contract (petrova.host.consumption.v0.yaml) marked rocky_ralph as omit_in_v0: true / ralph.queue.v0.unstable, deferring until rocky-hq Phase 3b ratified.

Investigation for N2 surfaced two facts:

1. The RALPH read-surface exists. ralph serve (rocky-hq/ralph Phase 3c) is live with a read-only HTTP API (GET /runs, /runs/{id}, /runs/{id}/events, Bearer auth). Phase 3b (KAHN-shaped journal emit) is implemented and the ROCKY→KAHN data plane (edge E2) is production-grade. The v0 note’s precondition is met.

2. The host has no HTTP source modality. Every reader in host/src/sources/* is file-based (reads registry.yaml, local JSONL, sibling repo paths). PETROVA_HOST_KAHN_API is declared in the consumption contract but is not referenced anywhere in host/src — the kahn upstream (edge E7) is a contract pin, not a live fetch. Adding a real RalphSource that fetches over HTTP would introduce a new I/O modality (network fetch, bearer handling, timeout/retry, failure degradation) to a host that currently touches only the local filesystem.

Decision

Split N2 into a contract step (now) and a source step (deferred):

1. Now — contract promotion. Add contracts/petrova.host.consumption.v1.yaml promoting rocky_ralph from omitted/unstable to a declared ralph.queue.v1 upstream, with its api_base_env, bearer_env, and read-only endpoints. Mark both kahn and rocky_ralph with fetched: false to record honestly that they are pinned, not yet read. This satisfies “federation trails, never leads” (docs/neverland/02-shared-contracts.md): the contract consumes a shipped owner version.

2. Deferred — HTTP source modality. Building sources/ralph.ts (and, symmetrically, a live sources/kahn.ts) is its own design phase: it adds network I/O, bearer config plumbing (config.ts), and a degradation contract (what the Fleet MCP returns when an upstream API is down) to the host. That work gets its own decision + phase rather than being bolted on inconsistently here.

Alternatives considered

• Implement sources/ralph.ts with fetch now — rejected: it would be the host’s only HTTP source, with no established pattern for auth, timeouts, or failure degradation, in a profile: strict repo. Design first.
• Read RALPH’s on-disk run state from a sibling path (file-based, like eva/grace) — rejected: RALPH queue state is runtime/ephemeral and not guaranteed present on the host’s filesystem; the serve API is the intended read-surface.
• Leave rocky_ralph omitted — rejected: the v0 precondition (“Phase 3b ratifies”) is now met; leaving it omitted keeps the map lying about a real, shipped read-surface.

Consequences

For code:

• New contracts/petrova.host.consumption.v1.yaml. No host source code yet; host/src unchanged.

For docs:

• docs/neverland/01-connector-map.md: correct E7 from LIVE to PARTIAL (pinned, not fetched) and move E8 to PARTIAL (contract declared, source deferred). Honest “pinned vs fetched” distinction added.

For in-flight phases:

• N2 contract half done; N2 source half becomes a scoped follow-up phase (HTTP source modality) covering both ralph and kahn.

For invariants:

• Reinforces “federation trails, never leads” as contract discipline; no new MR (MR-9).

References

• contracts/petrova.host.consumption.v1.yaml — this promotion.
• contracts/petrova.host.consumption.v0.yaml:25 — prior omitted entry.
• docs/neverland/01-connector-map.md — edges E7, E8.
• host/src/server.ts:25 — file-based source registration (no HTTP).
• rocky-hq/ralph src/rocky/serve/app.py — the live read-surface.

Sign-off

• Subagent: neverland N2 (cockpit federation, contract step), 2026-07-07
• Human: <<pending — Alex confirm>>