@modelprofile.com/flexharness 18.9.0 → 18.9.1

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.
@@ -516,7 +516,7 @@ export class FlexHarnessCore<TScope> {
516
516
  catalogue: new Map(liveScopeSessions(snapshot).map((session) => [session.sessionId, session])),
517
517
  sessionLocal: local !== undefined,
518
518
  qualifyingLegacy,
519
- recoverySessionIds: new Set(local && local.recoverySchemaVersion !== 1
519
+ recoverySessionIds: new Set(local && local.recoverySchemaVersion === 2
520
520
  && !this.cleanRecoveryEnabled(storageKey)
521
521
  ? [...new Set([...local.recoverySessionIds,
522
522
  ...(local.snapshot?.sessions.map((session) => session.sessionId) ?? [])])]
@@ -557,6 +557,10 @@ export class FlexHarnessCore<TScope> {
557
557
  for (const metadata of liveScopeSessions(snapshot).filter((session) =>
558
558
  !state.sessionLocal || qualifyingLegacy || state.recoverySessionIds.has(session.sessionId))) {
559
559
  compactorLifecycleController.signal.throwIfAborted();
560
+ if (local?.recoverySchemaVersion === 2 && !this.cleanRecoveryEnabled(storageKey)) {
561
+ // A compatibility open always invalidates inherited clean proof before full repair.
562
+ await this.markRecoveryRequired(state, metadata.sessionId);
563
+ }
560
564
  const stored = await this.loadSessionRuntime(
561
565
  state,
562
566
  metadata,
@@ -655,7 +659,7 @@ export class FlexHarnessCore<TScope> {
655
659
  for (const loaded of loadedSessions) {
656
660
  loaded.recovering = false;
657
661
  await this.updateRecoveryObligation(state, loaded);
658
- await this.publishSettledSessionClean(state, loaded.session.sessionId);
662
+ await this.settleQuiescentSessionRecovery(state, loaded.session.sessionId);
659
663
  }
660
664
  }
661
665
  return state;
@@ -786,7 +790,7 @@ export class FlexHarnessCore<TScope> {
786
790
  else state.catalogue.set(sessionId, stored.session);
787
791
  stored.recovering = false;
788
792
  await this.updateRecoveryObligation(state, stored);
789
- await this.publishSettledSessionClean(state, sessionId);
793
+ await this.settleQuiescentSessionRecovery(state, sessionId);
790
794
  this.assertStateAcceptingWork(state);
791
795
  return stored;
792
796
  } catch (error) {
@@ -827,6 +831,8 @@ export class FlexHarnessCore<TScope> {
827
831
  if (state.sessionLoads.has(id)) { await state.sessionLoads.get(id); continue; }
828
832
  const stored = state.sessions.get(id);
829
833
  if (!stored) { await this.hydrateSession(state, id, scopeId, scope); continue; }
834
+ await this.settleQuiescentSessionRecovery(state, id);
835
+ if (!state.recoverySessionIds.has(id)) continue;
830
836
  stored.recovering = true;
831
837
  await this.repairLoadedSession(state.storageKey, stored, state, scopeId, scope,
832
838
  new FlexTimeSlicer(state.compactorLifecycleController.signal));
@@ -835,6 +841,7 @@ export class FlexHarnessCore<TScope> {
835
841
  await this.mutateSessionScope(state, id, () => undefined);
836
842
  stored.recovering = false;
837
843
  await this.updateRecoveryObligation(state, stored);
844
+ await this.settleQuiescentSessionRecovery(state, id);
838
845
  }
839
846
  for (const root of roots) await this.deletion.finishTombstoneCleanup(state, root, scopeId, { scopeId, scope });
840
847
  })().finally(() => { if (state.sharedRecovery === recovery) delete state.sharedRecovery; });
@@ -879,10 +886,10 @@ export class FlexHarnessCore<TScope> {
879
886
  private recoveryProducerGate(state: IStorageState, sessionId: string): FlexRecoveryProducerGate {
880
887
  let gate = state.recoveryProducerGates.get(sessionId);
881
888
  if (!gate) {
882
- gate = new FlexRecoveryProducerGate(this.cleanRecoveryEnabled(state.storageKey) ? () => {
883
- void this.publishSettledSessionClean(state, sessionId)
889
+ gate = new FlexRecoveryProducerGate(() => {
890
+ void this.settleQuiescentSessionRecovery(state, sessionId)
884
891
  .catch((error: unknown) => this.lifecycle.deferNamespaceDrain(state, error));
885
- } : undefined);
892
+ });
886
893
  state.recoveryProducerGates.set(sessionId, gate);
887
894
  }
888
895
  return gate;
@@ -978,48 +985,63 @@ export class FlexHarnessCore<TScope> {
978
985
  });
979
986
  }
980
987
 
981
- /** Publish only a fully settled, locally repaired session with two rooted log heads. */
982
- public async publishSettledSessionClean(state: IStorageState, sessionId: string): Promise<void> {
988
+ /** Settle a fully repaired session after its producers and pending effects have drained. */
989
+ public async settleQuiescentSessionRecovery(state: IStorageState, sessionId: string): Promise<void> {
983
990
  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;
991
+ if (!state.sessionLocal || state.qualifyingLegacy || state.lifecycle !== 'active'
992
+ || !local || !state.recoverySessionIds.has(sessionId)) return;
993
+ const cleanRead = this.cleanRecoveryEnabled(state.storageKey);
994
+ if (cleanRead && (!local.publishSessionClean || !this.stores.projections.loadHead
995
+ || !this.stores.agentEvents.loadHead)) return;
987
996
  const gate = this.recoveryProducerGate(state, sessionId);
988
997
  if (!gate.canPublish) return;
989
998
  try {
990
- await this.withRecoveryPublication(state, sessionId, async () => {
991
- 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)
995
- || state.tombstones.has(sessionId) || state.activeRuns.has(sessionId)
996
- || stored.outstandingPromptsById.size > 0 || stored.pendingReversion !== undefined
997
- || stored.pendingReversionReleases.length > 0 || stored.stagedTerminals.length > 0
998
- || stored.metrics.pendingGenerationId !== undefined
999
- || stored.metrics.pendingCompactionId !== undefined
1000
- || [...state.pendingPermissions.values()].some((permission) =>
1001
- !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),
1008
- this.stores.agentEvents.loadHead!(state.storageKey, sessionId),
1009
- ]);
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 },
999
+ await gate.publish(async () => {
1000
+ const stored = state.sessions.get(sessionId);
1001
+ if (!stored || state.lifecycle !== 'active' || state.qualifyingLegacy || stored.recovering
1002
+ || !state.recoverySessionIds.has(sessionId)
1003
+ || stored.projectionReconciliationRequired || stored.metricsFailure !== undefined
1004
+ || state.initializingSessions.has(sessionId)
1005
+ || state.tombstones.has(sessionId) || state.activeRuns.has(sessionId)
1006
+ || stored.outstandingPromptsById.size > 0 || stored.pendingReversion !== undefined
1007
+ || stored.pendingReversionReleases.length > 0 || stored.stagedTerminals.length > 0
1008
+ || stored.metrics.pendingGenerationId !== undefined
1009
+ || stored.metrics.pendingCompactionId !== undefined
1010
+ || [...state.pendingPermissions.values()].some((permission) =>
1011
+ !permission.settled && permission.request.sessionId === sessionId)) return;
1012
+ const catalogue = await local.loadCatalogue(state.storageKey);
1013
+ const session = catalogue.snapshot?.sessions.find((entry) => entry.sessionId === sessionId);
1014
+ if (!catalogue.qualified || !session
1015
+ || flexSessionDigest(session) !== flexSessionDigest(stored.session)) return;
1016
+ if (!cleanRead) {
1017
+ // Compatibility has recovered this runtime. Schema 2 still requires full recovery
1018
+ // in the next runtime, since this mode does not publish authenticated clean proof.
1019
+ if (catalogue.recoverySchemaVersion !== 2) {
1020
+ await local.setRecoveryRequired(state.storageKey, sessionId, false);
1021
+ }
1022
+ state.recoverySessionIds.delete(sessionId);
1023
+ state.recoveryMarks.delete(sessionId);
1024
+ return;
1025
+ }
1026
+ if (catalogue.recoveryRevision === undefined) return;
1027
+ const [projection, agentEvents] = await Promise.all([
1028
+ this.stores.projections.loadHead!(state.storageKey, sessionId),
1029
+ this.stores.agentEvents.loadHead!(state.storageKey, sessionId),
1030
+ ]);
1031
+ if (!projection?.incarnationId || !agentEvents?.incarnationId) return;
1032
+ await local.publishSessionClean!(state.storageKey, catalogue.recoveryRevision, {
1033
+ sessionId,
1034
+ state: 'clean',
1035
+ ...requireSessionGeneration(session),
1036
+ sessionDigest: flexSessionDigest(session),
1037
+ projection: { incarnationId: projection.incarnationId, revision: projection.revision,
1038
+ contentRoot: projection.contentRoot },
1039
+ agentEvents: { incarnationId: agentEvents.incarnationId, revision: agentEvents.revision,
1040
+ contentRoot: agentEvents.contentRoot },
1041
+ });
1042
+ state.recoverySessionIds.delete(sessionId);
1043
+ state.recoveryMarks.delete(sessionId);
1020
1044
  });
1021
- state.recoverySessionIds.delete(sessionId);
1022
- });
1023
1045
  } catch (error) {
1024
1046
  // Another session can advance the namespace sidecar between our read and exact CAS.
1025
1047
  // This session remains durably dirty and another settled read can publish it.
@@ -1049,8 +1071,8 @@ export class FlexHarnessCore<TScope> {
1049
1071
  else if (!registerOnly) state.recoverySessionIds.delete(sessionId);
1050
1072
  return;
1051
1073
  }
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.
1074
+ // The quiescent settlement path clears marks after the event, job, permission and metadata
1075
+ // writers have settled.
1054
1076
  if (!required) return;
1055
1077
  await this.markRecoveryRequired(state, sessionId);
1056
1078
  }
@@ -1065,6 +1087,7 @@ export class FlexHarnessCore<TScope> {
1065
1087
  if (!state.sessionLocal || state.lifecycle !== 'active') return;
1066
1088
  try {
1067
1089
  await this.updateRecoveryObligation(state, stored);
1090
+ await this.settleQuiescentSessionRecovery(state, stored.session.sessionId);
1068
1091
  } catch (error) {
1069
1092
  this.lifecycle.deferNamespaceDrain(state, error);
1070
1093
  }
@@ -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';
@@ -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);
@@ -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/readme.md CHANGED
@@ -746,7 +746,7 @@ The reservation save is the admission point. A save failure produces no start ev
746
746
 
747
747
  The default `sessionLoading: 'eager'` preserves existing store behavior. Opt into `sessionLoading: 'session-local'` to load a complete metadata catalogue and hydrate only the session a request uses. Concurrent requests, including scope aliases of one storage key, join that session's hydration and repair. Creating an empty session reads none of the unrelated sessions' projections, permissions, events or jobs. `listSessions()` deliberately requests every session's repaired metadata; use `getScopeCatalogue()` or `listSessionIdentities()` for metadata-only enumeration.
748
748
 
749
- Clean recovery admission is a separate rollout. The default `recoveryFrontier: 'compatibility'` fully recovers schema-2 sessions on restart. To enable bounded clean reads, set `recoveryFrontier: { mode: 'clean-read' }` with `sessionLoading: 'session-local'`, a versioned recovery sidecar, and bounded projection and provider-level Agent-event heads. Use `storageKeys: ['exact-storage-key']` to enable selected namespaces; an empty list is rejected. Scope aliases share one storage key and therefore one setting. A valid clean proof whose head has changed is durably marked dirty before full hydration and repair; absent or unrooted heads take that same recovery path, and malformed evidence fails closed.
749
+ Clean recovery admission is a separate rollout. The default `recoveryFrontier: 'compatibility'` clears settled schema-1 obligations after the session's producers drain. With schema 2 it marks inherited clean entries dirty, recovers them once per runtime, and retains their durable marks for the next cold restart. To enable bounded clean reads, set `recoveryFrontier: { mode: 'clean-read' }` with `sessionLoading: 'session-local'`, a versioned recovery sidecar, and bounded projection and provider-level Agent-event heads. Use `storageKeys: ['exact-storage-key']` to enable selected namespaces; an empty list is rejected. Scope aliases share one storage key and therefore one setting. A valid clean proof whose head has changed is durably marked dirty before full hydration and repair; absent or unrooted heads take that same recovery path, and malformed evidence fails closed.
750
750
 
751
751
  ```typescript
752
752
  const harness = new FlexHarness({