@iislee/opencodex 2.11.0 → 2.31.0

package/src/lab/projection/verification.ts

@@ -0,0 +1,412 @@
+import type { ObservationEvent, ProtocolSubjectV1, RouteSubjectV1, TaskSubjectV1 } from "../events/types";
+import { EVIDENCE_LAYERS, type ExecutionMode } from "../constants";
+import type { SuiteManifestV1 } from "../conformance/suite-manifest";
+import type { VerificationRole } from "../conformance/types";
+import { isSha256Hex } from "../digest";
+
+export interface VerificationEvaluation {
+  applicableRequiredScenarioIds: string[];
+  passingRequiredScenarioIds: string[];
+  missingRequiredScenarioIds: string[];
+  canVerify: boolean;
+  notes: string[];
+}
+
+export type LoadScenarioManifest = (digest: string) => Record<string, unknown> | null;
+
+export interface ScenarioRequirements {
+  inboundProtocols?: string[];
+  upstreamProtocols?: string[];
+  surfaces?: string[];
+  requiredClaims?: string[];
+  requiredHarnessFeatures?: string[];
+  platforms?: string[];
+  routePreconditions?: string[];
+  freshness?: { maxAgeMs: number | null };
+}
+
+export type LoadScenarioRequirements = (digest: string) => ScenarioRequirements | null;
+
+/** Live-reserved scenarios are inapplicable in fixture-mode protocol conformance. */
+export function isScenarioApplicable(
+  scenarioId: string,
+  executionMode: ExecutionMode,
+  evidenceLayer: string,
+): boolean {
+  if (evidenceLayer === "protocol_conformance" && executionMode === "fixture") {
+    // The frozen CL-00 scenario schema has no explicit execution-mode field.
+    // Use an exact dot-delimited `live` segment rather than substring matching.
+    if (scenarioId.split(".").includes("live")) return false;
+  }
+  return true;
+}
+
+/** Match protocol subject fields against scenario requirement lists. */
+function scenarioApplicableToRequirements(
+  requirements: ScenarioRequirements,
+  subject: ProtocolSubjectV1,
+): boolean {
+  const inbound = requirements.inboundProtocols ?? [];
+  const upstream = requirements.upstreamProtocols ?? [];
+  const surfaces = requirements.surfaces ?? [];
+  return (
+    inbound.includes(subject.inboundProtocol) &&
+    upstream.includes(subject.upstreamProtocol) &&
+    surfaces.includes(subject.surface)
+  );
+}
+
+/** Applicability for live_route_compatibility using exact RouteSubjectV1 plus validated claim state. */
+export function routeSubjectApplicableToRequirements(
+  requirements: ScenarioRequirements,
+  subject: RouteSubjectV1,
+  supportedClaims: readonly string[],
+): boolean {
+  const inbound = requirements.inboundProtocols ?? [];
+  const upstream = requirements.upstreamProtocols ?? [];
+  const surfaces = requirements.surfaces ?? [];
+  const requiredClaims = requirements.requiredClaims ?? [];
+  const claimsOk = requiredClaims.every((claim) => supportedClaims.includes(claim));
+  return (
+    inbound.includes(subject.inboundProtocol) &&
+    upstream.includes(subject.upstreamProtocol) &&
+    surfaces.includes(subject.surface) &&
+    claimsOk
+  );
+}
+
+/** Task-layer applicability against harness/platform/precondition state. */
+export function taskSubjectApplicableToRequirements(
+  requirements: ScenarioRequirements,
+  capability: {
+    harnessFeatures: readonly string[];
+    platforms: readonly string[];
+    routePreconditions: readonly string[];
+  },
+): boolean {
+  const platforms = requirements.platforms ?? ["*"];
+  const features = requirements.requiredHarnessFeatures ?? [];
+  const preconditions = requirements.routePreconditions ?? [];
+  const platformOk = platforms.includes("*")
+    || capability.platforms.includes("*")
+    || platforms.some((platform) => capability.platforms.includes(platform));
+  const featuresOk = features.every((feature) => capability.harnessFeatures.includes(feature));
+  const preconditionsOk = preconditions.every((item) => capability.routePreconditions.includes(item));
+  return platformOk && featuresOk && preconditionsOk;
+}
+
+/** Return true for non-negative integer values used in freshness parsing. */
+function isNonNegativeInteger(value: unknown): value is number {
+  return typeof value === "number" && Number.isInteger(value) && value >= 0;
+}
+
+/** Parse a freshness object from a scenario manifest fragment. */
+function parseFreshness(value: unknown): { maxAgeMs: number | null } | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const maxAgeMs = (value as { maxAgeMs?: unknown }).maxAgeMs;
+  if (maxAgeMs === null) return { maxAgeMs: null };
+  if (!isNonNegativeInteger(maxAgeMs)) return null;
+  return { maxAgeMs };
+}
+
+/** Parse a string array requirement field from a manifest fragment. */
+function parseStringArray(value: unknown): string[] | null {
+  if (!Array.isArray(value) || !value.every((item) => typeof item === "string")) return null;
+  return value;
+}
+
+function scenarioContractFromManifest(
+  scenarioManifest: Record<string, unknown> | null,
+): ScenarioRequirements | null {
+  if (!scenarioManifest) return null;
+  const req = scenarioManifest.requirements;
+  if (!req || typeof req !== "object" || Array.isArray(req)) return null;
+  const row = req as Record<string, unknown>;
+  const inboundProtocols = parseStringArray(row.inboundProtocols);
+  const upstreamProtocols = parseStringArray(row.upstreamProtocols);
+  const surfaces = parseStringArray(row.surfaces);
+  if (!inboundProtocols || !upstreamProtocols || !surfaces) return null;
+  const requiredClaims = row.requiredClaims === undefined ? [] : parseStringArray(row.requiredClaims);
+  if (!requiredClaims) return null;
+  const requiredHarnessFeatures = row.requiredHarnessFeatures === undefined
+    ? []
+    : parseStringArray(row.requiredHarnessFeatures);
+  if (!requiredHarnessFeatures) return null;
+  const platforms = row.platforms === undefined ? ["*"] : parseStringArray(row.platforms);
+  if (!platforms) return null;
+  const routePreconditions = row.routePreconditions === undefined
+    ? []
+    : parseStringArray(row.routePreconditions);
+  if (!routePreconditions) return null;
+  const freshness = parseFreshness(scenarioManifest.freshness);
+  if (!freshness) return null;
+  return {
+    inboundProtocols,
+    upstreamProtocols,
+    surfaces,
+    requiredClaims,
+    requiredHarnessFeatures,
+    platforms,
+    routePreconditions,
+    freshness,
+  };
+}
+
+function effectiveMaxAgeMs(
+  suiteMaxAgeMs: number | null,
+  scenarioMaxAgeMs: number | null,
+): number | null {
+  if (suiteMaxAgeMs === null) return scenarioMaxAgeMs;
+  if (scenarioMaxAgeMs === null) return suiteMaxAgeMs;
+  return Math.min(suiteMaxAgeMs, scenarioMaxAgeMs);
+}
+
+export function newestObservationByScenario(
+  observations: ObservationEvent[],
+): Map<string, ObservationEvent> {
+  const byScenario = new Map<string, ObservationEvent>();
+  const ordered = [...observations].sort((a, b) => {
+    if (a.completedAt !== b.completedAt) return a.completedAt - b.completedAt;
+    return a.eventId < b.eventId ? -1 : a.eventId > b.eventId ? 1 : 0;
+  });
+  for (const obs of ordered) {
+    byScenario.set(obs.scenarioId, obs);
+  }
+  return byScenario;
+}
+
+/**
+ * Evaluate `all-applicable-required-pass-v1` per frozen CL-00 semantics.
+ * Positive VERIFIED requires a non-empty applicable required/control set and a
+ * current, fresh pass for every applicable required scenario and negative control.
+ */
+export function evaluateAllApplicableRequiredPassV1(
+  suiteManifest: SuiteManifestV1,
+  observations: ObservationEvent[],
+  executionMode: ExecutionMode,
+  opts: {
+    subject?: ProtocolSubjectV1 | RouteSubjectV1 | TaskSubjectV1;
+    /** For live projection this must come from validated current claim snapshots for subjectId. */
+    routeSupportedClaims?: readonly string[];
+    /** Fabric harness/platform/precondition state for task_effectiveness applicability. */
+    fabricCapability?: {
+      harnessFeatures: readonly string[];
+      platforms: readonly string[];
+      routePreconditions: readonly string[];
+    };
+    loadScenarioManifest?: LoadScenarioManifest;
+    loadScenarioRequirements?: LoadScenarioRequirements;
+    asOf?: number;
+  } = {},
+): VerificationEvaluation {
+  const notes: string[] = [];
+  if (suiteManifest.verificationRule !== "all-applicable-required-pass-v1") {
+    return {
+      applicableRequiredScenarioIds: [],
+      passingRequiredScenarioIds: [],
+      missingRequiredScenarioIds: [],
+      canVerify: false,
+      notes: ["unsupported_verification_rule"],
+    };
+  }
+  if (suiteManifest.evidenceLayer === "live_route_compatibility") {
+    if (opts.subject?.subjectKind !== "route") {
+      return { applicableRequiredScenarioIds: [], passingRequiredScenarioIds: [], missingRequiredScenarioIds: [], canVerify: false, notes: ["route_subject_required"] };
+    }
+    if (opts.routeSupportedClaims === undefined) {
+      return { applicableRequiredScenarioIds: [], passingRequiredScenarioIds: [], missingRequiredScenarioIds: [], canVerify: false, notes: ["route_claim_state_required"] };
+    }
+  }
+  if (suiteManifest.evidenceLayer === "task_effectiveness") {
+    if (opts.subject?.subjectKind !== "task") {
+      return {
+        applicableRequiredScenarioIds: [],
+        passingRequiredScenarioIds: [],
+        missingRequiredScenarioIds: [],
+        canVerify: false,
+        notes: ["task_subject_required"],
+      };
+    }
+    if (executionMode !== "fabric") {
+      return {
+        applicableRequiredScenarioIds: [],
+        passingRequiredScenarioIds: [],
+        missingRequiredScenarioIds: [],
+        canVerify: false,
+        notes: ["fabric_execution_mode_required"],
+      };
+    }
+  }
+
+  const requiredScenarios = suiteManifest.scenarios.filter(
+    (s) => s.role === "required" || s.role === "negative_control",
+  );
+  const applicableRequired: string[] = [];
+  const unavailableManifests: string[] = [];
+  const scenarioMaxAgeById = new Map<string, number | null>();
+
+  for (const s of requiredScenarios) {
+    if (!isScenarioApplicable(s.id, executionMode, suiteManifest.evidenceLayer)) continue;
+
+    let requirements: ScenarioRequirements | null = null;
+    const scenarioManifest = opts.loadScenarioManifest?.(s.manifestDigest) ?? null;
+    if (scenarioManifest) {
+      requirements = scenarioContractFromManifest(scenarioManifest);
+      if (!requirements) {
+        unavailableManifests.push(s.id);
+        continue;
+      }
+    } else {
+      requirements = opts.loadScenarioRequirements?.(s.manifestDigest) ?? null;
+      if (!requirements || !requirements.freshness) {
+        unavailableManifests.push(s.id);
+        continue;
+      }
+    }
+
+    if (suiteManifest.evidenceLayer === "protocol_conformance" && opts.subject?.subjectKind === "protocol") {
+      if (!scenarioApplicableToRequirements(requirements, opts.subject)) continue;
+    }
+    if (suiteManifest.evidenceLayer === "live_route_compatibility" && opts.subject?.subjectKind === "route") {
+      if (!routeSubjectApplicableToRequirements(requirements, opts.subject, opts.routeSupportedClaims!)) continue;
+    }
+    if (suiteManifest.evidenceLayer === "task_effectiveness" && opts.subject?.subjectKind === "task") {
+      const capability = opts.fabricCapability ?? {
+        harnessFeatures: ["fabric-scratch-v1"],
+        platforms: [process.platform, "*"],
+        routePreconditions: ["exact-route-subject"],
+      };
+      if (!taskSubjectApplicableToRequirements(requirements, capability)) continue;
+    }
+    applicableRequired.push(s.id);
+    scenarioMaxAgeById.set(s.id, requirements.freshness?.maxAgeMs ?? null);
+  }
+  applicableRequired.sort();
+
+  if (unavailableManifests.length > 0) {
+    return {
+      applicableRequiredScenarioIds: applicableRequired,
+      passingRequiredScenarioIds: [],
+      missingRequiredScenarioIds: [...new Set([...applicableRequired, ...unavailableManifests])].sort(),
+      canVerify: false,
+      notes: unavailableManifests.map((id) => `scenario_manifest_unavailable:${id}`),
+    };
+  }
+
+  if (applicableRequired.length === 0) {
+    return {
+      applicableRequiredScenarioIds: [],
+      passingRequiredScenarioIds: [],
+      missingRequiredScenarioIds: [],
+      canVerify: false,
+      notes: ["empty_applicable_required_set"],
+    };
+  }
+
+  const newest = newestObservationByScenario(observations);
+  const passing: string[] = [];
+  const missing: string[] = [];
+  const asOf = opts.asOf ?? observations.reduce((max, obs) => Math.max(max, obs.completedAt), 0);
+
+  for (const scenarioId of applicableRequired) {
+    const scenarioRef = requiredScenarios.find((s) => s.id === scenarioId)!;
+    const obs = newest.get(scenarioId);
+    if (!obs) {
+      missing.push(scenarioId);
+      continue;
+    }
+    if (obs.scenarioManifestDigest !== scenarioRef.manifestDigest) {
+      missing.push(scenarioId);
+      notes.push(`digest_mismatch:${scenarioId}`);
+      continue;
+    }
+    const maxAgeMs = effectiveMaxAgeMs(
+      suiteManifest.freshness.maxAgeMs,
+      scenarioMaxAgeById.get(scenarioId) ?? null,
+    );
+    if (maxAgeMs !== null && asOf - obs.completedAt > maxAgeMs) {
+      missing.push(scenarioId);
+      notes.push(`stale_observation:${scenarioId}`);
+      continue;
+    }
+    if (obs.outcome !== "pass") {
+      missing.push(scenarioId);
+      continue;
+    }
+    passing.push(scenarioId);
+  }
+
+  return {
+    applicableRequiredScenarioIds: applicableRequired,
+    passingRequiredScenarioIds: passing,
+    missingRequiredScenarioIds: missing,
+    canVerify: missing.length === 0 && passing.length === applicableRequired.length,
+    notes,
+  };
+}
+
+function requireNonEmptyString(value: unknown): string | null {
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+
+export function parseSuiteManifestFromArtifact(parsed: unknown): SuiteManifestV1 | null {
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+  const raw = parsed as Record<string, unknown>;
+  if (raw.schemaVersion !== 1) return null;
+
+  const id = requireNonEmptyString(raw.id);
+  const version = requireNonEmptyString(raw.version);
+  const capability = requireNonEmptyString(raw.capability);
+  const assertionDslVersion = requireNonEmptyString(raw.assertionDslVersion);
+  const evidenceSchemaVersion = requireNonEmptyString(raw.evidenceSchemaVersion);
+  const contradictionRule = requireNonEmptyString(raw.contradictionRule);
+  const verificationRule = requireNonEmptyString(raw.verificationRule);
+  if (
+    !id || !version || !capability || !assertionDslVersion ||
+    !evidenceSchemaVersion || !contradictionRule ||
+    verificationRule !== "all-applicable-required-pass-v1"
+  ) return null;
+  if (
+    typeof raw.evidenceLayer !== "string" ||
+    !(EVIDENCE_LAYERS as readonly string[]).includes(raw.evidenceLayer)
+  ) return null;
+  const freshness = parseFreshness(raw.freshness);
+  if (!freshness || !Array.isArray(raw.scenarios)) return null;
+
+  const roles = new Set<VerificationRole>(["required", "supplemental", "negative_control"]);
+  const seenScenarioIds = new Set<string>();
+  const scenarios: SuiteManifestV1["scenarios"] = [];
+  for (const s of raw.scenarios) {
+    if (!s || typeof s !== "object" || Array.isArray(s)) return null;
+    const row = s as Record<string, unknown>;
+    const scenarioId = requireNonEmptyString(row.id);
+    const scenarioVersion = requireNonEmptyString(row.version);
+    const manifestDigest = requireNonEmptyString(row.manifestDigest);
+    if (
+      !scenarioId || !scenarioVersion || !manifestDigest || !isSha256Hex(manifestDigest) ||
+      typeof row.role !== "string" || !roles.has(row.role as VerificationRole) ||
+      seenScenarioIds.has(scenarioId)
+    ) return null;
+    seenScenarioIds.add(scenarioId);
+    scenarios.push({
+      id: scenarioId,
+      version: scenarioVersion,
+      role: row.role as VerificationRole,
+      manifestDigest,
+    });
+  }
+
+  return {
+    schemaVersion: 1,
+    id,
+    version,
+    evidenceLayer: raw.evidenceLayer,
+    capability,
+    assertionDslVersion,
+    evidenceSchemaVersion,
+    freshness,
+    contradictionRule,
+    scenarios,
+    verificationRule,
+  };
+}

package/src/lab/public/bundle.ts

@@ -0,0 +1,217 @@
+import { jcsStringify } from "../digest";
+import { publicEvidenceId } from "./ids";
+import {
+  PUBLIC_EVIDENCE_BUNDLE_SCHEMA_VERSION,
+  PUBLIC_EXPORT_POLICY_VERSION,
+  type PublicArtifactV1,
+  type PublicEvidenceBundleUnsignedV1,
+  type PublicEvidenceRecordV1,
+  type PublicPublisherV1,
+} from "./types";
+import { PublicEvidenceValidationError, validatePublicEvidenceRecord } from "./validate";
+
+export const MAX_PUBLIC_BUNDLE_BYTES = 2 * 1024 * 1024;
+export const MAX_PUBLIC_BUNDLE_RECORDS = 256;
+export const MAX_PUBLIC_BUNDLE_ARTIFACTS = 16;
+export const MAX_PUBLIC_ARTIFACT_BYTES = 256 * 1024;
+export const MAX_PUBLIC_ARTIFACT_BYTES_TOTAL = 1024 * 1024;
+
+export interface PublicEvidenceContentInput {
+  records: PublicEvidenceRecordV1[];
+  artifacts: PublicArtifactV1[];
+  createdDayUtc: string;
+}
+
+export interface BuildPublicEvidenceBundleInput extends PublicEvidenceContentInput {
+  publisher: PublicPublisherV1;
+}
+
+/** Deterministic, locale-independent code-unit ordering for canonical identity. */
+function compareCanonicalId(a: string, b: string): number {
+  if (a < b) return -1;
+  if (a > b) return 1;
+  return 0;
+}
+
+function utcDay(value: string): string {
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(value)) {
+    throw new PublicEvidenceValidationError("invalid_day", "createdDayUtc must be YYYY-MM-DD");
+  }
+  const parsed = new Date(`${value}T00:00:00.000Z`);
+  if (Number.isNaN(parsed.getTime()) || parsed.toISOString().slice(0, 10) !== value) {
+    throw new PublicEvidenceValidationError("invalid_day", "createdDayUtc must be a real UTC day");
+  }
+  return value;
+}
+
+function validatePublisher(publisher: PublicPublisherV1): PublicPublisherV1 {
+  const raw = publisher as unknown as Record<string, unknown>;
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new PublicEvidenceValidationError("invalid_publisher", "publisher must be an object");
+  }
+  const keys = Object.keys(raw);
+  if (keys.some((key) => !["algorithm", "keyId", "publicKey"].includes(key))) {
+    throw new PublicEvidenceValidationError("unknown_field", "publisher contains unknown fields");
+  }
+  if (publisher.algorithm !== "ed25519") {
+    throw new PublicEvidenceValidationError("unsupported_algorithm", "publisher must use ed25519");
+  }
+  if (!/^[0-9a-f]{64}$/.test(publisher.keyId)) {
+    throw new PublicEvidenceValidationError("invalid_publisher", "publisher.keyId must be sha256 hex");
+  }
+  if (typeof publisher.publicKey !== "string" || publisher.publicKey.length === 0 || publisher.publicKey.length > 1024) {
+    throw new PublicEvidenceValidationError("invalid_publisher", "publisher.publicKey is invalid");
+  }
+  const publicKeyBytes = Buffer.from(publisher.publicKey, "base64");
+  if (publicKeyBytes.byteLength === 0 || publicKeyBytes.toString("base64") !== publisher.publicKey) {
+    throw new PublicEvidenceValidationError("invalid_publisher", "publisher.publicKey must use canonical base64");
+  }
+  const expectedKeyId = publicEvidenceId("publisher_key", {
+    algorithm: publisher.algorithm,
+    publicKey: publisher.publicKey,
+  });
+  if (publisher.keyId !== expectedKeyId) {
+    throw new PublicEvidenceValidationError("publisher_key_id_mismatch", "publisher.keyId does not match public key");
+  }
+  return { algorithm: "ed25519", keyId: publisher.keyId, publicKey: publisher.publicKey };
+}
+
+function validateArtifacts(artifacts: PublicArtifactV1[]): PublicArtifactV1[] {
+  if (!Array.isArray(artifacts) || artifacts.length > MAX_PUBLIC_BUNDLE_ARTIFACTS) {
+    throw new PublicEvidenceValidationError("array_too_large", `artifacts exceeds ${MAX_PUBLIC_BUNDLE_ARTIFACTS}`);
+  }
+  let aggregate = 0;
+  const ids = new Set<string>();
+  return artifacts.map((artifact, index) => {
+    const raw = artifact as unknown as Record<string, unknown>;
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+      throw new PublicEvidenceValidationError("invalid_artifact", `artifacts[${index}] must be an object`);
+    }
+    if (Object.keys(raw).some((key) => !["artifactId", "artifactClass", "mediaType", "byteCount", "contentBase64"].includes(key))) {
+      throw new PublicEvidenceValidationError("unknown_field", `artifacts[${index}] contains unknown fields`);
+    }
+    if (!/^[0-9a-f]{64}$/.test(artifact.artifactId)) {
+      throw new PublicEvidenceValidationError("invalid_artifact", `artifacts[${index}].artifactId is invalid`);
+    }
+    if (typeof artifact.artifactClass !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._:+-]{0,255}$/.test(artifact.artifactClass)) {
+      throw new PublicEvidenceValidationError("invalid_artifact", `artifacts[${index}].artifactClass is invalid`);
+    }
+    if (typeof artifact.mediaType !== "string" || artifact.mediaType.length === 0 || artifact.mediaType.length > 256) {
+      throw new PublicEvidenceValidationError("invalid_artifact", `artifacts[${index}].mediaType is invalid`);
+    }
+    if (!Number.isInteger(artifact.byteCount) || artifact.byteCount < 0 || artifact.byteCount > MAX_PUBLIC_ARTIFACT_BYTES) {
+      throw new PublicEvidenceValidationError("artifact_too_large", `artifacts[${index}].byteCount is invalid`);
+    }
+    let bytes: Buffer;
+    try {
+      bytes = Buffer.from(artifact.contentBase64, "base64");
+    } catch {
+      throw new PublicEvidenceValidationError("invalid_artifact", `artifacts[${index}].contentBase64 is invalid`);
+    }
+    if (bytes.byteLength !== artifact.byteCount || bytes.toString("base64") !== artifact.contentBase64) {
+      throw new PublicEvidenceValidationError("invalid_artifact", `artifacts[${index}] byte count or base64 is non-canonical`);
+    }
+    const expectedArtifactId = publicEvidenceId("artifact", {
+      artifactClass: artifact.artifactClass,
+      mediaType: artifact.mediaType,
+      byteCount: artifact.byteCount,
+      contentBase64: artifact.contentBase64,
+    });
+    if (artifact.artifactId !== expectedArtifactId) {
+      throw new PublicEvidenceValidationError("artifact_id_mismatch", `artifacts[${index}].artifactId mismatch`);
+    }
+    aggregate += artifact.byteCount;
+    if (aggregate > MAX_PUBLIC_ARTIFACT_BYTES_TOTAL) {
+      throw new PublicEvidenceValidationError("artifact_aggregate_too_large", "artifact aggregate exceeds 1 MiB");
+    }
+    if (ids.has(artifact.artifactId)) {
+      throw new PublicEvidenceValidationError("duplicate_id", "artifacts contains duplicate ids");
+    }
+    ids.add(artifact.artifactId);
+    return { ...artifact };
+  });
+}
+
+/** Validate all publisher-independent bundle content before any signing-key state is touched. */
+export function normalizePublicEvidenceContent(input: PublicEvidenceContentInput): PublicEvidenceContentInput {
+  if (!Array.isArray(input.records) || input.records.length > MAX_PUBLIC_BUNDLE_RECORDS) {
+    throw new PublicEvidenceValidationError("array_too_large", `records exceeds ${MAX_PUBLIC_BUNDLE_RECORDS}`);
+  }
+  const records = input.records
+    .map(validatePublicEvidenceRecord)
+    .sort((a, b) => compareCanonicalId(a.recordId, b.recordId));
+  if (new Set(records.map((record) => record.recordId)).size !== records.length) {
+    throw new PublicEvidenceValidationError("duplicate_id", "records contains duplicate ids");
+  }
+  const artifacts = validateArtifacts(input.artifacts)
+    .sort((a, b) => compareCanonicalId(a.artifactId, b.artifactId));
+  const artifactIds = new Set(artifacts.map((artifact) => artifact.artifactId));
+  for (const record of records) {
+    for (const artifactId of record.artifactRefs ?? []) {
+      if (!artifactIds.has(artifactId)) {
+        throw new PublicEvidenceValidationError("artifact_ref_missing", `record ${record.recordId} references a missing public artifact`);
+      }
+    }
+  }
+  return { records, artifacts, createdDayUtc: utcDay(input.createdDayUtc) };
+}
+
+export function canonicalPublicEvidenceContent(
+  input: PublicEvidenceContentInput,
+): { canonical: boolean; normalized: PublicEvidenceContentInput } {
+  const normalized = normalizePublicEvidenceContent(input);
+  const canonical = input.records.length === normalized.records.length
+    && input.artifacts.length === normalized.artifacts.length
+    && input.records.every((record, index) => record.recordId === normalized.records[index]!.recordId)
+    && input.artifacts.every((artifact, index) => artifact.artifactId === normalized.artifacts[index]!.artifactId);
+  return { canonical, normalized };
+}
+
+export function hasCanonicalPublicEvidenceOrder(input: PublicEvidenceContentInput): boolean {
+  return canonicalPublicEvidenceContent(input).canonical;
+}
+
+function buildFromNormalizedContent(
+  normalized: PublicEvidenceContentInput,
+  publisherInput: PublicPublisherV1,
+): PublicEvidenceBundleUnsignedV1 {
+  const publisher = validatePublisher(publisherInput);
+  const content = {
+    schemaVersion: PUBLIC_EVIDENCE_BUNDLE_SCHEMA_VERSION,
+    exportPolicyVersion: PUBLIC_EXPORT_POLICY_VERSION,
+    createdDayUtc: normalized.createdDayUtc,
+    publisher,
+    records: normalized.records,
+    artifacts: normalized.artifacts,
+  };
+  const bundleId = publicEvidenceId("bundle", content);
+  const bundleDigest = publicEvidenceId("bundle_digest", { ...content, bundleId });
+  const bundle: PublicEvidenceBundleUnsignedV1 = { ...content, bundleId, bundleDigest };
+  if (new TextEncoder().encode(jcsStringify(bundle)).byteLength > MAX_PUBLIC_BUNDLE_BYTES) {
+    throw new PublicEvidenceValidationError("bundle_too_large", "public bundle exceeds 2 MiB");
+  }
+  return bundle;
+}
+
+export function buildPublicEvidenceBundle(input: BuildPublicEvidenceBundleInput): PublicEvidenceBundleUnsignedV1 {
+  return buildFromNormalizedContent(normalizePublicEvidenceContent(input), input.publisher);
+}
+
+export function expectedPublicBundleIdentityFromNormalized(
+  normalized: PublicEvidenceContentInput,
+  publisher: PublicPublisherV1,
+): { bundleId: string; bundleDigest: string } {
+  const rebuilt = buildFromNormalizedContent(normalized, publisher);
+  return { bundleId: rebuilt.bundleId, bundleDigest: rebuilt.bundleDigest };
+}
+
+export function expectedPublicBundleIdentity(bundle: PublicEvidenceBundleUnsignedV1): { bundleId: string; bundleDigest: string } {
+  return expectedPublicBundleIdentityFromNormalized(
+    normalizePublicEvidenceContent({
+      records: bundle.records,
+      artifacts: bundle.artifacts,
+      createdDayUtc: bundle.createdDayUtc,
+    }),
+    bundle.publisher,
+  );
+}