@modelprofile.com/flexharness 18.9.0 → 18.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (35) hide show
  1. package/dist_ts/00_commitinfo_data.js +2 -2
  2. package/dist_ts/classes.flexharness.core.d.ts +15 -3
  3. package/dist_ts/classes.flexharness.core.js +211 -18
  4. package/dist_ts/classes.flexharness.d.ts +3 -1
  5. package/dist_ts/classes.flexharness.js +5 -1
  6. package/dist_ts/classes.flexharness.lifecycle.js +4 -1
  7. package/dist_ts/classes.flexharness.reversions.d.ts +2 -1
  8. package/dist_ts/classes.flexharness.reversions.js +15 -75
  9. package/dist_ts/classes.flexharness.sessions.js +9 -6
  10. package/dist_ts/classes.recoverygate.d.ts +1 -0
  11. package/dist_ts/classes.recoverygate.js +4 -1
  12. package/dist_ts/index.d.ts +1 -0
  13. package/dist_ts/index.js +2 -1
  14. package/dist_ts/interfaces.d.ts +20 -0
  15. package/dist_ts/interfaces.js +1 -1
  16. package/dist_ts/utils.reversionpresentation.d.ts +12 -0
  17. package/dist_ts/utils.reversionpresentation.js +219 -0
  18. package/dist_ts_stores_nosqldb/classes.nosqldbstores.js +76 -4
  19. package/dist_ts_stores_nosqldb/classes.recordstore.d.ts +1 -1
  20. package/dist_ts_stores_nosqldb/classes.recordstore.js +1 -1
  21. package/package.json +3 -3
  22. package/readme.md +5 -1
  23. package/ts/00_commitinfo_data.ts +1 -1
  24. package/ts/classes.flexharness.core.ts +239 -36
  25. package/ts/classes.flexharness.lifecycle.ts +3 -0
  26. package/ts/classes.flexharness.reversions.ts +19 -69
  27. package/ts/classes.flexharness.sessions.ts +6 -5
  28. package/ts/classes.flexharness.ts +10 -0
  29. package/ts/classes.recoverygate.ts +4 -0
  30. package/ts/index.ts +4 -0
  31. package/ts/interfaces.ts +32 -0
  32. package/ts/readme.md +5 -1
  33. package/ts/utils.reversionpresentation.ts +227 -0
  34. package/ts_stores_nosqldb/classes.nosqldbstores.ts +101 -2
  35. package/ts_stores_nosqldb/classes.recordstore.ts +1 -0
@@ -34,6 +34,7 @@ import type {
34
34
  IFlexScopeLoadMetrics,
35
35
  IFlexScopeSnapshot,
36
36
  IFlexSession,
37
+ IFlexSessionAuxiliarySummary,
37
38
  IFlexSessionImportLimits,
38
39
  IFlexSessionTombstone,
39
40
  IFlexSubagentDefinition,
@@ -66,6 +67,7 @@ import { FlexTimeSlicer } from './classes.timeslicer.js';
66
67
  import { liveScopeSessions, normalizeScopeSnapshot } from './utils.scopesnapshot.js';
67
68
  import { hydrateAgentMessages } from './utils.prompt.js';
68
69
  import { createProjectionChange, freezeProjectionEntries } from './utils.projectionchange.js';
70
+ import { assertFlexSessionAuxiliarySummary, deriveReversionPresentation } from './utils.reversionpresentation.js';
69
71
  import {
70
72
  normalizeAgentSessionPolicy,
71
73
  normalizeAttachmentResolver,
@@ -98,6 +100,7 @@ import { validateIdentifier, validateProjectedErrorInfo } from './utils.validati
98
100
  import {
99
101
  createSessionMetricsOperation,
100
102
  createSessionMetricsState,
103
+ sessionMetricsView,
101
104
  } from './utils.sessionmetrics.js';
102
105
  import type {
103
106
  TCanonicalOutcome,
@@ -516,7 +519,7 @@ export class FlexHarnessCore<TScope> {
516
519
  catalogue: new Map(liveScopeSessions(snapshot).map((session) => [session.sessionId, session])),
517
520
  sessionLocal: local !== undefined,
518
521
  qualifyingLegacy,
519
- recoverySessionIds: new Set(local && local.recoverySchemaVersion !== 1
522
+ recoverySessionIds: new Set(local && local.recoverySchemaVersion === 2
520
523
  && !this.cleanRecoveryEnabled(storageKey)
521
524
  ? [...new Set([...local.recoverySessionIds,
522
525
  ...(local.snapshot?.sessions.map((session) => session.sessionId) ?? [])])]
@@ -557,6 +560,10 @@ export class FlexHarnessCore<TScope> {
557
560
  for (const metadata of liveScopeSessions(snapshot).filter((session) =>
558
561
  !state.sessionLocal || qualifyingLegacy || state.recoverySessionIds.has(session.sessionId))) {
559
562
  compactorLifecycleController.signal.throwIfAborted();
563
+ if (local?.recoverySchemaVersion === 2 && !this.cleanRecoveryEnabled(storageKey)) {
564
+ // A compatibility open always invalidates inherited clean proof before full repair.
565
+ await this.markRecoveryRequired(state, metadata.sessionId);
566
+ }
560
567
  const stored = await this.loadSessionRuntime(
561
568
  state,
562
569
  metadata,
@@ -655,7 +662,7 @@ export class FlexHarnessCore<TScope> {
655
662
  for (const loaded of loadedSessions) {
656
663
  loaded.recovering = false;
657
664
  await this.updateRecoveryObligation(state, loaded);
658
- await this.publishSettledSessionClean(state, loaded.session.sessionId);
665
+ await this.settleQuiescentSessionRecovery(state, loaded.session.sessionId);
659
666
  }
660
667
  }
661
668
  return state;
@@ -786,7 +793,7 @@ export class FlexHarnessCore<TScope> {
786
793
  else state.catalogue.set(sessionId, stored.session);
787
794
  stored.recovering = false;
788
795
  await this.updateRecoveryObligation(state, stored);
789
- await this.publishSettledSessionClean(state, sessionId);
796
+ await this.settleQuiescentSessionRecovery(state, sessionId);
790
797
  this.assertStateAcceptingWork(state);
791
798
  return stored;
792
799
  } catch (error) {
@@ -827,6 +834,8 @@ export class FlexHarnessCore<TScope> {
827
834
  if (state.sessionLoads.has(id)) { await state.sessionLoads.get(id); continue; }
828
835
  const stored = state.sessions.get(id);
829
836
  if (!stored) { await this.hydrateSession(state, id, scopeId, scope); continue; }
837
+ await this.settleQuiescentSessionRecovery(state, id);
838
+ if (!state.recoverySessionIds.has(id)) continue;
830
839
  stored.recovering = true;
831
840
  await this.repairLoadedSession(state.storageKey, stored, state, scopeId, scope,
832
841
  new FlexTimeSlicer(state.compactorLifecycleController.signal));
@@ -835,6 +844,7 @@ export class FlexHarnessCore<TScope> {
835
844
  await this.mutateSessionScope(state, id, () => undefined);
836
845
  stored.recovering = false;
837
846
  await this.updateRecoveryObligation(state, stored);
847
+ await this.settleQuiescentSessionRecovery(state, id);
838
848
  }
839
849
  for (const root of roots) await this.deletion.finishTombstoneCleanup(state, root, scopeId, { scopeId, scope });
840
850
  })().finally(() => { if (state.sharedRecovery === recovery) delete state.sharedRecovery; });
@@ -879,10 +889,10 @@ export class FlexHarnessCore<TScope> {
879
889
  private recoveryProducerGate(state: IStorageState, sessionId: string): FlexRecoveryProducerGate {
880
890
  let gate = state.recoveryProducerGates.get(sessionId);
881
891
  if (!gate) {
882
- gate = new FlexRecoveryProducerGate(this.cleanRecoveryEnabled(state.storageKey) ? () => {
883
- void this.publishSettledSessionClean(state, sessionId)
892
+ gate = new FlexRecoveryProducerGate(() => {
893
+ void this.settleQuiescentSessionRecovery(state, sessionId)
884
894
  .catch((error: unknown) => this.lifecycle.deferNamespaceDrain(state, error));
885
- } : undefined);
895
+ });
886
896
  state.recoveryProducerGates.set(sessionId, gate);
887
897
  }
888
898
  return gate;
@@ -978,20 +988,132 @@ export class FlexHarnessCore<TScope> {
978
988
  });
979
989
  }
980
990
 
981
- /** Publish only a fully settled, locally repaired session with two rooted log heads. */
982
- public async publishSettledSessionClean(state: IStorageState, sessionId: string): Promise<void> {
991
+ /** Reads an exact-head auxiliary summary without acquiring a session runtime. */
992
+ public readGuardedCleanSessionAuxiliarySummary(
993
+ state: IStorageState,
994
+ sessionId: string,
995
+ ): Promise<IFlexSessionAuxiliarySummary | undefined> {
983
996
  const local = this.stores.scopes.sessionLocal;
984
- if (!state.sessionLocal || state.lifecycle !== 'active' || !this.cleanRecoveryEnabled(state.storageKey)
985
- || !local?.publishSessionClean || !this.stores.projections.loadHead
986
- || !this.stores.agentEvents.loadHead || !state.recoverySessionIds.has(sessionId)) return;
987
- const gate = this.recoveryProducerGate(state, sessionId);
988
- if (!gate.canPublish) return;
997
+ const projectionStore = this.stores.projections;
998
+ if (!state.sessionLocal || !this.cleanRecoveryEnabled(state.storageKey)
999
+ || !local?.readCleanSessionProof || !projectionStore.loadHead
1000
+ || !projectionStore.loadAuxiliarySummaryHead || !this.stores.agentEvents.loadHead) {
1001
+ return Promise.resolve(undefined);
1002
+ }
1003
+ return this.withRecoveryPublication(state, sessionId, async () => {
1004
+ const current = state.catalogue.get(sessionId);
1005
+ if (!current || state.tombstones.has(sessionId) || state.initializingSessions.has(sessionId)) return undefined;
1006
+ const proof = await local.readCleanSessionProof!(state.storageKey, sessionId);
1007
+ if (!proof) {
1008
+ if (!state.recoverySessionIds.has(sessionId)) {
1009
+ const catalogue = await local.loadCatalogue(state.storageKey);
1010
+ if (!catalogue.qualified) throw new FlexHarnessStoreFormatError('Session recovery proof became unqualified.');
1011
+ await this.markRecoveryRequired(state, sessionId);
1012
+ }
1013
+ return undefined;
1014
+ }
1015
+ if (flexSessionDigest(proof.session) !== flexSessionDigest(current)) {
1016
+ await this.markRecoveryRequired(state, sessionId);
1017
+ return undefined;
1018
+ }
1019
+ const matches = (actual: { incarnationId?: string; revision: number; contentRoot: string } | undefined,
1020
+ expected: { incarnationId: string; revision: number; contentRoot: string }) =>
1021
+ actual?.incarnationId === expected.incarnationId
1022
+ && actual.revision === expected.revision
1023
+ && actual.contentRoot === expected.contentRoot;
1024
+ const [projection, agentEvents] = await Promise.all([
1025
+ projectionStore.loadHead!(state.storageKey, sessionId),
1026
+ this.stores.agentEvents.loadHead!(state.storageKey, sessionId),
1027
+ ]);
1028
+ if (!matches(projection, proof.clean.projection) || !matches(agentEvents, proof.clean.agentEvents)) {
1029
+ await this.markRecoveryRequired(state, sessionId);
1030
+ return undefined;
1031
+ }
1032
+ const read = await projectionStore.loadAuxiliarySummaryHead!(
1033
+ state.storageKey, sessionId, this.reversionPolicy === 'workspace-required',
1034
+ );
1035
+ if (!read || !matches(read.projection, proof.clean.projection)) return undefined;
1036
+ // A clean sidecar and both exact heads must still match after the summary read settles.
1037
+ const [settledProof, settledProjection, settledAgentEvents] = await Promise.all([
1038
+ local.readCleanSessionProof!(state.storageKey, sessionId),
1039
+ projectionStore.loadHead!(state.storageKey, sessionId),
1040
+ this.stores.agentEvents.loadHead!(state.storageKey, sessionId),
1041
+ ]);
1042
+ if (!settledProof || flexSessionDigest(settledProof.session) !== flexSessionDigest(current)
1043
+ || !matches(settledProof.clean.projection, proof.clean.projection)
1044
+ || !matches(settledProof.clean.agentEvents, proof.clean.agentEvents)
1045
+ || !matches(settledProjection, proof.clean.projection)
1046
+ || !matches(settledAgentEvents, proof.clean.agentEvents)) return undefined;
1047
+ const latest = state.catalogue.get(sessionId);
1048
+ if (!latest || state.tombstones.has(sessionId)
1049
+ || flexSessionDigest(latest) !== flexSessionDigest(current)) return undefined;
1050
+ return assertFlexSessionAuxiliarySummary(read.summary);
1051
+ });
1052
+ }
1053
+
1054
+ /** Uses a proved bounded summary or coalesces the target's ordinary hydration. */
1055
+ public async readSessionAuxiliarySource(
1056
+ scopeId: string,
1057
+ sessionId: string,
1058
+ signal?: AbortSignal,
1059
+ ): Promise<{ summary: IFlexSessionAuxiliarySummary; stored?: never }
1060
+ | { summary?: never; stored: IStoredSessionState }> {
1061
+ const throwIfAborted = () => {
1062
+ if (signal?.aborted) throw signal.reason ?? new FlexHarnessAbortError('The session read was aborted.');
1063
+ };
1064
+ throwIfAborted();
1065
+ let onAbort: (() => void) | undefined;
1066
+ const aborted = signal === undefined ? undefined : new Promise<never>((_resolve, reject) => {
1067
+ onAbort = () => reject(signal.reason ?? new FlexHarnessAbortError('The session read was aborted.'));
1068
+ signal.addEventListener('abort', onAbort, { once: true });
1069
+ });
1070
+ const wait = <TValue>(pending: Promise<TValue>): Promise<TValue> =>
1071
+ aborted ? Promise.race([pending, aborted]) : pending;
989
1072
  try {
1073
+ const { state, scope } = await wait(this.resolveState(
1074
+ scopeId, this.cleanRecoveryConfigured ? undefined : sessionId,
1075
+ ));
1076
+ throwIfAborted();
1077
+ await wait(this.sessionReadBarrier(state, sessionId));
1078
+ throwIfAborted();
1079
+ this.assertStateAcceptingWork(state);
1080
+ if (state.initializingSessions.has(sessionId)) this.requireSession(state, sessionId);
1081
+ let hydratedForSummary = false;
1082
+ if (!state.sessions.has(sessionId)) {
1083
+ const summary = await wait(this.readGuardedCleanSessionAuxiliarySummary(state, sessionId));
1084
+ throwIfAborted();
1085
+ if (summary) return { summary };
1086
+ await wait(this.hydrateSession(state, sessionId, scopeId, scope.scope));
1087
+ throwIfAborted();
1088
+ hydratedForSummary = true;
1089
+ }
1090
+ const stored = this.requireSession(state, sessionId);
1091
+ await wait(stored.projectionQueue);
1092
+ throwIfAborted();
1093
+ this.assertStateAcceptingWork(state);
1094
+ if (hydratedForSummary) {
1095
+ await wait(this.populateSettledAuxiliarySummary(state, sessionId));
1096
+ throwIfAborted();
1097
+ }
1098
+ return { stored };
1099
+ } finally {
1100
+ if (signal && onAbort) signal.removeEventListener('abort', onAbort);
1101
+ }
1102
+ }
1103
+
1104
+ /** Backfills a missing summary after exact hydration of an already clean session. */
1105
+ private async populateSettledAuxiliarySummary(state: IStorageState, sessionId: string): Promise<void> {
1106
+ const local = this.stores.scopes.sessionLocal;
1107
+ const projections = this.stores.projections;
1108
+ if (!state.sessionLocal || !this.cleanRecoveryEnabled(state.storageKey)
1109
+ || !local?.readCleanSessionProof || !projections.loadHead
1110
+ || !projections.loadAuxiliarySummaryHead || !projections.saveAuxiliarySummaryHead
1111
+ || !this.stores.agentEvents.loadHead) return;
1112
+ if (!this.recoveryProducerGate(state, sessionId).canPublish) return;
990
1113
  await this.withRecoveryPublication(state, sessionId, async () => {
991
1114
  const stored = state.sessions.get(sessionId);
992
- if (!stored || state.lifecycle !== 'active' || stored.recovering
993
- || stored.projectionReconciliationRequired || stored.metricsFailure !== undefined
994
- || state.initializingSessions.has(sessionId)
1115
+ if (!stored || stored.recovering || stored.projectionReconciliationRequired
1116
+ || stored.metricsFailure !== undefined || state.initializingSessions.has(sessionId)
995
1117
  || state.tombstones.has(sessionId) || state.activeRuns.has(sessionId)
996
1118
  || stored.outstandingPromptsById.size > 0 || stored.pendingReversion !== undefined
997
1119
  || stored.pendingReversionReleases.length > 0 || stored.stagedTerminals.length > 0
@@ -999,27 +1121,107 @@ export class FlexHarnessCore<TScope> {
999
1121
  || stored.metrics.pendingCompactionId !== undefined
1000
1122
  || [...state.pendingPermissions.values()].some((permission) =>
1001
1123
  !permission.settled && permission.request.sessionId === sessionId)) return;
1002
- const catalogue = await local.loadCatalogue(state.storageKey);
1003
- const session = catalogue.snapshot?.sessions.find((entry) => entry.sessionId === sessionId);
1004
- if (!catalogue.qualified || catalogue.recoveryRevision === undefined || !session
1005
- || flexSessionDigest(session) !== flexSessionDigest(stored.session)) return;
1006
- const [projection, agentEvents] = await Promise.all([
1007
- this.stores.projections.loadHead!(state.storageKey, sessionId),
1124
+ const proof = await local.readCleanSessionProof!(state.storageKey, sessionId);
1125
+ if (!proof || flexSessionDigest(proof.session) !== flexSessionDigest(stored.session)) return;
1126
+ const [projection, agentEvents, existing] = await Promise.all([
1127
+ projections.loadHead!(state.storageKey, sessionId),
1008
1128
  this.stores.agentEvents.loadHead!(state.storageKey, sessionId),
1129
+ projections.loadAuxiliarySummaryHead!(
1130
+ state.storageKey, sessionId, this.reversionPolicy === 'workspace-required',
1131
+ ),
1009
1132
  ]);
1010
- if (!projection?.incarnationId || !agentEvents?.incarnationId) return;
1011
- await local.publishSessionClean!(state.storageKey, catalogue.recoveryRevision, {
1012
- sessionId,
1013
- state: 'clean',
1014
- ...requireSessionGeneration(session),
1015
- sessionDigest: flexSessionDigest(session),
1016
- projection: { incarnationId: projection.incarnationId, revision: projection.revision,
1017
- contentRoot: projection.contentRoot },
1018
- agentEvents: { incarnationId: agentEvents.incarnationId, revision: agentEvents.revision,
1019
- contentRoot: agentEvents.contentRoot },
1020
- });
1021
- state.recoverySessionIds.delete(sessionId);
1133
+ const matches = (actual: { incarnationId?: string; revision: number; contentRoot: string } | undefined,
1134
+ expected: { incarnationId: string; revision: number; contentRoot: string }) =>
1135
+ actual?.incarnationId === expected.incarnationId
1136
+ && actual.revision === expected.revision
1137
+ && actual.contentRoot === expected.contentRoot;
1138
+ if (!matches(projection, proof.clean.projection)
1139
+ || !matches(agentEvents, proof.clean.agentEvents)
1140
+ || (existing && matches(existing.projection, proof.clean.projection))) return;
1141
+ const presentation = deriveReversionPresentation(stored.reversionSegments, this.reversionPolicy);
1142
+ if (!presentation) throw new FlexHarnessStoreFormatError('Settled reversion presentation exceeds its bounds.');
1143
+ await projections.saveAuxiliarySummaryHead!(
1144
+ state.storageKey, sessionId, projection!, this.reversionPolicy === 'workspace-required',
1145
+ { reversionPresentation: presentation, sessionMetrics: sessionMetricsView(stored.metrics) },
1146
+ );
1022
1147
  });
1148
+ }
1149
+
1150
+ /** Settle a fully repaired session after its producers and pending effects have drained. */
1151
+ public async settleQuiescentSessionRecovery(state: IStorageState, sessionId: string): Promise<void> {
1152
+ const local = this.stores.scopes.sessionLocal;
1153
+ if (!state.sessionLocal || state.qualifyingLegacy || state.lifecycle !== 'active'
1154
+ || !local || !state.recoverySessionIds.has(sessionId)) return;
1155
+ const cleanRead = this.cleanRecoveryEnabled(state.storageKey);
1156
+ if (cleanRead && (!local.publishSessionClean || !this.stores.projections.loadHead
1157
+ || !this.stores.agentEvents.loadHead)) return;
1158
+ const gate = this.recoveryProducerGate(state, sessionId);
1159
+ if (!gate.canPublish) return;
1160
+ try {
1161
+ await gate.publish(async () => {
1162
+ const stored = state.sessions.get(sessionId);
1163
+ if (!stored || state.lifecycle !== 'active' || state.qualifyingLegacy || stored.recovering
1164
+ || !state.recoverySessionIds.has(sessionId)
1165
+ || stored.projectionReconciliationRequired || stored.metricsFailure !== undefined
1166
+ || state.initializingSessions.has(sessionId)
1167
+ || state.tombstones.has(sessionId) || state.activeRuns.has(sessionId)
1168
+ || stored.outstandingPromptsById.size > 0 || stored.pendingReversion !== undefined
1169
+ || stored.pendingReversionReleases.length > 0 || stored.stagedTerminals.length > 0
1170
+ || stored.metrics.pendingGenerationId !== undefined
1171
+ || stored.metrics.pendingCompactionId !== undefined
1172
+ || [...state.pendingPermissions.values()].some((permission) =>
1173
+ !permission.settled && permission.request.sessionId === sessionId)) return;
1174
+ const catalogue = await local.loadCatalogue(state.storageKey);
1175
+ const session = catalogue.snapshot?.sessions.find((entry) => entry.sessionId === sessionId);
1176
+ if (!catalogue.qualified || !session
1177
+ || flexSessionDigest(session) !== flexSessionDigest(stored.session)) return;
1178
+ if (!cleanRead) {
1179
+ // Compatibility has recovered this runtime. Schema 2 still requires full recovery
1180
+ // in the next runtime, since this mode does not publish authenticated clean proof.
1181
+ if (catalogue.recoverySchemaVersion !== 2) {
1182
+ await local.setRecoveryRequired(state.storageKey, sessionId, false);
1183
+ }
1184
+ state.recoverySessionIds.delete(sessionId);
1185
+ state.recoveryMarks.delete(sessionId);
1186
+ return;
1187
+ }
1188
+ if (catalogue.recoveryRevision === undefined) return;
1189
+ const [projection, agentEvents] = await Promise.all([
1190
+ this.stores.projections.loadHead!(state.storageKey, sessionId),
1191
+ this.stores.agentEvents.loadHead!(state.storageKey, sessionId),
1192
+ ]);
1193
+ if (!projection?.incarnationId || !agentEvents?.incarnationId) return;
1194
+ if (this.stores.projections.saveAuxiliarySummaryHead) {
1195
+ const presentation = deriveReversionPresentation(stored.reversionSegments, this.reversionPolicy);
1196
+ if (!presentation) throw new FlexHarnessStoreFormatError('Settled reversion presentation exceeds its bounds.');
1197
+ await this.stores.projections.saveAuxiliarySummaryHead(
1198
+ state.storageKey, sessionId, projection, this.reversionPolicy === 'workspace-required',
1199
+ { reversionPresentation: presentation, sessionMetrics: sessionMetricsView(stored.metrics) },
1200
+ );
1201
+ const [currentProjection, currentAgentEvents] = await Promise.all([
1202
+ this.stores.projections.loadHead!(state.storageKey, sessionId),
1203
+ this.stores.agentEvents.loadHead!(state.storageKey, sessionId),
1204
+ ]);
1205
+ if (currentProjection?.incarnationId !== projection.incarnationId
1206
+ || currentProjection.revision !== projection.revision
1207
+ || currentProjection.contentRoot !== projection.contentRoot
1208
+ || currentAgentEvents?.incarnationId !== agentEvents.incarnationId
1209
+ || currentAgentEvents.revision !== agentEvents.revision
1210
+ || currentAgentEvents.contentRoot !== agentEvents.contentRoot) return;
1211
+ }
1212
+ await local.publishSessionClean!(state.storageKey, catalogue.recoveryRevision, {
1213
+ sessionId,
1214
+ state: 'clean',
1215
+ ...requireSessionGeneration(session),
1216
+ sessionDigest: flexSessionDigest(session),
1217
+ projection: { incarnationId: projection.incarnationId, revision: projection.revision,
1218
+ contentRoot: projection.contentRoot },
1219
+ agentEvents: { incarnationId: agentEvents.incarnationId, revision: agentEvents.revision,
1220
+ contentRoot: agentEvents.contentRoot },
1221
+ });
1222
+ state.recoverySessionIds.delete(sessionId);
1223
+ state.recoveryMarks.delete(sessionId);
1224
+ });
1023
1225
  } catch (error) {
1024
1226
  // Another session can advance the namespace sidecar between our read and exact CAS.
1025
1227
  // This session remains durably dirty and another settled read can publish it.
@@ -1049,8 +1251,8 @@ export class FlexHarnessCore<TScope> {
1049
1251
  else if (!registerOnly) state.recoverySessionIds.delete(sessionId);
1050
1252
  return;
1051
1253
  }
1052
- // Clearing needs the complete, quiescent recovery frontier. A local lack of pending work is
1053
- // not proof that the event, job, permission and metadata writers have all settled.
1254
+ // The quiescent settlement path clears marks after the event, job, permission and metadata
1255
+ // writers have settled.
1054
1256
  if (!required) return;
1055
1257
  await this.markRecoveryRequired(state, sessionId);
1056
1258
  }
@@ -1065,6 +1267,7 @@ export class FlexHarnessCore<TScope> {
1065
1267
  if (!state.sessionLocal || state.lifecycle !== 'active') return;
1066
1268
  try {
1067
1269
  await this.updateRecoveryObligation(state, stored);
1270
+ await this.settleQuiescentSessionRecovery(state, stored.session.sessionId);
1068
1271
  } catch (error) {
1069
1272
  this.lifecycle.deferNamespaceDrain(state, error);
1070
1273
  }
@@ -722,6 +722,9 @@ export class FlexHarnessLifecycle<TScope> {
722
722
  this.core.appendUnexpectedErrors(errors, error);
723
723
  }
724
724
  }
725
+ // Retirement has closed publication admission. Join the sidecar write before releasing
726
+ // the storage key so a new runtime cannot race a late recovery update.
727
+ await Promise.all([...state.recoveryProducerGates.values()].map((gate) => gate.waitForPublication()));
725
728
  errors.push(...state.fenceAdditionalErrors.splice(0));
726
729
  if (errors.length > 0) throw combineErrors(errors);
727
730
  state.lifecycle = 'retired';
@@ -4,6 +4,7 @@ import {
4
4
  FlexHarnessSessionBusyError,
5
5
  FlexHarnessSlashCommandReentryError,
6
6
  FlexHarnessSlashCommandUnavailableError,
7
+ FlexHarnessStoreFormatError,
7
8
  FlexHarnessValidationError,
8
9
  } from './errors.js';
9
10
  import {
@@ -11,7 +12,6 @@ import {
11
12
  FLEX_REVERSION_REASON_CODE_MAX_BYTES,
12
13
  FLEX_REVERSION_REFERENCE_MAX_BYTES,
13
14
  FLEX_REVERSION_WORKSPACE_ID_MAX_BYTES,
14
- FLEX_SESSION_REVERSION_BARRIER_CAUSES,
15
15
  FLEX_REVERSION_WORKSPACE_LABEL_MAX_BYTES,
16
16
  type IFlexAgentContextInvocation,
17
17
  type IFlexAffectedWorkspace,
@@ -20,18 +20,18 @@ import {
20
20
  type IFlexPendingReversionRelease,
21
21
  type IFlexRedoSessionResult,
22
22
  type IFlexSessionGeneration,
23
- type IFlexSessionReversionGroup,
24
23
  type IFlexSessionReversionInfo,
24
+ type IFlexSessionReversionPresentation,
25
25
  type IFlexSessionTombstone,
26
26
  type IFlexUndoSessionResult,
27
27
  type TFlexProjectionSnapshot,
28
- type TFlexSessionReversionBarrierCause,
29
28
  type TFlexTurnReversionFinalizedOutcome,
30
29
  type TJsonValue,
31
30
  } from './interfaces.js';
32
31
  import { cloneSerializable, normalizeJsonValue } from './utils.json.js';
33
32
  import { createWholeProjectionChange } from './utils.projectionchange.js';
34
33
  import { publicSnapshot } from './utils.transfer.js';
34
+ import { deriveReversionGroups, deriveReversionPresentation, presentReversionGroups } from './utils.reversionpresentation.js';
35
35
  import type {
36
36
  TCanonicalOutcome,
37
37
  IStoredSessionState,
@@ -52,6 +52,20 @@ import type { FlexHarnessCore } from './classes.flexharness.core.js';
52
52
  export class FlexHarnessReversions<TScope> {
53
53
  constructor(private readonly core: FlexHarnessCore<TScope>) {}
54
54
 
55
+ public async getSessionReversionPresentation(
56
+ scopeId: string,
57
+ sessionId: string,
58
+ signal?: AbortSignal,
59
+ ): Promise<IFlexSessionReversionPresentation> {
60
+ const source = await this.core.readSessionAuxiliarySource(scopeId, sessionId, signal);
61
+ if (source.summary) return publicSnapshot(source.summary.reversionPresentation);
62
+ const presentation = deriveReversionPresentation(
63
+ source.stored.reversionSegments, this.core.reversionPolicy,
64
+ );
65
+ if (!presentation) throw new FlexHarnessStoreFormatError('Session reversion presentation exceeds its bounds.');
66
+ return publicSnapshot(presentation);
67
+ }
68
+
55
69
  public async getSessionReversionInfo(
56
70
  scopeId: string,
57
71
  sessionId: string,
@@ -77,15 +91,7 @@ export class FlexHarnessReversions<TScope> {
77
91
  return publicSnapshot({
78
92
  undoAvailable: isAvailable(undo),
79
93
  redoAvailable: isAvailable(redo),
80
- groups: groups.map((group, index): IFlexSessionReversionGroup => ({
81
- runId: group.target.runId,
82
- kind: group.kind,
83
- visibility: index < stored.revertCursor ? 'visible' : 'hidden',
84
- affectedWorkspaces: cloneSerializable(group.affectedWorkspaces),
85
- affectedWorkspacesTruncated: group.affectedWorkspacesTruncated,
86
- barrierCauses: [...group.barrierCauses],
87
- reasonCodes: [...group.reasonCodes],
88
- })),
94
+ groups: presentReversionGroups(groups, stored.revertCursor),
89
95
  });
90
96
  }
91
97
 
@@ -135,63 +141,7 @@ export class FlexHarnessReversions<TScope> {
135
141
  }
136
142
 
137
143
  public reversionGroups(stored: IStoredSessionState): IReversionGroup[] {
138
- const groups: IReversionGroup[] = [];
139
- let leading: IFlexReversionSegment[] = [];
140
- for (const segment of stored.reversionSegments) {
141
- if (segment.status === 'completed') {
142
- const segments = groups.length === 0 ? [...leading, segment] : [segment];
143
- leading = [];
144
- groups.push({
145
- target: segment,
146
- segments,
147
- kind: 'candidate',
148
- affectedWorkspaces: [],
149
- affectedWorkspacesTruncated: false,
150
- barrierCauses: [],
151
- reasonCodes: [],
152
- });
153
- } else if (groups.length > 0) {
154
- groups[groups.length - 1].segments.push(segment);
155
- } else {
156
- leading.push(segment);
157
- }
158
- }
159
- for (const group of groups) {
160
- const affected = new Map<string, IFlexAffectedWorkspace>();
161
- for (const workspace of group.segments.flatMap((segment) =>
162
- segment.affectedWorkspaces ?? [])) {
163
- if (affected.has(workspace.id)) continue;
164
- if (affected.size < FLEX_REVERSION_MAX_AFFECTED_WORKSPACES) {
165
- affected.set(workspace.id, cloneSerializable(workspace));
166
- } else {
167
- group.affectedWorkspacesTruncated = true;
168
- }
169
- }
170
- group.affectedWorkspaces = [...affected.values()];
171
- group.reasonCodes = [...new Set(group.segments.flatMap((segment) => (
172
- segment.disposition === 'nonrevertible' && segment.reasonCode !== undefined
173
- ? [segment.reasonCode]
174
- : []
175
- )))];
176
- if (this.core.reversionPolicy === 'transcript-optional') continue;
177
- const causes = new Set<TFlexSessionReversionBarrierCause>();
178
- for (const segment of group.segments) {
179
- if (segment.status === 'capturing' || segment.disposition === 'pending') causes.add('pending');
180
- if (segment.disposition === 'nonrevertible') causes.add('nonrevertible');
181
- if (segment.protocolVersion === 1 && segment.provenance === 'transcript') {
182
- causes.add('transcript-only');
183
- }
184
- }
185
- if (causes.size > 0) {
186
- group.kind = 'barrier';
187
- group.barrierCauses = FLEX_SESSION_REVERSION_BARRIER_CAUSES.filter((cause) => causes.has(cause));
188
- } else if (group.segments.some((segment) => segment.disposition === 'revertible')) {
189
- group.kind = 'candidate';
190
- } else {
191
- group.kind = 'no-change';
192
- }
193
- }
194
- return groups;
144
+ return deriveReversionGroups(stored.reversionSegments, this.core.reversionPolicy);
195
145
  }
196
146
 
197
147
  private async requireReversionIdle(
@@ -289,6 +289,8 @@ export class FlexHarnessSessions<TScope> {
289
289
  resolved.state.initializingSessions.delete(sessionId);
290
290
  completeInitialization();
291
291
  }
292
+ const stored = resolved.state.sessions.get(sessionId);
293
+ if (stored) await this.core.settleRecoveryObligation(resolved.state, stored);
292
294
  const result = publicSnapshot(metadata);
293
295
  this.core.emitEvent(scopeId, metadata, { type: 'session.created', session: result });
294
296
  return result;
@@ -330,7 +332,7 @@ export class FlexHarnessSessions<TScope> {
330
332
  await (aborted ? Promise.race([hydration, aborted]) : hydration);
331
333
  throwIfAborted();
332
334
  }
333
- await this.core.publishSettledSessionClean(state, sessionId);
335
+ await this.core.settleQuiescentSessionRecovery(state, sessionId);
334
336
  return publicSnapshot(this.core.requireSession(state, sessionId).session);
335
337
  } finally {
336
338
  if (signal && onAbort) signal.removeEventListener('abort', onAbort);
@@ -338,10 +340,9 @@ export class FlexHarnessSessions<TScope> {
338
340
  }
339
341
 
340
342
  public async getSessionMetrics(scopeId: string, sessionId: string): Promise<IFlexSessionMetrics> {
341
- const { state } = await this.core.resolveState(scopeId, sessionId);
342
- const stored = this.core.requireSession(state, sessionId);
343
- await stored.projectionQueue;
344
- this.core.assertStateAcceptingWork(state);
343
+ const source = await this.core.readSessionAuxiliarySource(scopeId, sessionId);
344
+ if (source.summary) return publicSnapshot(source.summary.sessionMetrics);
345
+ const stored = source.stored;
345
346
  if (stored.metricsFailure !== undefined) throw stored.metricsFailure;
346
347
  return publicSnapshot(sessionMetricsView(stored.metrics));
347
348
  }
@@ -41,6 +41,7 @@ import type {
41
41
  IFlexSessionImportHandle,
42
42
  IFlexSessionImportProgress,
43
43
  IFlexSessionReversionInfo,
44
+ IFlexSessionReversionPresentation,
44
45
  IFlexSlashCommandDescriptor,
45
46
  IFlexSlashCommandExecutionOptions,
46
47
  IFlexUncertainToolExecution,
@@ -155,6 +156,15 @@ export class FlexHarness<TScope = unknown> {
155
156
  return this.core.reversions.getSessionReversionInfo(scopeId, sessionId);
156
157
  }
157
158
 
159
+ /** Bounded Git reversion summary, read from a clean projection head when available. */
160
+ public getSessionReversionPresentation(
161
+ scopeId: string,
162
+ sessionId: string,
163
+ signal?: AbortSignal,
164
+ ): Promise<IFlexSessionReversionPresentation> {
165
+ return this.core.reversions.getSessionReversionPresentation(scopeId, sessionId, signal);
166
+ }
167
+
158
168
  public updateSession(
159
169
  scopeId: string,
160
170
  sessionId: string,
@@ -25,6 +25,10 @@ export class FlexRecoveryProducerGate {
25
25
  && this.runs === 0 && !this.runFailed;
26
26
  }
27
27
 
28
+ public async waitForPublication(): Promise<void> {
29
+ await this.publication;
30
+ }
31
+
28
32
  /** Generation execution may continue tool effects after prompt promotion has returned. */
29
33
  public admitRun(completion: Promise<unknown>): void {
30
34
  if (!this.context.getStore()?.leases) {
package/ts/index.ts CHANGED
@@ -47,6 +47,10 @@ export {
47
47
  type TFlexProjectionIndexNode,
48
48
  } from './utils.projectionindex.js';
49
49
  export { assertFlexToolJobSnapshot } from './utils.storecodecs.js';
50
+ export {
51
+ assertFlexSessionAuxiliarySummary,
52
+ assertFlexSessionReversionPresentation,
53
+ } from './utils.reversionpresentation.js';
50
54
  export {
51
55
  FLEX_SLASH_COMMAND_MAX_INPUT_BYTES,
52
56
  isReservedSlashCommandName,
package/ts/interfaces.ts CHANGED
@@ -1878,6 +1878,23 @@ export interface IFlexProjectionStore {
1878
1878
  load(storageKey: string, sessionId: string): Promise<TFlexProjectionSnapshot | undefined>;
1879
1879
  /** Optional bounded content commitment; undefined requires a full load. */
1880
1880
  loadHead?(storageKey: string, sessionId: string): Promise<IFlexProjectionHead | undefined>;
1881
+ /** Optional bounded summary bound to the exact rooted projection head and grouping-policy flag. */
1882
+ loadAuxiliarySummaryHead?(
1883
+ storageKey: string,
1884
+ sessionId: string,
1885
+ workspaceRequired: boolean,
1886
+ ): Promise<{
1887
+ projection: IFlexProjectionHead;
1888
+ summary: IFlexSessionAuxiliarySummary;
1889
+ } | undefined>;
1890
+ /** Stores a summary bound to this exact head; one current slot per session and flag is valid. */
1891
+ saveAuxiliarySummaryHead?(
1892
+ storageKey: string,
1893
+ sessionId: string,
1894
+ expectedProjection: IFlexProjectionHead,
1895
+ workspaceRequired: boolean,
1896
+ summary: IFlexSessionAuxiliarySummary,
1897
+ ): Promise<void>;
1881
1898
  /**
1882
1899
  * Applies `change` to the stored projection while its revision is `expectedRevision`; the
1883
1900
  * change's revision is the next one.
@@ -2147,6 +2164,21 @@ export interface IFlexSessionReversionInfo {
2147
2164
  readonly groups: readonly IFlexSessionReversionGroup[];
2148
2165
  }
2149
2166
 
2167
+ /** Bounded, group-ordered summary for a session's reversion presentation. */
2168
+ export interface IFlexSessionReversionPresentation {
2169
+ readonly affectedWorkspaces: readonly IFlexAffectedWorkspace[];
2170
+ readonly affectedWorkspacesTruncated: boolean;
2171
+ readonly barrierCauses: readonly TFlexSessionReversionBarrierCause[];
2172
+ readonly reasonCodes: readonly string[];
2173
+ readonly reasonCodesTruncated: boolean;
2174
+ }
2175
+
2176
+ /** A settled session's bounded auxiliary view, tied to one exact committed projection head. */
2177
+ export interface IFlexSessionAuxiliarySummary {
2178
+ readonly reversionPresentation: IFlexSessionReversionPresentation;
2179
+ readonly sessionMetrics: IFlexSessionMetrics;
2180
+ }
2181
+
2150
2182
  export interface IFlexUndoSessionResult {
2151
2183
  revertedRunId: string;
2152
2184
  }