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

package/docs/KFD-3-usage.md

@@ -0,0 +1,98 @@
+# 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`;
+- public fact sources that identify where load-bearing facts live and which
+  surfaces are only projections;
+- 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;
+- value evidence that binds important participant-facing value claims to facts,
+  artifacts, checks, trust assessments, and residual-risk state;
+- visible constraints, including what is restricted, why, and where review or
+  escalation happens;
+- choice paths that let participants choose or decline safe cooperation modes;
+- extension requests that tell participants how to ask for a new value,
+  capability, or interface when the declared interface is insufficient;
+- 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.
+
+## Value Evidence
+
+KFD-3 does not treat value as a marketing claim. A collaboration interface
+should state the value a participant is being asked to trust, then point to the
+facts and evidence that make that value inspectable.
+
+Each `valueEvidence` entry should identify:
+
+- the value claim;
+- the participants who depend on it;
+- the fact artifacts that define the claim;
+- the evidence artifacts or checks that show those facts are present;
+- a KFD-2 trust assessment or residual-risk state when the claim cannot be
+  exhaustively proved by machine.
+
+This is the engineering bridge between KFD-2 and KFD-3. KFD-2 explains how
+trust is assessed from facts. KFD-3 explains how that assessed value is exposed
+to participants before cooperation is requested.
+
+## 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.
+
+## Extension Requests
+
+KFD-3 treats extension requests as part of the collaboration interface. A
+human or agent should not have to infer how to cooperate when a declared
+interface is missing a value or capability. The interface should expose a
+visible request path, the participants it is for, the trigger, and the expected
+outcome.
+
+For KFD itself, the standard request path for missing KFD-2 trust-taxonomy
+values is a GitHub issue in `kungfu-systems/kfd`. This is both a KFD-2 trust
+rule and a KFD-3 collaboration rule: the taxonomy defines what values are valid,
+while the collaboration interface tells agents how to request an extension
+without inventing private values or relying on pressure.

package/docs/KFD-4-usage.md

@@ -0,0 +1,31 @@
+# KFD-4 Implementation Notes
+
+KFD-4 defines the observer-perspective rule: timelines must declare their
+observer. This page is the package implementation note for machine consumers
+and products that show perspective-bearing timelines. The authoritative
+decision text remains `decisions/KFD-4.md`.
+
+## Package Surface
+
+The KFD package implements KFD-4 through:
+
+- `decisions/KFD-4.md`: the authoritative procedure text.
+- `schemas/kfd-4/observer-perspective.schema.json`: the KFD-owned schema for
+  observer-relative timeline views.
+- `standards.json#/standards/kfd-4`: metadata that exposes the schema ID, schema
+  path, interface contract, and concept names.
+- `scripts/check.mjs`: verification that KFD-4 metadata and schema remain
+  wired into the package.
+
+## When To Use The Gate
+
+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.
+
+## 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.

package/docs/MAP.md

@@ -5,15 +5,32 @@
 | What is KFD, and what decisions exist? | [`../README.md`](../README.md) |
 | What is the KFD-1/2/3 foundation triad? | [`../README.md`](../README.md#foundation-triad) |
 | What worldview structure does the foundation triad express? | [`../README.md`](../README.md#foundation-model) |
+| What practice guidelines are derived from the foundation triad? | [`../README.md`](../README.md#practice-guidelines) |
+| 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 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) |
+| How should an agent quickly understand this package? | [`../README.md`](../README.md#agent-quickstart) |
+| What is the concrete self-proof case for KFD-1/2/3/4? | [`../README.md`](../README.md#product-proof-path) and the implementation case in each KFD |
+| Where is the public KFD fact source? | [`../README.md`](../README.md#decision-metadata) and [`../site/kfd-site.json`](../site/kfd-site.json) decision metadata |
+| What does Apache-2.0 cover, and what remains official/trademark-bound? | [`../TRADEMARKS.md`](../TRADEMARKS.md) |
 | 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) |
+| How should a site map decision pages to usage subpages? | [`../site/kfd-site.json`](../site/kfd-site.json) — `decisionPages.usagePages` maps `/N` to `/N/usage` |
+| 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-usage.md`](KFD-3-usage.md) |
+| What schema should a product or agent use for generic KFD-2 trust assessment? | [`KFD-2-usage.md`](KFD-2-usage.md#generic-trust-claims) |
+| What should an agent do when a needed KFD-2 trust taxonomy value is missing? | [`KFD-2-usage.md`](KFD-2-usage.md#trust-taxonomy) — open a KFD GitHub issue |
 | 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-usage.md`](KFD-2-usage.md) — release passports are a KFD-2 projection |
 | 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 |
+| How is this package versioned and released? | [KFD-1](../decisions/KFD-1.md) applied to itself; Buildchain governs releases |
 | What release impact ledger should Buildchain consume for production passports? | [`../release-impact.json`](../release-impact.json) |
+| What release provenance path must alpha promotion use? | [`release-governance.md`](release-governance.md) |
 | How do I verify registry/document agreement? | `node scripts/check.mjs` |
 | How do I report a vulnerability? | [`../SECURITY.md`](../SECURITY.md) |

package/docs/release-governance.md

@@ -0,0 +1,28 @@
+# Release Governance Notes
+
+KFD releases are governed by Buildchain channel promotion. The package version
+line stays fixed at `v1.0`; alpha and production releases move through
+protected channel branches.
+
+For alpha promotion, Buildchain treats the provenance path as part of the
+release contract:
+
+```text
+dev/v1/v1.0 -> alpha/v1/v1.0
+```
+
+The alpha branch must be updated by a merged same-repository pull request whose
+head is `dev/v1/v1.0` and whose base is `alpha/v1/v1.0`. A temporary promotion
+branch may satisfy GitHub freshness rules, but it is not a valid Buildchain
+release source for KFD alpha publishing.
+
+The protected branch required status check must also name the status emitted by
+the current Verify workflow. As of the alpha.14 line, that required check is:
+
+```text
+check / check
+```
+
+Keeping the branch protection rule and the workflow-emitted status name aligned
+is part of KFD-1's "facts must not drift" requirement: the release gate cannot
+depend on a stale status context that no current workflow can produce.

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.20",
+  "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,30 +1,56 @@
 {
   "name": "@kungfu-tech/kfd",
-  "version": "1.0.0-alpha.2",
+  "version": "1.0.0-alpha.20",
   "description": "Kung Fu Decisions (KFD): the kungfu-systems organization-wide decision registry, as a consumable artifact",
   "license": "Apache-2.0",
   "files": [
     "README.md",
+    "TRADEMARKS.md",
     "decisions",
     "registry.json",
     "standards.json",
+    "kfd.release.json",
     "schemas",
     "site",
+    "scripts",
+    "buildchain.contract-lock.json",
+    "buildchain.release-propagation.json",
+    "release-impact.json",
+    ".buildchain/kfd-1/contract-world.witness.json",
+    ".buildchain/kfd-2",
+    ".buildchain/kfd-3",
     "docs"
   ],
   "exports": {
     "./package.json": "./package.json",
     "./README.md": "./README.md",
+    "./TRADEMARKS.md": "./TRADEMARKS.md",
     "./registry.json": "./registry.json",
     "./standards.json": "./standards.json",
+    "./kfd.release.json": "./kfd.release.json",
     "./site/kfd-site.json": "./site/kfd-site.json",
+    "./buildchain.contract-lock.json": "./buildchain.contract-lock.json",
+    "./buildchain.release-propagation.json": "./buildchain.release-propagation.json",
+    "./release-impact.json": "./release-impact.json",
+    "./scripts/*.mjs": "./scripts/*.mjs",
+    "./buildchain/kfd-1/contract-world.witness.json": "./.buildchain/kfd-1/contract-world.witness.json",
+    "./buildchain/kfd-2/public-release-trust.claim.json": "./.buildchain/kfd-2/public-release-trust.claim.json",
+    "./buildchain/kfd-2/kfd-foundation.trust-claims.json": "./.buildchain/kfd-2/kfd-foundation.trust-claims.json",
+    "./buildchain/kfd-2/kfd-foundation.trust-assessment.json": "./.buildchain/kfd-2/kfd-foundation.trust-assessment.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:site-bundle": "node scripts/update-site-bundle.mjs",
+    "update:kfd-1-witness": "node scripts/update-kfd-1-witness.mjs",
+    "update:kfd-2-claim": "node scripts/update-kfd-2-claim.mjs",
+    "update:kfd-3-witness": "node scripts/update-kfd-3-witness.mjs"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",

package/registry.json

@@ -6,10 +6,10 @@
       "number": 1,
       "id": "KFD-1",
       "slug": "kfd-1",
-      "title": "Contracts must not drift: contract worlds need one fact source",
+      "title": "Facts must not drift: contract worlds need one fact source",
       "kind": "procedure",
       "status": "active",
-      "path": "decisions/kfd-1.md",
+      "path": "decisions/KFD-1.md",
       "url": "https://kfd.libkungfu.dev/1"
     },
     {
@@ -19,18 +19,28 @@
       "title": "Trust must start from facts: responsibility must be inspectable",
       "kind": "principle",
       "status": "active",
-      "path": "decisions/kfd-2.md",
+      "path": "decisions/KFD-2.md",
       "url": "https://kfd.libkungfu.dev/2"
     },
     {
       "number": 3,
       "id": "KFD-3",
       "slug": "kfd-3",
-      "title": "Cooperation must start from transparent value: compliance must not be coerced",
+      "title": "Cooperation must start from trusted value: compliance must not be coerced",
       "kind": "principle",
       "status": "active",
-      "path": "decisions/kfd-3.md",
+      "path": "decisions/KFD-3.md",
       "url": "https://kfd.libkungfu.dev/3"
+    },
+    {
+      "number": 4,
+      "id": "KFD-4",
+      "slug": "kfd-4",
+      "title": "Timelines must declare their observer: useful views need a stated perspective",
+      "kind": "procedure",
+      "status": "active",
+      "path": "decisions/KFD-4.md",
+      "url": "https://kfd.libkungfu.dev/4"
     }
   ]
 }

package/release-impact.json

@@ -0,0 +1,113 @@
+{
+  "schemaVersion": 1,
+  "contract": "kungfu-buildchain-impact",
+  "release": {
+    "line": "v1.0",
+    "channel": "release",
+    "targetRef": "release/v1/v1.0"
+  },
+  "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."
+  },
+  "surfaceImpacts": [
+    {
+      "id": "kfd-content",
+      "impact": "patch",
+      "class": "content",
+      "rationale": "KFD documents are append-only content coordinates; current documentation changes add KFD-4 as a practice guideline for declared observer timelines, while preserving existing decision numbers and registry shape."
+    },
+    {
+      "id": "kfd-registry-schema",
+      "impact": "patch",
+      "class": "compatible",
+      "rationale": "registry.json keeps schemaVersion 1 and the existing entry shape, including number, id, slug, title, kind, status, path, and url; slug and path values are stable number coordinates."
+    },
+    {
+      "id": "kfd-standards-metadata",
+      "impact": "minor",
+      "class": "additive",
+      "rationale": "standards.json and schemas/ add the KFD-2 trust-taxonomy, trust-claims, trust-assessment, release-claims, and release-trust-passport schema IDs, explicit KFD-1/2/3/4 interface versions, KFD-4 observer-perspective schema metadata, KFD document SHA-256 bindings, KFD-owned concept names, KFD-3 fact-source interface metadata, and official-status interface metadata for downstream consumers."
+    },
+    {
+      "id": "kfd-package-structure",
+      "impact": "minor",
+      "class": "additive",
+      "rationale": "The npm package now publishes the KFD-2 trust taxonomy, generic trust claims, generic trust assessment, release trust schemas, KFD usage documentation, KFD-3 self collaboration-interface witnesses, KFD-4 observer-perspective schema, TRADEMARKS.md, public fact-source metadata, agent quickstart/self-proof documentation, Buildchain contract lock metadata, and repository verification scripts through existing schemas/, docs/, standards.json, site/, scripts/, .buildchain/, and subpath exports while preserving README.md, decisions/, registry.json, and site/ as stable directories."
+    },
+    {
+      "id": "kfd-buildchain-contract-lock",
+      "impact": "minor",
+      "class": "release-governance",
+      "rationale": "KFD now uses Buildchain v2 floating workflow refs with a consumer-owned buildchain.contract-lock.json, so Buildchain runtime contract drift is checked before heavy build or promotion work while retaining floating-ref upgrade flow."
+    },
+    {
+      "id": "kfd-site-homepage-bundle",
+      "impact": "minor",
+      "class": "additive",
+      "rationale": "site/kfd-site.json now exposes generated README-backed homepage.sections and homepage.displayPlan fields, including the adoption-boundary and practice-guidelines homepage sections, and scripts/check.mjs verifies the checked-in bundle matches the README projection so downstream sites can render KFD-owned homepage content without maintaining their own README parser or drifting copy."
+    },
+    {
+      "id": "kfd-site-decision-usage-pages",
+      "impact": "minor",
+      "class": "additive",
+      "rationale": "site/kfd-site.json now exposes decisionPages.usagePages, mapping each authoritative KFD decision page to its docs/KFD-N-usage.md child page and stable /N/usage route."
+    },
+    {
+      "id": "kfd-3-self-collaboration",
+      "impact": "minor",
+      "class": "release-passport",
+      "rationale": "KFD now declares its own participant-facing collaboration interface and ships pre-build plus artifact-side KFD-3 witnesses so Buildchain can audit interface closure in the release passport."
+    },
+    {
+      "id": "kfd-3-trusted-value-evidence",
+      "impact": "minor",
+      "class": "additive",
+      "rationale": "KFD-3 collaboration interfaces now declare explicit valueEvidence that binds participant-facing value claims to fact artifacts, evidence artifacts, KFD-2 trust assessments, and residual-risk state."
+    },
+    {
+      "id": "kfd-2-public-release-trust-claim",
+      "impact": "minor",
+      "class": "release-passport",
+      "rationale": "KFD now ships an explicit machine-bound public KFD-2 release trust claim and passes it into Buildchain release passport generation."
+    },
+    {
+      "id": "kfd-2-generic-trust-assessment-core",
+      "impact": "minor",
+      "class": "additive",
+      "rationale": "KFD-2 now publishes generic trust-claims and trust-assessment schemas and dogfoods them through KFD-owned assessment files that evaluate KFD-1 contract-world, KFD-3 collaboration-interface, and KFD-4 observer-perspective claims."
+    },
+    {
+      "id": "kfd-numbered-paths",
+      "impact": "minor",
+      "class": "compatible",
+      "rationale": "Decision documents now use stable numbered paths under decisions/KFD-N.md, while usage documentation uses docs/KFD-N-usage.md to distinguish authoritative decision text from consumer implementation notes."
+    },
+    {
+      "id": "kfd-release-anchor",
+      "impact": "minor",
+      "class": "release-governance",
+      "rationale": "KFD now declares its package version through an anchored/manual release manifest so package version state is an explicit release fact rather than an auto-derived Buildchain side effect."
+    },
+    {
+      "id": "kfd-release-propagation",
+      "impact": "patch",
+      "class": "compatible",
+      "rationale": "The KFD to site-libkungfu-dev propagation graph now targets the downstream site's actual main branch and documents the exact KFD package surfaces consumed by kfd.libkungfu.dev, without changing the release propagation graph contract."
+    },
+    {
+      "id": "kfd-1-compatibility-impact-core",
+      "impact": "minor",
+      "class": "additive",
+      "rationale": "KFD-1 now defines breaking, additive, none, and unclassifiable as the generic compatibility-impact core, with release versioning as one projection rather than the only interpretation."
+    },
+    {
+      "id": "kfd-1-surface-register",
+      "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."
+    }
+  ],
+  "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."
+}

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

@@ -24,6 +24,13 @@
       "type": "string",
       "minLength": 1
     },
+    "compatibilityImpactClasses": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/compatibilityImpact"
+      },
+      "uniqueItems": true
+    },
     "surfaces": {
       "type": "array",
       "items": {
@@ -39,19 +46,75 @@
             "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
           },
           "class": {
-            "enum": [
-              "integration-time",
-              "cross-time"
-            ]
+            "$ref": "#/$defs/surfaceClass"
+          },
+          "classes": {
+            "type": "array",
+            "items": {
+              "$ref": "#/$defs/surfaceClass"
+            },
+            "uniqueItems": true,
+            "minItems": 1
           },
           "description": {
             "type": "string",
             "minLength": 1
+          },
+          "weldRationale": {
+            "type": "string",
+            "minLength": 1
+          },
+          "impactProjection": {
+            "$ref": "#/$defs/impactProjection"
           }
         },
         "additionalProperties": false
       }
     }
   },
+  "$defs": {
+    "surfaceClass": {
+      "enum": [
+        "integration-time",
+        "cross-time"
+      ]
+    },
+    "compatibilityImpact": {
+      "enum": [
+        "breaking",
+        "additive",
+        "none",
+        "unclassifiable"
+      ]
+    },
+    "impactProjection": {
+      "type": "object",
+      "required": [
+        "breaking",
+        "additive",
+        "none",
+        "unclassifiable"
+      ],
+      "properties": {
+        "breaking": {
+          "type": "string",
+          "minLength": 1
+        },
+        "additive": {
+          "type": "string",
+          "minLength": 1
+        },
+        "none": {
+          "type": "string",
+          "minLength": 1
+        },
+        "unclassifiable": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "additionalProperties": false
+    }
+  },
   "additionalProperties": true
 }

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

@@ -37,6 +37,75 @@
       },
       "additionalProperties": false
     },
+    "compatibilityImpactClasses": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/compatibilityImpact"
+      },
+      "uniqueItems": true
+    },
+    "surfaces": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "name",
+          "class",
+          "description",
+          "sourcePath",
+          "artifactPath",
+          "impactProjection"
+        ],
+        "properties": {
+          "name": {
+            "type": "string",
+            "minLength": 1
+          },
+          "class": {
+            "$ref": "#/$defs/surfaceClass"
+          },
+          "classes": {
+            "type": "array",
+            "items": {
+              "$ref": "#/$defs/surfaceClass"
+            },
+            "uniqueItems": true,
+            "minItems": 1
+          },
+          "description": {
+            "type": "string",
+            "minLength": 1
+          },
+          "weldRationale": {
+            "type": "string",
+            "minLength": 1
+          },
+          "sourcePath": {
+            "type": "string",
+            "minLength": 1
+          },
+          "artifactPath": {
+            "type": "string",
+            "minLength": 1
+          },
+          "sourceSha256": {
+            "type": "string",
+            "pattern": "^[0-9a-f]{64}$"
+          },
+          "expectedSha256": {
+            "type": "string",
+            "pattern": "^[0-9a-f]{64}$"
+          },
+          "byteForByte": {
+            "type": "boolean"
+          },
+          "impactProjection": {
+            "$ref": "#/$defs/impactProjection"
+          }
+        },
+        "additionalProperties": true
+      }
+    },
     "evidence": {
       "type": "array",
       "items": {
@@ -59,5 +128,49 @@
       }
     }
   },
+  "$defs": {
+    "surfaceClass": {
+      "enum": [
+        "integration-time",
+        "cross-time"
+      ]
+    },
+    "compatibilityImpact": {
+      "enum": [
+        "breaking",
+        "additive",
+        "none",
+        "unclassifiable"
+      ]
+    },
+    "impactProjection": {
+      "type": "object",
+      "required": [
+        "breaking",
+        "additive",
+        "none",
+        "unclassifiable"
+      ],
+      "properties": {
+        "breaking": {
+          "type": "string",
+          "minLength": 1
+        },
+        "additive": {
+          "type": "string",
+          "minLength": 1
+        },
+        "none": {
+          "type": "string",
+          "minLength": 1
+        },
+        "unclassifiable": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "additionalProperties": false
+    }
+  },
   "additionalProperties": true
 }