@modelprofile.com/flexharness 11.3.1 → 12.0.0

package/ts/classes.stores.ts

@@ -14,7 +14,7 @@ import type {
   IFlexProjectManagementStore,
   IFlexProjectManagementTombstone,
   IFlexProjectManagementWriteContext,
-  IFlexProjectionSnapshotV3,
+  IFlexProjectionChange,
   IFlexProjectionStore,
   IFlexResultStore,
   IFlexScopeSnapshot,
@@ -36,10 +36,15 @@ import {
   assertFlexProjectManagementSnapshot,
   assertFlexProjectManagementTombstone,
 } from './utils.projectmanagement.js';
+import {
+  createChangedProjectionSnapshot,
+  validateProjectionChangeSave,
+} from './utils.projectionchange.js';
 import {
   assertFlexToolJobSnapshot,
-  createAgentEventSnapshot,
+  createChangedAgentEventSnapshot,
   createToolJobSnapshot,
+  normalizeAgentEventChange,
   normalizeJsonObjectUndefined,
   validateAgentEventArchive,
   validateAgentEventSnapshot,
@@ -95,20 +100,17 @@ class InMemoryProjectionStore implements IFlexProjectionStore {
   public async save(
     storageKey: string,
     sessionId: string,
-    snapshot: IFlexProjectionSnapshotV3,
+    change: IFlexProjectionChange,
     expectedRevision: number,
   ): Promise<void> {
     const key = providerKey(storageKey, sessionId);
-    const validated = validateSnapshotSave(
-      snapshot,
-      expectedRevision,
-      (value) => assertFlexProjectionSnapshot(value, sessionId),
-    );
-    const actualRevision = this.snapshots.get(key)?.revision ?? 0;
+    const validated = validateProjectionChangeSave(change, expectedRevision);
+    const current = this.snapshots.get(key);
+    const actualRevision = current?.revision ?? 0;
     if (actualRevision !== expectedRevision) {
       throw new FlexHarnessStoreConflictError(key, expectedRevision, actualRevision);
     }
-    this.snapshots.set(key, validated);
+    this.snapshots.set(key, createChangedProjectionSnapshot(current, validated, sessionId));
   }
 
   public async deleteSession(storageKey: string, sessionId: string): Promise<void> {
@@ -203,10 +205,9 @@ export class InMemoryFlexProjectManagementStore implements IFlexProjectManagemen
   }
 }
 
-class InMemoryAgentEventStore implements plugins.IAgentEventStoreV2 {
-  public readonly eventSchemaVersion = 2 as const;
-  private snapshot: plugins.IAgentEventSnapshotV2 | undefined;
-  private readonly archives = new Map<string, plugins.IAgentEventArchiveV2>();
+class InMemoryAgentEventStore implements plugins.IAgentEventStore {
+  private snapshot: plugins.IAgentEventSnapshot | undefined;
+  private readonly archives = new Map<string, plugins.IAgentEventArchive>();
 
   constructor(private readonly sessionId: string) {}
 
@@ -218,29 +219,32 @@ class InMemoryAgentEventStore implements plugins.IAgentEventStoreV2 {
     }
   }
 
-  public async load(sessionId: string): Promise<plugins.IAgentEventSnapshotV2 | undefined> {
+  public async load(sessionId: string): Promise<plugins.IAgentEventSnapshot | undefined> {
     this.assertSession(sessionId);
     return this.snapshot ? cloneSerializable(this.snapshot) : undefined;
   }
 
   public async save(
     sessionId: string,
-    events: readonly plugins.TAgentEvent[],
+    change: plugins.IAgentEventChange,
     expectedRevision: number,
   ): Promise<number> {
     this.assertSession(sessionId);
     validateExpectedRevision(expectedRevision);
-    const snapshot = createAgentEventSnapshot(sessionId, events, expectedRevision + 1);
-    validateAgentEventSnapshot(snapshot, sessionId);
+    const normalized = normalizeAgentEventChange(change);
     const actualRevision = this.snapshot?.revision ?? 0;
     if (actualRevision !== expectedRevision) {
       throw new plugins.AgentEventStoreConflictError(sessionId, expectedRevision, actualRevision);
     }
-    this.snapshot = cloneSerializable(snapshot);
+    const snapshot = validateAgentEventSnapshot(
+      createChangedAgentEventSnapshot(sessionId, this.snapshot, normalized),
+      sessionId,
+    );
+    this.snapshot = snapshot;
     return snapshot.revision;
   }
 
-  public async archive(archive: plugins.IAgentEventArchiveV2): Promise<void> {
+  public async archive(archive: plugins.IAgentEventArchive): Promise<void> {
     this.assertSession(archive.sessionId);
     const normalized = normalizeJsonObjectUndefined(archive, '$archive');
     const validated = validateAgentEventArchive(normalized, this.sessionId, archive.archiveId);
@@ -255,7 +259,7 @@ class InMemoryAgentEventStore implements plugins.IAgentEventStoreV2 {
   public async loadArchive(
     sessionId: string,
     archiveId: string,
-  ): Promise<plugins.IAgentEventArchiveV2 | undefined> {
+  ): Promise<plugins.IAgentEventArchive | undefined> {
     this.assertSession(sessionId);
     validateIdentifier(archiveId, 'archiveId');
     const archive = this.archives.get(archiveId);
@@ -829,17 +833,14 @@ class JsonProjectionStore implements IFlexProjectionStore {
     });
   }
 
+  /** Applies the change and writes the whole projection again. */
   public async save(
     storageKey: string,
     sessionId: string,
-    snapshot: IFlexProjectionSnapshotV3,
+    change: IFlexProjectionChange,
     expectedRevision: number,
   ): Promise<void> {
-    const validated = validateSnapshotSave(
-      snapshot,
-      expectedRevision,
-      (value) => assertFlexProjectionSnapshot(value, sessionId),
-    );
+    const validated = validateProjectionChangeSave(change, expectedRevision);
     const filePath = this.root.sessionPath('projections', storageKey, sessionId);
     await JsonFileRoot.inQueue(filePath, async () => {
       const current = await this.root.read(filePath, (value) => {
@@ -850,7 +851,7 @@ class JsonProjectionStore implements IFlexProjectionStore {
       if (actualRevision !== expectedRevision) {
         throw new FlexHarnessStoreConflictError(providerKey(storageKey, sessionId), expectedRevision, actualRevision);
       }
-      await this.root.write(filePath, validated);
+      await this.root.write(filePath, createChangedProjectionSnapshot(current, validated, sessionId));
     });
   }
 
@@ -1066,9 +1067,8 @@ async function clearJsonAgentEventSession(
   });
 }
 
-class JsonAgentEventStore implements plugins.IAgentEventStoreV2 {
-  public readonly eventSchemaVersion = 2 as const;
-
+/** Stores a session's event log in one file; a save rewrites the whole log. */
+class JsonAgentEventStore implements plugins.IAgentEventStore {
   constructor(
     private readonly root: JsonFileRoot,
     private readonly storageKey: string,
@@ -1083,7 +1083,7 @@ class JsonAgentEventStore implements plugins.IAgentEventStoreV2 {
     }
   }
 
-  public async load(sessionId: string): Promise<plugins.IAgentEventSnapshotV2 | undefined> {
+  public async load(sessionId: string): Promise<plugins.IAgentEventSnapshot | undefined> {
     this.assertSession(sessionId);
     const filePath = this.root.sessionPath('events', this.storageKey, this.sessionId);
     return JsonFileRoot.inQueue(this.root.eventQueueKey(this.storageKey, this.sessionId), async () => {
@@ -1097,13 +1097,12 @@ class JsonAgentEventStore implements plugins.IAgentEventStoreV2 {
 
   public async save(
     sessionId: string,
-    events: readonly plugins.TAgentEvent[],
+    change: plugins.IAgentEventChange,
     expectedRevision: number,
   ): Promise<number> {
     this.assertSession(sessionId);
     validateExpectedRevision(expectedRevision);
-    const snapshot = createAgentEventSnapshot(sessionId, events, expectedRevision + 1);
-    validateAgentEventSnapshot(snapshot, sessionId);
+    const normalized = normalizeAgentEventChange(change);
     const filePath = this.root.sessionPath('events', this.storageKey, this.sessionId);
     return JsonFileRoot.inQueue(this.root.eventQueueKey(this.storageKey, this.sessionId), async () => {
       const current = await this.root.read(
@@ -1114,12 +1113,16 @@ class JsonAgentEventStore implements plugins.IAgentEventStoreV2 {
       if (actualRevision !== expectedRevision) {
         throw new plugins.AgentEventStoreConflictError(sessionId, expectedRevision, actualRevision);
       }
+      const snapshot = validateAgentEventSnapshot(
+        createChangedAgentEventSnapshot(sessionId, current, normalized),
+        sessionId,
+      );
       await this.root.write(filePath, snapshot);
       return snapshot.revision;
     });
   }
 
-  public async archive(archive: plugins.IAgentEventArchiveV2): Promise<void> {
+  public async archive(archive: plugins.IAgentEventArchive): Promise<void> {
     this.assertSession(archive.sessionId);
     const normalized = normalizeJsonObjectUndefined(archive, '$archive');
     const validated = validateAgentEventArchive(normalized, this.sessionId, archive.archiveId);
@@ -1144,7 +1147,7 @@ class JsonAgentEventStore implements plugins.IAgentEventStoreV2 {
   public async loadArchive(
     sessionId: string,
     archiveId: string,
-  ): Promise<plugins.IAgentEventArchiveV2 | undefined> {
+  ): Promise<plugins.IAgentEventArchive | undefined> {
     this.assertSession(sessionId);
     const filePath = this.root.archivePath(this.storageKey, this.sessionId, archiveId);
     return JsonFileRoot.inQueue(this.root.eventQueueKey(this.storageKey, this.sessionId), async () => {

package/ts/index.ts

@@ -21,6 +21,11 @@ export {
   assertFlexProjectManagementTombstone,
   createEmptyFlexProjectManagementSnapshot,
 } from './utils.projectmanagement.js';
+export {
+  applyFlexProjectionChange,
+  assertFlexProjectionChange,
+  createWholeProjectionChange,
+} from './utils.projectionchange.js';
 export { assertFlexToolJobSnapshot } from './utils.storecodecs.js';
 export {
   FLEX_SLASH_COMMAND_MAX_INPUT_BYTES,

package/ts/interfaces.flexharness.ts

@@ -2,6 +2,7 @@ import type * as plugins from './plugins.js';
 import type { FlexHarnessAbortError } from './errors.js';
 import type { FlexToolCatalog } from './classes.toolcatalog.js';
 import type { FlexCodeSandbox } from './classes.codesandbox.js';
+import type { IFlexProjectionLists } from './utils.projectionchange.js';
 import type {
   IFlexAgentContextInvocation,
   IFlexAffectedWorkspace,
@@ -69,6 +70,12 @@ export interface IStoredSessionState {
   pendingReversionReleases: IFlexPendingReversionRelease[];
   projectionSchemaVersion: 1 | 2 | 3;
   projectionBaseline?: TFlexProjectionSnapshot;
+  /**
+   * The lists as the store holds them, so a save sends only the entries that differ. Entries are
+   * frozen from their first save on and replaced rather than edited. Absent while the stored lists
+   * are unknown or of an older schema; the next save then sends whole lists.
+   */
+  savedProjectionLists?: IFlexProjectionLists;
   projectionReconciliationRequired: boolean;
   projectionRevision: number;
   projectionQueue: Promise<void>;
@@ -79,7 +86,7 @@ export interface IStoredSessionState {
   rememberedPermissionKeys: Set<string>;
   permissionRevision: number;
   permissionQueue: Promise<void>;
-  eventStore: plugins.IAgentEventStoreV2;
+  eventStore: plugins.IAgentEventStore;
   agentSession: plugins.IAgentSession;
   agentSessionAbortCompleted: boolean;
   agentSessionCloseCompleted: boolean;

package/ts/interfaces.ts

@@ -1231,6 +1231,27 @@ export interface IFlexProjectionSnapshotV3 {
   pendingReversionReleases: IFlexPendingReversionRelease[];
 }
 
+/**
+ * How a stored list changed: the new list is the stored entries from `start` up to `end`,
+ * followed by `items`. `{ start: 0, end: 0 }` carries the whole list.
+ */
+export interface IFlexListChange<TItem> {
+  start: number;
+  end: number;
+  items: TItem[];
+}
+
+/**
+ * How a session's projection changed since the store's last save: the current projection with
+ * its two growing lists as list changes. A change applies only to the current schema; to any
+ * other stored projection only whole lists apply.
+ */
+export interface IFlexProjectionChange
+  extends Omit<IFlexProjectionSnapshotV3, 'messages' | 'reversionSegments'> {
+  messages: IFlexListChange<IFlexMessage>;
+  reversionSegments: IFlexListChange<IFlexReversionSegment>;
+}
+
 export type IFlexProjectionSnapshot =
   | IFlexProjectionSnapshotV1
   | IFlexProjectionSnapshotV2
@@ -1436,10 +1457,14 @@ export interface IFlexScopeStore {
 
 export interface IFlexProjectionStore {
   load(storageKey: string, sessionId: string): Promise<TFlexProjectionSnapshot | undefined>;
+  /**
+   * Applies `change` to the stored projection while its revision is `expectedRevision`; the
+   * change's revision is the next one.
+   */
   save(
     storageKey: string,
     sessionId: string,
-    snapshot: IFlexProjectionSnapshotCurrent,
+    change: IFlexProjectionChange,
     expectedRevision: number,
   ): Promise<void>;
   deleteSession(storageKey: string, sessionId: string): Promise<void>;
@@ -1460,7 +1485,7 @@ export interface IFlexAgentEventStoreProvider {
   getStore(
     storageKey: string,
     sessionId: string,
-  ): Promise<plugins.IAgentEventStoreV2> | plugins.IAgentEventStoreV2;
+  ): Promise<plugins.IAgentEventStore> | plugins.IAgentEventStore;
   releaseSession?(storageKey: string, sessionId: string): Promise<void> | void;
   deleteSession(storageKey: string, sessionId: string): Promise<void>;
 }

package/ts/plugins.ts

@@ -94,6 +94,8 @@ export const importCodeSandboxEngine = async (): Promise<ICodeSandboxEngine> =>
 import {
   AgentEventStoreConflictError,
   AgentPendingInputQueue,
+  applyAgentEventChange,
+  assertAgentEventChange,
   AgentPendingInputRejectedError,
   AgentSession,
   AgentToolCallScheduler,
@@ -105,14 +107,16 @@ import {
   isGenerationInModelContext,
   modelMessagesToAgentEvents,
   tool,
-  validateAgentEventArchiveV2,
-  validateAgentEventSnapshotV2,
+  validateAgentEventArchive,
+  validateAgentEventSnapshot,
   z,
 } from '@modelprofile.com/flexharness-agent';
 
 export {
   AgentEventStoreConflictError,
   AgentPendingInputQueue,
+  applyAgentEventChange,
+  assertAgentEventChange,
   AgentPendingInputRejectedError,
   AgentSession,
   AgentToolCallScheduler,
@@ -124,17 +128,18 @@ export {
   isGenerationInModelContext,
   modelMessagesToAgentEvents,
   tool,
-  validateAgentEventArchiveV2,
-  validateAgentEventSnapshotV2,
+  validateAgentEventArchive,
+  validateAgentEventSnapshot,
   z,
 };
 export type {
   IAgentAppliedInput,
   ISmartAiCacheDispatch,
-  IAgentEventArchiveV2,
+  IAgentEventArchive,
+  IAgentEventChange,
   IAgentContextCompactionOptions,
-  IAgentEventSnapshotV2,
-  IAgentEventStoreV2,
+  IAgentEventSnapshot,
+  IAgentEventStore,
   IAgentGenerateResult,
   IAgentGenerationHandle,
   IAgentGenerationLease,

package/ts/readme.md

@@ -68,6 +68,7 @@ or provider SDKs.
 | `/mcp` | MCP clients, AI SDK tool conversion and `createMcpToolCatalog`, the tool catalog of MCP tools | `@modelcontextprotocol/sdk` |
 | `/migration` | Existing versioned harness migrations | None |
 | `/stores/nosqldb` | `NoSqlFlexHarnessStores`: cross-process CAS stores on `@lossless.org/client/nosqldb` | `@lossless.org/client` |
+| `/stores/testing` | `createFlexStoreContractTests`: the contract every built-in `IFlexHarnessStores` passes, to run against a custom store with any test runner | None |
 
 The integrations in the last column use optional peer dependencies. Install them
 only for the entrypoints your project imports, for example:
@@ -1128,7 +1129,9 @@ Current FlexHarness persistence is separated by trust and lifecycle domain throu
 
 `InMemoryFlexHarnessStores` implements all six required domains with revision-based compare-and-swap behavior for tests and ephemeral processes. It is the default when `stores` is omitted. Custom `IFlexHarnessStores` implementations must provide `projectManagement` even when project-management tools are disabled, because deletion cleanup always writes the generation fence.
 
-A custom store validates what it loads and saves with the validators the built-in stores apply. Each throws `FlexHarnessStoreFormatError` for a malformed or wrong-schema snapshot: `assertFlexScopeSnapshot()`, `assertFlexProjectionSnapshot(value, sessionId)`, which also requires every message and staged terminal to belong to `sessionId`, `assertFlexPermissionSnapshot()`, `assertFlexProjectManagementRecord()` and `assertFlexToolJobSnapshot()`. Agent event snapshots and archives have `validateAgentEventSnapshotV2()` and `validateAgentEventArchiveV2()` in `@modelprofile.com/flexharness-agent`.
+A custom store validates what it loads and saves with the validators the built-in stores apply. Each throws `FlexHarnessStoreFormatError` for a malformed or wrong-schema snapshot: `assertFlexScopeSnapshot()`, `assertFlexProjectionSnapshot(value, sessionId)`, which also requires every message and staged terminal to belong to `sessionId`, `assertFlexPermissionSnapshot()`, `assertFlexProjectManagementRecord()` and `assertFlexToolJobSnapshot()`. Agent event snapshots and archives have `validateAgentEventSnapshot()` and `validateAgentEventArchive()` in `@modelprofile.com/flexharness-agent`.
+
+Projections and Agent event histories are saved as changes, so a save costs what changed rather than the whole session. `IFlexProjectionStore.save(storageKey, sessionId, change, expectedRevision)` receives an `IFlexProjectionChange`: the schema-3 projection with `messages` and `reversionSegments` given as `IFlexListChange`s `{ start, end, items }`, each of which keeps the stored entries from `start` up to `end` and appends `items`. A list change with `start` and `end` at 0 replaces the list whole; FlexHarness sends whole lists when it cannot know which entries the store holds: for a projection it loaded in an older schema and after a save with an uncertain outcome. The Agent event store of each session receives an `IAgentEventChange` of removed, replaced and appended events, as the `@modelprofile.com/flexharness-agent` readme describes. A store that keeps snapshots checks a change's form with `assertFlexProjectionChange()` or `assertAgentEventChange()`, applies it with `applyFlexProjectionChange()` or `applyAgentEventChange()`, and validates the result as above; `createWholeProjectionChange(snapshot)` makes the change that stores a projection whole. FlexHarness freezes every message and reversion segment it saved and replaces an entry instead of editing it, which is how it tells the entries the store already holds. `/stores/testing` exports `createFlexStoreContractTests(backend)`, the cases every built-in store passes, for a custom store to run with any test runner; its readme shows how.
 
 Custom Agent event and job providers may implement `releaseSession(storageKey, sessionId)` to release session-bound wrappers, handles, or caches without deleting durable data. FlexHarness calls these hooks only after the corresponding AgentSession or execution context has released runtime ownership. A failed release remains owned for a later retirement or disposal retry. `deleteSession()` and `deleteSessionGenerationCohort()` are the separate destructive operations for durable session data.
 
@@ -1145,13 +1148,13 @@ After every harness using a `JsonFileFlexHarnessStores` instance has been dispos
 
 The JSON stores are explicitly not cross-process safe. When several processes can access the same storage namespace, every core `IFlexHarnessStores` domain and `stores.projectManagement` must use database-backed or equivalent cross-process CAS. Process-local CAS for the core stores or for PM alone is insufficient: session generation creation, cleanup tombstones, PM replacement, and stale-writer rejection must all retain their respective atomic preconditions across processes.
 
-`NoSqlFlexHarnessStores` from `/stores/nosqldb` is that database-backed bundle for every domain. Pass it an initialized `SmartdataDb` and `await stores.prepare()` at startup, before the first harness uses it; the subpath readme describes chunked snapshots and failure reporting.
+`NoSqlFlexHarnessStores` from `/stores/nosqldb` is that database-backed bundle for every domain. Pass it an initialized `SmartdataDb` and `await stores.prepare()` at startup, before the first harness uses it; the subpath readme describes chunked snapshots, change logs and failure reporting.
 
 Direct store operations and non-run session mutations surface conflicts as `FlexHarnessStoreConflictError` or the corresponding AgentSession store conflict. Malformed, wrong-schema, or non-JSON snapshots are surfaced as `FlexHarnessStoreFormatError`. A write or deletion that changed its target but cannot confirm parent-directory durability surfaces `FlexHarnessStoreCommitUncertainError` with the affected path, operation, and cause. Run persistence failures cross the external error boundary and therefore become `FlexHarnessExternalError`. FlexHarness does not merge conflicts.
 
 Each domain serializes its own mutations. A successful run first persists a hidden completed projection, then finalizes the canonical Agent generation as `accepted`, then promotes the hidden projection publicly. Recovery uses the canonical generation outcome to promote an accepted stage or publish a failed/cancelled projection. Failed and cancelled generations remain auditable but never enter future model context.
 
-Projection stores accept schema version 1, 2, or 3 from `load()`, but every `save()` receives the current schema-3 shape. Schema 3 records explicit reversion protocol, transcript/workspace provenance, and V2 disposition. A terminal V2 segment must be conclusively `revertible`, `no-change`, or `nonrevertible`; a pending V2 capture remains owned by its capture WAL and is never treated as transcript history.
+Projection stores accept schema version 1, 2, or 3 from `load()`, but every `save()` receives a change that makes the current schema-3 shape. A change to a loaded schema-1 or schema-2 projection carries both lists whole. Schema 3 records explicit reversion protocol, transcript/workspace provenance, and V2 disposition. A terminal V2 segment must be conclusively `revertible`, `no-change`, or `nonrevertible`; a pending V2 capture remains owned by its capture WAL and is never treated as transcript history.
 
 Current schema-3 projections also persist optional `metrics` state. Older strict readers that do not recognize this key, or the token breakdown keys inside it (`reportedLifetimeInputTokens`, `reportedLifetimeCacheReadTokens`, `reportedLifetimeCacheWriteTokens`, `lifetimeTokenBreakdownComplete`), cannot reopen a projection after they have been written; downgrade or mixed-version access to that session is unsupported.
 

package/ts/utils.projectionchange.ts

@@ -0,0 +1,190 @@
+import { FlexHarnessStoreFormatError } from './errors.js';
+import type {
+  IFlexListChange,
+  IFlexMessage,
+  IFlexProjectionChange,
+  IFlexProjectionSnapshotCurrent,
+  IFlexReversionSegment,
+  TFlexProjectionSnapshot,
+} from './interfaces.js';
+import {
+  assertFlexProjectionSnapshot,
+  assertJsonSerializable,
+  cloneSerializable,
+  deepFreeze,
+} from './utils.json.js';
+import { assertExactKeys, assertRecord } from './utils.storecodecs.js';
+import { validateExpectedRevision } from './utils.storerules.js';
+
+const projectionChangeKeys = [
+  'schemaVersion',
+  'revision',
+  'metrics',
+  'messages',
+  'stagedTerminals',
+  'reversionSegments',
+  'revertCursor',
+  'excludedRunIds',
+  'pendingReversion',
+  'pendingReversionReleases',
+];
+
+function assertListChange(value: unknown, path: string): void {
+  assertRecord(value, path);
+  assertExactKeys(value, ['start', 'end', 'items'], path);
+  if (!Number.isSafeInteger(value.start) || Number(value.start) < 0) {
+    throw new FlexHarnessStoreFormatError(`${path}.start must be a non-negative integer.`);
+  }
+  if (!Number.isSafeInteger(value.end) || Number(value.end) < Number(value.start)) {
+    throw new FlexHarnessStoreFormatError(`${path}.end must be an integer from start.`);
+  }
+  if (!Array.isArray(value.items)) {
+    throw new FlexHarnessStoreFormatError(`${path}.items must be an array.`);
+  }
+  for (let index = 0; index < value.items.length; index++) {
+    assertRecord(value.items[index], `${path}.items[${index}]`);
+  }
+}
+
+/**
+ * Checks the form of a projection change: its fields, a positive revision and two list changes
+ * of records. Whether its content makes a valid projection is decided on the snapshot it
+ * produces, by `assertFlexProjectionSnapshot`.
+ */
+export function assertFlexProjectionChange(value: unknown): asserts value is IFlexProjectionChange {
+  assertJsonSerializable(value, '$change');
+  assertRecord(value, '$change');
+  assertExactKeys(value, projectionChangeKeys, '$change');
+  if (value.schemaVersion !== 3) {
+    throw new FlexHarnessStoreFormatError('Projection change schemaVersion must be 3.');
+  }
+  if (!Number.isSafeInteger(value.revision) || Number(value.revision) < 1) {
+    throw new FlexHarnessStoreFormatError('$change.revision must be a positive integer.');
+  }
+  assertListChange(value.messages, '$change.messages');
+  assertListChange(value.reversionSegments, '$change.reversionSegments');
+}
+
+function applyListChange<TItem>(
+  stored: readonly TItem[],
+  change: IFlexListChange<TItem>,
+  path: string,
+): TItem[] {
+  if (change.end > stored.length) {
+    throw new FlexHarnessStoreFormatError(
+      `${path} keeps entries up to ${change.end}, but the store holds ${stored.length}.`,
+    );
+  }
+  const next = stored.slice(change.start, change.end);
+  for (const item of change.items) next.push(item);
+  return next;
+}
+
+/**
+ * Applies `change` to a stored projection and returns the new snapshot; neither input is
+ * modified. A stored projection of an older schema offers no entries to keep, so only whole
+ * lists apply to it. It rejects a change that keeps entries the stored lists lack; the change's
+ * form is `assertFlexProjectionChange`'s to check and the result's content
+ * `assertFlexProjectionSnapshot`'s.
+ */
+export function applyFlexProjectionChange(
+  stored: TFlexProjectionSnapshot | undefined,
+  change: IFlexProjectionChange,
+): IFlexProjectionSnapshotCurrent {
+  const lists = stored?.schemaVersion === 3 ? stored : undefined;
+  return {
+    schemaVersion: 3,
+    revision: change.revision,
+    ...(change.metrics === undefined ? {} : { metrics: change.metrics }),
+    messages: applyListChange(lists?.messages ?? [], change.messages, '$change.messages'),
+    stagedTerminals: change.stagedTerminals,
+    reversionSegments: applyListChange(
+      lists?.reversionSegments ?? [],
+      change.reversionSegments,
+      '$change.reversionSegments',
+    ),
+    revertCursor: change.revertCursor,
+    excludedRunIds: change.excludedRunIds,
+    ...(change.pendingReversion === undefined ? {} : { pendingReversion: change.pendingReversion }),
+    pendingReversionReleases: change.pendingReversionReleases,
+  };
+}
+
+/** A copy of a change a store was asked to save at `expectedRevision`, after checking its form. */
+export function validateProjectionChangeSave(
+  change: IFlexProjectionChange,
+  expectedRevision: number,
+): IFlexProjectionChange {
+  assertFlexProjectionChange(change);
+  validateExpectedRevision(expectedRevision);
+  if (change.revision !== expectedRevision + 1) {
+    throw new FlexHarnessStoreFormatError(
+      `Change revision ${change.revision} must equal expected revision ${expectedRevision} plus one.`,
+    );
+  }
+  return cloneSerializable(change);
+}
+
+/** The snapshot `change` makes of a stored projection, validated in full for `sessionId`. */
+export function createChangedProjectionSnapshot(
+  stored: TFlexProjectionSnapshot | undefined,
+  change: IFlexProjectionChange,
+  sessionId: string,
+): IFlexProjectionSnapshotCurrent {
+  const snapshot = applyFlexProjectionChange(stored, change);
+  assertFlexProjectionSnapshot(snapshot, sessionId);
+  return snapshot;
+}
+
+/** A projection's message and reversion segment lists, entry by entry. */
+export interface IFlexProjectionLists {
+  messages: readonly IFlexMessage[];
+  reversionSegments: readonly IFlexReversionSegment[];
+}
+
+/** Freezes the lists' entries, which a change refers to by identity once they are saved. */
+export function freezeProjectionEntries(lists: IFlexProjectionLists): void {
+  for (const message of lists.messages) deepFreeze(message);
+  for (const segment of lists.reversionSegments) deepFreeze(segment);
+}
+
+/**
+ * The list change that turns `saved` into `current`. It keeps the run of entries the two share by
+ * identity, starting where `current` starts, and sends the rest; without such a run it sends the
+ * whole list.
+ */
+function createListChange<TItem>(
+  saved: readonly TItem[] | undefined,
+  current: readonly TItem[],
+): IFlexListChange<TItem> {
+  const start = saved === undefined || current.length === 0 ? -1 : saved.indexOf(current[0]);
+  if (saved === undefined || start < 0) return { start: 0, end: 0, items: current.slice() };
+  let kept = 0;
+  while (start + kept < saved.length && kept < current.length && saved[start + kept] === current[kept]) {
+    kept++;
+  }
+  return { start, end: start + kept, items: current.slice(kept) };
+}
+
+/**
+ * The change that turns the stored projection into `snapshot`, given the lists the store holds
+ * (`saved`). Entries are compared by identity, so they must be replaced, never edited, once
+ * saved. Without `saved` both lists are sent whole.
+ */
+export function createProjectionChange(
+  saved: IFlexProjectionLists | undefined,
+  snapshot: IFlexProjectionSnapshotCurrent,
+): IFlexProjectionChange {
+  return {
+    ...snapshot,
+    messages: createListChange(saved?.messages, snapshot.messages),
+    reversionSegments: createListChange(saved?.reversionSegments, snapshot.reversionSegments),
+  };
+}
+
+/** The change that stores `snapshot` whole. */
+export function createWholeProjectionChange(
+  snapshot: IFlexProjectionSnapshotCurrent,
+): IFlexProjectionChange {
+  return createProjectionChange(undefined, snapshot);
+}

package/ts/utils.storecodecs.ts

@@ -96,25 +96,25 @@ export function assertRecord(value: unknown, path: string): asserts value is Rec
 
 export function createAgentEventSnapshot(
   sessionId: string,
-  events: readonly plugins.TAgentEvent[],
+  events: plugins.TAgentEvent[],
   revision: number,
-): plugins.IAgentEventSnapshotV2 {
+): plugins.IAgentEventSnapshot {
   return {
     schemaVersion: 2,
     sessionId,
     revision,
     updatedAt: events.reduce((latest, event) => Math.max(latest, event.timestamp), 0),
-    events: normalizeJsonObjectUndefined([...events], '$events'),
+    events,
   };
 }
 
 export function validateAgentEventSnapshot(
   value: unknown,
   sessionId: string,
-): plugins.IAgentEventSnapshotV2 {
+): plugins.IAgentEventSnapshot {
   assertJsonSerializable(value, '$snapshot');
   try {
-    return plugins.validateAgentEventSnapshotV2(value, sessionId);
+    return plugins.validateAgentEventSnapshot(value, sessionId);
   } catch (error) {
     throw new FlexHarnessStoreFormatError(
       `$snapshot is not a canonical schema-2 Agent event snapshot: ${error instanceof Error ? error.message : String(error)}`,
@@ -127,10 +127,10 @@ export function validateAgentEventArchive(
   value: unknown,
   sessionId: string,
   archiveId: string,
-): plugins.IAgentEventArchiveV2 {
+): plugins.IAgentEventArchive {
   assertJsonSerializable(value, '$archive');
   try {
-    return plugins.validateAgentEventArchiveV2(value, sessionId, archiveId);
+    return plugins.validateAgentEventArchive(value, sessionId, archiveId);
   } catch (error) {
     throw new FlexHarnessStoreFormatError(
       `$archive is not a canonical schema-2 Agent event archive: ${error instanceof Error ? error.message : String(error)}`,
@@ -139,6 +139,41 @@ export function validateAgentEventArchive(
   }
 }
 
+/** A JSON copy of `change`, checked by `assertAgentEventChange`. */
+export function normalizeAgentEventChange(change: unknown): plugins.IAgentEventChange {
+  const normalized = normalizeJsonObjectUndefined(change, '$change');
+  try {
+    plugins.assertAgentEventChange(normalized);
+  } catch (error) {
+    throw new FlexHarnessStoreFormatError(
+      `$change is not a valid Agent event change: ${error instanceof Error ? error.message : String(error)}`,
+      { cause: error },
+    );
+  }
+  return normalized;
+}
+
+/**
+ * The next snapshot of `current` after a normalized `change`; the store validates it before it
+ * keeps it.
+ */
+export function createChangedAgentEventSnapshot(
+  sessionId: string,
+  current: plugins.IAgentEventSnapshot | undefined,
+  change: plugins.IAgentEventChange,
+): plugins.IAgentEventSnapshot {
+  let events: plugins.TAgentEvent[];
+  try {
+    events = plugins.applyAgentEventChange(current?.events ?? [], change);
+  } catch (error) {
+    throw new FlexHarnessStoreFormatError(
+      `$change does not apply to the stored Agent event log: ${error instanceof Error ? error.message : String(error)}`,
+      { cause: error },
+    );
+  }
+  return createAgentEventSnapshot(sessionId, events, (current?.revision ?? 0) + 1);
+}
+
 export function assertFlexToolJobSnapshot(value: unknown): asserts value is plugins.IToolJobSnapshot {
   assertJsonSerializable(value, '$snapshot');
   assertRecord(value, '$snapshot');