@warpgogol/werkstatt-shared 0.2.0

package/src/share/image-provider.ts

@@ -0,0 +1,314 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+  [RFC-0152] The Image Provider Port — the rendering/optimization analogue of the
+  RFC-0141 content-source port. Defines "how an authored image becomes src + srcset"
+  as a swappable provider so the optimization backend (Cloudflare runtime today, a
+  CMS/DAM or build-time pipeline later) can change without touching any section or
+  component. Ships the `cloudflare-runtime` provider (Cloudflare Image Resizing via
+  /cdn-cgi/image) as the default.
+  [RFC-0204] Adds the `build-portable` provider that emits srcset from pre-generated
+  static width variants (no Cloudflare Image Transformations required).
+</purpose>
+<non-goals>
+  <item>Do not run sharp or any build-time optimization here — providers emit URLs only.</item>
+  <item>Do not resolve asset tokens — that is resolveImage / the content-source port.</item>
+  <item>Do not implement the cms-native provider yet (later phase).</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0152: introduced the Image Provider Port and the cloudflare-runtime provider.</item>
+  <item>RFC-0204: added ImageVariantManifest types and createBuildPortableProvider factory.</item>
+</CHANGE_SUMMARY>
+*/
+
+/** A resolved image to render. Astro's ImageMetadata is structurally assignable. */
+export interface ImageDescriptor {
+  /** Origin path: root-relative for in-repo assets ("/_astro/..") or an absolute URL (CMS/DAM). */
+  src: string;
+  /** Intrinsic width, when known — used to avoid upscaling the responsive ladder. */
+  width?: number;
+  /** Intrinsic height, when known. */
+  height?: number;
+}
+
+/** Output format requested from the provider. */
+export type ImageFormat = "webp" | "avif" | "auto";
+
+/** Quality presets. NOTE: Cloudflare expects a numeric quality — never the literal "max". */
+export const IMAGE_QUALITY_PRESETS = { low: 30, mid: 60, high: 80, max: 100 } as const;
+export type ImageQualityPreset = keyof typeof IMAGE_QUALITY_PRESETS;
+
+/** Default no-upscale responsive width ladder. */
+export const DEFAULT_IMAGE_WIDTHS: readonly number[] = [320, 480, 640, 768, 1024, 1280, 1536, 1920];
+
+export interface ImageRequest {
+  /** Candidate widths; defaults to DEFAULT_IMAGE_WIDTHS. Filtered to never exceed the intrinsic width. */
+  widths?: readonly number[];
+  /** <img sizes> hint; defaults to "100vw". */
+  sizes?: string;
+  /** Numeric quality OR a preset; resolved to a number for the provider. */
+  quality?: number | ImageQualityPreset;
+  /** Output format; defaults to "webp". */
+  format?: ImageFormat;
+}
+
+export interface ImageSources {
+  /** Fallback src (largest candidate). */
+  src: string;
+  /** Responsive srcset (`url 320w, url 640w, ...`); omitted when a single candidate. */
+  srcset?: string;
+  /** <img sizes>. */
+  sizes?: string;
+  /**
+   * Width of the fallback `src` variant in CSS pixels.
+   * Set by providers that select a specific variant (e.g. build-portable).
+   * When present, <ResponsiveImage> uses this instead of the intrinsic ImageMetadata width.
+   */
+  width?: number;
+  /**
+   * Height of the fallback `src` variant in CSS pixels.
+   * Derived from the selected variant width + original aspect ratio.
+   */
+  height?: number;
+}
+
+/** The Image Provider Port. Every optimization backend implements this single interface. */
+export interface ImageProvider {
+  readonly id: "cloudflare-runtime" | "cms-native" | "build-portable";
+  buildSources(descriptor: ImageDescriptor, request?: ImageRequest): ImageSources;
+}
+
+const clamp = (n: number, lo: number, hi: number): number => Math.min(hi, Math.max(lo, n));
+
+/** Resolve a preset or numeric quality to a Cloudflare-valid integer (1..100). */
+export function resolveImageQuality(quality?: number | ImageQualityPreset): number {
+  if (typeof quality === "number") return clamp(Math.round(quality), 1, 100);
+  if (quality && quality in IMAGE_QUALITY_PRESETS) return IMAGE_QUALITY_PRESETS[quality];
+  return IMAGE_QUALITY_PRESETS.high;
+}
+
+/** Build a sorted, de-duplicated, no-upscale candidate width list. */
+export function candidateWidths(
+  intrinsic?: number,
+  widths: readonly number[] = DEFAULT_IMAGE_WIDTHS,
+): number[] {
+  const base = widths.filter((w) => !intrinsic || w < intrinsic);
+  const set = new Set(base);
+  if (intrinsic && intrinsic > 0) set.add(intrinsic);
+  const sorted = [...set].sort((a, b) => a - b);
+  return sorted.length > 0 ? sorted : intrinsic ? [intrinsic] : [...widths];
+}
+
+function isAbsoluteUrl(src: string): boolean {
+  return /^https?:\/\//i.test(src) || src.startsWith("data:");
+}
+
+/**
+ * cloudflare-runtime provider (RFC-0152 default).
+ * When Cloudflare Image Transformations are enabled (PUBLIC_CF_IMAGE_TRANSFORM=on),
+ * emits /cdn-cgi/image/<opts>/<origin> URLs resolved at request time by Cloudflare —
+ * a responsive srcset for in-repo assets and remote CMS URLs. `onerror=redirect` only
+ * helps when the feature IS enabled but a specific transform errors; it does NOT save a
+ * zone where the feature is OFF (those URLs 404). Hence the safe passthrough default.
+ */
+/**
+ * Whether to emit /cdn-cgi/image transform URLs (baked at build time).
+ *
+ * IMPORTANT: /cdn-cgi/image only works when Cloudflare Image Transformations are
+ * ENABLED on the zone. When the feature is OFF, those URLs return 404 with NO
+ * `onerror` fallback — so emitting them unconditionally breaks every image on a
+ * zone that has not enabled the feature. Therefore the safe default is OFF: serve
+ * the raw origin asset (always 200, no resize, no srcset). Opt in per app by
+ * setting `PUBLIC_CF_IMAGE_TRANSFORM=on` once Transformations are enabled on the
+ * zone — then the provider emits the responsive /cdn-cgi/image srcset.
+ */
+function cloudflareTransformEnabled(): boolean {
+  try {
+    const env = (import.meta as ImportMeta & { env?: Record<string, string | undefined> }).env;
+    return env?.PUBLIC_CF_IMAGE_TRANSFORM === "on";
+  } catch {
+    return false;
+  }
+}
+
+export const cloudflareRuntimeProvider: ImageProvider = {
+  id: "cloudflare-runtime",
+  buildSources(descriptor, request = {}) {
+    // data: URLs cannot be resized — pass straight through.
+    if (descriptor.src.startsWith("data:")) {
+      return { src: descriptor.src };
+    }
+    // Safe default: until Cloudflare Image Transformations are enabled on the zone
+    // (PUBLIC_CF_IMAGE_TRANSFORM=on), serve the raw origin asset — it always deploys
+    // to dist/client/_astro and is served 200. No /cdn-cgi/image, no srcset, no resize.
+    if (!cloudflareTransformEnabled()) {
+      return { src: descriptor.src };
+    }
+    const quality = resolveImageQuality(request.quality);
+    const format: ImageFormat = request.format ?? "webp";
+    const origin = isAbsoluteUrl(descriptor.src)
+      ? descriptor.src
+      : descriptor.src.replace(/^\//, "");
+
+    const url = (w: number): string => {
+      const opts = `onerror=redirect,width=${w},quality=${quality},format=${format}`;
+      return `/cdn-cgi/image/${opts}/${origin}`;
+    };
+
+    const widths = candidateWidths(descriptor.width, request.widths);
+    const largest = widths[widths.length - 1] ?? descriptor.width ?? 1280;
+    const srcset = widths.length > 1 ? widths.map((w) => `${url(w)} ${w}w`).join(", ") : undefined;
+
+    return {
+      src: url(largest),
+      srcset,
+      sizes: srcset ? (request.sizes ?? "100vw") : undefined,
+    };
+  },
+};
+
+let activeProvider: ImageProvider = cloudflareRuntimeProvider;
+
+/** Return the active default image provider. */
+export function getDefaultImageProvider(): ImageProvider {
+  return activeProvider;
+}
+
+/** Override the active default image provider (app/deploy-target wiring, tests). */
+export function setDefaultImageProvider(provider: ImageProvider): void {
+  activeProvider = provider;
+}
+
+/** Convenience: build sources via the active default provider. */
+export function buildImageSources(
+  descriptor: ImageDescriptor,
+  request?: ImageRequest,
+): ImageSources {
+  return activeProvider.buildSources(descriptor, request);
+}
+
+// ---------------------------------------------------------------------------
+// RFC-0204: build-portable provider — pre-generated responsive variants.
+// ---------------------------------------------------------------------------
+
+/** A single pre-generated width variant for one source image. */
+export interface ImageVariant {
+  /** CSS pixel width of this variant. */
+  width: number;
+  /** Root-relative URL served from public/_img/<hash>/<width>.webp (always deployed). */
+  url: string;
+}
+
+/** Manifest entry for one source image origin. */
+export interface ImageVariantEntry {
+  /**
+   * Origin src key — matches the exact `descriptor.src` value emitted by resolveImage
+   * (e.g. "/_astro/katrin-hennings.<hash>.webp"). Used as the lookup key.
+   */
+  origin: string;
+  /** Intrinsic width of the source, when known. */
+  intrinsicWidth?: number;
+  /** Intrinsic height of the source, when known. */
+  intrinsicHeight?: number;
+  /** Pre-generated variants sorted ascending by width, never exceeding intrinsicWidth. */
+  variants: ImageVariant[];
+  /**
+   * SHA-256 hex digest of the source file bytes at generation time.
+   * Used by `image.variants.generate` to detect source changes and invalidate
+   * stale derived variants (same contract as video.variants.generate RFC-0210).
+   */
+  sourceHash?: string;
+}
+
+/** Top-level manifest written by `image.variants.generate` and read by createBuildPortableProvider. */
+export interface ImageVariantManifest {
+  version: 1;
+  /** Map from origin src → entry (stable content-path key, e.g. /src/content/business-profile/de/assets/portrait.webp). */
+  byOrigin: Record<string, ImageVariantEntry>;
+  /**
+   * Secondary lookup: maps the bare image basename (no hash, no ext) to the entry origin key.
+   * Allows the provider to resolve Astro-hashed descriptor.src values like
+   * "/_astro/katrin-hennings.BIwCI837.webp" → entry via "katrin-hennings".
+   */
+  byBasename: Record<string, string>;
+}
+
+/**
+ * Extract the bare basename (no hash suffix, no extension) from an Astro-hashed URL.
+ * "/_astro/katrin-hennings.CrtmuSkJ.webp" → "katrin-hennings"
+ * "/src/content/business-profile/de/assets/katrin-hennings.webp" → "katrin-hennings"
+ *
+ * Vite/Rollup content hashes use base64url characters (a-z A-Z 0-9 - _), not pure hex.
+ * The hash is always exactly 8 characters before the final extension.
+ */
+function extractBasename(src: string): string {
+  const filename = src.split("/").pop() ?? "";
+  // Strip extension
+  const noExt = filename.replace(/\.[a-z0-9]+$/i, "");
+  // Strip Vite/Rollup hash suffix: ".<8-char alphanumeric-dash-underscore>"
+  return noExt.replace(/\.[a-zA-Z0-9_-]{8}$/, "");
+}
+
+/**
+ * RFC-0204: build-portable provider factory.
+ *
+ * Reads a pre-generated `ImageVariantManifest` (produced by `image.variants.generate`)
+ * and emits a responsive `srcset` from static width-variant URLs. Falls back to
+ * `{ src: descriptor.src }` for images not in the manifest (SVG, data:, unmanaged).
+ *
+ * Lookup strategy: primary by exact `byOrigin` key (content-relative path);
+ * fallback by `byBasename` to handle Astro-hashed `/_astro/<name>.<hash>.webp` URLs.
+ *
+ * IMPORTANT: synchronous — do NOT import Astro `astro:assets` / `<Image>` / `getImage`.
+ */
+export function createBuildPortableProvider(manifest: ImageVariantManifest): ImageProvider {
+  return {
+    id: "build-portable",
+    buildSources(descriptor, request = {}) {
+      if (!descriptor.src || descriptor.src.startsWith("data:")) {
+        return { src: descriptor.src };
+      }
+
+      // Primary: exact origin key match (e.g. /src/content/.../portrait.webp)
+      let entry = manifest.byOrigin[descriptor.src];
+
+      // Secondary: match by stripped basename for Astro-hashed URLs (/_astro/<name>.<hash>.webp)
+      if (!entry && manifest.byBasename) {
+        const basename = extractBasename(descriptor.src);
+        const originKey = manifest.byBasename[basename];
+        if (originKey) entry = manifest.byOrigin[originKey];
+      }
+
+      if (!entry || entry.variants.length === 0) {
+        return { src: descriptor.src };
+      }
+
+      const widths = candidateWidths(entry.intrinsicWidth, request.widths);
+      const available = entry.variants.filter((v) => widths.includes(v.width));
+      const sorted = available.length > 0 ? available : entry.variants;
+
+      const largest = sorted[sorted.length - 1];
+      if (!largest) return { src: descriptor.src };
+
+      const srcset =
+        sorted.length > 1 ? sorted.map((v) => `${v.url} ${v.width}w`).join(", ") : undefined;
+
+      // Derive variant height from the original aspect ratio
+      const aspectRatio =
+        entry.intrinsicWidth && entry.intrinsicHeight
+          ? entry.intrinsicHeight / entry.intrinsicWidth
+          : undefined;
+      const variantHeight =
+        aspectRatio !== undefined ? Math.round(largest.width * aspectRatio) : undefined;
+
+      return {
+        src: largest.url,
+        srcset,
+        sizes: srcset ? (request.sizes ?? "100vw") : undefined,
+        width: largest.width,
+        height: variantHeight,
+      };
+    },
+  };
+}

package/src/share/index.ts

@@ -0,0 +1,86 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+Deprecated compatibility barrel for @warpgogol/werkstatt-shared/share (RFC-0264). New code MUST
+import from the domain subpath instead — see the map in
+packages/share/AGENTS.md. This root barrel re-exports each subpath module
+unchanged (never new logic) so existing consumers keep working while they
+migrate. The `page` and `i18n` domains have completed their migration wave:
+their re-export blocks are deleted here — import them from
+`@warpgogol/werkstatt-shared/share/page` / `@warpgogol/werkstatt-shared/share/i18n`.
+</purpose>
+<non-goals>
+  <item>Do not add business logic here — keep as a pure re-export barrel.</item>
+  <item>Do not re-add the page or i18n domains — those are fully migrated; import the subpath directly.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>Initial barrel created alongside package extraction.</item>
+  <item>RFC-0264: split into subpath entry points. Root barrel shrunk to a deprecated compatibility surface; page and i18n domains fully migrated (root re-export blocks deleted, all consumers rewritten).</item>
+  <item>C6: image-utils.ts shim deleted; root barrel re-exports from @warpgogol/werkstatt-site/content-source directly. page-handler.ts shim deleted; export map points to resolve-route.ts.</item>
+</CHANGE_SUMMARY>
+*/
+
+/** @deprecated import from "@warpgogol/werkstatt-shared/share/content" instead */
+export * from "./content/index.ts";
+/** @deprecated import from "@warpgogol/werkstatt-shared/share/semantic" instead */
+export * from "./semantic/index.ts";
+/** @deprecated import from "@warpgogol/werkstatt-shared/share/middleware" instead */
+export * from "./middleware/language-redirect.ts";
+/** @deprecated import from "@warpgogol/werkstatt-shared/share/entitlement" instead */
+export * from "./entitlement.ts";
+/** @deprecated import from "@warpgogol/werkstatt-shared/share/offer-capacity" instead */
+export * from "./offer-capacity.ts";
+/** @deprecated import from "@warpgogol/werkstatt-shared/share/knowledge" instead */
+export * from "./knowledge/index.ts";
+/** @deprecated import from "@warpgogol/werkstatt-shared/share/schemas" instead */
+export * from "./schemas/index.ts";
+/** @deprecated import from "@warpgogol/werkstatt-shared/share/feature-policy" instead */
+export * from "./feature-policy.ts";
+/** @deprecated import from "@warpgogol/werkstatt-shared/share/counter-utils" instead */
+export * from "./counter-utils.ts";
+/** @deprecated import from "@warpgogol/werkstatt-shared/share/image-provider" instead */
+export * from "./image-provider.ts";
+/** @deprecated import from "@warpgogol/werkstatt-shared/share/runtime-context" instead */
+export { EMPTY_RUNTIME_CONTEXT } from "./runtime-context.ts";
+export type { RuntimeContext } from "./runtime-context.ts";
+/** @deprecated import from "@warpgogol/werkstatt-shared/share/visibility" instead */
+export * from "./visibility.ts";
+/** @deprecated import from "@warpgogol/werkstatt-shared/share/wrap-inline-numbers" instead */
+export * from "./wrap-inline-numbers.ts";
+/** @deprecated import from "@warpgogol/werkstatt-shared/share/text-normalize" instead */
+export * from "./text-normalize.ts";
+// dev-props-validator is NOT re-exported from the root barrel. It imports
+// node:fs/promises and @warpgogol/werkstatt-shared/ontology/schemas (which also imports node:fs),
+// so re-exporting it here pulls Node-only modules into the Vite client bundle.
+// The sole consumer (resolve-route.ts) imports it via relative path.
+// Import from "@warpgogol/werkstatt-shared/share/dev-props-validator" subpath directly if needed.
+/** @deprecated import from "@warpgogol/werkstatt-shared/share/rfc0042-utils" instead */
+export { need, cast, withDefault } from "./rfc0042-utils.ts";
+/** @deprecated import from "@warpgogol/werkstatt-shared/share/shared-context" instead */
+export * from "./shared-context.ts";
+/** @deprecated import from "@warpgogol/werkstatt-shared/share/content-discipline" instead */
+export * from "./content-discipline/types.ts";
+export * from "./content-discipline/parsers.ts";
+/** @deprecated import from "@warpgogol/werkstatt-shared/share/legal" instead */
+export { resolveTranslationContext, TRANSLATION_STATUSES } from "./legal/translation-policy.ts";
+export type {
+  TranslationStatus,
+  PageTranslationPolicy,
+  ResolvedTranslationContext,
+} from "./legal/translation-policy.ts";
+/** @deprecated import from "@warpgogol/werkstatt-shared/share/material-credits" instead */
+export {
+  parseMaterialCreditMap,
+  findMaterialCredit,
+  creditByTarget,
+  buildMaterialCreditJsonLd,
+  langFromCreditPath,
+} from "./material-credits.ts";
+export type { MaterialCreditRecord, RawMaterialCreditMap } from "./material-credits.ts";
+/** @deprecated import from "@warpgogol/werkstatt-shared/share/attribution-display" instead */
+export * from "./attribution-display.ts";
+/** @deprecated import from "@warpgogol/werkstatt-shared/share/string-utils" instead */
+export { toKebabCase } from "./string-utils.ts";
+/** @deprecated import from "@warpgogol/werkstatt-shared/share/css-value-normalize" instead */
+export { normalizeCssValue } from "./css-value-normalize.ts";

package/src/share/knowledge/claim.ts

@@ -0,0 +1,129 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+RFC-0211: the Content Knowledge Lifecycle (CKL) claim model. A claim is the
+atomic unit of durable site truth — the binding of a value to a subject field,
+qualified by provenance and time. Framework-free types + the canonical subject
+address parser/formatter shared by every CKL command and validator (RFC-0212..0218).
+</purpose>
+<non-goals>
+  <item>Do not read the filesystem, evaluate freshness, hash derivations, or emit Diagnostics — those live in the kernel checks and later CKL modules.</item>
+  <item>Do not define the source descriptor (RFC-0214) or the ledger event (RFC-0217) — only the in-content claim shape.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0211: initial claim model + subject address codec.</item>
+</CHANGE_SUMMARY>
+*/
+
+/** RFC-0211: how a value is known. */
+export type ClaimProvenanceKind = "external" | "derived" | "asserted" | "generated";
+
+export const CLAIM_PROVENANCE_KINDS: readonly ClaimProvenanceKind[] = [
+  "external",
+  "derived",
+  "asserted",
+  "generated",
+] as const;
+
+/** Confidence an author/agent attaches to an asserted value. */
+export type ClaimConfidence = "high" | "medium" | "low";
+
+/**
+ * A content address — the subject a claim is about. Reuses RFC-0045 coordinates:
+ * a `collection`, a locale-independent `file` stem (RFC-0044), and a dotted
+ * `fieldPath` into the record. `lang` is present for language-scoped collections
+ * (e.g. `business/{lang}/…`).
+ */
+export interface ClaimSubject {
+  collection: string;
+  file: string;
+  fieldPath: string[];
+  lang?: string;
+}
+
+/** The temporal validity window of a claim (RFC-0212/0213). */
+export interface ClaimValidity {
+  /** ISO date the value was last verified / asserted. */
+  asOf: string;
+  /** ISO date after which the claim is stale. */
+  validUntil?: string;
+  /** ISO 8601 duration, e.g. "P3M" — recurring review cadence. */
+  reviewEvery?: string;
+}
+
+/**
+ * A claim: the binding of a value to a subject field, qualified by provenance and
+ * time. Stored per-field in a `<record>.claims.yaml` sidecar (RFC-0212); the value
+ * itself stays in the record body — a claim annotates, it never wraps the value.
+ */
+export interface Claim {
+  subject: ClaimSubject;
+  provenance: ClaimProvenanceKind;
+  validity?: ClaimValidity;
+  /** → source descriptor id (RFC-0214) when provenance = external. */
+  sourceRef?: string;
+  /** Source subject (RFC-0215) when provenance = derived. */
+  derivedFrom?: ClaimSubject;
+  /** Normalized hash of the source value at derivation time (RFC-0215). */
+  sourceHash?: string;
+  /** Responsible agent/human handle — routing (RFC-0216). */
+  owner?: string;
+  confidence?: ClaimConfidence;
+}
+
+// ─── Canonical subject address codec ────────────────────────────────────────
+// String form: `<collection>/[<lang>/]<file>#<dotted.field.path>`
+//   business/de/location#residents
+//   business/uk/offer#price.monthly
+//   surface#someField                (no lang, no nested path)
+// `lang` is recognized as a 2-letter segment immediately after the collection.
+
+const TWO_LETTER_LANG = /^[a-z]{2}$/;
+
+export class ClaimSubjectParseError extends Error {}
+
+/** Parse the canonical subject string into a ClaimSubject. Throws on malformed input. */
+export function parseClaimSubject(input: string): ClaimSubject {
+  const hashIndex = input.indexOf("#");
+  if (hashIndex < 0) {
+    throw new ClaimSubjectParseError(
+      `Subject "${input}" is missing the "#fieldPath" part (expected <collection>/[<lang>/]<file>#<field>)`,
+    );
+  }
+  const pathPart = input.slice(0, hashIndex);
+  const fieldPart = input.slice(hashIndex + 1);
+  const segments = pathPart.split("/").filter((s) => s.length > 0);
+  if (segments.length < 2) {
+    throw new ClaimSubjectParseError(
+      `Subject "${input}" must have at least <collection>/<file> before "#"`,
+    );
+  }
+  if (fieldPart.length === 0) {
+    throw new ClaimSubjectParseError(`Subject "${input}" has an empty fieldPath after "#"`);
+  }
+  const collection = segments[0]!;
+  let lang: string | undefined;
+  let fileSegments = segments.slice(1);
+  if (fileSegments.length >= 2 && TWO_LETTER_LANG.test(fileSegments[0]!)) {
+    lang = fileSegments[0]!;
+    fileSegments = fileSegments.slice(1);
+  }
+  return {
+    collection,
+    lang,
+    file: fileSegments.join("/"),
+    fieldPath: fieldPart.split("."),
+  };
+}
+
+/** Render a ClaimSubject back to its canonical string. Inverse of parseClaimSubject. */
+export function formatClaimSubject(subject: ClaimSubject): string {
+  const langPart = subject.lang ? `${subject.lang}/` : "";
+  return `${subject.collection}/${langPart}${subject.file}#${subject.fieldPath.join(".")}`;
+}
+
+/** Structural equality on subjects (ignores undefined-vs-absent lang differences). */
+export function claimSubjectsEqual(a: ClaimSubject, b: ClaimSubject): boolean {
+  return formatClaimSubject(a) === formatClaimSubject(b);
+}

package/src/share/knowledge/derivation.ts

@@ -0,0 +1,55 @@
+/*
+<MODULE_CONTRACT>
+<purpose>
+RFC-0215: derived-content staleness. A translation/copy is a `derived` claim that
+remembers which source it came from (derivedFrom) and a normalized hash of that
+source at derivation time (sourceHash). When the source changes, the stored hash
+no longer matches → the derivative is `outdated`. Framework-free hashing + compare,
+shared with the enriched-content frozen-provenance model (RFC-0197/0207).
+</purpose>
+<non-goals>
+  <item>Do not read the filesystem or parse sidecars — the kernel command does that.</item>
+  <item>Do not translate or regenerate content — only detect staleness.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0215: initial normalized hasher + state compare.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { createHash } from "node:crypto";
+
+export type DerivedState = "current" | "outdated" | "source-missing";
+
+/**
+ * Normalize a source value so cosmetic edits (whitespace reflow, markdown emphasis)
+ * do not falsely mark a derivative outdated, while wording/number changes do.
+ * Whitespace is collapsed; common markdown punctuation is stripped; result trimmed.
+ */
+export function normalizeForHash(value: string): string {
+  return value
+    .replace(/[*_`~#>]/g, "")
+    .replace(/[[\]()]/g, "")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+/** Hash a value (after normalization) into a stable "sha256:<hex>" string. */
+export function hashSourceValue(value: string): string {
+  const hex = createHash("sha256").update(normalizeForHash(value), "utf8").digest("hex");
+  return `sha256:${hex}`;
+}
+
+/**
+ * Compare a derivative's stored sourceHash against a freshly computed hash of the
+ * current source value. A missing stored hash counts as `outdated` (never stamped).
+ */
+export function derivedState(
+  storedHash: string | undefined,
+  currentSourceValue: string | undefined,
+): { state: DerivedState; currentHash?: string } {
+  if (currentSourceValue === undefined) return { state: "source-missing" };
+  const currentHash = hashSourceValue(currentSourceValue);
+  if (!storedHash || storedHash !== currentHash) return { state: "outdated", currentHash };
+  return { state: "current", currentHash };
+}