Workspace Registry YAML Schema

ELI5

registry.yaml is a paper register of every workspace Rocky has been deployed into. Each line says: who they are (slug), what plan they bought (tier), what kind of deployer ran the install (driver), when they joined, and a receipt the deployer gave back (deployment_ref). PETROVA reads this register to decide what to provision; HEARTH reads it to find what already exists.

Technical Deep Dive

File location and edit policy

• registry.yaml lives at parent root.
• Edits are PR-only (header comment in registry.yaml:3).
• The schema lives next door at registry.schema.json (Draft 2020-12).
• version is currently 1; workspaces ships empty in Phase 1 and gains its first row when Phase 5 (hearth-local) provisioning is exercised end-to-end (registry.yaml:5).

Top-level shape

version: 1
updated: "2026-05-02"   # ^\d{4}-\d{2}-\d{2}$
workspaces: []

additionalProperties: false is enforced at every object level — unknown keys fail validation.

workspace entry

The workspaces array has uniqueItems: true, so two rows that hash identically are rejected — practical floor against duplicate slugs slipping through review.

Class diagram

classDiagram
    class Registry {
        +int version (const 1)
        +string updated (YYYY-MM-DD)
        +Workspace[] workspaces (uniqueItems)
    }
    class Workspace {
        +string slug (^[a-z0-9][a-z0-9-]*[a-z0-9]$)
        +Tier tier
        +DriverName driver?
        +string added (YYYY-MM-DD)
        +string deployment_ref?
        +string notes?
    }
    class Tier {
        <<enum>>
        solo
        team
        studio
        bespoke
    }
    class DriverName {
        <<enum>>
        LocalDocker
        Kustomize
        DevarnoCloud
    }
    Registry --> Workspace
    Workspace --> Tier
    Workspace --> DriverName

Why deployment_ref is a string, not a struct

deployment_ref is documented as “Opaque reference returned by the HEARTH driver. Format depends on driver.” Each driver chooses its own encoding (a Docker container UID, a kustomize git path, a cloud resource ARN). The registry is a thin index; the rich DeploymentRef schema (rocky-010) lives in the console DB.

Key Terms

• Slug → workspace identity used as the primary key for VAULT, HATCH, and HEARTH lookups
• Tier → resolves to a ProvisioningProfile (rocky-009)
• Driver → which HEARTH implementation provisioned the workspace (Phase 5 ships LocalDocker only)
• Opaque reference → driver-defined string the registry stores without parsing

Q&A

Q: Why is driver optional on a workspace row? A: A registry row may exist before HEARTH has provisioned the workspace (e.g. PETROVA wrote the slug + tier first). The driver field is filled when provisioning runs successfully.

Q: What stops two PRs from racing the same slug? A: uniqueItems: true on the workspaces array catches identical-row duplicates; the unique-slug invariant beyond that is a review responsibility (HEARTH Provision is also idempotent on (slug, tier, driver), see rocky-008).

Q: Why is the file empty today? A: Phase 1 ships the scaffold only. Phase 5 writes the first row when LocalDocker provisioning runs end-to-end. The empty file is a deliberate state, not a bug.

Examples

A guest book in a hotel lobby: each row records who checked in (slug), what room class they booked (tier), which front-desk clerk processed them (driver), and the locker number (deployment_ref) the clerk handed over. The book is the index; the lockers, the room keys, and the billing system are elsewhere.