@tokenoftrust/storefront-runner 1.4.2-rc.0 → 2.0.0

package/packages/public-runtime/src/integration/resolve.ts

@@ -0,0 +1,465 @@
+/**
+ * The server-computed effective-plan resolver (ADR 0014 C1
+ * `integration-schema-shared`, S1/S2 `integration-phases-fixed-dag`; ext-kernel-03).
+ *
+ * One resolver merges the three declaration origins — platform adapters,
+ * tenant-local declarations, and installed managed apps — into a single immutable
+ * {@link EffectivePlan} for one tenant/environment/version. It is a PURE,
+ * SYNCHRONOUS function over already-materialized inputs: it performs no network,
+ * disk, or KV access, so it is safe on the render hot path. Materializing the
+ * declarations (Gitea/KV/D1 → in-memory) is the control plane's job; resolving
+ * them into a plan is this function's, and the two never blur.
+ *
+ * The resolver is FAIL-CLOSED: an invalid manifest, a missing entry asset (a
+ * partially materialized version), a secret-bearing or off-schema public config,
+ * a duplicate app, or an unresolvable order yields violations and NO plan — never
+ * a partial one. It is DETERMINISTIC: the same set of declarations resolves to a
+ * byte-identical plan (including `planRevision`) regardless of input array order,
+ * and a plan-affecting change to any input changes `planRevision`, which is the
+ * component the candidate/edge-cache identity folds in.
+ */
+import type { ContractResult, ContractViolation } from "./result.js";
+import { Violations, isPlainObject, joinPath } from "./result.js";
+import { EFFECTIVE_PLAN_SCHEMA_VERSION } from "./version.js";
+import type { BrowserEnvironment } from "./environment.js";
+import { validateBrowserEnvironment } from "./environment.js";
+import { phaseRank, type ReservedPhase } from "./phases.js";
+import {
+  validateIntegrationManifest,
+  INTEGRATION_ORIGINS,
+  type IntegrationManifest,
+  type IntegrationOrigin,
+  type IntegrationDependency,
+  type IntegrationContribution,
+} from "./manifest.js";
+import type {
+  EffectivePlan,
+  PlanIntegration,
+  NormalizedContribution,
+  SourceReference,
+} from "./plan.js";
+import type { CommerceEventType } from "./events.js";
+import { fnv1a128Hex, stableStringify } from "./digest.js";
+import { assertPlanBrowserSafe } from "./plan.js";
+import {
+  INTEGRATION_CSP_DIRECTIVES,
+  validateCspSourceSet,
+  type CspSourceSet,
+} from "./csp.js";
+import { findForbiddenFields } from "./secrets.js";
+
+/**
+ * One already-materialized declaration the resolver merges. The `manifest` is
+ * re-validated as defense-in-depth; `publicConfig` carries the resolved tenant
+ * values (never a schema); `materializedAssets` is the set of asset paths present
+ * for this integration's version — a missing entry asset blocks the whole plan.
+ */
+export interface IntegrationDeclarationInput {
+  origin: IntegrationOrigin;
+  /** Declaration id, adapter id, or board slug this integration traces to. */
+  ref: string;
+  manifest: IntegrationManifest;
+  publicConfig: Record<string, unknown>;
+  materializedAssets: readonly string[];
+}
+
+/** The complete, already-materialized input for one tenant/environment/version. */
+export interface ResolvePlanInput {
+  tenantPublicId: string;
+  environment: BrowserEnvironment;
+  declarations: readonly IntegrationDeclarationInput[];
+}
+
+const ORIGIN_RANK: Record<IntegrationOrigin, number> = {
+  "platform-adapter": 0,
+  "tenant-local": 1,
+  "managed-app": 2,
+};
+
+/**
+ * Resolve already-materialized declarations into one immutable effective plan.
+ * Returns `{ ok: true, value }` only when every input validates and every entry
+ * asset is present; otherwise `{ ok: false, violations }` with no plan.
+ */
+export function resolveEffectivePlan(
+  input: ResolvePlanInput,
+): ContractResult<EffectivePlan> {
+  const v = new Violations();
+
+  const envResult = validateBrowserEnvironment(input.environment);
+  if (!envResult.ok) {
+    for (const violation of prefix(envResult.violations, "environment")) v.items.push(violation);
+  }
+
+  if (typeof input.tenantPublicId !== "string" || input.tenantPublicId.length === 0) {
+    v.add("tenantPublicId", "type", "tenantPublicId must be a non-empty string.");
+  }
+
+  if (!Array.isArray(input.declarations)) {
+    v.add("declarations", "type", "declarations must be an array.");
+    return { ok: false, violations: v.items };
+  }
+
+  const seenAppIds = new Set<string>();
+  input.declarations.forEach((decl, i) => {
+    validateDeclaration(decl, i, seenAppIds, v);
+  });
+
+  if (!v.ok) return { ok: false, violations: v.items };
+
+  // Every declaration validated: build the plan. Canonical ordering by
+  // (origin, appId, version) makes the output independent of input array order.
+  const sorted = [...input.declarations].sort(compareDeclarations);
+
+  const contributions: NormalizedContribution[] = [];
+  const orderNodes: OrderNode[] = [];
+  const orderEdges: OrderEdge[] = [];
+  const dependencies: IntegrationDependency[] = [];
+  const integrations: PlanIntegration[] = [];
+  const provenance: SourceReference[] = [];
+  const publicConfig: Record<string, Record<string, unknown>> = {};
+  const consentSet = new Set<string>();
+  const cspMerge = new Map<string, Set<string>>();
+
+  sorted.forEach((decl, integrationIndex) => {
+    const { app, browser } = decl.manifest;
+    const source: SourceReference = {
+      origin: decl.origin,
+      ref: decl.ref,
+      appId: app.id,
+      version: app.version,
+      digest: app.digest,
+    };
+    provenance.push(source);
+    integrations.push({
+      origin: decl.origin,
+      appId: app.id,
+      version: app.version,
+      digest: app.digest,
+      executionTier: browser.executionTier,
+      // The declared entry asset — validated present in `materializedAssets` by
+      // validateDeclaration — is the exact-version module the runtime imports.
+      entry: {
+        url: browser.entry.asset,
+        format: browser.entry.format,
+        phase: browser.entry.phase,
+      },
+      consent: {
+        purposes: [...browser.consent.purposes],
+        loadWhen: browser.consent.loadWhen,
+      },
+      // Every declared event was cross-checked browser-deliverable by
+      // validateIntegrationManifest above (an unknown/reserved/verified-provider type
+      // fails the plan), so the set is safe to narrow to CommerceEventType for the wire.
+      events: [...browser.permissions.events] as CommerceEventType[],
+    });
+    publicConfig[app.id] = { ...decl.publicConfig };
+
+    for (const purpose of browser.consent.purposes) consentSet.add(purpose);
+    for (const directive of INTEGRATION_CSP_DIRECTIVES) {
+      const origins = browser.csp.sources[directive];
+      if (!origins || origins.length === 0) continue;
+      let set = cspMerge.get(directive);
+      if (!set) cspMerge.set(directive, (set = new Set()));
+      for (const origin of origins) set.add(origin);
+    }
+
+    const localContributionIds = new Set<string>();
+    browser.contributions.forEach((contribution: IntegrationContribution, declIndex: number) => {
+      const id = globalId(app.id, app.version, contribution.id);
+      contributions.push({
+        id,
+        origin: decl.origin,
+        phase: contribution.phase,
+        kind: contribution.kind,
+        source,
+      });
+      orderNodes.push({ id, phase: contribution.phase, integrationIndex, declIndex });
+      localContributionIds.add(contribution.id);
+    });
+
+    // Carry every declared edge (including entry-referencing ones) namespaced for
+    // the render engine; constrain `order` only by contribution-to-contribution
+    // edges, since `order` is over contribution ids.
+    for (const dep of browser.dependencies) {
+      dependencies.push({
+        contribution: globalId(app.id, app.version, dep.contribution),
+        after: globalId(app.id, app.version, dep.after),
+      });
+      if (localContributionIds.has(dep.contribution) && localContributionIds.has(dep.after)) {
+        orderEdges.push({
+          dependent: globalId(app.id, app.version, dep.contribution),
+          prerequisite: globalId(app.id, app.version, dep.after),
+        });
+      }
+    }
+  });
+
+  const order = resolveOrder(orderNodes, orderEdges);
+  if (order.length !== orderNodes.length) {
+    v.add("order", "cycle", "Contribution order could not be resolved; the graph is not acyclic.");
+    return { ok: false, violations: v.items };
+  }
+
+  const cspNeeds: CspSourceSet = {};
+  for (const directive of INTEGRATION_CSP_DIRECTIVES) {
+    const set = cspMerge.get(directive);
+    if (set && set.size > 0) cspNeeds[directive] = [...set].sort();
+  }
+  validateCspSourceSet(cspNeeds, v, "cspNeeds");
+
+  const planBody: Omit<EffectivePlan, "planRevision"> = {
+    schemaVersion: EFFECTIVE_PLAN_SCHEMA_VERSION,
+    environment: envResult.ok ? envResult.value : input.environment,
+    tenantPublicId: input.tenantPublicId,
+    integrations,
+    contributions,
+    order,
+    publicConfig,
+    dependencies,
+    consentNeeds: [...consentSet].sort(),
+    cspNeeds,
+    provenance,
+  };
+
+  const planRevision = computePlanRevision(planBody);
+  const plan: EffectivePlan = { ...planBody, planRevision };
+
+  // Defense-in-depth: the finished plan must carry no secret material.
+  for (const violation of assertPlanBrowserSafe(plan)) v.items.push(violation);
+
+  if (!v.ok) return { ok: false, violations: v.items };
+  return { ok: true, value: plan };
+}
+
+/**
+ * Resolve the environment-only effective plan: a valid {@link BrowserEnvironment}
+ * with NO integration declarations. The render engine consumes this on every
+ * request until declaration materialization is wired — it carries the environment,
+ * a stable `planRevision`, and empty contributions, so a page with no integration
+ * declaration emits no vendor runtime/markup. Throws (fail closed) only on the
+ * impossible case of an invalid environment.
+ */
+export function resolveEnvironmentOnlyPlan(
+  environment: BrowserEnvironment,
+  tenantPublicId: string,
+): EffectivePlan {
+  const result = resolveEffectivePlan({ tenantPublicId, environment, declarations: [] });
+  if (!result.ok) {
+    throw new Error(
+      `resolveEnvironmentOnlyPlan: environment-only plan failed to resolve: ` +
+        result.violations.map((x) => `${x.path}: ${x.message}`).join("; "),
+    );
+  }
+  return result.value;
+}
+
+/**
+ * The stable identity component the candidate/edge-cache key folds in. It changes
+ * when the tenant, environment stage, version revision, or the resolved plan
+ * itself changes — so a plan change invalidates a cached response and a removed
+ * version leaves no matching key.
+ */
+export function planCacheIdentity(plan: EffectivePlan): string {
+  return `${plan.tenantPublicId}:${plan.environment.environment}:${plan.environment.revision}:${plan.planRevision}`;
+}
+
+interface OrderNode {
+  id: string;
+  phase: ReservedPhase;
+  integrationIndex: number;
+  declIndex: number;
+}
+
+interface OrderEdge {
+  dependent: string;
+  prerequisite: string;
+}
+
+function validateDeclaration(
+  decl: IntegrationDeclarationInput,
+  index: number,
+  seenAppIds: Set<string>,
+  v: Violations,
+): void {
+  const path = `declarations[${index}]`;
+  if (!isPlainObject(decl)) {
+    v.add(path, "type", "Each declaration must be an object.");
+    return;
+  }
+
+  if (!(INTEGRATION_ORIGINS as readonly string[]).includes(decl.origin)) {
+    v.add(`${path}.origin`, "unknown_enum", `origin must be one of: ${INTEGRATION_ORIGINS.join(", ")}.`);
+  }
+  if (typeof decl.ref !== "string" || decl.ref.length === 0) {
+    v.add(`${path}.ref`, "type", "ref must be a non-empty string.");
+  }
+  if (!Array.isArray(decl.materializedAssets)) {
+    v.add(`${path}.materializedAssets`, "type", "materializedAssets must be an array of asset paths.");
+  }
+  if (!isPlainObject(decl.publicConfig)) {
+    v.add(`${path}.publicConfig`, "type", "publicConfig must be an object of resolved tenant values.");
+  }
+
+  const manifestResult = validateIntegrationManifest(decl.manifest);
+  if (!manifestResult.ok) {
+    for (const violation of prefix(manifestResult.violations, `${path}.manifest`)) v.items.push(violation);
+    return; // A malformed manifest is unsafe to inspect further.
+  }
+
+  const manifest = manifestResult.value;
+  const appId = manifest.app.id;
+  if (seenAppIds.has(appId)) {
+    v.add(`${path}.manifest.app.id`, "duplicate", `Duplicate integration "${appId}"; an app resolves at most once.`);
+  }
+  seenAppIds.add(appId);
+
+  // Fail closed on a partially materialized version: the declared entry module
+  // must be present before the integration can be served.
+  const assets = Array.isArray(decl.materializedAssets) ? decl.materializedAssets : [];
+  if (!assets.includes(manifest.browser.entry.asset)) {
+    v.add(
+      `${path}.manifest.browser.entry.asset`,
+      "missing_asset",
+      `Entry asset "${manifest.browser.entry.asset}" is not materialized; a partial version blocks the plan.`,
+    );
+  }
+
+  if (isPlainObject(decl.publicConfig)) {
+    validatePublicConfigValues(
+      manifest.browser.publicConfigSchema,
+      decl.publicConfig,
+      v,
+      `${path}.publicConfig`,
+    );
+  }
+}
+
+/**
+ * Validate resolved tenant public-config VALUES against the integration's closed
+ * public-config schema: no secret keys, no key outside the schema, every required
+ * key present, and each value's primitive type matching the schema.
+ */
+function validatePublicConfigValues(
+  schema: Record<string, unknown>,
+  config: Record<string, unknown>,
+  v: Violations,
+  path: string,
+): void {
+  for (const violation of findForbiddenFields(config, path)) v.items.push(violation);
+
+  const propsRaw = schema["properties"];
+  const props = isPlainObject(propsRaw) ? propsRaw : {};
+  const allowed = new Set(Object.keys(props));
+  const required = Array.isArray(schema["required"])
+    ? (schema["required"] as unknown[]).filter((r): r is string => typeof r === "string")
+    : [];
+
+  for (const key of Object.keys(config)) {
+    if (!allowed.has(key)) {
+      v.add(joinPath(path, key), "unknown_field", `Public config key "${key}" is not in the integration schema; tenant config is closed.`);
+      continue;
+    }
+    const propSchema = props[key];
+    const expected =
+      isPlainObject(propSchema) && typeof propSchema["type"] === "string"
+        ? (propSchema["type"] as string)
+        : undefined;
+    if (!valueMatchesType(config[key], expected)) {
+      v.add(joinPath(path, key), "type", `Public config value "${key}" must be of type ${expected ?? "string|number|boolean"}.`);
+    }
+  }
+
+  for (const key of required) {
+    if (!(key in config)) {
+      v.add(joinPath(path, key), "type", `Required public config key "${key}" is missing.`);
+    }
+  }
+}
+
+function valueMatchesType(value: unknown, expected: string | undefined): boolean {
+  switch (expected) {
+    case "string":
+      return typeof value === "string";
+    case "boolean":
+      return typeof value === "boolean";
+    case "number":
+      return typeof value === "number" && Number.isFinite(value);
+    case "integer":
+      return typeof value === "number" && Number.isInteger(value);
+    default:
+      return typeof value === "string" || typeof value === "number" || typeof value === "boolean";
+  }
+}
+
+function compareDeclarations(a: IntegrationDeclarationInput, b: IntegrationDeclarationInput): number {
+  const ra = ORIGIN_RANK[a.origin] ?? Number.MAX_SAFE_INTEGER;
+  const rb = ORIGIN_RANK[b.origin] ?? Number.MAX_SAFE_INTEGER;
+  if (ra !== rb) return ra - rb;
+  const ida = a.manifest.app.id;
+  const idb = b.manifest.app.id;
+  if (ida !== idb) return ida < idb ? -1 : 1;
+  const va = a.manifest.app.version;
+  const vb = b.manifest.app.version;
+  return va < vb ? -1 : va > vb ? 1 : 0;
+}
+
+function globalId(appId: string, version: string, local: string): string {
+  return `${appId}@${version}#${local}`;
+}
+
+/**
+ * Deterministic topological order over contribution nodes: phase order first,
+ * then canonical integration order, then declaration order, subject to the
+ * contribution dependency edges. Returns fewer ids than nodes only if a cycle
+ * survived manifest validation (treated as a fail-closed error by the caller).
+ */
+function resolveOrder(nodes: readonly OrderNode[], edges: readonly OrderEdge[]): string[] {
+  const byId = new Map(nodes.map((n) => [n.id, n]));
+  const indegree = new Map<string, number>(nodes.map((n) => [n.id, 0]));
+  const dependents = new Map<string, string[]>();
+
+  for (const edge of edges) {
+    if (!byId.has(edge.dependent) || !byId.has(edge.prerequisite)) continue;
+    indegree.set(edge.dependent, (indegree.get(edge.dependent) ?? 0) + 1);
+    const list = dependents.get(edge.prerequisite);
+    if (list) list.push(edge.dependent);
+    else dependents.set(edge.prerequisite, [edge.dependent]);
+  }
+
+  const compare = (a: string, b: string): number => {
+    const na = byId.get(a)!;
+    const nb = byId.get(b)!;
+    const pa = phaseRank(na.phase);
+    const pb = phaseRank(nb.phase);
+    if (pa !== pb) return pa - pb;
+    if (na.integrationIndex !== nb.integrationIndex) return na.integrationIndex - nb.integrationIndex;
+    if (na.declIndex !== nb.declIndex) return na.declIndex - nb.declIndex;
+    return a < b ? -1 : a > b ? 1 : 0;
+  };
+
+  const ready = nodes.filter((n) => (indegree.get(n.id) ?? 0) === 0).map((n) => n.id);
+  const out: string[] = [];
+  while (ready.length > 0) {
+    ready.sort(compare);
+    const id = ready.shift()!;
+    out.push(id);
+    for (const dependent of dependents.get(id) ?? []) {
+      const next = (indegree.get(dependent) ?? 0) - 1;
+      indegree.set(dependent, next);
+      if (next === 0) ready.push(dependent);
+    }
+  }
+  return out;
+}
+
+function computePlanRevision(planBody: Omit<EffectivePlan, "planRevision">): string {
+  return `pr1-${fnv1a128Hex(stableStringify(planBody))}`;
+}
+
+function prefix(violations: readonly ContractViolation[], path: string): ContractViolation[] {
+  return violations.map((violation) => ({
+    ...violation,
+    path: violation.path ? `${path}.${violation.path}` : path,
+  }));
+}

package/packages/public-runtime/src/integration/result.ts

@@ -0,0 +1,239 @@
+/**
+ * Shared validation core for the browser-integration public contracts.
+ *
+ * Every public contract is CLOSED and FAIL-CLOSED: unknown fields, unknown enum
+ * members, malformed shapes, and duplicates produce structured violations
+ * rather than being ignored or assumed safe. Validators accumulate violations
+ * with a JSON path so callers (CLI, docs, admin, evidence) can render
+ * actionable failures.
+ */
+
+export interface ContractViolation {
+  /** JSON path to the offending value, e.g. `browser.contributions[1].phase`. */
+  path: string;
+  /** Stable machine code, e.g. `unknown_field`, `unknown_enum`, `duplicate`. */
+  code: string;
+  message: string;
+}
+
+export type ContractResult<T> =
+  | { ok: true; value: T }
+  | { ok: false; violations: ContractViolation[] };
+
+/**
+ * JSON-Schema annotation keywords permitted on any contract object. They carry
+ * no semantic contract data and never bear executable or secret material (a
+ * `$`-named secret is still caught by the secret scanner), so they are allowed
+ * without opening the closed field set.
+ */
+export const ANNOTATION_KEYS: readonly string[] = ["$schema", "$comment", "$id"];
+
+export class Violations {
+  readonly items: ContractViolation[] = [];
+  add(path: string, code: string, message: string): void {
+    this.items.push({ path, code, message });
+  }
+  get ok(): boolean {
+    return this.items.length === 0;
+  }
+}
+
+export function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function joinPath(path: string, key: string): string {
+  return path ? `${path}.${key}` : key;
+}
+
+export function rejectUnknownKeys(
+  obj: Record<string, unknown>,
+  allowed: readonly string[],
+  v: Violations,
+  path: string,
+): void {
+  const set = new Set([...allowed, ...ANNOTATION_KEYS]);
+  for (const key of Object.keys(obj)) {
+    if (!set.has(key)) {
+      v.add(
+        joinPath(path, key),
+        "unknown_field",
+        `Unknown field "${key}"; this contract is closed.`,
+      );
+    }
+  }
+}
+
+export function reqObject(
+  value: unknown,
+  v: Violations,
+  path: string,
+): Record<string, unknown> | undefined {
+  if (!isPlainObject(value)) {
+    v.add(path || "(root)", "type", "Expected an object.");
+    return undefined;
+  }
+  return value;
+}
+
+export function childObject(
+  obj: Record<string, unknown>,
+  key: string,
+  v: Violations,
+  path: string,
+): Record<string, unknown> | undefined {
+  return reqObject(obj[key], v, joinPath(path, key));
+}
+
+export function reqString(
+  obj: Record<string, unknown>,
+  key: string,
+  v: Violations,
+  path: string,
+): string | undefined {
+  const value = obj[key];
+  if (typeof value !== "string" || value.length === 0) {
+    v.add(joinPath(path, key), "type", `Expected a non-empty string at "${key}".`);
+    return undefined;
+  }
+  return value;
+}
+
+export function optString(
+  obj: Record<string, unknown>,
+  key: string,
+  v: Violations,
+  path: string,
+): string | undefined {
+  if (!(key in obj)) return undefined;
+  return reqString(obj, key, v, path);
+}
+
+export function reqEnum<T extends string>(
+  obj: Record<string, unknown>,
+  key: string,
+  allowed: readonly T[],
+  v: Violations,
+  path: string,
+): T | undefined {
+  const value = obj[key];
+  if (typeof value !== "string" || !(allowed as readonly string[]).includes(value)) {
+    v.add(
+      joinPath(path, key),
+      "unknown_enum",
+      `"${key}" must be one of: ${allowed.join(", ")}.`,
+    );
+    return undefined;
+  }
+  return value as T;
+}
+
+export function reqLiteral<T extends string | number | boolean>(
+  obj: Record<string, unknown>,
+  key: string,
+  expected: T,
+  v: Violations,
+  path: string,
+): T | undefined {
+  if (obj[key] !== expected) {
+    v.add(
+      joinPath(path, key),
+      "unsupported_version",
+      `"${key}" must equal ${JSON.stringify(expected)}.`,
+    );
+    return undefined;
+  }
+  return expected;
+}
+
+export function reqInt(
+  obj: Record<string, unknown>,
+  key: string,
+  v: Violations,
+  path: string,
+): number | undefined {
+  const value = obj[key];
+  if (typeof value !== "number" || !Number.isInteger(value)) {
+    v.add(joinPath(path, key), "type", `Expected an integer at "${key}".`);
+    return undefined;
+  }
+  return value;
+}
+
+export function reqBool(
+  obj: Record<string, unknown>,
+  key: string,
+  v: Violations,
+  path: string,
+): boolean | undefined {
+  const value = obj[key];
+  if (typeof value !== "boolean") {
+    v.add(joinPath(path, key), "type", `Expected a boolean at "${key}".`);
+    return undefined;
+  }
+  return value;
+}
+
+export function reqArray(
+  obj: Record<string, unknown>,
+  key: string,
+  v: Violations,
+  path: string,
+): unknown[] | undefined {
+  const value = obj[key];
+  if (!Array.isArray(value)) {
+    v.add(joinPath(path, key), "type", `Expected an array at "${key}".`);
+    return undefined;
+  }
+  return value;
+}
+
+export function reqStringArray(
+  obj: Record<string, unknown>,
+  key: string,
+  v: Violations,
+  path: string,
+): string[] | undefined {
+  const arr = reqArray(obj, key, v, path);
+  if (!arr) return undefined;
+  const out: string[] = [];
+  arr.forEach((item, i) => {
+    if (typeof item !== "string" || item.length === 0) {
+      v.add(`${joinPath(path, key)}[${i}]`, "type", "Expected a non-empty string.");
+      return;
+    }
+    out.push(item);
+  });
+  return out;
+}
+
+export function reqIsoTimestamp(
+  obj: Record<string, unknown>,
+  key: string,
+  v: Violations,
+  path: string,
+): string | undefined {
+  const value = reqString(obj, key, v, path);
+  if (value === undefined) return undefined;
+  if (!/\d{4}-\d{2}-\d{2}T/.test(value) || Number.isNaN(Date.parse(value))) {
+    v.add(joinPath(path, key), "format", `"${key}" must be an ISO-8601 timestamp.`);
+    return undefined;
+  }
+  return value;
+}
+
+/** Fail-closed on repeated values; duplicates are always rejected, never merged. */
+export function assertUnique(
+  values: readonly string[],
+  v: Violations,
+  path: string,
+  label: string,
+): void {
+  const seen = new Set<string>();
+  values.forEach((value, i) => {
+    if (seen.has(value)) {
+      v.add(`${path}[${i}]`, "duplicate", `Duplicate ${label} "${value}"; duplicates are rejected.`);
+    }
+    seen.add(value);
+  });
+}