@modelprofile.com/flexharness 3.7.0 → 4.0.0

package/ts/utils.json.ts

@@ -1,13 +1,19 @@
 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,
+  FLEX_SESSION_GENERATION_ID_MAX_BYTES,
 } from './interfaces.js';
 import type {
   IFlexJsonLimits,
   IFlexPermissionSnapshot,
   IFlexProjectionSnapshotV1,
   IFlexProjectionSnapshotV2,
+  IFlexProjectionSnapshotV3,
   IFlexScopeSnapshot,
   TFlexAgentModelMessage,
   TJsonValue,
@@ -427,6 +433,39 @@ const activityStatuses = [
   'cancelled',
 ] as const;
 
+function validateOptionalSessionGeneration(
+  value: Record<string, unknown>,
+  path: string,
+): { sessionGenerationId?: string; sessionGenerationSequence?: number } {
+  const hasId = value.sessionGenerationId !== undefined;
+  const hasSequence = value.sessionGenerationSequence !== undefined;
+  if (hasId !== hasSequence) {
+    throw new FlexHarnessStoreFormatError(`${path} has partial session generation fields.`);
+  }
+  if (!hasId) return {};
+  const sessionGenerationId = requireString(
+    value.sessionGenerationId,
+    `${path}.sessionGenerationId`,
+  );
+  if (Buffer.byteLength(sessionGenerationId, 'utf8') > FLEX_SESSION_GENERATION_ID_MAX_BYTES) {
+    throw new FlexHarnessStoreFormatError(
+      `${path}.sessionGenerationId exceeds ${FLEX_SESSION_GENERATION_ID_MAX_BYTES} UTF-8 bytes.`,
+    );
+  }
+  if (
+    !Number.isSafeInteger(value.sessionGenerationSequence)
+    || Number(value.sessionGenerationSequence) < 1
+  ) {
+    throw new FlexHarnessStoreFormatError(
+      `${path}.sessionGenerationSequence must be a positive integer.`,
+    );
+  }
+  return {
+    sessionGenerationId,
+    sessionGenerationSequence: value.sessionGenerationSequence as number,
+  };
+}
+
 function validateSession(value: unknown, path: string): IValidatedSessionIdentity {
   const session = requireRecord(value, path);
   requireOnlyKeys(
@@ -434,6 +473,8 @@ function validateSession(value: unknown, path: string): IValidatedSessionIdentit
     [
       'scopeId',
       'sessionId',
+      'sessionGenerationId',
+      'sessionGenerationSequence',
       'title',
       'createdAt',
       'updatedAt',
@@ -450,6 +491,7 @@ function validateSession(value: unknown, path: string): IValidatedSessionIdentit
   );
   requireString(session.scopeId, `${path}.scopeId`);
   const sessionId = requireString(session.sessionId, `${path}.sessionId`);
+  const generation = validateOptionalSessionGeneration(session, path);
   requireOptionalString(session.title, `${path}.title`);
   requireString(session.createdAt, `${path}.createdAt`);
   requireString(session.updatedAt, `${path}.updatedAt`);
@@ -491,6 +533,7 @@ function validateSession(value: unknown, path: string): IValidatedSessionIdentit
   }
   return {
     sessionId,
+    ...generation,
     ...(relationshipCount === 0
       ? {}
       : {
@@ -536,6 +579,8 @@ interface IValidatedMessageIdentity {
 
 interface IValidatedSessionIdentity {
   sessionId: string;
+  sessionGenerationId?: string;
+  sessionGenerationSequence?: number;
   parentSessionId?: string;
   parentRunId?: string;
   parentToolCallId?: string;
@@ -775,10 +820,19 @@ export function assertFlexScopeSnapshot(value: unknown): asserts value is IFlexS
     const tombstone = requireRecord(snapshot.tombstones[index], path);
     requireOnlyKeys(
       tombstone,
-      ['sessionId', 'deletedAt', 'rootSessionId', 'depth', 'parentSessionId'],
+      [
+        'sessionId',
+        'sessionGenerationId',
+        'sessionGenerationSequence',
+        'deletedAt',
+        'rootSessionId',
+        'depth',
+        'parentSessionId',
+      ],
       path,
     );
     const sessionId = requireString(tombstone.sessionId, `${path}.sessionId`);
+    validateOptionalSessionGeneration(tombstone, path);
     requireString(tombstone.deletedAt, `${path}.deletedAt`);
     const parentSessionId = tombstone.parentSessionId === undefined
       ? undefined
@@ -1148,18 +1202,25 @@ export function assertFlexProjectionSnapshotV2(
       const fromCursor = Number(pending.fromCursor);
       const toCursor = Number(pending.toCursor);
       const direction = pending.direction as 'undo' | 'redo';
-      if (fromCursor !== Number(snapshot.revertCursor) || toCursor !== fromCursor + (direction === 'undo' ? -1 : 1)) {
-        throw new FlexHarnessStoreFormatError('Snapshot pending apply cursor movement is invalid.');
-      }
       const completed = segments.filter((segment) =>
         (segment as Record<string, unknown>).status === 'completed');
-      const target = direction === 'undo' ? completed[fromCursor - 1] : completed[fromCursor];
-      if (!target) throw new FlexHarnessStoreFormatError('Snapshot pending apply has no target candidate.');
-      const targetRunId = (target as Record<string, unknown>).runId;
-      const targetIndex = segments.findIndex((segment) =>
-        (segment as Record<string, unknown>).runId === targetRunId);
-      const start = target === completed[0] ? 0 : targetIndex;
-      const next = completed[direction === 'undo' ? fromCursor : fromCursor + 1];
+      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)
@@ -1211,12 +1272,259 @@ export function assertFlexProjectionSnapshotV2(
   }
 }
 
+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 {
+): asserts value is IFlexProjectionSnapshotV1 | IFlexProjectionSnapshotV2 | IFlexProjectionSnapshotV3 {
   const record = requireRecord(value, '$snapshot');
   if (record.schemaVersion === 1) assertFlexProjectionSnapshotV1(value);
-  else assertFlexProjectionSnapshotV2(value);
+  else if (record.schemaVersion === 2) assertFlexProjectionSnapshotV2(value);
+  else assertFlexProjectionSnapshotV3(value);
 }
 
 export function assertFlexPermissionSnapshot(

package/ts/utils.projectmanagement.ts

@@ -0,0 +1,226 @@
+import {
+  FlexHarnessStoreFormatError,
+} from './errors.js';
+import {
+  FLEX_PROJECT_MANAGEMENT_LIMITS,
+  FLEX_PROJECT_MANAGEMENT_SCHEMA_VERSION,
+  FLEX_SESSION_GENERATION_ID_MAX_BYTES,
+} from './interfaces.js';
+import type {
+  IFlexProjectManagementSnapshot,
+  IFlexProjectManagementTombstone,
+  IFlexProjectTask,
+  TFlexProjectManagementRecord,
+} from './interfaces.js';
+import { assertJsonSerializable } from './utils.json.js';
+
+function requireRecord(value: unknown, path: string): Record<string, unknown> {
+  if (
+    !value
+    || typeof value !== 'object'
+    || Array.isArray(value)
+    || ![Object.prototype, null].includes(Object.getPrototypeOf(value))
+  ) {
+    throw new FlexHarnessStoreFormatError(`${path} must be a plain object.`);
+  }
+  return value as Record<string, unknown>;
+}
+
+function requireOnlyKeys(
+  value: Record<string, unknown>,
+  keys: readonly string[],
+  path: string,
+): void {
+  const unsupported = Object.keys(value).find((key) => !keys.includes(key));
+  if (unsupported) {
+    throw new FlexHarnessStoreFormatError(`${path}.${unsupported} is not supported.`);
+  }
+}
+
+function requireBoundedString(
+  value: unknown,
+  path: string,
+  maxBytes: number,
+  nonEmpty = false,
+): asserts value is string {
+  if (
+    typeof value !== 'string'
+    || (nonEmpty && !value.trim())
+    || Buffer.byteLength(value, 'utf8') > maxBytes
+  ) {
+    throw new FlexHarnessStoreFormatError(
+      `${path} must be ${nonEmpty ? 'a non-empty ' : 'a '}string of at most ${maxBytes} UTF-8 bytes.`,
+    );
+  }
+}
+
+function requireTimestamp(value: unknown, path: string): asserts value is string {
+  if (typeof value !== 'string') {
+    throw new FlexHarnessStoreFormatError(`${path} must be a canonical ISO timestamp.`);
+  }
+  const timestamp = Date.parse(value);
+  if (!Number.isFinite(timestamp) || new Date(timestamp).toISOString() !== value) {
+    throw new FlexHarnessStoreFormatError(`${path} must be a canonical ISO timestamp.`);
+  }
+}
+
+function requireSessionGeneration(value: Record<string, unknown>, path: string): void {
+  requireBoundedString(
+    value.sessionGenerationId,
+    `${path}.sessionGenerationId`,
+    FLEX_SESSION_GENERATION_ID_MAX_BYTES,
+    true,
+  );
+  if (
+    !Number.isSafeInteger(value.sessionGenerationSequence)
+    || Number(value.sessionGenerationSequence) < 1
+  ) {
+    throw new FlexHarnessStoreFormatError(
+      `${path}.sessionGenerationSequence must be a positive integer.`,
+    );
+  }
+}
+
+function validateTask(value: unknown, path: string): IFlexProjectTask {
+  const task = requireRecord(value, path);
+  requireOnlyKeys(
+    task,
+    ['id', 'content', 'status', 'priority', 'createdAt', 'updatedAt'],
+    path,
+  );
+  requireBoundedString(task.id, `${path}.id`, FLEX_PROJECT_MANAGEMENT_LIMITS.maxTaskIdBytes, true);
+  requireBoundedString(
+    task.content,
+    `${path}.content`,
+    FLEX_PROJECT_MANAGEMENT_LIMITS.maxTaskContentBytes,
+    true,
+  );
+  if (!['pending', 'in_progress', 'completed', 'cancelled'].includes(String(task.status))) {
+    throw new FlexHarnessStoreFormatError(`${path}.status is invalid.`);
+  }
+  if (!['high', 'medium', 'low'].includes(String(task.priority))) {
+    throw new FlexHarnessStoreFormatError(`${path}.priority is invalid.`);
+  }
+  requireTimestamp(task.createdAt, `${path}.createdAt`);
+  requireTimestamp(task.updatedAt, `${path}.updatedAt`);
+  if (task.updatedAt < task.createdAt) {
+    throw new FlexHarnessStoreFormatError(`${path}.updatedAt cannot precede createdAt.`);
+  }
+  return task as unknown as IFlexProjectTask;
+}
+
+export function createEmptyFlexProjectManagementSnapshot(
+  sessionGenerationId: string,
+  sessionGenerationSequence: number,
+): IFlexProjectManagementSnapshot {
+  const snapshot: IFlexProjectManagementSnapshot = {
+    schemaVersion: FLEX_PROJECT_MANAGEMENT_SCHEMA_VERSION,
+    revision: 0,
+    sessionGenerationId,
+    sessionGenerationSequence,
+    scratchpad: '',
+    tasks: [],
+  };
+  assertFlexProjectManagementSnapshot(snapshot);
+  return snapshot;
+}
+
+export function assertFlexProjectManagementSnapshot(
+  value: unknown,
+): asserts value is IFlexProjectManagementSnapshot {
+  assertJsonSerializable(value, '$snapshot');
+  const snapshot = requireRecord(value, '$snapshot');
+  requireOnlyKeys(
+    snapshot,
+    [
+      'schemaVersion',
+      'revision',
+      'sessionGenerationId',
+      'sessionGenerationSequence',
+      'goal',
+      'scratchpad',
+      'tasks',
+    ],
+    '$snapshot',
+  );
+  if (snapshot.schemaVersion !== FLEX_PROJECT_MANAGEMENT_SCHEMA_VERSION) {
+    throw new FlexHarnessStoreFormatError(
+      `Project management snapshot schemaVersion must be ${FLEX_PROJECT_MANAGEMENT_SCHEMA_VERSION}.`,
+    );
+  }
+  if (!Number.isSafeInteger(snapshot.revision) || Number(snapshot.revision) < 0) {
+    throw new FlexHarnessStoreFormatError('Project management snapshot revision must be a non-negative integer.');
+  }
+  requireSessionGeneration(snapshot, '$snapshot');
+  if (snapshot.goal !== undefined) {
+    requireBoundedString(
+      snapshot.goal,
+      '$snapshot.goal',
+      FLEX_PROJECT_MANAGEMENT_LIMITS.maxGoalBytes,
+      true,
+    );
+  }
+  requireBoundedString(
+    snapshot.scratchpad,
+    '$snapshot.scratchpad',
+    FLEX_PROJECT_MANAGEMENT_LIMITS.maxScratchpadBytes,
+  );
+  if (!Array.isArray(snapshot.tasks)) {
+    throw new FlexHarnessStoreFormatError('$snapshot.tasks must be an array.');
+  }
+  if (snapshot.tasks.length > FLEX_PROJECT_MANAGEMENT_LIMITS.maxTasks) {
+    throw new FlexHarnessStoreFormatError('$snapshot.tasks exceeds its task-count limit.');
+  }
+  const taskIds = new Set<string>();
+  for (let index = 0; index < snapshot.tasks.length; index++) {
+    const task = validateTask(snapshot.tasks[index], `$snapshot.tasks[${index}]`);
+    if (taskIds.has(task.id)) {
+      throw new FlexHarnessStoreFormatError(`$snapshot.tasks contains duplicate task "${task.id}".`);
+    }
+    taskIds.add(task.id);
+  }
+  if (Buffer.byteLength(JSON.stringify(snapshot), 'utf8') > FLEX_PROJECT_MANAGEMENT_LIMITS.maxSnapshotBytes) {
+    throw new FlexHarnessStoreFormatError('Project management snapshot exceeds its serialized byte limit.');
+  }
+}
+
+export function assertFlexProjectManagementTombstone(
+  value: unknown,
+): asserts value is IFlexProjectManagementTombstone {
+  assertJsonSerializable(value, '$tombstone');
+  const tombstone = requireRecord(value, '$tombstone');
+  requireOnlyKeys(
+    tombstone,
+    [
+      'schemaVersion',
+      'revision',
+      'sessionGenerationId',
+      'sessionGenerationSequence',
+      'deletedAt',
+    ],
+    '$tombstone',
+  );
+  if (tombstone.schemaVersion !== FLEX_PROJECT_MANAGEMENT_SCHEMA_VERSION) {
+    throw new FlexHarnessStoreFormatError(
+      `Project management tombstone schemaVersion must be ${FLEX_PROJECT_MANAGEMENT_SCHEMA_VERSION}.`,
+    );
+  }
+  if (!Number.isSafeInteger(tombstone.revision) || Number(tombstone.revision) < 1) {
+    throw new FlexHarnessStoreFormatError(
+      'Project management tombstone revision must be a positive integer.',
+    );
+  }
+  requireSessionGeneration(tombstone, '$tombstone');
+  requireTimestamp(tombstone.deletedAt, '$tombstone.deletedAt');
+}
+
+export function assertFlexProjectManagementRecord(
+  value: unknown,
+): asserts value is TFlexProjectManagementRecord {
+  const record = requireRecord(value, '$record');
+  if (Object.prototype.hasOwnProperty.call(record, 'deletedAt')) {
+    assertFlexProjectManagementTombstone(value);
+  } else {
+    assertFlexProjectManagementSnapshot(value);
+  }
+}

package/ts_migration/v3_legacyflexharness.ts

@@ -405,7 +405,7 @@ function createMigrationPlan(
       tombstones: [],
     };
     const projectionSnapshot: IFlexProjectionSnapshotCurrent = {
-      schemaVersion: 2,
+      schemaVersion: 3,
       revision: 1,
       messages: stored.messages,
       stagedTerminals: [],