@modelprofile.com/flexharness 9.4.0 → 9.5.0

package/ts/errors.ts

@@ -44,6 +44,17 @@ export class FlexHarnessSessionBusyError extends FlexHarnessError {
   }
 }
 
+/** An operation would change the history or model context of an imported, read-only session. */
+export class FlexHarnessImportedSessionError extends FlexHarnessError {
+  public readonly sessionId: string;
+
+  constructor(sessionId: string) {
+    super('FLEX_SESSION_READ_ONLY', `Session "${sessionId}" is an imported conversation and is read-only.`);
+    this.name = 'FlexHarnessImportedSessionError';
+    this.sessionId = sessionId;
+  }
+}
+
 export class FlexHarnessSlashCommandUnavailableError extends FlexHarnessError {
   public readonly commandName: string;
   public readonly unavailableReason: string;

package/ts/interfaces.ts

@@ -169,8 +169,129 @@ export interface IFlexSession {
   parentToolCallId?: string;
   agent?: string;
   depth?: number;
+  /** Set only on a session the staged session import created; such a session is read-only. */
+  origin?: IFlexSessionOrigin;
 }
 
+/** The position of an imported session when one source conversation was split into several sessions. */
+export interface IFlexSessionImportPart {
+  /** Zero-based position of this session among the parts. */
+  index: number;
+  /** The number of parts the source was split into. */
+  count: number;
+}
+
+/** What an import caller states about the source of the history it imports. */
+export interface IFlexSessionImportSource {
+  /** The kind of source, for example `claude-code-transcript`. */
+  source: string;
+  /** The source's own identifier of the conversation. */
+  sourceId: string;
+  /** The caller's digest of the source content; a changed source has a changed digest. */
+  digest: string;
+  part?: IFlexSessionImportPart;
+  /** Source-specific metadata, for example the source working directory or what the conversion lost. */
+  details?: IJsonObject;
+}
+
+/** Where an imported session's history came from. */
+export interface IFlexSessionOrigin extends IFlexSessionImportSource {
+  kind: 'import';
+  /** When FlexHarness committed the import. */
+  importedAt: string;
+}
+
+/** The imported parent session, run and tool call an imported child session belongs to. */
+export interface IFlexSessionImportParent {
+  sessionId: string;
+  runId: string;
+  toolCallId: string;
+  agent: string;
+}
+
+export interface IFlexBeginSessionImportOptions {
+  /** Caller-chosen and deterministic, so a repeated import finds the earlier one. */
+  sessionId: string;
+  title?: string;
+  /** When the source conversation started, as `Date.prototype.toISOString()` renders it. */
+  createdAt: string;
+  /** When the source conversation last changed; defaults to `createdAt`. */
+  updatedAt?: string;
+  origin: IFlexSessionImportSource;
+  parent?: IFlexSessionImportParent;
+}
+
+export interface IFlexSessionImportHandle {
+  importId: string;
+  scopeId: string;
+  sessionId: string;
+}
+
+export interface IFlexSessionImportStarted {
+  status: 'started';
+  handle: IFlexSessionImportHandle;
+}
+
+/**
+ * A session with the same source, source id and part already exists. `already_imported` means its
+ * digest equals the requested one; `digest_mismatch` means the source changed since that import.
+ */
+export interface IFlexSessionImportExisting {
+  status: 'already_imported' | 'digest_mismatch';
+  session: IFlexSession;
+}
+
+export type TFlexBeginSessionImportResult = IFlexSessionImportStarted | IFlexSessionImportExisting;
+
+/** One imported run: a user message and the assistant message that answered it. */
+export interface IFlexImportedRun {
+  user: IFlexMessage;
+  assistant: IFlexMessage;
+}
+
+export interface IFlexSessionImportProgress {
+  runs: number;
+  messages: number;
+  bytes: number;
+}
+
+export interface IFlexSessionImportLimits {
+  /** Staged imports open at once in one FlexHarness. */
+  maxOpenImports?: number;
+  /** Messages in one imported session, two per run. */
+  maxMessagesPerSession?: number;
+  /** JSON bytes of all messages of one imported session. */
+  maxSessionBytes?: number;
+  /** JSON bytes of the runs one `appendImportedRuns()` call carries. */
+  maxPageBytes?: number;
+  /**
+   * Milliseconds a staged import may stay without an `appendImportedRuns()` call. An expired
+   * import is discarded as if it were aborted, which frees its slot and its staged memory.
+   */
+  stagedImportIdleTimeoutMs?: number;
+}
+
+/** JSON bytes of one imported message; a larger message could not be read back whole. */
+export const FLEX_SESSION_IMPORT_MAX_MESSAGE_BYTES = 480 * 1024;
+export const FLEX_SESSION_IMPORT_MAX_DETAILS_BYTES = 16 * 1024;
+export const FLEX_SESSION_IMPORT_MAX_DEPTH = 8;
+
+export const FLEX_SESSION_IMPORT_DEFAULT_LIMITS = Object.freeze({
+  maxOpenImports: 2,
+  maxMessagesPerSession: 2048,
+  maxSessionBytes: 64 * 1024 * 1024,
+  maxPageBytes: 1024 * 1024,
+  stagedImportIdleTimeoutMs: 5 * 60 * 1000,
+});
+
+export const FLEX_SESSION_IMPORT_MAXIMUM_LIMITS = Object.freeze({
+  maxOpenImports: 64,
+  maxMessagesPerSession: 20_000,
+  maxSessionBytes: 256 * 1024 * 1024,
+  maxPageBytes: 1536 * 1024,
+  stagedImportIdleTimeoutMs: 60 * 60 * 1000,
+});
+
 export interface IFlexCreateSessionOptions {
   sessionId?: string;
   sessionGenerationId?: string;
@@ -1134,6 +1255,7 @@ export interface IFlexHarnessOptions<TScope> {
   callbackLimits?: IFlexCallbackLimits;
   promptQueueLimits?: IFlexPromptQueueLimits;
   reversionLimits?: IFlexReversionLimits;
+  sessionImportLimits?: IFlexSessionImportLimits;
   /**
    * Bounds each turn-reversion maintenance operation. Falls back to
    * agentSessionPolicy.generationLeaseCleanupTimeoutMs, then 30 seconds.

package/ts/readme.md

@@ -235,6 +235,13 @@ const harness = new FlexHarness<IProjectScope>({
     maxExcludedRunIds: 1000,
     maxPendingReversionReleases: 1000,
   },
+  sessionImportLimits: {
+    maxOpenImports: 2,
+    maxMessagesPerSession: 2048,
+    maxSessionBytes: 64 * 1024 * 1024,
+    maxPageBytes: 1024 * 1024,
+    stagedImportIdleTimeoutMs: 5 * 60 * 1000,
+  },
   subagents: [
     {
       name: 'researcher',
@@ -805,6 +812,82 @@ Public audit history is safe to send to controllers: attachment parts contain so
 
 Sessions expose `idle`, `scheduled`, `running`, `waiting_permission`, `failed`, and `cancelled` status. Persisted non-terminal activity is repaired from canonical Agent generation outcomes after process restart; incomplete messages and parts normalize to `cancelled` unless an accepted hidden terminal stage can be promoted.
 
+## Conversation Import
+
+A finished conversation from another tool can be imported as an archived, read-only session. The import is staged in three steps, so a large conversation crosses a process boundary in bounded pages. Turning a source format into Flex messages is the importer's job; the core validates, bounds, persists and protects the result.
+
+```typescript
+const started = await harness.beginSessionImport('project:billing', {
+  sessionId: 'claude-7f3c2a',
+  title: 'Fix the billing export',
+  createdAt: '2026-09-01T09:00:00.000Z',
+  updatedAt: '2026-09-01T11:00:00.000Z',
+  origin: {
+    source: 'claude-code-transcript',
+    sourceId: '7f3c2a',
+    digest: 'sha256:9b1d…',
+    details: { cwd: '/workspace' },
+  },
+});
+
+if (started.status === 'started') {
+  try {
+    for (const page of pages) {
+      await harness.appendImportedRuns(started.handle, page);
+    }
+    const session = await harness.commitSessionImport(started.handle);
+  } finally {
+    await harness.abortSessionImport(started.handle);
+  }
+}
+```
+
+- **`beginSessionImport(scopeId, options)`** validates the options and reserves the caller-chosen `sessionId`. Choose a deterministic id, derived from the source. The result is one of three:
+  - `started`, with a handle `{ importId, scopeId, sessionId }`;
+  - `already_imported`, with the existing session;
+  - `digest_mismatch`, with the existing session.
+
+  A scope holds at most one import per `origin.source`, `origin.sourceId` and `origin.part.index`, whatever its session id. `already_imported` means that session has the same `origin.digest`, so the caller skips it. `digest_mismatch` means the source changed since; the caller deletes that session and imports again. A staged import of the same session id or source identity throws `FlexHarnessSessionBusyError`. Until the commit completes, `listSessions()` omits the session and `createSession()` refuses its id. While the import is staged, `getSession()` throws `FlexHarnessSessionBusyError`. While its commit runs, `getSession()` throws `FlexHarnessNotFoundError`, because a deletion tombstone reserves the id.
+- **`appendImportedRuns(handle, runs)`** stages one page of runs, in order. A run is `{ user, assistant }`, two messages of the exact `IFlexMessage` shape. Both belong to the imported session, share one `runId` and one terminal status (`completed`, `failed` or `cancelled`), and have no `running` reasoning or tool part. Timestamps are ISO 8601 as `Date.prototype.toISOString()` renders them. Run ids and message ids are unique within the import. A page that breaks a rule or a bound stages nothing, and the import stays open. The result reports the staged `runs`, `messages` and `bytes`.
+- **`commitSessionImport(handle)`** persists the runs and publishes the session, with one `session.created` event:
+  - `origin` is `{ kind: 'import', source, sourceId, digest, part?, details?, importedAt }`, and `archivedAt` equals `importedAt`;
+  - `createdAt` and `updatedAt` are the ones passed to `beginSessionImport()`, and the status is `idle`.
+
+  The commit first persists a deletion tombstone for the id, then writes the projection, then replaces the tombstone with the session in one scope save. A failed commit removes what it persisted through the normal tombstone cleanup. After a crash, or a save whose outcome is uncertain, the next load of the namespace resolves it: a surviving tombstone is cleaned up, and a published session is kept. A commit needs at least one run.
+- **`abortSessionImport(handle)`** discards a staged import. Nothing of it was persisted. An unknown or finished handle is ignored, so the call is safe in a `finally`. A staged import that receives no `appendImportedRuns()` call for `stagedImportIdleTimeoutMs` expires and is discarded the same way; its handle then reports `FlexHarnessNotFoundError`.
+- **Child sessions.** `parent: { sessionId, runId, toolCallId, agent }` imports a child session, such as a subagent's conversation. The parent must be a committed imported session in the same scope. Its assistant message of `runId` must hold the tool call `toolCallId` whose `childSessionId` names the child. No other session may claim that tool call. The child gets `depth` one below its parent, at most `FLEX_SESSION_IMPORT_MAX_DEPTH` (8). Deleting the parent deletes its children.
+
+**Read-only.** An imported session never runs, and nothing writes model context for it: it has no Agent events and no tool jobs. Every operation that would change its history or model context throws `FlexHarnessImportedSessionError` (code `FLEX_SESSION_READ_ONLY`):
+
+- `prompt`, `startPrompt`, `enqueuePrompt` and `schedulePrompt`;
+- `executeSlashCommand` and `compactSession`;
+- `undoSession` and `redoSession`;
+- `pushRuntimeEvent`, `reconcileToolExecution` and `archiveSessionEvents`;
+- the project-management writes: tasks, goal and scratchpad.
+
+`listSlashCommands()` reports every command unavailable with the reason `Session is an imported conversation and is read-only.` Reads work: sessions, messages, message pages, reversion info and project state. So do `updateSession()` (title and archived flag), `deleteSession()` and `deleteSessionGenerationCohort()`. A load never repairs an imported session's runs from Agent generation outcomes, because it has none.
+
+**Bounds.** `sessionImportLimits` sets the bounds; each must be an integer from 1 through its maximum:
+
+| Limit | Default | Maximum |
+|---|---|---|
+| `maxOpenImports` (staged imports at once, per harness) | 2 | 64 |
+| `maxMessagesPerSession` | 2048 | 20000 |
+| `maxSessionBytes` (JSON bytes of all messages) | 64 MiB | 256 MiB |
+| `maxPageBytes` (JSON bytes of one `appendImportedRuns()` page) | 1 MiB | 1.5 MiB |
+| `stagedImportIdleTimeoutMs` (idle time before a staged import expires) | 5 minutes | 1 hour |
+
+Some bounds are fixed:
+
+- one message is at most `FLEX_SESSION_IMPORT_MAX_MESSAGE_BYTES` (480 KiB), and must read back through the message transfer limits;
+- `origin.details` is a JSON object of at most `FLEX_SESSION_IMPORT_MAX_DETAILS_BYTES` (16 KiB);
+- `origin.source` is at most 128 UTF-8 bytes, `origin.sourceId` 512 and `origin.digest` 256, none with control characters;
+- `origin.part` has a `count` from 1 through 1024 and a zero-based `index` below it.
+
+Staged runs are held in memory until the commit, so the memory of open imports is bounded by `maxOpenImports` × `maxSessionBytes`. Retiring the scope, disposing the harness or the idle expiry discards staged imports. The expiry timer does not keep the process alive.
+
+**Stores.** The import adds no store method. Scope snapshots carry the optional session `origin`, and a store that validates session keys exactly must accept it. The commit writes the whole projection in one save at revision 1. FlexHarness versions before 9.5.0 reject the new key under their strict reader, so a downgrade over imported sessions is unsupported.
+
 ## Permissions
 
 Tools request permission through the run-scoped provider context:

package/ts/utils.json.ts

@@ -494,10 +494,12 @@ function validateSession(value: unknown, path: string): IValidatedSessionIdentit
       'parentToolCallId',
       'agent',
       'depth',
+      'origin',
     ],
     path,
   );
   requireString(session.scopeId, `${path}.scopeId`);
+  if (session.origin !== undefined) validateSessionOrigin(session.origin, `${path}.origin`);
   const sessionId = requireString(session.sessionId, `${path}.sessionId`);
   const generation = validateOptionalSessionGeneration(session, path);
   requireOptionalString(session.title, `${path}.title`);
@@ -555,6 +557,41 @@ function validateSession(value: unknown, path: string): IValidatedSessionIdentit
   };
 }
 
+function validateSessionOrigin(value: unknown, path: string): void {
+  const origin = requireRecord(value, path);
+  requireOnlyKeys(
+    origin,
+    ['kind', 'source', 'sourceId', 'digest', 'importedAt', 'part', 'details'],
+    path,
+  );
+  if (origin.kind !== 'import') {
+    throw new FlexHarnessStoreFormatError(`${path}.kind is invalid.`);
+  }
+  requireString(origin.source, `${path}.source`);
+  requireString(origin.sourceId, `${path}.sourceId`);
+  requireString(origin.digest, `${path}.digest`);
+  requireString(origin.importedAt, `${path}.importedAt`);
+  if (origin.part !== undefined) {
+    const part = requireRecord(origin.part, `${path}.part`);
+    requireOnlyKeys(part, ['index', 'count'], `${path}.part`);
+    requireNonNegativeInteger(part.index, `${path}.part.index`);
+    requireNonNegativeInteger(part.count, `${path}.part.count`);
+    if (Number(part.index) >= Number(part.count)) {
+      throw new FlexHarnessStoreFormatError(`${path}.part.index must be below part.count.`);
+    }
+  }
+  if (origin.details !== undefined) requireRecord(origin.details, `${path}.details`);
+}
+
+/**
+ * Asserts the exact stored shape of one public message: its keys, part kinds and field types.
+ * Throws `FlexHarnessStoreFormatError`.
+ */
+export function assertFlexMessageRecord(value: unknown, path: string): void {
+  assertJsonSerializable(value, path);
+  validateMessage(value, path);
+}
+
 function validateSubagentProvenance(
   value: unknown,
   path: string,

package/ts/utils.sessionimport.ts

@@ -0,0 +1,327 @@
+import { FlexHarnessValidationError } from './errors.js';
+import {
+  FLEX_PROJECT_MANAGEMENT_LIMITS,
+  FLEX_SESSION_IMPORT_DEFAULT_LIMITS,
+  FLEX_SESSION_IMPORT_MAXIMUM_LIMITS,
+  FLEX_SESSION_IMPORT_MAX_DETAILS_BYTES,
+  FLEX_SESSION_IMPORT_MAX_MESSAGE_BYTES,
+} from './interfaces.js';
+import type {
+  IFlexBeginSessionImportOptions,
+  IFlexImportedRun,
+  IFlexMessage,
+  IFlexSessionImportHandle,
+  IFlexSessionImportLimits,
+  IFlexSessionImportParent,
+  IFlexSessionImportPart,
+  IFlexSessionImportSource,
+  IJsonObject,
+} from './interfaces.js';
+import { maxSubagentNameBytes } from './utils.harnessoptions.js';
+import { assertFlexMessageRecord, assertJsonSerializable, cloneSerializable } from './utils.json.js';
+import {
+  createBoundedTransferMessage,
+  jsonBytes,
+  maxTransferIdentifierBytes,
+  requireTransferIdentifier,
+} from './utils.transfer.js';
+import { validateIdentifier, validateUtf8String } from './utils.validation.js';
+
+const maxSourceBytes = 128;
+const maxDigestBytes = 256;
+const maxImportParts = 1024;
+const controlCharacterPattern = /[\u0000-\u001f\u007f]/u;
+
+export interface INormalizedSessionImportOptions {
+  sessionId: string;
+  title?: string;
+  createdAt: string;
+  updatedAt: string;
+  origin: IFlexSessionImportSource;
+  parent?: IFlexSessionImportParent;
+}
+
+export interface INormalizedImportedRunPage {
+  runs: IFlexImportedRun[];
+  bytes: number;
+}
+
+export function resolveSessionImportLimits(
+  limits: IFlexSessionImportLimits = {},
+): Required<IFlexSessionImportLimits> {
+  const resolved = {
+    maxOpenImports: limits.maxOpenImports ?? FLEX_SESSION_IMPORT_DEFAULT_LIMITS.maxOpenImports,
+    maxMessagesPerSession: limits.maxMessagesPerSession
+      ?? FLEX_SESSION_IMPORT_DEFAULT_LIMITS.maxMessagesPerSession,
+    maxSessionBytes: limits.maxSessionBytes ?? FLEX_SESSION_IMPORT_DEFAULT_LIMITS.maxSessionBytes,
+    maxPageBytes: limits.maxPageBytes ?? FLEX_SESSION_IMPORT_DEFAULT_LIMITS.maxPageBytes,
+    stagedImportIdleTimeoutMs: limits.stagedImportIdleTimeoutMs
+      ?? FLEX_SESSION_IMPORT_DEFAULT_LIMITS.stagedImportIdleTimeoutMs,
+  };
+  for (const [name, value] of Object.entries(resolved)) {
+    const maximum = FLEX_SESSION_IMPORT_MAXIMUM_LIMITS[name as keyof IFlexSessionImportLimits];
+    if (!Number.isSafeInteger(value) || value < 1 || value > maximum) {
+      throw new FlexHarnessValidationError(
+        `sessionImportLimits.${name} must be an integer from 1 through ${maximum}.`,
+      );
+    }
+  }
+  return resolved;
+}
+
+function requirePlainRecord(value: unknown, name: string): Record<string, unknown> {
+  if (
+    !value
+    || typeof value !== 'object'
+    || Array.isArray(value)
+    || ![Object.prototype, null].includes(Object.getPrototypeOf(value))
+  ) {
+    throw new FlexHarnessValidationError(`${name} must be a plain object.`);
+  }
+  return value as Record<string, unknown>;
+}
+
+function requireKnownKeys(
+  record: Record<string, unknown>,
+  allowedKeys: readonly string[],
+  name: string,
+): void {
+  const unsupported = Reflect.ownKeys(record).find((key) =>
+    typeof key !== 'string' || !allowedKeys.includes(key));
+  if (unsupported !== undefined) {
+    throw new FlexHarnessValidationError(`${name} does not support "${String(unsupported)}".`);
+  }
+}
+
+function requireBoundedText(value: unknown, name: string, maxBytes: number): string {
+  validateUtf8String(value, name, maxBytes, true);
+  if (controlCharacterPattern.test(value)) {
+    throw new FlexHarnessValidationError(`${name} must not contain control characters.`);
+  }
+  return value;
+}
+
+/** A timestamp exactly as `Date.prototype.toISOString()` renders it. */
+export function requireCanonicalTimestamp(value: unknown, name: string): string {
+  if (typeof value !== 'string' || value.length > 64) {
+    throw new FlexHarnessValidationError(`${name} must be an ISO 8601 timestamp.`);
+  }
+  const time = Date.parse(value);
+  if (!Number.isFinite(time) || new Date(time).toISOString() !== value) {
+    throw new FlexHarnessValidationError(
+      `${name} must be an ISO 8601 timestamp as Date.prototype.toISOString() renders it.`,
+    );
+  }
+  return value;
+}
+
+function normalizeImportPart(value: unknown): IFlexSessionImportPart {
+  const part = requirePlainRecord(value, 'origin.part');
+  requireKnownKeys(part, ['index', 'count'], 'origin.part');
+  const { index, count } = part;
+  if (
+    !Number.isSafeInteger(count)
+    || Number(count) < 1
+    || Number(count) > maxImportParts
+    || !Number.isSafeInteger(index)
+    || Number(index) < 0
+    || Number(index) >= Number(count)
+  ) {
+    throw new FlexHarnessValidationError(
+      `origin.part must have a count from 1 through ${maxImportParts} and a zero-based index below it.`,
+    );
+  }
+  return { index: index as number, count: count as number };
+}
+
+function normalizeImportDetails(value: unknown): IJsonObject {
+  requirePlainRecord(value, 'origin.details');
+  try {
+    assertJsonSerializable(value, 'origin.details');
+  } catch (error) {
+    throw new FlexHarnessValidationError('origin.details must be a JSON object.', { cause: error });
+  }
+  if (jsonBytes(value) > FLEX_SESSION_IMPORT_MAX_DETAILS_BYTES) {
+    throw new FlexHarnessValidationError(
+      `origin.details must be at most ${FLEX_SESSION_IMPORT_MAX_DETAILS_BYTES} JSON bytes.`,
+    );
+  }
+  return cloneSerializable(value as IJsonObject);
+}
+
+function normalizeImportSource(value: unknown): IFlexSessionImportSource {
+  const origin = requirePlainRecord(value, 'origin');
+  requireKnownKeys(origin, ['source', 'sourceId', 'digest', 'part', 'details'], 'origin');
+  return {
+    source: requireBoundedText(origin.source, 'origin.source', maxSourceBytes),
+    sourceId: requireBoundedText(origin.sourceId, 'origin.sourceId', maxTransferIdentifierBytes),
+    digest: requireBoundedText(origin.digest, 'origin.digest', maxDigestBytes),
+    ...(origin.part === undefined ? {} : { part: normalizeImportPart(origin.part) }),
+    ...(origin.details === undefined ? {} : { details: normalizeImportDetails(origin.details) }),
+  };
+}
+
+function normalizeImportParent(value: unknown): IFlexSessionImportParent {
+  const parent = requirePlainRecord(value, 'parent');
+  requireKnownKeys(parent, ['sessionId', 'runId', 'toolCallId', 'agent'], 'parent');
+  return {
+    sessionId: requireBoundedText(parent.sessionId, 'parent.sessionId', maxTransferIdentifierBytes),
+    runId: requireBoundedText(parent.runId, 'parent.runId', maxTransferIdentifierBytes),
+    toolCallId: requireBoundedText(parent.toolCallId, 'parent.toolCallId', maxTransferIdentifierBytes),
+    agent: requireBoundedText(parent.agent, 'parent.agent', maxSubagentNameBytes),
+  };
+}
+
+export function normalizeBeginSessionImportOptions(
+  options: IFlexBeginSessionImportOptions,
+): INormalizedSessionImportOptions {
+  const record = requirePlainRecord(options, 'beginSessionImport options');
+  requireKnownKeys(
+    record,
+    ['sessionId', 'title', 'createdAt', 'updatedAt', 'origin', 'parent'],
+    'beginSessionImport options',
+  );
+  const sessionId = record.sessionId as string;
+  validateIdentifier(sessionId, 'sessionId');
+  requireTransferIdentifier(sessionId, 'sessionId');
+  if (record.title !== undefined) {
+    validateUtf8String(record.title, 'title', FLEX_PROJECT_MANAGEMENT_LIMITS.maxTitleBytes, true);
+  }
+  const createdAt = requireCanonicalTimestamp(record.createdAt, 'createdAt');
+  const updatedAt = record.updatedAt === undefined
+    ? createdAt
+    : requireCanonicalTimestamp(record.updatedAt, 'updatedAt');
+  if (Date.parse(updatedAt) < Date.parse(createdAt)) {
+    throw new FlexHarnessValidationError('updatedAt must not be earlier than createdAt.');
+  }
+  const parent = record.parent === undefined ? undefined : normalizeImportParent(record.parent);
+  if (parent?.sessionId === sessionId) {
+    throw new FlexHarnessValidationError('An imported session cannot be its own parent.');
+  }
+  return {
+    sessionId,
+    ...(record.title === undefined ? {} : { title: record.title as string }),
+    createdAt,
+    updatedAt,
+    origin: normalizeImportSource(record.origin),
+    ...(parent === undefined ? {} : { parent }),
+  };
+}
+
+/** The identity an import is idempotent by: its source, source id and part. */
+export function sessionImportIdentity(
+  origin: Pick<IFlexSessionImportSource, 'source' | 'sourceId' | 'part'>,
+): string {
+  return JSON.stringify([origin.source, origin.sourceId, origin.part?.index ?? null]);
+}
+
+function normalizeImportedMessage(
+  value: unknown,
+  path: string,
+  role: IFlexMessage['role'],
+  sessionId: string,
+): { message: IFlexMessage; bytes: number } {
+  try {
+    assertFlexMessageRecord(value, path);
+  } catch (error) {
+    throw new FlexHarnessValidationError(
+      `${path} is not a valid message: ${error instanceof Error ? error.message : String(error)}`,
+      { cause: error },
+    );
+  }
+  const message = cloneSerializable(value as IFlexMessage);
+  if (message.role !== role) {
+    throw new FlexHarnessValidationError(`${path}.role must be "${role}".`);
+  }
+  if (message.sessionId !== sessionId) {
+    throw new FlexHarnessValidationError(`${path}.sessionId must be the imported session "${sessionId}".`);
+  }
+  if (message.status === 'streaming') {
+    throw new FlexHarnessValidationError(`${path}.status must be completed, failed or cancelled.`);
+  }
+  requireCanonicalTimestamp(message.createdAt, `${path}.createdAt`);
+  if (message.completedAt !== undefined) {
+    requireCanonicalTimestamp(message.completedAt, `${path}.completedAt`);
+  }
+  for (const [index, part] of message.parts.entries()) {
+    if (part.type !== 'reasoning' && part.type !== 'tool') continue;
+    if (part.status === 'running') {
+      throw new FlexHarnessValidationError(`${path}.parts[${index}] must not be running.`);
+    }
+  }
+  const bytes = jsonBytes(message);
+  if (bytes > FLEX_SESSION_IMPORT_MAX_MESSAGE_BYTES) {
+    throw new FlexHarnessValidationError(
+      `${path} exceeds ${FLEX_SESSION_IMPORT_MAX_MESSAGE_BYTES} JSON bytes.`,
+    );
+  }
+  try {
+    createBoundedTransferMessage(message);
+  } catch (error) {
+    throw new FlexHarnessValidationError(`${path} cannot be read back within the transfer limits.`, {
+      cause: error,
+    });
+  }
+  return { message, bytes };
+}
+
+/**
+ * Validates one page of imported runs. Every message must belong to `sessionId`, be terminal and
+ * fit the transfer limits; a run's user and assistant message share its run id and status.
+ */
+export function normalizeImportedRunPage(
+  runs: readonly IFlexImportedRun[],
+  sessionId: string,
+  maxPageBytes: number,
+): INormalizedImportedRunPage {
+  if (!Array.isArray(runs) || runs.length === 0) {
+    throw new FlexHarnessValidationError('Imported runs must be a non-empty array.');
+  }
+  let pageBytes: number;
+  try {
+    assertJsonSerializable(runs, 'runs');
+    pageBytes = jsonBytes(runs);
+  } catch (error) {
+    throw new FlexHarnessValidationError('Imported runs must be JSON-safe.', { cause: error });
+  }
+  if (pageBytes > maxPageBytes) {
+    throw new FlexHarnessValidationError(`Imported runs exceed the page limit of ${maxPageBytes} JSON bytes.`);
+  }
+  const normalized: IFlexImportedRun[] = [];
+  let bytes = 0;
+  for (const [index, value] of runs.entries()) {
+    const path = `runs[${index}]`;
+    const run = requirePlainRecord(value, path);
+    requireKnownKeys(run, ['user', 'assistant'], path);
+    const user = normalizeImportedMessage(run.user, `${path}.user`, 'user', sessionId);
+    const assistant = normalizeImportedMessage(run.assistant, `${path}.assistant`, 'assistant', sessionId);
+    if (user.message.runId !== assistant.message.runId) {
+      throw new FlexHarnessValidationError(`${path} user and assistant messages must share one runId.`);
+    }
+    if (user.message.messageId === assistant.message.messageId) {
+      throw new FlexHarnessValidationError(`${path} user and assistant messages must have distinct ids.`);
+    }
+    if (user.message.status !== assistant.message.status) {
+      throw new FlexHarnessValidationError(`${path} user and assistant messages must share one status.`);
+    }
+    normalized.push({ user: user.message, assistant: assistant.message });
+    bytes += user.bytes + assistant.bytes;
+  }
+  return { runs: normalized, bytes };
+}
+
+/** Validates the shape of a handle `beginSessionImport()` returned. */
+export function validateSessionImportHandle(handle: IFlexSessionImportHandle): IFlexSessionImportHandle {
+  const record = requirePlainRecord(handle, 'Session import handle');
+  requireKnownKeys(record, ['importId', 'scopeId', 'sessionId'], 'Session import handle');
+  for (const key of ['importId', 'scopeId', 'sessionId'] as const) {
+    if (typeof record[key] !== 'string' || record[key] === '') {
+      throw new FlexHarnessValidationError(`Session import handle ${key} must be a non-empty string.`);
+    }
+  }
+  return {
+    importId: record.importId as string,
+    scopeId: record.scopeId as string,
+    sessionId: record.sessionId as string,
+  };
+}