feat(evidence): ADR-0005 WP-2 Set 0 provider contract and conformance suite.

Adds P/D/F qualification types, provider API, golden exemplars E01–E10,
provider-json reference provider, presentation primitives, and pnpm test-provider gate.

Author: betterdataco

package.json

@@ -24,7 +24,8 @@
     "version-packages": "changeset version",
     "validate:publish": "node scripts/check-no-workspace-refs.mjs",
     "typecheck:examples": "tsc -p tsconfig.examples.json",
-    "release": "pnpm validate:publish && changeset publish"
+    "release": "pnpm validate:publish && changeset publish",
+    "test-provider": "pnpm --filter @loop-engine/provider-conformance run test-provider"
   },
   "devDependencies": {
     "@changesets/changelog-github": "^0.5.2",

packages/evidence/src/__tests__/provider-snapshot-contract.test.ts

@@ -0,0 +1,67 @@
+// SPDX-License-Identifier: Apache-2.0
+import { describe, expect, it } from "vitest";
+import {
+  definitionMeetsMinimum,
+  provenanceMeetsMinimum,
+} from "../qualification.js";
+import { validateEvidenceSnapshotProposed } from "../validate-provider-snapshot.js";
+import { LAUNCH_DECISION_RECORD_VERSIONS } from "../types.js";
+
+const baseSnapshot = {
+  snapshotKey: "metric-total",
+  sourceSystem: "warehouse",
+  sourceRef: "semantic://revenue_total",
+  capturedAt: "2026-07-07T12:00:00.000Z",
+  capturedBy: "provider-json",
+  values: { amount: 12500, currency: "USD" },
+  versions: LAUNCH_DECISION_RECORD_VERSIONS,
+  qualification: {
+    provenance: "system-attested",
+    definition: "governed",
+    freshness: {
+      applicable: "applicable",
+      snapshotFrozenAt: "2026-07-07T12:00:00.000Z",
+      valueAsOf: "2026-07-07T11:58:00.000Z",
+      bindingClock: "valueAsOf",
+      freshnessVerdict: "fresh",
+    },
+  },
+};
+
+describe("qualification vector ordering", () => {
+  it("compares provenance rungs with ≥ semantics", () => {
+    expect(provenanceMeetsMinimum("origin-attested", "system-attested")).toBe(true);
+    expect(provenanceMeetsMinimum("unknown", "system-attested")).toBe(false);
+  });
+
+  it("skips definition check when axis is not-applicable", () => {
+    expect(definitionMeetsMinimum("not-applicable", "governed")).toBe(true);
+    expect(definitionMeetsMinimum("governed", "not-applicable")).toBe(true);
+  });
+});
+
+describe("validateEvidenceSnapshotProposed (Set 0)", () => {
+  it("accepts a governed semantic metric exemplar shape", () => {
+    expect(validateEvidenceSnapshotProposed(baseSnapshot).valid).toBe(true);
+  });
+
+  it("rejects missing qualification vector", () => {
+    const result = validateEvidenceSnapshotProposed({
+      ...baseSnapshot,
+      qualification: undefined,
+    });
+    expect(result.valid).toBe(false);
+  });
+
+  it("rejects applicable freshness without clocks", () => {
+    const result = validateEvidenceSnapshotProposed({
+      ...baseSnapshot,
+      qualification: {
+        ...baseSnapshot.qualification,
+        freshness: { applicable: "applicable" },
+      },
+    });
+    expect(result.valid).toBe(false);
+    expect(result.errors.some((e) => e.path?.includes("snapshotFrozenAt"))).toBe(true);
+  });
+});

packages/evidence/src/index.ts

@@ -47,3 +47,29 @@ export {
   validateEvidenceSnapshotPersistedBatch,
   validateGovernedEvidencePresent,
 } from "./validate-evidence-snapshot.js";
+export {
+  validateEvidenceSnapshotProposed,
+  assertEvidenceSnapshotProposed,
+  assertQualificationVector,
+} from "./validate-provider-snapshot.js";
+export { isFreshnessApplicable } from "./qualification.js";
+export type {
+  ProvenanceRung,
+  DefinitionRung,
+  FreshnessQualification,
+  FreshnessVerdict,
+  FreshnessBindingClock,
+  QualificationVector,
+  VersionIdentityConstraint,
+} from "./qualification.js";
+export {
+  PROVENANCE_ORDER,
+  DEFINITION_ORDER,
+  provenanceMeetsMinimum,
+  definitionMeetsMinimum,
+} from "./qualification.js";
+export type {
+  EvidenceSnapshotProposed,
+  EvidenceSnapshotContract,
+  EvidenceRenderedArtifact,
+} from "./provider-snapshot-contract.js";

packages/evidence/src/provider-snapshot-contract.ts

@@ -0,0 +1,56 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) Better Data, Inc.
+
+/**
+ * ADR-0005 Set 0 — EvidenceSnapshot provider contract DTO.
+ *
+ * Extends WP-1 commit input with qualification vector, version identity,
+ * measurements (opaque), and native metadata isolation boundaries.
+ */
+
+import type { EvidenceLineageRef, DecisionRecordVersionMetadata } from "./types.js";
+import type {
+  FreshnessQualification,
+  QualificationVector,
+  VersionIdentityConstraint,
+} from "./qualification.js";
+
+/** Provider-proposed snapshot before engine freeze (ADR-0005). */
+export type EvidenceSnapshotProposed = {
+  snapshotKey: string;
+  sourceSystem: string;
+  sourceRef?: string;
+  capturedAt: string;
+  capturedBy: string;
+  values: Record<string, unknown>;
+  versions: DecisionRecordVersionMetadata;
+  qualification: QualificationVector;
+  lineage?: EvidenceLineageRef[];
+  version?: VersionIdentityConstraint;
+  /** Quantitative properties — opaque until Canon promotes a key (ADR-0005). */
+  measurements?: Record<string, unknown>;
+  /** Provider-native terms — must not leak into Canon vocabulary. */
+  nativeMetadata?: Record<string, unknown>;
+  timelineEvent?: string;
+  timelineAt?: string;
+  sequence?: number;
+  providerId?: string;
+  conformanceSuiteVersion?: string;
+  /** Optional client hash — engine recomputes from `values` at commit. */
+  contentSha256?: string;
+  renderedArtifact?: EvidenceRenderedArtifact;
+};
+
+/** Frozen authoritative snapshot after engine commit (ADR-0004 + ADR-0005). */
+export type EvidenceSnapshotContract = EvidenceSnapshotProposed & {
+  id?: string;
+  contentSha256: string;
+};
+
+export type EvidenceRenderedArtifact = {
+  kind: "image" | "pdf" | "html" | "json";
+  mimeType: string;
+  uri?: string;
+  /** Inline preview payload when uri absent (reference viewer only). */
+  inlineBase64?: string;
+};

packages/evidence/src/qualification.ts

@@ -0,0 +1,93 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) Better Data, Inc.
+
+/**
+ * ADR-0005 Qualification Vector — P/D/F axes (Set 0 Provider Contract).
+ *
+ * Qualification is inherited from provider mapping, never caller-asserted (ADR-0004 C1).
+ */
+
+/** Axis P — Provenance (universal). */
+export type ProvenanceRung = "unknown" | "system-attested" | "origin-attested";
+
+/** Axis D — Definition (derived values; `not-applicable` for raw facts). */
+export type DefinitionRung =
+  | "not-applicable"
+  | "unreviewed"
+  | "certified"
+  | "governed";
+
+export type FreshnessVerdict = "fresh" | "stale" | "unknown";
+
+export type FreshnessBindingClock =
+  | "snapshotFrozenAt"
+  | "valueAsOf"
+  | "sourceDataFreshness";
+
+/** Axis F — Freshness (where temporal; identity constraints use `version` instead). */
+export type FreshnessQualification =
+  | { applicable: "not-applicable" }
+  | {
+      applicable: "applicable";
+      snapshotFrozenAt: string;
+      valueAsOf: string;
+      sourceDataFreshness?: string;
+      freshnessSla?: string;
+      freshnessVerdict?: FreshnessVerdict;
+      /** Two-clock sources: binding (stalest) clock for role evaluation. */
+      bindingClock?: FreshnessBindingClock;
+    };
+
+/** Open extensible vector — only P/D/F defined at launch (ADR-0005). */
+export type QualificationVector = {
+  provenance: ProvenanceRung;
+  definition: DefinitionRung;
+  freshness: FreshnessQualification;
+};
+
+/** Version identity constraint — not an ordered axis (ADR-0005). */
+export type VersionIdentityConstraint = {
+  kind: "must_equal" | "must_be_in";
+  value: string | string[];
+};
+
+/** Compare ordered rungs on a single axis (≥ semantics for P/D; F uses age separately). */
+export const PROVENANCE_ORDER: readonly ProvenanceRung[] = [
+  "unknown",
+  "system-attested",
+  "origin-attested",
+];
+
+export const DEFINITION_ORDER: readonly DefinitionRung[] = [
+  "not-applicable",
+  "unreviewed",
+  "certified",
+  "governed",
+];
+
+export function provenanceMeetsMinimum(
+  actual: ProvenanceRung,
+  required: ProvenanceRung,
+): boolean {
+  return (
+    PROVENANCE_ORDER.indexOf(actual) >= PROVENANCE_ORDER.indexOf(required)
+  );
+}
+
+export function definitionMeetsMinimum(
+  actual: DefinitionRung,
+  required: DefinitionRung,
+): boolean {
+  if (actual === "not-applicable" || required === "not-applicable") {
+    return true;
+  }
+  return (
+    DEFINITION_ORDER.indexOf(actual) >= DEFINITION_ORDER.indexOf(required)
+  );
+}
+
+export function isFreshnessApplicable(
+  freshness: FreshnessQualification,
+): freshness is Extract<FreshnessQualification, { applicable: "applicable" }> {
+  return freshness.applicable === "applicable";
+}