@tokenoftrust/storefront-runner 2.0.16 → 2.0.18

package/packages/public-runtime/src/publication-version.ts

@@ -0,0 +1,587 @@
+/**
+ * Immutable publication versions and tenant+space scoped channel pointers.
+ *
+ * This is a pure contract/state-transition seam. Durable stores must commit the
+ * returned pointer and audit transition atomically; materialization and UI live
+ * outside this module.
+ */
+import {
+  type PublicationSpaceForgeV1,
+  validatePublicationSpaceRefV1,
+} from "./publication-space.js";
+import {
+  ANNOTATION_KEYS,
+  type ContractResult,
+  type ContractViolation,
+  Violations,
+  reqEnum,
+  reqInt,
+  reqLiteral,
+  reqObject,
+  reqString,
+} from "./integration/result.js";
+
+export const PUBLICATION_VERSION_SCHEMA_VERSION = 1 as const;
+export const PUBLICATION_POINTER_SCHEMA_VERSION = 1 as const;
+export const PUBLICATION_POINTER_TRANSITION_SCHEMA_VERSION = 1 as const;
+export const PUBLICATION_TRANSITION_REQUEST_SCHEMA_VERSION = 1 as const;
+
+export const PUBLICATION_CHANNELS = ["preview", "live"] as const;
+export type PublicationChannelV1 = (typeof PUBLICATION_CHANNELS)[number];
+export type PublicationTransitionOperationV1 = "activate" | "rollback";
+
+const SHA40_RE = /^[0-9a-f]{40}$/;
+const SHA256_RE = /^[0-9a-f]{64}$/;
+const REPO_RE = /^[A-Za-z0-9](?:[A-Za-z0-9._/-]{0,254}[A-Za-z0-9])?$/;
+const OPAQUE_ID_RE = /^[a-z0-9](?:[a-z0-9._:-]{6,126}[a-z0-9])$/;
+const VERSION_ID_RE = /^pv_[a-z0-9](?:[a-z0-9._:-]{4,122}[a-z0-9])$/;
+const CANONICAL_INSTANT_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+
+export interface PublicationVersionV1 {
+  schemaVersion: typeof PUBLICATION_VERSION_SCHEMA_VERSION;
+  /** Opaque immutable version identity; tenant+space are part of the address. */
+  versionId: string;
+  tenant: string;
+  spaceId: string;
+  source: {
+    forge: PublicationSpaceForgeV1;
+    repo: string;
+    commitSha: string;
+  };
+  renderer: {
+    contractVersion: string;
+    themeContractVersion: string;
+  };
+  /** Lowercase sha256 hex of the immutable materialized artifact set. */
+  artifactDigest: string;
+  createdAt: string;
+  /** Closed, non-descriptive build metadata; arbitrary user metadata is forbidden. */
+  metadata: {
+    buildId: string;
+  };
+}
+
+export interface PublicationChannelPointerV1 {
+  schemaVersion: typeof PUBLICATION_POINTER_SCHEMA_VERSION;
+  tenant: string;
+  spaceId: string;
+  channel: PublicationChannelV1;
+  revision: number;
+  versionId: string;
+  sourceSha: string;
+  artifactDigest: string;
+  updatedAt: string;
+}
+
+export interface PublicationPointerSnapshotV1 {
+  revision: number;
+  versionId: string;
+  sourceSha: string;
+  artifactDigest: string;
+}
+
+export interface PublicationPointerTransitionV1 {
+  schemaVersion: typeof PUBLICATION_POINTER_TRANSITION_SCHEMA_VERSION;
+  transitionId: string;
+  operation: PublicationTransitionOperationV1;
+  tenant: string;
+  spaceId: string;
+  channel: PublicationChannelV1;
+  previous: PublicationPointerSnapshotV1 | null;
+  next: PublicationPointerSnapshotV1;
+  principal: string;
+  occurredAt: string;
+}
+
+export interface PublicationTransitionRequestV1 {
+  schemaVersion: typeof PUBLICATION_TRANSITION_REQUEST_SCHEMA_VERSION;
+  transitionId: string;
+  operation: PublicationTransitionOperationV1;
+  tenant: string;
+  spaceId: string;
+  channel: PublicationChannelV1;
+  targetVersionId: string;
+  expectedSourceSha: string;
+  expectedArtifactDigest: string;
+  expectedRevision: number;
+  principal: string;
+  occurredAt: string;
+}
+
+export interface PublicationVersionStateV1 {
+  versions: PublicationVersionV1[];
+  pointers: PublicationChannelPointerV1[];
+  transitions: PublicationPointerTransitionV1[];
+}
+
+function rejectUnknownKeys(
+  obj: Record<string, unknown>,
+  allowed: readonly string[],
+  v: Violations,
+  path: string,
+): void {
+  const allowedKeys = new Set([...allowed, ...ANNOTATION_KEYS]);
+  if (Object.keys(obj).some((key) => !allowedKeys.has(key))) {
+    v.add(path || "(root)", "unknown_field", "Unexpected field in publication version contract.");
+  }
+}
+
+function validateRefFields(
+  tenant: string | undefined,
+  spaceId: string | undefined,
+  v: Violations,
+): void {
+  if (!tenant || !spaceId) return;
+  const result = validatePublicationSpaceRefV1({ version: 1, tenant, spaceId });
+  if (!result.ok) {
+    for (const item of result.violations) v.add(item.path, item.code, item.message);
+  }
+}
+
+function validateSha(value: string | undefined, v: Violations, path: string, length: 40 | 64): string | undefined {
+  const matches = length === 40 ? SHA40_RE.test(value ?? "") : SHA256_RE.test(value ?? "");
+  if (value !== undefined && !matches) {
+    v.add(path, length === 40 ? "publication_source_sha" : "publication_artifact_digest", "Expected a lowercase hexadecimal digest of the required length.");
+    return undefined;
+  }
+  return value;
+}
+
+function validateOpaqueId(value: string | undefined, v: Violations, path: string): string | undefined {
+  if (value !== undefined && !OPAQUE_ID_RE.test(value)) {
+    v.add(path, "publication_opaque_id", "Expected a bounded opaque identifier.");
+    return undefined;
+  }
+  return value;
+}
+
+function validateVersionId(value: string | undefined, v: Violations, path: string): string | undefined {
+  if (value !== undefined && !VERSION_ID_RE.test(value)) {
+    v.add(path, "publication_version_id", "Expected a bounded publication-version identifier.");
+    return undefined;
+  }
+  return value;
+}
+
+function fieldPath(path: string, key: string): string {
+  return path ? `${path}.${key}` : key;
+}
+
+function validateInstant(value: string | undefined, v: Violations, path: string): string | undefined {
+  if (value === undefined) return undefined;
+  const timestamp = Date.parse(value);
+  if (!CANONICAL_INSTANT_RE.test(value) || !Number.isFinite(timestamp) || new Date(timestamp).toISOString() !== value) {
+    v.add(path, "publication_timestamp", "Expected a canonical UTC ISO-8601 instant.");
+    return undefined;
+  }
+  return value;
+}
+
+function validatePositiveRevision(value: number | undefined, v: Violations, path: string): number | undefined {
+  if (value !== undefined && value < 1) {
+    v.add(path, "publication_pointer_revision", "Pointer revision must be a positive integer.");
+    return undefined;
+  }
+  return value;
+}
+
+/** Validate and normalize a closed immutable publication version. */
+export function validatePublicationVersionV1(raw: unknown): ContractResult<PublicationVersionV1> {
+  const v = new Violations();
+  const root = reqObject(raw, v, "");
+  if (!root) return { ok: false, violations: v.items };
+  rejectUnknownKeys(root, ["schemaVersion", "versionId", "tenant", "spaceId", "source", "renderer", "artifactDigest", "createdAt", "metadata"], v, "");
+  reqLiteral(root, "schemaVersion", PUBLICATION_VERSION_SCHEMA_VERSION, v, "");
+  const versionId = validateVersionId(reqString(root, "versionId", v, ""), v, "versionId");
+  const tenant = reqString(root, "tenant", v, "");
+  const spaceId = reqString(root, "spaceId", v, "");
+  validateRefFields(tenant, spaceId, v);
+
+  const sourceRaw = reqObject(root["source"], v, "source");
+  let source: PublicationVersionV1["source"] | undefined;
+  if (sourceRaw) {
+    rejectUnknownKeys(sourceRaw, ["forge", "repo", "commitSha"], v, "source");
+    const forge = reqEnum<PublicationSpaceForgeV1>(sourceRaw, "forge", ["gitea", "github", "fixture"], v, "source");
+    const repo = reqString(sourceRaw, "repo", v, "source");
+    const commitSha = validateSha(reqString(sourceRaw, "commitSha", v, "source"), v, "source.commitSha", 40);
+    if (repo && (!REPO_RE.test(repo) || repo.includes("..") || repo.includes("//"))) {
+      v.add("source.repo", "publication_source_repo", "Source repo must be a stable repository name or owner/name.");
+    }
+    if (forge && repo && commitSha) source = { forge, repo, commitSha };
+  }
+
+  const rendererRaw = reqObject(root["renderer"], v, "renderer");
+  let renderer: PublicationVersionV1["renderer"] | undefined;
+  if (rendererRaw) {
+    rejectUnknownKeys(rendererRaw, ["contractVersion", "themeContractVersion"], v, "renderer");
+    const contractVersion = reqString(rendererRaw, "contractVersion", v, "renderer");
+    const themeContractVersion = reqString(rendererRaw, "themeContractVersion", v, "renderer");
+    if (contractVersion && themeContractVersion) renderer = { contractVersion, themeContractVersion };
+  }
+  const artifactDigest = validateSha(reqString(root, "artifactDigest", v, ""), v, "artifactDigest", 64);
+  const createdAt = validateInstant(reqString(root, "createdAt", v, ""), v, "createdAt");
+
+  const metadataRaw = reqObject(root["metadata"], v, "metadata");
+  let metadata: PublicationVersionV1["metadata"] | undefined;
+  if (metadataRaw) {
+    rejectUnknownKeys(metadataRaw, ["buildId"], v, "metadata");
+    const buildId = validateOpaqueId(reqString(metadataRaw, "buildId", v, "metadata"), v, "metadata.buildId");
+    if (buildId) metadata = { buildId };
+  }
+
+  if (!v.ok || !versionId || !tenant || !spaceId || !source || !renderer || !artifactDigest || !createdAt || !metadata) {
+    return { ok: false, violations: v.items };
+  }
+  return {
+    ok: true,
+    value: {
+      schemaVersion: PUBLICATION_VERSION_SCHEMA_VERSION,
+      versionId,
+      tenant,
+      spaceId,
+      source,
+      renderer,
+      artifactDigest,
+      createdAt,
+      metadata,
+    },
+  };
+}
+
+function validateSnapshot(
+  raw: unknown,
+  v: Violations,
+  path: string,
+  closed = true,
+): PublicationPointerSnapshotV1 | undefined {
+  const snapshot = reqObject(raw, v, path);
+  if (!snapshot) return undefined;
+  if (closed) rejectUnknownKeys(snapshot, ["revision", "versionId", "sourceSha", "artifactDigest"], v, path);
+  const revision = validatePositiveRevision(reqInt(snapshot, "revision", v, path), v, fieldPath(path, "revision"));
+  const versionId = validateVersionId(reqString(snapshot, "versionId", v, path), v, fieldPath(path, "versionId"));
+  const sourceSha = validateSha(reqString(snapshot, "sourceSha", v, path), v, fieldPath(path, "sourceSha"), 40);
+  const artifactDigest = validateSha(reqString(snapshot, "artifactDigest", v, path), v, fieldPath(path, "artifactDigest"), 64);
+  return revision && versionId && sourceSha && artifactDigest
+    ? { revision, versionId, sourceSha, artifactDigest }
+    : undefined;
+}
+
+/** Validate a closed tenant+space+channel pointer record. */
+export function validatePublicationChannelPointerV1(raw: unknown): ContractResult<PublicationChannelPointerV1> {
+  const v = new Violations();
+  const root = reqObject(raw, v, "");
+  if (!root) return { ok: false, violations: v.items };
+  rejectUnknownKeys(root, ["schemaVersion", "tenant", "spaceId", "channel", "revision", "versionId", "sourceSha", "artifactDigest", "updatedAt"], v, "");
+  reqLiteral(root, "schemaVersion", PUBLICATION_POINTER_SCHEMA_VERSION, v, "");
+  const tenant = reqString(root, "tenant", v, "");
+  const spaceId = reqString(root, "spaceId", v, "");
+  validateRefFields(tenant, spaceId, v);
+  const channel = reqEnum<PublicationChannelV1>(root, "channel", PUBLICATION_CHANNELS, v, "");
+  const snapshot = validateSnapshot(root, v, "", false);
+  const updatedAt = validateInstant(reqString(root, "updatedAt", v, ""), v, "updatedAt");
+  if (!v.ok || !tenant || !spaceId || !channel || !snapshot || !updatedAt) return { ok: false, violations: v.items };
+  return { ok: true, value: { schemaVersion: PUBLICATION_POINTER_SCHEMA_VERSION, tenant, spaceId, channel, ...snapshot, updatedAt } };
+}
+
+/** Validate one immutable audit record for an atomic pointer transition. */
+export function validatePublicationPointerTransitionV1(raw: unknown): ContractResult<PublicationPointerTransitionV1> {
+  const v = new Violations();
+  const root = reqObject(raw, v, "");
+  if (!root) return { ok: false, violations: v.items };
+  rejectUnknownKeys(root, ["schemaVersion", "transitionId", "operation", "tenant", "spaceId", "channel", "previous", "next", "principal", "occurredAt"], v, "");
+  reqLiteral(root, "schemaVersion", PUBLICATION_POINTER_TRANSITION_SCHEMA_VERSION, v, "");
+  const transitionId = validateOpaqueId(reqString(root, "transitionId", v, ""), v, "transitionId");
+  const operation = reqEnum<PublicationTransitionOperationV1>(root, "operation", ["activate", "rollback"], v, "");
+  const tenant = reqString(root, "tenant", v, "");
+  const spaceId = reqString(root, "spaceId", v, "");
+  validateRefFields(tenant, spaceId, v);
+  const channel = reqEnum<PublicationChannelV1>(root, "channel", PUBLICATION_CHANNELS, v, "");
+  const previous = root["previous"] === null ? null : validateSnapshot(root["previous"], v, "previous");
+  const next = validateSnapshot(root["next"], v, "next");
+  const principal = validateOpaqueId(reqString(root, "principal", v, ""), v, "principal");
+  const occurredAt = validateInstant(reqString(root, "occurredAt", v, ""), v, "occurredAt");
+  if (operation === "rollback" && previous === null) {
+    v.add("previous", "publication_rollback_without_pointer", "Rollback requires an existing channel pointer.");
+  }
+  if (!v.ok || !transitionId || !operation || !tenant || !spaceId || !channel || previous === undefined || !next || !principal || !occurredAt) {
+    return { ok: false, violations: v.items };
+  }
+  return {
+    ok: true,
+    value: {
+      schemaVersion: PUBLICATION_POINTER_TRANSITION_SCHEMA_VERSION,
+      transitionId,
+      operation,
+      tenant,
+      spaceId,
+      channel,
+      previous,
+      next,
+      principal,
+      occurredAt,
+    },
+  };
+}
+
+/** Runtime validator for activation/rollback commands at the persistence boundary. */
+export function validatePublicationTransitionRequestV1(raw: unknown): ContractResult<PublicationTransitionRequestV1> {
+  const v = new Violations();
+  const root = reqObject(raw, v, "");
+  if (!root) return { ok: false, violations: v.items };
+  rejectUnknownKeys(root, ["schemaVersion", "transitionId", "operation", "tenant", "spaceId", "channel", "targetVersionId", "expectedSourceSha", "expectedArtifactDigest", "expectedRevision", "principal", "occurredAt"], v, "");
+  reqLiteral(root, "schemaVersion", PUBLICATION_TRANSITION_REQUEST_SCHEMA_VERSION, v, "");
+  const transitionId = validateOpaqueId(reqString(root, "transitionId", v, ""), v, "transitionId");
+  const operation = reqEnum<PublicationTransitionOperationV1>(root, "operation", ["activate", "rollback"], v, "");
+  const tenant = reqString(root, "tenant", v, "");
+  const spaceId = reqString(root, "spaceId", v, "");
+  validateRefFields(tenant, spaceId, v);
+  const channel = reqEnum<PublicationChannelV1>(root, "channel", PUBLICATION_CHANNELS, v, "");
+  const targetVersionId = validateVersionId(reqString(root, "targetVersionId", v, ""), v, "targetVersionId");
+  const expectedSourceSha = validateSha(reqString(root, "expectedSourceSha", v, ""), v, "expectedSourceSha", 40);
+  const expectedArtifactDigest = validateSha(reqString(root, "expectedArtifactDigest", v, ""), v, "expectedArtifactDigest", 64);
+  const expectedRevision = reqInt(root, "expectedRevision", v, "");
+  if (expectedRevision !== undefined && expectedRevision < 0) {
+    v.add("expectedRevision", "publication_pointer_revision", "Expected pointer revision must be non-negative.");
+  }
+  const principal = validateOpaqueId(reqString(root, "principal", v, ""), v, "principal");
+  const occurredAt = validateInstant(reqString(root, "occurredAt", v, ""), v, "occurredAt");
+  if (!v.ok || !transitionId || !operation || !tenant || !spaceId || !channel || !targetVersionId || !expectedSourceSha || !expectedArtifactDigest || expectedRevision === undefined || !principal || !occurredAt) {
+    return { ok: false, violations: v.items };
+  }
+  return { ok: true, value: { schemaVersion: 1, transitionId, operation, tenant, spaceId, channel, targetVersionId, expectedSourceSha, expectedArtifactDigest, expectedRevision, principal, occurredAt } };
+}
+
+function parseJson<T>(json: string, validate: (raw: unknown) => ContractResult<T>): ContractResult<T> {
+  try {
+    return validate(JSON.parse(json));
+  } catch {
+    return { ok: false, violations: [{ path: "(root)", code: "publication_invalid_json", message: "Publication version contract is not valid JSON." }] };
+  }
+}
+
+function serializeValidated<T>(value: T, validate: (raw: unknown) => ContractResult<T>, label: string): string {
+  const result = validate(value);
+  if (!result.ok) throw new Error(`Invalid ${label}: ${result.violations.map((item) => item.code).join(", ")}`);
+  return `${JSON.stringify(result.value, null, 2)}\n`;
+}
+
+export function parsePublicationVersionV1Json(json: string): ContractResult<PublicationVersionV1> {
+  return parseJson(json, validatePublicationVersionV1);
+}
+export function serializePublicationVersionV1(value: PublicationVersionV1): string {
+  return serializeValidated(value, validatePublicationVersionV1, "PublicationVersionV1");
+}
+export function parsePublicationChannelPointerV1Json(json: string): ContractResult<PublicationChannelPointerV1> {
+  return parseJson(json, validatePublicationChannelPointerV1);
+}
+export function serializePublicationChannelPointerV1(value: PublicationChannelPointerV1): string {
+  return serializeValidated(value, validatePublicationChannelPointerV1, "PublicationChannelPointerV1");
+}
+export function parsePublicationPointerTransitionV1Json(json: string): ContractResult<PublicationPointerTransitionV1> {
+  return parseJson(json, validatePublicationPointerTransitionV1);
+}
+export function serializePublicationPointerTransitionV1(value: PublicationPointerTransitionV1): string {
+  return serializeValidated(value, validatePublicationPointerTransitionV1, "PublicationPointerTransitionV1");
+}
+export function parsePublicationTransitionRequestV1Json(json: string): ContractResult<PublicationTransitionRequestV1> {
+  return parseJson(json, validatePublicationTransitionRequestV1);
+}
+export function serializePublicationTransitionRequestV1(value: PublicationTransitionRequestV1): string {
+  return serializeValidated(value, validatePublicationTransitionRequestV1, "PublicationTransitionRequestV1");
+}
+
+export function publicationVersionKey(tenant: string, spaceId: string, versionId: string): string {
+  return `cust:publication-version:${tenant}:${spaceId}:${versionId}`;
+}
+export function publicationPointerKey(tenant: string, spaceId: string, channel: PublicationChannelV1): string {
+  return `cust:publication-pointer:${tenant}:${spaceId}:${channel}`;
+}
+export function publicationTransitionKey(tenant: string, spaceId: string, transitionId: string): string {
+  return `cust:publication-transition:${tenant}:${spaceId}:${transitionId}`;
+}
+
+export function emptyPublicationVersionStateV1(): PublicationVersionStateV1 {
+  return { versions: [], pointers: [], transitions: [] };
+}
+
+function versionKey(value: Pick<PublicationVersionV1, "tenant" | "spaceId" | "versionId">): string {
+  return `${value.tenant}\u0000${value.spaceId}\u0000${value.versionId}`;
+}
+function pointerKey(value: Pick<PublicationChannelPointerV1, "tenant" | "spaceId" | "channel">): string {
+  return `${value.tenant}\u0000${value.spaceId}\u0000${value.channel}`;
+}
+function transitionKey(value: Pick<PublicationPointerTransitionV1, "tenant" | "spaceId" | "transitionId">): string {
+  return `${value.tenant}\u0000${value.spaceId}\u0000${value.transitionId}`;
+}
+
+function compareVersion(left: PublicationVersionV1, right: PublicationVersionV1): number {
+  return left.tenant.localeCompare(right.tenant) || left.spaceId.localeCompare(right.spaceId) || left.versionId.localeCompare(right.versionId);
+}
+function comparePointer(left: PublicationChannelPointerV1, right: PublicationChannelPointerV1): number {
+  return left.tenant.localeCompare(right.tenant) || left.spaceId.localeCompare(right.spaceId) || left.channel.localeCompare(right.channel);
+}
+function compareTransition(left: PublicationPointerTransitionV1, right: PublicationPointerTransitionV1): number {
+  return left.tenant.localeCompare(right.tenant) || left.spaceId.localeCompare(right.spaceId) || left.occurredAt.localeCompare(right.occurredAt) || left.transitionId.localeCompare(right.transitionId);
+}
+
+function snapshotsEqual(
+  left: PublicationPointerSnapshotV1,
+  right: PublicationPointerSnapshotV1,
+): boolean {
+  return left.revision === right.revision && left.versionId === right.versionId &&
+    left.sourceSha === right.sourceSha && left.artifactDigest === right.artifactDigest;
+}
+
+function snapshot(pointer: PublicationChannelPointerV1): PublicationPointerSnapshotV1 {
+  return {
+    revision: pointer.revision,
+    versionId: pointer.versionId,
+    sourceSha: pointer.sourceSha,
+    artifactDigest: pointer.artifactDigest,
+  };
+}
+
+/** Validate duplicate-free state and return deterministic collection ordering. */
+export function validatePublicationVersionStateV1(raw: PublicationVersionStateV1): ContractResult<PublicationVersionStateV1> {
+  if (!raw || !Array.isArray(raw.versions) || !Array.isArray(raw.pointers) || !Array.isArray(raw.transitions)) {
+    return { ok: false, violations: [{ path: "state", code: "type", message: "Publication version state must contain record arrays." }] };
+  }
+  const violations: ContractViolation[] = [];
+  const versions: PublicationVersionV1[] = [];
+  const pointers: PublicationChannelPointerV1[] = [];
+  const transitions: PublicationPointerTransitionV1[] = [];
+  const collect = <T>(items: readonly unknown[], validate: (item: unknown) => ContractResult<T>, into: T[], path: string): void => {
+    items.forEach((item, index) => {
+      const result = validate(item);
+      if (result.ok) into.push(result.value);
+      else for (const violation of result.violations) violations.push({ ...violation, path: `${path}[${index}].${violation.path}` });
+    });
+  };
+  collect(raw.versions, validatePublicationVersionV1, versions, "versions");
+  collect(raw.pointers, validatePublicationChannelPointerV1, pointers, "pointers");
+  collect(raw.transitions, validatePublicationPointerTransitionV1, transitions, "transitions");
+  const duplicates = <T>(items: readonly T[], key: (item: T) => string, path: string): void => {
+    const seen = new Set<string>();
+    items.forEach((item, index) => {
+      const itemKey = key(item);
+      if (seen.has(itemKey)) violations.push({ path: `${path}[${index}]`, code: "duplicate", message: "Duplicate publication version state record." });
+      seen.add(itemKey);
+    });
+  };
+  duplicates(versions, versionKey, "versions");
+  duplicates(pointers, pointerKey, "pointers");
+  duplicates(transitions, transitionKey, "transitions");
+
+  const byVersion = new Map(versions.map((version) => [versionKey(version), version]));
+  const snapshotHasVersion = (
+    tenant: string,
+    spaceId: string,
+    value: PublicationPointerSnapshotV1,
+  ): boolean => {
+    const version = byVersion.get(`${tenant}\u0000${spaceId}\u0000${value.versionId}`);
+    return !!version && version.source.commitSha === value.sourceSha &&
+      version.artifactDigest === value.artifactDigest;
+  };
+  pointers.forEach((pointer, index) => {
+    if (!snapshotHasVersion(pointer.tenant, pointer.spaceId, snapshot(pointer))) {
+      violations.push({
+        path: `pointers[${index}]`,
+        code: "publication_pointer_version_mismatch",
+        message: "Publication pointer does not resolve to matching immutable version provenance.",
+      });
+    }
+  });
+  transitions.forEach((transition, index) => {
+    if (!snapshotHasVersion(transition.tenant, transition.spaceId, transition.next) ||
+      (transition.previous !== null && !snapshotHasVersion(transition.tenant, transition.spaceId, transition.previous))) {
+      violations.push({
+        path: `transitions[${index}]`,
+        code: "publication_transition_version_mismatch",
+        message: "Publication transition does not resolve to matching immutable version provenance.",
+      });
+    }
+  });
+
+  const pointerByChannel = new Map(pointers.map((pointer) => [pointerKey(pointer), pointer]));
+  const historyByChannel = new Map<string, PublicationPointerTransitionV1[]>();
+  for (const transition of transitions) {
+    const key = pointerKey(transition);
+    const history = historyByChannel.get(key) ?? [];
+    history.push(transition);
+    historyByChannel.set(key, history);
+  }
+  for (const [key, history] of historyByChannel) {
+    history.sort((left, right) => left.next.revision - right.next.revision || left.transitionId.localeCompare(right.transitionId));
+    let prior: PublicationPointerTransitionV1 | undefined;
+    const activatedVersions = new Set<string>();
+    for (const transition of history) {
+      const advancesOnce = transition.next.revision === (transition.previous?.revision ?? 0) + 1;
+      const chainStarts = !prior && transition.previous === null && advancesOnce;
+      const chainContinues = !!prior && transition.previous !== null &&
+        advancesOnce && snapshotsEqual(transition.previous, prior.next) &&
+        transition.occurredAt >= prior.occurredAt;
+      if (!chainStarts && !chainContinues) {
+        violations.push({
+          path: "transitions",
+          code: "publication_transition_chain",
+          message: "Publication transition history is not a contiguous monotonic pointer chain.",
+        });
+        break;
+      }
+      if (transition.operation === "rollback" &&
+        (!activatedVersions.has(transition.next.versionId) ||
+          transition.previous?.versionId === transition.next.versionId)) {
+        violations.push({
+          path: "transitions",
+          code: "publication_rollback_target_not_prior",
+          message: "Publication rollback target is not a prior activation in this pointer chain.",
+        });
+        break;
+      }
+      if (transition.operation === "activate") activatedVersions.add(transition.next.versionId);
+      prior = transition;
+    }
+    const pointer = pointerByChannel.get(key);
+    if (!pointer || !prior || !snapshotsEqual(snapshot(pointer), prior.next) || pointer.updatedAt !== prior.occurredAt) {
+      violations.push({
+        path: "pointers",
+        code: "publication_pointer_history_mismatch",
+        message: "Publication pointer does not equal the terminal audited transition.",
+      });
+    }
+  }
+  for (const pointer of pointers) {
+    if (!historyByChannel.has(pointerKey(pointer))) {
+      violations.push({
+        path: "pointers",
+        code: "publication_pointer_history_missing",
+        message: "Publication pointer has no audited transition history.",
+      });
+    }
+  }
+  if (violations.length > 0) return { ok: false, violations };
+  return {
+    ok: true,
+    value: {
+      versions: versions.sort(compareVersion),
+      pointers: pointers.sort(comparePointer),
+      transitions: transitions.sort(compareTransition),
+    },
+  };
+}
+
+/** Resolve one validated channel pointer and its exact immutable version. */
+export function resolvePublicationChannelVersionV1(
+  stateRaw: PublicationVersionStateV1,
+  tenant: string,
+  spaceId: string,
+  channel: PublicationChannelV1,
+): { pointer: PublicationChannelPointerV1; version: PublicationVersionV1 } | null {
+  const state = validatePublicationVersionStateV1(stateRaw);
+  if (!state.ok) return null;
+  const pointer = state.value.pointers.find((item) => item.tenant === tenant && item.spaceId === spaceId && item.channel === channel);
+  if (!pointer) return null;
+  const version = state.value.versions.find((item) => item.tenant === tenant && item.spaceId === spaceId && item.versionId === pointer.versionId);
+  if (!version || version.source.commitSha !== pointer.sourceSha || version.artifactDigest !== pointer.artifactDigest) return null;
+  return { pointer, version };
+}