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

package/docs/KFD-1-usage.md

@@ -12,6 +12,9 @@ The KFD package implements KFD-1 through a declared contract world:
   surface register.
 - `schemas/kfd-1/contract-world.schema.json` defines the contract-world schema.
 - `schemas/kfd-1/witness.schema.json` defines the witness schema.
+- `schemas/kfd-1/publication-url-semantics.schema.json` defines the
+  canonical/latest/immutable publication URL contract for papers,
+  specifications, release notes, and other long-lived publication artifacts.
 - `.buildchain/kfd-1/contract-world.witness.json` projects registered surfaces,
   source hashes, artifact hashes, surface classes, and impact projections.
 - `scripts/check.mjs` verifies the register, schema enums, witness hashes, and
@@ -30,6 +33,45 @@ Release versioning is only one projection of those classes. Other domains can
 project the same core into config migration, ABI epochs, API namespaces,
 runtime compatibility bridges, or workflow gates.
 
+## Publication URL Semantics
+
+Publication artifacts frequently need both mutable and immutable routes. A
+canonical reader page may remain stable while its content is updated to point
+at the latest recommended version. A versioned PDF, source bundle, release
+passport, publication registry entry, or site bundle is different: once
+published, the versioned URL and digest are facts that downstream readers,
+agents, release passports, citations, and audits may weld to.
+
+The KFD-1 publication URL schema gives Buildchain and site repositories a
+shared vocabulary:
+
+- `canonicalUrl`: stable reader entrypoint; it may display the latest
+  recommended version.
+- `latestUrl`: mutable latest alias or evidence entrypoint; it may move when a
+  new version is published.
+- `immutableVersionBaseUrl`: version-addressed archive prefix; its published
+  artifacts must not change content.
+- `immutableArtifacts[]`: digest-bound artifacts such as PDF, source bundle,
+  release passport, site bundle, or publication registry entry.
+- `sourceCoordinate`: repository commit, tag, source bundle, release passport,
+  or equivalent coordinate for the source fact.
+- `archivePolicy`: the rule that same-version digest drift fails, destructive
+  sync must not cover immutable prefixes, and site builds must preserve
+  declared historical versions.
+
+KFD does not choose bucket names, CDN providers, product slugs, or exact route
+layout. Concrete packages declare those facts in their own site bundle or
+Buildchain release metadata. KFD owns the route semantics so those facts can be
+validated consistently.
+
+This connects the foundation triad:
+
+- KFD-1: the immutable artifact URL and digest must not drift.
+- KFD-2: trust in the publication starts from version, digest, source
+  coordinate, release passport, and archive location.
+- KFD-3: site renderers and agents should see the route facts instead of
+  reverse-engineering or forking them locally.
+
 ## Dogfood Role
 
 This package uses KFD-1 on itself. New public package surfaces should be added

package/docs/KFD-4-usage.md

@@ -23,9 +23,23 @@ Use KFD-4 when a product surface represents time, history, replay, sync,
 ordering, or mixed-source work state. A product that does not present a
 perspective-bearing timeline does not need a KFD-4 gate.
 
+The gate is about the view's declared perspective. A product may pass the KFD-4
+interface boundary by exposing view-subject, observer, accepted-fact,
+projection-policy, causal-constraint, degraded-evidence, and verification
+metadata. That package or product still needs separate evidence for any
+stronger claim, such as
+"this adapter captured every remote event" or "this product timeline is
+complete and correct."
+
 ## Trust Relation
 
 KFD-4 claims can be assessed by KFD-2. The KFD package does this through
 `.buildchain/kfd-2/kfd-foundation.trust-claims.json` and
 `.buildchain/kfd-2/kfd-foundation.trust-assessment.json`, where KFD-4 is
 assessed as an `observer-perspective` subject.
+
+The KFD package's own KFD-2 assessment proves the package-level interface
+surface: decision text, standards metadata, schema, and self-check wiring. It
+does not transfer trust to an adopter's runtime timeline. Adopters should make
+their own KFD-2 claim or release passport when they want users or agents to
+trust a concrete timeline implementation.

package/docs/MAP.md

@@ -9,6 +9,7 @@
 | How should a product show timeline order from a declared perspective? | [KFD-4](../decisions/KFD-4.md) |
 | What schema should products use for KFD-4 observer-relative timeline views? | [`../schemas/kfd-4/observer-perspective.schema.json`](../schemas/kfd-4/observer-perspective.schema.json) |
 | What are the package implementation notes for KFD-1? | [`KFD-1-usage.md`](KFD-1-usage.md) |
+| What schema should papers, specifications, or sites use for canonical/latest/immutable publication URL semantics? | [`../schemas/kfd-1/publication-url-semantics.schema.json`](../schemas/kfd-1/publication-url-semantics.schema.json) and [`KFD-1-usage.md`](KFD-1-usage.md#publication-url-semantics) |
 | What are the package implementation notes for KFD-2? | [`KFD-2-usage.md`](KFD-2-usage.md) |
 | What are the package implementation notes for KFD-3? | [`KFD-3-usage.md`](KFD-3-usage.md) |
 | What are the package implementation notes for KFD-4? | [`KFD-4-usage.md`](KFD-4-usage.md) |

package/kfd.release.json

@@ -4,7 +4,7 @@
   "line": "v1.0",
   "channel": "alpha",
   "npmPackage": "@kungfu-tech/kfd",
-  "npmVersion": "1.0.0-alpha.20",
+  "npmVersion": "1.0.0-alpha.22",
   "source": {
     "repository": "kungfu-systems/kfd",
     "branch": "alpha/v1/v1.0"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/kfd",
-  "version": "1.0.0-alpha.20",
+  "version": "1.0.0-alpha.22",
   "description": "Kung Fu Decisions (KFD): the kungfu-systems organization-wide decision registry, as a consumable artifact",
   "license": "Apache-2.0",
   "files": [

package/release-impact.json

@@ -8,8 +8,8 @@
   },
   "versionImpact": {
     "final": "minor",
-    "source": "kfd-site-decision-usage-pages",
-    "rationale": "This change additively exposes decision usage subpage mapping in the KFD site bundle, while preserving existing registry, package, and schemaVersion 1 compatibility."
+    "source": "kfd-1-publication-url-semantics",
+    "rationale": "This change additively exposes KFD-1 publication URL semantics for canonical/latest/immutable publication routes, while preserving existing registry, package, and schemaVersion 1 compatibility."
   },
   "surfaceImpacts": [
     {
@@ -107,7 +107,13 @@
       "impact": "minor",
       "class": "additive",
       "rationale": "standards.json now publishes the KFD package surface register as the KFD-1 fact source, and the KFD-1 witness projects each registered surface class and impact projection from that fact source."
+    },
+    {
+      "id": "kfd-1-publication-url-semantics",
+      "impact": "minor",
+      "class": "additive",
+      "rationale": "KFD-1 now publishes a machine-readable schema for canonical reader URLs, latest aliases, immutable version artifact URLs, artifact digests, source coordinates, lineage, site consumption, and archive policies that prevent same-version digest drift or destructive deletion of immutable publication prefixes."
     }
   ],
-  "summary": "KFD v1.0 production promotion is minor-impact because it additively exposes decision usage subpage mapping in the site bundle, preserves existing package and schemaVersion 1 compatibility, and separates authoritative decision paths from numbered usage documentation."
+  "summary": "KFD v1.0 production promotion is minor-impact because it additively exposes publication URL semantics and related machine metadata while preserving existing package and schemaVersion 1 compatibility."
 }

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/schemas/kfd-4/observer-perspective.schema.json

@@ -27,6 +27,9 @@
       "type": "string",
       "minLength": 1
     },
+    "viewSubject": {
+      "$ref": "#/$defs/viewSubject"
+    },
     "observer": {
       "$ref": "#/$defs/observer"
     },
@@ -60,6 +63,31 @@
   },
   "additionalProperties": false,
   "$defs": {
+    "viewSubject": {
+      "type": "object",
+      "required": [
+        "kind",
+        "description"
+      ],
+      "properties": {
+        "kind": {
+          "enum": [
+            "timeline",
+            "history",
+            "replay",
+            "sync",
+            "ordering",
+            "mixed-source-work-state",
+            "other"
+          ]
+        },
+        "description": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "additionalProperties": false
+    },
     "observer": {
       "type": "object",
       "required": [

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");
@@ -494,7 +522,7 @@ const kfd4ObserverPerspectiveSchema = JSON.parse(readFileSync("schemas/kfd-4/obs
 if (kfd4ObserverPerspectiveSchema.properties?.contract?.const !== "kfd-4-observer-perspective") {
   fail("KFD-4 observerPerspective schema must describe the kfd-4-observer-perspective contract");
 }
-for (const concept of ["observer", "declaredPerspective", "observerPerspective", "acceptedFacts", "projectionPolicy", "causalDominance", "degradedEvidence", "timeline"]) {
+for (const concept of ["observer", "declaredPerspective", "observerPerspective", "viewSubject", "acceptedFacts", "projectionPolicy", "causalDominance", "degradedEvidence", "timeline"]) {
   if (!kfd4?.concepts?.[concept]) fail(`KFD-4 standards metadata missing concept ${concept}`);
 }
 if (!kfd4?.interfaces?.observerPerspective) fail("KFD-4 standards metadata missing interface observerPerspective");
@@ -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/scripts/update-kfd-2-claim.mjs

@@ -200,7 +200,7 @@ const trustClaims = {
     {
       id: "kfd-4-observer-perspective-trust",
       statement:
-        "KFD-4 is trustable as an observer-perspective interface because KFD publishes the schema, standards metadata, decision text, and verification gate for observer-relative timeline views.",
+        "KFD-4 is trustable as a package-level observer-perspective interface because KFD publishes the schema, standards metadata, decision text, and verification gate for observer-relative timeline views; adopter-specific timeline correctness remains a separate KFD-2 claim.",
       subject: {
         kind: "observer-perspective",
         id: "kfd-4-observer-perspective",
@@ -215,14 +215,14 @@ const trustClaims = {
       evidence: [
         evidence("schema", "schemas/kfd-4/observer-perspective.schema.json", "KFD-4 observer-perspective schema is published."),
         evidence("file", "standards.json", "Standards metadata exposes the KFD-4 schema ID, path, interface version, and concept names."),
-        evidence("file", "scripts/check.mjs", "The package check gate validates the KFD-4 schema and standards metadata."),
+        evidence("file", "scripts/check.mjs", "The package check gate validates the KFD-4 schema and standards metadata; it does not assess adopter-specific timeline correctness."),
       ],
       verification: {
         command: "node scripts/check.mjs",
         expectedResult: "pass",
       },
       auditBoundary: {
-        scope: "KFD-4 decision text, observer-perspective schema, standards metadata, and self-verification gate",
+        scope: "KFD-4 package decision text, observer-perspective schema, standards metadata, and self-verification gate; excludes adopter runtime timeline correctness",
         enumerability: "closed-world",
       },
       residualRisk: [],

package/site/kfd-site.json

@@ -82,7 +82,7 @@
       ],
       "explanation": [
         "| Layer | Decision | Reader question | Commitment | |---|---|---|---| | Perspective-bearing views | KFD-4 | How should a product show time, history, replay, sync, or mixed-source work state? | Timelines must declare their observer: a useful view states who is observing, which facts were accepted, and how concurrent facts were projected. |",
-        "KFD-4 is the first such guideline. It applies KFD-1/2/3 to the problem of perspective and timeline order. In a multi-machine or multi-agent world, a product should not pretend to own a universal global clock. It should preserve non-drifting facts, make trust start from those facts, and let participants cooperate by exposing the observer, accepted ranges, causal constraints, and projection policy behind the view."
+        "KFD-4 is the first such guideline. It applies KFD-1/2/3 to the problem of perspective and timeline order. In a multi-machine or multi-agent world, a product should not pretend to own a universal global clock. It should preserve non-drifting facts, make trust start from those facts, and let participants cooperate by exposing the observer, accepted ranges, causal constraints, and projection policy behind the view. KFD-4 gates perspective-bearing views; it does not claim that importing the KFD-4 schema proves an adopter's concrete timeline implementation is complete or correct."
       ]
     },
     "productProofPath": {
@@ -136,7 +136,7 @@
         "homepagePriority": 27,
         "defaultPresentation": "practice-table",
         "includeInFirstScreen": false,
-        "markdown": "KFDs after the foundation triad may define practice guidelines: procedures\nthat apply the foundation to a specific class of real-world product behavior.\nThey do not expand the foundation triad; they show how the foundation behaves\nwhen a product must make a concrete kind of reality legible.\n\n| Layer | Decision | Reader question | Commitment |\n|---|---|---|---|\n| Perspective-bearing views | KFD-4 | How should a product show time, history, replay, sync, or mixed-source work state? | Timelines must declare their observer: a useful view states who is observing, which facts were accepted, and how concurrent facts were projected. |\n\nKFD-4 is the first such guideline. It applies KFD-1/2/3 to the problem of\nperspective and timeline order. In a multi-machine or multi-agent world, a\nproduct should not pretend to own a universal global clock. It should preserve\nnon-drifting facts, make trust start from those facts, and let participants\ncooperate by exposing the observer, accepted ranges, causal constraints, and\nprojection policy behind the view."
+        "markdown": "KFDs after the foundation triad may define practice guidelines: procedures\nthat apply the foundation to a specific class of real-world product behavior.\nThey do not expand the foundation triad; they show how the foundation behaves\nwhen a product must make a concrete kind of reality legible.\n\n| Layer | Decision | Reader question | Commitment |\n|---|---|---|---|\n| Perspective-bearing views | KFD-4 | How should a product show time, history, replay, sync, or mixed-source work state? | Timelines must declare their observer: a useful view states who is observing, which facts were accepted, and how concurrent facts were projected. |\n\nKFD-4 is the first such guideline. It applies KFD-1/2/3 to the problem of\nperspective and timeline order. In a multi-machine or multi-agent world, a\nproduct should not pretend to own a universal global clock. It should preserve\nnon-drifting facts, make trust start from those facts, and let participants\ncooperate by exposing the observer, accepted ranges, causal constraints, and\nprojection policy behind the view. KFD-4 gates perspective-bearing views; it\ndoes not claim that importing the KFD-4 schema proves an adopter's concrete\ntimeline implementation is complete or correct."
       },
       {
         "id": "product-proof-path",
@@ -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."
+        "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",