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

package/README.md

@@ -113,6 +113,15 @@ e.g. `https://kfd.libkungfu.dev/1`). This repository publishes
 `@kungfu-tech/kfd` — the decision texts plus a machine-readable
 `registry.json` — which the site consumes as its single fact source.
 
+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:
+
+```js
+import standards from "@kungfu-tech/kfd/standards.json" with { type: "json" };
+```
+
 ## Current decisions
 
 | ID | Kind | Title | Status |
@@ -137,6 +146,9 @@ reference KFDs; KFDs never depend on repository internals.
 ```text
 decisions/     one markdown file per decision (kfd-N.md)
 registry.json  machine-readable index (schemaVersion 1, contract kfd-registry)
+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
 release-impact.json
                Buildchain surface-aware impact ledger for production release passports
@@ -144,9 +156,12 @@ scripts/       conformance check: registry and documents must agree
 ```
 
 `node scripts/check.mjs` (also `pnpm run check`) verifies numbering
-uniqueness, registry/document agreement, status validity, 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.
+uniqueness, registry/document agreement, standards metadata/schema agreement,
+status validity, 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
+promotion.
 
 ## Release impact ledger
 
@@ -160,7 +175,9 @@ release-passport-impact-json: release-impact.json
 For ordinary KFD content changes, keep `kfd-content` at `patch`. Move
 `kfd-registry-schema` or `kfd-package-structure` to `minor` or `major` only
 when those machine-consumed surfaces add or break fields, meanings, package
-paths, or published structure under KFD-1.
+paths, or published structure under KFD-1. These values are Buildchain release
+passport impact classifications; they do not by themselves open a new
+`@kungfu-tech/kfd` package major or minor line.
 
 ## License
 

package/decisions/kfd-1.md

@@ -157,10 +157,12 @@ and does not drift invisibly.
 KFD documents are append-only. A KFD's number is immutable and is the
 content-layer coordinate; substantive semantic change is made by minting a new
 KFD that supersedes the old number (namespace welding applied to decisions).
-Consequently, in the `@kungfu-tech/kfd` package, content operations — new
-KFDs, status flips, editorial clarifications — are patches; only the machine
-surfaces of the package itself (the registry schema, the package structure)
-can move minor or major.
+Consequently, in the `@kungfu-tech/kfd` package, the outer package line stays
+fixed at `v1.0`. Content operations — new KFDs, status flips, editorial
+clarifications — are patches. Machine surfaces of the package itself (the
+registry schema, the package structure) can still require `minor` or `major`
+surface-impact review in the Buildchain release passport, but that review
+classification is not a silent package-line upgrade.
 
 ## Adopters
 

package/docs/MAP.md

@@ -9,6 +9,8 @@
 | 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 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) |
 | 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/package.json

@@ -1,10 +1,37 @@
 {
   "name": "@kungfu-tech/kfd",
-  "version": "1.0.0-alpha.0",
+  "version": "1.0.0-alpha.2",
   "description": "Kung Fu Decisions (KFD): the kungfu-systems organization-wide decision registry, as a consumable artifact",
   "license": "Apache-2.0",
-  "files": ["README.md", "decisions", "registry.json", "site", "docs"],
-  "scripts": {"check": "node scripts/check.mjs"},
-  "publishConfig": {"registry": "https://registry.npmjs.org/", "access": "public"},
-  "repository": {"type": "git", "url": "git+https://github.com/kungfu-systems/kfd.git"}
+  "files": [
+    "README.md",
+    "decisions",
+    "registry.json",
+    "standards.json",
+    "schemas",
+    "site",
+    "docs"
+  ],
+  "exports": {
+    "./package.json": "./package.json",
+    "./README.md": "./README.md",
+    "./registry.json": "./registry.json",
+    "./standards.json": "./standards.json",
+    "./site/kfd-site.json": "./site/kfd-site.json",
+    "./schemas/*.json": "./schemas/*.json",
+    "./schemas/*/*.json": "./schemas/*/*.json",
+    "./decisions/*.md": "./decisions/*.md",
+    "./docs/*": "./docs/*"
+  },
+  "scripts": {
+    "check": "node scripts/check.mjs"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kungfu-systems/kfd.git"
+  }
 }

package/schemas/kfd-1/contract-world.schema.json

@@ -0,0 +1,57 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kfd.libkungfu.dev/schemas/kfd-1/contract-world.schema.json",
+  "title": "KFD-1 contract world",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "contract",
+    "standard",
+    "factSource",
+    "surfaces"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": 1
+    },
+    "contract": {
+      "const": "kfd-1-contract-world"
+    },
+    "standard": {
+      "const": "kfd-1"
+    },
+    "factSource": {
+      "type": "string",
+      "minLength": 1
+    },
+    "surfaces": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "class",
+          "description"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
+          },
+          "class": {
+            "enum": [
+              "integration-time",
+              "cross-time"
+            ]
+          },
+          "description": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "additionalProperties": true
+}

package/schemas/kfd-1/witness.schema.json

@@ -0,0 +1,63 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kfd.libkungfu.dev/schemas/kfd-1/witness.schema.json",
+  "title": "KFD-1 witness",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "contract",
+    "standard",
+    "contractWorld",
+    "evidence"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": 1
+    },
+    "contract": {
+      "const": "kfd-1-witness"
+    },
+    "standard": {
+      "const": "kfd-1"
+    },
+    "contractWorld": {
+      "type": "object",
+      "required": [
+        "schemaId",
+        "digest"
+      ],
+      "properties": {
+        "schemaId": {
+          "const": "https://kfd.libkungfu.dev/schemas/kfd-1/contract-world.schema.json"
+        },
+        "digest": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "additionalProperties": false
+    },
+    "evidence": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "kind",
+          "path"
+        ],
+        "properties": {
+          "kind": {
+            "type": "string",
+            "minLength": 1
+          },
+          "path": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "additionalProperties": true
+      }
+    }
+  },
+  "additionalProperties": true
+}

package/schemas/kfd-standards.schema.json

@@ -0,0 +1,200 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kfd.libkungfu.dev/schemas/kfd-standards.schema.json",
+  "title": "KFD standards metadata",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "contract",
+    "metadataSchema",
+    "source",
+    "standards"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": 1
+    },
+    "contract": {
+      "const": "kfd-standards-metadata"
+    },
+    "metadataSchema": {
+      "type": "object",
+      "required": [
+        "id",
+        "path",
+        "version"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "format": "uri"
+        },
+        "path": {
+          "type": "string"
+        },
+        "version": {
+          "type": "string"
+        }
+      },
+      "additionalProperties": false
+    },
+    "source": {
+      "type": "object",
+      "required": [
+        "package",
+        "registry",
+        "decisionsDir"
+      ],
+      "properties": {
+        "package": {
+          "const": "@kungfu-tech/kfd"
+        },
+        "registry": {
+          "const": "registry.json"
+        },
+        "decisionsDir": {
+          "const": "decisions"
+        }
+      },
+      "additionalProperties": false
+    },
+    "standards": {
+      "type": "object",
+      "patternProperties": {
+        "^kfd-[1-9][0-9]*$": {
+          "$ref": "#/$defs/standard"
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "standard": {
+      "type": "object",
+      "required": [
+        "key",
+        "id",
+        "number",
+        "label",
+        "title",
+        "kind",
+        "status",
+        "revision",
+        "metadataSchemaVersion",
+        "document",
+        "compatibility",
+        "schemaIds",
+        "schemaPaths",
+        "concepts"
+      ],
+      "properties": {
+        "key": {
+          "type": "string",
+          "pattern": "^kfd-[1-9][0-9]*$"
+        },
+        "id": {
+          "type": "string",
+          "pattern": "^KFD-[1-9][0-9]*$"
+        },
+        "number": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "label": {
+          "type": "string",
+          "pattern": "^KFD-[1-9][0-9]*$"
+        },
+        "title": {
+          "type": "string",
+          "minLength": 1
+        },
+        "kind": {
+          "enum": [
+            "principle",
+            "procedure"
+          ]
+        },
+        "status": {
+          "enum": [
+            "draft",
+            "active",
+            "superseded"
+          ]
+        },
+        "revision": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "metadataSchemaVersion": {
+          "type": "string"
+        },
+        "document": {
+          "type": "object",
+          "required": [
+            "path",
+            "url"
+          ],
+          "properties": {
+            "path": {
+              "type": "string"
+            },
+            "url": {
+              "type": "string",
+              "format": "uri"
+            }
+          },
+          "additionalProperties": false
+        },
+        "compatibility": {
+          "type": "object",
+          "required": [
+            "packageLine",
+            "registrySchemaVersion",
+            "metadataSchemaVersion",
+            "rule"
+          ],
+          "properties": {
+            "packageLine": {
+              "type": "string"
+            },
+            "registrySchemaVersion": {
+              "type": "integer",
+              "minimum": 1
+            },
+            "metadataSchemaVersion": {
+              "type": "string"
+            },
+            "rule": {
+              "type": "string"
+            }
+          },
+          "additionalProperties": false
+        },
+        "schemaIds": {
+          "type": "object",
+          "minProperties": 1,
+          "additionalProperties": {
+            "type": "string",
+            "format": "uri"
+          }
+        },
+        "schemaPaths": {
+          "type": "object",
+          "minProperties": 1,
+          "additionalProperties": {
+            "type": "string"
+          }
+        },
+        "concepts": {
+          "type": "object",
+          "minProperties": 1,
+          "additionalProperties": {
+            "type": "string"
+          }
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/standards.json

@@ -0,0 +1,118 @@
+{
+  "schemaVersion": 1,
+  "contract": "kfd-standards-metadata",
+  "metadataSchema": {
+    "id": "https://kfd.libkungfu.dev/schemas/kfd-standards.schema.json",
+    "path": "schemas/kfd-standards.schema.json",
+    "version": "1"
+  },
+  "source": {
+    "package": "@kungfu-tech/kfd",
+    "registry": "registry.json",
+    "decisionsDir": "decisions"
+  },
+  "standards": {
+    "kfd-1": {
+      "key": "kfd-1",
+      "id": "KFD-1",
+      "number": 1,
+      "label": "KFD-1",
+      "title": "Contracts must not drift: contract worlds need one fact source",
+      "kind": "procedure",
+      "status": "active",
+      "revision": 1,
+      "metadataSchemaVersion": "1",
+      "document": {
+        "path": "decisions/kfd-1.md",
+        "url": "https://kfd.libkungfu.dev/1"
+      },
+      "compatibility": {
+        "packageLine": "v1.0",
+        "registrySchemaVersion": 1,
+        "metadataSchemaVersion": "1",
+        "rule": "Substantive semantic changes mint a new KFD; compatible metadata additions keep schemaVersion 1."
+      },
+      "schemaIds": {
+        "metadata": "https://kfd.libkungfu.dev/schemas/kfd-standards.schema.json",
+        "contractWorld": "https://kfd.libkungfu.dev/schemas/kfd-1/contract-world.schema.json",
+        "witness": "https://kfd.libkungfu.dev/schemas/kfd-1/witness.schema.json"
+      },
+      "schemaPaths": {
+        "metadata": "schemas/kfd-standards.schema.json",
+        "contractWorld": "schemas/kfd-1/contract-world.schema.json",
+        "witness": "schemas/kfd-1/witness.schema.json"
+      },
+      "concepts": {
+        "factSource": "fact source",
+        "contractWorld": "contract world",
+        "weldedSurfaceRegister": "welded-surface register",
+        "witness": "contract witness"
+      }
+    },
+    "kfd-2": {
+      "key": "kfd-2",
+      "id": "KFD-2",
+      "number": 2,
+      "label": "KFD-2",
+      "title": "Trust must start from facts: responsibility must be inspectable",
+      "kind": "principle",
+      "status": "active",
+      "revision": 1,
+      "metadataSchemaVersion": "1",
+      "document": {
+        "path": "decisions/kfd-2.md",
+        "url": "https://kfd.libkungfu.dev/2"
+      },
+      "compatibility": {
+        "packageLine": "v1.0",
+        "registrySchemaVersion": 1,
+        "metadataSchemaVersion": "1",
+        "rule": "Substantive semantic changes mint a new KFD; compatible metadata additions keep schemaVersion 1."
+      },
+      "schemaIds": {
+        "metadata": "https://kfd.libkungfu.dev/schemas/kfd-standards.schema.json"
+      },
+      "schemaPaths": {
+        "metadata": "schemas/kfd-standards.schema.json"
+      },
+      "concepts": {
+        "facts": "inspectable facts",
+        "responsibilityState": "responsibility state",
+        "trust": "trust from facts"
+      }
+    },
+    "kfd-3": {
+      "key": "kfd-3",
+      "id": "KFD-3",
+      "number": 3,
+      "label": "KFD-3",
+      "title": "Cooperation must start from transparent value: compliance must not be coerced",
+      "kind": "principle",
+      "status": "active",
+      "revision": 1,
+      "metadataSchemaVersion": "1",
+      "document": {
+        "path": "decisions/kfd-3.md",
+        "url": "https://kfd.libkungfu.dev/3"
+      },
+      "compatibility": {
+        "packageLine": "v1.0",
+        "registrySchemaVersion": 1,
+        "metadataSchemaVersion": "1",
+        "rule": "Substantive semantic changes mint a new KFD; compatible metadata additions keep schemaVersion 1."
+      },
+      "schemaIds": {
+        "metadata": "https://kfd.libkungfu.dev/schemas/kfd-standards.schema.json"
+      },
+      "schemaPaths": {
+        "metadata": "schemas/kfd-standards.schema.json"
+      },
+      "concepts": {
+        "transparentValue": "transparent value",
+        "stableChoice": "stable choice",
+        "explainableConstraints": "explainable constraints",
+        "nonCoercion": "non-coercive cooperation"
+      }
+    }
+  }
+}