@modelprofile.com/flexharness 11.3.0 → 12.0.0

package/dist_ts_stores_testing/fixtures.d.ts

@@ -0,0 +1,20 @@
+import * as plugins from './plugins.js';
+import type { IFlexMessage, IFlexPermissionSnapshot, IFlexProjectionSnapshotCurrent, IFlexReversionSegment, IFlexScopeSnapshot } from '../dist_ts/interfaces.js';
+/** A scope snapshot with one idle session. */
+export declare function scopeSnapshot(revision: number, sessionId?: string): IFlexScopeSnapshot;
+/** An empty projection. */
+export declare function projectionSnapshot(revision: number): IFlexProjectionSnapshotCurrent;
+/** The user and assistant message of one completed run of `session-1`. */
+export declare function runMessages(runId: string): IFlexMessage[];
+/** The reversion segment of one completed run, without a workspace capture. */
+export declare function runSegment(runId: string): IFlexReversionSegment;
+/** A projection of completed runs of `session-1`, each with its messages and reversion segment. */
+export declare function projectionWithRuns(revision: number, runIds: string[]): IFlexProjectionSnapshotCurrent;
+/** A permission snapshot that remembers one approval. */
+export declare function permissionSnapshot(revision: number): IFlexPermissionSnapshot;
+/** A system message event. */
+export declare function agentEvent(id?: string, content?: string): plugins.ISystemMessageEvent;
+/** The Agent event change that appends `events`. */
+export declare function appendEvents(...events: plugins.TAgentEvent[]): plugins.IAgentEventChange;
+/** A finished shell job. */
+export declare function finishedJob(executionId?: string): plugins.IToolJobState;

package/dist_ts_stores_testing/fixtures.js

@@ -0,0 +1,112 @@
+import * as plugins from './plugins.js';
+/** A scope snapshot with one idle session. */
+export function scopeSnapshot(revision, sessionId = 'session-1') {
+    return {
+        schemaVersion: 1,
+        revision,
+        sessions: [
+            {
+                scopeId: 'scope-1',
+                sessionId,
+                createdAt: '2026-08-05T00:00:00.000Z',
+                updatedAt: '2026-08-05T00:00:00.000Z',
+                status: 'idle',
+                activity: { status: 'idle' },
+            },
+        ],
+        tombstones: [],
+    };
+}
+/** An empty projection. */
+export function projectionSnapshot(revision) {
+    return {
+        schemaVersion: 3,
+        revision,
+        messages: [],
+        stagedTerminals: [],
+        reversionSegments: [],
+        revertCursor: 0,
+        excludedRunIds: [],
+        pendingReversionReleases: [],
+    };
+}
+/** The user and assistant message of one completed run of `session-1`. */
+export function runMessages(runId) {
+    return [{
+            messageId: `user-${runId}`,
+            sessionId: 'session-1',
+            runId,
+            role: 'user',
+            status: 'completed',
+            createdAt: '2026-08-05T00:00:00.000Z',
+            completedAt: '2026-08-05T00:00:01.000Z',
+            parts: [{ partId: `user-part-${runId}`, type: 'text', text: runId }],
+        }, {
+            messageId: `assistant-${runId}`,
+            sessionId: 'session-1',
+            runId,
+            role: 'assistant',
+            status: 'completed',
+            createdAt: '2026-08-05T00:00:00.000Z',
+            completedAt: '2026-08-05T00:00:01.000Z',
+            parts: [{ partId: `assistant-part-${runId}`, type: 'text', text: 'answer' }],
+        }];
+}
+/** The reversion segment of one completed run, without a workspace capture. */
+export function runSegment(runId) {
+    return {
+        runId,
+        userMessageId: `user-${runId}`,
+        status: 'completed',
+        contextAvailable: true,
+        eventIds: [`event-${runId}`],
+        workspaceCaptured: false,
+        protocolVersion: 1,
+        provenance: 'transcript',
+    };
+}
+/** A projection of completed runs of `session-1`, each with its messages and reversion segment. */
+export function projectionWithRuns(revision, runIds) {
+    return {
+        ...projectionSnapshot(revision),
+        messages: runIds.flatMap(runMessages),
+        reversionSegments: runIds.map(runSegment),
+        revertCursor: runIds.length,
+    };
+}
+/** A permission snapshot that remembers one approval. */
+export function permissionSnapshot(revision) {
+    return {
+        schemaVersion: 1,
+        revision,
+        rememberedPermissionKeys: ['shell:approved'],
+    };
+}
+/** A system message event. */
+export function agentEvent(id = 'event-1', content = 'System prompt') {
+    return plugins.createAgentEvent({
+        id,
+        timestamp: 1,
+        type: 'system-message',
+        content,
+    });
+}
+/** The Agent event change that appends `events`. */
+export function appendEvents(...events) {
+    return { remove: [], replace: [], append: events };
+}
+/** A finished shell job. */
+export function finishedJob(executionId = 'job-1') {
+    return {
+        executionId,
+        type: 'shell',
+        state: 'finished',
+        exitCode: 0,
+        stdout: 'ok',
+        stderr: '',
+        startedAt: 1,
+        updatedAt: 2,
+        finishedAt: 2,
+    };
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZml4dHVyZXMuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90c19zdG9yZXNfdGVzdGluZy9maXh0dXJlcy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssT0FBTyxNQUFNLGNBQWMsQ0FBQztBQVN4Qyw4Q0FBOEM7QUFDOUMsTUFBTSxVQUFVLGFBQWEsQ0FBQyxRQUFnQixFQUFFLFNBQVMsR0FBRyxXQUFXO0lBQ3JFLE9BQU87UUFDTCxhQUFhLEVBQUUsQ0FBQztRQUNoQixRQUFRO1FBQ1IsUUFBUSxFQUFFO1lBQ1I7Z0JBQ0UsT0FBTyxFQUFFLFNBQVM7Z0JBQ2xCLFNBQVM7Z0JBQ1QsU0FBUyxFQUFFLDBCQUEwQjtnQkFDckMsU0FBUyxFQUFFLDBCQUEwQjtnQkFDckMsTUFBTSxFQUFFLE1BQU07Z0JBQ2QsUUFBUSxFQUFFLEVBQUUsTUFBTSxFQUFFLE1BQU0sRUFBRTthQUM3QjtTQUNGO1FBQ0QsVUFBVSxFQUFFLEVBQUU7S0FDZixDQUFDO0FBQ0osQ0FBQztBQUVELDJCQUEyQjtBQUMzQixNQUFNLFVBQVUsa0JBQWtCLENBQUMsUUFBZ0I7SUFDakQsT0FBTztRQUNMLGFBQWEsRUFBRSxDQUFDO1FBQ2hCLFFBQVE7UUFDUixRQUFRLEVBQUUsRUFBRTtRQUNaLGVBQWUsRUFBRSxFQUFFO1FBQ25CLGlCQUFpQixFQUFFLEVBQUU7UUFDckIsWUFBWSxFQUFFLENBQUM7UUFDZixjQUFjLEVBQUUsRUFBRTtRQUNsQix3QkFBd0IsRUFBRSxFQUFFO0tBQzdCLENBQUM7QUFDSixDQUFDO0FBRUQsMEVBQTBFO0FBQzFFLE1BQU0sVUFBVSxXQUFXLENBQUMsS0FBYTtJQUN2QyxPQUFPLENBQUM7WUFDTixTQUFTLEVBQUUsUUFBUSxLQUFLLEVBQUU7WUFDMUIsU0FBUyxFQUFFLFdBQVc7WUFDdEIsS0FBSztZQUNMLElBQUksRUFBRSxNQUFNO1lBQ1osTUFBTSxFQUFFLFdBQVc7WUFDbkIsU0FBUyxFQUFFLDBCQUEwQjtZ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

package/dist_ts_stores_testing/index.d.ts

@@ -0,0 +1,2 @@
+export { createFlexStoreContractTests, type IFlexStoreContractBackend, type IFlexStoreContractFixture, type IFlexStoreContractTest, } from './contract.js';
+export { agentEvent, appendEvents, finishedJob, permissionSnapshot, projectionSnapshot, projectionWithRuns, runMessages, runSegment, scopeSnapshot, } from './fixtures.js';

package/dist_ts_stores_testing/index.js

@@ -0,0 +1,3 @@
+export { createFlexStoreContractTests, } from './contract.js';
+export { agentEvent, appendEvents, finishedJob, permissionSnapshot, projectionSnapshot, projectionWithRuns, runMessages, runSegment, scopeSnapshot, } from './fixtures.js';
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90c19zdG9yZXNfdGVzdGluZy9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEVBQ0wsNEJBQTRCLEdBSTdCLE1BQU0sZUFBZSxDQUFDO0FBQ3ZCLE9BQU8sRUFDTCxVQUFVLEVBQ1YsWUFBWSxFQUNaLFdBQVcsRUFDWCxrQkFBa0IsRUFDbEIsa0JBQWtCLEVBQ2xCLGtCQUFrQixFQUNsQixXQUFXLEVBQ1gsVUFBVSxFQUNWLGFBQWEsR0FDZCxNQUFNLGVBQWUsQ0FBQyJ9

package/dist_ts_stores_testing/plugins.d.ts

@@ -0,0 +1,5 @@
+import { strict as assert } from 'node:assert';
+export { assert };
+import { AgentEventStoreConflictError, ToolJobStoreConflictError, createAgentEvent } from '@modelprofile.com/flexharness-agent';
+export { AgentEventStoreConflictError, ToolJobStoreConflictError, createAgentEvent };
+export type { IAgentEventArchive, IAgentEventChange, ISystemMessageEvent, IToolJobState, TAgentEvent, } from '@modelprofile.com/flexharness-agent';

package/dist_ts_stores_testing/plugins.js

@@ -0,0 +1,7 @@
+// node native scope
+import { strict as assert } from 'node:assert';
+export { assert };
+// @modelprofile.com scope
+import { AgentEventStoreConflictError, ToolJobStoreConflictError, createAgentEvent, } from '@modelprofile.com/flexharness-agent';
+export { AgentEventStoreConflictError, ToolJobStoreConflictError, createAgentEvent };
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicGx1Z2lucy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3RzX3N0b3Jlc190ZXN0aW5nL3BsdWdpbnMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsb0JBQW9CO0FBQ3BCLE9BQU8sRUFBRSxNQUFNLElBQUksTUFBTSxFQUFFLE1BQU0sYUFBYSxDQUFDO0FBRS9DLE9BQU8sRUFBRSxNQUFNLEVBQUUsQ0FBQztBQUVsQiwwQkFBMEI7QUFDMUIsT0FBTyxFQUNMLDRCQUE0QixFQUM1Qix5QkFBeUIsRUFDekIsZ0JBQWdCLEdBQ2pCLE1BQU0scUNBQXFDLENBQUM7QUFFN0MsT0FBTyxFQUFFLDRCQUE0QixFQUFFLHlCQUF5QixFQUFFLGdCQUFnQixFQUFFLENBQUMifQ==

package/package.json

@@ -2,7 +2,7 @@
   "author": "Task Venture Capital GmbH",
   "license": "MIT",
   "name": "@modelprofile.com/flexharness",
-  "version": "11.3.0",
+  "version": "12.0.0",
   "type": "module",
   "description": "Managed agent sessions with tools, MCP, chat, OCR, documents and browser control through focused subpath imports.",
   "main": "./dist_ts/index.js",
@@ -80,6 +80,10 @@
       "types": "./dist_ts_stores_nosqldb/index.d.ts",
       "import": "./dist_ts_stores_nosqldb/index.js"
     },
+    "./stores/testing": {
+      "types": "./dist_ts_stores_testing/index.d.ts",
+      "import": "./dist_ts_stores_testing/index.js"
+    },
     "./typedrequest": {
       "types": "./dist_ts_typedrequest/index.d.ts",
       "import": "./dist_ts_typedrequest/index.js"
@@ -87,8 +91,8 @@
   },
   "dependencies": {
     "@cfworker/json-schema": "^4.1.1",
-    "@modelprofile.com/flexharness-agent": "11.3.0",
-    "@modelprofile.com/flexharness-models": "11.3.0",
+    "@modelprofile.com/flexharness-agent": "12.0.0",
+    "@modelprofile.com/flexharness-models": "12.0.0",
     "@push.rocks/smartrequest": "^5.5.1",
     "ai": "^7.0.111",
     "zod": "^4.6.5"
@@ -216,6 +220,8 @@
     "dist_ts_chat_harness_typedsocket",
     "ts_stores_nosqldb",
     "dist_ts_stores_nosqldb",
+    "ts_stores_testing",
+    "dist_ts_stores_testing",
     "ts_typedrequest",
     "dist_ts_typedrequest",
     "readme.md",

package/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/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@modelprofile.com/flexharness',
-  version: '11.3.0',
+  version: '12.0.0',
   description: 'The FlexHarness toolbox source repository and shared dependency catalog.'
 }

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) {