hachure 0.6.0 → 0.7.0

package/README.md

@@ -104,8 +104,14 @@ Plain-language definition (ADR 0002):
 > the producer played by — packed so it can cross a product boundary without the
 > receiver needing access to the producer's internals.
 
-The `source` field identifies the producer. Bundles from multiple producers can be
-merged; conflicts surface as `disputed` status (never last-write-wins).
+The `source` field identifies the producer (free-text, may vary per run); an optional
+`producerId` field carries a stable, unsigned identifier for the producing system,
+consistent across every bundle it emits. When present, `producerId` MUST be a
+non-empty string. Bundles from multiple producers can be merged
+into one ledger without last-write-wins and without deleting losing evidence; conflicts
+between claims are surfaced as `contradiction` transparency gaps, never silently
+resolved or used to flip a claim's status. The full specification of identifier
+conventions and the merge algorithm is in [merge.md](merge.md).
 
 An optional `identityLinks` array declares co-referent subjects — real-world entities
 known under more than one identifier.  Each link carries a stable optional `id`, a

package/conformance/README.md

@@ -32,3 +32,39 @@ implementation derives the expected statuses.
   }
 }
 ```
+
+## Merge conformance vectors
+
+`conformance/merge/` contains a second, distinct family of vectors that make
+the [Identifier & Multi-Producer Merge Semantics specification](../merge.md)
+executable. Each vector merges two or more input `TrustBundle`s and asserts
+the merged claim-id set, any id collisions, and the per-claim status derived
+independently on the merged bundle. This repo's `npm test` (`test/merge.test.mjs`)
+validates vector *shape* and Ajv-validates every `inputs[]` entry against
+`trust-bundle.schema.json`; it does not execute `mergeBundles`/
+`mergeBundlesDetailed`/`deriveClaimStatus` (this repo carries no
+`@kontourai/surface` dependency) — see `merge.md`'s "Reference implementation
+notes" for the implementation-side conformance loop.
+
+### Merge test vector inventory
+
+| File | Scenario | Now |
+|---|---|---|
+| `merge-agree-values.json` | Two producers' claims agree on the same canonical subject+field; both retained as distinct records, both derive their own status independently | 2026-06-10T00:00:00.000Z |
+| `merge-conflict-value.json` | Two producers' claims disagree on value, governed by a shared `incompatibleValues` policy; both retained, statuses computed independently | 2026-06-10T00:00:00.000Z |
+| `merge-conflict-status.json` | Producer A's claim reaches `disputed` via its own blocking evidence; producer B's claim independently reaches `verified` — merge does not let one overwrite or suppress the other | 2026-06-10T00:00:00.000Z |
+| `merge-collision-order-independence.json` | Three bundles; one `Claim.id` shared by two with genuinely different content (accidental collision) plus one unrelated bundle; asserts the merge result (kept content + collisions) is identical for every permutation of `inputs` | 2026-06-10T00:00:00.000Z |
+
+### Merge test vector format
+
+```json
+{
+  "now": "<ISO 8601 string>",
+  "inputs": [ /* TrustBundle, TrustBundle, ... */ ],
+  "expect": {
+    "mergedClaimIds": ["<id>", "..."],
+    "collisions": [{ "collection": "claims", "id": "<id>" }],
+    "statusByClaimId": { "<claimId>": "<TrustStatus>" }
+  }
+}
+```

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

@@ -0,0 +1,59 @@
+{
+  "$comment": "Hand-derivation (merge.md §4/§5/§7a; status-function.md Step 6). Bundle A (producer-a) and Bundle B (producer-b) each carry one claim with the same subjectType/subjectId ('repo'/'repo-1') and the same fieldOrBehavior ('coverage'), no qualifiers on either side -> canonicalClaimKey equal (§4) -> same logical claim. Values are deep-equal (91 === 91) -> agreement (§7a): both claims MUST be retained as distinct records (never collapsed), so mergedClaimIds contains both distinct ids. Neither claims/evidence/policies/events share an id across the two bundles, so collisions is empty. Per-claim status: neither bundle attaches any policy or evidence/events for its claim, so status-function.md Step 6 ('No policy') applies for both -> policy is undefined and evidence.length === 0 -> 'unknown' for both, independently of one another and of the agreement itself (merge does not synthesize a stronger status from agreement, §7a).",
+  "now": "2026-06-10T00:00:00.000Z",
+  "inputs": [
+    {
+      "schemaVersion": 4,
+      "source": "producer-a:run-1",
+      "producerId": "producer-a",
+      "claims": [
+        {
+          "id": "producer-a.claim.readiness.coverage",
+          "subjectType": "repo",
+          "subjectId": "repo-1",
+          "surface": "readiness",
+          "claimType": "coverage",
+          "fieldOrBehavior": "coverage",
+          "value": 91,
+          "createdAt": "2026-06-01T00:00:00.000Z",
+          "updatedAt": "2026-06-01T00:00:00.000Z"
+        }
+      ],
+      "evidence": [],
+      "policies": [],
+      "events": []
+    },
+    {
+      "schemaVersion": 4,
+      "source": "producer-b:run-7",
+      "producerId": "producer-b",
+      "claims": [
+        {
+          "id": "producer-b.claim.readiness.coverage",
+          "subjectType": "repo",
+          "subjectId": "repo-1",
+          "surface": "readiness",
+          "claimType": "coverage",
+          "fieldOrBehavior": "coverage",
+          "value": 91,
+          "createdAt": "2026-06-02T00:00:00.000Z",
+          "updatedAt": "2026-06-02T00:00:00.000Z"
+        }
+      ],
+      "evidence": [],
+      "policies": [],
+      "events": []
+    }
+  ],
+  "expect": {
+    "mergedClaimIds": [
+      "producer-a.claim.readiness.coverage",
+      "producer-b.claim.readiness.coverage"
+    ],
+    "collisions": [],
+    "statusByClaimId": {
+      "producer-a.claim.readiness.coverage": "unknown",
+      "producer-b.claim.readiness.coverage": "unknown"
+    }
+  }
+}

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

@@ -0,0 +1,85 @@
+{
+  "$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'.",
+  "now": "2026-06-10T00:00:00.000Z",
+  "inputs": [
+    {
+      "schemaVersion": 4,
+      "source": "producer-a",
+      "producerId": "producer-a",
+      "claims": [
+        {
+          "id": "shared.claim.x",
+          "subjectType": "repo",
+          "subjectId": "r1",
+          "surface": "readiness",
+          "claimType": "coverage",
+          "fieldOrBehavior": "coverage",
+          "value": 91,
+          "createdAt": "2026-06-01T00:00:00.000Z",
+          "updatedAt": "2026-06-01T00:00:00.000Z"
+        }
+      ],
+      "evidence": [],
+      "policies": [],
+      "events": []
+    },
+    {
+      "schemaVersion": 4,
+      "source": "producer-b",
+      "producerId": "producer-b",
+      "claims": [
+        {
+          "id": "shared.claim.x",
+          "subjectType": "repo",
+          "subjectId": "r2",
+          "surface": "governance",
+          "claimType": "policy-check",
+          "fieldOrBehavior": "signed-off",
+          "value": true,
+          "createdAt": "2026-06-01T00:00:00.000Z",
+          "updatedAt": "2026-06-01T00:00:00.000Z"
+        }
+      ],
+      "evidence": [],
+      "policies": [],
+      "events": []
+    },
+    {
+      "schemaVersion": 4,
+      "source": "producer-c",
+      "producerId": "producer-c",
+      "claims": [
+        {
+          "id": "unrelated.claim.y",
+          "subjectType": "gate",
+          "subjectId": "g1",
+          "surface": "gates",
+          "claimType": "gate-status",
+          "fieldOrBehavior": "passed",
+          "value": true,
+          "createdAt": "2026-06-01T00:00:00.000Z",
+          "updatedAt": "2026-06-01T00:00:00.000Z"
+        }
+      ],
+      "evidence": [],
+      "policies": [],
+      "events": []
+    }
+  ],
+  "expect": {
+    "mergedClaimIds": [
+      "shared.claim.x",
+      "unrelated.claim.y"
+    ],
+    "collisions": [
+      {
+        "collection": "claims",
+        "id": "shared.claim.x"
+      }
+    ],
+    "statusByClaimId": {
+      "shared.claim.x": "unknown",
+      "unrelated.claim.y": "unknown"
+    }
+  }
+}

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

@@ -0,0 +1,149 @@
+{
+  "$comment": "Hand-derivation (merge.md §7c; status-function.md Steps 1-4). Both claims share subjectType/subjectId ('resource'/'svc-1') and fieldOrBehavior ('granted') -> same canonical claim (§4). Both bundles carry the identical policy 'policy.access-check.basic' (byte-identical in both -> unioning it is not a collision), which additionally declares incompatibleStatuses covering ['verified','disputed'] purely as an illustration that this does NOT by itself flip either claim's status (§7c) -- neither this vector's expect block nor status-function.md's fold reads incompatibleStatuses at all; it only affects the report layer, out of scope here (§9). No ids collide across the two bundles -> collisions is empty. Fold for producer-a's claim: latestEvent is 'producer-a.event.access.verified' (status 'verified', not terminal, skip Steps 2-3) -> Step 4 applies. 4a: claim has no expiresAt/ttlSeconds, policy validityRule.kind='duration', durationDays=30, verifiedAt=2026-06-01T00:00:00Z, now=2026-06-10T00:00:00Z -> 9 days elapsed < 30 -> not stale. 4b: entailing evidence (supportStrength defaults to 'entails' on both evidence items) = [producer-a.evidence.access.pass, producer-a.evidence.access.fail]; their evidenceType set {source_excerpt} and method set {observation} both satisfy policy.requiredEvidence=['source_excerpt']/requiredMethods=['observation']; requiresCorroboration=false -> no gap. 4c: 'producer-a.evidence.access.fail' has passing=false and blocking=true, observedAt=2026-06-05 (after the verified event) -> blocking failure found -> return 'disputed'. Fold for producer-b's claim: latestEvent is 'producer-b.event.access.verified' (status 'verified') -> Step 4. 4a: verifiedAt=2026-06-02T00:00:00Z, now=2026-06-10T00:00:00Z -> 8 days < 30 -> not stale. 4b: entailing evidence = [producer-b.evidence.access.pass], evidenceType {source_excerpt}, method {observation} -> satisfies policy -> no gap. 4c: the one evidence item has no 'passing:false' entry (passing is absent) -> no blocking failure -> 4d: return 'verified'. This demonstrates merge does not let producer-b's 'verified' overwrite or suppress producer-a's independently-derived 'disputed', and vice versa.",
+  "now": "2026-06-10T00:00:00.000Z",
+  "inputs": [
+    {
+      "schemaVersion": 4,
+      "source": "producer-a:run-3",
+      "producerId": "producer-a",
+      "claims": [
+        {
+          "id": "producer-a.claim.access.grant",
+          "subjectType": "resource",
+          "subjectId": "svc-1",
+          "surface": "access",
+          "claimType": "access-check",
+          "fieldOrBehavior": "granted",
+          "value": true,
+          "createdAt": "2026-06-01T00:00:00.000Z",
+          "updatedAt": "2026-06-01T00:00:00.000Z"
+        }
+      ],
+      "evidence": [
+        {
+          "id": "producer-a.evidence.access.pass",
+          "claimId": "producer-a.claim.access.grant",
+          "evidenceType": "source_excerpt",
+          "method": "observation",
+          "sourceRef": "source A: access log",
+          "excerptOrSummary": "Access granted.",
+          "observedAt": "2026-06-01T00:00:00.000Z",
+          "collectedBy": "agent-a"
+        },
+        {
+          "id": "producer-a.evidence.access.fail",
+          "claimId": "producer-a.claim.access.grant",
+          "evidenceType": "source_excerpt",
+          "method": "observation",
+          "sourceRef": "source A2: revocation log",
+          "excerptOrSummary": "Access revocation observed after original grant.",
+          "observedAt": "2026-06-05T00:00:00.000Z",
+          "collectedBy": "agent-a",
+          "passing": false,
+          "blocking": true
+        }
+      ],
+      "policies": [
+        {
+          "id": "policy.access-check.basic",
+          "claimType": "access-check",
+          "requiredEvidence": ["source_excerpt"],
+          "requiredMethods": ["observation"],
+          "requiresCorroboration": false,
+          "acceptanceCriteria": ["access confirmed from source"],
+          "reviewAuthority": "operator",
+          "validityRule": { "kind": "duration", "durationDays": 30 },
+          "stalenessTriggers": [],
+          "conflictRules": [],
+          "impactLevel": "medium",
+          "incompatibleStatuses": [
+            { "statuses": ["verified", "disputed"], "message": "conflicting access status across producers" }
+          ]
+        }
+      ],
+      "events": [
+        {
+          "id": "producer-a.event.access.verified",
+          "claimId": "producer-a.claim.access.grant",
+          "status": "verified",
+          "actor": "operator-a",
+          "method": "attestation",
+          "evidenceIds": ["producer-a.evidence.access.pass"],
+          "createdAt": "2026-06-01T00:00:00.000Z",
+          "verifiedAt": "2026-06-01T00:00:00.000Z"
+        }
+      ]
+    },
+    {
+      "schemaVersion": 4,
+      "source": "producer-b:run-4",
+      "producerId": "producer-b",
+      "claims": [
+        {
+          "id": "producer-b.claim.access.grant",
+          "subjectType": "resource",
+          "subjectId": "svc-1",
+          "surface": "access",
+          "claimType": "access-check",
+          "fieldOrBehavior": "granted",
+          "value": true,
+          "createdAt": "2026-06-02T00:00:00.000Z",
+          "updatedAt": "2026-06-02T00:00:00.000Z"
+        }
+      ],
+      "evidence": [
+        {
+          "id": "producer-b.evidence.access.pass",
+          "claimId": "producer-b.claim.access.grant",
+          "evidenceType": "source_excerpt",
+          "method": "observation",
+          "sourceRef": "source B: access log",
+          "excerptOrSummary": "Access granted, confirmed.",
+          "observedAt": "2026-06-02T00:00:00.000Z",
+          "collectedBy": "agent-b"
+        }
+      ],
+      "policies": [
+        {
+          "id": "policy.access-check.basic",
+          "claimType": "access-check",
+          "requiredEvidence": ["source_excerpt"],
+          "requiredMethods": ["observation"],
+          "requiresCorroboration": false,
+          "acceptanceCriteria": ["access confirmed from source"],
+          "reviewAuthority": "operator",
+          "validityRule": { "kind": "duration", "durationDays": 30 },
+          "stalenessTriggers": [],
+          "conflictRules": [],
+          "impactLevel": "medium",
+          "incompatibleStatuses": [
+            { "statuses": ["verified", "disputed"], "message": "conflicting access status across producers" }
+          ]
+        }
+      ],
+      "events": [
+        {
+          "id": "producer-b.event.access.verified",
+          "claimId": "producer-b.claim.access.grant",
+          "status": "verified",
+          "actor": "operator-b",
+          "method": "attestation",
+          "evidenceIds": ["producer-b.evidence.access.pass"],
+          "createdAt": "2026-06-02T00:00:00.000Z",
+          "verifiedAt": "2026-06-02T00:00:00.000Z"
+        }
+      ]
+    }
+  ],
+  "expect": {
+    "mergedClaimIds": [
+      "producer-a.claim.access.grant",
+      "producer-b.claim.access.grant"
+    ],
+    "collisions": [],
+    "statusByClaimId": {
+      "producer-a.claim.access.grant": "disputed",
+      "producer-b.claim.access.grant": "verified"
+    }
+  }
+}

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

@@ -0,0 +1,100 @@
+{
+  "$comment": "Hand-derivation (merge.md §4/§5/§7b; status-function.md Step 7). Both claims share subjectType/subjectId ('repo'/'repo-2') and fieldOrBehavior ('tier'), no qualifiers -> same canonical claim key (§4). Values 'gold' (producer-a) and 'silver' (producer-b) are not deep-equal, and both bundles reference the identical policy 'policy.pricing-field.tier-conflict', which declares incompatibleValues covering ['gold','silver'] -> this is a value conflict (§7b): both claims MUST be retained (mergedClaimIds has both distinct ids); the conflict itself surfaces only as a report-layer contradiction transparency gap, which is out of this vector format's scope (merge.md §9) and does NOT affect either claim's own status computation. The policy object is byte-identical in both bundles under the same id, so unioning it is not a collision (merge.md §5 rule 2) -> collisions is empty. Status-function.md fold, per claim: no verification event in either bundle (skip Steps 1-5); a policy IS resolved (claimType 'pricing-field' matches) so Step 6 ('no policy') does not apply; Step 7 applies ('policy present, no verification event'): producer-a's claim has one entailing evidence item with evidenceType 'source_excerpt', so its evidence-type set is {source_excerpt}, which is a superset of policy.requiredEvidence=['source_excerpt'] -> 'proposed'. producer-b's claim has no evidence at all, so its evidence-type set is {} which does NOT contain 'source_excerpt' -> 'unknown'. The two claims resolve to different statuses purely from their own attached evidence, independent of the value conflict between them.",
+  "now": "2026-06-10T00:00:00.000Z",
+  "inputs": [
+    {
+      "schemaVersion": 4,
+      "source": "producer-a:run-2",
+      "producerId": "producer-a",
+      "claims": [
+        {
+          "id": "producer-a.claim.pricing.tier",
+          "subjectType": "repo",
+          "subjectId": "repo-2",
+          "surface": "pricing",
+          "claimType": "pricing-field",
+          "fieldOrBehavior": "tier",
+          "value": "gold",
+          "createdAt": "2026-06-01T00:00:00.000Z",
+          "updatedAt": "2026-06-01T00:00:00.000Z"
+        }
+      ],
+      "evidence": [
+        {
+          "id": "producer-a.evidence.tier.source",
+          "claimId": "producer-a.claim.pricing.tier",
+          "evidenceType": "source_excerpt",
+          "method": "observation",
+          "sourceRef": "source A: internal pricing sheet",
+          "excerptOrSummary": "Tier is gold.",
+          "observedAt": "2026-06-01T00:00:00.000Z",
+          "collectedBy": "crawler-a"
+        }
+      ],
+      "policies": [
+        {
+          "id": "policy.pricing-field.tier-conflict",
+          "claimType": "pricing-field",
+          "requiredEvidence": ["source_excerpt"],
+          "acceptanceCriteria": ["tier confirmed by source"],
+          "reviewAuthority": "operator",
+          "validityRule": { "kind": "historical" },
+          "stalenessTriggers": [],
+          "conflictRules": [],
+          "impactLevel": "medium",
+          "incompatibleValues": [
+            { "values": ["gold", "silver"], "message": "tier values conflict across producers" }
+          ]
+        }
+      ],
+      "events": []
+    },
+    {
+      "schemaVersion": 4,
+      "source": "producer-b:run-9",
+      "producerId": "producer-b",
+      "claims": [
+        {
+          "id": "producer-b.claim.pricing.tier",
+          "subjectType": "repo",
+          "subjectId": "repo-2",
+          "surface": "pricing",
+          "claimType": "pricing-field",
+          "fieldOrBehavior": "tier",
+          "value": "silver",
+          "createdAt": "2026-06-02T00:00:00.000Z",
+          "updatedAt": "2026-06-02T00:00:00.000Z"
+        }
+      ],
+      "evidence": [],
+      "policies": [
+        {
+          "id": "policy.pricing-field.tier-conflict",
+          "claimType": "pricing-field",
+          "requiredEvidence": ["source_excerpt"],
+          "acceptanceCriteria": ["tier confirmed by source"],
+          "reviewAuthority": "operator",
+          "validityRule": { "kind": "historical" },
+          "stalenessTriggers": [],
+          "conflictRules": [],
+          "impactLevel": "medium",
+          "incompatibleValues": [
+            { "values": ["gold", "silver"], "message": "tier values conflict across producers" }
+          ]
+        }
+      ],
+      "events": []
+    }
+  ],
+  "expect": {
+    "mergedClaimIds": [
+      "producer-a.claim.pricing.tier",
+      "producer-b.claim.pricing.tier"
+    ],
+    "collisions": [],
+    "statusByClaimId": {
+      "producer-a.claim.pricing.tier": "proposed",
+      "producer-b.claim.pricing.tier": "unknown"
+    }
+  }
+}

package/merge.md

@@ -0,0 +1,364 @@
+# Identifier & Multi-Producer Merge Semantics — Specification
+
+**Function:** `mergeBundles(bundles: TrustBundle[]) → TrustBundle` /
+`mergeBundlesDetailed(bundles: TrustBundle[]) → { bundle: TrustBundle; collisions: MergeCollision[] }`
+**Source of truth:** `src/merge.ts`, `src/identity.ts`, `src/canonical.ts` in `@kontourai/surface`
+
+---
+
+## 1. Principle
+
+A Trust Bundle (README §"TrustBundle") is the supply side of the ledger, from
+a single producer (ADR 0002). Multiple producers' bundles about overlapping
+subjects MUST be combinable into one ledger without:
+
+- silently overwriting one producer's claim with another's (never
+  last-write-wins),
+- deleting losing evidence,
+- requiring a shared identifier authority, key infrastructure, or
+  pre-registration between producers.
+
+This document specifies: how a claim's identity is compared across producers
+(§4), how bundles fold into one ledger (§5), the determinism guarantee that
+folding MUST satisfy (§6), how agreement/conflict/dispute are represented
+(§7), and how accidental id collisions between *unrelated* records are
+detected (§8).
+
+---
+
+## 2. Producer identity
+
+`TrustBundle.source` (`schemas/trust-bundle.schema.json`) is a free-text
+string. Real producers use it inconsistently as a human-readable label, a
+run-scoped value, or both (e.g. `source: 'producer-b:${run_id}'`,
+`source: 'session-log'`, `source: 'filesystem-inferred'`). `source`
+alone is not a stable, comparable producer identity — it changes per
+run/session for the same producer.
+
+`TrustBundle` carries one OPTIONAL field, `producerId` (string), a stable
+identifier for the *system* that produced the bundle, distinct from
+`source`'s run-scoped free text:
+
+```jsonc
+{
+  "schemaVersion": 4,
+  "source": "producer-a:run-48213",  // unchanged: free text, may vary per run
+  "producerId": "producer-a",        // OPTIONAL, new: stable across runs
+  "claims": [ /* ... */ ]
+}
+```
+
+Rules:
+
+- `producerId` is OPTIONAL. A bundle without it is exactly as valid as a
+  bundle that predates this field (additive; `trust-bundle.schema.json`'s
+  `required` array is unchanged).
+- When present, `producerId` MUST be a non-empty string
+  (`trust-bundle.schema.json`'s `producerId` property carries `minLength: 1`)
+  — an empty string carries no identifying information, so it is
+  schema-invalid rather than treated as equivalent to omitting the field.
+- When present, `producerId` SHOULD be stable across every bundle the same
+  system emits, and SHOULD be used (§3) as the leading segment of that
+  producer's record ids.
+- `producerId` carries no cryptographic weight. It is an L0
+  (producer-asserted) fact in Assurance-profile terms (`assurance.md`).
+  Producers wanting a verifiable producer identity SHOULD present that
+  identity via the existing Assurance L1 (OIDC-backed) or L2 (held-key)
+  presentation (`assurance.md` §"Identity presentation"). This document does
+  not define, and MUST NOT be read to require, any DID or key-resolution
+  mechanism. Cryptographic identity is Assurance-profile territory;
+  `producerId` is the plain, unsigned, always-available floor underneath it.
+- On merge (§5), a merged bundle represents more than one producer, so a
+  merged bundle's `producerId` MUST be omitted — it MUST NOT be synthesized
+  the way `source` is (`source` becomes `merged:<a>+<b>`; `producerId` has no
+  analogous synthesized form). Per-record producer attribution across a merge
+  is best-effort via the id convention in §3, not a schema-enforced field on
+  every record; `Claim`, `Evidence`, `VerificationPolicy`, and
+  `VerificationEvent` do not each carry their own `producerId` — the
+  bundle-level field plus the id convention is the complete mechanism.
+
+---
+
+## 3. Identifier format
+
+`id` fields (`Claim.id`, `Evidence.id`, `VerificationPolicy.id`,
+`VerificationEvent.id`, etc.) remain `{ "type": "string" }` with no `pattern`
+constraint. This document introduces no schema change to any `id` field.
+
+- Producers SHOULD mint ids as dot-separated, lowercase, URL-safe segments
+  (a stable helper that lowercases, collapses non-alphanumeric runs to `-`,
+  and joins segments with `.` is the recommended shape).
+- Producers that set `producerId` (§2) SHOULD make the id's leading segment
+  equal to `producerId` (or a short slug derived from it), e.g.
+  `producerId: "producer-a"` → ids like `producer-a.recommendation.upgrade-node`.
+- This is a SHOULD, not a MUST, and is never schema-enforced. A conforming
+  bundle with un-prefixed ids remains fully conformant.
+- Rationale for SHOULD over MUST: enforcing a producer prefix would need a
+  `pattern` regex, which cannot be written today without either rejecting
+  real existing ids or being so permissive it adds no safety. The prefix
+  convention earns its value from making *accidental* id collisions between
+  unrelated producers vanishingly unlikely (§8), not from schema enforcement.
+
+---
+
+## 4. Claim identity across producers
+
+Two claims from different producers are the same logical claim (candidates
+for agreement/conflict comparison, §7) **if and only if:**
+
+1. Their subjects resolve to the same canonical key under the merged bundle's
+   identity index (`IdentityIndex.canonicalKeyForClaim`) — i.e. same subject,
+   or subjects declared co-referent via `identityLinks`/`subjectAliases`.
+2. `canonicalClaimKey({ subjectType, subjectId, fieldOrBehavior, qualifiers })`
+   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 —
+this is a deliberate design decision, not an oversight:**
+
+- `claimType` is excluded because the canonical claim key is defined over
+  *subject, predicate, value, qualifiers* — `fieldOrBehavior` is the
+  predicate; `claimType` is a taxonomy tag, not part of the matching grammar.
+  Two producers describing the same subject+field under different
+  `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
+  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;
+  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
+  role in cross-producer identity.
+
+This means: **claims are never collapsed into one record by claim identity.**
+Two producers' claims about the same canonical subject+field, even when they
+fully agree, remain two distinct `Claim` records with two distinct ids in the
+merged bundle (§5 unions by `id`, not by claim identity) — claim identity is
+used only to decide *how to interpret* the pair (§7), never to deduplicate
+them into one.
+
+---
+
+## 5. The merge algorithm
+
+Given `bundles: TrustBundle[]` (all sharing one `schemaVersion` —
+implementations MUST reject a merge across differing `schemaVersion` values
+rather than guessing a coercion):
+
+1. **Union every collection by `id`**: `claims`, `evidence`, `policies`,
+   `events` (each item has a required `id`); `claimGroups`, `authorityTrace`
+   (each item has an optional `id`; items without an `id` are always kept,
+   never deduped). `identityLinks` are concatenated in full (they may omit
+   `id`; a union-find-based identity index dedupes them harmlessly even when
+   duplicated).
+2. **First-occurrence wins content, subject to the determinism rule in §6** —
+   when two records share an `id`:
+   - If their content is structurally identical (deep-equal), keep it; this
+     is not a collision (the same fact was reported by two bundles, e.g.
+     after a re-export round-trip).
+   - If their content differs, this is a **collision** (§8): the
+     implementation MUST record it (`MergeCollision`: `collection`, `id`, and
+     enough information to identify the contributing bundles) rather than
+     silently picking one. The throwing entry point (`mergeBundles`) MUST
+     throw when any **claim** collision (differing content, same `Claim.id`)
+     is detected — silent claim corruption is the one thing merge MUST NOT
+     ever do. The non-throwing entry point (`mergeBundlesDetailed`) MUST
+     return the collisions for the caller to inspect/reconcile instead of
+     throwing.
+3. **`source` becomes a synthesized combination** of the distinct `source`
+   values across the merged bundles (`merged:<a>+<b>`); **`producerId` MUST
+   be omitted** on a merged bundle (§2).
+4. The merged bundle is not itself a new producer assertion — it MUST be
+   accepted as input to the same, unmodified status derivation
+   (`status-function.md`) and to the merge function again (merge MUST be
+   re-appliable to an already-merged bundle, since a bundle is a bundle
+   regardless of how many producers contributed to it — no special "already
+   merged" flag is introduced).
+
+---
+
+## 6. Determinism (order independence)
+
+**MUST:** for any fixed *set* of input bundles, the merge function's output
+(both the retained record content and the `collisions[]` set, modulo list
+ordering) MUST be identical regardless of the order the bundles are supplied
+in. `merge([A, B, C])`, `merge([C, A, B])`, and every other permutation of the
+same set MUST produce the same merged bundle.
+
+**Normative tie-break rule:** when N ≥ 2 records share an id and are not all
+content-identical, an implementation MUST:
+
+1. Compare **every** colliding record's content against every other's (not
+   just against the first-seen one), and report a collision for every
+   distinct-content pair.
+2. Choose the *kept* record deterministically from content alone — not from
+   array position — using the record whose RFC 8785 (JSON Canonicalization
+   Scheme) serialization sorts lexicographically first among the distinct
+   contents. (RFC 8785/JCS is the target canonicalization primitive; until it
+   is adopted bundle-wide, an implementation MAY substitute `JSON.stringify`
+   of each object with its keys sorted recursively, which is
+   order-independent for this purpose even though it is not RFC 8785-compliant
+   in general — this rule asks for convergence-under-permutation of *this*
+   function, not full JCS compliance.)
+
+This makes the merged bundle a pure, order-independent function of the *set*
+of input bundles — the same guarantee `status-function.md` already gives for
+`now`-parameterized status derivation, extended to the merge step that
+precedes it.
+
+---
+
+## 7. Agreement, conflict, and dispute mechanics
+
+Given two claims that are the same logical claim under §4:
+
+### 7a. Agreement
+
+If `deepEqual(a.value, b.value)`: the claims agree. They MUST NOT be
+collapsed into one record (§4). Agreement is informational at the merge
+layer; agreement alone does not synthesize a stronger status. A consumer that
+wants "N producers agree" as an input to a decision already has the tool for
+it without a new mechanism: an authored `DerivationRule` (ADR 0003 §5,
+`derivation-rule.schema.json`) can require `acceptedStatuses` across both
+claim ids explicitly. This document does not add corroboration-across-producers
+as an automatic status input.
+
+### 7b. Value conflict
+
+If the claims are governed by a `VerificationPolicy` with `incompatibleValues`
+covering the pair (`verification-policy.schema.json`) and the values match an
+`incompatibleValues` pair: **both claims MUST be retained** (never
+last-write-wins) and the conflict is surfaced as a `contradiction`
+transparency gap. This document does not add a normative JSON Schema for
+`TransparencyGap` — that remains explicitly out of scope
+(`schemas/trust-report.schema.json`'s own `$comment` already documents this;
+see §9). The merge-layer guarantee this document DOES make is
+schema-checkable without a `TransparencyGap` schema: neither claim is
+dropped, mutated, or status-overridden by the presence of the other (§5 rule
+2).
+
+### 7c. Status conflict
+
+A cross-producer `incompatibleStatuses` policy match (like a value conflict,
+§7b) produces a `contradiction` transparency gap. It does not, by itself,
+flip either claim's `status`.
+
+A claim's `status` becomes `disputed` **only** through the existing,
+single-claim mechanisms already in `status-function.md`: blocking
+non-passing evidence (Step 4c), a terminal event with `status: "disputed"`
+(Step 2), or an authority-gated resolution that is itself overridden by newer
+blocking evidence (Step 1). Nothing in the cross-producer conflict path sets
+a claim's status to `disputed`; `TrustReport.summary.disputedClaims` is
+populated purely by scanning `claim.status === "disputed"` from each claim's
+own single-claim fold output.
+
+### 7d. Dispute resolution — no new record type
+
+When a human/authority needs to resolve a `disputed` status (from 7c's
+existing mechanisms), the spec already has the shape (ADR 0003 §8): a
+`VerificationEvent` with `resolvesDispute: true` and an optional
+`authorityRef`, gated by an active `AuthorityTrace` at decision time
+(`status-function.md` Step 1). This document does not introduce a new
+"Dispute" resource. Reusing `VerificationEvent` + `AuthorityTrace` means a
+cross-producer dispute is resolved exactly the same way a single-producer one
+is — the resolving event just needs `claimId` pointed at whichever specific
+claim the authority is ruling on (the fold is per-claim; resolving "the
+subject+field disagreement" in general means issuing a resolution event on
+each affected claim id, or issuing one and letting a `DerivationRule` compose
+the pair — no new bulk-resolution primitive is added by this document).
+
+---
+
+## 8. Id collision handling for records that are NOT the same logical claim
+
+This is the case where two producers, without coordinating, mint the
+identical `id` string for two *unrelated* records (accidental collision —
+distinct from §4's "same logical claim, different ids" case, and distinct
+from §7's value/status conflict between claims that *are* the same logical
+claim).
+
+- **Detection:** compare content; identical content is not a problem
+  (idempotent re-merge); differing content under the same id is a collision
+  that MUST be surfaced (`mergeBundles` throws for claims;
+  `mergeBundlesDetailed` reports for every collection).
+- **Mitigation is the id convention (§3), not a new mechanism.** A collision
+  between two truly unrelated records is only possible if both producers
+  independently chose the same opaque string. The producer-prefixed dotted
+  convention (e.g. `producer-a.recommendation.upgrade-node` vs.
+  `producer-b.candidate.upgrade-node`) makes this vanishingly unlikely
+  without any schema enforcement. This document does not add a registry,
+  reservation scheme, or uniqueness authority — that would introduce the
+  kind of cross-producer coordination infrastructure the "stand-alone,
+  vendor-neutral format" goal explicitly rules out.
+
+---
+
+## 9. Explicitly out of scope
+
+- **`TransparencyGap` / `EvidenceRequirement` normative JSON Schemas.**
+  Referenced descriptively in §7b/§7c (the `contradiction` gap type already
+  exists informally, per `schemas/trust-report.schema.json`'s own
+  `$comment`), but this document does not add a schema for them.
+- **RFC 8785 canonicalization as a general bundle-hashing primitive.** §6
+  depends on *a* canonicalization function existing for its tie-break rule
+  and names RFC 8785 (JCS) as the target, with a documented interim fallback
+  (sorted-key `JSON.stringify`) — it does not itself specify RFC 8785
+  adoption bundle-wide.
+- **Cryptographic producer identity (DIDs, keys, transparency-log-anchored
+  identity).** `producerId` (§2) is deliberately unsigned and unverified.
+  Where verifiable producer identity is needed, use Assurance L1/L2
+  (`assurance.md`) — this document adds no new identity/signing mechanism.
+- **Survey chains, Veritas standards, Flow gates** — unchanged; still
+  extension-profile territory per README's existing "Out of scope" section.
+
+---
+
+## Prior art
+
+- **W3C Verifiable Credentials.** VC issuer identity is built on DIDs — a
+  resolvable, typically key-based identifier scheme. Requiring DIDs for
+  `producerId` would collapse the existing layered design (Assurance
+  L0/producer-asserted is the default; L1/L2 signing is opt-in) into "every
+  producer needs key infrastructure just to be namespaced for merge," a
+  strictly higher bar than merge needs. `producerId` is deliberately at the
+  same trust level as the existing `source` field (L0, free-text, unsigned).
+- **in-toto.** `interop-in-toto.md` already wraps a whole `TrustBundle` as one
+  in-toto `Statement`'s `predicate` — in-toto's subject/predicate model is
+  single-attestation by design and defines no multi-producer merge algorithm
+  at the claim level. This document is compatible with that profile
+  unchanged: merge happens on `TrustBundle`s *before* DSSE wrapping, or a
+  verifier can independently wrap several signed Statements' predicates and
+  merge them after unwrapping — either order works because merge is a pure
+  function over `TrustBundle` values, not over signed envelopes.
+
+---
+
+## Reference implementation notes (for implementers)
+
+| Normative rule (this document) | Where it lands in `@kontourai/surface` `src/` | Status |
+|---|---|---|
+| §2 `producerId` field | `src/types.ts` `TrustBundle` interface; `schemas/trust-bundle.schema.json` (this repo) | New — add optional field (not yet in the reference implementation) |
+| §3 id convention | Prose-only; no code change (SHOULD, unenforced) | N/A |
+| §4 claim identity across producers | `src/canonical.ts` `canonicalClaimKey` + `src/identity.ts` `buildIdentityIndex` | Reused unchanged |
+| §5 rule 1–2 (union by id, first-occurrence-wins-if-identical, collision on differing content) | `src/merge.ts` `unionById` / `unionOptionalById` | Implemented |
+| §5 rule 3 (`producerId` omitted on merge) | `src/merge.ts` `mergeBundlesDetailed` (the `source` synthesis block) | Implementer TODO: add omission of `producerId` |
+| §6 determinism / order-independence | `src/merge.ts` `unionById` | **Known gap**: current `unionById` only compares against the first-seen record for a given id, not every colliding record — kept-content and the collision set are both order-dependent today for 3+-way collisions on one id. Not yet true; needs an implementation fix. |
+| §6 tie-break (canonical-serialization ordering) | `src/merge.ts` `sameContent` | Implementer TODO: no multi-way tie-break exists yet, since there's no multi-way comparison yet |
+| §7b value conflict → `contradiction` gap | `src/conflict-derivation.ts` `deriveConflictTransparencyGaps` | Implemented |
+| §7c status conflict | `src/conflict-derivation.ts` (no code change needed — the code already matches this document's narrower rule) | Implemented; `docs/adr/0002-trust-bundle.md` in `@kontourai/surface` previously described a broader behavior and has a correction note |
+| §7d dispute resolution | `src/dispute.ts` `buildDisputeResolutionEvent`; `status-function.md` Step 1 | Implemented |
+| §8 collision detection | `src/merge.ts` `MergeCollision` (a TS type; not currently a normative wire schema, and stays that way per §9) | Implemented |
+| Conformance vectors | `conformance/merge/*.json` (this repo) | Vector shape/schema validated by this repo's `npm test`; algorithmic correctness is proven by an implementation actually running `mergeBundlesDetailed`/`deriveClaimStatus` against them, not by this repo alone |
+
+---
+
+## 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hachure",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "statusFunctionVersion": "2",
   "description": "Hachure — canonical distribution of the open trust format: normative JSON schemas, conformance test vectors, and spec constants.",
   "type": "module",
@@ -16,6 +16,7 @@
     "index.mjs",
     "README.md",
     "status-function.md",
+    "merge.md",
     "interop-in-toto.md",
     "verification-endpoint.md",
     "assurance.md"

package/schemas/trust-bundle.schema.json

@@ -8,6 +8,11 @@
   "properties": {
     "schemaVersion": { "enum": [2, 3, 4] },
     "source": { "type": "string" },
+    "producerId": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Optional stable identifier for the producing system, distinct from source (which is free-text and may vary per run). When present, MUST be a non-empty string (minLength: 1) -- see merge.md section 2. Omitted (never synthesized) on a merged bundle."
+    },
     "claims": {
       "type": "array",
       "items": { "$ref": "claim.schema.json" }