@kungfu-tech/kfd 1.0.0-alpha.3 → 1.0.0-alpha.5

package/README.md

@@ -115,13 +115,26 @@ e.g. `https://kfd.libkungfu.dev/1`). This repository publishes
 
 Machine consumers that need KFD-owned standard identity should read
 `standards.json`. It is the versioned metadata surface for stable standard
-keys, document routes, schema IDs, and KFD-owned concept names. In Node or
-TypeScript projects, import it as:
+keys, document routes and SHA-256 digests, schema IDs, KFD-owned concept names,
+and machine-interface contract versions. In Node or TypeScript projects, import
+it as:
 
 ```js
 import standards from "@kungfu-tech/kfd/standards.json" with { type: "json" };
 ```
 
+KFD package semver is only the distribution version. KFD-owned machine
+interfaces carry their own `schemaVersion` and `contract` fields. Compatible
+additions may keep the same interface version; semantic changes, required-field
+changes, verification meaning changes, or responsibility-boundary changes must
+use a new interface version or contract.
+
+KFD-2 publishes release-claims and release-trust-passport schemas under
+`schemas/kfd-2/`. These schemas let Buildchain and other release systems audit
+whether public release claims are bound to source facts, evidence, hashes,
+audit boundaries, residual risk, and responsibility state. See
+[`docs/kfd-2-release-trust.md`](docs/kfd-2-release-trust.md).
+
 KFD-3 also publishes a general collaboration-interface schema and witness
 schema under `schemas/kfd-3/`. These schemas are for participant-facing product
 interfaces, not only agent APIs. A product such as Kungfu may implement an
@@ -158,6 +171,8 @@ standards.json machine-readable KFD standard metadata (schemaVersion 1,
                contract kfd-standards-metadata)
 schemas/       JSON schemas for package metadata and KFD-owned schema IDs
 site/          machine-readable site bundle for kfd.libkungfu.dev renderers
+buildchain.release-propagation.json
+               Buildchain release propagation graph for KFD -> site consumers
 release-impact.json
                Buildchain surface-aware impact ledger for production release passports
 scripts/       conformance check: registry and documents must agree
@@ -165,7 +180,8 @@ scripts/       conformance check: registry and documents must agree
 
 `node scripts/check.mjs` (also `pnpm run check`) verifies numbering
 uniqueness, registry/document agreement, standards metadata/schema agreement,
-status validity, and the release impact ledger required by Buildchain
+status validity, decision document SHA-256 bindings, interface contract
+version bindings, and the release impact ledger required by Buildchain
 production release passports. Releases are governed by Buildchain; this package
 versions itself under KFD-1's own rules: the outer package line remains `v1.0`,
 while patch and prerelease numbers are advanced by Buildchain release

package/buildchain.release-propagation.json

@@ -0,0 +1,32 @@
+{
+  "schemaVersion": 1,
+  "contract": "kungfu-buildchain-release-propagation-graph",
+  "nodes": [
+    {
+      "id": "kfd",
+      "repository": "kungfu-systems/kfd",
+      "package": "@kungfu-tech/kfd"
+    },
+    {
+      "id": "site-libkungfu-dev",
+      "repository": "kungfu-systems/site-libkungfu-dev",
+      "lockPath": "buildchain.upstreams/kfd.release.json",
+      "baseRef": "main"
+    }
+  ],
+  "edges": [
+    {
+      "id": "kfd-to-site-libkungfu-dev",
+      "from": "kfd",
+      "to": "site-libkungfu-dev",
+      "channelPolicy": "preserve",
+      "consumes": [
+        "@kungfu-tech/kfd",
+        "site/kfd-site.json",
+        "registry.json",
+        "standards.json",
+        "decisions/*.md"
+      ]
+    }
+  ]
+}

package/docs/MAP.md

@@ -12,6 +12,7 @@
 | What does a specific decision say? | [`../decisions/`](../decisions) (index: [`../registry.json`](../registry.json)) |
 | What machine metadata should Buildchain or another consumer import for KFD standard identity and schema IDs? | [`../standards.json`](../standards.json) |
 | What schema validates the standards metadata surface? | [`../schemas/kfd-standards.schema.json`](../schemas/kfd-standards.schema.json) |
+| What schema should release systems use for KFD-2 release claims and trust passports? | [`kfd-2-release-trust.md`](kfd-2-release-trust.md) |
 | How do I cite a decision? | [`../README.md`](../README.md) — cite by number, e.g. `KFD-1` |
 | How do decisions change over time? | [`../CONTRIBUTING.md`](../CONTRIBUTING.md) — append-only; explicit supersession mints a new number |
 | How is this package versioned and released? | [KFD-1](../decisions/kfd-1.md) applied to itself; Buildchain governs releases |

package/docs/kfd-2-release-trust.md

@@ -0,0 +1,46 @@
+# KFD-2 Release Trust Metadata
+
+KFD-2 says that trust must start from inspectable facts and responsibility
+state. For releases, that means a product must not ask users or agents to trust
+release claims only because they appear in prose, changelogs, or repository
+history.
+
+This package defines two KFD-owned machine interfaces:
+
+- `schemas/kfd-2/release-claims.schema.json`: the product's declared public
+  release claims.
+- `schemas/kfd-2/release-trust-passport.schema.json`: the verifier's result
+  after auditing those claims against evidence.
+
+The intended Buildchain flow is:
+
+```text
+release claims -> evidence audit -> release trust passport -> release passport
+```
+
+Each claim should declare the statement being made, the source of the claim,
+machine-readable evidence, the audit boundary, residual risk, and responsibility
+state. The trust passport should then record whether each claim is bound to
+evidence, which evidence was checked, what the result was, and who owns the
+release decision.
+
+## Interface Versioning
+
+KFD package semver is only the distribution version. It is not the version of a
+KFD-owned machine interface.
+
+Every KFD-owned machine interface uses:
+
+- `schemaVersion`: the interface version consumed by tools.
+- `contract`: the stable contract name, such as `kfd-2-release-claims`.
+- `$id`: the canonical schema URL for the current stable interface.
+
+Compatible additions may keep `schemaVersion: 1`. A change that alters required
+fields, field semantics, verification meaning, audit boundary semantics, or
+responsibility semantics must not silently reuse the same interface contract.
+It must introduce a new interface version or, when the standard itself changes,
+a new KFD decision or amendment path.
+
+The same rule applies to KFD-1 and KFD-3 schemas. Their current schemas already
+carry `schemaVersion: 1` and a `contract` value; this document makes the
+evolution rule explicit across the KFD package.

package/kfd.release.json

@@ -0,0 +1,13 @@
+{
+  "schemaVersion": 1,
+  "contract": "kfd-release-anchor",
+  "line": "v1.0",
+  "channel": "alpha",
+  "npmPackage": "@kungfu-tech/kfd",
+  "npmVersion": "1.0.0-alpha.5",
+  "source": {
+    "repository": "kungfu-systems/kfd",
+    "branch": "alpha/v1/v1.0"
+  },
+  "rationale": "KFD uses an anchored/manual Buildchain mode: the public package version is an explicit release fact, while the outer KFD line remains v1.0."
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/kfd",
-  "version": "1.0.0-alpha.3",
+  "version": "1.0.0-alpha.5",
   "description": "Kung Fu Decisions (KFD): the kungfu-systems organization-wide decision registry, as a consumable artifact",
   "license": "Apache-2.0",
   "files": [
@@ -8,8 +8,12 @@
     "decisions",
     "registry.json",
     "standards.json",
+    "kfd.release.json",
     "schemas",
     "site",
+    "buildchain.release-propagation.json",
+    ".buildchain/kfd-1/contract-world.witness.json",
+    ".buildchain/kfd-3",
     "docs"
   ],
   "exports": {
@@ -17,14 +21,21 @@
     "./README.md": "./README.md",
     "./registry.json": "./registry.json",
     "./standards.json": "./standards.json",
+    "./kfd.release.json": "./kfd.release.json",
     "./site/kfd-site.json": "./site/kfd-site.json",
+    "./buildchain.release-propagation.json": "./buildchain.release-propagation.json",
+    "./buildchain/kfd-1/contract-world.witness.json": "./.buildchain/kfd-1/contract-world.witness.json",
+    "./buildchain/kfd-3/collaboration-interface.json": "./.buildchain/kfd-3/collaboration-interface.json",
+    "./buildchain/kfd-3/collaboration-interface.prebuild.json": "./.buildchain/kfd-3/collaboration-interface.prebuild.json",
+    "./buildchain/kfd-3/collaboration-interface.artifact.json": "./.buildchain/kfd-3/collaboration-interface.artifact.json",
     "./schemas/*.json": "./schemas/*.json",
     "./schemas/*/*.json": "./schemas/*/*.json",
     "./decisions/*.md": "./decisions/*.md",
     "./docs/*": "./docs/*"
   },
   "scripts": {
-    "check": "node scripts/check.mjs"
+    "check": "node scripts/check.mjs",
+    "update:kfd-3-witness": "node scripts/update-kfd-3-witness.mjs"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",

package/schemas/kfd-2/release-claims.schema.json

@@ -0,0 +1,332 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kfd.libkungfu.dev/schemas/kfd-2/release-claims.schema.json",
+  "title": "KFD-2 release claims",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "contract",
+    "standard",
+    "product",
+    "release",
+    "claims"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": 1
+    },
+    "contract": {
+      "const": "kfd-2-release-claims"
+    },
+    "standard": {
+      "const": "kfd-2"
+    },
+    "product": {
+      "$ref": "#/$defs/product"
+    },
+    "release": {
+      "$ref": "#/$defs/release"
+    },
+    "claims": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "$ref": "#/$defs/claim"
+      }
+    },
+    "schemaEvolution": {
+      "$ref": "#/$defs/schemaEvolution"
+    }
+  },
+  "additionalProperties": true,
+  "$defs": {
+    "product": {
+      "type": "object",
+      "required": [
+        "name"
+      ],
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1
+        },
+        "repository": {
+          "type": "string",
+          "minLength": 1
+        },
+        "package": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "additionalProperties": true
+    },
+    "release": {
+      "type": "object",
+      "required": [
+        "version",
+        "channel"
+      ],
+      "properties": {
+        "version": {
+          "type": "string",
+          "minLength": 1
+        },
+        "channel": {
+          "type": "string",
+          "minLength": 1
+        },
+        "tag": {
+          "type": "string",
+          "minLength": 1
+        },
+        "sourceSha": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "additionalProperties": true
+    },
+    "claim": {
+      "type": "object",
+      "required": [
+        "id",
+        "statement",
+        "source",
+        "evidence",
+        "auditBoundary",
+        "responsibility",
+        "status"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
+        },
+        "statement": {
+          "type": "string",
+          "minLength": 1
+        },
+        "category": {
+          "enum": [
+            "metadata",
+            "schema",
+            "package-export",
+            "artifact",
+            "site",
+            "release",
+            "kfd-1",
+            "kfd-2",
+            "kfd-3",
+            "other"
+          ]
+        },
+        "source": {
+          "$ref": "#/$defs/artifactPointer"
+        },
+        "evidence": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "$ref": "#/$defs/evidenceBinding"
+          }
+        },
+        "verification": {
+          "$ref": "#/$defs/verification"
+        },
+        "auditBoundary": {
+          "$ref": "#/$defs/auditBoundary"
+        },
+        "residualRisk": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "responsibility": {
+          "$ref": "#/$defs/responsibilityState"
+        },
+        "status": {
+          "enum": [
+            "declared",
+            "audited",
+            "enforced",
+            "not-applicable"
+          ]
+        }
+      },
+      "additionalProperties": true
+    },
+    "artifactPointer": {
+      "type": "object",
+      "required": [
+        "kind"
+      ],
+      "properties": {
+        "kind": {
+          "enum": [
+            "file",
+            "schema",
+            "package-export",
+            "artifact",
+            "command",
+            "witness",
+            "passport",
+            "url",
+            "other"
+          ]
+        },
+        "path": {
+          "type": "string",
+          "minLength": 1
+        },
+        "specifier": {
+          "type": "string",
+          "minLength": 1
+        },
+        "url": {
+          "type": "string",
+          "format": "uri"
+        },
+        "schemaId": {
+          "type": "string",
+          "format": "uri"
+        },
+        "sha256": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{64}$"
+        },
+        "digest": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "additionalProperties": true
+    },
+    "evidenceBinding": {
+      "type": "object",
+      "required": [
+        "type"
+      ],
+      "properties": {
+        "type": {
+          "enum": [
+            "file",
+            "schema",
+            "package-export",
+            "artifact",
+            "hash",
+            "command-result",
+            "witness",
+            "passport-section",
+            "url",
+            "other"
+          ]
+        },
+        "pointer": {
+          "$ref": "#/$defs/artifactPointer"
+        },
+        "description": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "additionalProperties": true
+    },
+    "verification": {
+      "type": "object",
+      "properties": {
+        "resultRef": {
+          "$ref": "#/$defs/artifactPointer"
+        },
+        "command": {
+          "type": "string",
+          "minLength": 1
+        },
+        "expectedResult": {
+          "enum": [
+            "pass",
+            "fail",
+            "warning",
+            "unverifiable"
+          ]
+        }
+      },
+      "additionalProperties": true
+    },
+    "auditBoundary": {
+      "type": "object",
+      "required": [
+        "scope",
+        "enumerability"
+      ],
+      "properties": {
+        "scope": {
+          "type": "string",
+          "minLength": 1
+        },
+        "enumerability": {
+          "enum": [
+            "closed-world",
+            "declared-open",
+            "sampled",
+            "manual"
+          ]
+        },
+        "exclusions": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      },
+      "additionalProperties": true
+    },
+    "responsibilityState": {
+      "type": "object",
+      "required": [
+        "sourceOwner",
+        "verificationOwner",
+        "releaseDecisionOwner"
+      ],
+      "properties": {
+        "sourceOwner": {
+          "type": "string",
+          "minLength": 1
+        },
+        "verificationOwner": {
+          "type": "string",
+          "minLength": 1
+        },
+        "releaseDecisionOwner": {
+          "type": "string",
+          "minLength": 1
+        },
+        "escalation": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "additionalProperties": true
+    },
+    "schemaEvolution": {
+      "type": "object",
+      "required": [
+        "interfaceVersion",
+        "compatibilityRule"
+      ],
+      "properties": {
+        "interfaceVersion": {
+          "const": 1
+        },
+        "compatibilityRule": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "additionalProperties": true
+    }
+  }
+}