hachure 0.4.0 → 0.5.0

package/README.md

@@ -73,8 +73,16 @@ 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
-`3`) and in the status function version (a string exported by the reference
-implementation as `statusFunctionVersion`, currently `"1"`).
+`4`) 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` /
+`ttlSeconds`) and an optional invalidation event vocabulary (event `status:
+"revoked"` and event `type: "invalidation"`). All additions are optional, so
+every bundle valid at `schemaVersion` `3` remains valid; only the deriver
+(`statusFunctionVersion` `2`) folds the new fields into a status. See
+`status-function.md` and the `sf-expired-window` / `sf-revoked-event` /
+`sf-no-freshness-fields` conformance vectors.
 
 ---
 

package/conformance/README.md

@@ -17,6 +17,9 @@ implementation derives the expected statuses.
 | `sf-disputed-blocking.json` | Verified event + blocking contradicting evidence → disputed | 2026-06-10T00:00:00.000Z |
 | `sf-authority-resolved.json` | Disputed claim resolved by authority-gated event | 2026-06-10T00:00:00.000Z |
 | `sf-reference-bundle-snapshot.json` | Full the reference bundle at fixed now — four claims | 2026-06-10T00:00:00.000Z |
+| `sf-expired-window.json` | Claim-intrinsic validity window — stale past `expiresAt` and past `ttlSeconds` (schema 4) | 2026-06-10T00:00:00.000Z |
+| `sf-revoked-event.json` | Explicit invalidation event (`status: revoked`, `type: invalidation`) → stale (schema 4) | 2026-06-10T00:00:00.000Z |
+| `sf-no-freshness-fields.json` | No freshness fields present → derives unchanged from `statusFunctionVersion` `1` | 2026-06-10T00:00:00.000Z |
 
 ## Test vector format
 

package/conformance/sf-expired-window.json

@@ -0,0 +1,102 @@
+{
+  "now": "2026-06-10T00:00:00.000Z",
+  "input": {
+    "schemaVersion": 4,
+    "source": "spec-conformance:expired-window",
+    "claims": [
+      {
+        "id": "claim.window.expires-at",
+        "subjectType": "data-field",
+        "subjectId": "dataset:session-token",
+        "surface": "public-data.status",
+        "claimType": "public-data-field",
+        "fieldOrBehavior": "tokenValid",
+        "value": true,
+        "createdAt": "2026-05-01T00:00:00.000Z",
+        "updatedAt": "2026-05-01T00:00:00.000Z",
+        "expiresAt": "2026-06-01T00:00:00.000Z",
+        "impactLevel": "high",
+        "verificationPolicyId": "policy.public-data-field.manual"
+      },
+      {
+        "id": "claim.window.ttl",
+        "subjectType": "data-field",
+        "subjectId": "dataset:cache-entry",
+        "surface": "public-data.status",
+        "claimType": "public-data-field",
+        "fieldOrBehavior": "cacheFresh",
+        "value": true,
+        "createdAt": "2026-06-09T00:00:00.000Z",
+        "updatedAt": "2026-06-09T00:00:00.000Z",
+        "ttlSeconds": 3600,
+        "impactLevel": "medium",
+        "verificationPolicyId": "policy.public-data-field.manual"
+      }
+    ],
+    "evidence": [
+      {
+        "id": "evidence.window.expires-at",
+        "claimId": "claim.window.expires-at",
+        "evidenceType": "human_attestation",
+        "method": "attestation",
+        "sourceRef": "operator review",
+        "excerptOrSummary": "Token issued and attested valid until 2026-06-01.",
+        "observedAt": "2026-05-01T00:00:00.000Z",
+        "collectedBy": "operator"
+      },
+      {
+        "id": "evidence.window.ttl",
+        "claimId": "claim.window.ttl",
+        "evidenceType": "human_attestation",
+        "method": "attestation",
+        "sourceRef": "operator review",
+        "excerptOrSummary": "Cache entry attested fresh at refresh time.",
+        "observedAt": "2026-06-09T00:00:00.000Z",
+        "collectedBy": "operator"
+      }
+    ],
+    "policies": [
+      {
+        "id": "policy.public-data-field.manual",
+        "claimType": "public-data-field",
+        "requiredEvidence": ["human_attestation"],
+        "requiredMethods": ["attestation"],
+        "requiresCorroboration": false,
+        "acceptanceCriteria": ["operator attestation"],
+        "reviewAuthority": "operator",
+        "validityRule": { "kind": "manual" },
+        "stalenessTriggers": ["validity window expires"],
+        "conflictRules": [],
+        "impactLevel": "high"
+      }
+    ],
+    "events": [
+      {
+        "id": "event.window.expires-at.verified",
+        "claimId": "claim.window.expires-at",
+        "status": "verified",
+        "actor": "operator",
+        "method": "attestation",
+        "evidenceIds": ["evidence.window.expires-at"],
+        "createdAt": "2026-05-01T00:00:00.000Z",
+        "verifiedAt": "2026-05-01T00:00:00.000Z"
+      },
+      {
+        "id": "event.window.ttl.verified",
+        "claimId": "claim.window.ttl",
+        "status": "verified",
+        "actor": "operator",
+        "method": "attestation",
+        "evidenceIds": ["evidence.window.ttl"],
+        "createdAt": "2026-06-09T00:00:00.000Z",
+        "verifiedAt": "2026-06-09T00:00:00.000Z"
+      }
+    ]
+  },
+  "expect": {
+    "statusByClaimId": {
+      "claim.window.expires-at": "stale",
+      "claim.window.ttl": "stale"
+    }
+  }
+}

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

@@ -0,0 +1,68 @@
+{
+  "now": "2026-06-10T00:00:00.000Z",
+  "input": {
+    "schemaVersion": 4,
+    "source": "spec-conformance:no-freshness-fields",
+    "claims": [
+      {
+        "id": "claim.api.rate-limit",
+        "subjectType": "api",
+        "subjectId": "public-api",
+        "surface": "api.guarantees",
+        "claimType": "software-evidence",
+        "fieldOrBehavior": "rate limit is enforced",
+        "value": "100 requests/minute",
+        "createdAt": "2026-04-25T00:00:00.000Z",
+        "updatedAt": "2026-04-25T00:05:00.000Z",
+        "impactLevel": "high",
+        "currentIntegrityRef": "commit:abc123",
+        "verificationPolicyId": "policy.software-evidence.commit"
+      }
+    ],
+    "evidence": [
+      {
+        "id": "evidence.api.rate-limit.test",
+        "claimId": "claim.api.rate-limit",
+        "evidenceType": "test_output",
+        "method": "validation",
+        "sourceRef": "ci:1847",
+        "excerptOrSummary": "Rate-limit tests passed.",
+        "observedAt": "2026-04-25T00:05:00.000Z",
+        "collectedBy": "ci",
+        "integrityRef": "commit:abc123"
+      }
+    ],
+    "policies": [
+      {
+        "id": "policy.software-evidence.commit",
+        "claimType": "software-evidence",
+        "requiredEvidence": ["test_output"],
+        "requiredMethods": ["validation"],
+        "requiresCorroboration": false,
+        "acceptanceCriteria": ["evidence check passes for the affected commit"],
+        "reviewAuthority": "repo policy",
+        "validityRule": { "kind": "commit" },
+        "stalenessTriggers": ["new commit touches the same surface"],
+        "conflictRules": [],
+        "impactLevel": "high"
+      }
+    ],
+    "events": [
+      {
+        "id": "event.api.rate-limit.verified",
+        "claimId": "claim.api.rate-limit",
+        "status": "verified",
+        "actor": "ci",
+        "method": "npm test",
+        "evidenceIds": ["evidence.api.rate-limit.test"],
+        "createdAt": "2026-04-25T00:05:00.000Z",
+        "verifiedAt": "2026-04-25T00:05:00.000Z"
+      }
+    ]
+  },
+  "expect": {
+    "statusByClaimId": {
+      "claim.api.rate-limit": "verified"
+    }
+  }
+}

package/conformance/sf-revoked-event.json

@@ -0,0 +1,76 @@
+{
+  "now": "2026-06-10T00:00:00.000Z",
+  "input": {
+    "schemaVersion": 4,
+    "source": "spec-conformance:revoked-event",
+    "claims": [
+      {
+        "id": "claim.access.grant",
+        "subjectType": "credential",
+        "subjectId": "access:deploy-key-7",
+        "surface": "access-control.grants",
+        "claimType": "software-evidence",
+        "fieldOrBehavior": "deployKeyValid",
+        "value": true,
+        "createdAt": "2026-05-01T00:00:00.000Z",
+        "updatedAt": "2026-06-05T00:00:00.000Z",
+        "impactLevel": "critical",
+        "verificationPolicyId": "policy.software-evidence.commit"
+      }
+    ],
+    "evidence": [
+      {
+        "id": "evidence.access.grant",
+        "claimId": "claim.access.grant",
+        "evidenceType": "test_output",
+        "method": "validation",
+        "sourceRef": "grant issuance log",
+        "excerptOrSummary": "Deploy key issued and validated.",
+        "observedAt": "2026-05-01T00:00:00.000Z",
+        "collectedBy": "access-service"
+      }
+    ],
+    "policies": [
+      {
+        "id": "policy.software-evidence.commit",
+        "claimType": "software-evidence",
+        "requiredEvidence": ["test_output"],
+        "requiredMethods": ["validation"],
+        "requiresCorroboration": false,
+        "acceptanceCriteria": ["evidence check passes"],
+        "reviewAuthority": "repo policy",
+        "validityRule": { "kind": "commit" },
+        "stalenessTriggers": ["revocation"],
+        "conflictRules": [],
+        "impactLevel": "critical"
+      }
+    ],
+    "events": [
+      {
+        "id": "event.access.grant.verified",
+        "claimId": "claim.access.grant",
+        "status": "verified",
+        "actor": "access-service",
+        "method": "validation",
+        "evidenceIds": ["evidence.access.grant"],
+        "createdAt": "2026-05-01T00:00:00.000Z",
+        "verifiedAt": "2026-05-01T00:00:00.000Z"
+      },
+      {
+        "id": "event.access.grant.revoked",
+        "claimId": "claim.access.grant",
+        "status": "revoked",
+        "type": "invalidation",
+        "actor": "security-officer",
+        "method": "manual-revocation",
+        "evidenceIds": [],
+        "createdAt": "2026-06-05T00:00:00.000Z"
+      }
+    ]
+  },
+  "expect": {
+    "statusByClaimId": {
+      "claim.access.grant": "stale"
+    }
+  }
+}

package/index.mjs

@@ -24,7 +24,7 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 // Any implementation claiming conformance at this version must produce the
 // same status outputs as the test vectors for all cases in conformance/.
 // ---------------------------------------------------------------------------
-export const statusFunctionVersion = '1';
+export const statusFunctionVersion = '2';
 
 // ---------------------------------------------------------------------------
 // Schemas — Map of record name (filename without .schema.json) → parsed JSON.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hachure",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Hachure \u2014 canonical distribution of the open trust format: normative JSON schemas, conformance test vectors, and spec constants.",
   "type": "module",
   "main": "./index.mjs",

package/schemas/claim.schema.json

@@ -12,9 +12,19 @@
     "claimType": { "type": "string" },
     "fieldOrBehavior": { "type": "string" },
     "value": {},
-    "status": { "enum": ["unknown", "proposed", "assumed", "verified", "stale", "disputed", "superseded", "rejected"] },
+    "status": { "enum": ["unknown", "proposed", "assumed", "verified", "stale", "disputed", "superseded", "rejected", "revoked"] },
     "createdAt": { "type": "string", "format": "date-time" },
     "updatedAt": { "type": "string", "format": "date-time" },
+    "expiresAt": {
+      "description": "Optional absolute validity window: ISO-8601 instant after which the claim is no longer fresh. Canonical when both expiresAt and ttlSeconds are present (expiresAt wins). Behaviour is derived by Surface, not by this schema.",
+      "type": "string",
+      "format": "date-time"
+    },
+    "ttlSeconds": {
+      "description": "Optional relative validity window in seconds, resolved by the deriver against the governing verification event's verifiedAt (falling back to createdAt). If expiresAt is also present, expiresAt takes precedence. Behaviour is derived by Surface, not by this schema.",
+      "type": "integer",
+      "minimum": 0
+    },
     "impactLevel": { "enum": ["low", "medium", "high", "critical"] },
     "materiality": { "enum": ["low", "medium", "high"] },
     "currentIntegrityRef": { "type": "string" },

package/schemas/inquiry-record.schema.json

@@ -26,7 +26,7 @@
       "additionalProperties": false,
       "properties": {
         "value": {},
-        "status": { "enum": ["unknown", "proposed", "assumed", "verified", "stale", "disputed", "superseded", "rejected"] }
+        "status": { "enum": ["unknown", "proposed", "assumed", "verified", "stale", "disputed", "superseded", "rejected", "revoked"] }
       }
     },
     "inputSnapshot": {
@@ -37,7 +37,7 @@
         "additionalProperties": false,
         "properties": {
           "claimId": { "type": "string" },
-          "status": { "enum": ["unknown", "proposed", "assumed", "verified", "stale", "disputed", "superseded", "rejected"] }
+          "status": { "enum": ["unknown", "proposed", "assumed", "verified", "stale", "disputed", "superseded", "rejected", "revoked"] }
         }
       }
     },

package/schemas/trust-bundle.schema.json

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

package/schemas/verification-event.schema.json

@@ -7,7 +7,11 @@
   "properties": {
     "id": { "type": "string" },
     "claimId": { "type": "string" },
-    "status": { "enum": ["unknown", "proposed", "assumed", "verified", "stale", "disputed", "superseded", "rejected"] },
+    "status": { "enum": ["unknown", "proposed", "assumed", "verified", "stale", "disputed", "superseded", "rejected", "revoked"] },
+    "type": {
+      "description": "Optional event classifier. 'invalidation' marks a ledger line that explicitly revokes/stales a previously-good claim (use with status 'revoked' or 'stale'). 'verification' is the default assertion of a status. Surface treats an invalidation event as terminal for the claim.",
+      "enum": ["verification", "invalidation"]
+    },
     "actor": { "type": "string" },
     "method": { "type": "string" },
     "evidenceIds": { "type": "array", "items": { "type": "string" } },

package/status-function.md

@@ -1,7 +1,7 @@
 # Status Derivation — Specification
 
 **Function:** `status = f(claim, evidence, events, policy, authorityTrace, now)`
-**Version constant:** `statusFunctionVersion` (currently `"1"`)
+**Version constant:** `statusFunctionVersion` (currently `"2"`)
 **Source of truth:** `src/status.ts` in `@kontourai/surface`
 
 ---
@@ -110,8 +110,17 @@ Filter all events to those matching `claim.id`, sort most-recent-first by `creat
 Let `latestEvent` be the first (most recent) event.
 
 If `latestEvent` exists and its `status` is one of `"rejected"`, `"disputed"`,
-`"superseded"`, or `"stale"` — return that status. These are terminal: they are
-not overridden by evidence inspection.
+`"superseded"`, `"stale"`, or `"revoked"` — return that status. These are
+terminal: they are not overridden by evidence inspection. An event with
+`type: "invalidation"` is always terminal in this step regardless of its
+`status` (it asserts the claim is no longer good); `"revoked"` derives `stale`
+(treated as an explicit, event-driven staleness) unless a later verification
+event re-asserts the claim.
+
+> **Schema-version note (`statusFunctionVersion` `"2"`, `schemaVersion` `4`):**
+> the `"revoked"` event status and `type: "invalidation"` classifier are new.
+> Bundles that never use them derive identically to `statusFunctionVersion`
+> `"1"`.
 
 ### Step 3: Assumed from event
 
@@ -123,7 +132,21 @@ If `latestEvent` exists and `latestEvent.status === "verified"`:
 
 #### 4a. Staleness check
 
-If a policy is present, check whether the verification is stale based on
+**Claim-intrinsic validity window (`statusFunctionVersion` `"2"`, schema `4`).**
+Before consulting the policy validity rule, check the claim's own validity
+window, which overrides policy timing when present:
+
+- If `claim.expiresAt` is set, the claim is stale when `now > Date.parse(claim.expiresAt)`.
+- Else if `claim.ttlSeconds` is set, compute
+  `expiry = Date.parse(latestEvent.verifiedAt ?? latestEvent.createdAt) + claim.ttlSeconds * 1000`;
+  the claim is stale when `now > expiry`.
+- **Precedence:** `expiresAt` wins over `ttlSeconds` when both are present.
+  When neither is present, fall through to the policy validity rule below
+  (identical to `statusFunctionVersion` `"1"`).
+
+If the claim-intrinsic window marks the claim stale: return **`stale`**.
+
+Otherwise, if a policy is present, check whether the verification is stale based on
 `policy.validityRule.kind`:
 
 - **`"commit"`** — stale if `claim.currentIntegrityRef` is set AND none of the