agl 43.13.0 → 44.0.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 (99) hide show
  1. package/changelog.md +28 -0
  2. package/dist_serve/bundle.js +4473 -4235
  3. package/dist_serve/bundle.js.map +2 -2
  4. package/dist_serve/bundle.js.third-party-notices.json +29 -29
  5. package/dist_serve/bundle.js.third-party-notices.txt +29 -29
  6. package/dist_ts/00_commitinfo_data.js +2 -2
  7. package/dist_ts/aglapi/aglapisurface.document.js +37 -4
  8. package/dist_ts/classes.authstore.d.ts +60 -3
  9. package/dist_ts/classes.authstore.js +161 -13
  10. package/dist_ts/classes.controller.d.ts +63 -0
  11. package/dist_ts/classes.controller.js +502 -43
  12. package/dist_ts/classes.embeddeddb.js +7 -2
  13. package/dist_ts/classes.flexmodels.private.d.ts +39 -0
  14. package/dist_ts/classes.flexmodels.private.js +127 -1
  15. package/dist_ts/classes.flexprojectpreparation.d.ts +21 -0
  16. package/dist_ts/classes.flexprojectpreparation.js +69 -0
  17. package/dist_ts/classes.flexpromptqueue.d.ts +21 -1
  18. package/dist_ts/classes.flexpromptqueue.js +67 -7
  19. package/dist_ts/classes.flexrequestqueue.d.ts +11 -0
  20. package/dist_ts/classes.flexrequestqueue.js +40 -0
  21. package/dist_ts/classes.flexservice.d.ts +46 -14
  22. package/dist_ts/classes.flexservice.js +179 -55
  23. package/dist_ts/classes.flexstore.d.ts +68 -3
  24. package/dist_ts/classes.flexstore.js +277 -11
  25. package/dist_ts/classes.flexsubmissionmodels.d.ts +58 -0
  26. package/dist_ts/classes.flexsubmissionmodels.js +162 -0
  27. package/dist_ts/classes.flexsubmissionstore.d.ts +70 -0
  28. package/dist_ts/classes.flexsubmissionstore.js +323 -0
  29. package/dist_ts/classes.flexsupervisor.d.ts +10 -0
  30. package/dist_ts/classes.flexsupervisor.js +27 -1
  31. package/dist_ts/classes.harnessoperationmanager.d.ts +31 -0
  32. package/dist_ts/classes.harnessoperationmanager.js +69 -7
  33. package/dist_ts/classes.mcpclient.js +4 -3
  34. package/dist_ts/classes.mcpcontrollerhost.js +3 -2
  35. package/dist_ts/classes.pendingpromptstore.d.ts +11 -3
  36. package/dist_ts/classes.pendingpromptstore.js +66 -10
  37. package/dist_ts/classes.sessionidentityservice.d.ts +18 -1
  38. package/dist_ts/classes.sessionidentityservice.js +34 -4
  39. package/dist_ts/classes.ticketstore.d.ts +5 -3
  40. package/dist_ts/classes.ticketstore.js +7 -2
  41. package/dist_ts/classes.validation.d.ts +3 -0
  42. package/dist_ts/classes.validation.js +50 -1
  43. package/dist_ts/functions.deviceapi.js +7 -3
  44. package/dist_ts/interfaces.auth.d.ts +3 -1
  45. package/dist_ts/interfaces.auth.js +1 -1
  46. package/dist_ts/interfaces.flexipc.d.ts +29 -5
  47. package/dist_ts/interfaces.flexipc.js +13 -4
  48. package/dist_ts_authswitch/classes.authoritydatabase.d.ts +1 -0
  49. package/dist_ts_authswitch/classes.authoritydatabase.js +17 -5
  50. package/dist_ts_interfaces/flexadmission.d.ts +69 -0
  51. package/dist_ts_interfaces/flexadmission.js +2 -0
  52. package/dist_ts_interfaces/index.d.ts +1 -0
  53. package/dist_ts_interfaces/index.js +2 -1
  54. package/dist_ts_interfaces/interfaces.d.ts +10 -1
  55. package/dist_ts_interfaces/interfaces.js +2 -2
  56. package/dist_ts_interfaces/requests.d.ts +2 -1
  57. package/dist_ts_interfaces/requests.js +1 -1
  58. package/dist_ts_interfaces/tickets.d.ts +9 -1
  59. package/dist_ts_interfaces/tickets.js +11 -2
  60. package/dist_ts_migration/v10_flexharnessv3migration.js +4 -1
  61. package/docs/nosqldb11-migration.md +59 -0
  62. package/package.json +10 -9
  63. package/readme.md +5 -1
  64. package/ts/00_commitinfo_data.ts +1 -1
  65. package/ts/aglapi/aglapisurface.document.ts +36 -3
  66. package/ts/classes.authstore.ts +179 -11
  67. package/ts/classes.controller.ts +498 -40
  68. package/ts/classes.embeddeddb.ts +6 -1
  69. package/ts/classes.flexmodels.private.ts +109 -0
  70. package/ts/classes.flexprojectpreparation.ts +69 -0
  71. package/ts/classes.flexpromptqueue.ts +69 -6
  72. package/ts/classes.flexrequestqueue.ts +47 -0
  73. package/ts/classes.flexservice.ts +187 -51
  74. package/ts/classes.flexstore.ts +352 -10
  75. package/ts/classes.flexsubmissionmodels.ts +89 -0
  76. package/ts/classes.flexsubmissionstore.ts +312 -0
  77. package/ts/classes.flexsupervisor.ts +26 -0
  78. package/ts/classes.harnessoperationmanager.ts +79 -6
  79. package/ts/classes.mcpclient.ts +3 -2
  80. package/ts/classes.mcpcontrollerhost.ts +2 -1
  81. package/ts/classes.pendingpromptstore.ts +55 -6
  82. package/ts/classes.sessionidentityservice.ts +33 -2
  83. package/ts/classes.ticketstore.ts +11 -4
  84. package/ts/classes.validation.ts +42 -0
  85. package/ts/functions.deviceapi.ts +6 -2
  86. package/ts/interfaces.auth.ts +3 -1
  87. package/ts/interfaces.flexipc.ts +38 -4
  88. package/ts_authswitch/classes.authoritydatabase.ts +19 -5
  89. package/ts_interfaces/flexadmission.ts +52 -0
  90. package/ts_interfaces/index.ts +2 -0
  91. package/ts_interfaces/interfaces.ts +10 -1
  92. package/ts_interfaces/requests.ts +3 -0
  93. package/ts_interfaces/tickets.ts +12 -2
  94. package/ts_migration/v10_flexharnessv3migration.ts +3 -0
  95. package/ts_web/00_commitinfo_data.ts +1 -1
  96. package/ts_web/classes.browsersubmissions.ts +279 -0
  97. package/ts_web/classes.sessiondraftsync.ts +64 -1
  98. package/ts_web/elements.harnesscontrollerapp.ts +340 -5
  99. package/ts_web/functions.flexsubmissions.ts +88 -0
@@ -1,5 +1,6 @@
1
1
  import * as plugins from './plugins.js';
2
2
  import { FlexFramedTransport } from './classes.flexframedtransport.js';
3
+ import { FlexRequestQueue } from './classes.flexrequestqueue.js';
3
4
  import {
4
5
  FlexModelChoiceModel,
5
6
  type IFlexModelChoiceDocument,
@@ -9,6 +10,7 @@ import {
9
10
  FlexStore,
10
11
  type IFlexProjectManagementHost,
11
12
  type IFlexScopeLoadReads,
13
+ type TFlexWriteProvenanceQualification,
12
14
  } from './classes.flexstore.js';
13
15
  import { FlexPersistenceMigrationRunner } from '../ts_migration/classes.flexmigrationrunner.js';
14
16
  import {
@@ -54,6 +56,8 @@ import {
54
56
  type TFlexSessionGeneration,
55
57
  type TFlexSessionGenerationCohortEntry,
56
58
  type TFlexSessionIdentity,
59
+ type TFlexProjectPreparationState,
60
+ type TFlexSessionDeletionResult,
57
61
  createFlexServiceError,
58
62
  flexGenerationLeaseCleanupTimeoutMs,
59
63
  flexIntelligenceInstallationScopeId,
@@ -368,6 +372,48 @@ export const formatFlexScopeLoadLine = (
368
372
  totalMs: Math.round(metricsArg.totalMs),
369
373
  })}`;
370
374
 
375
+ /**
376
+ * Writes a FlexHarness namespace qualification to the controller log: `absent` is expected once per
377
+ * project after the upgrade that added the write witness, and for a new project; `stale` is a warning
378
+ * naming both counts (a writer whose writes were not known wrote the namespace).
379
+ */
380
+ export const reportFlexWriteProvenanceQualification = (
381
+ qualificationArg: TFlexWriteProvenanceQualification,
382
+ ): void => {
383
+ const fields = qualificationArg.reason === 'absent'
384
+ ? { projectId: qualificationArg.storageKey, reason: 'absent' }
385
+ : {
386
+ projectId: qualificationArg.storageKey,
387
+ reason: 'stale',
388
+ writeCount: qualificationArg.writeCount,
389
+ knownWriteCount: qualificationArg.knownWriteCount,
390
+ };
391
+ process.stderr.write(`${qualificationArg.reason === 'stale' ? 'Warning: ' : ''}`
392
+ + `Flex project qualified: ${JSON.stringify(fields)}\n`);
393
+ };
394
+
395
+ /**
396
+ * A project's FlexHarness preparation in a Flex child generation: the store's writer lease for the
397
+ * project first, then `prepareScope` with explicit legacy qualification (a complete load and repair
398
+ * only where the stored proof or write provenance is absent or stale), then the reversion state of
399
+ * the sessions it left recovery obligations for. Sessions without one stay cold. Runs once per
400
+ * project and generation, never in a request's path or a retry loop.
401
+ */
402
+ export const prepareFlexProjectNamespace = async <TScope>(
403
+ storeArg: Pick<FlexStore, 'holdWriterLease'>,
404
+ harnessArg: Pick<plugins.flexharness.FlexHarness<TScope>, 'prepareScope' | 'getSessionReversionInfo'>,
405
+ projectIdArg: string,
406
+ continueArg: () => boolean = () => true,
407
+ ): Promise<plugins.flexharness.IFlexScopeCatalogue> => {
408
+ await storeArg.holdWriterLease(projectIdArg);
409
+ const catalogue = await harnessArg.prepareScope(projectIdArg, { qualifyLegacy: true });
410
+ for (const sessionId of catalogue.recoverySessionIds) {
411
+ if (!continueArg()) break;
412
+ await harnessArg.getSessionReversionInfo(projectIdArg, sessionId);
413
+ }
414
+ return catalogue;
415
+ };
416
+
371
417
  export const createFlexBuiltInTools = (): plugins.flexharness.IFlexBuiltInToolsOptions => ({
372
418
  renameSession: true,
373
419
  projectManagement: {
@@ -421,6 +467,15 @@ const projectRequestScopeId = (
421
467
  }
422
468
  return (payloadArg as { scopeId: string }).scopeId;
423
469
  };
470
+ /** Requests confined to one session; destructive and project-wide requests remain barriers. */
471
+ const sessionRequestId = (methodArg: TFlexRequestMethod, payloadArg: unknown): string | undefined => {
472
+ if (methodArg === 'session.create') {
473
+ return (payloadArg as IFlexRequestMap['session.create']['request']).options.sessionId;
474
+ }
475
+ if (methodArg === 'session.delete') return undefined;
476
+ const payload = payloadArg as { sessionId?: unknown };
477
+ return typeof payload.sessionId === 'string' ? payload.sessionId : undefined;
478
+ };
424
479
  const projectScopedMethods: ReadonlySet<TFlexRequestMethod> = new Set([
425
480
  'intelligence.start',
426
481
  'intelligence.get',
@@ -722,6 +777,8 @@ export class FlexService {
722
777
  private initData?: IFlexServiceInit;
723
778
  private database?: plugins.nosqldb.SmartdataDb;
724
779
  private store?: FlexStore;
780
+ /** Each project's one preparation in this generation; see `startProjectPreparation`. */
781
+ private readonly projectPreparations = new Map<string, Promise<void>>();
725
782
  private harness?: TFlexHarness<IFlexProjectScope>;
726
783
  private unsubscribeHarness?: () => void;
727
784
  private providerRegistry?: plugins.openAiAccount.SmartAiProviderRegistry;
@@ -746,6 +803,7 @@ export class FlexService {
746
803
  private claudePoolCatalog?: IFlexProxyClaudeModel[];
747
804
  private readonly connectionQueues = new Map<string, Promise<void>>();
748
805
  private readonly projectRequestTails = new Map<string, Promise<void>>();
806
+ private requestQueue?: FlexRequestQueue;
749
807
  private readonly jobs = new Map<string, IFlexJob>();
750
808
  private readonly intelligenceJobs = new Map<string, IFlexIntelligenceJob>();
751
809
  private readonly activeIntelligenceJobIdsBySource = new Map<string, string>();
@@ -973,6 +1031,7 @@ export class FlexService {
973
1031
  retiredWriterIds: initArg.retiredWriterIds,
974
1032
  projectManagementHost: this.createProjectManagementHost(),
975
1033
  onFatalError: (error) => this.handleStoreFatalError(error),
1034
+ onWriteProvenanceQualified: (qualification) => reportFlexWriteProvenanceQualification(qualification),
976
1035
  });
977
1036
  this.store = store;
978
1037
  await store.init();
@@ -1015,6 +1074,9 @@ export class FlexService {
1015
1074
  reversionPolicy: 'workspace-required',
1016
1075
  slashCommands: [this.worktreeSlashCommand()],
1017
1076
  stores: store,
1077
+ // Each request hydrates only the session it uses; `prepareProject` qualifies a namespace once
1078
+ // per generation, so nothing falls back to loading every history of a project.
1079
+ sessionLoading: 'session-local',
1018
1080
  scopeLoadObserver: (metrics) => this.reportScopeLoad(store, metrics),
1019
1081
  builtInTools: createFlexBuiltInTools(),
1020
1082
  toolOutputLimits: { maxDepth: 12, maxBytes: toolOutputBytes },
@@ -1045,20 +1107,10 @@ export class FlexService {
1045
1107
  }
1046
1108
  this.initialized = true;
1047
1109
  await this.sendStatus({ state: 'ready', ready: true, startedAt: nowIso() });
1048
- // Recovery stays owned and fail-closed, but histories unrelated to the first request do not
1049
- // delay the ready handshake. Concurrent reads join the harness's existing namespace load.
1050
- this.trackBackgroundTask((async () => {
1051
- for (const project of this.projects.values()) {
1052
- if (this.disposing || this.disposed) return;
1053
- const sessions = await harness.listSessions(project.projectId);
1054
- for (const session of sessions) {
1055
- if (this.disposing || this.disposed) return;
1056
- await harness.getSessionReversionInfo(project.projectId, session.sessionId);
1057
- }
1058
- }
1059
- })().catch((error: unknown) => this.handleFatalError(
1060
- error instanceof Error ? error : new Error('Deferred Flex recovery failed.'),
1061
- )));
1110
+ // Each project the controller started this generation with is prepared in the background:
1111
+ // the ready handshake never waits for a project's recovery, and a request of a project waits
1112
+ // only for that project's preparation.
1113
+ for (const project of this.projects.values()) void this.startProjectPreparation(project.projectId);
1062
1114
  } catch (errorArg) {
1063
1115
  throw errorArg;
1064
1116
  }
@@ -1183,7 +1235,7 @@ export class FlexService {
1183
1235
  const scopeId = projectRequestScopeId(methodArg, payloadArg);
1184
1236
  return scopeId === undefined
1185
1237
  ? dispatch()
1186
- : this.withProjectRequestQueue(scopeId, signalArg, dispatch);
1238
+ : this.withProjectRequestQueue(scopeId, signalArg, dispatch, sessionRequestId(methodArg, payloadArg));
1187
1239
  }
1188
1240
 
1189
1241
  /**
@@ -1228,12 +1280,30 @@ export class FlexService {
1228
1280
  this.pendingProjectRetirements.has(scopeId)
1229
1281
  || this.pendingProjectRemovals.has(scopeId)
1230
1282
  ) throw new FlexServiceError('BUSY');
1283
+ // Identities come from the stored catalogue alone and never wait (AGL-1713); every other
1284
+ // request of the project uses FlexHarness's prepared namespace.
1285
+ if (methodArg !== 'session.identities') await this.waitForProjectPrepared(scopeId, signalArg);
1231
1286
  }
1232
1287
  const harness = this.requireHarness();
1233
1288
  switch (methodArg) {
1234
1289
  case 'project.register': {
1235
1290
  const payload = payloadArg as IFlexRequestMap['project.register']['request'];
1236
- const added = await this.registerProject(payload.project, signalArg);
1291
+ const projectId = payload.project.projectId;
1292
+ const known = this.projects.has(projectId);
1293
+ // A project this generation removed keeps the preparation its removal ran (a re-issued
1294
+ // removal shares it); registered again, it is a new project and prepares anew.
1295
+ if (!known) this.projectPreparations.delete(projectId);
1296
+ if (!known) await this.reportProjectPreparation(projectId, 'preparing');
1297
+ let added: boolean;
1298
+ try {
1299
+ added = await this.registerProject(payload.project, signalArg);
1300
+ } catch (errorArg) {
1301
+ if (!known && !this.projects.has(projectId)) await this.reportProjectPreparation(projectId, 'failed');
1302
+ throw errorArg;
1303
+ }
1304
+ // Registration answers within its control budget; the preparation runs after it, once per
1305
+ // project and generation (a known project's, ready, running or failed, is not run again).
1306
+ if (!this.projectPreparations.has(projectId)) void this.startProjectPreparation(projectId);
1237
1307
  return { result: { registered: true, added } };
1238
1308
  }
1239
1309
  case 'project.remove': {
@@ -1365,7 +1435,20 @@ export class FlexService {
1365
1435
  }
1366
1436
  this.deleteSessionUploadGrants(payload.scopeId, payload.root.sessionId);
1367
1437
  this.promptStages.delete(`${payload.scopeId}\0${payload.root.sessionId}`);
1368
- return { result };
1438
+ // Why a root did not match decides what the controller may end of its own records.
1439
+ const answer: TFlexSessionDeletionResult = result.matched
1440
+ ? { matched: true }
1441
+ : result.reason === 'absent'
1442
+ ? { matched: false, reason: 'absent' }
1443
+ : {
1444
+ matched: false,
1445
+ reason: 'superseded',
1446
+ current: {
1447
+ sessionGenerationId: result.current.sessionGenerationId,
1448
+ sessionGenerationSequence: result.current.sessionGenerationSequence,
1449
+ },
1450
+ };
1451
+ return { result: answer };
1369
1452
  }
1370
1453
  case 'session.compact': {
1371
1454
  const payload = payloadArg as IFlexRequestMap['session.compact']['request'];
@@ -5289,11 +5372,9 @@ export class FlexService {
5289
5372
  }
5290
5373
 
5291
5374
  /**
5292
- * `prompt.start` holds its project's request queue until its run starts, so it admits a prompt
5293
- * only into a session without outstanding prompts; waiting prompts belong to the controller
5294
- * queue. `prompt.start` is serialized by the project request queue and the controller runs a
5295
- * Flex slash command only on a session without other operations, so no admission races this
5296
- * check.
5375
+ * Starts are ordered within their session, so no other prompt admission can overtake this
5376
+ * idle check. Other sessions may prepare their own starts concurrently; project lifecycle
5377
+ * barriers still exclude and drain all of them.
5297
5378
  */
5298
5379
  private async assertSessionIdle(
5299
5380
  harnessArg: TFlexHarness<IFlexProjectScope>,
@@ -5306,42 +5387,21 @@ export class FlexService {
5306
5387
  }
5307
5388
  }
5308
5389
 
5309
- /**
5310
- * Runs the requests of one project one at a time, in arrival order. Registration, removal and
5311
- * prompt admission check and change a project's state across awaits, and the controller relies
5312
- * on a project's requests taking effect in the order it sent them. Different projects share no
5313
- * such state (the project limit is reserved synchronously in `registerProject`), so each project
5314
- * has its own queue and one project's slow request never holds another's. A request cancelled
5315
- * while it waits leaves the queue at once without starting.
5316
- */
5390
+ /** Session-local FIFO work under a project-wide lifecycle barrier. */
5317
5391
  private withProjectRequestQueue<T>(
5318
5392
  scopeIdArg: string,
5319
5393
  signalArg: AbortSignal,
5320
5394
  operationArg: () => Promise<T>,
5395
+ sessionIdArg?: string,
5321
5396
  ): Promise<T> {
5322
- const previous = this.projectRequestTails.get(scopeIdArg) ?? Promise.resolve();
5323
- let started = false;
5324
- const operation = previous.then(() => {
5325
- signalArg.throwIfAborted();
5326
- started = true;
5327
- return operationArg();
5328
- });
5397
+ this.requestQueue ??= new FlexRequestQueue();
5398
+ const operation = this.requestQueue.run(scopeIdArg, sessionIdArg, signalArg, operationArg);
5399
+ if (sessionIdArg !== undefined) return operation;
5329
5400
  const tail = operation.then(() => undefined, () => undefined);
5330
5401
  this.projectRequestTails.set(scopeIdArg, tail);
5331
- void tail.then(() => {
5332
- if (this.projectRequestTails.get(scopeIdArg) === tail) {
5333
- this.projectRequestTails.delete(scopeIdArg);
5334
- }
5335
- });
5336
- return new Promise<T>((resolve, reject) => {
5337
- const leaveQueue = (): void => {
5338
- if (!started) reject(signalArg.reason);
5339
- };
5340
- if (signalArg.aborted) leaveQueue();
5341
- else signalArg.addEventListener('abort', leaveQueue, { once: true });
5342
- void operation.then(resolve, reject).finally(() => {
5343
- signalArg.removeEventListener('abort', leaveQueue);
5344
- });
5402
+ // The caller resumes only after its project-wide request left the tails it was observed in.
5403
+ return operation.finally(() => {
5404
+ if (this.projectRequestTails.get(scopeIdArg) === tail) this.projectRequestTails.delete(scopeIdArg);
5345
5405
  });
5346
5406
  }
5347
5407
 
@@ -5502,6 +5562,9 @@ export class FlexService {
5502
5562
  let completed = false;
5503
5563
  try {
5504
5564
  await this.waitForFencedAcknowledgements(fence, signalArg);
5565
+ // Its deletions run in FlexHarness's prepared namespace: a project this generation never
5566
+ // registered gets its one preparation here.
5567
+ await this.waitForProjectPrepared(projectId, signalArg, true);
5505
5568
  const authorizedCohort: TFlexSessionGenerationCohortEntry[] = cleanupCohortArg.map((entry) => ({
5506
5569
  sessionId: entry.sessionId,
5507
5570
  sessionGenerationId: entry.sessionGenerationId,
@@ -5522,6 +5585,7 @@ export class FlexService {
5522
5585
  signalArg.throwIfAborted();
5523
5586
  await this.deleteModelChoiceForScope(projectId);
5524
5587
  this.projects.delete(projectId);
5588
+ await this.reportProjectPreparation(projectId, 'failed');
5525
5589
  this.deleteProjectUploadGrants(projectId);
5526
5590
  for (const key of this.promptStages.keys()) if (key.startsWith(`${projectId}\0`)) this.promptStages.delete(key);
5527
5591
  for (const [key, event] of this.sessionChangeQueue.entries()) {
@@ -5548,6 +5612,78 @@ export class FlexService {
5548
5612
  });
5549
5613
  }
5550
5614
 
5615
+ /**
5616
+ * Starts a project's one preparation of this generation and reports it (`preparing`, then `ready`
5617
+ * or `failed`). A failed preparation stays failed until the next generation: it is never retried
5618
+ * by a request, and a FlexHarness store format error is never answered by requalifying. Only a
5619
+ * project this generation removed, registered again, prepares anew (`project.register`).
5620
+ */
5621
+ private startProjectPreparation(projectIdArg: string): Promise<void> {
5622
+ const existing = this.projectPreparations.get(projectIdArg);
5623
+ if (existing) return existing;
5624
+ const preparation = (async () => {
5625
+ await this.reportProjectPreparation(projectIdArg, 'preparing');
5626
+ try {
5627
+ await this.prepareProject(projectIdArg);
5628
+ } catch (errorArg) {
5629
+ process.stderr.write(`Flex project preparation failed: ${JSON.stringify({
5630
+ projectId: projectIdArg,
5631
+ failure: describeFailure(errorArg),
5632
+ })}\n`);
5633
+ if (this.projects.has(projectIdArg)) await this.reportProjectPreparation(projectIdArg, 'failed');
5634
+ throw errorArg;
5635
+ }
5636
+ await this.reportProjectPreparation(projectIdArg, 'ready');
5637
+ })();
5638
+ this.projectPreparations.set(projectIdArg, preparation);
5639
+ this.trackBackgroundTask(preparation);
5640
+ return preparation;
5641
+ }
5642
+
5643
+ /**
5644
+ * The project's writer lease first, then FlexHarness's preparation of its namespace with explicit
5645
+ * legacy qualification (a complete load and repair only where the stored evidence is absent or
5646
+ * stale), then the reversion state of the sessions it left recovery obligations for. Sessions
5647
+ * without one stay cold.
5648
+ */
5649
+ private async prepareProject(projectIdArg: string): Promise<void> {
5650
+ const store = this.store;
5651
+ if (!store) throw new FlexServiceError('NOT_READY');
5652
+ await prepareFlexProjectNamespace(
5653
+ store,
5654
+ this.requireHarness(),
5655
+ projectIdArg,
5656
+ () => !this.disposing && !this.disposed,
5657
+ );
5658
+ }
5659
+
5660
+ /**
5661
+ * Waits for the project's preparation in this generation, or refuses with `NOT_READY` when it
5662
+ * failed. `startArg` starts a project's preparation that this generation has not started yet.
5663
+ */
5664
+ private async waitForProjectPrepared(projectIdArg: string, signalArg: AbortSignal, startArg = false): Promise<void> {
5665
+ const preparation = this.projectPreparations.get(projectIdArg)
5666
+ ?? (startArg ? this.startProjectPreparation(projectIdArg) : undefined);
5667
+ if (!preparation) throw new FlexServiceError('NOT_READY');
5668
+ signalArg.throwIfAborted();
5669
+ await new Promise<void>((resolve, reject) => {
5670
+ const abort = (): void => reject(signalArg.reason);
5671
+ signalArg.addEventListener('abort', abort, { once: true });
5672
+ preparation.then(
5673
+ () => { signalArg.removeEventListener('abort', abort); resolve(); },
5674
+ () => { signalArg.removeEventListener('abort', abort); reject(new FlexServiceError('NOT_READY')); },
5675
+ );
5676
+ });
5677
+ }
5678
+
5679
+ /**
5680
+ * Tells the controller where a project's preparation stands in this generation (`preparing`,
5681
+ * `ready`, `failed`); see `startProjectPreparation`.
5682
+ */
5683
+ private reportProjectPreparation(projectIdArg: string, stateArg: TFlexProjectPreparationState): Promise<void> {
5684
+ return this.sendEvent({ type: 'project.preparation', scopeId: projectIdArg, state: stateArg });
5685
+ }
5686
+
5551
5687
  private async sendEvent(eventArg: TFlexChildEvent): Promise<void> {
5552
5688
  if (this.disposed) return;
5553
5689
  if (this.disposing && eventArg.type !== 'prompt.finished') return;