Executable Registry Audits Eliminate Stub Entries

The stub problem

Your registry lists thousands of components, yet many rows are placeholders. They contain a name, a version and a short description, but no build artefact, no test suite, no entry‑point. When a downstream team pulls one of these entries, the build fails or the component behaves unexpectedly. The stub is a lie: the count says “present”, the reality says “absent”.

The failure mode is simple. A stub passes the static validation that checks for required fields, but it never passes an execution test. Because the registry never exercises the artefact, the stub remains unchallenged. Over time the stub count grows, and the inventory becomes a liability rather than an asset.

Why metadata alone is insufficient

Metadata describes intent. It does not prove capability. A component can claim to be “node‑compatible” while its source never compiles, or it can claim to expose a REST endpoint that never starts. The pillar post A component count is not an inventory explains that a trustworthy software inventory must be executable.

When you rely only on the catalog, you inherit three risks:

1. Silent breakage – a downstream build breaks without a trace back to the registry.
2. Stale stubs – entries that were never promoted to real artefacts linger indefinitely.
3. Mis‑allocation of effort – teams waste time investigating missing behaviour that never existed.

The only way to eliminate these risks is to verify that each row can be read, built and run.

Executable verification as a registry audit

An executable verification run is a registry audit that treats every row as a test case. The audit follows a fixed harness that attempts to:

• fetch the source or binary,
• resolve its declared dependencies,
• compile or install it,
• launch the component in a minimal environment, and
• record the outcome as CERTIFIED, PROVISIONAL, INCONCLUSIVE or FAILED.

The harness is model‑independent. It does not guess whether the component should work; it simply executes the steps defined by the component’s contract. The result is a binary verdict that replaces the previous “present” flag.

Consider a simple Node library registered as utils@1.2.3. The audit script performs:

git clone https://repo.example.com/utils.git
cd utils
npm ci
node -e "require('./index.js')"

If the script exits with code 0, the row is marked CERTIFIED. If the build succeeds but the runtime throws, the row is FAILED. If the harness cannot locate a required file, the row is INCONCLUSIVE – a limit of the harness, not a defect in the component.

Running this audit across the entire registry produces a new column: execution grade. Stubs that never produced a binary artefact end up FAILED or INCONCLUSIVE and can be filtered out. The remaining CERTIFIED rows constitute a software inventory that can be queried, reused and composed with confidence.

Turning the audit into a reusable inventory

The audit is not a one‑off operation. It should be part of the continuous integration pipeline that governs registry writes. Every time an agent proposes a new entry, the Build Intent gate registers the proposal, resolves licensing and invariants, and then triggers the same harness. The preview costs nothing; the final artefact is stored only after it receives a CERTIFIED verdict.

Because the harness runs on the same tools used by downstream consumers – the plain HTTP API, the typed TypeScript client, or the offline file edition – the grades are portable. A downstream service can request only CERTIFIED components via the API, guaranteeing that it never receives a stub.

The result is a trusted software inventory:

• each row is executable,
• each row carries a reproducible grade,
• each row can be filtered by grade, and
• the inventory can be safely exported or shared, because the underlying archives are sealed with published checksums.

What to do on Monday

Schedule a one‑day registry audit for the components you own. Use the free repository evaluation lane to run the harness against a representative slice of your registry. Record the grades, remove any rows that return FAILED or INCONCLUSIVE, and promote the CERTIFIED rows to your production catalog.

When the audit finishes, you will have a leaner, executable‑verified inventory that your teams can trust. The next time a build fails, you will know whether the fault lies in the component or elsewhere – because the registry no longer hides stub entries behind a count.