blocksmith.lock.v1

The lock — package-lock.json for design

Lives in the consumer repository next to DESIGN.md. Pins every promoted block to an exact version + contentHash. Agents resolve against the lock, never "latest markdown". CI fails when the lock drifts from the promoted graph.

blocksmith.lock

{
  "schema": "blocksmith.lock.v1",
  "docRef": "upload:scan-acme-mobile-app.md",
  "systemId": "acme-mobile-app",
  "contentHash": "sha256:afffd0184ad0a9a1d184f247916216c1",
  "generatedAt": "2026-06-04T12:00:00.000Z",
  "blocks": {
    "agent-rule:cta-density":   { "version": 2, "contentHash": "sha256:f230b745…" },
    "component:button-primary": { "version": 4, "contentHash": "sha256:d9d425a1…" },
    "token:color:accent":       { "version": 1, "contentHash": "sha256:a40ae6c9…" }
  },
  "package": { "name": "@blocksmith/acme-mobile-app" }
}

Staleness — the core mechanic

contentHash is the official graph hash at lock time. Any promote or rollback after that changes the graph hash, so verifyLockAgainstGraph(lock, graph) reports stale: true — your repo is pinned to yesterday's truth and needs a re-pull. Field-level drift (a pin whose version no longer matches the official pointer) is reported per block.

@blocksmith/protocol

import { verifyLockAgainstGraph, validateLock } from "@blocksmith/protocol";

validateLock(lock);                            // shape check
const { ok, stale, errors } = verifyLockAgainstGraph(lock, officialGraph);
// stale → re-pull; errors list per-block version/hash drift

Pull flow (reference implementation)

Step	What happens
1 · Human promotes in wiki Pipeline	Official pointer advances; reference lock regenerated server-side
2 · `blocksmith pull --doc …`	CLI writes blocksmith.lock into the repo (also available: GET /api/v1/lock?format=file)
3 · Agents (MCP) read pinned versions	Every tool response is stamped “pinned vN (sha256:…)”; drafts are never served
4 · CI gate `validate:ui`	PR fails on stale/missing lock or off-token values in the diff
5 · Rollback	Pointer moves back; lock regenerates; the rollback itself is an audited run

Determinism guarantee: the same official graph always serializes to the same lock body (sorted block ids, canonical hashes) — locks diff cleanly in code review, and two machines never disagree about what production means.

Downloads

JSON Schema · fixture: @blocksmith/protocol/fixtures/acme-minimal.lock.v1.json