@warpgogol/werkstatt-shared 0.2.0

package/src/share/knowledge/freshness.ts

@@ -0,0 +1,127 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+RFC-0213: the authored-content freshness model. Given a claim's temporal window
+(asOf / validUntil / reviewEvery) and "today", derive a freshness state and the
+ledger entry shape. Framework-free, deterministic, date-only — the surface
+Freshness Ledger (RFC-0196) shares this state taxonomy + ledger shape so one
+health view can read both, but computes state from page substance, not dates.
+</purpose>
+<non-goals>
+  <item>Do not read the filesystem, parse sidecars, or emit Diagnostics — the kernel command does that.</item>
+  <item>Do not compute page-substance decay (surface RFC-0196 owns that input).</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0213: initial freshness state model + ledger shapes.</item>
+</CHANGE_SUMMARY>
+*/
+
+export type FreshnessState = "fresh" | "review-due" | "expiring-soon" | "expired" | "unsourced";
+
+export type FreshnessCriticality = "advisory" | "important" | "blocking";
+
+const MS_PER_DAY = 86_400_000;
+
+/** Parse an ISO date (YYYY-MM-DD) to a UTC epoch-ms at midnight, or null. */
+function parseIsoDate(date: string): number | null {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(date)) return null;
+  const ms = Date.parse(`${date}T00:00:00Z`);
+  return Number.isNaN(ms) ? null : ms;
+}
+
+function toIso(ms: number): string {
+  return new Date(ms).toISOString().slice(0, 10);
+}
+
+const DURATION_RE =
+  /^P(?:(\d+)Y)?(?:(\d+)M)?(?:(\d+)W)?(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+)S)?)?$/;
+
+/**
+ * Add an ISO 8601 duration to an ISO date. Calendar-correct for Y/M; W/D add
+ * fixed days; the time component is truncated to whole days (cadences are coarse).
+ * Returns null on malformed input.
+ */
+export function addDuration(dateIso: string, duration: string): string | null {
+  const base = parseIsoDate(dateIso);
+  if (base === null) return null;
+  const m = DURATION_RE.exec(duration);
+  if (!m || duration === "P" || duration === "PT") return null;
+  const [, y, mo, w, d] = m;
+  const dt = new Date(base);
+  if (y) dt.setUTCFullYear(dt.getUTCFullYear() + Number(y));
+  if (mo) dt.setUTCMonth(dt.getUTCMonth() + Number(mo));
+  const extraDays = (w ? Number(w) * 7 : 0) + (d ? Number(d) : 0);
+  if (extraDays) dt.setUTCDate(dt.getUTCDate() + extraDays);
+  return toIso(dt.getTime());
+}
+
+export interface FreshnessWindow {
+  asOf: string;
+  validUntil?: string;
+  reviewEvery?: string;
+}
+
+export interface FreshnessEvaluation {
+  state: FreshnessState;
+  reviewDueAt?: string;
+  /** Days until validUntil; negative if past. Computed, not stored. */
+  daysToExpiry?: number;
+}
+
+/**
+ * Derive freshness state from a window relative to `today` (ISO date).
+ * `unsourced` is decided by the caller (a NEED_THIS value) and short-circuits here.
+ * Precedence: expired > expiring-soon > review-due > fresh.
+ */
+export function evaluateFreshness(
+  window: FreshnessWindow,
+  today: string,
+  soonWindowDays = 30,
+): FreshnessEvaluation {
+  const todayMs = parseIsoDate(today);
+  const reviewDueAt = window.reviewEvery
+    ? (addDuration(window.asOf, window.reviewEvery) ?? undefined)
+    : undefined;
+
+  let daysToExpiry: number | undefined;
+  if (window.validUntil) {
+    const vu = parseIsoDate(window.validUntil);
+    if (vu !== null && todayMs !== null) {
+      daysToExpiry = Math.round((vu - todayMs) / MS_PER_DAY);
+    }
+  }
+
+  let state: FreshnessState = "fresh";
+  if (daysToExpiry !== undefined && daysToExpiry < 0) {
+    state = "expired";
+  } else if (daysToExpiry !== undefined && daysToExpiry <= soonWindowDays) {
+    state = "expiring-soon";
+  } else if (reviewDueAt && todayMs !== null) {
+    const due = parseIsoDate(reviewDueAt);
+    if (due !== null && due <= todayMs) state = "review-due";
+  }
+
+  return { state, reviewDueAt, daysToExpiry };
+}
+
+/** One claim's freshness in the ledger. `subject` is the canonical address string. */
+export interface FreshnessLedgerEntry {
+  subject: string;
+  state: FreshnessState;
+  asOf?: string;
+  validUntil?: string;
+  reviewDueAt?: string;
+  criticality: FreshnessCriticality;
+}
+
+/** The deterministic per-app authored Freshness Ledger (mirrors the surface ledger shape). */
+export interface AuthoredFreshnessLedger {
+  site: string;
+  entries: FreshnessLedgerEntry[];
+  summary: Record<FreshnessState, number>;
+}
+
+export function emptyFreshnessSummary(): Record<FreshnessState, number> {
+  return { fresh: 0, "review-due": 0, "expiring-soon": 0, expired: 0, unsourced: 0 };
+}

package/src/share/knowledge/index.ts

@@ -0,0 +1,23 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+RFC-0211: barrel for the Content Knowledge Lifecycle (CKL) shared model. Re-exports
+the framework-free claim contracts consumed by the kernel CKL commands and validators
+(RFC-0212..0218). Later CKL RFCs add sibling modules here (freshness, source,
+derivation, plan, ledger) and re-export them from this barrel.
+</purpose>
+<non-goals>
+  <item>Do not add logic here — pure re-export barrel.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0211: initial barrel exporting the claim model.</item>
+</CHANGE_SUMMARY>
+*/
+
+export * from "./claim.ts";
+export * from "./freshness.ts";
+export * from "./derivation.ts";
+export * from "./source.ts";
+export * from "./plan.ts";
+export * from "./ledger.ts";

package/src/share/knowledge/ledger.ts

@@ -0,0 +1,222 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+RFC-0217: The Claim Ledger — event schema, append helpers, as-of/lineage
+query, and knowledge-graph/temporal-SEO projectors. The ledger is an
+append-only NDJSON file (`src/content/ledger/claims.ndjson`); each line is
+one immutable ClaimEvent. The projector produces two generated JSON artifacts
+(knowledge.generated.yaml + seo/temporal.generated.yaml) on demand.
+Framework-free; no filesystem access.
+</purpose>
+<keywords>RFC-0217, CKL, ledger, claim event, lineage, temporal SEO, knowledge graph</keywords>
+<responsibilities>
+  <item>Define ClaimEvent, ClaimLineage, TemporalSeo, KnowledgeGraph contracts.</item>
+  <item>stableEventId — deterministic event identifier.</item>
+  <item>buildLineage — assemble lineage from flat event list for a subject.</item>
+  <item>queryAsOf — value of a subject as of a given date.</item>
+  <item>projectGraph — current claims × lineage as nodes+edges.</item>
+  <item>projectTemporalSeo — per-page datePublished/dateModified.</item>
+</responsibilities>
+<non-goals>
+  <item>Do not read/write the filesystem — the kernel command does that.</item>
+  <item>Do not parse sidecar files — consume pre-parsed events only.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<MODULE_MAP>
+  <entry key="ClaimEvent / ClaimEventKind">The immutable ledger record shape.</entry>
+  <entry key="stableEventId">sha256-based deterministic event id.</entry>
+  <entry key="buildLineage">Lineage for a subject: current + history (newest→oldest).</entry>
+  <entry key="queryAsOf">Value as of a given date.</entry>
+  <entry key="projectGraph / projectTemporalSeo">Deterministic projections.</entry>
+</MODULE_MAP>
+<CHANGE_SUMMARY>
+  <item>RFC-0217: initial ledger contract and projection helpers.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { createHash } from "node:crypto";
+import type { ClaimProvenanceKind } from "./claim.ts";
+
+export type ClaimEventKind =
+  "genesis" | "verify-update" | "verify-noop" | "translate" | "supersede" | "retire";
+
+export interface ClaimEvent {
+  /** Stable deterministic id for this event line. */
+  id: string;
+  /** ISO timestamp (event time, UTC). */
+  ts: string;
+  /** Canonical subject address (RFC-0211). */
+  subject: string;
+  /** String value (omitted for large prose; then valueHash set). */
+  value?: string;
+  /** sha256:<hex> of the value for large prose. */
+  valueHash?: string;
+  provenance: ClaimProvenanceKind;
+  sourceRef?: string;
+  /** ISO date of the fact (when the value was true). */
+  asOf: string;
+  /** Id of the event this supersedes (linking lineage). */
+  supersedes?: string;
+  /** Agent or human handle that produced this event. */
+  actor: string;
+  event: ClaimEventKind;
+}
+
+export interface ClaimLineage {
+  subject: string;
+  current: ClaimEvent;
+  /** Full history including current, newest → oldest. */
+  history: ClaimEvent[];
+}
+
+export interface TemporalSeo {
+  /** Route/page slug. */
+  page: string;
+  /** ISO date of earliest genesis event for claims on this page. */
+  datePublished: string;
+  /** ISO date of latest verify-update event for claims on this page. */
+  dateModified: string;
+  /** ISO interval "YYYY-MM-DD/YYYY-MM-DD" when earliest ≠ latest. */
+  temporalCoverage?: string;
+}
+
+export interface KnowledgeGraphNode {
+  subject: string;
+  currentValue?: string;
+  provenance: ClaimProvenanceKind;
+  asOf: string;
+  sourceRef?: string;
+  latestEventId: string;
+  historyCount: number;
+}
+
+export interface KnowledgeGraph {
+  generatedAt: string;
+  app: string;
+  nodes: KnowledgeGraphNode[];
+}
+
+export const LEDGER_GENERATED_MARKER =
+  "GENERATED. Do not change this line unless the file contains project specific changes.";
+
+/**
+ * Deterministic event id: sha256 of (subject + asOf + event + actor + value).
+ * The value (or valueHash for large prose) is part of the identity so that two
+ * genuinely distinct corrections on the same day by the same actor produce
+ * distinct events, while re-appending an identical event stays idempotent.
+ */
+export function stableEventId(
+  subject: string,
+  asOf: string,
+  event: ClaimEventKind,
+  actor: string,
+  value?: string,
+): string {
+  const key = `${subject}|${asOf}|${event}|${actor}|${value ?? ""}`;
+  return `evt_${createHash("sha256").update(key, "utf8").digest("hex").slice(0, 16)}`;
+}
+
+/** Parse an NDJSON string into a list of ClaimEvents (skips blank lines). */
+export function parseNdjson(ndjson: string): ClaimEvent[] {
+  return ndjson
+    .split("\n")
+    .filter((l) => l.trim().length > 0)
+    .map((l) => JSON.parse(l) as ClaimEvent);
+}
+
+/** Serialize a ClaimEvent to a single NDJSON line (no trailing newline). */
+export function serializeEvent(event: ClaimEvent): string {
+  return JSON.stringify(event);
+}
+
+/** Build a lineage chain for a subject from the flat event list. */
+export function buildLineage(events: ClaimEvent[], subject: string): ClaimLineage | null {
+  const relevant = events.filter((e) => e.subject === subject);
+  if (relevant.length === 0) return null;
+  // Sort newest first by ts.
+  const sorted = [...relevant].sort((a, b) => b.ts.localeCompare(a.ts));
+  return {
+    subject,
+    current: sorted[0],
+    history: sorted,
+  };
+}
+
+/**
+ * Query the value of a subject as of a given ISO date.
+ * Returns the most-recent event whose asOf ≤ queryDate, or null.
+ */
+export function queryAsOf(
+  events: ClaimEvent[],
+  subject: string,
+  queryDate: string,
+): ClaimEvent | null {
+  const candidates = events
+    .filter((e) => e.subject === subject && e.asOf <= queryDate)
+    .sort((a, b) => b.asOf.localeCompare(a.asOf) || b.ts.localeCompare(a.ts));
+  return candidates[0] ?? null;
+}
+
+/** Project current-state knowledge graph from the ledger. */
+export function projectGraph(events: ClaimEvent[], app: string): KnowledgeGraph {
+  const bySubject = new Map<string, ClaimEvent[]>();
+  for (const e of events) {
+    const list = bySubject.get(e.subject) ?? [];
+    list.push(e);
+    bySubject.set(e.subject, list);
+  }
+
+  const nodes: KnowledgeGraphNode[] = [];
+  for (const [subject, evts] of bySubject) {
+    const sorted = [...evts].sort((a, b) => b.ts.localeCompare(a.ts));
+    const current = sorted[0];
+    nodes.push({
+      subject,
+      currentValue: current.value,
+      provenance: current.provenance,
+      asOf: current.asOf,
+      sourceRef: current.sourceRef,
+      latestEventId: current.id,
+      historyCount: evts.length,
+    });
+  }
+
+  nodes.sort((a, b) => a.subject.localeCompare(b.subject));
+  return {
+    generatedAt: new Date().toISOString(),
+    app,
+    nodes,
+  };
+}
+
+/**
+ * Project temporal SEO metadata per page from the ledger.
+ * `pageClaimsMap` maps a page route → array of claim subjects surfaced on that page.
+ */
+export function projectTemporalSeo(
+  events: ClaimEvent[],
+  pageClaimsMap: Map<string, string[]>,
+): TemporalSeo[] {
+  const result: TemporalSeo[] = [];
+  for (const [page, subjects] of pageClaimsMap) {
+    const relevantEvents = events.filter((e) => subjects.includes(e.subject));
+    if (relevantEvents.length === 0) continue;
+
+    const genesisDates = relevantEvents
+      .filter((e) => e.event === "genesis")
+      .map((e) => e.asOf)
+      .sort();
+    const updateDates = relevantEvents
+      .filter((e) => e.event === "verify-update" || e.event === "genesis")
+      .map((e) => e.asOf)
+      .sort();
+
+    const datePublished = genesisDates[0] ?? updateDates[0] ?? relevantEvents[0].asOf;
+    const dateModified = updateDates[updateDates.length - 1] ?? datePublished;
+    const temporalCoverage =
+      datePublished !== dateModified ? `${datePublished}/${dateModified}` : undefined;
+
+    result.push({ page, datePublished, dateModified, temporalCoverage });
+  }
+  return result.sort((a, b) => a.page.localeCompare(b.page));
+}

package/src/share/knowledge/plan.ts

@@ -0,0 +1,122 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+RFC-0216: Content Maintenance Plan — shared contracts and task-id hashing. The
+planner is a pure consolidator over RFC-0213 (freshness ledger), RFC-0214 (source
+outbox), and RFC-0215 (derivation states). Each signal becomes a deduplicated
+MaintenanceTask with a pre-deadline dueAt, owner, criticality, and the originating
+Diagnostic rule ids. Framework-free; no filesystem access.
+</purpose>
+<keywords>RFC-0216, CKL, maintenance, plan, task, criticality, calendar</keywords>
+<responsibilities>
+  <item>Define MaintenanceTask, MaintenancePlan, Criticality, MaintenanceTrigger.</item>
+  <item>Stable task id = sha256 of (subject + trigger) so re-runs are idempotent.</item>
+  <item>Compute pre-deadline dueAt from validUntil − leadTime or reviewDueAt.</item>
+</responsibilities>
+<non-goals>
+  <item>Do not read the filesystem or fetch sources — the kernel command does that.</item>
+  <item>Do not emit Diagnostics — tasks are the plan's output; the gate reads plan.gate.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<MODULE_MAP>
+  <entry key="MaintenanceTask / MaintenancePlan">Core plan contracts.</entry>
+  <entry key="stableTaskId">Idempotent hash for (subject, trigger).</entry>
+  <entry key="computeDueAt">Pre-deadline task date from policy + signal.</entry>
+</MODULE_MAP>
+<CHANGE_SUMMARY>
+  <item>RFC-0216: initial maintenance plan contracts.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { createHash } from "node:crypto";
+
+export type MaintenanceTrigger =
+  "review-due" | "expiring-soon" | "expired" | "source-diverged" | "derived-outdated";
+
+export type Criticality = "advisory" | "important" | "blocking";
+
+export interface MaintenanceTask {
+  /** Stable hash of (subject + trigger) — idempotent across plan builds. */
+  id: string;
+  subject: string;
+  trigger: MaintenanceTrigger;
+  /** Pre-deadline: validUntil − leadTime, or reviewDueAt, or today for already-expired/diverged. */
+  dueAt: string;
+  criticality: Criticality;
+  owner: string;
+  /** Originating Diagnostic rule ids (e.g. "CKL-FRESH-02 apps/…/offer.claims.yaml:3"). */
+  diagnostics: string[];
+  status: "open" | "routed" | "done";
+}
+
+export interface MaintenancePlan {
+  generatedAt: string | null;
+  site: string;
+  tasks: MaintenanceTask[];
+  gate: {
+    /** Amber: important + expired, advisory + any, or important + expiring. Ships with flag. */
+    amber: number;
+    /** Red: blocking + expired/diverged. Blocks build. */
+    red: number;
+  };
+}
+
+/** Deterministic task id — hash of (subject, trigger). */
+export function stableTaskId(subject: string, trigger: MaintenanceTrigger): string {
+  return `t_${createHash("sha256").update(`${subject}:${trigger}`, "utf8").digest("hex").slice(0, 16)}`;
+}
+
+/**
+ * Compute a pre-deadline dueAt for a task.
+ * - For time-based signals: validUntil − leadTimeDays (clamped to today if already past).
+ * - For already-expired or event-driven signals: today (already overdue).
+ */
+export function computeDueAt(opts: {
+  validUntil?: string;
+  reviewDueAt?: string;
+  leadTimeDays: number;
+  today: string;
+}): string {
+  const { validUntil, reviewDueAt, leadTimeDays, today } = opts;
+  if (validUntil) {
+    // Subtract leadTimeDays by finding (validUntil in ms) - (leadTimeDays * ms/day).
+    const vu = Date.parse(`${validUntil}T00:00:00Z`);
+    if (!Number.isNaN(vu)) {
+      const early = new Date(vu - leadTimeDays * 86_400_000).toISOString().slice(0, 10);
+      if (early > today) return early;
+    }
+    return today;
+  }
+  if (reviewDueAt) return reviewDueAt < today ? today : reviewDueAt;
+  return today;
+}
+
+/** Default gate policy for a trigger × criticality pair. */
+export function defaultCriticality(trigger: MaintenanceTrigger): Criticality {
+  if (trigger === "expired") return "important";
+  if (trigger === "source-diverged") return "important";
+  return "advisory";
+}
+
+/**
+ * The single source of truth for the red (build-blocking) gate verdict, shared by
+ * content.plan.build and (future) APPS_CHECK so the two never diverge. A task is
+ * red iff it is `blocking` criticality AND its claim no longer matches reality,
+ * has drifted from its source/derivation, or its required comparative-commercial
+ * source review is due.
+ */
+export function isRedTask(
+  task: Pick<MaintenanceTask, "criticality" | "trigger" | "status">,
+): boolean {
+  if (task.status === "done") return false;
+  if (task.criticality !== "blocking") return false;
+  return (
+    task.trigger === "review-due" ||
+    task.trigger === "expired" ||
+    task.trigger === "source-diverged" ||
+    task.trigger === "derived-outdated"
+  );
+}
+
+export const GENERATED_MARKER =
+  "GENERATED. Do not change this line unless the file contains project specific changes.";

package/src/share/knowledge/source.ts

@@ -0,0 +1,170 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+RFC-0214: external source binding. A source descriptor names an external authority
+and how to obtain a value (kind, endpoint, extraction, expected type, check cadence,
+tolerance). A claim's sourceRef resolves to a descriptor; the shared Truth Monitor
+fetches it on a cadence and compares the observed value to the asserted one. This
+module is the framework-free contract: the zod descriptor schema, value extraction,
+and tolerance comparison — reused by source.binding.validate and source.monitor.run.
+</purpose>
+<non-goals>
+  <item>Do not perform network I/O — the monitor command/worker fetches; this module only shapes + compares.</item>
+  <item>Do not parse HTML selectors here — that lives in the worker runtime (browser/DOM); the shared lib handles JSON.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0214: initial source descriptor schema, JSON extraction, tolerance compare.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { z } from "zod";
+
+export const SOURCE_KINDS = ["http-json", "http-html-selector", "rest-api", "manual"] as const;
+export type SourceKind = (typeof SOURCE_KINDS)[number];
+
+const ISO8601_DURATION = /^P(?:\d+Y)?(?:\d+M)?(?:\d+W)?(?:\d+D)?(?:T(?:\d+H)?(?:\d+M)?(?:\d+S)?)?$/;
+
+export const sourceToleranceSchema = z.object({
+  kind: z.enum(["exact", "relative", "absolute"]),
+  value: z.number().nonnegative(),
+});
+export type SourceTolerance = z.infer<typeof sourceToleranceSchema>;
+
+export const sourceDescriptorSchema = z
+  .object({
+    id: z.string().min(1),
+    title: z.string().min(1),
+    kind: z.enum(SOURCE_KINDS),
+    endpoint: z.string().url().optional(),
+    /** JSONPath-lite (`$.a.b[0].c`) or CSS selector (http-html-selector). */
+    extract: z.string().min(1).optional(),
+    expectedType: z.enum(["string", "integer", "number", "money", "date", "enum"]),
+    checkEvery: z
+      .string()
+      .regex(ISO8601_DURATION, "must be an ISO 8601 duration (e.g. P3M)")
+      .refine((v) => v !== "P" && v !== "PT", "duration must have at least one component"),
+    tolerance: sourceToleranceSchema.optional(),
+    residency: z.enum(["eu", "any"]).optional().default("eu"),
+    /** RFC-0241: the source's license (e.g. "CC-BY-4.0"), for third-party cited datasets. */
+    license: z.string().min(1).optional(),
+    /**
+     * RFC-0241: identity-firewall marker for external public-good sources that must be cited, never
+     * branded as a studio project. "ownership-forbidden" is enforced by a dedicated firewall check
+     * (e.g. `hdri.firewall.validate`), not by this schema.
+     */
+    firewall: z.enum(["ownership-forbidden"]).optional(),
+  })
+  .strict()
+  .superRefine((d, ctx) => {
+    if (d.kind !== "manual" && !d.endpoint) {
+      ctx.addIssue({
+        code: "custom",
+        message: `kind "${d.kind}" requires an endpoint`,
+        path: ["endpoint"],
+      });
+    }
+    if ((d.kind === "http-json" || d.kind === "http-html-selector") && !d.extract) {
+      ctx.addIssue({
+        code: "custom",
+        message: `kind "${d.kind}" requires an extract path`,
+        path: ["extract"],
+      });
+    }
+  });
+
+export type SourceDescriptor = z.infer<typeof sourceDescriptorSchema>;
+
+/**
+ * Read a JSONPath-lite expression `$.a.b[0].c` from a parsed JSON value.
+ * Supports dotted keys and `[index]` array access. Returns undefined on any miss.
+ */
+export function extractJsonPath(payload: unknown, path: string): unknown {
+  const trimmed = path.startsWith("$.")
+    ? path.slice(2)
+    : path.startsWith("$")
+      ? path.slice(1)
+      : path;
+  const tokens: string[] = [];
+  for (const seg of trimmed.split(".")) {
+    if (seg === "") continue;
+    const m = seg.match(/^([^[\]]*)((?:\[\d+\])*)$/);
+    if (!m) return undefined;
+    if (m[1]) tokens.push(m[1]);
+    for (const idx of m[2]!.matchAll(/\[(\d+)\]/g)) tokens.push(idx[1]!);
+  }
+  let cur: unknown = payload;
+  for (const tok of tokens) {
+    if (cur === null || cur === undefined) return undefined;
+    if (Array.isArray(cur)) {
+      const i = Number(tok);
+      if (!Number.isInteger(i)) return undefined;
+      cur = cur[i];
+    } else if (typeof cur === "object") {
+      cur = (cur as Record<string, unknown>)[tok];
+    } else {
+      return undefined;
+    }
+  }
+  return cur;
+}
+
+/** Pull the first number out of a string/number (handles "70 € / Monat", "39,120"). */
+export function coerceNumber(value: unknown): number | null {
+  if (typeof value === "number") return Number.isFinite(value) ? value : null;
+  if (typeof value !== "string") return null;
+  const cleaned = value
+    .replace(/\s/g, "")
+    .replace(/[.,](?=\d{3}(?:\D|$))/g, "") // drop thousands separators
+    .replace(",", "."); // remaining comma = decimal point
+  const m = cleaned.match(/-?\d+(?:\.\d+)?/);
+  return m ? Number(m[0]) : null;
+}
+
+/**
+ * Compare an observed value against the asserted one under a descriptor's tolerance.
+ * Numeric types compare numerically (with relative/absolute bands); others compare as
+ * normalized strings (exact). Returns whether the observed value is within tolerance.
+ */
+export function compareValues(
+  asserted: unknown,
+  observed: unknown,
+  expectedType: SourceDescriptor["expectedType"],
+  tolerance?: SourceTolerance,
+): { withinTolerance: boolean; assertedStr: string; observedStr: string } {
+  const assertedStr = String(asserted ?? "");
+  const observedStr = String(observed ?? "");
+  const numeric =
+    expectedType === "integer" || expectedType === "number" || expectedType === "money";
+
+  if (numeric) {
+    const a = coerceNumber(asserted);
+    const o = coerceNumber(observed);
+    if (a === null || o === null) {
+      return { withinTolerance: assertedStr === observedStr, assertedStr, observedStr };
+    }
+    const t = tolerance ?? { kind: "exact" as const, value: 0 };
+    let within: boolean;
+    if (t.kind === "exact") within = a === o;
+    else if (t.kind === "absolute") within = Math.abs(a - o) <= t.value;
+    else within = a === 0 ? o === 0 : Math.abs(a - o) / Math.abs(a) <= t.value; // relative
+    return { withinTolerance: within, assertedStr, observedStr };
+  }
+
+  const norm = (s: string) => s.replace(/\s+/g, " ").trim();
+  return { withinTolerance: norm(assertedStr) === norm(observedStr), assertedStr, observedStr };
+}
+
+/** One Truth Monitor finding, written to the outbox and surfaced by source.binding.validate. */
+export interface DivergenceRecord {
+  sourceId: string;
+  /** Canonical subject string of the bound claim. */
+  subject: string;
+  app: string;
+  assertedValue: string;
+  observedValue: string;
+  withinTolerance: boolean;
+  observedAt: string;
+  /** True when the source could not be fetched (CKL-SRC-04, info — not a divergence). */
+  unreachable?: boolean;
+}