hachure 0.8.0 → 0.9.0

package/README.md

@@ -73,7 +73,7 @@ Resource Shape envelope. Product-specific records use product-scoped namespaces
 Pre-1.0: the format uses hard breaking changes rather than compatibility aliases.
 No forward or backward compatibility guarantees are made across versions. Version
 bumps are reflected in `schemaVersion` (an integer field in TrustBundle, currently
-`4`) and in the status function version (a string exported by the reference
+`5`) and in the status function version (a string exported by the reference
 implementation as `statusFunctionVersion`, currently `"2"`).
 
 Schema version `4` adds optional claim freshness fields (`expiresAt` /
@@ -84,6 +84,14 @@ every bundle valid at `schemaVersion` `3` remains valid; only the deriver
 `status-function.md` and the `sf-expired-window` / `sf-revoked-event` /
 `sf-no-freshness-fields` conformance vectors.
 
+Schema version `5` renames the Claim `surface` field to `facet` and makes it
+optional (previously required) — the one deliberate hard break named above.
+Bundles declaring `schemaVersion` `2` through `4` are no longer schema-valid
+under this release: their `surface` field is rejected by `claim.schema.json`'s
+`additionalProperties: false`. Producers MUST re-emit as `facet` and self-declare
+`schemaVersion: 5`. See `merge.md` §4 for `facet`'s (unchanged) treatment in claim
+identity.
+
 ---
 
 ## Conformance language
@@ -140,7 +148,9 @@ a disputed mapping claim cannot yield a verified answer.
 ### Claim
 
 An assertion about a real-world subject. A claim has a stable `id`, a `subjectType`
-and `subjectId` pair identifying what is being asserted, a `claimType`, a
+and `subjectId` pair identifying what is being asserted, an optional `facet` (a
+producer-defined grouping or namespace for the claim — see `merge.md` §4 for why
+it's excluded from cross-producer claim identity), a `claimType`, a
 `fieldOrBehavior`, and a `value`. Claims carry optional `impactLevel`, integrity
 anchors, policy references, derivation edges, and confidence basis metadata.
 

package/conformance/manifest.json

@@ -2,7 +2,7 @@
   "$schemaComment": "Machine-readable conformance manifest for the Hachure trust format. Not a JSON Schema itself — a structured index of what an implementation must pass to claim conformance at each level. Additive to, not a replacement for, index.mjs's `testVectors` export (which lists raw vectors, not levels/pass-criteria).",
   "manifestVersion": 1,
   "appliesTo": {
-    "schemaVersion": [2, 3, 4],
+    "schemaVersion": [5],
     "statusFunctionVersion": "2"
   },
   "levels": [

package/conformance/merge/merge-agree-values.json

@@ -3,7 +3,7 @@
   "now": "2026-06-10T00:00:00.000Z",
   "inputs": [
     {
-      "schemaVersion": 4,
+      "schemaVersion": 5,
       "source": "producer-a:run-1",
       "producerId": "producer-a",
       "claims": [
@@ -11,7 +11,7 @@
           "id": "producer-a.claim.readiness.coverage",
           "subjectType": "repo",
           "subjectId": "repo-1",
-          "surface": "readiness",
+          "facet": "readiness",
           "claimType": "coverage",
           "fieldOrBehavior": "coverage",
           "value": 91,
@@ -24,7 +24,7 @@
       "events": []
     },
     {
-      "schemaVersion": 4,
+      "schemaVersion": 5,
       "source": "producer-b:run-7",
       "producerId": "producer-b",
       "claims": [
@@ -32,7 +32,7 @@
           "id": "producer-b.claim.readiness.coverage",
           "subjectType": "repo",
           "subjectId": "repo-1",
-          "surface": "readiness",
+          "facet": "readiness",
           "claimType": "coverage",
           "fieldOrBehavior": "coverage",
           "value": 91,

package/conformance/merge/merge-collision-order-independence.json

@@ -1,9 +1,9 @@
 {
-  "$comment": "Hand-derivation (merge.md §5/§6/§8). This vector's inputs/expect are STRUCTURALLY identical to .kontourai/flow-agents/hachure-identifier-merge/design.md §11 'Worked example + independent hand-derivation' -- the bundle-level source/producerId values were genericized from design.md §11's worked example (survey -> producer-a, veritas -> producer-b, flow -> producer-c; mapping recorded in this session's deliver.md History) to keep this shipped, machine-checked conformance fixture vendor-neutral, consistent with the rest of this repo's conformance vectors and merge.md's own examples (plan.md AC7). This rename does NOT change expect: source/producerId are bundle-level fields, not part of the Claim record being compared, so the tie-break outcome below is unaffected -- re-derived by hand against the renamed inputs. shared.claim.x appears in Bundle A (subjectId r1, surface readiness, claimType coverage, value 91) and Bundle B (subjectId r2, surface governance, claimType policy-check, value true) -- content differs under the same id, so per merge.md §5 rule 2 this is a collision, reported as {collection: 'claims', id: 'shared.claim.x'}. Per merge.md §6's tie-break, compute a canonical (sorted-key) serialization of each variant: A's serialization starts '{\\\"claimType\\\":\\\"coverage\\\",...}', B's starts '{\\\"claimType\\\":\\\"policy-check\\\",...}' -- lexicographically 'coverage' < 'policy-check' ('c' < 'p'), so A's record is the deterministically-kept content regardless of whether the implementation is handed [A,B,C], [B,A,C], [C,B,A], or any other permutation of the 3 inputs -- this is the vector that exercises the order-independence MUST (test/merge.test.mjs asserts identical output across every permutation of inputs). Bundle C's claim ('unrelated.claim.y') never collides with anything, and its id is a distinct string never repeated. Status-function.md Step 6 ('no policy, no evidence') applies to both surviving claim ids ('shared.claim.x' from kept content A, and 'unrelated.claim.y') since no bundle attaches any policy or evidence/events -> both derive 'unknown'.",
+  "$comment": "Hand-derivation (merge.md §5/§6/§8). This vector's inputs/expect are STRUCTURALLY identical to .kontourai/flow-agents/hachure-identifier-merge/design.md §11 'Worked example + independent hand-derivation' -- the bundle-level source/producerId values were genericized from design.md §11's worked example (survey -> producer-a, veritas -> producer-b, flow -> producer-c; mapping recorded in this session's deliver.md History) to keep this shipped, machine-checked conformance fixture vendor-neutral, consistent with the rest of this repo's conformance vectors and merge.md's own examples (plan.md AC7). This rename does NOT change expect: source/producerId are bundle-level fields, not part of the Claim record being compared, so the tie-break outcome below is unaffected -- re-derived by hand against the renamed inputs. shared.claim.x appears in Bundle A (subjectId r1, facet readiness, claimType coverage, value 91) and Bundle B (subjectId r2, facet governance, claimType policy-check, value true) -- content differs under the same id, so per merge.md §5 rule 2 this is a collision, reported as {collection: 'claims', id: 'shared.claim.x'}. Per merge.md §6's tie-break, compute a canonical (sorted-key) serialization of each variant: A's serialization starts '{\\\"claimType\\\":\\\"coverage\\\",...}', B's starts '{\\\"claimType\\\":\\\"policy-check\\\",...}' -- lexicographically 'coverage' < 'policy-check' ('c' < 'p'), so A's record is the deterministically-kept content regardless of whether the implementation is handed [A,B,C], [B,A,C], [C,B,A], or any other permutation of the 3 inputs -- this is the vector that exercises the order-independence MUST (test/merge.test.mjs asserts identical output across every permutation of inputs). hachure-facet-rename provenance note: this vector's claim key was renamed surface -> facet (0.9.0). The tie-break outcome is unaffected by that rename and was re-derived by hand, not merely asserted: both colliding records' sorted-key canonical serializations still diverge for the first time inside the claimType value ('coverage' vs 'policy-check'), a key that is alphabetically earlier than every other property on this claim shape (id, subjectType, subjectId, facet, fieldOrBehavior, value, createdAt, updatedAt) both before and after the rename -- the facet/surface key itself never becomes part of the comparison because the strings already diverge before either serialization reaches that key, regardless of where the renamed key sorts relative to the others. (Confirmed by direct RFC-8785-shaped sorted-key serialization of both the pre-rename and post-rename claim objects: both produce the same 'A sorts first' result.) Bundle C's claim ('unrelated.claim.y') never collides with anything, and its id is a distinct string never repeated. Status-function.md Step 6 ('no policy, no evidence') applies to both surviving claim ids ('shared.claim.x' from kept content A, and 'unrelated.claim.y') since no bundle attaches any policy or evidence/events -> both derive 'unknown'.",
   "now": "2026-06-10T00:00:00.000Z",
   "inputs": [
     {
-      "schemaVersion": 4,
+      "schemaVersion": 5,
       "source": "producer-a",
       "producerId": "producer-a",
       "claims": [
@@ -11,7 +11,7 @@
           "id": "shared.claim.x",
           "subjectType": "repo",
           "subjectId": "r1",
-          "surface": "readiness",
+          "facet": "readiness",
           "claimType": "coverage",
           "fieldOrBehavior": "coverage",
           "value": 91,
@@ -24,7 +24,7 @@
       "events": []
     },
     {
-      "schemaVersion": 4,
+      "schemaVersion": 5,
       "source": "producer-b",
       "producerId": "producer-b",
       "claims": [
@@ -32,7 +32,7 @@
           "id": "shared.claim.x",
           "subjectType": "repo",
           "subjectId": "r2",
-          "surface": "governance",
+          "facet": "governance",
           "claimType": "policy-check",
           "fieldOrBehavior": "signed-off",
           "value": true,
@@ -45,7 +45,7 @@
       "events": []
     },
     {
-      "schemaVersion": 4,
+      "schemaVersion": 5,
       "source": "producer-c",
       "producerId": "producer-c",
       "claims": [
@@ -53,7 +53,7 @@
           "id": "unrelated.claim.y",
           "subjectType": "gate",
           "subjectId": "g1",
-          "surface": "gates",
+          "facet": "gates",
           "claimType": "gate-status",
           "fieldOrBehavior": "passed",
           "value": true,

package/conformance/merge/merge-conflict-status.json

@@ -3,7 +3,7 @@
   "now": "2026-06-10T00:00:00.000Z",
   "inputs": [
     {
-      "schemaVersion": 4,
+      "schemaVersion": 5,
       "source": "producer-a:run-3",
       "producerId": "producer-a",
       "claims": [
@@ -11,7 +11,7 @@
           "id": "producer-a.claim.access.grant",
           "subjectType": "resource",
           "subjectId": "svc-1",
-          "surface": "access",
+          "facet": "access",
           "claimType": "access-check",
           "fieldOrBehavior": "granted",
           "value": true,
@@ -75,7 +75,7 @@
       ]
     },
     {
-      "schemaVersion": 4,
+      "schemaVersion": 5,
       "source": "producer-b:run-4",
       "producerId": "producer-b",
       "claims": [
@@ -83,7 +83,7 @@
           "id": "producer-b.claim.access.grant",
           "subjectType": "resource",
           "subjectId": "svc-1",
-          "surface": "access",
+          "facet": "access",
           "claimType": "access-check",
           "fieldOrBehavior": "granted",
           "value": true,

package/conformance/merge/merge-conflict-value.json

@@ -3,7 +3,7 @@
   "now": "2026-06-10T00:00:00.000Z",
   "inputs": [
     {
-      "schemaVersion": 4,
+      "schemaVersion": 5,
       "source": "producer-a:run-2",
       "producerId": "producer-a",
       "claims": [
@@ -11,7 +11,7 @@
           "id": "producer-a.claim.pricing.tier",
           "subjectType": "repo",
           "subjectId": "repo-2",
-          "surface": "pricing",
+          "facet": "pricing",
           "claimType": "pricing-field",
           "fieldOrBehavior": "tier",
           "value": "gold",
@@ -50,7 +50,7 @@
       "events": []
     },
     {
-      "schemaVersion": 4,
+      "schemaVersion": 5,
       "source": "producer-b:run-9",
       "producerId": "producer-b",
       "claims": [
@@ -58,7 +58,7 @@
           "id": "producer-b.claim.pricing.tier",
           "subjectType": "repo",
           "subjectId": "repo-2",
-          "surface": "pricing",
+          "facet": "pricing",
           "claimType": "pricing-field",
           "fieldOrBehavior": "tier",
           "value": "silver",

package/conformance/sf-authority-resolved.json

@@ -1,14 +1,14 @@
 {
   "now": "2026-06-10T00:00:00.000Z",
   "input": {
-    "schemaVersion": 3,
+    "schemaVersion": 5,
     "source": "spec-conformance:authority-resolved",
     "claims": [
       {
         "id": "claim.status.current",
         "subjectType": "data-field",
         "subjectId": "dataset:program-status",
-        "surface": "public-data.program",
+        "facet": "public-data.program",
         "claimType": "public-data-field",
         "fieldOrBehavior": "currentStatus",
         "value": "active",

package/conformance/sf-disputed-blocking.json

@@ -1,14 +1,14 @@
 {
   "now": "2026-06-10T00:00:00.000Z",
   "input": {
-    "schemaVersion": 3,
+    "schemaVersion": 5,
     "source": "spec-conformance:disputed-blocking",
     "claims": [
       {
         "id": "claim.fee.value",
         "subjectType": "data-field",
         "subjectId": "dataset:registration-fee",
-        "surface": "public-data.fees",
+        "facet": "public-data.fees",
         "claimType": "public-data-field",
         "fieldOrBehavior": "registrationFee",
         "value": 150,

package/conformance/sf-expired-window.json

@@ -1,14 +1,14 @@
 {
   "now": "2026-06-10T00:00:00.000Z",
   "input": {
-    "schemaVersion": 4,
+    "schemaVersion": 5,
     "source": "spec-conformance:expired-window",
     "claims": [
       {
         "id": "claim.window.expires-at",
         "subjectType": "data-field",
         "subjectId": "dataset:session-token",
-        "surface": "public-data.status",
+        "facet": "public-data.status",
         "claimType": "public-data-field",
         "fieldOrBehavior": "tokenValid",
         "value": true,
@@ -22,7 +22,7 @@
         "id": "claim.window.ttl",
         "subjectType": "data-field",
         "subjectId": "dataset:cache-entry",
-        "surface": "public-data.status",
+        "facet": "public-data.status",
         "claimType": "public-data-field",
         "fieldOrBehavior": "cacheFresh",
         "value": true,

package/conformance/sf-no-freshness-fields.json

@@ -1,14 +1,14 @@
 {
   "now": "2026-06-10T00:00:00.000Z",
   "input": {
-    "schemaVersion": 4,
+    "schemaVersion": 5,
     "source": "spec-conformance:no-freshness-fields",
     "claims": [
       {
         "id": "claim.api.rate-limit",
         "subjectType": "api",
         "subjectId": "public-api",
-        "surface": "api.guarantees",
+        "facet": "api.guarantees",
         "claimType": "software-evidence",
         "fieldOrBehavior": "rate limit is enforced",
         "value": "100 requests/minute",

package/conformance/sf-reference-bundle-snapshot.json

@@ -1,7 +1,7 @@
 {
   "now": "2026-06-10T00:00:00.000Z",
   "input": {
-    "schemaVersion": 3,
+    "schemaVersion": 5,
     "source": "kontour-surface-validation-fixtures",
     "identityLinks": [
       {
@@ -23,7 +23,7 @@
         "id": "claim.repo-governance.api-proof",
         "subjectType": "repo-surface",
         "subjectId": "example/repo:src/api",
-        "surface": "repo-governance.developer-evidence",
+        "facet": "repo-governance.developer-evidence",
         "claimType": "software-evidence",
         "fieldOrBehavior": "acceptanceCriteriaLane",
         "value": "npm test passed for API surface change",
@@ -49,7 +49,7 @@
         "id": "claim.field-attested-records.registration-status",
         "subjectType": "attested-record",
         "subjectId": "field-attested-records:denver-example-record",
-        "surface": "field-attested-records.public-data",
+        "facet": "field-attested-records.public-data",
         "claimType": "public-data-field",
         "fieldOrBehavior": "registrationStatus",
         "value": "OPEN",
@@ -70,7 +70,7 @@
         "id": "claim.fact-resolution.w2-wages",
         "subjectType": "fact",
         "subjectId": "fact-resolution:demo-case-2025:w2.wages",
-        "surface": "fact-resolution.financial-facts",
+        "facet": "fact-resolution.financial-facts",
         "claimType": "verified-financial-fact",
         "fieldOrBehavior": "w2.wages",
         "value": 123456,
@@ -90,7 +90,7 @@
         "id": "claim.surface.future-console",
         "subjectType": "roadmap-item",
         "subjectId": "kontour-surface:hosted-console",
-        "surface": "surface.roadmap",
+        "facet": "surface.roadmap",
         "claimType": "roadmap-capability",
         "fieldOrBehavior": "implementationStatus",
         "value": "planned",

package/conformance/sf-revoked-event.json

@@ -1,14 +1,14 @@
 {
   "now": "2026-06-10T00:00:00.000Z",
   "input": {
-    "schemaVersion": 4,
+    "schemaVersion": 5,
     "source": "spec-conformance:revoked-event",
     "claims": [
       {
         "id": "claim.access.grant",
         "subjectType": "credential",
         "subjectId": "access:deploy-key-7",
-        "surface": "access-control.grants",
+        "facet": "access-control.grants",
         "claimType": "software-evidence",
         "fieldOrBehavior": "deployKeyValid",
         "value": true,

package/conformance/sf-stale-duration.json

@@ -1,14 +1,14 @@
 {
   "now": "2026-06-10T00:00:00.000Z",
   "input": {
-    "schemaVersion": 3,
+    "schemaVersion": 5,
     "source": "spec-conformance:stale-duration",
     "claims": [
       {
         "id": "claim.public.field",
         "subjectType": "data-field",
         "subjectId": "dataset:registration-status",
-        "surface": "public-data.status",
+        "facet": "public-data.status",
         "claimType": "public-data-field",
         "fieldOrBehavior": "registrationStatus",
         "value": "OPEN",

package/conformance/sf-verified-commit.json

@@ -1,14 +1,14 @@
 {
   "now": "2026-06-10T00:00:00.000Z",
   "input": {
-    "schemaVersion": 3,
+    "schemaVersion": 5,
     "source": "spec-conformance:verified-commit",
     "claims": [
       {
         "id": "claim.api.rate-limit",
         "subjectType": "api",
         "subjectId": "public-api",
-        "surface": "api.guarantees",
+        "facet": "api.guarantees",
         "claimType": "software-evidence",
         "fieldOrBehavior": "rate limit is enforced",
         "value": "100 requests/minute",

package/merge.md

@@ -42,7 +42,7 @@ identifier for the *system* that produced the bundle, distinct from
 
 ```jsonc
 {
-  "schemaVersion": 4,
+  "schemaVersion": 5,
   "source": "producer-a:run-48213",  // unchanged: free text, may vary per run
   "producerId": "producer-a",        // OPTIONAL, new: stable across runs
   "claims": [ /* ... */ ]
@@ -114,7 +114,7 @@ for agreement/conflict comparison, §7) **if and only if:**
    is equal once (1) is applied (same `fieldOrBehavior`, same `qualifiers`
    after the existing trim/lowercase/sort normalization).
 
-**`claimType` and `surface` are explicitly excluded from the identity key —
+**`claimType` and `facet` are explicitly excluded from the identity key —
 this is a deliberate design decision, not an oversight:**
 
 - `claimType` is excluded because the canonical claim key is defined over
@@ -124,13 +124,13 @@ this is a deliberate design decision, not an oversight:**
   `claimType` taxonomies are still the same logical claim for merge
   purposes; reusing the canonical key means merge and Inquiry matching never
   diverge on this point.
-- `surface` is excluded because it is a producer-defined grouping or
+- `facet` is excluded because it is a producer-defined grouping or
   namespace for related claims, not the primary thing users evaluate. Two
-  producers will pick unrelated `surface` values for logically identical
-  claims — there is no shared `surface` vocabulary across producers;
+  producers will pick unrelated `facet` values for logically identical
+  claims — there is no shared `facet` vocabulary across producers;
   including it in the identity key would make cross-producer matches
-  essentially never fire. `surface` remains meaningful *within* one
-  producer's bundle (grouping, reporting `bySurface` counts) but plays no
+  essentially never fire. `facet` remains meaningful *within* one
+  producer's bundle (grouping, reporting `byFacet` counts) but plays no
   role in cross-producer identity.
 
 This means: **claims are never collapsed into one record by claim identity.**
@@ -386,9 +386,14 @@ claim).
 
 ## Versioning
 
-This document introduces no change to `statusFunctionVersion` (stays `"2"`)
-and no change to `schemaVersion`'s meaning (stays `4` — the new
-`TrustBundle.producerId` field is optional and ignored by the unchanged
-status-derivation fold). A bundle merged under this document and fed to the
-unchanged fold produces identical per-claim results to a bundle that was
-never merged.
+This document introduces no change to `statusFunctionVersion` (stays `"2"`).
+`schemaVersion` itself has moved since this document's `producerId` addition
+first shipped: it is now `5` (README.md's Namespace and versioning section is
+the single source of truth for the current value), reflecting the unrelated
+`surface` → `facet` rename described in §4 — not anything this document
+introduces. Nothing in this document depends on that hard break: the
+`producerId` field (§2) is optional and ignored by the unchanged
+status-derivation fold, and remains schema-valid at `schemaVersion` `5`
+exactly as it was when it shipped. A bundle merged under this document and fed
+to the unchanged fold produces identical per-claim results to a bundle that
+was never merged.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hachure",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "statusFunctionVersion": "2",
   "description": "Hachure — canonical distribution of the open trust format: normative JSON schemas, conformance test vectors, and spec constants.",
   "type": "module",

package/schemas/claim.schema.json

@@ -3,12 +3,12 @@
   "$id": "https://hachure.org/schemas/claim.schema.json",
   "title": "Hachure Claim",
   "type": "object",
-  "required": ["id", "subjectType", "subjectId", "surface", "claimType", "fieldOrBehavior", "value", "createdAt", "updatedAt"],
+  "required": ["id", "subjectType", "subjectId", "claimType", "fieldOrBehavior", "value", "createdAt", "updatedAt"],
   "properties": {
     "id": { "type": "string" },
     "subjectType": { "type": "string" },
     "subjectId": { "type": "string" },
-    "surface": { "type": "string" },
+    "facet": { "type": "string" },
     "claimType": { "type": "string" },
     "fieldOrBehavior": { "type": "string" },
     "value": {},

package/schemas/trust-bundle.schema.json

@@ -6,7 +6,7 @@
   "additionalProperties": false,
   "required": ["schemaVersion", "source", "claims", "evidence", "policies", "events"],
   "properties": {
-    "schemaVersion": { "enum": [2, 3, 4] },
+    "schemaVersion": { "enum": [5] },
     "source": { "type": "string" },
     "producerId": {
       "type": "string",

package/schemas/trust-report.schema.json

@@ -23,7 +23,7 @@
     "statusFunctionVersion"
   ],
   "properties": {
-    "schemaVersion": { "enum": [2, 3, 4] },
+    "schemaVersion": { "enum": [5] },
     "id": { "type": "string" },
     "generatedAt": { "type": "string", "format": "date-time" },
     "source": { "type": "string" },