Version-Locked Component Metadata for Reliable Reuse

The failure hidden in a component count

A registry that only reports a component count is not an inventory. Half of those rows are stubs – they contain a name, a version string and a hand‑written description, but no artefact that can be executed. When a build pulls such a stub it either fails at runtime or silently uses a different version than the author intended. The result is brittle reuse and wasted debugging time.

Version‑locked rows: git hash and build timestamp

The only way to turn a count into a trustworthy inventory is to bind every row to an immutable source reference. Embedding the exact git commit hash and the UTC build timestamp into the component metadata creates a version lock that cannot drift.

{
  "name": "@myorg/util‑math",
  "gitHash": "a3f9c2d7e1b4f8c6d9e0a1b2c3d4e5f6a7b8c9d0",
  "builtAt": "2026-09-30T12:34:56Z",
  "certification": "PROVISIONAL"
}

The hash guarantees the source code that produced the artefact. The timestamp proves when the artefact was built, which helps detect re‑builds that unintentionally overwrite a previous release. Because the registry stores this data verbatim, the row is repeatable and can be verified against the published archive checksums in the Root of Trust.

CI validation before promotion

A CI pipeline can enforce the lock with a single step that rejects any row lacking the required fields or whose certification status is not at least PROVISIONAL.

## .github/workflows/registry-lock.yml
steps:
  - uses: actions/checkout@v3
  - name: Build component
    run: npm run build
  - name: Record lock
    run: |
      HASH=$(git rev-parse HEAD)
      TIME=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
      jq ".gitHash=\"$HASH\" | .builtAt=\"$TIME\" | .certification=\"PROVISIONAL\"" \
         dist/metadata.json > dist/metadata.locked.json
  - name: Verify lock
    run: |
      jq -e '.gitHash and .builtAt and .certification' dist/metadata.locked.json \
        || exit 1
  - name: Run certification harness
    run: ./harness verify dist/metadata.locked.json

The Verify lock step fails fast if the metadata is incomplete. The harness step executes the artefact in a controlled environment and records a verdict – CERTIFIED, PROVISIONAL, INCONCLUSIVE or FAILED. Only rows that pass this gate are eligible for promotion to the public registry.

The broader impact on reuse

When every entry in the registry carries a verifiable lock, downstream projects can fetch a component and immediately know which source commit it originates from and whether it has been exercised by the harness. That knowledge eliminates the “I’m using the right version” guesswork that plagues large monorepos and micro‑service ecosystems.

The lock also enables automated dependency updates. A tool can compare the hash stored in a consuming project's lockfile with the hash in the registry; if they differ, the tool can raise a PR that updates the version and runs the same CI validation before merging. Thus the registry becomes a living inventory, not a static count.

How SHPBL enforces version‑locked metadata

SHPBL’s Build Intent gate records every write proposal, resolves licensing invariants, and returns a terminal state before any artefact is stored. The same gate is used by the typed TypeScript client (@shpbl/sdk) and the plain HTTP API, ensuring that the lock is applied regardless of the access method. A certification harness runs the artefact and records a verdict, so a row can only be promoted when the harness reports CERTIFIED or PROVISIONAL. This workflow is described in detail in the pillar post “A component count is not an inventory” and illustrated in the executable‑registry audit guide /blog/executable-registry-audits-turn-stubs-into-trusted-assets.

Monday’s concrete step

Add the “Record lock” and “Verify lock” stages to your CI pipeline today. Commit the snippet above, adjust the paths to match your build output, and run the harness on the resulting metadata.locked.json. If the step fails, you have identified a stub that needs a real artefact. Once the lock passes, promote the component through the SHPBL Build Intent gate. From then on, every row you count will be a verifiable inventory entry ready for reliable reuse.