blocksmith.registry.v1

The registry — versions and the promote gate

The registry is the artifact store of Design CI/CD: per block id, an append-only list of version records plus one official pointer that defines production. Promote moves the pointer forward; rollback moves it back; history is never edited or deleted — npm-style.

Per-block entry

BlockRegistryEntry

{
  "id": "component:primary-action-button",
  "official": 2,
  "versions": [
    {
      "version": 1, "status": "finalized",
      "title": "Primary Action Button", "type": "component",
      "content": { "role": "Primary CTA", "radius": "12px" },
      "contentHash": "sha256:…",
      "source": { "file": "src/components/Button.tsx", "ingest": "scan" },
      "updatedAt": "…", "createdAt": "…", "finalizedAt": "…", "editedBy": "ingest"
    },
    {
      "version": 2, "status": "finalized",
      "title": "Primary Action Button", "type": "component",
      "content": { "role": "Primary CTA", "radius": "14px" },
      "contentHash": "sha256:…",
      "source": { "file": "src/components/Button.tsx", "ingest": "scan" },
      "updatedAt": "…", "createdAt": "…", "finalizedAt": "…", "editedBy": "web"
    }
  ]
}

Per-doc manifest

RegistryManifest

{
  "schema": "blocksmith.registry.v1",
  "docRef": "upload:scan-acme-app.md",
  "systemId": "acme-design-system",
  "lastIngestAt": "2026-06-09T12:00:00.000Z",
  "officialGraphHash": "sha256:…",
  "blockCount": 40,
  "promotedCount": 38,
  "draftCount": 2,
  "staleCount": 0
}

Constitutional semantics

Rule	Spec text
Versions	Append-only; strictly ascending; never delete or rewrite
`official`	Production pointer; the only lock-eligible version; must reference a recorded version
Auto-promote	token + component facts from scan ingest promote immediately — code is authoritative until re-scan
Draft	Governance edits (guideline, agent-rule, page) stage as draft until a human promotes
`stale`	Source vanished; block is flagged, last official version remains in the lock until a human decides
`conflict`	Cross-source disagreement (e.g. Figma hex ≠ scan hex); promote is blocked until a human resolves
Partial ingest	Adapters contributing alongside the primary scan (Storybook, Figma) must not stale blocks they don't own

These semantics are reviewed protocol law — implemented in the reference registry, exercised by verify:ir-cicd (29 assertions), and validated structurally by validateRegistryEntry / validateRegistryManifest. Changes require professor + platform sign-off (see PROTOCOL-GOVERNANCE).

Lifecycle

INGEST → v(N+1) recorded ──┐
                            ├─ scan fact?      → auto-promote (official = N+1)
                            └─ governance?     → draft (staging)
PROMOTE (human gate)        → official = N+1; lock regenerated
ROLLBACK                    → official = previous finalized vK; lock regenerated
RE-SCAN (block missing)     → latest marked stale; lock pin survives

Downloads

JSON Schema (manifest + entry shapes) · validators in @blocksmith/protocol