@modelprofile.com/flexharness 11.3.1 → 12.1.0

package/ts/classes.flexharness.core.ts

@@ -21,6 +21,7 @@ import type {
   IFlexMessage,
   IFlexPartSnapshotEvent,
   IFlexPromptQueueLimits,
+  IFlexProjectionChange,
   IFlexProjectionSnapshotCurrent,
   IFlexReversionLimits,
   IFlexReversionSegment,
@@ -51,6 +52,7 @@ import {
   resolveJsonLimits,
 } from './utils.json.js';
 import { hydrateAgentMessages } from './utils.prompt.js';
+import { createProjectionChange, freezeProjectionEntries } from './utils.projectionchange.js';
 import {
   normalizeAgentSessionPolicy,
   normalizeBuiltInTools,
@@ -550,7 +552,7 @@ export class FlexHarnessCore<TScope> {
       rememberedPermissionKeys: new Set(),
       permissionRevision: 0,
       permissionQueue: Promise.resolve(),
-      eventStore: undefined as unknown as plugins.IAgentEventStoreV2,
+      eventStore: undefined as unknown as plugins.IAgentEventStore,
       agentSession: unavailable,
       agentSessionAbortCompleted: true,
       agentSessionCloseCompleted: true,
@@ -699,6 +701,8 @@ export class FlexHarnessCore<TScope> {
         terminalPromptQueueEntries: new Map(),
         outstandingPromptBytes: 0,
       };
+      freezeProjectionEntries(stored);
+      if (currentProjection) this.rememberSavedProjectionLists(stored);
       if (currentProjection?.metrics === undefined
         || stored.metrics.pendingGenerationId !== undefined
         || stored.metrics.pendingCompactionId !== undefined
@@ -971,18 +975,20 @@ export class FlexHarnessCore<TScope> {
     if (stored.stagedTerminals.length > 0) stored.stagedTerminals = [];
     const activeEvents = stored.agentSession.getEvents();
     const activeEventIds = new Set(activeEvents.map((event) => event.id));
-    for (let index = 0; index < stored.reversionSegments.length; index++) {
-      const segment = stored.reversionSegments[index];
-      if (segment.eventIds.length > 0 && !segment.eventIds.some((id) => activeEventIds.has(id))) {
-        segment.contextAvailable = false;
-      }
-      if (segment.status !== 'capturing') {
+    stored.reversionSegments = stored.reversionSegments.map((segment) => {
+      const contextAvailable = segment.contextAvailable
+        && (segment.eventIds.length === 0 || segment.eventIds.some((id) => activeEventIds.has(id)));
+      let status = segment.status;
+      if (status !== 'capturing') {
         const outcome = outcomes.get(segment.runId);
-        if (outcome === 'accepted') segment.status = 'completed';
-        else if (outcome === 'rejected') segment.status = 'failed';
-        else if (outcome === 'interrupted' || segment.contextAvailable) segment.status = 'cancelled';
+        if (outcome === 'accepted') status = 'completed';
+        else if (outcome === 'rejected') status = 'failed';
+        else if (outcome === 'interrupted' || contextAvailable) status = 'cancelled';
       }
-    }
+      return contextAvailable === segment.contextAvailable && status === segment.status
+        ? segment
+        : { ...segment, contextAvailable, status };
+    });
     stored.revertCursor = stored.reversionSegments
       .slice(0, reversionVisibilityBoundary)
       .filter((segment) => segment.status === 'completed')
@@ -1032,17 +1038,19 @@ export class FlexHarnessCore<TScope> {
     });
     if (projectionChanged) {
       const expected = stored.projectionRevision;
-      const snapshot = this.createProjectionSnapshot(stored, expected + 1);
+      freezeProjectionEntries(stored);
+      const change = this.createProjectionChange(stored, expected + 1);
       await this.stores.projections.save(
         storageKey,
         stored.session.sessionId,
-        snapshot,
+        change,
         expected,
       );
       stored.projectionSchemaVersion = 3;
       delete stored.projectionBaseline;
+      this.rememberSavedProjectionLists(stored);
       stored.projectionReconciliationRequired = false;
-      stored.projectionRevision = snapshot.revision;
+      stored.projectionRevision = change.revision;
     }
     return beforeSession !== JSON.stringify(stored.session);
   }
@@ -1239,9 +1247,10 @@ export class FlexHarnessCore<TScope> {
         ? undefined
         : cloneSerializable(stored.projectionBaseline);
       const beforeMetrics = cloneSerializable(stored.metrics);
-      const beforeMessages = cloneSerializable(stored.messages);
+      // List entries are frozen and replaced rather than edited, so copies of the lists suffice.
+      const beforeMessages = stored.messages.slice();
       const beforeStages = cloneSerializable(stored.stagedTerminals);
-      const beforeSegments = cloneSerializable(stored.reversionSegments);
+      const beforeSegments = stored.reversionSegments.slice();
       const beforeCursor = stored.revertCursor;
       const beforeExcludedRunIds = cloneSerializable(stored.excludedRunIds);
       const beforePendingReversion = stored.pendingReversion === undefined
@@ -1285,18 +1294,20 @@ export class FlexHarnessCore<TScope> {
         restore();
         throw error;
       }
-      const snapshot = this.createProjectionSnapshot(stored, beforeRevision + 1);
+      freezeProjectionEntries(stored);
+      const revision = beforeRevision + 1;
       try {
         await this.stores.projections.save(
           state.storageKey,
           stored.session.sessionId,
-          snapshot,
+          this.createProjectionChange(stored, revision),
           beforeRevision,
         );
         stored.projectionSchemaVersion = 3;
         delete stored.projectionBaseline;
+        this.rememberSavedProjectionLists(stored);
         stored.projectionReconciliationRequired = false;
-        stored.projectionRevision = snapshot.revision;
+        stored.projectionRevision = revision;
         return result;
       } catch (error) {
         if (error instanceof FlexHarnessStoreConflictError) {
@@ -1305,11 +1316,13 @@ export class FlexHarnessCore<TScope> {
         }
         if (error instanceof FlexHarnessStoreCommitUncertainError) {
           stored.projectionSchemaVersion = 3;
+          delete stored.savedProjectionLists;
           stored.projectionReconciliationRequired = true;
-          stored.projectionRevision = snapshot.revision;
+          stored.projectionRevision = revision;
           state.lifecycle = 'fenced';
           throw error;
         }
+        const snapshot = this.createProjectionSnapshot(stored, revision);
         let current: TFlexProjectionSnapshot | undefined;
         let reconciliationError: unknown;
         try {
@@ -1323,8 +1336,9 @@ export class FlexHarnessCore<TScope> {
         if (current && JSON.stringify(current) === JSON.stringify(snapshot)) {
           stored.projectionSchemaVersion = 3;
           delete stored.projectionBaseline;
+          this.rememberSavedProjectionLists(stored);
           stored.projectionReconciliationRequired = false;
-          stored.projectionRevision = snapshot.revision;
+          stored.projectionRevision = revision;
           throw error;
         }
         if (
@@ -1335,8 +1349,9 @@ export class FlexHarnessCore<TScope> {
           throw error;
         }
         stored.projectionSchemaVersion = 3;
+        delete stored.savedProjectionLists;
         stored.projectionReconciliationRequired = true;
-        stored.projectionRevision = snapshot.revision;
+        stored.projectionRevision = revision;
         state.lifecycle = 'fenced';
         throw reconciliationError === undefined
           ? error
@@ -1380,6 +1395,35 @@ export class FlexHarnessCore<TScope> {
     };
   }
 
+  /** The change from the lists the store holds to the session's projection at `revision`. */
+  private createProjectionChange(
+    stored: IStoredSessionState,
+    revision: number,
+  ): IFlexProjectionChange {
+    return createProjectionChange(stored.savedProjectionLists, {
+      schemaVersion: 3,
+      revision,
+      metrics: cloneSerializable(stored.metrics),
+      messages: stored.messages,
+      stagedTerminals: cloneSerializable(stored.stagedTerminals),
+      reversionSegments: stored.reversionSegments,
+      revertCursor: stored.revertCursor,
+      excludedRunIds: cloneSerializable(stored.excludedRunIds),
+      ...(stored.pendingReversion === undefined
+        ? {}
+        : { pendingReversion: cloneSerializable(stored.pendingReversion) }),
+      pendingReversionReleases: cloneSerializable(stored.pendingReversionReleases),
+    });
+  }
+
+  /** Records the session's lists as the ones the store now holds. */
+  private rememberSavedProjectionLists(stored: IStoredSessionState): void {
+    stored.savedProjectionLists = {
+      messages: stored.messages.slice(),
+      reversionSegments: stored.reversionSegments.slice(),
+    };
+  }
+
   public upgradeProjectionSnapshot(
     projection: TFlexProjectionSnapshot,
   ): IFlexProjectionSnapshotCurrent {
@@ -1443,8 +1487,14 @@ export class FlexHarnessCore<TScope> {
     if (current.pendingReversion === undefined) delete stored.pendingReversion;
     else stored.pendingReversion = current.pendingReversion;
     stored.pendingReversionReleases = current.pendingReversionReleases;
-    if (projection.schemaVersion === 3) delete stored.projectionBaseline;
-    else stored.projectionBaseline = cloneSerializable(projection);
+    freezeProjectionEntries(stored);
+    if (projection.schemaVersion === 3) {
+      delete stored.projectionBaseline;
+      this.rememberSavedProjectionLists(stored);
+    } else {
+      stored.projectionBaseline = cloneSerializable(projection);
+      delete stored.savedProjectionLists;
+    }
     stored.projectionSchemaVersion = projection.schemaVersion;
     stored.projectionRevision = projection.revision;
     stored.projectionReconciliationRequired = false;

package/ts/classes.flexharness.imports.ts

@@ -17,6 +17,7 @@ import {
   type TFlexBeginSessionImportResult,
 } from './interfaces.js';
 import { cloneSerializable } from './utils.json.js';
+import { createWholeProjectionChange } from './utils.projectionchange.js';
 import { publicSnapshot } from './utils.transfer.js';
 import {
   normalizeBeginSessionImportOptions,
@@ -231,7 +232,7 @@ export class FlexHarnessSessionImports<TScope> {
         });
       });
       reserved = true;
-      await this.core.stores.projections.save(state.storageKey, sessionId, {
+      await this.core.stores.projections.save(state.storageKey, sessionId, createWholeProjectionChange({
         schemaVersion: 3,
         revision: 1,
         metrics: createSessionMetricsState(false),
@@ -241,7 +242,7 @@ export class FlexHarnessSessionImports<TScope> {
         revertCursor: 0,
         excludedRunIds: [],
         pendingReversionReleases: [],
-      }, 0);
+      }), 0);
       const runtime = await this.core.loadSessionRuntime(state, metadata, scopeId, scope);
       loaded = runtime;
       await this.core.mutateScope(state, () => {

package/ts/classes.flexharness.reversions.ts

@@ -28,6 +28,7 @@ import {
   type TJsonValue,
 } from './interfaces.js';
 import { cloneSerializable, normalizeJsonValue } from './utils.json.js';
+import { createWholeProjectionChange } from './utils.projectionchange.js';
 import { publicSnapshot } from './utils.transfer.js';
 import type {
   TCanonicalOutcome,
@@ -402,13 +403,8 @@ export class FlexHarnessReversions<TScope> {
       && !segment.eventIds.some((eventId) => activeEvents.has(eventId)))) return false;
     let branchCommitted = false;
     await this.core.mutateProjection(state, stored, () => {
-      for (const segment of stored.reversionSegments) {
-        if (
-          segment.contextAvailable
-          && segment.eventIds.length > 0
-          && !segment.eventIds.some((eventId) => activeEvents.has(eventId))
-        ) segment.contextAvailable = false;
-      }
+      this.markReversionContextUnavailable(stored, (segment) =>
+        segment.eventIds.length > 0 && !segment.eventIds.some((eventId) => activeEvents.has(eventId)));
       branchCommitted = this.commitArchivedHiddenBranchState(stored);
       this.pruneReversionState(stored, false, true);
     }, true);
@@ -618,16 +614,22 @@ export class FlexHarnessReversions<TScope> {
       return;
     }
     await this.core.mutateProjection(state, stored, () => {
-      segment.status = outcome === 'accepted'
-        ? 'completed'
-        : outcome === 'rejected'
-          ? 'failed'
-        : 'cancelled';
-      this.applyFinalizedReversionOutcome(stored, segment, finalizedOutcome);
-      segment.eventIds = stored.agentSession.getEvents()
+      const index = stored.reversionSegments.findIndex((entry) => entry.runId === pending.runId);
+      if (index < 0) throw new FlexHarnessValidationError('Pending capture references a missing segment.');
+      const finalized: IFlexReversionSegment = {
+        ...stored.reversionSegments[index],
+        status: outcome === 'accepted'
+          ? 'completed'
+          : outcome === 'rejected'
+            ? 'failed'
+          : 'cancelled',
+      };
+      this.applyFinalizedReversionOutcome(stored, finalized, finalizedOutcome);
+      finalized.eventIds = stored.agentSession.getEvents()
         .filter((event) => event.generationId === pending.runId)
         .map((event) => event.id);
-      if (segment.status === 'completed') stored.revertCursor++;
+      stored.reversionSegments[index] = finalized;
+      if (finalized.status === 'completed') stored.revertCursor++;
       if (outcome === undefined && !stored.excludedRunIds.includes(pending.runId)) {
         stored.excludedRunIds.push(pending.runId);
       }
@@ -1077,23 +1079,42 @@ export class FlexHarnessReversions<TScope> {
     };
   }
 
-  /** Records a run's terminal status and events on its segment and moves the revert cursor. */
+  /**
+   * Replaces a run's segment with a copy that records its terminal status and events, moves the
+   * revert cursor and returns the copy.
+   */
   private closeRunReversionSegment(
     run: IActiveRun,
     status: 'completed' | 'failed' | 'cancelled',
   ): IFlexReversionSegment {
-    const segment = run.stored.reversionSegments.find((entry) => entry.runId === run.runId);
-    if (!segment) throw new FlexHarnessValidationError('Reversion segment changed before finalization.');
-    const wasCompleted = segment.status === 'completed';
-    segment.status = status;
-    segment.eventIds = run.stored.agentSession.getEvents()
-      .filter((event) => event.generationId === run.runId)
-      .map((event) => event.id);
+    const index = run.stored.reversionSegments.findIndex((entry) => entry.runId === run.runId);
+    if (index < 0) throw new FlexHarnessValidationError('Reversion segment changed before finalization.');
+    const wasCompleted = run.stored.reversionSegments[index].status === 'completed';
+    const closed: IFlexReversionSegment = {
+      ...run.stored.reversionSegments[index],
+      status,
+      eventIds: run.stored.agentSession.getEvents()
+        .filter((event) => event.generationId === run.runId)
+        .map((event) => event.id),
+    };
+    run.stored.reversionSegments[index] = closed;
     if (!wasCompleted && status === 'completed') run.stored.revertCursor++;
     else if (wasCompleted && status !== 'completed') run.stored.revertCursor--;
-    return segment;
+    return closed;
   }
 
+  /** Replaces the segments `unavailable` selects with copies that have no context available. */
+  public markReversionContextUnavailable(
+    stored: IStoredSessionState,
+    unavailable: (segment: IFlexReversionSegment) => boolean,
+  ): void {
+    stored.reversionSegments = stored.reversionSegments.map((segment) =>
+      segment.contextAvailable && unavailable(segment)
+        ? { ...segment, contextAvailable: false }
+        : segment);
+  }
+
+  /** Records a finalized capture on `segment`, an unsaved copy the caller puts in place. */
   private applyFinalizedReversionOutcome(
     stored: IStoredSessionState,
     segment: IFlexReversionSegment,
@@ -1270,9 +1291,8 @@ export class FlexHarnessReversions<TScope> {
     const archivedIds = new Set(events.flatMap((event) => event.type === 'context-compaction' && event.automatic
       ? event.coveredEventIds.filter((id) => !activeIds.has(id)) : []));
     if (archivedIds.size === 0) return;
-    for (const segment of stored.reversionSegments) {
-      if (segment.eventIds.some((id) => archivedIds.has(id))) segment.contextAvailable = false;
-    }
+    this.markReversionContextUnavailable(stored, (segment) =>
+      segment.eventIds.some((id) => archivedIds.has(id)));
     this.commitArchivedHiddenBranchState(stored);
     this.pruneReversionState(stored, false, true);
   }
@@ -1394,7 +1414,12 @@ export class FlexHarnessReversions<TScope> {
     const persistDirect = async (next: IFlexProjectionSnapshotCurrent): Promise<void> => {
       const before = durableProjection;
       try {
-        await this.core.stores.projections.save(storageKey, sessionId, next, projection.revision);
+        await this.core.stores.projections.save(
+          storageKey,
+          sessionId,
+          createWholeProjectionChange(next),
+          projection.revision,
+        );
         durableProjection = next;
         projection = next;
       } catch (error) {

package/ts/classes.flexharness.sessions.ts

@@ -456,11 +456,8 @@ export class FlexHarnessSessions<TScope> {
       const archivedIds = new Set(archive.events.map((event) => event.id));
       await this.core.mutateProjection(state, stored, () => {
         branchCommitted = this.core.reversions.commitRevertedBranchState(stored);
-        for (const segment of stored.reversionSegments) {
-          if (segment.eventIds.some((eventId) => archivedIds.has(eventId))) {
-            segment.contextAvailable = false;
-          }
-        }
+        this.core.reversions.markReversionContextUnavailable(stored, (segment) =>
+          segment.eventIds.some((eventId) => archivedIds.has(eventId)));
         this.core.reversions.pruneReversionState(stored);
       }, true);
     } catch (error) {

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;