@kungfu-tech/kfd 1.0.0-alpha.21 → 1.0.0-alpha.22

package/schemas/kfd-1/publication-url-semantics.schema.json

@@ -0,0 +1,255 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://kfd.libkungfu.dev/schemas/kfd-1/publication-url-semantics.schema.json",
+  "title": "KFD-1 publication URL semantics",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "contract",
+    "standard",
+    "publication",
+    "routes",
+    "immutableArtifacts",
+    "archivePolicy"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": 1
+    },
+    "contract": {
+      "const": "kfd-1-publication-url-semantics"
+    },
+    "standard": {
+      "const": "kfd-1"
+    },
+    "publication": {
+      "$ref": "#/$defs/publication"
+    },
+    "routes": {
+      "$ref": "#/$defs/routes"
+    },
+    "immutableArtifacts": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/immutableArtifact"
+      },
+      "minItems": 1
+    },
+    "archivePolicy": {
+      "$ref": "#/$defs/archivePolicy"
+    },
+    "lineage": {
+      "$ref": "#/$defs/lineage"
+    },
+    "siteConsumption": {
+      "$ref": "#/$defs/siteConsumption"
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "uri": {
+      "type": "string",
+      "format": "uri"
+    },
+    "digest": {
+      "type": "string",
+      "pattern": "^[0-9a-f]{64}$"
+    },
+    "publication": {
+      "type": "object",
+      "required": [
+        "id",
+        "version",
+        "sourceCoordinate"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
+        },
+        "title": {
+          "type": "string",
+          "minLength": 1
+        },
+        "version": {
+          "type": "string",
+          "minLength": 1
+        },
+        "sourceCoordinate": {
+          "$ref": "#/$defs/sourceCoordinate"
+        }
+      },
+      "additionalProperties": false
+    },
+    "sourceCoordinate": {
+      "type": "object",
+      "required": [
+        "kind",
+        "repository",
+        "ref"
+      ],
+      "properties": {
+        "kind": {
+          "enum": [
+            "git-commit",
+            "git-tag",
+            "source-bundle",
+            "release-passport",
+            "other"
+          ]
+        },
+        "repository": {
+          "type": "string",
+          "minLength": 1
+        },
+        "ref": {
+          "type": "string",
+          "minLength": 1
+        },
+        "digest": {
+          "$ref": "#/$defs/digest"
+        },
+        "url": {
+          "$ref": "#/$defs/uri"
+        }
+      },
+      "additionalProperties": false
+    },
+    "routes": {
+      "type": "object",
+      "required": [
+        "canonicalUrl",
+        "immutableVersionBaseUrl"
+      ],
+      "properties": {
+        "canonicalUrl": {
+          "$ref": "#/$defs/uri",
+          "description": "Stable reader entrypoint. It may show the latest recommended version."
+        },
+        "latestUrl": {
+          "$ref": "#/$defs/uri",
+          "description": "Mutable latest alias or evidence entrypoint. It may move as new versions are published."
+        },
+        "evidenceUrl": {
+          "$ref": "#/$defs/uri",
+          "description": "Reader or agent entrypoint for release evidence."
+        },
+        "immutableVersionBaseUrl": {
+          "$ref": "#/$defs/uri",
+          "description": "Version-addressed base URL whose artifact contents must not change after publication."
+        }
+      },
+      "additionalProperties": false
+    },
+    "immutableArtifact": {
+      "type": "object",
+      "required": [
+        "id",
+        "kind",
+        "url",
+        "sha256"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
+        },
+        "kind": {
+          "enum": [
+            "pdf",
+            "source-bundle",
+            "release-passport",
+            "site-bundle",
+            "publication-registry",
+            "other"
+          ]
+        },
+        "url": {
+          "$ref": "#/$defs/uri"
+        },
+        "path": {
+          "type": "string",
+          "minLength": 1
+        },
+        "mediaType": {
+          "type": "string",
+          "minLength": 1
+        },
+        "sha256": {
+          "$ref": "#/$defs/digest"
+        },
+        "sourceCoordinate": {
+          "$ref": "#/$defs/sourceCoordinate"
+        }
+      },
+      "additionalProperties": false
+    },
+    "archivePolicy": {
+      "type": "object",
+      "required": [
+        "immutability",
+        "sameVersionDigestPolicy",
+        "destructiveSyncPolicy",
+        "historyRetention"
+      ],
+      "properties": {
+        "immutability": {
+          "const": "published-version-artifacts-are-append-only"
+        },
+        "sameVersionDigestPolicy": {
+          "const": "fail-on-digest-change"
+        },
+        "destructiveSyncPolicy": {
+          "const": "must-not-delete-immutable-prefix"
+        },
+        "historyRetention": {
+          "const": "site-builds-must-preserve-declared-historical-versions"
+        }
+      },
+      "additionalProperties": false
+    },
+    "lineage": {
+      "type": "object",
+      "properties": {
+        "supersedes": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "uniqueItems": true
+        },
+        "supersededBy": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "uniqueItems": true
+        },
+        "revisionNote": {
+          "type": "string"
+        }
+      },
+      "additionalProperties": false
+    },
+    "siteConsumption": {
+      "type": "object",
+      "required": [
+        "latestPackageRole",
+        "archiveRole",
+        "rendererRole"
+      ],
+      "properties": {
+        "latestPackageRole": {
+          "const": "may-update-canonical-and-latest-pages"
+        },
+        "archiveRole": {
+          "const": "owns-immutable-version-artifacts"
+        },
+        "rendererRole": {
+          "const": "render-and-link-without-forking-route-facts"
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/scripts/check.mjs

@@ -273,16 +273,23 @@ if (kfd1?.schemaIds?.contractWorld !== "https://kfd.libkungfu.dev/schemas/kfd-1/
 if (kfd1?.schemaIds?.witness !== "https://kfd.libkungfu.dev/schemas/kfd-1/witness.schema.json") {
   fail("KFD-1 standards metadata must expose the canonical witness schema URI");
 }
-for (const concept of ["factSource", "contractWorld", "weldedSurfaceRegister", "witness", "surfaceClass", "compatibilityImpact", "impactProjection"]) {
+if (kfd1?.schemaIds?.publicationUrlSemantics !== "https://kfd.libkungfu.dev/schemas/kfd-1/publication-url-semantics.schema.json") {
+  fail("KFD-1 standards metadata must expose the canonical publicationUrlSemantics schema URI");
+}
+if (kfd1?.schemaPaths?.publicationUrlSemantics !== "schemas/kfd-1/publication-url-semantics.schema.json") {
+  fail("KFD-1 standards metadata must expose the publicationUrlSemantics schema path");
+}
+for (const concept of ["factSource", "contractWorld", "weldedSurfaceRegister", "witness", "surfaceClass", "compatibilityImpact", "impactProjection", "publicationUrlSemantics", "canonicalUrl", "latestUrl", "immutableVersionUrl", "immutableArtifact", "archivePolicy", "sourceCoordinate"]) {
   if (!kfd1?.concepts?.[concept]) fail(`KFD-1 standards metadata missing concept ${concept}`);
 }
-for (const iface of ["contractWorld", "witness"]) {
+for (const iface of ["contractWorld", "witness", "publicationUrlSemantics"]) {
   if (!kfd1?.interfaces?.[iface]) fail(`KFD-1 standards metadata missing interface ${iface}`);
 }
 const expectedKfd1SurfaceClasses = ["integration-time", "cross-time"];
 const expectedKfd1ImpactClasses = ["breaking", "additive", "none", "unclassifiable"];
 const kfd1ContractWorldSchema = JSON.parse(readFileSync("schemas/kfd-1/contract-world.schema.json", "utf8"));
 const kfd1WitnessSchema = JSON.parse(readFileSync("schemas/kfd-1/witness.schema.json", "utf8"));
+const kfd1PublicationUrlSemanticsSchema = JSON.parse(readFileSync("schemas/kfd-1/publication-url-semantics.schema.json", "utf8"));
 for (const [schemaName, schemaDoc] of [["contractWorld", kfd1ContractWorldSchema], ["witness", kfd1WitnessSchema]]) {
   requireSameEnum(schemaDoc.$defs?.surfaceClass?.enum, expectedKfd1SurfaceClasses, `KFD-1 ${schemaName} surfaceClass`);
   requireSameEnum(schemaDoc.$defs?.compatibilityImpact?.enum, expectedKfd1ImpactClasses, `KFD-1 ${schemaName} compatibilityImpact`);
@@ -292,6 +299,27 @@ for (const [schemaName, schemaDoc] of [["contractWorld", kfd1ContractWorldSchema
     }
   }
 }
+if (kfd1PublicationUrlSemanticsSchema.properties?.contract?.const !== "kfd-1-publication-url-semantics") {
+  fail("KFD-1 publicationUrlSemantics schema must describe the kfd-1-publication-url-semantics contract");
+}
+if (kfd1PublicationUrlSemanticsSchema.properties?.standard?.const !== "kfd-1") {
+  fail("KFD-1 publicationUrlSemantics schema must declare standard kfd-1");
+}
+for (const requiredField of ["canonicalUrl", "immutableVersionBaseUrl"]) {
+  if (!kfd1PublicationUrlSemanticsSchema.$defs?.routes?.required?.includes(requiredField)) {
+    fail(`KFD-1 publicationUrlSemantics routes must require ${requiredField}`);
+  }
+}
+for (const [field, expectedConst] of [
+  ["immutability", "published-version-artifacts-are-append-only"],
+  ["sameVersionDigestPolicy", "fail-on-digest-change"],
+  ["destructiveSyncPolicy", "must-not-delete-immutable-prefix"],
+  ["historyRetention", "site-builds-must-preserve-declared-historical-versions"],
+]) {
+  if (kfd1PublicationUrlSemanticsSchema.$defs?.archivePolicy?.properties?.[field]?.const !== expectedConst) {
+    fail(`KFD-1 publicationUrlSemantics archivePolicy.${field} must be ${expectedConst}`);
+  }
+}
 const kfd1SurfaceRegister = kfd1?.surfaceRegister;
 if (kfd1SurfaceRegister?.factSource !== "standards.json#/standards/kfd-1/surfaceRegister") {
   fail("KFD-1 surfaceRegister must declare standards.json as its fact source");
@@ -552,6 +580,7 @@ if (!kfd1Witness) {
     const witnessedSurfaceNames = new Set(kfd1Witness.surfaces.map((surface) => surface.name));
     for (const requiredSurface of [
       "readme",
+      "kfd-1-publication-url-semantics-schema",
       "kfd-2-trust-taxonomy-schema",
       "kfd-2-trust-claims-schema",
       "kfd-2-trust-assessment-schema",

package/site/kfd-site.json

@@ -158,7 +158,7 @@
         "homepagePriority": 40,
         "defaultPresentation": "ordered-steps",
         "includeInFirstScreen": false,
-        "markdown": "Agents consuming this package should start from the same sources as humans:\n\n1. Read this README for the foundation model and package map.\n2. Read `standards.json` for canonical KFD numbers, schema IDs, concept names,\n   and interface contracts.\n3. Use `site/kfd-site.json` decision metadata or the KFD-3 collaboration\n   interface fact-source metadata to identify the public KFD fact source.\n4. Use `schemas/kfd-2/trust-taxonomy.schema.json` for KFD-2 residual-risk and\n   trust-downgrade values. Unknown taxonomy values are invalid.\n5. Use `schemas/kfd-2/trust-claims.schema.json` and\n   `schemas/kfd-2/trust-assessment.schema.json` when a claim needs generic\n   KFD-2 assessment instead of a release-specific passport.\n6. Use `schemas/kfd-3/collaboration-interface.schema.json` and\n   `schemas/kfd-3/witness.schema.json` to inspect collaboration interfaces.\n7. If a needed KFD-2 taxonomy value is missing, open a KFD GitHub issue rather\n   than inventing a local value:\n   `https://github.com/kungfu-systems/kfd/issues/new?title=KFD-2%20trust%20taxonomy%20extension%20request`.\n\nKFD package semver is only the distribution version. KFD-owned machine\ninterfaces carry their own `schemaVersion` and `contract` fields. Compatible\nadditions may keep the same interface version; semantic changes, required-field\nchanges, verification meaning changes, or responsibility-boundary changes must\nuse a new interface version or contract.\n\nKFD-2 publishes trust-taxonomy, trust-claims, trust-assessment,\nrelease-claims, and release-trust-passport schemas under `schemas/kfd-2/`.\nThe generic schemas let humans, agents, Buildchain, and other systems assess\nwhether claims about KFD-1, KFD-3, KFD-4, future KFDs, or product surfaces are\nbound to source facts, evidence, hashes, audit boundaries, residual risk, and\nresponsibility state. The release schemas are a release-specific projection of\nthat model. See [`docs/KFD-2-usage.md`](docs/KFD-2-usage.md).\n\nKFD-3 also publishes a general collaboration-interface schema and witness\nschema under `schemas/kfd-3/`. These schemas are for participant-facing product\ninterfaces, not only agent APIs. A product such as Kungfu may implement an\nagent-first profile, but that profile remains a product-specific realization of\nKFD-3. The KFD-owned boundary is the standard vocabulary, schema IDs, and\nclosed-world evidence shape. See\n[`docs/KFD-3-usage.md`](docs/KFD-3-usage.md).\n\nKFD-4 publishes an observer-perspective schema under `schemas/kfd-4/`. It gives\nhumans and agents a standard vocabulary for observer, accepted facts,\nprojection policy, causal constraints, degraded evidence, and verification\nstate when a product shows a perspective-bearing timeline. The package-level\nclaim proves the KFD-owned interface surface; adopter runtime correctness\nrequires adopter-owned KFD-2 evidence."
+        "markdown": "Agents consuming this package should start from the same sources as humans:\n\n1. Read this README for the foundation model and package map.\n2. Read `standards.json` for canonical KFD numbers, schema IDs, concept names,\n   and interface contracts.\n3. Use `site/kfd-site.json` decision metadata or the KFD-3 collaboration\n   interface fact-source metadata to identify the public KFD fact source.\n4. Use `schemas/kfd-2/trust-taxonomy.schema.json` for KFD-2 residual-risk and\n   trust-downgrade values. Unknown taxonomy values are invalid.\n5. Use `schemas/kfd-2/trust-claims.schema.json` and\n   `schemas/kfd-2/trust-assessment.schema.json` when a claim needs generic\n   KFD-2 assessment instead of a release-specific passport.\n6. Use `schemas/kfd-3/collaboration-interface.schema.json` and\n   `schemas/kfd-3/witness.schema.json` to inspect collaboration interfaces.\n7. Use `schemas/kfd-1/publication-url-semantics.schema.json` when a package,\n   paper, specification, or site bundle must distinguish stable reader URLs,\n   latest aliases, and immutable versioned artifacts.\n8. If a needed KFD-2 taxonomy value is missing, open a KFD GitHub issue rather\n   than inventing a local value:\n   `https://github.com/kungfu-systems/kfd/issues/new?title=KFD-2%20trust%20taxonomy%20extension%20request`.\n\nKFD package semver is only the distribution version. KFD-owned machine\ninterfaces carry their own `schemaVersion` and `contract` fields. Compatible\nadditions may keep the same interface version; semantic changes, required-field\nchanges, verification meaning changes, or responsibility-boundary changes must\nuse a new interface version or contract.\n\nKFD-2 publishes trust-taxonomy, trust-claims, trust-assessment,\nrelease-claims, and release-trust-passport schemas under `schemas/kfd-2/`.\nThe generic schemas let humans, agents, Buildchain, and other systems assess\nwhether claims about KFD-1, KFD-3, KFD-4, future KFDs, or product surfaces are\nbound to source facts, evidence, hashes, audit boundaries, residual risk, and\nresponsibility state. The release schemas are a release-specific projection of\nthat model. See [`docs/KFD-2-usage.md`](docs/KFD-2-usage.md).\n\nKFD-3 also publishes a general collaboration-interface schema and witness\nschema under `schemas/kfd-3/`. These schemas are for participant-facing product\ninterfaces, not only agent APIs. A product such as Kungfu may implement an\nagent-first profile, but that profile remains a product-specific realization of\nKFD-3. The KFD-owned boundary is the standard vocabulary, schema IDs, and\nclosed-world evidence shape. See\n[`docs/KFD-3-usage.md`](docs/KFD-3-usage.md).\n\nKFD-4 publishes an observer-perspective schema under `schemas/kfd-4/`. It gives\nhumans and agents a standard vocabulary for observer, accepted facts,\nprojection policy, causal constraints, degraded evidence, and verification\nstate when a product shows a perspective-bearing timeline. The package-level\nclaim proves the KFD-owned interface surface; adopter runtime correctness\nrequires adopter-owned KFD-2 evidence."
       },
       {
         "id": "decision-metadata",

package/standards.json

@@ -25,7 +25,7 @@
       "document": {
         "path": "decisions/KFD-1.md",
         "url": "https://kfd.libkungfu.dev/1",
-        "sha256": "0b7b1ec54d661b271f91f02cefa97b11e1d1ef9c637efd2d1878d5f9c9185d80"
+        "sha256": "dcc97d2e24ffc8f0380cd027ba973bf8268cff59fa9ab766b178e894bcf1f164"
       },
       "compatibility": {
         "packageLine": "v1.0",
@@ -36,12 +36,14 @@
       "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"
+        "witness": "https://kfd.libkungfu.dev/schemas/kfd-1/witness.schema.json",
+        "publicationUrlSemantics": "https://kfd.libkungfu.dev/schemas/kfd-1/publication-url-semantics.schema.json"
       },
       "schemaPaths": {
         "metadata": "schemas/kfd-standards.schema.json",
         "contractWorld": "schemas/kfd-1/contract-world.schema.json",
-        "witness": "schemas/kfd-1/witness.schema.json"
+        "witness": "schemas/kfd-1/witness.schema.json",
+        "publicationUrlSemantics": "schemas/kfd-1/publication-url-semantics.schema.json"
       },
       "interfaces": {
         "contractWorld": {
@@ -57,6 +59,13 @@
           "schemaId": "https://kfd.libkungfu.dev/schemas/kfd-1/witness.schema.json",
           "schemaPath": "schemas/kfd-1/witness.schema.json",
           "compatibilityRule": "Compatible additions may keep schemaVersion 1; semantic or required-field changes require a new interface version or contract."
+        },
+        "publicationUrlSemantics": {
+          "contract": "kfd-1-publication-url-semantics",
+          "schemaVersion": 1,
+          "schemaId": "https://kfd.libkungfu.dev/schemas/kfd-1/publication-url-semantics.schema.json",
+          "schemaPath": "schemas/kfd-1/publication-url-semantics.schema.json",
+          "compatibilityRule": "Compatible additions may keep schemaVersion 1; semantic or required-field changes require a new interface version or contract."
         }
       },
       "concepts": {
@@ -66,7 +75,14 @@
         "witness": "contract witness",
         "surfaceClass": "surface class",
         "compatibilityImpact": "compatibility impact",
-        "impactProjection": "domain-specific impact projection"
+        "impactProjection": "domain-specific impact projection",
+        "publicationUrlSemantics": "publication URL semantics",
+        "canonicalUrl": "canonical reader URL",
+        "latestUrl": "latest alias URL",
+        "immutableVersionUrl": "immutable version URL",
+        "immutableArtifact": "immutable publication artifact",
+        "archivePolicy": "publication archive policy",
+        "sourceCoordinate": "publication source coordinate"
       },
       "surfaceRegister": {
         "factSource": "standards.json#/standards/kfd-1/surfaceRegister",
@@ -658,6 +674,23 @@
               "none": "Changes that do not touch this registered surface do not create KFD-1 compatibility impact for this surface.",
               "unclassifiable": "If impact cannot be classified, the surface register is deficient and must be fixed before the dependent gate may pass."
             }
+          },
+          {
+            "id": "kfd-1-publication-url-semantics-schema",
+            "class": "integration-time",
+            "classes": [
+              "integration-time",
+              "cross-time"
+            ],
+            "description": "Published JSON schema surface at schemas/kfd-1/publication-url-semantics.schema.json.",
+            "sourcePath": "schemas/kfd-1/publication-url-semantics.schema.json",
+            "weldRationale": "Buildchain and site repositories can bind to this surface when declaring canonical/latest/immutable publication URL semantics, and published version artifacts remain audit-relevant after release.",
+            "impactProjection": {
+              "breaking": "Incompatible changes to this registered surface require an explicit compatibility action before the dependent gate may pass.",
+              "additive": "Backward-compatible additions to this registered surface must be declared and may proceed through the domain projection as additive impact.",
+              "none": "Changes that do not touch this registered surface do not create KFD-1 compatibility impact for this surface.",
+              "unclassifiable": "If impact cannot be classified, the surface register is deficient and must be fixed before the dependent gate may pass."
+            }
           }
         ]
       }