Executable Registry Entries as Live Component Tests

Stubs masquerade as inventory

A component count that includes entries without executable proof is a false inventory. In most organisations the registry is populated from build artefacts, issue trackers or manual submissions. Half of those rows are placeholders – a name, a version string, a short description. They pass a static lint, but nothing ever runs them. When a downstream team queries the registry for a dependency, the answer looks complete, yet the underlying artefact may never compile, may be missing transitive imports, or may have been removed from source control. The failure mode is clear: the inventory claims health, but the evidence is absent.

Executable proof as the missing invariant

The only way to guarantee that a registry row represents a usable component is to execute it against a known contract. SHPBL’s certification harness provides exactly that invariant. An entry is wrapped in a lightweight harness that:

1. Installs the artefact in an isolated environment.
2. Executes a predefined entry‑point or test script.
3. Records the outcome as CERTIFIED, PROVISIONAL, INCONCLUSIVE, or FAILED.

The harness does not rely on any model output; it runs the code exactly as shipped. The result is stored alongside the row, turning the catalog into a living test suite. When the harness reports CERTIFIED, the row can be trusted as part of a real inventory. When it reports FAILED or INCONCLUSIVE, the row is flagged for remediation or removal.

A concrete walk‑through

Consider an internal utility library @org/logging. The registry currently holds a stub entry:

{
  "name": "@org/logging",
  "version": "2.1.0",
  "description": "Centralised logging helpers",
  "status": "registered"
}

No build artefact is attached, and the entry never leaves the documentation portal. To turn this into executable proof:

1. Create a harness script that installs the package and runs its exported testHealth function.

npm install @org/logging@2.1.0
node -e "require('@org/logging').testHealth().then(r=>process.exit(r?0:1))"

1. Register the harness with the certification system via the HTTP API (/api-access). The API call includes the script, the expected contract (the testHealth promise resolves to true), and any runtime constraints.

1. Run the harness. The system spawns an isolated container, executes the script, and captures the exit code. In this case the script exits with 1 because the package no longer exports testHealth.

1. Record the verdict. The harness writes a FAILED status back to the registry row, and the row now carries a concrete health signal.

After this process the registry entry looks like:

{
  "name": "@org/logging",
  "version": "2.1.0",
  "description": "Centralised logging helpers",
  "status": "FAILED",
  "lastChecked": "2026-11-04T09:12:00Z",
  "harnessId": "h-7f3c2a"
}

The entry is no longer a silent stub; it is an actionable item. A developer scanning the inventory can instantly see that @org/logging needs attention, and automated tooling can exclude it from builds until the issue is resolved.

Turning the whole catalog into a health monitor

When every row is paired with a harness, the registry becomes a continuous health monitor rather than a static list. The benefits are immediate:

• Predictable builds – downstream pipelines can gate on the CERTIFIED flag, avoiding surprise breakages.
• Focused remediation – rows that are FAILED or INCONCLUSIVE are obvious candidates for cleanup, reducing technical debt.
• Quantifiable inventory – the count of CERTIFIED rows is a true inventory, as described in the pillar post /blog/a-component-count-is-not-an-inventory.

Implementing this at scale does not require a wholesale rewrite of existing tooling. The harness is lightweight, runs from files, and can be invoked through the same HTTP API used for other catalog operations. The live run view on the /harness page demonstrates the process on a real component, showing how quickly a verdict is produced.

Monday’s concrete step

Pick a single high‑traffic component that currently exists only as metadata. Write a one‑line harness script that installs the component and runs a basic sanity check (for a library, a require followed by a no‑op function call is sufficient). Register the script via the API, execute it, and record the verdict back into the registry. By the end of the day you will have turned a stub into an executable proof, and you will have a template you can apply to the rest of the catalog.