hachure 0.7.0 → 0.8.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kontour AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -86,6 +86,19 @@ every bundle valid at `schemaVersion` `3` remains valid; only the deriver
 
 ---
 
+## Conformance language
+
+The key words **MUST**, **MUST NOT**, **REQUIRED**, **SHALL**, **SHALL NOT**,
+**SHOULD**, **SHOULD NOT**, **RECOMMENDED**, **MAY**, and **OPTIONAL** in this
+document and in every other normative document in this repository
+(`merge.md`, `assurance.md`, `verification-endpoint.md`,
+`status-function.md`, `interop-in-toto.md`, `SECURITY.md`) are to be
+interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119)
+and clarified by [RFC 8174](https://www.rfc-editor.org/rfc/rfc8174) (BCP 14),
+only when they appear in all capitals, as shown here.
+
+---
+
 ## Scope: core record shapes
 
 This specification covers the following record types. Each is a first-class concept
@@ -260,6 +273,42 @@ a profile requires no changes to core record shapes or the status function.
 
 ---
 
+## Relationship to W3C Verifiable Credentials
+
+Hachure and the [W3C Verifiable Credentials](https://www.w3.org/TR/vc-data-model-2.0/)
+data model both represent claims-with-evidence, and it is a fair question why
+this format does not simply build on VC instead of defining its own record
+shapes.
+
+**The short answer:** DID-based issuer identity is the dominant convention
+in the VC ecosystem — a resolvable, typically key-based identifier scheme —
+though the VC data model itself permits any URL as an issuer identifier.
+Hachure treats signing as an opt-in [Assurance](assurance.md) dial (L0
+unsigned by default, L1/L2 signed on request), not a precondition for a
+record to exist.
+Requiring DIDs for `producerId` ([merge.md](merge.md) §2) would collapse that
+layered design into "every producer needs key infrastructure just to be
+namespaced for merge" — a strictly higher bar than merge, or basic claim
+authorship, actually needs. `producerId` is deliberately at the same trust
+level as the existing `source` field: free-text, unsigned, always available,
+upgradable to a cryptographically verifiable identity only when a consumer's
+policy requires it.
+
+This is not a rejection of DIDs or VCs — an implementation that wants
+DID-backed producer identity can express it today via Assurance L1/L2's OIDC-
+or held-key-backed signing (`assurance.md` §"Identity presentation"), and
+nothing here prevents a future profile from mapping Hachure records into a VC
+envelope for interop with VC-native ecosystems. It is a statement that Hachure
+does not *require* DID infrastructure just to produce a valid, useful record —
+consistent with the "signing is a dial, not a gate" principle that runs
+through the whole Assurance profile.
+
+See [merge.md](merge.md) §10 "Prior art" for the fuller technical rationale,
+and [assurance.md](assurance.md) for how signed identity is layered on top
+when a consumer needs it.
+
+---
+
 ## Out of scope: future extension profiles
 
 The following producer domains are explicitly out of scope for this core specification.
@@ -286,7 +335,28 @@ fixed `now`. The test at `tests/spec-conformance.test.ts` loads every test vecto
 asserts that the reference implementation derives the expected statuses, making this
 specification executable.
 
-See [conformance/README.md](conformance/README.md) for the test vector inventory.
+See [conformance/README.md](conformance/README.md) for the test vector inventory, and
+[conformance/manifest.json](conformance/manifest.json) (also exported as
+`conformanceManifest`) for a machine-readable index of what an implementation
+must pass to claim conformance at each level (L1 schema-valid records, L2
+status-derivation vectors, L3 merge vectors).
+
+---
+
+## Project documents
+
+- **[SECURITY.md](SECURITY.md)** — the format's honest trust boundaries:
+  source/producerId spoofing, verification-endpoint replay risk, and
+  whole-bundle substitution, and which [Assurance](assurance.md) level
+  mitigates each.
+- **[CONTRIBUTING.md](CONTRIBUTING.md)** — how to propose a change, when a
+  design writeup is expected, and the conformance-vector requirement for
+  behavior changes. *(Draft — see the banner in that file.)*
+- **[GOVERNANCE.md](GOVERNANCE.md)** — who currently has decision authority,
+  and what "neutral governance" is expected to mean when the project moves
+  toward it. Expands the "Governance intent" paragraph above; does not
+  contradict it. *(Draft — see the banner in that file.)*
+- **[LICENSE](LICENSE)** — MIT, matching `package.json`'s `"license"` field.
 
 ---
 

package/SECURITY.md

@@ -0,0 +1,180 @@
+# Security Considerations
+
+This document describes the trust boundaries of the Hachure core format and
+its optional profiles, and points at the mechanism each risk is mitigated by.
+It is a description of the format's own honest limits, not a claim that these
+risks are solved by default — most of them are solved only when a consumer
+opts into a higher [Assurance](assurance.md) level.
+
+Reporting a vulnerability in the schemas, conformance vectors, or prose in
+this repository: open an issue at
+[hachure-org/spec](https://github.com/hachure-org/spec/issues). This repo
+ships specification artifacts (JSON Schemas, test vectors, markdown), not
+runtime code; there is no server or service to report an exploit against
+here. Vulnerabilities in the reference implementation (`@kontourai/surface`)
+should be reported in that repository.
+
+---
+
+## Threat model summary
+
+The core format (schemas, `merge.md`, `status-function.md`) makes **no
+cryptographic guarantee by default.** Every TrustBundle is valid — and fully
+conformant — with zero signatures. This is a deliberate design choice
+(`assurance.md` §"Principle: signing is a dial, not a gate"), not an
+oversight, but it means a receiver's default trust posture for an unsigned
+bundle is "as trustworthy as the channel it arrived over," never higher.
+
+The three risk classes below are the direct, honest consequences of that
+default. All three share the same mitigation dial: [assurance.md](assurance.md)'s
+L0/L1/L2 levels. **Signing is opt-in, not a precondition for validity** — a
+consumer that needs a mitigation below must pull the dial itself, by
+requiring L1/L2 in its `VerificationPolicy`; the format does not do it for
+them.
+
+### 1. Source / producerId spoofing (L0)
+
+`TrustBundle.source` (`schemas/trust-bundle.schema.json`) is free text, and
+the optional `TrustBundle.producerId` (`merge.md` §2) is an unsigned string.
+Both are **self-asserted**: nothing in the core format cryptographically
+binds either field to the system that actually produced the bundle. A
+receiver of an unsigned bundle has no guarantee that the `source`/`producerId`
+values are accurate — only that they are what the sender chose to write down.
+Below Assurance L1, this is trust-on-first-use: the receiver's confidence in
+producer identity comes entirely from the trustworthiness of the transport
+channel (e.g. an authenticated HTTPS connection to a known host), not from
+anything inside the bundle itself.
+
+`producerId` was introduced (`merge.md` §2) specifically to give merge a
+stable, comparable identity across runs — it is explicitly documented there
+as carrying "no cryptographic weight," an L0 fact in Assurance-profile terms.
+Reusing it as an authorization or access-control signal without an L1/L2
+signature over it is a misuse of the field, not a supported use case.
+
+**Mitigation:** [assurance.md](assurance.md) L1 (OIDC-backed identity-signed)
+or L2 (org-held-key-signed) records bind a verifiable identity to the record
+via a DSSE envelope. A consumer that needs verified producer identity should
+require L1 or L2 in its `VerificationPolicy`'s acceptance criteria and treat
+a below-threshold bundle as a transparency gap (`assurance.md` §"Consumer
+policy"), not silently accept the self-asserted `source`/`producerId` values
+as authoritative.
+
+### 2. Replay in the verification-endpoint profile
+
+[verification-endpoint.md](verification-endpoint.md) defines a pull-based
+delta-fetch channel (`GET/POST .well-known/hachure/verify`) for a receiver to
+ask a producer "what has changed since this bundle was issued?" As of this
+writing, that profile defines no nonce, freshness token, or monotonic cursor
+in either the request or the response. A response is authenticated only by
+whatever transport-level authentication the producer chooses to require
+(profile text: "Producers MAY require authentication before serving a
+response") and, optionally, by a DSSE signature over the response bundle
+(`verification-endpoint.md` §"Assurance levels").
+
+This means: an unsigned verification-endpoint response carries no
+cryptographic freshness guarantee. A response captured and replayed later by
+a party sitting on the transport path (or by a compromised intermediate
+cache) is not distinguishable, at the profile level, from a fresh response —
+the profile's own `respondedAt` metadata field is producer-asserted, not
+verified. This is named here as an explicit, currently-unmitigated gap in the
+profile, not as a solved problem being restated: no existing
+freshness-handling language exists in `verification-endpoint.md` today, and
+this document does not silently invent one.
+
+**Mitigation:** treat every verification-endpoint response — signed or not —
+as advisory testimony, per the profile's own framing ("It is testimony with a
+timestamp... It is never a verdict the receiver is expected to obey,"
+`verification-endpoint.md` §"Problem"). Receivers that need replay resistance
+should (a) require a signed response (Assurance L1/L2) *and* (b) layer their
+own freshness handling on top — for example, rejecting a response whose
+`respondedAt` is older than a receiver-chosen staleness bound, or pinning
+expected `respondedAt` monotonicity per producer host — since the core
+profile does not provide either mechanism itself.
+
+### 3. Whole-bundle substitution
+
+A TrustBundle transmitted without a DSSE envelope (Assurance L0, the default)
+has no integrity protection against wholesale substitution in transit or at
+rest. An attacker or compromised intermediary who can replace the bytes of an
+unsigned bundle — swap it for a different bundle, an older bundle, or a
+bundle from a different producer — is undetectable by the receiver using
+only the core format's own mechanisms. Nothing in `schemas/*.schema.json` or
+`status-function.md` provides tamper-evidence; those layers assume the bytes
+they operate on are already the intended bytes.
+
+**Mitigation:** Assurance L1/L2 DSSE signing
+([interop-in-toto.md](interop-in-toto.md)) wraps the serialized bundle in a
+signed envelope; a receiver that verifies the signature before parsing the
+bundle detects substitution (the signature will not verify over substituted
+bytes). This is the same mechanism item 1's mitigation depends on — signing
+the bundle simultaneously binds its producer identity and its content
+integrity. A receiver that only checks `source`/`producerId` (item 1) without
+also verifying the envelope (item 3) has closed neither gap: an attacker who
+can substitute the bundle can substitute the self-asserted `source` field
+along with it.
+
+---
+
+## Integrity anchors and canonicalization
+
+Bundle and claim records carry optional `integrityAnchor` objects
+(`schemas/claim.schema.json` `$defs/integrityAnchor`,
+`schemas/trust-bundle.schema.json` `$defs/integrityAnchor`) with a `kind`
+enum that includes `"hash"`. When an implementation computes a `"hash"`-kind
+integrity anchor over a bundle or record — or independently verifies one — it
+**MUST** canonicalize the JSON with [RFC 8785](https://www.rfc-editor.org/rfc/rfc8785)
+(the JSON Canonicalization Scheme, JCS) before hashing. This is the same
+canonicalization primitive `merge.md` §6 now ratifies as normative for its
+deterministic tie-break rule (see `merge.md` §6/§9) — one canonicalization
+decision for the whole format, not two independently-evolving ones.
+Canonicalization MUST be RFC 8785 (JCS) — full stop, with no
+sorted-key-`JSON.stringify` shortcut carve-out. Two implementations that both
+claim RFC 8785 compliance and hash the same logical content MUST produce the
+same digest.
+
+> **Note (informative, not normative):** producing byte-identical RFC 8785
+> output across languages has real cross-language pitfalls implementers
+> should verify against, not assume away. (a) Non-ASCII string escaping —
+> RFC 8785 (via RFC 8259) requires strings to contain literal UTF-8
+> characters, never `\uXXXX` escapes, but several languages' default JSON
+> serializers `\u`-escape non-ASCII by default (e.g. Python's `json.dumps`'s
+> `ensure_ascii=True` default) and must be reconfigured to emit literal
+> UTF-8. (b) Number serialization MUST follow the ECMAScript
+> `Number::toString` algorithm (RFC 8785 §3.2.2.3) — native to JavaScript
+> engines, but other languages need a compliant implementation of that exact
+> algorithm, not their own default float-to-string routine. (c) Property
+> sort order is by UTF-16 code unit value (RFC 8785 §3.2.3), not codepoint,
+> byte, or locale-collation order. RFC 8785 §3.1 also does not apply Unicode
+> normalization — strings are canonicalized exactly as they already are in
+> memory, so two visually-identical strings that differ only in Unicode
+> normalization form produce different canonical bytes. A hand-rolled
+> sorted-key `JSON.stringify` can silently diverge from RFC 8785 on any of
+> these points; there is no shortcut that is safe to assume equivalent
+> without verifying against a conformant JCS implementation.
+
+An integrity anchor is only as trustworthy as the channel it arrived over
+unless it is itself covered by an Assurance L1/L2 signature (item 3 above) —
+a `"hash"` anchor on an otherwise-unsigned L0 bundle is a self-asserted
+checksum, useful for detecting accidental corruption, not for detecting a
+deliberate adversary who can also recompute the hash over substituted
+content.
+
+---
+
+## Summary: the mitigation is one dial, not three
+
+All three risk classes above, and the integrity-anchor guidance, resolve to
+the same answer: **[assurance.md](assurance.md)'s L0/L1/L2 levels are the
+dial a consumer pulls when any of this matters.** L0 (the default, unsigned)
+carries none of these guarantees and is not pretending to. L1/L2 (DSSE
+signing, per [interop-in-toto.md](interop-in-toto.md)) closes the producer-identity
+and bundle-substitution gaps together, because they are the same mechanism.
+The verification-endpoint replay gap additionally needs receiver-side
+freshness handling that the format does not currently specify — named here
+explicitly rather than left implicit.
+
+A consumer that needs any of these properties expresses that need as a
+`VerificationPolicy` acceptance criterion requiring a minimum assurance
+level; a bundle that falls short is a transparency gap for a human or policy
+layer to act on (`assurance.md` §"Consumer policy"), never a silent
+downgrade.

package/assurance.md

@@ -4,6 +4,7 @@
 **Status:** draft
 **Namespace:** `hachure.org/v1`
 **Depends on:** core record shapes, [interop-in-toto.md](interop-in-toto.md), [verification-endpoint.md](verification-endpoint.md)
+**Conformance language:** MUST/SHOULD/MAY keywords in this document are to be interpreted per RFC 2119/BCP 14, as defined in [README.md's Conformance language section](README.md#conformance-language).
 
 ---
 

package/conformance/README.md

@@ -3,6 +3,18 @@
 This directory contains input bundles and expected per-claim statuses that make
 the [Status Derivation specification](../status-function.md) executable.
 
+**Machine-readable conformance manifest:** [`manifest.json`](manifest.json)
+(also exported as `conformanceManifest` from the package root) is a
+structured index of what an implementation must pass to claim conformance at
+each level (L1 schema-valid records, L2 status-derivation vectors, L3 merge
+vectors) — distinct from, and more structured than, the raw vector inventory
+below. Read it, or run:
+
+```js
+import { conformanceManifest } from 'hachure';
+console.log(conformanceManifest.levels);
+```
+
 Each test vector is a JSON file with an `input` (a valid TrustBundle) and an `expect`
 object listing expected per-claim statuses at a fixed `now` timestamp. The test at
 `tests/spec-conformance.test.ts` loads every test vector and asserts that the reference

package/conformance/manifest.json

@@ -0,0 +1,71 @@
+{
+  "$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],
+    "statusFunctionVersion": "2"
+  },
+  "levels": [
+    {
+      "level": "L1",
+      "name": "Schema-valid records",
+      "description": "Every core record type an implementation emits or accepts validates against the corresponding normative JSON Schema in schemas/. This is the floor: an implementation that cannot produce or consume schema-valid records cannot claim any higher level.",
+      "requires": [],
+      "satisfiedBy": {
+        "kind": "schema-validation",
+        "schemaDir": "schemas",
+        "schemaFiles": [
+          "claim.schema.json",
+          "derivation-rule.schema.json",
+          "evidence.schema.json",
+          "inquiry-record.schema.json",
+          "trust-bundle.schema.json",
+          "trust-report.schema.json",
+          "verification-event.schema.json",
+          "verification-policy.schema.json"
+        ],
+        "howToRun": "Validate your implementation's own TrustBundle output (and any other emitted record types) against schemas/trust-bundle.schema.json with all sibling schemas registered for $ref resolution, using an Ajv (draft 2020-12) instance or equivalent."
+      }
+    },
+    {
+      "level": "L2",
+      "name": "Status derivation vectors",
+      "description": "The implementation's status-derivation function (status-function.md) produces the expected per-claim status for every single-bundle conformance vector in this directory, at the vector's fixed `now`.",
+      "requires": ["L1"],
+      "satisfiedBy": {
+        "kind": "test-vectors",
+        "vectorDir": "conformance",
+        "vectorFilePattern": "sf-*.json",
+        "vectorCount": 8,
+        "specRef": "status-function.md",
+        "howToRun": "For each vector file, call your status-derivation function with vector.input and new Date(vector.now), then assert the derived status for every claim id matches vector.expect.statusByClaimId. All vectors must pass for the statusFunctionVersion declared in appliesTo.statusFunctionVersion."
+      }
+    },
+    {
+      "level": "L3",
+      "name": "Multi-producer merge vectors",
+      "description": "The implementation's merge function (merge.md) produces the expected merged claim-id set, collision set, and per-claim statuses on the merged bundle for every merge conformance vector, and the merge result is identical regardless of input bundle order (merge.md §6 determinism rule).",
+      "requires": ["L1", "L2"],
+      "satisfiedBy": {
+        "kind": "test-vectors",
+        "vectorDir": "conformance/merge",
+        "vectorFilePattern": "merge-*.json",
+        "vectorCount": 4,
+        "specRef": "merge.md",
+        "howToRun": "For each vector file, call mergeBundles/mergeBundlesDetailed on vector.inputs (and on every permutation of vector.inputs, to prove order-independence per merge.md §6), then assert the merged claim ids, collisions, and per-claim statuses (via your L2 status-derivation function on the merged bundle) match vector.expect."
+      }
+    }
+  ],
+  "canonicalization": {
+    "primitive": "RFC 8785 (JCS)",
+    "appliesTo": [
+      "merge.md §6 deterministic tie-break rule",
+      "\"hash\"-kind integrityAnchor computation (SECURITY.md)"
+    ],
+    "status": "ratified"
+  },
+  "notes": [
+    "This manifest describes what passing looks like; it does not itself execute anything. hachure-org/spec ships schemas, prose, and vector fixtures — it does not depend on @kontourai/surface, so this repo's own `npm test` validates vector shape and Ajv-validates vector `input`/`inputs[]` fields against trust-bundle.schema.json, but does not run status/merge derivation itself. Algorithmic conformance (L2/L3) is proven by an implementation actually running its own deriveClaimStatus/mergeBundles against these vectors, per merge.md's \"Reference implementation notes\" table.",
+    "L2 and L3 are independent axes in principle (an implementation could theoretically support merge without an L1-conformant single-bundle deriver), but requires:['L1','L2'] on L3 reflects that merge.md's own conformance loop (merge.md's Reference implementation notes table) evaluates merged-bundle status via the same deriveClaimStatus function L2 exercises — there is no separate merge-only status function to test independently."
+  ]
+}

package/index.mjs

@@ -11,6 +11,13 @@
  *                             vectors. Each vector has `input`, `expect`, and
  *                             `now` fields; run them against your implementation
  *                             to claim conformance.
+ *   conformanceManifest    — structured object describing conformance levels
+ *                             (L1 schema-valid, L2 status vectors, L3 merge
+ *                             vectors), which files satisfy each, and the
+ *                             schemaVersion/statusFunctionVersion it applies
+ *                             to. Parsed from conformance/manifest.json.
+ *                             Distinct from testVectors: this describes what
+ *                             passing means, testVectors is the raw fixtures.
  */
 
 import { readFileSync, readdirSync } from 'node:fs';
@@ -50,7 +57,9 @@ function loadTestVectors() {
   const conformanceDir = join(__dirname, 'conformance');
   const vectors = [];
   for (const file of readdirSync(conformanceDir).sort()) {
-    if (!file.endsWith('.json')) continue;
+    // manifest.json is structured metadata (see conformanceManifest below),
+    // not a { now, input, expect } test vector — excluded here.
+    if (!file.endsWith('.json') || file === 'manifest.json') continue;
     const name = basename(file, '.json');
     const vector = JSON.parse(readFileSync(join(conformanceDir, file), 'utf8'));
     vectors.push({ name, vector });
@@ -59,3 +68,15 @@ function loadTestVectors() {
 }
 
 export const testVectors = loadTestVectors();
+
+// ---------------------------------------------------------------------------
+// Conformance manifest — structured levels/requirements, distinct from the
+// raw testVectors list above. See conformance/manifest.json and
+// conformance/README.md for the human-readable pointer.
+// ---------------------------------------------------------------------------
+function loadConformanceManifest() {
+  const manifestPath = join(__dirname, 'conformance', 'manifest.json');
+  return JSON.parse(readFileSync(manifestPath, 'utf8'));
+}
+
+export const conformanceManifest = loadConformanceManifest();

package/interop-in-toto.md

@@ -2,6 +2,7 @@
 
 **Module:** `@kontourai/surface` — `src/interop/in-toto.ts`
 **Public exports:** `toInTotoStatement`, `toDsseEnvelope`, `buildPaeBytes`, `parseDssePayload`
+**Conformance language:** MUST/SHOULD/MAY keywords in this document are to be interpreted per RFC 2119/BCP 14, as defined in [README.md's Conformance language section](README.md#conformance-language).
 
 ---
 

package/merge.md

@@ -3,6 +3,7 @@
 **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`
+**Conformance language:** MUST/SHOULD/MAY keywords in this document are to be interpreted per RFC 2119/BCP 14, as defined in [README.md's Conformance language section](README.md#conformance-language).
 
 ---
 
@@ -194,14 +195,40 @@ content-identical, an implementation MUST:
    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.)
+   array position — using the record whose [RFC 8785](https://www.rfc-editor.org/rfc/rfc8785)
+   (JSON Canonicalization Scheme, JCS) serialization sorts lexicographically
+   first among the distinct contents.
+
+**Canonicalization decision (ratified):** RFC 8785/JCS is the normative
+canonicalization primitive for this tie-break rule, and for `"hash"`-kind
+`integrityAnchor` computation bundle-wide (`SECURITY.md` §"Integrity anchors
+and canonicalization" states the identical rule for hashing — one decision,
+cited from both places). This was previously a "target primitive... until
+adopted bundle-wide" hedge; it is now ratified as MUST, not a future
+aspiration: canonicalization MUST be RFC 8785 (JCS) — full stop, with no
+sorted-key-`JSON.stringify` shortcut carve-out. Two implementations that both
+claim RFC 8785 compliance and compare the same distinct contents MUST agree
+on which one sorts first.
+
+> **Note (informative, not normative):** producing byte-identical RFC 8785
+> output across languages has real cross-language pitfalls implementers
+> should verify against, not assume away. (a) Non-ASCII string escaping —
+> RFC 8785 (via RFC 8259) requires strings to contain literal UTF-8
+> characters, never `\uXXXX` escapes, but several languages' default JSON
+> serializers `\u`-escape non-ASCII by default (e.g. Python's `json.dumps`'s
+> `ensure_ascii=True` default) and must be reconfigured to emit literal
+> UTF-8. (b) Number serialization MUST follow the ECMAScript
+> `Number::toString` algorithm (RFC 8785 §3.2.2.3) — native to JavaScript
+> engines, but other languages need a compliant implementation of that exact
+> algorithm, not their own default float-to-string routine. (c) Property
+> sort order is by UTF-16 code unit value (RFC 8785 §3.2.3), not codepoint,
+> byte, or locale-collation order. RFC 8785 §3.1 also does not apply Unicode
+> normalization — strings are canonicalized exactly as they already are in
+> memory, so two visually-identical strings that differ only in Unicode
+> normalization form produce different canonical bytes. A hand-rolled
+> sorted-key `JSON.stringify` can silently diverge from RFC 8785 on any of
+> these points; there is no shortcut that is safe to assume equivalent
+> without verifying against a conformant JCS implementation.
 
 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
@@ -301,11 +328,14 @@ claim).
   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.
+- **A canonicalization *library* shipped by this repo.** RFC 8785/JCS is
+  ratified (§6) as the normative canonicalization primitive for both the §6
+  tie-break rule and `"hash"`-kind `integrityAnchor` computation
+  (`SECURITY.md`) — that decision is now settled, not deferred. What remains
+  out of scope here is providing a canonicalization *implementation*:
+  `hachure-org/spec` ships schemas and prose, not runtime code: it is the
+  reference implementation's (`@kontourai/surface`'s) responsibility to
+  implement RFC 8785, not this repo's.
 - **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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hachure",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "statusFunctionVersion": "2",
   "description": "Hachure — canonical distribution of the open trust format: normative JSON schemas, conformance test vectors, and spec constants.",
   "type": "module",
@@ -19,7 +19,8 @@
     "merge.md",
     "interop-in-toto.md",
     "verification-endpoint.md",
-    "assurance.md"
+    "assurance.md",
+    "SECURITY.md"
   ],
   "scripts": {
     "test": "node --test test/*.test.mjs"

package/schemas/claim.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://kontourai.io/schemas/surface/claim.schema.json",
-  "title": "Kontour Surface Claim",
+  "$id": "https://hachure.org/schemas/claim.schema.json",
+  "title": "Hachure Claim",
   "type": "object",
   "required": ["id", "subjectType", "subjectId", "surface", "claimType", "fieldOrBehavior", "value", "createdAt", "updatedAt"],
   "properties": {

package/schemas/derivation-rule.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://kontourai.io/schemas/surface/derivation-rule.schema.json",
-  "title": "Surface DerivationRule",
+  "$id": "https://hachure.org/schemas/derivation-rule.schema.json",
+  "title": "Hachure DerivationRule",
   "description": "A named, versioned rule composing existing claims into a derived boolean answer (ADR 0003 §5).",
   "type": "object",
   "required": ["id", "version", "name", "target", "requirements", "combinator"],

package/schemas/evidence.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://kontourai.io/schemas/surface/evidence.schema.json",
-  "title": "Kontour Surface Evidence",
+  "$id": "https://hachure.org/schemas/evidence.schema.json",
+  "title": "Hachure Evidence",
   "type": "object",
   "required": ["id", "claimId", "evidenceType", "method", "sourceRef", "excerptOrSummary", "observedAt", "collectedBy"],
   "properties": {

package/schemas/inquiry-record.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://kontourai.io/schemas/surface/inquiry-record.schema.json",
-  "title": "Surface InquiryRecord",
+  "$id": "https://hachure.org/schemas/inquiry-record.schema.json",
+  "title": "Hachure InquiryRecord",
   "description": "Append-only record capturing the resolution of an Inquiry against a TrustBundle (ADR 0003 §6).",
   "type": "object",
   "required": ["id", "inquiry", "outcome", "resolutionPath", "inputSnapshot", "statusFunctionVersion", "resolvedAt"],

package/schemas/trust-bundle.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://kontourai.io/schemas/surface/trust-bundle.schema.json",
-  "title": "Surface TrustBundle",
+  "$id": "https://hachure.org/schemas/trust-bundle.schema.json",
+  "title": "Hachure TrustBundle",
   "type": "object",
   "additionalProperties": false,
   "required": ["schemaVersion", "source", "claims", "evidence", "policies", "events"],

package/schemas/trust-report.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://kontourai.io/schemas/surface/trust-report.schema.json",
-  "title": "Surface TrustReport",
+  "$id": "https://hachure.org/schemas/trust-report.schema.json",
+  "title": "Hachure TrustReport",
   "$comment": "transparencyGaps, changeRecords, subjectGroups, claimGroupRollups, summary, and evidenceRequirementsByClaimId are intentionally loosely typed pending dedicated normative sub-schemas (no existing schema for TransparencyGap/DerivationChangeRecord/SubjectGroup/ClaimGroupRollup/TrustReportSummary/EvidenceRequirement exists anywhere in the ecosystem today); only the top-level report shape and the pass-through bundle fields are strictly validated.",
   "type": "object",
   "additionalProperties": false,

package/schemas/verification-event.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://kontourai.io/schemas/surface/verification-event.schema.json",
-  "title": "Kontour Surface Verification Event",
+  "$id": "https://hachure.org/schemas/verification-event.schema.json",
+  "title": "Hachure VerificationEvent",
   "type": "object",
   "required": ["id", "claimId", "status", "actor", "method", "evidenceIds", "createdAt"],
   "properties": {

package/schemas/verification-policy.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "$id": "https://kontourai.io/schemas/surface/verification-policy.schema.json",
-  "title": "Kontour Surface Verification Policy",
+  "$id": "https://hachure.org/schemas/verification-policy.schema.json",
+  "title": "Hachure VerificationPolicy",
   "type": "object",
   "required": ["id", "claimType", "requiredEvidence", "acceptanceCriteria", "reviewAuthority", "validityRule", "stalenessTriggers", "conflictRules", "impactLevel"],
   "properties": {

package/status-function.md

@@ -3,6 +3,7 @@
 **Function:** `status = f(claim, evidence, events, policy, authorityTrace, now)`
 **Version constant:** `statusFunctionVersion` (currently `"2"`)
 **Source of truth:** `src/status.ts` in `@kontourai/surface`
+**Conformance language:** MUST/SHOULD/MAY keywords in this document are to be interpreted per RFC 2119/BCP 14, as defined in [README.md's Conformance language section](README.md#conformance-language).
 
 ---
 

package/verification-endpoint.md

@@ -4,6 +4,7 @@
 **Status:** draft
 **Namespace:** `hachure.org/v1`
 **Depends on:** core record shapes, [status-function.md](status-function.md), [interop-in-toto.md](interop-in-toto.md)
+**Conformance language:** MUST/SHOULD/MAY keywords in this document are to be interpreted per RFC 2119/BCP 14, as defined in [README.md's Conformance language section](README.md#conformance-language).
 
 ---