title: Rocky — System Redesign status: Draft for review date: 2026-05-02 author: Alex (devarno) + Claude supersedes: docs/specs/2026-05-02-rocky-design.md (in scope, not in deletion — that doc remains the SS-07 RALPH spec)

Rocky — System Redesign

Purpose

Pivot rocky-hq from a single-feature Python prompt-queue tool into a superproject that delivers per-workspace operations & modelling. The existing Python tool becomes one subsystem (SS-07 RALPH) inside a multi-subsystem product whose canonical surface is the existing Next.js console previously developed at devarno-cloud/rocky (@rocky/ops).

Rocky's long-term role: every PETROVA-onboarded project gets exactly one Rocky instance, alongside one GRACE and one TRACEO instance. Rocky owns operations, modelling, prompt automation, and per-workspace knowledge-stack provisioning (1×CAIRNET + 1×LORE per workspace, tiered).

Goals

1. Lift the existing Next.js @rocky/ops console (7 shipped subsystems, all VTM Pass) into the new structure without rewrites.
2. Wrap the current Python rocky-hq CLI as a console subsystem (SS-07 RALPH) while keeping the standalone CLI usable.
3. Add SS-08 HEARTH — a tiered per-workspace CAIRNET+LORE provisioner.
4. Keep the system Airlock-tenanted: every action resolves to an authenticated Airlock session and a HATCH audit event.
5. Ship as OSS by default, with cloud-only Polar.sh entitlement gates layered on top — never leaking commercial paths into self-host installs.
6. Match devarno-cloud's superproject pattern so PETROVA already knows how to govern Rocky.

Non-goals (this redesign)

• Rewriting any of the 7 existing console subsystems.
• Building CAIRNET, LORE, SHIELD, HATCH, or AIRLOCK — they already exist as separate services under devarno-cloud/. HEARTH is a deployer, not the services.
• Designing the PETROVA verb that calls HEARTH (extension lives in petrova-hq).
• Designing the project-specific algo packages themselves (e.g. devarno-cloud financial forecasting). They surface through the existing SS-03 PLUGINS seam; no new subsystem needed.
• Migration of in-flight devarno-cloud tenants. We assume a clean cut where devarno-cloud's rocky submodule URL is repointed at rocky-hq/console.

Big design decisions

Architecture

Repository layout

rocky-hq/                                # this repo, the superproject
  console/         → submodule → @rocky/console      (Next.js 16 + React 19, lifted from devarno-cloud/rocky)
  ralph/           → submodule → @rocky/ralph        (Python 3, current rocky-hq codebase moved here)
  hearth/           → submodule → @rocky/hearth        (NEW; Go — see "Why Go for HEARTH")
  algo/            → submodule → @rocky/algo         (project-specific modelling packages, plugged via SS-03 PLUGINS)
  contracts/       → submodule → @rocky/contracts    (zod + JSON schema + proto for cross-submodule interfaces)
  docs/                                              (in-tree)
  registry.yaml                                      (in-tree; lists deployed workspaces + tiers)
  AGENTS.xml                                         (in-tree; PETROVA-compatible verb declarations)
  CLAUDE.md                                          (in-tree; MR-12 projection only)
  pyproject.toml + package.json minimal scaffolds for superproject-level scripts

Per devarno-cloud decision 0004 (push-down policy): the parent CLAUDE.md is projection-only. Build/test/runtime instructions live in each submodule's own CLAUDE.md.

Subsystem map

Tenancy invariant (applies to every subsystem)

No Rocky route, worker call, or driver action executes without:

1. A valid Airlock session (admin / operator / observer / denied)
2. A corresponding HATCH audit event written before the action takes effect
3. (Cloud build only) A Polar.sh entitlement check on provisioning, upgrade, and decommission of any tier > solo. Per-request runtime checks are not required — the tier is enforced through the DeploymentRef row plus the tier_downgrade_active_data policy below.

Self-host (ROCKY_BILLING=disabled, typically with ROCKY_AUTH=local) skips (3) and resolves (1) via the LocalAuth adapter; (2) is non-negotiable in all builds (HATCH defaults to a local JSONL sink in self-host mode).

SS-07 RALPH — wrapping the Python tool

Inside ralph/ (the submodule)

The current rocky-hq Python code moves verbatim: cli.py, runner.py, agent.py, judge.py, merge_driver.py, journal.py, workspace.py, loader.py, plus tests and the existing design spec at docs/specs/2026-05-02-rocky-design.md.

One additive change: a new ralph serve mode.

• HTTP server (FastAPI) accepts RunConfig + prompts.yaml payloads.
• Background worker (RQ or arq — pick at implementation time, both work) executes the existing pipeline.
• Streams run.jsonl events as SSE.
• Auth: shared HMAC token from VAULT, never exposed to the browser; the console's API route is the only thing that talks to the worker.

The standalone rocky run CLI continues to work unchanged for self-hosters who don't want the console.

Inside console/src/lib/ralph/ (NEW)

// console/src/lib/ralph/client.ts
submitRun(workspace_slug: string, prompts_yaml: string, config: RunConfig): Promise<{ run_id: string }>
streamEvents(run_id: string): AsyncIterable<JournalEvent>
cancelRun(run_id: string): Promise<void>   // admin-only

• Artifacts (plan.md, deviation_pre/post.md, diff.patch, transcripts) → object store already used by SS-04 WORKSPACE.
• New SS-02 dashboard panel ralph.runs.
• New SS-05 RELAY route /api/relay/ralph so deviation/major events reach HATCH in addition to the per-action HATCH events.

UI surface

• New top-level page /ralph with /runs, /runs/[id], /prompts/[file] sub-routes.
• No new design system; reuses Tailwind + radix-ui.
• Permissions: operator submits, observer views, admin cancels mid-run.

SS-08 HEARTH — per-workspace CAIRNET+LORE provisioning

Tiers

A tier is a YAML row resolving to a ProvisioningProfile (resource caps + driver flags). Adding a tier never adds code paths.

Inside hearth/ (NEW submodule, Go)

// hearth/internal/driver/driver.go
type Driver interface {
    Provision(ctx context.Context, slug string, profile ProvisioningProfile) (DeploymentRef, error)
    Status(ctx context.Context, ref DeploymentRef) (Status, error)
    Upgrade(ctx context.Context, ref DeploymentRef, profile ProvisioningProfile) (DeploymentRef, error)
    Teardown(ctx context.Context, ref DeploymentRef) error
}

Cross-language types come from contracts/ via codegen — ProvisioningProfile, DeploymentRef, Status are defined once (zod or proto, TBD in the contracts spec) and emitted to both Go (via quicktype or buf if proto) and TypeScript.

Why Go for HEARTH

HEARTH is a coordinator: it calls Docker, k8s, and cloud APIs and writes a Postgres row. The decision is dominated by ecosystem fit and distribution shape, not by language semantics.

• Ecosystem fit. client-go, docker/cli, kustomize, helm, and controller-runtime (if HEARTH later evolves into an operator) are all Go-native and importable as libraries with zero shelling out. The TypeScript equivalents (@kubernetes/client-node, dockerode) work but lag in completeness and battle-testing.
• Distribution. A single static binary is the right shape for a self-hostable OSS provisioner. Node-based distribution drags in npm trees and runtime version coupling.
• Concurrency model. Goroutines fit parallel provisioning naturally; no async colour or worker-pool ceremony.

Rejected alternatives:

• TypeScript — would let us share the runtime with the console, but the console doesn't actually need to embed HEARTH; it talks to it over a small RPC surface. That's the right place for polyglot. Loses the ecosystem and distribution wins above.
• Rust — compile times slow iteration on a tool that'll get edited a lot. kube-rs and bollard work but are behind client-go/docker/cli. The borrow checker buys little here — the work is I/O-bound API plumbing, not the bug class Rust prevents.
• Zig — pre-1.0, std and ABI still churning. No production-grade Docker or k8s client. Zig shines where explicit memory and no hidden allocation matter; none of HEARTH's hot paths qualify.

Drivers shipped:

• LocalDocker — dev/self-host. Spins CAIRNET + LORE containers on operator's box. Required for OSS parity.
• Kustomize — emits manifests for self-hosters running their own k8s; expects them to apply.
• DevarnoCloud — managed driver, deploys into existing devarno-cloud infrastructure (mirrors what devarno-cloud/cairnet and devarno-cloud/lore already use).

State store: DeploymentRef rows in the console's existing Postgres — {workspace_slug, tier, driver, endpoint, secrets_vault_path, created, last_status}. Rocky never stores CAIRNET/LORE contents — only deployment metadata. Driver-issued credentials land in SS-06 VAULT keyed by workspace_slug.

Inside console/src/lib/hearth/ (NEW)

provisionWorkspace(slug: string, tier: Tier): Promise<DeploymentRef>     // admin-only
getWorkspaceDeployment(slug: string): Promise<DeploymentRef | null>      // any role with workspace access
decommissionWorkspace(slug: string): Promise<void>                       // admin-only

getWorkspaceDeployment is the discovery seam every other subsystem uses to resolve a workspace's CAIRNET/LORE endpoints.

Polar.sh integration

• console/src/lib/polar/entitlements.ts is the only place Polar.sh code lives.
• Webhook → SS-05 RELAY route /api/relay/polar → mutates HEARTH tier on subscription.active|canceled.
• Self-host build sets ROCKY_BILLING=disabled and forces tier=solo. The Polar adapter compiles to a no-op when disabled. No Polar code paths leak into self-host installs.

UI surface

• New admin-only page /hearth listing all deployments and statuses.
• Observers see only their own workspace's deployment row.

End-to-end data flow (workspace onboarding → first RALPH run)

1. Human edits petrova-hq/registry.yaml — adds entry with rocky_tier=team
2. PETROVA verb provision_rocky(slug, tier) → console.hearth.provisionWorkspace(slug, "team")
3. SS-08 HEARTH:
   a. Airlock check: caller has admin role on workspace
   b. Polar.sh check: workspace has active "rocky-team" entitlement (cloud build)
   c. Driver=DevarnoCloud → deploys 1×CAIRNET + 1×LORE
   d. Credentials → SS-06 VAULT
   e. DeploymentRef row → console DB
   f. SS-05 RELAY → HATCH "hearth.provisioned"
4. Operator opens /ralph/runs/new:
   a. Selects workspace (HEARTH resolves CAIRNET/LORE endpoints)
   b. Uploads prompts.yaml
   c. submitRun() POSTs to ralph worker with HMAC + workspace context
5. RALPH worker (existing pipeline):
   plan → judge → execute → audit → merge per prompt
   Events stream SSE → console → browser; mirrored to HATCH
   Artifacts → SS-04 object store
6. Run finishes: ralph.runs panel updates; deviation reports linkable from /ralph/runs/[id]

Error handling

Every error class produces a HATCH event. Provisioning never auto-retries — failures are loud, admin re-runs explicitly.

Testing strategy

Three tiers (mirrors RALPH's existing pattern)

1. Unit (per submodule, fast, no network)

• console: existing vitest suite stays. New unit tests for console/src/lib/ralph/, console/src/lib/hearth/, console/src/lib/polar/.
• ralph (Python): existing pytest suite stays. Add tests for ralph serve HTTP layer with FastAPI's TestClient.
• hearth: driver protocol contract tests against a FakeDriver that records calls.

2. Integration (per submodule, real local services)

• console: existing 21+ cross-subsystem integration tests stay.
• hearth: LocalDocker driver against testcontainers — actually spins up CAIRNET + LORE images, exercises provision / status / teardown. Gated ROCKY_HEARTH_INTEGRATION=1.
• Superproject e2e: tests/e2e/test_provision_then_ralph.py provisions a solo workspace via LocalDocker, submits the existing 4-prompt mock RALPH run, asserts the full event chain reaches a fake HATCH sink.

3. Smoke (manual, gated, real cloud)

• ROCKY_SMOKE=1 runs one provision against the DevarnoCloud driver in a sandbox tenant, then tears down. Catches driver/credential drift.
• Existing RALPH smoke (ROCKY_SMOKE=1 for the SDK) keeps running.

CI shape

Mirrors devarno-cloud:

• Parent rocky-hq CI runs git submodule status consistency check + the e2e test only.
• Each submodule has its own CI for its own unit + integration tests.

OSS test parity invariant

The solo tier + LocalDocker driver + LocalAuth adapter path must pass the full e2e test with no Polar.sh network calls and no devarno-cloud-tenant credentials. If a self-hoster's CI breaks on the e2e test, we broke OSS.

Licensing

• Per-submodule licensing:
  • console, ralph, hearth, algo → MIT (matches the lightweight, infrastructure-tool ethos).
  • contracts → Apache-2.0 (explicit patent grant for redistributable schemas/IDL).
• The cloud-hosted rocky.erid.tech deployment is the only Rocky surface that requires Polar.sh entitlements. The OSS build is fully featured, just without billing.

PETROVA hookup (out of scope for this spec, sketched only)

petrova-hq/registry.yaml schema gains:

integrations_applicability:
  ...existing...
  rocky: required | optional | not_applicable
rocky_tier: solo | team | studio | bespoke    # only when rocky != not_applicable

PETROVA gains a provision_rocky verb that calls console.hearth.provisionWorkspace with the registry's declared tier. Verb design lives in a separate PETROVA spec.

KAHN integration (operator-facing observability)

KAHN (kahn-hq) is the operator's existing fleet-observability product (PRODUCT.md: "agent-fleet observability tool"). It already ships a vendored producer→consumer contract at kahn-hq/contracts/: transitions.schema.json, graph.schema.json, and a stdlib-only kahn_emit.py (additive-compatible; sister repos vendor it directly per contracts/README.md). Rocky does not duplicate this surface.

• Phase 3 (lift-ralph) commitment: Rocky RALPH adopts KAHN's transitions.schema.json as its on-disk event format. Vendor kahn_emit.py into ralph/ per KAHN's recommended consumption path. Each Rocky run becomes one KAHN run; each prompt becomes a node; plan/execute/audit are node attempts; deviation severity maps onto KAHN's Outcome enum (clean | clean_with_flake | partial | stuck | catastrophic). Rocky's deviation-detection metadata rides as KAHN's documented "unknown fields pass through" extension.
• Operator UX: Rocky runs surface in KAHN Scope alongside Choco/STRATT/Traceo runs; KAHN Scope is the canonical fleet dashboard. Rocky's console SS-02 DASHBOARDS continues to own ops-and-modelling views (workbench history, plugin registry, vault audit) that KAHN intentionally does not cover.
• What we explicitly DO NOT do here: wrap KAHN's orchestrator as Rocky's runtime. Rocky RALPH stays a sequential prompt-queue with plan/judge/execute/audit/merge; KAHN's prompt-DAG orchestrator solves an adjacent problem (fleet-wide convergence). Re-evaluate post-Phase-3 once we have real Rocky-on-KAHN-emit telemetry; do not unify on speculation.
• Decision record: rationale and rename of SS-08 (FLEET → HEARTH) to avoid the namespace collision are recorded in docs/decisions/0002-rename-fleet-to-hearth.md.

Phasing (rough order, fully detailed in the implementation plan)

1. Stand up the superproject scaffold: empty submodule pointers, AGENTS.xml, CLAUDE.md projection, registry.yaml.
2. Lift devarno-cloud/rocky → rocky-hq/console (new repo, fresh history or filtered subtree — TBD; see open question).
3. Move current rocky-hq Python code → rocky-hq/ralph. Add ralph serve. Wire console SS-07. Adopt KAHN's transitions.schema.json + vendor kahn_emit.py as the RALPH on-disk event format.
4. Stand up rocky-hq/contracts with the cross-submodule schemas needed by SS-07.
5. Build rocky-hq/hearth with LocalDocker driver only. Wire console SS-08. Ship the e2e test.
6. Add Kustomize and DevarnoCloud drivers.
7. Wire Polar.sh entitlements + /api/relay/polar.
8. (PETROVA, separate spec) Extend registry schema and add provision_rocky verb.

Resolved decisions (formerly open questions)

1. Submodule history → git subtree split. Preserves commit history and the VTM Pass lineage. Slightly slower lift, materially more credible provenance for the 7 already-shipped subsystems.
2. HEARTH implementation language → Go. Rationale in "Why Go for HEARTH" above.
3. contracts/ license → Apache-2.0. All other submodules are MIT. contracts/ is the only repo whose artifacts (zod schemas, proto, generated clients) get redistributed downstream by consumers, where the explicit patent grant in Apache-2 is the standard-of-care choice for schema/IDL libraries.
4. algo/ shape → one repo with namespaced packages. @rocky/algo-devarno-finance, @rocky/algo-foo, etc. PETROVA governs one slug, package boundary is the per-project unit. Re-evaluate at ≥3 consumers — split if individual project teams need independent release cadence.
5. OSS solo identity → LocalAuth adapter. Self-host with ROCKY_AUTH=local resolves the Airlock session to a local single-user identity (file-backed). Tenancy invariant still holds; the HATCH event sink defaults to a local JSONL file in this mode. Cloud build (ROCKY_AUTH=airlock) is unchanged.