@kungfu-tech/kfd 1.0.0-alpha.2 → 1.0.0-alpha.4

package/.buildchain/kfd-1/contract-world.witness.json

@@ -0,0 +1,161 @@
+{
+  "id": "kfd-standard-package",
+  "standard": "kfd-1",
+  "source": {
+    "repo": "kungfu-systems/kfd",
+    "factSource": "standards.json"
+  },
+  "contractWorld": {
+    "id": "kfd-standard-package",
+    "kind": "standard-metadata",
+    "name": "KFD standards metadata and release propagation surfaces",
+    "schemaId": "https://kfd.libkungfu.dev/schemas/kfd-1/contract-world.schema.json",
+    "digest": "sha256:394139c8915426e81eee7f7ea9f3d8209eb0e2b566ddadfccbddea2a3563585d"
+  },
+  "canonicalPolicy": {
+    "path": "standards.json",
+    "sha256": "394139c8915426e81eee7f7ea9f3d8209eb0e2b566ddadfccbddea2a3563585d"
+  },
+  "registry": {
+    "path": "registry.json",
+    "sha256": "b83cfadeb726e18f96ec4f7451c66091892f4964420dd81939d1120108991c38"
+  },
+  "surfaces": [
+    {
+      "name": "kfd-1-document",
+      "sourcePath": "decisions/kfd-1.md",
+      "sourceSha256": "2ef7438b0737009d36da248d2ecec5f788d46a93b184efadf5e2e31ca20254f0",
+      "artifactPath": "decisions/kfd-1.md",
+      "expectedSha256": "2ef7438b0737009d36da248d2ecec5f788d46a93b184efadf5e2e31ca20254f0",
+      "byteForByte": true
+    },
+    {
+      "name": "kfd-2-document",
+      "sourcePath": "decisions/kfd-2.md",
+      "sourceSha256": "b8be7b7526dcec9ea501998056c55f546492abc4eb63484a9bb8856eb434b710",
+      "artifactPath": "decisions/kfd-2.md",
+      "expectedSha256": "b8be7b7526dcec9ea501998056c55f546492abc4eb63484a9bb8856eb434b710",
+      "byteForByte": true
+    },
+    {
+      "name": "kfd-3-document",
+      "sourcePath": "decisions/kfd-3.md",
+      "sourceSha256": "e329bef41ab5cb689346333df317b39918ea1016424a872e438eea8090070b96",
+      "artifactPath": "decisions/kfd-3.md",
+      "expectedSha256": "e329bef41ab5cb689346333df317b39918ea1016424a872e438eea8090070b96",
+      "byteForByte": true
+    },
+    {
+      "name": "kfd-registry",
+      "sourcePath": "registry.json",
+      "sourceSha256": "b83cfadeb726e18f96ec4f7451c66091892f4964420dd81939d1120108991c38",
+      "artifactPath": "registry.json",
+      "expectedSha256": "b83cfadeb726e18f96ec4f7451c66091892f4964420dd81939d1120108991c38",
+      "byteForByte": true
+    },
+    {
+      "name": "kfd-standards",
+      "sourcePath": "standards.json",
+      "sourceSha256": "394139c8915426e81eee7f7ea9f3d8209eb0e2b566ddadfccbddea2a3563585d",
+      "artifactPath": "standards.json",
+      "expectedSha256": "394139c8915426e81eee7f7ea9f3d8209eb0e2b566ddadfccbddea2a3563585d",
+      "byteForByte": true
+    },
+    {
+      "name": "kfd-standards-schema",
+      "sourcePath": "schemas/kfd-standards.schema.json",
+      "sourceSha256": "2ecc7049d13463700f143f4e8c40488d6587484c94d26e827c239eeedc892336",
+      "artifactPath": "schemas/kfd-standards.schema.json",
+      "expectedSha256": "2ecc7049d13463700f143f4e8c40488d6587484c94d26e827c239eeedc892336",
+      "byteForByte": true
+    },
+    {
+      "name": "kfd-1-contract-world-schema",
+      "sourcePath": "schemas/kfd-1/contract-world.schema.json",
+      "sourceSha256": "6be00cca75c80bf96429eb62336989d8931ea380d86388fcb8b834dcf8d3c13b",
+      "artifactPath": "schemas/kfd-1/contract-world.schema.json",
+      "expectedSha256": "6be00cca75c80bf96429eb62336989d8931ea380d86388fcb8b834dcf8d3c13b",
+      "byteForByte": true
+    },
+    {
+      "name": "kfd-1-witness-schema",
+      "sourcePath": "schemas/kfd-1/witness.schema.json",
+      "sourceSha256": "50104a2962cb75cc1da634fa65553e993f87d8fb9b3c237f0609a2208ad4c1f3",
+      "artifactPath": "schemas/kfd-1/witness.schema.json",
+      "expectedSha256": "50104a2962cb75cc1da634fa65553e993f87d8fb9b3c237f0609a2208ad4c1f3",
+      "byteForByte": true
+    },
+    {
+      "name": "kfd-2-release-claims-schema",
+      "sourcePath": "schemas/kfd-2/release-claims.schema.json",
+      "sourceSha256": "cf90ef7d0a7c2abc33af0d97d793b7e9c3ed96335da0b79a082523139282963e",
+      "artifactPath": "schemas/kfd-2/release-claims.schema.json",
+      "expectedSha256": "cf90ef7d0a7c2abc33af0d97d793b7e9c3ed96335da0b79a082523139282963e",
+      "byteForByte": true
+    },
+    {
+      "name": "kfd-2-release-trust-passport-schema",
+      "sourcePath": "schemas/kfd-2/release-trust-passport.schema.json",
+      "sourceSha256": "92bdd34c0575d18240d1c8be12e86034209f54819048ead9617e7aa2e539aaef",
+      "artifactPath": "schemas/kfd-2/release-trust-passport.schema.json",
+      "expectedSha256": "92bdd34c0575d18240d1c8be12e86034209f54819048ead9617e7aa2e539aaef",
+      "byteForByte": true
+    },
+    {
+      "name": "kfd-3-collaboration-interface-schema",
+      "sourcePath": "schemas/kfd-3/collaboration-interface.schema.json",
+      "sourceSha256": "03e8d54c08f26bf8aff570995142684b04f0c97578c5fb58d29bc9f1559206d6",
+      "artifactPath": "schemas/kfd-3/collaboration-interface.schema.json",
+      "expectedSha256": "03e8d54c08f26bf8aff570995142684b04f0c97578c5fb58d29bc9f1559206d6",
+      "byteForByte": true
+    },
+    {
+      "name": "kfd-3-witness-schema",
+      "sourcePath": "schemas/kfd-3/witness.schema.json",
+      "sourceSha256": "cb80768ab8a4f90f86d256555b1995ddb516371ccbe291a8c28581fa371ccd10",
+      "artifactPath": "schemas/kfd-3/witness.schema.json",
+      "expectedSha256": "cb80768ab8a4f90f86d256555b1995ddb516371ccbe291a8c28581fa371ccd10",
+      "byteForByte": true
+    },
+    {
+      "name": "release-propagation-graph",
+      "sourcePath": "buildchain.release-propagation.json",
+      "sourceSha256": "007b465f3a69b25cf9bb7554e8c0e8727dbd5d5440b2e496d8c257f0ef69c011",
+      "artifactPath": "buildchain.release-propagation.json",
+      "expectedSha256": "007b465f3a69b25cf9bb7554e8c0e8727dbd5d5440b2e496d8c257f0ef69c011",
+      "byteForByte": true
+    },
+    {
+      "name": "buildchain-build-workflow",
+      "sourcePath": ".github/workflows/build.yml",
+      "sourceSha256": "a3e3f935897f16af86f468c8ee0a4500e2d68828e62411df88684087c65a73ad",
+      "artifactPath": ".github/workflows/build.yml",
+      "expectedSha256": "a3e3f935897f16af86f468c8ee0a4500e2d68828e62411df88684087c65a73ad",
+      "byteForByte": true
+    },
+    {
+      "name": "buildchain-ref-promotion-workflow",
+      "sourcePath": ".github/workflows/buildchain-ref-promotion.yml",
+      "sourceSha256": "f947f5ab19a856914ea03fb094580c9c7cf4b63d6690b88240b7558b40778e2e",
+      "artifactPath": ".github/workflows/buildchain-ref-promotion.yml",
+      "expectedSha256": "f947f5ab19a856914ea03fb094580c9c7cf4b63d6690b88240b7558b40778e2e",
+      "byteForByte": true
+    },
+    {
+      "name": "release-propagation-workflow",
+      "sourcePath": ".github/workflows/release-propagation.yml",
+      "sourceSha256": "216710af3be1ac6e85dc50836f21e4bdfe7a28fdec47647e843baa2cc7c9b4e7",
+      "artifactPath": ".github/workflows/release-propagation.yml",
+      "expectedSha256": "216710af3be1ac6e85dc50836f21e4bdfe7a28fdec47647e843baa2cc7c9b4e7",
+      "byteForByte": true
+    },
+    {
+      "name": "verify-workflow",
+      "sourcePath": ".github/workflows/verify.yml",
+      "sourceSha256": "448f4b6b8263399005a9866cee7906f5334cf5e3daea7d13c70768e586576947",
+      "artifactPath": ".github/workflows/verify.yml",
+      "expectedSha256": "448f4b6b8263399005a9866cee7906f5334cf5e3daea7d13c70768e586576947",
+      "byteForByte": true
+    }
+  ]
+}

package/README.md

@@ -115,13 +115,34 @@ 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
+agent-first profile, but that profile remains a product-specific realization of
+KFD-3. The KFD-owned boundary is the standard vocabulary, schema IDs, and
+closed-world evidence shape. See
+[`docs/kfd-3-collaboration-interface.md`](docs/kfd-3-collaboration-interface.md).
+
 ## Current decisions
 
 | ID | Kind | Title | Status |
@@ -150,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
@@ -157,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,25 @@
+{
+  "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": "dev/v2/v2.7"
+    }
+  ],
+  "edges": [
+    {
+      "id": "kfd-to-site-libkungfu-dev",
+      "from": "kfd",
+      "to": "site-libkungfu-dev",
+      "channelPolicy": "preserve"
+    }
+  ]
+}

package/docs/MAP.md

@@ -8,9 +8,11 @@
 | What should a site renderer consume to render `kfd.libkungfu.dev`? | [`../site/kfd-site.json`](../site/kfd-site.json) |
 | What is the top-level product accountability principle? | [KFD-2](../decisions/kfd-2.md) |
 | What stance should products take toward humans and agents as reasoning participants? | [KFD-3](../decisions/kfd-3.md) |
+| What schema should products use for KFD-3 participant-facing collaboration interfaces? | [`kfd-3-collaboration-interface.md`](kfd-3-collaboration-interface.md) |
 | 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/docs/kfd-3-collaboration-interface.md

@@ -0,0 +1,59 @@
+# KFD-3 Collaboration Interface
+
+KFD-3 is a cooperation standard for intelligent participants. It is not an
+agent-only standard. Products can use it for humans, agents, operators,
+extension authors, API consumers, hosted-service users, service integrators,
+maintainers, and other participants who need to understand value, choices, and
+constraints before cooperating.
+
+The KFD-owned schema surface is intentionally general:
+
+- `schemas/kfd-3/collaboration-interface.schema.json` declares a product's
+  participant-facing collaboration interface.
+- `schemas/kfd-3/witness.schema.json` declares release or build evidence that
+  the interface is discoverable, classified, constraint-transparent, and closed
+  over reachable participant-facing entrypoints.
+
+KFD owns the standard identity, schema IDs, concept names, and compatibility
+rules. Product repositories own their concrete profiles. For example, Kungfu
+may expose an agent-first profile because agents are a first-class participant
+in the current product, but that profile remains a Kungfu implementation of
+KFD-3 rather than the definition of KFD-3 itself.
+
+## Required shape
+
+A product collaboration interface should identify:
+
+- participant profiles, such as `human`, `agent`, `operator`,
+  `extension-author`, or `api-consumer`;
+- minimal entrypoints that let each participant discover the rest of the
+  interface;
+- participant-visible surfaces, such as CLI commands, JSON APIs, manuals,
+  skills, GUI routes, envelopes, packages, or protocols;
+- visible constraints, including what is restricted, why, and where review or
+  escalation happens;
+- choice paths that let participants choose or decline safe cooperation modes;
+- a closure policy for reachable participant-facing entrypoints.
+
+The KFD-3 witness schema is intentionally stricter about closure: a passing
+closed-world proof reports reachable entrypoints, classified entrypoints, and
+an empty `unclassifiedEntrypoints` list. This prevents a product from exposing
+a participant-facing or callable backdoor API outside the declared interface.
+
+## Product profile boundary
+
+Concrete product profiles may add their own contracts, registry fields, command
+metadata, generated manuals, or audit output. Those fields should reference the
+KFD-3 schema IDs from `standards.json` instead of copying KFD-owned terms.
+
+Examples:
+
+- A Kungfu agent-first bridge can map local commands, provider skills, command
+  metadata, and operating manuals into a KFD-3 collaboration interface.
+- A Buildchain release passport can carry a KFD-3 witness once a downstream
+  product can freeze and verify the concrete interface artifact.
+- A hosted surface can use the same standard to show where policy constraints,
+  permission gates, and user choices are visible before cooperation is
+  requested.
+
+This keeps KFD-3 general while making real product interfaces testable.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/kfd",
-  "version": "1.0.0-alpha.2",
+  "version": "1.0.0-alpha.4",
   "description": "Kung Fu Decisions (KFD): the kungfu-systems organization-wide decision registry, as a consumable artifact",
   "license": "Apache-2.0",
   "files": [
@@ -10,6 +10,8 @@
     "standards.json",
     "schemas",
     "site",
+    "buildchain.release-propagation.json",
+    ".buildchain/kfd-1/contract-world.witness.json",
     "docs"
   ],
   "exports": {
@@ -18,6 +20,8 @@
     "./registry.json": "./registry.json",
     "./standards.json": "./standards.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",
     "./schemas/*.json": "./schemas/*.json",
     "./schemas/*/*.json": "./schemas/*/*.json",
     "./decisions/*.md": "./decisions/*.md",