Controller Evidence

status: draft period: ongoing theme: buildchain-controller-evidence doc_type: analysis source_level: local-files confidence: high sensitivity: public evidence_grade: B review_state: unreviewed last_reviewed: 2026-07-14 ai_provenance: model_family: GPT-5 product: Codex generated_at: 2026-07-14 boundary: Based on repository source and tests; no claim about unobserved downstream runs.

Buildchain controller evidence records what a reusable workflow intended to do and what it actually completed. It is a project-independent envelope around Buildchain orchestration; it does not replace a consumer project’s own policy, Gate registry, or domain receipts.

The machine-readable entrypoint is dist/site/controller-registry.json. The Node API is exported as @kungfu-tech/buildchain/controller-evidence.

Public controller inventory

The first versioned inventory contains:

source check;
lifecycle build and channel routing;
the Shifu Gate profile envelope;
web-surface build/deploy orchestration;
publication artifact and paper release;
release-candidate promotion;
release propagation.

Patrol and repository-maintenance workflows are not controllers. A controller descriptor declares its workflow, version, input classifications, expected stages, capabilities, evidence kinds, and a deterministic descriptor digest.

Plan contract

A buildchain.controller-evidence/v1 plan binds:

the controller id, version, workflow path, and descriptor digest;
the exact consumer repository and 40-character source SHA;
the requested Buildchain ref, exact runtime SHA, and runtime contract digest;
normalized inputs;
expected stages, capabilities, and evidence kinds.

Inputs use one of four policies:

included for safe scalar values;
digest-only for commands, structured values, runner selection, paths, role identifiers, registries, mirrors, and other environment-shaped values;
redacted for workflow secrets and token/private-key shaped fields;
unsupported for a declared input that must fail closed when provided.

Redacted inputs carry no value, digest, or presence bit. Included path-like inputs reject absolute runner paths. Undeclared inputs fail plan creation.

Receipt and aggregation

A receipt binds back to the plan digest and repeats the source and runtime identities. Every declared stage is recorded as passed, failed, skipped, cancelled, or missing; the receipt status is passed, failed, skipped, or partial. Evidence is represented by kind and SHA-256 digest, with an optional artifact name.

Reusable workflows expose these outputs:

controller-plan-artifact, controller-plan-json, and controller-plan-digest;
controller-receipt-artifact, controller-receipt-json, controller-receipt-digest, and controller-receipt-status.

Final aggregation uses always(). A required missing stage, required missing evidence, invalid digest, source/runtime mismatch, or missing receipt cannot be reported as qualifying green. aggregateControllerReceipts() reports an explicit receipt-missing status when a plan has no receipt.

Shifu boundary

The Shifu profile controller is an envelope only. Its controller receipt references the digest and status of buildchain.shifu-gate-aggregate/v1; it does not copy project Gate identifiers, Gate semantics, registry contents, or per-Gate results into Buildchain’s generic controller contract.

Release Passport references

Release-candidate and final Release Passport documents may carry compact controllerReceipts[] references. Each reference contains the controller id, plan and receipt digests, source and runtime SHAs, status, and artifact name. The passport validates those identities; it never invents a controller receipt from a successful job conclusion.

The PR-stage lifecycle build creates its qualifying receipt before the release-candidate passport. Promotion validates that passport and preserves the same references in the final Release Passport, closing the build-to-publish evidence chain.

Train validation

An unreleased contract should be tested through a temporary Buildchain train ref and an exact downstream consumer source SHA. The downstream run should retain the plan artifact, receipt artifact, workflow outputs, and Release Passport or release-candidate reference. Promote to an official alpha or stable channel only after those identities and digests agree.

Controller Evidence