agl 43.14.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 (89) hide show
  1. package/changelog.md +22 -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.pendingpromptstore.d.ts +11 -3
  34. package/dist_ts/classes.pendingpromptstore.js +66 -10
  35. package/dist_ts/classes.sessionidentityservice.d.ts +18 -1
  36. package/dist_ts/classes.sessionidentityservice.js +34 -4
  37. package/dist_ts/classes.validation.d.ts +3 -0
  38. package/dist_ts/classes.validation.js +50 -1
  39. package/dist_ts/functions.deviceapi.js +3 -1
  40. package/dist_ts/interfaces.auth.d.ts +3 -1
  41. package/dist_ts/interfaces.auth.js +1 -1
  42. package/dist_ts/interfaces.flexipc.d.ts +29 -5
  43. package/dist_ts/interfaces.flexipc.js +13 -4
  44. package/dist_ts_authswitch/classes.authoritydatabase.d.ts +1 -0
  45. package/dist_ts_authswitch/classes.authoritydatabase.js +17 -5
  46. package/dist_ts_interfaces/flexadmission.d.ts +69 -0
  47. package/dist_ts_interfaces/flexadmission.js +2 -0
  48. package/dist_ts_interfaces/index.d.ts +1 -0
  49. package/dist_ts_interfaces/index.js +2 -1
  50. package/dist_ts_interfaces/interfaces.d.ts +10 -1
  51. package/dist_ts_interfaces/interfaces.js +2 -2
  52. package/dist_ts_interfaces/requests.d.ts +2 -1
  53. package/dist_ts_interfaces/requests.js +1 -1
  54. package/dist_ts_migration/v10_flexharnessv3migration.js +4 -1
  55. package/docs/nosqldb11-migration.md +59 -0
  56. package/package.json +10 -9
  57. package/readme.md +5 -1
  58. package/ts/00_commitinfo_data.ts +1 -1
  59. package/ts/aglapi/aglapisurface.document.ts +36 -3
  60. package/ts/classes.authstore.ts +179 -11
  61. package/ts/classes.controller.ts +498 -40
  62. package/ts/classes.embeddeddb.ts +6 -1
  63. package/ts/classes.flexmodels.private.ts +109 -0
  64. package/ts/classes.flexprojectpreparation.ts +69 -0
  65. package/ts/classes.flexpromptqueue.ts +69 -6
  66. package/ts/classes.flexrequestqueue.ts +47 -0
  67. package/ts/classes.flexservice.ts +187 -51
  68. package/ts/classes.flexstore.ts +352 -10
  69. package/ts/classes.flexsubmissionmodels.ts +89 -0
  70. package/ts/classes.flexsubmissionstore.ts +312 -0
  71. package/ts/classes.flexsupervisor.ts +26 -0
  72. package/ts/classes.harnessoperationmanager.ts +79 -6
  73. package/ts/classes.pendingpromptstore.ts +55 -6
  74. package/ts/classes.sessionidentityservice.ts +33 -2
  75. package/ts/classes.validation.ts +42 -0
  76. package/ts/functions.deviceapi.ts +2 -0
  77. package/ts/interfaces.auth.ts +3 -1
  78. package/ts/interfaces.flexipc.ts +38 -4
  79. package/ts_authswitch/classes.authoritydatabase.ts +19 -5
  80. package/ts_interfaces/flexadmission.ts +52 -0
  81. package/ts_interfaces/index.ts +2 -0
  82. package/ts_interfaces/interfaces.ts +10 -1
  83. package/ts_interfaces/requests.ts +3 -0
  84. package/ts_migration/v10_flexharnessv3migration.ts +3 -0
  85. package/ts_web/00_commitinfo_data.ts +1 -1
  86. package/ts_web/classes.browsersubmissions.ts +279 -0
  87. package/ts_web/classes.sessiondraftsync.ts +64 -1
  88. package/ts_web/elements.harnesscontrollerapp.ts +340 -5
  89. package/ts_web/functions.flexsubmissions.ts +88 -0
@@ -10,11 +10,15 @@ import {
10
10
  FlexDomainHeadModel,
11
11
  FlexHeadModel,
12
12
  FlexMigrationModel,
13
+ FlexNamespaceWritesModel,
13
14
  FlexPrivateCandidateModel,
14
15
  FlexPrivateChunkModel,
16
+ FlexScopeRecoveryModel,
15
17
  FlexWriterLeaseModel,
16
18
  type IFlexDomainHeadDocument,
17
19
  type IFlexMigrationDocument,
20
+ type IFlexNamespaceWritesDocument,
21
+ type IFlexScopeRecoveryDocument,
18
22
  type IFlexPrivateCandidateDocument,
19
23
  type IFlexPrivateCandidateManifest,
20
24
  type IFlexPrivateChunkDocument,
@@ -22,11 +26,15 @@ import {
22
26
  type TFlexDomainKind,
23
27
  assertFlexDomainHeadDocument,
24
28
  assertFlexMigrationDocument,
29
+ assertFlexNamespaceWritesDocument,
25
30
  assertFlexPrivateCandidateDocument,
26
31
  assertFlexPrivateChunkDocument,
32
+ assertFlexScopeRecoveryDocument,
27
33
  assertFlexWriterLeaseDocument,
28
34
  flexDomainHeadId,
29
35
  flexMigrationId,
36
+ flexNamespaceWritesId,
37
+ flexScopeRecoveryId,
30
38
  flexWriterLeaseId,
31
39
  initFlexPrivateModels,
32
40
  registerFlexPrivateModels,
@@ -94,6 +102,8 @@ type TStoredDomainHead = plugins.nosqldb.TStoredDocument<IFlexDomainHeadDocument
94
102
  type TStoredMigration = plugins.nosqldb.TStoredDocument<IFlexMigrationDocument>;
95
103
  type TStoredPublicHead = plugins.nosqldb.TStoredDocument<IFlexPublicHeadDocument>;
96
104
  type TStoredLease = plugins.nosqldb.TStoredDocument<IFlexWriterLeaseDocument>;
105
+ type TStoredNamespaceWrites = plugins.nosqldb.TStoredDocument<IFlexNamespaceWritesDocument>;
106
+ type TStoredScopeRecovery = plugins.nosqldb.TStoredDocument<IFlexScopeRecoveryDocument>;
97
107
  type TFlexObjectId = TStoredDomainHead['_id'];
98
108
  type TFlexDomainHeadFilter = NonNullable<
99
109
  plugins.nosqldb.IFindStoredOptions<IFlexDomainHeadDocument>['filter']
@@ -126,8 +136,24 @@ export interface IFlexStoreOptions {
126
136
  retiredWriterIds?: readonly string[];
127
137
  projectManagementHost: IFlexProjectManagementHost;
128
138
  onFatalError?: (errorArg: Error) => void;
139
+ /**
140
+ * Called once each time FlexHarness qualifies a namespace explicitly (`prepareScope` with
141
+ * `qualifyLegacy`), with what the store found when the namespace's provenance first read
142
+ * unqualified. The Flex child writes it to the controller log.
143
+ */
144
+ onWriteProvenanceQualified?: (qualificationArg: TFlexWriteProvenanceQualification) => void;
129
145
  }
130
146
 
147
+ /**
148
+ * Why a namespace needed explicit qualification: no write witness (`absent`: the first start after
149
+ * the upgrade that added it, or a new project), or writes the witness does not know (`stale`: a
150
+ * writer whose provenance was not activated wrote it; `writeCount` equal to `knownWriteCount` means
151
+ * only the recovery proof was out of date).
152
+ */
153
+ export type TFlexWriteProvenanceQualification =
154
+ | { storageKey: string; reason: 'absent' }
155
+ | { storageKey: string; reason: 'stale'; writeCount: number; knownWriteCount: number };
156
+
131
157
  /** What a migration may do in its storage key's writer turn; see `FlexStore.runMigrationTurn`. */
132
158
  export interface IFlexMigrationTurn {
133
159
  readonly controllerId: string;
@@ -295,6 +321,8 @@ interface IFlexHeadMutationOptions<THead extends object> {
295
321
  ) => Promise<plugins.nosqldb.TStoredDocument<THead> | null>;
296
322
  project: (valueArg: THead) => THead;
297
323
  targetName: string;
324
+ /** Only the last step of a purge, which deletes the namespace's write witness itself. */
325
+ deletesWriteWitness?: true;
298
326
  }
299
327
 
300
328
  interface IFlexReadOptions {
@@ -790,6 +818,21 @@ const migrationBody = (valueArg: IFlexMigrationDocument): IFlexMigrationDocument
790
818
  completedAt: valueArg.completedAt,
791
819
  });
792
820
 
821
+ const namespaceWritesBody = (valueArg: IFlexNamespaceWritesDocument): IFlexNamespaceWritesDocument => ({
822
+ id: valueArg.id,
823
+ controllerId: valueArg.controllerId,
824
+ storageKey: valueArg.storageKey,
825
+ writeCount: valueArg.writeCount,
826
+ knownWriteCount: valueArg.knownWriteCount,
827
+ });
828
+
829
+ const scopeRecoveryBody = (valueArg: IFlexScopeRecoveryDocument): IFlexScopeRecoveryDocument => ({
830
+ id: valueArg.id,
831
+ controllerId: valueArg.controllerId,
832
+ storageKey: valueArg.storageKey,
833
+ proof: structuredClone(valueArg.proof),
834
+ });
835
+
793
836
  const projectPrivateChunk = (modelArg: FlexPrivateChunkModel): IFlexPrivateChunkDocument => ({
794
837
  id: modelArg.id,
795
838
  controllerId: modelArg.controllerId,
@@ -1223,9 +1266,36 @@ export class FlexStore implements plugins.flexharness.IFlexHarnessStores {
1223
1266
  public readonly agentEvents: plugins.flexharness.IFlexAgentEventStoreProvider;
1224
1267
  public readonly jobs: plugins.flexharness.IFlexToolJobStoreProvider;
1225
1268
 
1269
+ /**
1270
+ * FlexHarness's recovery sidecar for this storage (`scopes.sessionLocal`): the proof lives in
1271
+ * `flex_scope_recovery`, the write provenance in `flex_namespace_writes`, which every write
1272
+ * transaction of the namespace counts (`renewLeaseAndCountWrite`).
1273
+ */
1274
+ public readonly scopeRecovery: plugins.flexharness.IFlexScopeRecoveryStore = {
1275
+ deactivateWriteProvenance: (storageKey) => {
1276
+ this.knownWriteKeys.delete(storageKey);
1277
+ },
1278
+ loadWriteProvenance: (storageKey) => this.loadWriteProvenance(storageKey),
1279
+ qualifyWriteProvenance: (storageKey) => this.qualifyWriteProvenance(storageKey),
1280
+ load: (storageKey) => this.loadScopeRecovery(storageKey),
1281
+ save: (storageKey, snapshot, expectedRevision) =>
1282
+ this.saveScopeRecovery(storageKey, snapshot, expectedRevision),
1283
+ };
1284
+
1226
1285
  private readonly database: plugins.nosqldb.SmartdataDb;
1227
1286
  private readonly controllerId: string;
1228
1287
  private readonly writerId: string;
1288
+ private readonly onWriteProvenanceQualified?: (
1289
+ qualificationArg: TFlexWriteProvenanceQualification,
1290
+ ) => void;
1291
+ /** Storage keys whose writes this store records as known: FlexHarness activated their provenance. */
1292
+ private readonly knownWriteKeys = new Set<string>();
1293
+ /**
1294
+ * What the first unqualified provenance read of a storage key found since its last qualification,
1295
+ * reported when FlexHarness qualifies it. A qualifying load writes before it qualifies, so a later
1296
+ * read would no longer see the state the preparation started from.
1297
+ */
1298
+ private readonly unqualifiedProvenance = new Map<string, TFlexWriteProvenanceQualification>();
1229
1299
  private readonly retiredWriterIds: ReadonlySet<string>;
1230
1300
  private readonly onFatalError?: (errorArg: Error) => void;
1231
1301
  private readonly manager: { db: plugins.nosqldb.SmartdataDb };
@@ -1305,16 +1375,17 @@ export class FlexStore implements plugins.flexharness.IFlexHarnessStores {
1305
1375
  this.writerId = optionsArg.writerId;
1306
1376
  this.retiredWriterIds = new Set(retiredWriterIds);
1307
1377
  this.onFatalError = optionsArg.onFatalError;
1378
+ this.onWriteProvenanceQualified = optionsArg.onWriteProvenanceQualified;
1308
1379
  this.manager = { db: this.database };
1309
1380
  registerFlexPrivateModels(this.manager);
1310
1381
  registerFlexPublicModels(this.manager);
1311
1382
  registerFlexPostHarnessMigrationMarkerModel(this.manager);
1312
1383
 
1313
- this.scopes = {
1384
+ this.scopes = new plugins.flexharness.RecoverableFlexScopeStore({
1314
1385
  load: (storageKey) => this.loadScope(storageKey),
1315
1386
  save: (storageKey, snapshot, expectedRevision) =>
1316
1387
  this.saveScope(storageKey, snapshot, expectedRevision),
1317
- };
1388
+ }, this.scopeRecovery);
1318
1389
  this.projections = {
1319
1390
  load: (storageKey, sessionId) => this.loadProjection(storageKey, sessionId),
1320
1391
  save: (storageKey, sessionId, change, expectedRevision) =>
@@ -1402,9 +1473,12 @@ export class FlexStore implements plugins.flexharness.IFlexHarnessStores {
1402
1473
  public getLegacyMigrationStores(): plugins.flexharness.IFlexHarnessStores {
1403
1474
  return {
1404
1475
  scopes: {
1405
- ...this.scopes,
1406
- save: (storageKey, snapshot, expectedRevision) =>
1407
- this.saveScope(storageKey, snapshot, expectedRevision, false),
1476
+ load: (storageKey) => this.loadScope(storageKey),
1477
+ // A migration is not a recovery-aware writer: its writes are unknown to the witness.
1478
+ save: (storageKey, snapshot, expectedRevision) => {
1479
+ this.knownWriteKeys.delete(storageKey);
1480
+ return this.saveScope(storageKey, snapshot, expectedRevision, false);
1481
+ },
1408
1482
  },
1409
1483
  projections: {
1410
1484
  ...this.projections,
@@ -1650,6 +1724,14 @@ export class FlexStore implements plugins.flexharness.IFlexHarnessStores {
1650
1724
  this.publicProjectionsToVerify.add(storageKeyArg);
1651
1725
  }
1652
1726
 
1727
+ /**
1728
+ * Takes this store's writer lease for the storage key in its writer turn, or proves it still holds
1729
+ * it. The Flex child prepares a project's FlexHarness namespace only after this.
1730
+ */
1731
+ public async holdWriterLease(storageKeyArg: string): Promise<void> {
1732
+ await this.runStorage(storageKeyArg, async () => undefined);
1733
+ }
1734
+
1653
1735
  public async purgeScope(storageKeyArg: string): Promise<void> {
1654
1736
  await this.runStorage(storageKeyArg, async (lease) => {
1655
1737
  this.evictProviderScope(storageKeyArg);
@@ -1711,12 +1793,26 @@ export class FlexStore implements plugins.flexharness.IFlexHarnessStores {
1711
1793
  });
1712
1794
  }
1713
1795
 
1796
+ const recovery = await this.readScopeRecovery(storageKeyArg);
1797
+ if (recovery) {
1798
+ await this.commitHeadMutation({
1799
+ lease,
1800
+ exact: FlexScopeRecoveryModel.exact,
1801
+ current: recovery,
1802
+ next: null,
1803
+ readCurrent: (options) => this.readScopeRecovery(storageKeyArg, options),
1804
+ project: scopeRecoveryBody,
1805
+ targetName: `scope-recovery:${recovery.id}`,
1806
+ });
1807
+ }
1808
+
1714
1809
  await this.deleteScopeRecords(lease, storageKeyArg);
1715
1810
  const remaining = await Promise.all([
1716
1811
  FlexDomainHeadModel.exact.count({ controllerId: this.controllerId, storageKey: storageKeyArg }),
1717
1812
  FlexPublicHeadModel.exact.count({ controllerId: this.controllerId, storageKey: storageKeyArg }),
1718
1813
  FlexMigrationModel.exact.count({ controllerId: this.controllerId, storageKey: storageKeyArg }),
1719
1814
  FlexHeadModel.exact.count({ controllerId: this.controllerId, storageKey: storageKeyArg }),
1815
+ FlexScopeRecoveryModel.exact.count({ controllerId: this.controllerId, storageKey: storageKeyArg }),
1720
1816
  ]);
1721
1817
  if (remaining.some((count) => count !== 0)) {
1722
1818
  throw new plugins.nosqldb.SmartdataExactPersistenceError(
@@ -1724,6 +1820,22 @@ export class FlexStore implements plugins.flexharness.IFlexHarnessStores {
1724
1820
  'Flex scope purge could not confirm all head deletions.',
1725
1821
  );
1726
1822
  }
1823
+ // Every domain is empty: the last step deletes the write witness itself, uncounted.
1824
+ this.knownWriteKeys.delete(storageKeyArg);
1825
+ this.unqualifiedProvenance.delete(storageKeyArg);
1826
+ const witness = await this.readNamespaceWrites(storageKeyArg);
1827
+ if (witness) {
1828
+ await this.commitHeadMutation({
1829
+ lease,
1830
+ exact: FlexNamespaceWritesModel.exact,
1831
+ current: witness,
1832
+ next: null,
1833
+ readCurrent: (options) => this.readNamespaceWrites(storageKeyArg, options),
1834
+ project: namespaceWritesBody,
1835
+ targetName: `namespace-writes:${witness.id}`,
1836
+ deletesWriteWitness: true,
1837
+ });
1838
+ }
1727
1839
  await this.releaseHeldLease(lease);
1728
1840
  });
1729
1841
  }
@@ -3744,7 +3856,11 @@ export class FlexStore implements plugins.flexharness.IFlexHarnessStores {
3744
3856
  const session = this.database.createSession();
3745
3857
  try {
3746
3858
  await session.withTransaction(async (transaction) => {
3747
- await this.renewLeaseInTransaction(optionsArg.lease, transaction);
3859
+ await this.renewLeaseAndCountWrite(
3860
+ optionsArg.lease,
3861
+ transaction,
3862
+ optionsArg.deletesWriteWitness === true,
3863
+ );
3748
3864
  await this.applyHeadMutation(optionsArg, transaction);
3749
3865
  }, {
3750
3866
  timeoutMS: Math.max(1, deadline - Date.now()),
@@ -3802,12 +3918,20 @@ export class FlexStore implements plugins.flexharness.IFlexHarnessStores {
3802
3918
  }
3803
3919
 
3804
3920
  /**
3805
- * Renews the held lease inside a transaction, so the transaction commits only while this store
3806
- * still owns the lease and a concurrent takeover conflicts with it.
3921
+ * The first step of both Flex namespace write transactions (`commitHeadMutationWithLease`,
3922
+ * `deleteScopeRecordBatchWithLease`) and of nothing else. It renews the held lease, so the
3923
+ * transaction commits only while this store still owns the lease and a concurrent takeover
3924
+ * conflicts with it, and counts the write in the namespace's witness (`flex_namespace_writes`):
3925
+ * a write of a storage key whose provenance FlexHarness activated (`knownWriteKeys`) requires
3926
+ * every earlier write to be known and counts itself as known; any other write counts as unknown.
3927
+ * A known write that finds an unknown one fails with `FlexHarnessStoreFormatError`, so the
3928
+ * transaction and its data write abort. Acquiring, renewing and taking over a lease never count.
3929
+ * Only a purge's last step, which deletes the witness itself, skips the count.
3807
3930
  */
3808
- private async renewLeaseInTransaction(
3931
+ private async renewLeaseAndCountWrite(
3809
3932
  leaseArg: IFlexHeldLease,
3810
3933
  transactionArg: plugins.nosqldb.SmartdataSession,
3934
+ deletesWriteWitnessArg = false,
3811
3935
  ): Promise<void> {
3812
3936
  const current = await this.readLease(leaseArg.storageKey, { session: transactionArg });
3813
3937
  const now = Date.now();
@@ -3822,6 +3946,224 @@ export class FlexStore implements plugins.flexharness.IFlexHarnessStores {
3822
3946
  },
3823
3947
  }, { session: transactionArg });
3824
3948
  if (renewal.status !== 'transitioned') throw new FlexLeaseLostError(leaseArg.storageKey);
3949
+ if (deletesWriteWitnessArg) return;
3950
+
3951
+ const storageKey = leaseArg.storageKey;
3952
+ const known = this.knownWriteKeys.has(storageKey);
3953
+ const witness = await this.readNamespaceWrites(storageKey, { session: transactionArg });
3954
+ if (!witness) {
3955
+ if (known) {
3956
+ throw new plugins.flexharness.FlexHarnessStoreFormatError(
3957
+ `Flex namespace "${storageKey}" lost its write witness; it needs explicit qualification.`,
3958
+ );
3959
+ }
3960
+ const inserted = await FlexNamespaceWritesModel.exact.insert({
3961
+ id: flexNamespaceWritesId(this.controllerId, storageKey),
3962
+ controllerId: this.controllerId,
3963
+ storageKey,
3964
+ writeCount: 1,
3965
+ knownWriteCount: 0,
3966
+ }, { session: transactionArg });
3967
+ if (inserted.status !== 'inserted') {
3968
+ throw new Error(`The write witness of Flex namespace "${storageKey}" changed concurrently.`);
3969
+ }
3970
+ return;
3971
+ }
3972
+ const counts = namespaceWritesBody(witness);
3973
+ if (known && counts.writeCount !== counts.knownWriteCount) {
3974
+ throw new plugins.flexharness.FlexHarnessStoreFormatError(
3975
+ `Flex namespace "${storageKey}" holds writes its witness does not know `
3976
+ + `(${counts.writeCount} writes, ${counts.knownWriteCount} known); it needs explicit qualification.`,
3977
+ );
3978
+ }
3979
+ if (counts.writeCount >= Number.MAX_SAFE_INTEGER) {
3980
+ throw new plugins.flexharness.FlexHarnessStoreFormatError(
3981
+ `The write witness of Flex namespace "${storageKey}" is exhausted.`,
3982
+ );
3983
+ }
3984
+ const counted = await FlexNamespaceWritesModel.exact.transition({
3985
+ current: witness,
3986
+ change: (model) => {
3987
+ model.writeCount = counts.writeCount + 1;
3988
+ if (known) model.knownWriteCount = counts.knownWriteCount + 1;
3989
+ },
3990
+ }, { session: transactionArg });
3991
+ if (counted.status !== 'transitioned') {
3992
+ throw new Error(`The write witness of Flex namespace "${storageKey}" changed concurrently.`);
3993
+ }
3994
+ }
3995
+
3996
+ private async readNamespaceWrites(
3997
+ storageKeyArg: string,
3998
+ optionsArg?: plugins.nosqldb.IExactBoundedOptions,
3999
+ ): Promise<TStoredNamespaceWrites | null> {
4000
+ const id = flexNamespaceWritesId(this.controllerId, storageKeyArg);
4001
+ const witness = await FlexNamespaceWritesModel.exact.findStoredOne({ id }, optionsArg);
4002
+ if (!witness) return null;
4003
+ const body = namespaceWritesBody(witness);
4004
+ assertFlexNamespaceWritesDocument(body);
4005
+ if (body.controllerId !== this.controllerId || body.storageKey !== storageKeyArg) {
4006
+ throw new plugins.flexharness.FlexHarnessStoreFormatError('Flex namespace write witness identity mismatch.');
4007
+ }
4008
+ return witness;
4009
+ }
4010
+
4011
+ private async readScopeRecovery(
4012
+ storageKeyArg: string,
4013
+ optionsArg?: IFlexReadOptions,
4014
+ ): Promise<TStoredScopeRecovery | null> {
4015
+ const id = flexScopeRecoveryId(this.controllerId, storageKeyArg);
4016
+ const stored = await FlexScopeRecoveryModel.exact.findStoredOne({ id }, optionsArg);
4017
+ if (!stored) return null;
4018
+ const body = scopeRecoveryBody(stored);
4019
+ assertFlexScopeRecoveryDocument(body);
4020
+ if (body.controllerId !== this.controllerId || body.storageKey !== storageKeyArg) {
4021
+ throw new plugins.flexharness.FlexHarnessStoreFormatError('Flex scope recovery identity mismatch.');
4022
+ }
4023
+ return stored;
4024
+ }
4025
+
4026
+ /**
4027
+ * True only when the namespace's witness exists and knows every write; then this store records
4028
+ * its writes of the key as known. An absent witness is unqualified whatever the namespace holds:
4029
+ * the store never assumes an empty namespace is new. Reads metadata only.
4030
+ */
4031
+ private async loadWriteProvenance(storageKeyArg: string): Promise<boolean> {
4032
+ assertIdentifier(storageKeyArg, 'storageKey');
4033
+ await this.init();
4034
+ const witness = await this.readNamespaceWrites(storageKeyArg);
4035
+ const counts = witness ? namespaceWritesBody(witness) : undefined;
4036
+ if (counts && counts.writeCount === counts.knownWriteCount) {
4037
+ this.knownWriteKeys.add(storageKeyArg);
4038
+ return true;
4039
+ }
4040
+ this.knownWriteKeys.delete(storageKeyArg);
4041
+ if (!this.unqualifiedProvenance.has(storageKeyArg)) {
4042
+ this.unqualifiedProvenance.set(storageKeyArg, counts
4043
+ ? {
4044
+ storageKey: storageKeyArg,
4045
+ reason: 'stale',
4046
+ writeCount: counts.writeCount,
4047
+ knownWriteCount: counts.knownWriteCount,
4048
+ }
4049
+ : { storageKey: storageKeyArg, reason: 'absent' });
4050
+ }
4051
+ return false;
4052
+ }
4053
+
4054
+ /**
4055
+ * Marks every write so far as known, in the storage key's writer turn under its lease, and records
4056
+ * this store's later writes as known. FlexHarness calls it only at the end of an explicit
4057
+ * qualification (`prepareScope` with `qualifyLegacy`), after its complete load and repair.
4058
+ */
4059
+ private async qualifyWriteProvenance(storageKeyArg: string): Promise<void> {
4060
+ assertIdentifier(storageKeyArg, 'storageKey');
4061
+ await this.runStorage(storageKeyArg, async () => {
4062
+ const witness = await this.readNamespaceWrites(storageKeyArg);
4063
+ if (!witness) {
4064
+ const inserted = await FlexNamespaceWritesModel.exact.insert({
4065
+ id: flexNamespaceWritesId(this.controllerId, storageKeyArg),
4066
+ controllerId: this.controllerId,
4067
+ storageKey: storageKeyArg,
4068
+ writeCount: 0,
4069
+ knownWriteCount: 0,
4070
+ });
4071
+ if (inserted.status !== 'inserted') {
4072
+ throw new plugins.flexharness.FlexHarnessStoreConflictError(storageKeyArg, 0, 0);
4073
+ }
4074
+ return;
4075
+ }
4076
+ const counts = namespaceWritesBody(witness);
4077
+ if (counts.knownWriteCount === counts.writeCount) return;
4078
+ const qualified = await FlexNamespaceWritesModel.exact.transition({
4079
+ current: witness,
4080
+ change: (model) => {
4081
+ model.knownWriteCount = counts.writeCount;
4082
+ },
4083
+ });
4084
+ if (qualified.status !== 'transitioned') {
4085
+ throw new plugins.flexharness.FlexHarnessStoreConflictError(
4086
+ storageKeyArg,
4087
+ counts.knownWriteCount,
4088
+ counts.writeCount,
4089
+ );
4090
+ }
4091
+ });
4092
+ this.knownWriteKeys.add(storageKeyArg);
4093
+ const qualification = this.unqualifiedProvenance.get(storageKeyArg)
4094
+ ?? { storageKey: storageKeyArg, reason: 'absent' as const };
4095
+ this.unqualifiedProvenance.delete(storageKeyArg);
4096
+ try {
4097
+ this.onWriteProvenanceQualified?.(structuredClone(qualification));
4098
+ } catch { /* A report never fails the qualification. */ }
4099
+ }
4100
+
4101
+ private async loadScopeRecovery(
4102
+ storageKeyArg: string,
4103
+ ): Promise<plugins.flexharness.IFlexScopeRecoverySnapshot | undefined> {
4104
+ assertIdentifier(storageKeyArg, 'storageKey');
4105
+ await this.init();
4106
+ const stored = await this.readScopeRecovery(storageKeyArg);
4107
+ return stored ? structuredClone(scopeRecoveryBody(stored).proof) : undefined;
4108
+ }
4109
+
4110
+ /** A compare-and-swap on the proof's revision through the namespace's head mutation path. */
4111
+ private async saveScopeRecovery(
4112
+ storageKeyArg: string,
4113
+ snapshotArg: plugins.flexharness.IFlexScopeRecoverySnapshot,
4114
+ expectedRevisionArg: number,
4115
+ ): Promise<void> {
4116
+ assertIdentifier(storageKeyArg, 'storageKey');
4117
+ const proof = plugins.flexharness.validateFlexScopeRecoverySave(snapshotArg, expectedRevisionArg);
4118
+ await this.runStorage(storageKeyArg, async (lease) => {
4119
+ const current = await this.readScopeRecovery(storageKeyArg);
4120
+ const actualRevision = current ? scopeRecoveryBody(current).proof.revision : 0;
4121
+ if (actualRevision !== expectedRevisionArg) {
4122
+ throw new plugins.flexharness.FlexHarnessStoreConflictError(
4123
+ storageKeyArg,
4124
+ expectedRevisionArg,
4125
+ actualRevision,
4126
+ );
4127
+ }
4128
+ const next: IFlexScopeRecoveryDocument = {
4129
+ id: flexScopeRecoveryId(this.controllerId, storageKeyArg),
4130
+ controllerId: this.controllerId,
4131
+ storageKey: storageKeyArg,
4132
+ proof,
4133
+ };
4134
+ assertFlexScopeRecoveryDocument(next);
4135
+ try {
4136
+ await this.commitHeadMutation({
4137
+ lease,
4138
+ exact: FlexScopeRecoveryModel.exact,
4139
+ current,
4140
+ next,
4141
+ readCurrent: (options) => this.readScopeRecovery(storageKeyArg, options),
4142
+ project: scopeRecoveryBody,
4143
+ targetName: `scope-recovery:${next.id}`,
4144
+ });
4145
+ } catch (errorArg) {
4146
+ if (errorArg instanceof FlexHeadCasError) {
4147
+ const stored = await this.readScopeRecovery(storageKeyArg);
4148
+ throw new plugins.flexharness.FlexHarnessStoreConflictError(
4149
+ storageKeyArg,
4150
+ expectedRevisionArg,
4151
+ stored ? scopeRecoveryBody(stored).proof.revision : 0,
4152
+ );
4153
+ }
4154
+ if (
4155
+ errorArg instanceof plugins.nosqldb.SmartdataExactPersistenceError
4156
+ && errorArg.code === 'ambiguous_write'
4157
+ ) {
4158
+ throw new plugins.flexharness.FlexHarnessStoreCommitUncertainError(
4159
+ storageKeyArg,
4160
+ 'write',
4161
+ { cause: errorArg },
4162
+ );
4163
+ }
4164
+ throw errorArg;
4165
+ }
4166
+ });
3825
4167
  }
3826
4168
 
3827
4169
  private async applyHeadMutation<THead extends object>(
@@ -3928,7 +4270,7 @@ export class FlexStore implements plugins.flexharness.IFlexHarnessStores {
3928
4270
  const session = this.database.createSession();
3929
4271
  try {
3930
4272
  await session.withTransaction(async (transaction) => {
3931
- await this.renewLeaseInTransaction(leaseArg, transaction);
4273
+ await this.renewLeaseAndCountWrite(leaseArg, transaction);
3932
4274
  await recordModelArg.atomicDeleteMany(batch, { session: transaction });
3933
4275
  }, {
3934
4276
  timeoutMS: Math.max(1, deadline - Date.now()),
@@ -0,0 +1,89 @@
1
+ import * as plugins from './plugins.js';
2
+ import type { IControllerFlexSubmissionReceipt } from '../ts_interfaces/index.js';
3
+
4
+ /**
5
+ * A submission's identity and the digest of its immutable input, nothing more: the text and the
6
+ * attachments live in the pending row while the message waits and leave with it, so a receipt
7
+ * never repeats input or keeps an attachment set alive. Receipts live as long as their project.
8
+ */
9
+ export interface IFlexSubmissionContent {
10
+ version: 1;
11
+ digest: string;
12
+ receipt: IControllerFlexSubmissionReceipt;
13
+ }
14
+
15
+ export interface IFlexAdmissionConversationContent {
16
+ version: 1;
17
+ sessionId: IControllerFlexSubmissionReceipt['sessionId'];
18
+ sessionGenerationId: string;
19
+ sessionGenerationSequence?: number;
20
+ sessionIdentityId?: string;
21
+ clientConversationId?: string;
22
+ title?: string;
23
+ scratchpad?: string;
24
+ configurationRevision?: string;
25
+ creationOperationId?: string;
26
+ creationRequestedAt?: number;
27
+ /** The next durable admission sequence. Native completion never determines this order. */
28
+ sequence: number;
29
+ creation: IControllerFlexSubmissionReceipt['creation'];
30
+ }
31
+
32
+ export interface IFlexSubmissionDocument { id: string; controllerId: string; projectId: string; content: IFlexSubmissionContent }
33
+ export interface IFlexAdmissionConversationDocument { id: string; controllerId: string; projectId: string; content: IFlexAdmissionConversationContent }
34
+
35
+ const object = (valueArg: unknown): valueArg is Record<string, unknown> => !!valueArg && typeof valueArg === 'object' && !Array.isArray(valueArg)
36
+ && (Object.getPrototypeOf(valueArg) === Object.prototype || Object.getPrototypeOf(valueArg) === null);
37
+ const base = (valueArg: unknown): valueArg is Record<string, unknown> => object(valueArg) && Object.keys(valueArg).length === 4
38
+ && typeof valueArg.id === 'string' && /^[A-Za-z0-9_-]{43}$/u.test(valueArg.id)
39
+ && typeof valueArg.controllerId === 'string' && /^controller:[1-9][0-9]{0,4}$/u.test(valueArg.controllerId)
40
+ && typeof valueArg.projectId === 'string' && /^[A-Za-z0-9_-]{22}$/u.test(valueArg.projectId) && object(valueArg.content);
41
+ const generation = (valueArg: Record<string, unknown>): boolean => object(valueArg.sessionId) && valueArg.sessionId.harnessId === 'flex'
42
+ && typeof valueArg.sessionId.nativeId === 'string' && valueArg.sessionId.nativeId.length > 0
43
+ && typeof valueArg.sessionGenerationId === 'string' && /^[A-Za-z0-9_-]{43}$/u.test(valueArg.sessionGenerationId)
44
+ && (valueArg.sessionGenerationSequence === undefined || (Number.isSafeInteger(valueArg.sessionGenerationSequence) && Number(valueArg.sessionGenerationSequence) > 0));
45
+ const assertSubmission: (valueArg: unknown) => asserts valueArg is IFlexSubmissionDocument = valueArg => {
46
+ if (!base(valueArg) || !object(valueArg.content) || Object.keys(valueArg.content).length !== 3 || valueArg.content.version !== 1
47
+ || typeof valueArg.content.digest !== 'string' || !/^[a-f0-9]{64}$/u.test(valueArg.content.digest)
48
+ || !object(valueArg.content.receipt) || !generation(valueArg.content.receipt)
49
+ || valueArg.content.receipt.projectId !== valueArg.projectId
50
+ || typeof valueArg.content.receipt.clientMessageId !== 'string' || valueArg.content.receipt.clientMessageId.length === 0
51
+ || !Number.isSafeInteger(valueArg.content.receipt.serverSequence) || Number(valueArg.content.receipt.serverSequence) < 1
52
+ || typeof valueArg.content.receipt.operationId !== 'string' || !/^[A-Za-z0-9_-]{22}$/u.test(valueArg.content.receipt.operationId)) {
53
+ throw new Error('Invalid immutable Flex submission record.');
54
+ }
55
+ };
56
+ const assertConversation: (valueArg: unknown) => asserts valueArg is IFlexAdmissionConversationDocument = valueArg => {
57
+ if (!base(valueArg) || !object(valueArg.content) || valueArg.content.version !== 1 || !generation(valueArg.content)
58
+ || !Number.isSafeInteger(valueArg.content.sequence) || Number(valueArg.content.sequence) < 0
59
+ || !['pending', 'ready', 'uncertain', 'retired'].includes(String(valueArg.content.creation))) {
60
+ throw new Error('Invalid Flex admission conversation record.');
61
+ }
62
+ };
63
+
64
+ /** The index a project's removal deletes its receipts and conversation intents through, page by page. */
65
+ export const flexSubmissionProjectIndexName = 'agl_flex_submission_project';
66
+ export const flexAdmissionConversationProjectIndexName = 'agl_flex_admission_conversation_project';
67
+
68
+ /** Fixed top-level sidecars: old exact readers never encounter undeclared fields on their models. */
69
+ @plugins.nosqldb.compoundIndex({ name: flexSubmissionProjectIndexName, key: { controllerId: 1, projectId: 1, id: 1 } })
70
+ @plugins.nosqldb.managed({ collectionName: 'agl_flex_submission_receipts' })
71
+ @plugins.nosqldb.exactPersistence({ assertDocument: assertSubmission })
72
+ export class ControllerFlexSubmissionModel extends plugins.nosqldb.SmartDataDbDoc<ControllerFlexSubmissionModel, IFlexSubmissionDocument> {
73
+ declare static exact: plugins.nosqldb.TExact<ControllerFlexSubmissionModel>;
74
+ @plugins.nosqldb.unI() public id!: string;
75
+ @plugins.nosqldb.svDb() public controllerId!: string;
76
+ @plugins.nosqldb.svDb() public projectId!: string;
77
+ @plugins.nosqldb.svDb() public content!: IFlexSubmissionContent;
78
+ }
79
+
80
+ @plugins.nosqldb.compoundIndex({ name: flexAdmissionConversationProjectIndexName, key: { controllerId: 1, projectId: 1, id: 1 } })
81
+ @plugins.nosqldb.managed({ collectionName: 'agl_flex_submission_conversations' })
82
+ @plugins.nosqldb.exactPersistence({ assertDocument: assertConversation })
83
+ export class ControllerFlexAdmissionConversationModel extends plugins.nosqldb.SmartDataDbDoc<ControllerFlexAdmissionConversationModel, IFlexAdmissionConversationDocument> {
84
+ declare static exact: plugins.nosqldb.TExact<ControllerFlexAdmissionConversationModel>;
85
+ @plugins.nosqldb.unI() public id!: string;
86
+ @plugins.nosqldb.svDb() public controllerId!: string;
87
+ @plugins.nosqldb.svDb() public projectId!: string;
88
+ @plugins.nosqldb.svDb() public content!: IFlexAdmissionConversationContent;
89
+ }