@bitkyc08/opencodex 2.19.0 → 2.20.0

package/src/lab/ledger/store.ts

@@ -25,6 +25,12 @@ export interface LedgerStore {
   replay(): ReplayResult;
 }
 
+export interface LedgerMutationContext {
+  replay(): ReplayResult;
+  append(event: LabEvent): void;
+  appendIfAbsent(event: LabEvent): boolean;
+}
+
 const LEDGER_LOCK_STALE_MS = 60_000;
 const LEDGER_LOCK_WAIT_MS = 5_000;
 
@@ -36,10 +42,7 @@ interface LedgerLockMeta {
 
 /** Block synchronously for the given duration (ledger lock retry only). */
 function sleepSyncMs(ms: number): void {
-  const end = Date.now() + ms;
-  while (Date.now() < end) {
-    /* spin */
-  }
+  Bun.sleepSync(ms);
 }
 
 /** Read pid, createdAt, and token metadata from a ledger lock file, if well-formed. */
@@ -83,8 +86,94 @@ function isLedgerLockStale(lockPath: string): boolean {
       return false;
     }
   }
-  if (isLockHolderAlive(meta.pid)) return false;
-  return Date.now() - meta.createdAt > LEDGER_LOCK_STALE_MS;
+  return !isLockHolderAlive(meta.pid);
+}
+
+/** Write lock ownership metadata to a newly created exclusive lock file. */
+function writeLedgerLockMeta(fd: number, token: string): void {
+  const metadataBytes = Buffer.from(JSON.stringify({
+    pid: process.pid,
+    createdAt: Date.now(),
+    token,
+  }), "utf8");
+  let written = 0;
+  while (written < metadataBytes.byteLength) {
+    const n = writeSync(fd, metadataBytes, written, metadataBytes.byteLength - written);
+    if (n <= 0) {
+      throw new LabValidationError("short_write", "ledger lock metadata write incomplete");
+    }
+    written += n;
+  }
+}
+
+/** Discard a lock whose exclusive creator failed before publishing ownership metadata. */
+function discardUninitialisedLedgerLock(lockPath: string, lockFd: number): void {
+  try {
+    closeSync(lockFd);
+  } catch {
+    /* ignore */
+  }
+  try {
+    unlinkSync(lockPath);
+  } catch {
+    /* best-effort */
+  }
+}
+
+/** Release a lock file only when the token still matches the path owner. */
+function releaseLedgerLock(lockPath: string, lockFd: number, token: string): void {
+  try {
+    closeSync(lockFd);
+  } catch {
+    /* ignore */
+  }
+  try {
+    const meta = readLedgerLockMeta(lockPath);
+    if (meta?.token === token) unlinkSync(lockPath);
+  } catch {
+    /* best-effort */
+  }
+}
+
+/**
+ * Recover one stale lock while holding a separate recovery mutex.
+ *
+ * The recovery mutex prevents two waiters from both observing the same stale
+ * owner and then unlinking each other's replacement lock. If a process dies
+ * while holding the recovery mutex, acquisition fails closed instead of
+ * guessing ownership of that mutex.
+ */
+function recoverStaleLedgerLock(lockPath: string): boolean {
+  const recoveryPath = `${lockPath}.recovery`;
+  const token = randomBytes(16).toString("hex");
+  let recoveryFd: number;
+  try {
+    recoveryFd = openSync(
+      recoveryPath,
+      fsConstants.O_CREAT | fsConstants.O_EXCL | fsConstants.O_WRONLY,
+      0o600,
+    );
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "EEXIST") return false;
+    throw error;
+  }
+
+  try {
+    writeLedgerLockMeta(recoveryFd, token);
+  } catch (error) {
+    discardUninitialisedLedgerLock(recoveryPath, recoveryFd);
+    throw error;
+  }
+
+  try {
+    // Re-check after taking the recovery mutex. Another waiter may already
+    // have recovered the old lock and installed a live replacement.
+    if (!existsSync(lockPath) || !isLedgerLockStale(lockPath)) return false;
+    unlinkSync(lockPath);
+    return true;
+  } finally {
+    releaseLedgerLock(recoveryPath, recoveryFd, token);
+  }
 }
 
 /** Create a ledger lock file exclusively, recovering stale locks when needed. */
@@ -97,30 +186,19 @@ function tryAcquireLedgerLock(lockPath: string, deadline: number): { fd: number;
     } catch (error) {
       if (existsSync(lockPath) && isLedgerLockStale(lockPath)) {
         try {
-          unlinkSync(lockPath);
-        } catch (unlinkError) {
-          if (Date.now() >= deadline) throw unlinkError;
-          sleepSyncMs(10);
+          if (recoverStaleLedgerLock(lockPath)) continue;
+        } catch (recoveryError) {
+          if (Date.now() >= deadline) throw recoveryError;
         }
-        continue;
       }
       if (Date.now() >= deadline) throw error;
       sleepSyncMs(10);
       continue;
     }
     try {
-      const metadataBytes = Buffer.from(JSON.stringify({ pid: process.pid, createdAt: Date.now(), token }), "utf8");
-      const written = writeSync(fd, metadataBytes);
-      if (written !== metadataBytes.byteLength) {
-        throw new LabValidationError("short_write", "ledger lock metadata write incomplete");
-      }
+      writeLedgerLockMeta(fd, token);
     } catch (error) {
-      closeSync(fd);
-      try {
-        unlinkSync(lockPath);
-      } catch {
-        /* best-effort */
-      }
+      discardUninitialisedLedgerLock(lockPath, fd);
       throw error;
     }
     return { fd, token };
@@ -128,21 +206,6 @@ function tryAcquireLedgerLock(lockPath: string, deadline: number): { fd: number;
   throw new Error("ledger lock acquisition timed out");
 }
 
-/** Release a ledger lock only when the token still matches the lock file. */
-function releaseLedgerLock(lockPath: string, lockFd: number, token: string): void {
-  try {
-    closeSync(lockFd);
-  } catch {
-    /* ignore */
-  }
-  try {
-    const meta = readLedgerLockMeta(lockPath);
-    if (meta?.token === token) unlinkSync(lockPath);
-  } catch {
-    /* best-effort */
-  }
-}
-
 /** Run a ledger mutation while holding the compatibility ledger lock file. */
 function withLedgerLock<T>(ledgerPath: string, fn: () => T): T {
   const lockPath = `${ledgerPath}.lock`;
@@ -156,11 +219,10 @@ function withLedgerLock<T>(ledgerPath: string, fn: () => T): T {
   }
 }
 
-/** Durable append of one validated event as a single JSONL line + fsync. */
-export function appendLabEvent(ledgerPath: string, event: LabEvent): void {
-  const validated = validateLabEvent(event);
+/** Durable append of one already-validated event as a single JSONL line + fsync. */
+function appendValidatedLabEvent(ledgerPath: string, event: LabEvent): void {
   mkdirSync(dirname(ledgerPath), { recursive: true, mode: 0o700 });
-  const line = `${jcsStringify(validated)}\n`;
+  const line = `${jcsStringify(event)}\n`;
   const bytes = new TextEncoder().encode(line);
   const fd = openSync(ledgerPath, "a", 0o600);
   try {
@@ -178,26 +240,78 @@ export function appendLabEvent(ledgerPath: string, event: LabEvent): void {
   }
 }
 
+function isThenable(value: unknown): value is PromiseLike<unknown> {
+  return (
+    (typeof value === "object" && value !== null) || typeof value === "function"
+  ) && typeof (value as { then?: unknown }).then === "function";
+}
+
 /**
- * Append only when eventId is absent. Uses an exclusive lock file plus a
- * process-local event-id index refreshed under the lock.
+ * Serialize a ledger read-modify-write transaction with all ordinary appends.
+ * The callback is intentionally synchronous. Mutation methods become invalid
+ * as soon as the callback returns, so an accidental async continuation cannot
+ * write after the lock has been released.
  */
-export function appendLabEventIfAbsent(ledgerPath: string, event: LabEvent): boolean {
-  const validated = validateLabEvent(event);
+export function withLedgerMutation<T>(
+  ledgerPath: string,
+  fn: (mutation: LedgerMutationContext) => T,
+): T {
   return withLedgerLock(ledgerPath, () => {
-    // Refresh from disk under the lock so concurrent writers are visible.
-    const fresh = new Set<string>();
-    if (existsSync(ledgerPath)) {
-      for (const row of replayLabLedger(ledgerPath).events) {
-        fresh.add(row.eventId);
+    let active = true;
+    const requireActive = () => {
+      if (!active) {
+        throw new LabValidationError(
+          "inactive_ledger_mutation",
+          "ledger mutation context used after its lock was released",
+        );
       }
+    };
+    const replay = () => {
+      requireActive();
+      return replayLabLedger(ledgerPath);
+    };
+    const append = (event: LabEvent) => {
+      requireActive();
+      appendValidatedLabEvent(ledgerPath, validateLabEvent(event));
+    };
+    const appendIfAbsent = (event: LabEvent): boolean => {
+      requireActive();
+      const validated = validateLabEvent(event);
+      if (replay().events.some((row) => row.eventId === validated.eventId)) return false;
+      appendValidatedLabEvent(ledgerPath, validated);
+      return true;
+    };
+
+    try {
+      const result = fn({ replay, append, appendIfAbsent });
+      if (isThenable(result)) {
+        throw new LabValidationError(
+          "async_ledger_mutation",
+          "ledger mutation callback must be synchronous",
+        );
+      }
+      return result;
+    } finally {
+      active = false;
     }
-    if (fresh.has(validated.eventId)) return false;
-    appendLabEvent(ledgerPath, validated);
-    return true;
   });
 }
 
+/** Durable append of one validated event as a single JSONL line + fsync. */
+export function appendLabEvent(ledgerPath: string, event: LabEvent): void {
+  withLedgerMutation(ledgerPath, (mutation) => {
+    mutation.append(event);
+  });
+}
+
+/**
+ * Append only when eventId is absent. Uses the same mutation lock as every
+ * other ledger writer so the presence check and append are one transaction.
+ */
+export function appendLabEventIfAbsent(ledgerPath: string, event: LabEvent): boolean {
+  return withLedgerMutation(ledgerPath, (mutation) => mutation.appendIfAbsent(event));
+}
+
 function processLine(
   line: string,
   lineNumber: number,
@@ -415,4 +529,4 @@ export function openLedgerStore(configDir?: string): LedgerStore {
 
 export function defaultLedgerPath(configDir?: string): string {
   return labLedgerPath(configDir);
-}
+}

package/src/lab/observe/from-conformance.ts

@@ -17,7 +17,7 @@ import {
 } from "../digest";
 import type { ObservationEvent } from "../events/types";
 import { assignEventId } from "../events/validate";
-import { appendLabEvent } from "../ledger/store";
+import { withLedgerMutation } from "../ledger/store";
 import { ensureLabDirs } from "../paths";
 import type {
   CaseAuthority,
@@ -285,12 +285,14 @@ export function persistConformanceResult(
   const ownsStore = !opts.artifactStore;
   const store = opts.artifactStore ?? createArtifactStore(paths.artifactsDir);
   try {
-    const { event } = observationFromConformanceResult(result, caseRecord, authority, {
-      ...opts,
-      artifactStore: store,
+    return withLedgerMutation(paths.ledgerPath, (ledger) => {
+      const { event } = observationFromConformanceResult(result, caseRecord, authority, {
+        ...opts,
+        artifactStore: store,
+      });
+      ledger.append(event);
+      return { event, ledgerPath: paths.ledgerPath };
     });
-    appendLabEvent(paths.ledgerPath, event);
-    return { event, ledgerPath: paths.ledgerPath };
   } finally {
     if (ownsStore) store.close();
   }

package/src/lab/observe/from-live.ts

@@ -5,7 +5,7 @@ import { LAB_EVENT_SCHEMA_VERSION, LAB_PRODUCER, LAB_PRODUCER_VERSION, OBSERVATI
 import { fixtureDigest, scenarioManifestDigest, subjectIdForSubject, suiteManifestDigest } from "../digest";
 import type { FailureRecordV1, ObservationEvent } from "../events/types";
 import { assignEventId } from "../events/validate";
-import { appendLabEvent } from "../ledger/store";
+import { withLedgerMutation } from "../ledger/store";
 import { ensureLabDirs } from "../paths";
 import type { CaseAuthority, CaseRecord } from "../conformance/types";
 import { trustedLiveResultRetryable } from "../live/executor";
@@ -106,6 +106,12 @@ export function observationFromLiveResult(result: LiveScenarioRunResult, caseRec
 
 export function persistLiveResult(result: LiveScenarioRunResult, caseRecord: CaseRecord, authority: CaseAuthority, opts: PersistLiveOptions = {}): PersistedLiveObservation {
   const paths = ensureLabDirs(opts.configDir); const ownsStore = !opts.artifactStore; const store = opts.artifactStore ?? createArtifactStore(paths.artifactsDir);
-  try { const { event } = observationFromLiveResult(result, caseRecord, authority, { ...opts, artifactStore: store }); appendLabEvent(paths.ledgerPath, event); return { event, ledgerPath: paths.ledgerPath }; }
+  try {
+    return withLedgerMutation(paths.ledgerPath, (ledger) => {
+      const { event } = observationFromLiveResult(result, caseRecord, authority, { ...opts, artifactStore: store });
+      ledger.append(event);
+      return { event, ledgerPath: paths.ledgerPath };
+    });
+  }
   finally { if (ownsStore) store.close(); }
 }

package/src/lab/paths.ts

@@ -81,10 +81,25 @@ export function labScratchDir(configDir = getConfigDir()): string {
   return join(labRoot(configDir), "scratch");
 }
 
+/** Shared Lab export directory. Public evidence bundles intentionally live here too. */
 export function labExportDir(configDir = getConfigDir()): string {
   return join(labRoot(configDir), "export");
 }
 
+export function labCommunityDir(configDir = getConfigDir()): string {
+  return join(labRoot(configDir), "community");
+}
+
+export function labPublicOriginDir(configDir = getConfigDir()): string {
+  return join(labRoot(configDir), "public-origin-v1");
+}
+
+export const LAB_PUBLIC_PUBLISHER_KEY_FILE = "publisher-ed25519.pem";
+
+export function labPublicPublisherKeyPath(configDir = getConfigDir()): string {
+  return join(labRoot(configDir), LAB_PUBLIC_PUBLISHER_KEY_FILE);
+}
+
 /** Opaque per-installation salt for local fingerprinting (never exported as evidence). */
 export function labInstallationSaltPath(configDir = getConfigDir()): string {
   return join(labRoot(configDir), "installation-salt.bin");
@@ -110,15 +125,21 @@ export function ensureLabDirs(configDir = getConfigDir()): {
   artifactsDir: string;
   scratchDir: string;
   exportDir: string;
+  communityDir: string;
+  publicOriginDir: string;
 } {
   const root = labRoot(configDir);
   const artifactsDir = labArtifactsDir(configDir);
   const scratchDir = labScratchDir(configDir);
   const exportDir = labExportDir(configDir);
+  const communityDir = labCommunityDir(configDir);
+  const publicOriginDir = labPublicOriginDir(configDir);
   ensureRestrictedDir(root, root);
   ensureRestrictedDir(artifactsDir, root);
   ensureRestrictedDir(scratchDir, root);
   ensureRestrictedDir(exportDir, root);
+  ensureRestrictedDir(communityDir, root);
+  ensureRestrictedDir(publicOriginDir, root);
   return {
     root,
     ledgerPath: labLedgerPath(configDir),
@@ -126,5 +147,7 @@ export function ensureLabDirs(configDir = getConfigDir()): {
     artifactsDir,
     scratchDir,
     exportDir,
+    communityDir,
+    publicOriginDir,
   };
 }

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,
+  );
+}