Automating CI Verification of SHPBL Registry Entries

Registry entries are stubs, not inventory

A typical component registry contains rows that read like a promise. The row lists a name, a version, a short description and a link to source. No one ever loads the artifact. When the build later asks for the component, the loader throws a missing‑dependency error or the code crashes on first use. The failure is hidden until production, and the inventory claim is meaningless.

Metadata alone does not give inventory reliability

An inventory is a set of artefacts that can be exercised. Without execution the row is only documentation. The pillar post A Component Count Is Not an Inventory explains why a count is a claim, not a proof. When the same row is loaded in a CI harness, the harness either confirms the contract or records a defect. That binary verdict turns a stub into an executable proof.

A minimal CI harness turns stubs into verified entries

The harness needs three things: a catalogue source, a loader, and a verdict recorder. The loader can be the typed TypeScript client that ships with the library.

import { catalog } from '@shpbl/sdk';
import { runMinimalTest } from './harness';

async function verifyEntry(id: string) {
  const entry = await catalog.get(id);
  const result = await runMinimalTest(entry);
  console.log(`${id}: ${result}`);
}

runMinimalTest invokes the entry’s exported main function with a no‑op payload. If the function returns without exception the harness writes CERTIFIED. If the function throws, the harness writes FAILED. If the harness cannot satisfy the entry’s input contract, it writes INCONCLUSIVE.

The harness is deliberately small. It does not attempt full integration testing, only the contract that the catalogue promises: the entry can be loaded and executed.

Integrating the harness into an existing pipeline

Add a new CI job that runs after the catalogue is generated. The job fetches the catalogue JSON from the HTTP API (/api-access) or from the offline archive. It iterates over each identifier, calls verifyEntry, and writes the verdicts to a JSON artifact. The CI system can then fail the build if any row reports FAILED.

Because the harness uses the same client library that agents use over MCP, the behaviour is identical whether the job runs locally or in a remote runner. The result is a single source of truth: a catalogue where every row carries a verdict. Future developers can query the verdicts to decide whether a component is safe to depend on.

How SHPBL solves registry verification

SHPBL provides a certification harness that executes each artifact and records one of four verdicts: CERTIFIED, PROVISIONAL, INCONCLUSIVE, or FAILED. The harness is reachable through the same four doors – MCP, HTTP API, TypeScript SDK, and offline files – ensuring the same gate and meter for every call. Running the harness as a CI step turns a metadata‑only registry into an executable inventory with proven reliability. See the live run at /harness for a concrete example.

Monday’s concrete step

Clone the repository that holds your catalogue. Add the short TypeScript snippet above to a new file ci‑verify.ts. Install @shpbl/sdk and run node ci‑verify.ts on a single entry. If the verdict prints CERTIFIED, extend the script to loop over the whole catalogue and add the command to your CI configuration. By the end of the week you will have a CI‑driven, executable proof for every registry entry.