KFD independent verifier

August 12, 2026 ยท View on GitHub

kfd is the independent verification side of KFD conformance. It is a Rust library with native CLI and WebAssembly projections. It deliberately contains no Kungfu, Xinfa, Buildchain, Shifu, or other product code dependency.

The verifier is implemented from published schemas and specifications. A profile is enabled only when those public sources are precise enough for an independent implementation to fail closed. Product implementations remain the format authorities; KFD owns the verifier profile, report contract, and the claim that a passing object satisfies the checks enumerated by that profile.

Command surface

The Rust-native binary implements the offline verify and bundle commands shown below. Commands such as gate, scaffold, and test are supplied by the npm host and are not native-binary capabilities. See Native CLI downloads for platform assets and checksums.

kfd verify kfd-record <json-file> [--schema <schema-file>] [--json]
kfd verify passport <file-or-directory> [--json]
kfd verify pack <file-or-directory> [--json]
kfd verify atlas <file-or-directory> [--json]
kfd verify episode <directory> [--json]
kfd verify agent-runtime-report <report.json> [--json]
kfd verify self-conformance-transition <transition-bundle.json> [--json]
kfd bundle <kind> <file-or-directory> --output <bundle.json>
kfd verify bundle <bundle.json> [--json]

npx @kungfu-tech/kfd provides the broader host command surface and uses the packaged WebAssembly projection for shared verification operations. Native and WebAssembly verification consume the same kfd.verification-bundle/v1 input and emit the same kfd.verification-report/v1 JSON bytes.

Report contract

Every invocation returns one report:

{
  "schemaVersion": 1,
  "contract": "kfd.verification-report/v1",
  "profile": "xinfa.context-pack/v1",
  "valid": true,
  "qualifying": false,
  "selfCertified": false,
  "offline": true,
  "checks": [],
  "issues": []
}

The verifier proves only the checks named by profile and checks. It does not prove work quality, source completeness, product fitness, human approval, or release authorization. A structurally valid KFD record does not prove that its claim is true. A verified Git Episode segment preserves a qualified Episode root; it does not recompute the journal-native POD root.

Issues have stable code, path, and message fields. Unknown contracts, unknown schema versions, missing sibling evidence, non-canonical bytes, root drift, and unsupported semantics fail closed.

Canonical JSON

The common root algorithm is sha256-kfd-canonical-json-v1:

  • JSON only; duplicate object keys are rejected by the parser;
  • object keys are ordered by UTF-8 byte order;
  • strings and object keys must already be NFC-normalized;
  • integers must be non-negative and no larger than 2^53 - 1;
  • floating-point and exponent number encodings are rejected;
  • no insignificant whitespace is emitted;
  • a single LF is appended before SHA-256 hashing;
  • roots use sha256:<64 lowercase hexadecimal digits>.

Profiles whose owner specifies different byte framing declare it explicitly. For example, artifact digests hash exact bytes without adding LF, while Git Episode provider and qualification roots hash canonical JSON without an added LF. Episode claims hash the complete canonical JSONL byte stream including its terminal LF.

Verification profiles

KFD record

The verifier selects the schema from an explicit --schema file or the record's $schema. Built-in KFD schemas resolve only to packaged schema IDs; the verifier never fetches a schema over the network. The supported JSON-Schema subset is the subset used by the published KFD schemas:

  • type, required, properties, additionalProperties;
  • const, enum, pattern, format: uri;
  • minLength, minimum;
  • items, minItems, maxItems, uniqueItems;
  • $ref to local definitions or another packaged KFD schema;
  • allOf, contains, if, and then;
  • patternProperties.

An unsupported schema keyword fails closed instead of being ignored. The packaged KFD-7 Domain Profile Declaration schema is discoverable by either its canonical $schema URI or contract: kfd-7-domain-profile. Its example Domain Profile fixture passes structurally, while missing-coordinate and premature-activation fixtures are required to fail identically in native and WebAssembly verification.

Buildchain release passport

The v1 profile verifies the documented release-evidence closure:

  • v1 contract identity for the passport and its product mechanism, artifact-evidence, impact, and agent-index siblings;
  • release tag and artifact inventory;
  • every passport artifact is matched to sibling evidence by structured identity and digest;
  • optional package-set, trusted-publishing, transaction, and anchor-manifest sections are complete when present;
  • the impact ledger and passport expose the same surface-impact inventory.

The verifier never follows HTTP URLs. A remote passport must first be materialized as a local bundle with all sibling evidence.

Xinfa Context Pack

The v1 profile verifies:

  • the published Context Pack schema;
  • Pack, source, policy, cut, authority, and coverage roots;
  • exact UTF-8 inventory content roots and sizes;
  • route roots, selected-node authority roots, status, and two-audience parity;
  • directory manifest binding to the exact pack.json bytes;
  • non-qualifying, non-self-certified receipt binding.

Xinfa Atlas

The v1 profile verifies:

  • the published Atlas schema and immutable identity;
  • Atlas and component roots;
  • declared-scope and compatibility bindings;
  • the complete embedded Context Pack;
  • exact derived Human and Agent views;
  • the directory manifest and non-qualifying receipt.

The Xinfa schema root is computed from the packaged, digest-pinned public schema set rather than imported from a product binary.

Git Workspace Episode

The v1 profile verifies the public qualified-shadow representation:

  • manifest contract and provider-root preimage;
  • the requested semantic-root directory coordinate;
  • qualification canonical bytes, root, ended/ok status, typed-fold policy, Episode identity, and safe export_evidence capability;
  • canonical JSONL framing, terminal LF, digest, count, zero-based order, duplicate indexes, and segment schema;
  • the explicit authority boundary: the semantic root is preserved but not recomputed by this profile.

KFD Agent runtime report

The kfd.agent-runtime-report/v1 profile verifies the packaged kfd-agent-runtime@0.1.0-alpha.1 manifest and fixed KFD Runtime 100 registry:

  • exact profile manifest, Agent Hub dependency, suite version and vector roots;
  • one result for each of the 100 fixed IDs, with no duplicate, missing, unknown or reclassified result;
  • fixed expected status/code, adapter actual status/code, retained response, response root and adapter identity agreement;
  • handshake, transcript and aggregate result roots;
  • independent 35 Core / 65 Experimental partition summaries;
  • adapter artifact/source coordinates, offline execution and fixed non-qualifying/non-self-certified scope.

Unknown roots, expectation drift, result mutation, partition widening, incomplete results, placeholder source commits, or stronger claim flags fail closed. Verification does not attest that the recorded process execution occurred; it proves the retained report is closed under the packaged profile and roots.

KFD Self-Conformance transition

The kfd.self-conformance-transition/v1 profile independently verifies the published kfd-self-conformance@1.0.0-alpha.1 transition contract:

  • strict canonical JSON, closed bundle/state fields, and exact profile version;
  • recomputed previous/proposed state roots and the packaged schema-set root;
  • sorted, unique evidence, gap, and immutable-coordinate sets;
  • separate verifier, authority, review, evidence, and predecessor root roles;
  • the exact reviewed bootstrap anchor or a finite report/package predecessor;
  • non-self-containing and non-circular root preimages;
  • the closed transition table, subject/publication preservation, explicit gaps, bounded claims, and expected-result agreement.

The fixed machine matrix covers positive bootstrap and report-predecessor chains plus missing, malformed, stale, conflicting, reordered, substituted, circular, self-containing, wrong-predecessor, wrong-authority, review-gap, and claim-overreach failures. Historical regressions remain protocol fixtures and do not import adopter behavior. A pass remains structural, non-qualifying, non-self-certified, offline, and insufficient for any governance or release decision.

KFD Self-Conformance lifecycle gate

The host-side lifecycle gate composes the independent transition verifier with the published lifecycle-gates.json policy. For every entry from the approved bootstrap anchor to the requested terminal transition it reproduces the WASM report, checks the exact bundle/report/package roots, verifies state and predecessor continuity, and matches the supplied authority and independent- review receipt bytes to the roots carried by the bundle.

The terminal Candidate, qualification, draft-promotion, activation, supersession, Foundation Revision, or release path must match its published transition, authority role, and decision. Absent, stale, wrong-root, wrong-predecessor, wrong-authority, missing-review, claim-overreach, and package-substitution evidence fails closed with stable diagnostics. A valid revision, rejection, provisional-retention, or no-new-KFD chain returns non-promotion and retains counterevidence; it is not coerced into proceed.

This composition is intentionally host-side because it reads a chain of objects and produces a retained gate report. Every transition bundle inside the chain is still verified by the independent packaged WebAssembly core. The gate marks verifierNecessary: true, verifierSufficient: false, and all automatic authority flags false.

KFD Agent Hub report

The kfd.agent-hub-report/v1 host profile verifies the fixed Agent Hub 20 report against the installed package:

  • exact package manifest, release anchor, profile, protocol, vector, failure inventory, and verifier bytes;
  • unique rooted capability documents for at least two Hubs and their handshake binding;
  • exactly one retained response and fixed three-field outcome for every vector;
  • response, result, and reconstructed transcript roots;
  • offline execution plus fixed non-qualifying and non-certifying scope;
  • optional exact adapter-byte binding with --adapter.

The verifier fails closed on unsupported profile versions, unknown or missing results, duplicate IDs, expected-outcome drift, root mutation, capability mutation, adapter drift, or claim widening. It remains one host-side Node authority because it reads installed package and optional adapter bytes. No Agent Hub report checks are duplicated in the Rust/WASM bundle verifier. A future move requires a versioned self-contained bundle kind and byte-for-byte native/WASM parity for the complete check set; process spawning remains host-only.

Independence and extraction

verifier/extraction-manifest.json is an allowlist for a clean extraction. The extraction contains verifier source, packaged public schemas, fixtures, and license files only. It rejects path, Git, private-registry, monorepo-relative, and product-code dependencies. Tests build the extraction with cargo build --locked, run native fixtures, build WebAssembly, and compare the native and WebAssembly reports byte for byte.

The verifier performs no network calls. Paths are resolved only inside the caller-provided object directory. Symlinks and path escape fail closed.

Versioning

The CLI is a KFD-1 welded surface with its own interface version. Compatible additions may keep kfd.verifier/v1. A command rename, required-input change, canonicalization change, report-meaning change, weaker check, or responsibility boundary change requires a new interface version or explicit compatibility action. The outer @kungfu-tech/kfd package remains on its KFD-governed v1.0 line.