Embedding Certification Metadata in Release Manifests

The hidden risk in green test suites

Most CI pipelines stop at “all tests pass”. That verdict tells you the code compiles and the unit suite ran without failure. It does not tell you whether the artifact behaves correctly under the contract the harness defines. The gap between a green test suite and a formally verified artifact is where regressions slip into production. Teams that ignore this gap often discover bugs after release, because the test suite never exercised the edge cases the harness checks.

Adding certification metadata to the release manifest

The certification harness runs the artifact against a matrix of 40 primitives and records a single verdict: CERTIFIED, PROVISIONAL, INCONCLUSIVE, or FAILED. The harness can emit that verdict as structured data. The simplest place to store it is the release manifest that already travels with the artifact.

{
  "name": "my-lib",
  "version": "1.4.2",
  "sha256": "3a7f…e9c1",
  "certification": {
    "verdict": "PROVISIONAL",
    "timestamp": "2026-10-20T12:34:56Z",
    "harnessRunId": "h-7f9b3c"
  }
}

The field is called certification metadata. It is computed, not generated, and therefore repeatable. Because the manifest is a plain file, any downstream tool can read the JSON without needing a special client.

Embedding the metadata happens as part of the build‑intent gate. The gate registers the write, resolves licensing, and returns the terminal state. When the harness finishes, the build step writes the verdict into the manifest before the artifact is published. No manual step is required.

Enforcing policy in your pipeline

Once the manifest carries the harness verdict, the CI job can enforce a policy that matches your risk tolerance.

1. Parse the manifest after the artifact is built.
2. Inspect certification.verdict.
3. Fail the job if the verdict is not CERTIFIED (or PROVISIONAL if you accept a feature‑flag style gate).

Because the verdict is a single string, the check can be a one‑liner in any script language. For example, in a Bash step:

verdict=$(jq -r .certification.verdict release-manifest.json)
if [[ $verdict != "CERTIFIED" ]]; then
  echo "Release blocked: harness verdict $verdict"
  exit 1
fi

The same logic can be expressed in a TypeScript pipeline using the typed client from @shpbl/sdk. The client reads the manifest via the HTTP API, providing verification logic that behaves consistently across environments.

Embedding certification metadata also enables downstream consumers—deployment tools, service meshes, or downstream teams—to make automated decisions without contacting the harness again. The manifest becomes a portable proof of the artifact’s status, aligning with the principle that “the artifact carries its own certification”.

The approach ties directly into the layered verdict model described in the pillar post /blog/the-four-verdicts-between-green-tests-and-correct-code. By naming the rung (the harness verdict) explicitly in the manifest, you avoid the temptation to claim a higher level of correctness than you have earned.

How SHPBL makes this straightforward

SHPBL provides a repeatable certification harness that runs artifacts and records a verdict. The harness output can be written directly into the release manifest as certification metadata. The harness is reachable through the MCP server, the plain HTTP API, and the typed TypeScript client, allowing the manifest‑embedding step to be performed in any environment with consistent results. For a concrete example of CI integration, see our post on /blog/ci-integration-of-harness-verdicts-to-block-unsafe-deploys.

Start by adding a post‑build step that calls the harness (see /harness) and writes the JSON snippet above into your manifest. Commit the change, and your next pipeline run will enforce the policy automatically.

---

Monday action: Add a script to your build pipeline that runs the SHPBL harness, extracts the verdict, and injects it into your release manifest as shown. Then add a CI check that aborts on any verdict other than CERTIFIED. You’ll have a concrete, enforceable gate between compilation and correctness.