@modelprofile.com/flexharness 3.6.0 → 3.8.0

package/ts/utils.json.ts

@@ -1,8 +1,18 @@
 import { FlexHarnessStoreFormatError, FlexHarnessValidationError } from './errors.js';
+import {
+  FLEX_REVERSION_MAX_AFFECTED_WORKSPACES,
+  FLEX_REVERSION_MAXIMUM_LIMITS,
+  FLEX_REVERSION_REASON_CODE_MAX_BYTES,
+  FLEX_REVERSION_REFERENCE_MAX_BYTES,
+  FLEX_REVERSION_WORKSPACE_ID_MAX_BYTES,
+  FLEX_REVERSION_WORKSPACE_LABEL_MAX_BYTES,
+} from './interfaces.js';
 import type {
   IFlexJsonLimits,
   IFlexPermissionSnapshot,
-  IFlexProjectionSnapshot,
+  IFlexProjectionSnapshotV1,
+  IFlexProjectionSnapshotV2,
+  IFlexProjectionSnapshotV3,
   IFlexScopeSnapshot,
   TFlexAgentModelMessage,
   TJsonValue,
@@ -390,8 +400,8 @@ function requireString(value: unknown, path: string): string {
   return value;
 }
 
-function requireOptionalString(value: unknown, path: string): void {
-  if (value !== undefined) requireString(value, path);
+function requireOptionalString(value: unknown, path: string): string | undefined {
+  return value === undefined ? undefined : requireString(value, path);
 }
 
 function requireNonNegativeNumber(value: unknown, path: string): void {
@@ -873,15 +883,12 @@ export function assertFlexScopeSnapshot(value: unknown): asserts value is IFlexS
   }
 }
 
-export function assertFlexProjectionSnapshot(
-  value: unknown,
-): asserts value is IFlexProjectionSnapshot {
-  const snapshot = validateSnapshotHeader(value, [
-    'schemaVersion',
-    'revision',
-    'messages',
-    'stagedTerminals',
-  ]);
+interface IValidatedProjectionBody {
+  messages: IValidatedMessageIdentity[];
+  stagedUsers: IValidatedMessageIdentity[];
+}
+
+function validateProjectionBody(snapshot: Record<string, unknown>): IValidatedProjectionBody {
   const visibleMessages = validateMessages(snapshot.messages, '$snapshot.messages');
   let projectionSessionId = visibleMessages[0]?.sessionId;
   if (visibleMessages.some((message) => message.sessionId !== projectionSessionId)) {
@@ -892,6 +899,7 @@ export function assertFlexProjectionSnapshot(
   }
   const runIds = new Set<string>();
   const stagedMessageIds = new Set<string>();
+  const stagedUsers: IValidatedMessageIdentity[] = [];
   for (let index = 0; index < snapshot.stagedTerminals.length; index++) {
     const path = `$snapshot.stagedTerminals[${index}]`;
     const terminal = requireRecord(snapshot.stagedTerminals[index], path);
@@ -928,6 +936,10 @@ export function assertFlexProjectionSnapshot(
     if (assistant.status !== terminal.status) {
       throw new FlexHarnessStoreFormatError(`${path}.status does not match its assistant message.`);
     }
+    if (user.status !== terminal.status) {
+      throw new FlexHarnessStoreFormatError(`${path}.status does not match its user message.`);
+    }
+    stagedUsers.push(user);
     projectionSessionId ??= user.sessionId;
     if (user.sessionId !== projectionSessionId) {
       throw new FlexHarnessStoreFormatError(`${path} belongs to another session.`);
@@ -945,6 +957,525 @@ export function assertFlexProjectionSnapshot(
     requireOptionalString(terminal.finishReason, `${path}.finishReason`);
     if (terminal.steps !== undefined) requireNonNegativeInteger(terminal.steps, `${path}.steps`);
   }
+  return { messages: visibleMessages, stagedUsers };
+}
+
+export function assertFlexProjectionSnapshotV1(
+  value: unknown,
+): asserts value is IFlexProjectionSnapshotV1 {
+  const snapshot = validateSnapshotHeader(value, [
+    'schemaVersion',
+    'revision',
+    'messages',
+    'stagedTerminals',
+  ]);
+  validateProjectionBody(snapshot);
+}
+
+export function assertFlexProjectionSnapshotV2(
+  value: unknown,
+): asserts value is IFlexProjectionSnapshotV2 {
+  assertJsonSerializable(value, '$snapshot');
+  const snapshot = requireRecord(value, '$snapshot');
+  requireOnlyKeys(snapshot, [
+    'schemaVersion',
+    'revision',
+    'messages',
+    'stagedTerminals',
+    'reversionSegments',
+    'revertCursor',
+    'excludedRunIds',
+    'pendingReversion',
+    'pendingReversionReleases',
+  ], '$snapshot');
+  if (snapshot.schemaVersion !== 2) {
+    throw new FlexHarnessStoreFormatError('Projection snapshot schemaVersion must be 2.');
+  }
+  requireNonNegativeInteger(snapshot.revision, 'Snapshot revision');
+  const projectionBody = validateProjectionBody(snapshot);
+  const segments = Array.isArray(snapshot.reversionSegments)
+    ? snapshot.reversionSegments
+    : (() => { throw new FlexHarnessStoreFormatError('Snapshot reversionSegments must be an array.'); })();
+  if (segments.length > FLEX_REVERSION_MAXIMUM_LIMITS.maxSegments) {
+    throw new FlexHarnessStoreFormatError('Snapshot reversionSegments exceeds its hard limit.');
+  }
+  const segmentRunIds = new Set<string>();
+  const segmentCaptureIds = new Set<string>();
+  const segmentEventIds = new Set<string>();
+  const capturingWorkspaceSegments = new Map<string, string>();
+  for (let index = 0; index < segments.length; index++) {
+    const path = `$snapshot.reversionSegments[${index}]`;
+    const segment = requireRecord(segments[index], path);
+    requireOnlyKeys(segment, [
+      'runId',
+      'userMessageId',
+      'status',
+      'contextAvailable',
+      'eventIds',
+      'workspaceCaptured',
+      'captureId',
+      'workspaceReference',
+    ], path);
+    const runId = requireString(segment.runId, `${path}.runId`);
+    const userMessageId = requireString(segment.userMessageId, `${path}.userMessageId`);
+    if (segmentRunIds.has(runId)) {
+      throw new FlexHarnessStoreFormatError(`Snapshot contains duplicate reversion run "${runId}".`);
+    }
+    segmentRunIds.add(runId);
+    if (!['capturing', 'completed', 'failed', 'cancelled'].includes(String(segment.status))) {
+      throw new FlexHarnessStoreFormatError(`${path}.status is invalid.`);
+    }
+    if (typeof segment.contextAvailable !== 'boolean') {
+      throw new FlexHarnessStoreFormatError(`${path}.contextAvailable must be a boolean.`);
+    }
+    const eventIds = requireStringArray(segment.eventIds, `${path}.eventIds`);
+    if (eventIds.some((id) => !id) || new Set(eventIds).size !== eventIds.length) {
+      throw new FlexHarnessStoreFormatError(`${path}.eventIds is invalid.`);
+    }
+    for (const eventId of eventIds) {
+      if (segmentEventIds.has(eventId)) {
+        throw new FlexHarnessStoreFormatError(`Snapshot reuses reversion event "${eventId}".`);
+      }
+      segmentEventIds.add(eventId);
+    }
+    if (typeof segment.workspaceCaptured !== 'boolean') {
+      throw new FlexHarnessStoreFormatError(`${path}.workspaceCaptured must be a boolean.`);
+    }
+    const captureId = requireOptionalString(segment.captureId, `${path}.captureId`);
+    if (segment.workspaceCaptured && captureId === undefined) {
+      throw new FlexHarnessStoreFormatError(`${path} is capture-backed without a capture ID.`);
+    }
+    if (captureId !== undefined) {
+      if (segmentCaptureIds.has(captureId)) {
+        throw new FlexHarnessStoreFormatError(`Snapshot contains duplicate capture "${captureId}".`);
+      }
+      segmentCaptureIds.add(captureId);
+      if (segment.status === 'capturing') capturingWorkspaceSegments.set(runId, captureId);
+    }
+    if (!segment.workspaceCaptured && (captureId !== undefined || segment.workspaceReference !== undefined)) {
+      throw new FlexHarnessStoreFormatError(`${path} is transcript-only but contains workspace capture data.`);
+    }
+    if (
+      segment.workspaceCaptured
+      && segment.status !== 'capturing'
+      && segment.workspaceReference === undefined
+    ) {
+      throw new FlexHarnessStoreFormatError(`${path} is terminal but has no workspace reference.`);
+    }
+    if (segment.status === 'capturing' && segment.workspaceReference !== undefined) {
+      throw new FlexHarnessStoreFormatError(`${path} is capturing but already has a workspace reference.`);
+    }
+    if (segment.workspaceReference !== undefined) {
+      if (captureId === undefined) {
+        throw new FlexHarnessStoreFormatError(`${path} has a workspace reference without a capture ID.`);
+      }
+      if (Buffer.byteLength(JSON.stringify(segment.workspaceReference)) > FLEX_REVERSION_REFERENCE_MAX_BYTES) {
+        throw new FlexHarnessStoreFormatError(`${path}.workspaceReference exceeds its byte limit.`);
+      }
+    }
+    const correlatedUsers = new Set([...projectionBody.messages, ...projectionBody.stagedUsers]
+      .filter((message) =>
+        message.role === 'user' && message.runId === runId && message.messageId === userMessageId)
+      .map((message) => `${message.runId}:${message.messageId}`));
+    if (correlatedUsers.size !== 1) {
+      throw new FlexHarnessStoreFormatError(`${path} does not match exactly one projected user message.`);
+    }
+  }
+  requireNonNegativeInteger(snapshot.revertCursor, '$snapshot.revertCursor');
+  const candidateCount = segments.filter((segment) => {
+    const record = segment as Record<string, unknown>;
+    return record.status === 'completed';
+  }).length;
+  if (candidateCount > FLEX_REVERSION_MAXIMUM_LIMITS.maxCompletedTurns) {
+    throw new FlexHarnessStoreFormatError('Snapshot completed reversion turns exceed their hard limit.');
+  }
+  if (Number(snapshot.revertCursor) > candidateCount) {
+    throw new FlexHarnessStoreFormatError('Snapshot revertCursor exceeds its candidate count.');
+  }
+  const excludedRunIds = requireStringArray(snapshot.excludedRunIds, '$snapshot.excludedRunIds');
+  if (
+    excludedRunIds.some((id) => !id)
+    || new Set(excludedRunIds).size !== excludedRunIds.length
+  ) throw new FlexHarnessStoreFormatError('Snapshot excludedRunIds is invalid.');
+  if (excludedRunIds.length > FLEX_REVERSION_MAXIMUM_LIMITS.maxExcludedRunIds) {
+    throw new FlexHarnessStoreFormatError('Snapshot excludedRunIds exceeds its hard limit.');
+  }
+  if (snapshot.pendingReversion !== undefined) {
+    const pending = requireRecord(snapshot.pendingReversion, '$snapshot.pendingReversion');
+    if (pending.kind === 'capture') {
+      requireOnlyKeys(pending, ['kind', 'runId', 'captureId', 'state'], '$snapshot.pendingReversion');
+      const pendingRunId = requireString(pending.runId, '$snapshot.pendingReversion.runId');
+      const pendingCaptureId = requireString(pending.captureId, '$snapshot.pendingReversion.captureId');
+      if (!['preparing', 'prepared', 'finalizing'].includes(String(pending.state))) {
+        throw new FlexHarnessStoreFormatError('Snapshot pending capture state is invalid.');
+      }
+      const matches = segments.filter((segment) => {
+        const record = segment as Record<string, unknown>;
+        return record.runId === pendingRunId
+          && record.captureId === pendingCaptureId
+          && record.workspaceCaptured === true
+          && record.status === 'capturing';
+      });
+      if (matches.length !== 1) {
+        throw new FlexHarnessStoreFormatError('Snapshot pending capture does not match exactly one segment.');
+      }
+      capturingWorkspaceSegments.delete(pendingRunId);
+    } else if (pending.kind === 'apply') {
+      requireOnlyKeys(pending, [
+        'kind',
+        'operationId',
+        'direction',
+        'fromCursor',
+        'toCursor',
+        'segmentRunIds',
+        'appliedRunIds',
+      ], '$snapshot.pendingReversion');
+      requireString(pending.operationId, '$snapshot.pendingReversion.operationId');
+      if (!['undo', 'redo'].includes(String(pending.direction))) {
+        throw new FlexHarnessStoreFormatError('Snapshot pending apply direction is invalid.');
+      }
+      requireNonNegativeInteger(pending.fromCursor, '$snapshot.pendingReversion.fromCursor');
+      requireNonNegativeInteger(pending.toCursor, '$snapshot.pendingReversion.toCursor');
+      const pendingRuns = requireStringArray(
+        pending.segmentRunIds,
+        '$snapshot.pendingReversion.segmentRunIds',
+      );
+      const appliedRuns = requireStringArray(
+        pending.appliedRunIds,
+        '$snapshot.pendingReversion.appliedRunIds',
+      );
+      if (new Set(pendingRuns).size !== pendingRuns.length || new Set(appliedRuns).size !== appliedRuns.length) {
+        throw new FlexHarnessStoreFormatError('Snapshot pending apply run IDs are invalid.');
+      }
+      if (appliedRuns.some((runId) => !pendingRuns.includes(runId))) {
+        throw new FlexHarnessStoreFormatError('Snapshot pending apply progress is invalid.');
+      }
+      const fromCursor = Number(pending.fromCursor);
+      const toCursor = Number(pending.toCursor);
+      const direction = pending.direction as 'undo' | 'redo';
+      const completed = segments.filter((segment) =>
+        (segment as Record<string, unknown>).status === 'completed');
+      if (
+        fromCursor !== Number(snapshot.revertCursor)
+        || (direction === 'undo' && !(toCursor >= 0 && toCursor < fromCursor))
+        || (direction === 'redo' && !(toCursor > fromCursor && toCursor <= completed.length))
+      ) {
+        throw new FlexHarnessStoreFormatError('Snapshot pending apply cursor movement is invalid.');
+      }
+      const rangeStart = Math.min(fromCursor, toCursor);
+      const rangeEnd = Math.max(fromCursor, toCursor);
+      const first = completed[rangeStart];
+      if (!first) throw new FlexHarnessStoreFormatError('Snapshot pending apply has no target candidate.');
+      const firstRunId = (first as Record<string, unknown>).runId;
+      const start = rangeStart === 0
+        ? 0
+        : segments.findIndex((segment) =>
+            (segment as Record<string, unknown>).runId === firstRunId);
+      const next = completed[rangeEnd];
+      const end = next
+        ? segments.findIndex((segment) =>
+            (segment as Record<string, unknown>).runId === (next as Record<string, unknown>).runId)
+        : segments.length;
+      const exactRuns = segments.slice(start, end).map((segment) =>
+        String((segment as Record<string, unknown>).runId));
+      if (JSON.stringify(pendingRuns) !== JSON.stringify(exactRuns)) {
+        throw new FlexHarnessStoreFormatError('Snapshot pending apply segment unit is invalid.');
+      }
+      const applyOrder = direction === 'undo' ? [...exactRuns].reverse() : exactRuns;
+      if (JSON.stringify(appliedRuns) !== JSON.stringify(applyOrder.slice(0, appliedRuns.length))) {
+        throw new FlexHarnessStoreFormatError('Snapshot pending apply progress is out of order.');
+      }
+    } else {
+      throw new FlexHarnessStoreFormatError('Snapshot pendingReversion kind is invalid.');
+    }
+  }
+  if (capturingWorkspaceSegments.size > 0) {
+    throw new FlexHarnessStoreFormatError(
+      'Snapshot contains a capture-backed capturing segment without exact pending ownership.',
+    );
+  }
+  if (!Array.isArray(snapshot.pendingReversionReleases)) {
+    throw new FlexHarnessStoreFormatError('Snapshot pendingReversionReleases must be an array.');
+  }
+  if (
+    snapshot.pendingReversionReleases.length
+    > FLEX_REVERSION_MAXIMUM_LIMITS.maxPendingReversionReleases
+  ) {
+    throw new FlexHarnessStoreFormatError('Snapshot pending reversion releases exceed their hard limit.');
+  }
+  const releaseCaptureIds = new Set<string>();
+  for (let index = 0; index < snapshot.pendingReversionReleases.length; index++) {
+    const path = `$snapshot.pendingReversionReleases[${index}]`;
+    const release = requireRecord(snapshot.pendingReversionReleases[index], path);
+    requireOnlyKeys(release, ['runId', 'captureId', 'reference'], path);
+    requireString(release.runId, `${path}.runId`);
+    const captureId = requireString(release.captureId, `${path}.captureId`);
+    if (releaseCaptureIds.has(captureId)) {
+      throw new FlexHarnessStoreFormatError(`Snapshot contains duplicate release capture "${captureId}".`);
+    }
+    releaseCaptureIds.add(captureId);
+    if (!Object.prototype.hasOwnProperty.call(release, 'reference')) {
+      throw new FlexHarnessStoreFormatError(`${path}.reference is required.`);
+    }
+    if (Buffer.byteLength(JSON.stringify(release.reference)) > FLEX_REVERSION_REFERENCE_MAX_BYTES) {
+      throw new FlexHarnessStoreFormatError(`${path}.reference exceeds its byte limit.`);
+    }
+  }
+}
+
+function requireBoundedString(value: unknown, path: string, maxBytes: number): string {
+  const result = requireString(value, path);
+  if (Buffer.byteLength(result, 'utf8') > maxBytes) {
+    throw new FlexHarnessStoreFormatError(`${path} exceeds its byte limit.`);
+  }
+  return result;
+}
+
+function validateAffectedWorkspaces(value: unknown, path: string): void {
+  if (!Array.isArray(value)) {
+    throw new FlexHarnessStoreFormatError(`${path} must be an array.`);
+  }
+  if (value.length > FLEX_REVERSION_MAX_AFFECTED_WORKSPACES) {
+    throw new FlexHarnessStoreFormatError(`${path} exceeds its item limit.`);
+  }
+  const ids = new Set<string>();
+  for (let index = 0; index < value.length; index++) {
+    const workspacePath = `${path}[${index}]`;
+    const workspace = requireRecord(value[index], workspacePath);
+    requireOnlyKeys(workspace, ['id', 'label'], workspacePath);
+    const id = requireBoundedString(
+      workspace.id,
+      `${workspacePath}.id`,
+      FLEX_REVERSION_WORKSPACE_ID_MAX_BYTES,
+    );
+    if (!id.trim()) {
+      throw new FlexHarnessStoreFormatError(`${workspacePath}.id must contain non-whitespace characters.`);
+    }
+    const label = requireBoundedString(
+      workspace.label,
+      `${workspacePath}.label`,
+      FLEX_REVERSION_WORKSPACE_LABEL_MAX_BYTES,
+    );
+    if (!label.trim()) {
+      throw new FlexHarnessStoreFormatError(`${workspacePath}.label must contain non-whitespace characters.`);
+    }
+    if (ids.has(id)) {
+      throw new FlexHarnessStoreFormatError(`${path} contains duplicate workspace "${id}".`);
+    }
+    ids.add(id);
+  }
+}
+
+export function assertFlexProjectionSnapshotV3(
+  value: unknown,
+): asserts value is IFlexProjectionSnapshotV3 {
+  assertJsonSerializable(value, '$snapshot');
+  const snapshot = requireRecord(value, '$snapshot');
+  requireOnlyKeys(snapshot, [
+    'schemaVersion',
+    'revision',
+    'messages',
+    'stagedTerminals',
+    'reversionSegments',
+    'revertCursor',
+    'excludedRunIds',
+    'pendingReversion',
+    'pendingReversionReleases',
+  ], '$snapshot');
+  if (snapshot.schemaVersion !== 3) {
+    throw new FlexHarnessStoreFormatError('Projection snapshot schemaVersion must be 3.');
+  }
+  if (!Array.isArray(snapshot.reversionSegments)) {
+    throw new FlexHarnessStoreFormatError('Snapshot reversionSegments must be an array.');
+  }
+  const retainedCaptureIds = new Set<string>();
+  for (let index = 0; index < snapshot.reversionSegments.length; index++) {
+    const path = `$snapshot.reversionSegments[${index}]`;
+    const segment = requireRecord(snapshot.reversionSegments[index], path);
+    requireOnlyKeys(segment, [
+      'runId',
+      'userMessageId',
+      'status',
+      'contextAvailable',
+      'eventIds',
+      'workspaceCaptured',
+      'captureId',
+      'workspaceReference',
+      'protocolVersion',
+      'provenance',
+      'disposition',
+      'affectedWorkspaces',
+      'reasonCode',
+    ], path);
+    const protocolVersion = segment.protocolVersion;
+    if (protocolVersion !== 1 && protocolVersion !== 2) {
+      throw new FlexHarnessStoreFormatError(`${path}.protocolVersion is invalid.`);
+    }
+    if (segment.provenance !== 'transcript' && segment.provenance !== 'workspace') {
+      throw new FlexHarnessStoreFormatError(`${path}.provenance is invalid.`);
+    }
+    if (segment.workspaceCaptured !== (segment.provenance === 'workspace')) {
+      throw new FlexHarnessStoreFormatError(`${path}.workspaceCaptured does not match its provenance.`);
+    }
+    if (protocolVersion === 2 && segment.provenance !== 'workspace') {
+      throw new FlexHarnessStoreFormatError(`${path} uses protocol 2 without workspace provenance.`);
+    }
+    if (protocolVersion === 1 && segment.affectedWorkspaces !== undefined) {
+      throw new FlexHarnessStoreFormatError(`${path} protocol 1 contains affected workspace metadata.`);
+    }
+    const status = String(segment.status);
+    const disposition = segment.disposition;
+    const captureId = segment.captureId;
+    if (captureId !== undefined) retainedCaptureIds.add(String(captureId));
+    if (segment.affectedWorkspaces !== undefined) {
+      validateAffectedWorkspaces(segment.affectedWorkspaces, `${path}.affectedWorkspaces`);
+    }
+    if (segment.reasonCode !== undefined) {
+      const reasonCode = requireBoundedString(
+        segment.reasonCode,
+        `${path}.reasonCode`,
+        FLEX_REVERSION_REASON_CODE_MAX_BYTES,
+      );
+      if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/u.test(reasonCode)) {
+        throw new FlexHarnessStoreFormatError(`${path}.reasonCode is invalid.`);
+      }
+    }
+    if (segment.provenance === 'transcript') {
+      if (
+        disposition !== undefined
+        || captureId !== undefined
+        || segment.workspaceReference !== undefined
+        || segment.affectedWorkspaces !== undefined
+        || segment.reasonCode !== undefined
+      ) throw new FlexHarnessStoreFormatError(`${path} transcript provenance contains workspace data.`);
+      continue;
+    }
+    if (status === 'capturing') {
+      if (disposition !== 'pending' || captureId === undefined || segment.workspaceReference !== undefined) {
+        throw new FlexHarnessStoreFormatError(`${path} has invalid pending workspace ownership.`);
+      }
+      if (segment.affectedWorkspaces !== undefined || segment.reasonCode !== undefined) {
+        throw new FlexHarnessStoreFormatError(`${path} pending workspace capture has terminal metadata.`);
+      }
+      continue;
+    }
+    if (protocolVersion === 1 && disposition !== 'revertible') {
+      throw new FlexHarnessStoreFormatError(`${path} terminal protocol-1 workspace capture is not revertible.`);
+    }
+    if (protocolVersion === 2 && !['revertible', 'no-change', 'nonrevertible'].includes(String(disposition))) {
+      throw new FlexHarnessStoreFormatError(`${path} terminal protocol-2 capture lacks a conclusive disposition.`);
+    }
+    if (disposition === 'revertible') {
+      if (captureId === undefined || segment.workspaceReference === undefined) {
+        throw new FlexHarnessStoreFormatError(`${path} revertible capture lacks retained ownership.`);
+      }
+      if (protocolVersion === 2 && segment.affectedWorkspaces === undefined) {
+        throw new FlexHarnessStoreFormatError(`${path} revertible protocol-2 capture lacks affected workspaces.`);
+      }
+      if (segment.reasonCode !== undefined) {
+        throw new FlexHarnessStoreFormatError(`${path} revertible capture has a reason code.`);
+      }
+    } else {
+      if (captureId !== undefined || segment.workspaceReference !== undefined) {
+        throw new FlexHarnessStoreFormatError(`${path} terminal disposition retains segment ownership.`);
+      }
+      if (disposition === 'no-change') {
+        if (Array.isArray(segment.affectedWorkspaces) && segment.affectedWorkspaces.length > 0) {
+          throw new FlexHarnessStoreFormatError(`${path} no-change capture affects a workspace.`);
+        }
+        if (segment.reasonCode !== undefined) {
+          throw new FlexHarnessStoreFormatError(`${path} no-change capture has a reason code.`);
+        }
+      }
+      if (disposition === 'nonrevertible' && segment.reasonCode === undefined) {
+        throw new FlexHarnessStoreFormatError(`${path} nonrevertible capture lacks a reason code.`);
+      }
+    }
+  }
+  if (snapshot.pendingReversion !== undefined) {
+    const pending = requireRecord(snapshot.pendingReversion, '$snapshot.pendingReversion');
+    if (pending.kind === 'capture') {
+      requireOnlyKeys(
+        pending,
+        ['kind', 'runId', 'captureId', 'state', 'protocolVersion'],
+        '$snapshot.pendingReversion',
+      );
+      if (pending.protocolVersion !== 1 && pending.protocolVersion !== 2) {
+        throw new FlexHarnessStoreFormatError('$snapshot.pendingReversion.protocolVersion is invalid.');
+      }
+      const matching = snapshot.reversionSegments.filter((entry) => {
+        const segment = entry as Record<string, unknown>;
+        return segment.runId === pending.runId
+          && segment.captureId === pending.captureId
+          && segment.protocolVersion === pending.protocolVersion
+          && segment.status === 'capturing'
+          && segment.disposition === 'pending';
+      });
+      if (matching.length !== 1) {
+        throw new FlexHarnessStoreFormatError('Snapshot pending capture does not match exactly one segment.');
+      }
+    }
+  }
+  if (!Array.isArray(snapshot.pendingReversionReleases)) {
+    throw new FlexHarnessStoreFormatError('Snapshot pendingReversionReleases must be an array.');
+  }
+  const releaseCaptureIds = new Set<string>();
+  for (let index = 0; index < snapshot.pendingReversionReleases.length; index++) {
+    const path = `$snapshot.pendingReversionReleases[${index}]`;
+    const release = requireRecord(snapshot.pendingReversionReleases[index], path);
+    requireOnlyKeys(release, ['runId', 'captureId', 'reference', 'protocolVersion'], path);
+    const captureId = requireString(release.captureId, `${path}.captureId`);
+    if (release.protocolVersion !== 1 && release.protocolVersion !== 2) {
+      throw new FlexHarnessStoreFormatError(`${path}.protocolVersion is invalid.`);
+    }
+    if (releaseCaptureIds.has(captureId) || retainedCaptureIds.has(captureId)) {
+      throw new FlexHarnessStoreFormatError(`${path} has duplicate durable capture ownership.`);
+    }
+    releaseCaptureIds.add(captureId);
+  }
+  const compatibleV2 = {
+    ...snapshot,
+    schemaVersion: 2,
+    reversionSegments: snapshot.reversionSegments.map((entry) => {
+      const segment = entry as Record<string, unknown>;
+      return {
+        runId: segment.runId,
+        userMessageId: segment.userMessageId,
+        status: segment.status,
+        contextAvailable: segment.contextAvailable,
+        eventIds: segment.eventIds,
+        workspaceCaptured: segment.provenance === 'workspace'
+          && (segment.status === 'capturing' || segment.disposition === 'revertible'),
+        ...(segment.captureId === undefined ? {} : { captureId: segment.captureId }),
+        ...(segment.workspaceReference === undefined
+          ? {}
+          : { workspaceReference: segment.workspaceReference }),
+      };
+    }),
+    ...(snapshot.pendingReversion === undefined
+      ? {}
+      : {
+          pendingReversion: (() => {
+            const { protocolVersion: _protocolVersion, ...pending } = snapshot.pendingReversion as
+              Record<string, unknown>;
+            return pending;
+          })(),
+        }),
+    pendingReversionReleases: snapshot.pendingReversionReleases.map((entry) => {
+      const { protocolVersion: _protocolVersion, ...release } = entry as Record<string, unknown>;
+      return release;
+    }),
+  };
+  assertFlexProjectionSnapshotV2(compatibleV2);
+}
+
+export function assertFlexProjectionSnapshot(
+  value: unknown,
+): asserts value is IFlexProjectionSnapshotV1 | IFlexProjectionSnapshotV2 | IFlexProjectionSnapshotV3 {
+  const record = requireRecord(value, '$snapshot');
+  if (record.schemaVersion === 1) assertFlexProjectionSnapshotV1(value);
+  else if (record.schemaVersion === 2) assertFlexProjectionSnapshotV2(value);
+  else assertFlexProjectionSnapshotV3(value);
 }
 
 export function assertFlexPermissionSnapshot(