@fantastic.dev/better-stripe 0.104.0 → 0.106.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 (70) hide show
  1. package/CHANGELOG.md +12 -0
  2. package/README.md +1 -1
  3. package/dist/client/billing/renewalAttach/internal/c10/configureEvents.d.ts +23 -0
  4. package/dist/client/billing/renewalAttach/internal/c10/configureEvents.d.ts.map +1 -1
  5. package/dist/client/billing/renewalAttach/internal/c10/configureEvents.js +28 -0
  6. package/dist/client/billing/renewalAttach/internal/c10/configureEvents.js.map +1 -1
  7. package/dist/client/billing/renewalAttach/internal/configure/transport.d.ts +300 -0
  8. package/dist/client/billing/renewalAttach/internal/configure/transport.d.ts.map +1 -1
  9. package/dist/client/billing/renewalAttach/internal/configure/transport.js +44 -2
  10. package/dist/client/billing/renewalAttach/internal/configure/transport.js.map +1 -1
  11. package/dist/client/billing/renewalAttach/internal/producer/configureAcknowledgement.d.ts +19 -0
  12. package/dist/client/billing/renewalAttach/internal/producer/configureAcknowledgement.d.ts.map +1 -0
  13. package/dist/client/billing/renewalAttach/internal/producer/configureAcknowledgement.js +11 -0
  14. package/dist/client/billing/renewalAttach/internal/producer/configureAcknowledgement.js.map +1 -0
  15. package/dist/client/billing/renewalAttach/internal/producer/configureAttemptAuthority.d.ts +56 -0
  16. package/dist/client/billing/renewalAttach/internal/producer/configureAttemptAuthority.d.ts.map +1 -0
  17. package/dist/client/billing/renewalAttach/internal/producer/configureAttemptAuthority.js +79 -0
  18. package/dist/client/billing/renewalAttach/internal/producer/configureAttemptAuthority.js.map +1 -0
  19. package/dist/client/billing/renewalAttach/internal/producer/configureFrontier.d.ts +47 -0
  20. package/dist/client/billing/renewalAttach/internal/producer/configureFrontier.d.ts.map +1 -1
  21. package/dist/client/billing/renewalAttach/internal/producer/configureFrontier.js +79 -0
  22. package/dist/client/billing/renewalAttach/internal/producer/configureFrontier.js.map +1 -1
  23. package/dist/client/billing/renewalAttach/internal/producer/configureJournalData.d.ts +25 -0
  24. package/dist/client/billing/renewalAttach/internal/producer/configureJournalData.d.ts.map +1 -1
  25. package/dist/client/billing/renewalAttach/internal/producer/configureJournalData.js +62 -0
  26. package/dist/client/billing/renewalAttach/internal/producer/configureJournalData.js.map +1 -1
  27. package/dist/client/billing/renewalAttach/internal/producer/configureJournalWork.d.ts +14 -0
  28. package/dist/client/billing/renewalAttach/internal/producer/configureJournalWork.d.ts.map +1 -1
  29. package/dist/client/billing/renewalAttach/internal/producer/configureJournalWork.js +17 -0
  30. package/dist/client/billing/renewalAttach/internal/producer/configureJournalWork.js.map +1 -1
  31. package/dist/client/billing/renewalAttach/internal/producer/configureRecovery.d.ts +5 -0
  32. package/dist/client/billing/renewalAttach/internal/producer/configureRecovery.d.ts.map +1 -0
  33. package/dist/client/billing/renewalAttach/internal/producer/configureRecovery.js +259 -0
  34. package/dist/client/billing/renewalAttach/internal/producer/configureRecovery.js.map +1 -0
  35. package/dist/client/billing/renewalAttach/internal/producer/configureWrite.d.ts +7 -0
  36. package/dist/client/billing/renewalAttach/internal/producer/configureWrite.d.ts.map +1 -0
  37. package/dist/client/billing/renewalAttach/internal/producer/configureWrite.js +209 -0
  38. package/dist/client/billing/renewalAttach/internal/producer/configureWrite.js.map +1 -0
  39. package/dist/client/billing/renewalAttach/internal/producer/configureWriteFactory.d.ts +61 -0
  40. package/dist/client/billing/renewalAttach/internal/producer/configureWriteFactory.d.ts.map +1 -0
  41. package/dist/client/billing/renewalAttach/internal/producer/configureWriteFactory.js +73 -0
  42. package/dist/client/billing/renewalAttach/internal/producer/configureWriteFactory.js.map +1 -0
  43. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts +32 -32
  44. package/dist/client/connect/payoutSyncTestHelpers.d.ts +16 -16
  45. package/dist/component/balanceFunding/mutations.d.ts +27 -27
  46. package/dist/component/balanceFunding/preparationHandlers.d.ts +8 -8
  47. package/dist/component/balanceFunding/stateHandlers.d.ts +8 -8
  48. package/dist/component/earnings/triggers.d.ts +16 -16
  49. package/dist/component/payoutRelease/queries.d.ts +2 -2
  50. package/dist/component/payoutRelease/queries.d.ts.map +1 -1
  51. package/dist/component/processingCostReconciliation/rollback.d.ts +1 -1
  52. package/dist/component/usage/allowance.fixtures.d.ts +16 -16
  53. package/dist/component/usageCredits/accounting.fixtures.d.ts +16 -16
  54. package/docs/renewal-context-reads.md +99 -4
  55. package/package.json +1 -1
  56. package/src/client/billing/renewalAttach/internal/c10/configureEvents.ts +37 -0
  57. package/src/client/billing/renewalAttach/internal/configure/transport.ts +64 -2
  58. package/src/client/billing/renewalAttach/internal/producer/configureAcknowledgement.ts +11 -0
  59. package/src/client/billing/renewalAttach/internal/producer/configureAttemptAuthority.ts +121 -0
  60. package/src/client/billing/renewalAttach/internal/producer/configureFrontier.ts +155 -0
  61. package/src/client/billing/renewalAttach/internal/producer/configureJournalData.ts +84 -0
  62. package/src/client/billing/renewalAttach/internal/producer/configureJournalWork.ts +16 -0
  63. package/src/client/billing/renewalAttach/internal/producer/configureRecovery.ts +361 -0
  64. package/src/client/billing/renewalAttach/internal/producer/configureWrite.ts +288 -0
  65. package/src/client/billing/renewalAttach/internal/producer/configureWriteFactory.ts +88 -0
  66. package/src/client/billing/renewalAttach/internal/producer/producerConfigureRecovery.integration.test.ts +99 -0
  67. package/src/client/billing/renewalAttach/internal/producer/producerConfigureRecoveryControls.integration.test.ts +420 -0
  68. package/src/client/billing/renewalAttach/internal/producer/producerConfigureWrite.integration.test.ts +158 -0
  69. package/src/client/billing/renewalAttach/internal/producer/producerConfigureWriteControls.integration.test.ts +537 -0
  70. package/src/client/billing/renewalAttach/internal/test-fixtures/producerConfigureAdmission.ts +85 -2
@@ -263,7 +263,7 @@ call.
263
263
 
264
264
  The result is an opaque private view containing `owner`, `basisJSON` and
265
265
  `operationalAuthority: false`. The separate private C10 factory below can use
266
- that identity. Configure write transport, write actors and public scheduling
266
+ that identity. Cross-process configure recovery and public scheduling
267
267
  remain required, as do genuine generation and operational qualification.
268
268
  Production Source profile arrays remain empty.
269
269
 
@@ -299,9 +299,9 @@ a committed response or receipt event, and a retained C9 do not establish provid
299
299
  custody, returned configure ACK custody, pending/effective replacement or fresh
300
300
  dispatch permission. Receipt retention remains a separate operation; a future
301
301
  configure completion pipeline must retain the complete C9 before publishing
302
- receipt event 3 and returning its actual acknowledgement. Future execution also
303
- requires its own frontier checks. This channel factory supplies no provider
304
- transport or write actor and activates no operational Source profile.
302
+ receipt event 3 and returning its actual acknowledgement. Execution requires its
303
+ own frontier checks. This channel factory supplies no provider transport and
304
+ activates no operational Source profile.
305
305
 
306
306
  ## Private admitted configure preflight
307
307
 
@@ -335,6 +335,101 @@ the actor. The legacy preflight functions retain their original Owner checks
335
335
  around shared DATA kernels. This readonly consistency result grants no configure
336
336
  POST permission, returned configure ACK custody or public scheduling support.
337
337
 
338
+ ## Private admitted configure write
339
+
340
+ `captureAdmittedConfigureWrite(token)` captures one initial write actor from the
341
+ actual completed preflight view. It retains the actual parent ACK, original
342
+ profile entry and preflight predicate pointers. A unique compiled write entry
343
+ must link to that original entry, and its predicate identity remains fixed.
344
+ Copied tokens, output DATA, pending preflight and replacement arguments cannot
345
+ supply custody. Production profile arrays remain empty.
346
+
347
+ The write transport preserves the legacy POST latch and quarantine kernel while
348
+ using the admitted child's original parent Owner and stock SDK delegate. It
349
+ performs its own fixed fresh GET sequence. The separate readonly preflight output
350
+ cannot mark this pair's read generation complete. Current reads and a fresh C6
351
+ reconstruction must still match the retained request exactly, including its key,
352
+ first-dispatch time, path, payload and API version.
353
+
354
+ Before dispatch intent, the actor checks the complete head-zero frontier. It
355
+ awaits the actual committed dispatch event 1 and C10 ACK, then checks full stored
356
+ event DATA, basis, absent acknowledgement, idle journal work and exact head one
357
+ before POST. Each invocation permits at most one POST, with the retained key and
358
+ zero retries. These checks are bounded read fences, not an atomic writer lock.
359
+ The transport marks uncertainty before calling the stock delegate. Synchronous
360
+ throws or non-Promise results cannot establish a proven provider rejection.
361
+
362
+ Fulfillment enters quarantine before response inspection or Owner checks. Only
363
+ safe captured response DATA can publish event 2. After actual C9 construction,
364
+ the actor records the receipt as known, durably retains its complete canonical
365
+ JSON at head two, validates the complete retention reply and reads it back.
366
+ Retention precedes whole-output admission and receipt event 3. Output refusal,
367
+ pending or rejected persistence replies, or failed event-3 publication cannot
368
+ permit another POST or establish a returned ACK. A private live attempt view
369
+ retains immutable actual C9/input DATA and POST disposition independently of the
370
+ returned ACK view. Copied tokens cannot read it, and the view grants no replay
371
+ or dispatch permission.
372
+
373
+ `readAdmittedConfigureAcknowledgement(token)` returns custody only after receipt
374
+ event 3 commits, its actual C10 ACK returns and the final complete history and
375
+ retention fence passes. The view retains the exact returned output and its
376
+ receipt/raw-receipt identities. A final guard precedes quarantine discard with
377
+ no intervening callback or Owner sample. Late fulfillment after retirement stays
378
+ unknown and cannot publish ACK custody. This initial-write actor never replays itself. Separate recovery remains explicit;
379
+ public scheduling and pending/effective acceptance remain outstanding.
380
+
381
+ ## Private same-live-Owner configure recovery
382
+
383
+ `captureAdmittedConfigureRecovery(token)` synchronously reserves one recovery
384
+ from the actual original child attempt before its first await. The original
385
+ invocation must have started and settled, with idle journal work and no returned
386
+ ACK. The attempt retains its actual qualified pair, original fresh evidence,
387
+ preflight/profile pointers, immutable C7 and any owned safe response/C9/retention
388
+ reply. A disposition marker, copied token or journal DATA cannot supply that
389
+ custody. The original Owner, SDK client, method, basis and deadlines remain fixed.
390
+ Production Source profile arrays remain empty.
391
+
392
+ `NOT_STARTED`, `PENDING`, unsettled invocations and pending journal RPCs refuse.
393
+ A committed row does not establish that its actual RPC reply returned. Recovery
394
+ also refuses `FULFILLED_SAFE` without the actual saved response or C9. The write
395
+ producer saves that safe response before awaiting response-event publication;
396
+ a failed response append therefore cannot turn an owned response into permission
397
+ for another POST.
398
+
399
+ Unknown replay requires no owned response/C9, exact dispatch-only history and no
400
+ known acknowledgement. A distinct replay transport performs its own fixed fresh
401
+ GET generation. Complete raw baseline equality, fresh C6 reconstruction and the
402
+ captured write predicate must preserve the original C7, key and first-dispatch
403
+ time. Retention requires `0 <= now - originalFirstDispatch < 86400` before
404
+ acquisition and again immediately before POST. The original Owner must still be
405
+ live; this scalar rule never revives it. The actor re-ACKs the identical dispatch
406
+ DATA and repeats the full head-one/ACK-null/idle fence before its single replay
407
+ POST, with zero retries. Baseline drift or an already-applied state never becomes
408
+ a newly projected request.
409
+
410
+ Owned safe-response or C9 completion performs no provider GET or POST. It checks
411
+ the complete existing journal prefix against that actual custody, uses a distinct
412
+ original-journal sender, and re-ACKs or completes matching dispatch/response DATA.
413
+ A stopped original sender cannot be reopened. The actor constructs missing C9
414
+ from the owned response, retains complete canonical C9 and validates retention
415
+ reply/readback before whole-output admission or receipt event three. Matching
416
+ head-three DATA can be re-ACKed after a lost append reply. Every observed retained
417
+ descriptor must stay identical; conflicts refuse without repair. An output-budget
418
+ failure stays unknown with its complete known receipt, never truncated DATA.
419
+
420
+ The unified `readAdmittedConfigureAcknowledgement(token)` returns only actual
421
+ initial or recovered completion. Its output and receipt/raw-receipt identities
422
+ come from the actual returned wrapper. There is no caller receipt/output
423
+ registration API. Final guards precede quarantine discard without intervening
424
+ callbacks. Pending work, retirement or observed pointer changes cannot publish
425
+ late ACK custody or create another recovery reservation.
426
+
427
+ These are bounded read fences, not an atomic provider-writer lock. The recovery
428
+ is process-local and uses the same live Owner; persisted DATA cannot create a new
429
+ Owner or a cross-process execution grant. Public scheduling, cross-process
430
+ recovery, genuine generated/deployed compatibility, provider/native qualification
431
+ and complete Dojo adoption remain separate acceptance work.
432
+
338
433
  ## Component operation journal
339
434
 
340
435
  The component's `renewalOperations` functions retain host-authorized operation
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fantastic.dev/better-stripe",
3
- "version": "0.104.0",
3
+ "version": "0.106.0",
4
4
  "description": "Convex component for Stripe Accounts v2, subscriptions, metered billing and Connect marketplaces, with React workflows.",
5
5
  "keywords": [
6
6
  "stripe",
@@ -1,3 +1,4 @@
1
+ import { readConfigureRecoveryAuthority } from "../producer/configureAttemptAuthority.js";
1
2
  import type { CapturedNode } from "./eventCodec.js";
2
3
  import type {
3
4
  ProjectedRenewalConfigurationV2,
@@ -58,6 +59,42 @@ export function createAdmittedConfigureEventCompiler(token: object) {
58
59
  );
59
60
  return configureEventCompiler(lineage.configuration, channel);
60
61
  }
62
+ const recoveryChannels = new WeakSet<object>();
63
+ /** Distinct original-journal sender after synchronous actual recovery reservation. */
64
+ export function createRecoveryConfigureEventCompiler(recovery: object) {
65
+ need(
66
+ typeof recovery === "object" &&
67
+ recovery !== null &&
68
+ !recoveryChannels.has(recovery),
69
+ );
70
+ recoveryChannels.add(recovery);
71
+ need(arguments.length === 1);
72
+ const state = readConfigureRecoveryAuthority(recovery);
73
+ const lineage = readConfigureLineage(state.token);
74
+ const guard = () => {
75
+ readConfigureRecoveryAuthority(recovery);
76
+ };
77
+ const send = journalWorkForConfigureLineage(state.token).captureSend();
78
+ const channel = createGuardedInitialStageChannel(
79
+ lineage.parentToken,
80
+ {
81
+ timeoutMs: 5000,
82
+ send(
83
+ record: Parameters<typeof send>[0],
84
+ ack: Parameters<typeof send>[1],
85
+ ) {
86
+ guard();
87
+ return send(record, (value) => {
88
+ guard();
89
+ ack(value);
90
+ guard();
91
+ });
92
+ },
93
+ },
94
+ guard,
95
+ );
96
+ return configureEventCompiler(lineage.configuration, channel);
97
+ }
61
98
  function configureEventCompiler(
62
99
  raw: unknown,
63
100
  channel: ReturnType<typeof createStageChannel>,
@@ -1,5 +1,6 @@
1
1
  import { types } from "node:util";
2
2
  import { OWNER } from "../originalOwner.js";
3
+ import { captureAdmittedConfigureWriteFrame } from "../producer/configureWriteFactory.js";
3
4
  import { closed } from "../operations/types.js";
4
5
  import { equal } from "../../../renewalAggregate/shared.js";
5
6
  import {
@@ -34,6 +35,13 @@ function build(load: () => unknown) {
34
35
  OWNER.check();
35
36
  const raw = load();
36
37
  OWNER.check();
38
+ return configureWriteKernel(raw, OWNER);
39
+ }
40
+ function configureWriteKernel(
41
+ raw: unknown,
42
+ owner: typeof OWNER,
43
+ guard?: () => void,
44
+ ) {
37
45
  need(!types.isProxy(raw));
38
46
  const frame = closed(raw, [
39
47
  "owner",
@@ -42,7 +50,7 @@ function build(load: () => unknown) {
42
50
  "readPlan",
43
51
  "delegate",
44
52
  ]);
45
- need(frame.owner === OWNER);
53
+ need(frame.owner === owner);
46
54
  const operation = frame.operation,
47
55
  readPlanReference = frame.readPlan,
48
56
  delegate = frame.delegate;
@@ -77,7 +85,9 @@ function build(load: () => unknown) {
77
85
  }
78
86
  checking = true;
79
87
  try {
80
- OWNER.check();
88
+ guard?.();
89
+ owner.check();
90
+ guard?.();
81
91
  if (closedOwner) stop();
82
92
  } catch {
83
93
  closedOwner = true;
@@ -346,3 +356,55 @@ export function createConfigureReplayTransport() {
346
356
  need(arguments.length === 0);
347
357
  return build(loadConfigureReplayTransportSource);
348
358
  }
359
+
360
+ type QualifiedPair = ReturnType<typeof qualifiedWrite>;
361
+ const qualifiedWrites = new WeakMap<object, QualifiedPair>();
362
+ const replayCaptures = new WeakSet<object>();
363
+ function bindQualified(
364
+ source: ReturnType<typeof captureAdmittedConfigureWriteFrame>,
365
+ token: object,
366
+ ) {
367
+ const pair = configureWriteKernel(source.frame, source.owner, source.guard);
368
+ need(
369
+ pair.capability.assertSourceOperationBinding(
370
+ token,
371
+ source.record.request,
372
+ source.frame.readPlan,
373
+ source.frame.delegate,
374
+ source.frame.delegate.rawRequest,
375
+ source.expected,
376
+ ),
377
+ );
378
+ need(pair.capability.reserveAcquisition());
379
+ source.guard();
380
+ return Object.freeze({ ...source, ...pair });
381
+ }
382
+ function qualifiedWrite(token: object, arity: number) {
383
+ return bindQualified(captureAdmittedConfigureWriteFrame(token, arity), token);
384
+ }
385
+ /** Actual completed preflight custody only; no caller-supplied frame or Owner. */
386
+ export function createAdmittedConfigureWriteTransport(token: object) {
387
+ const pair = qualifiedWrite(token, arguments.length);
388
+ qualifiedWrites.set(token, pair);
389
+ return pair;
390
+ }
391
+ /** Original actual pair identity for trusted producers, never reconstructed DATA. */
392
+ export function readOriginalConfigureWriteTransport(token: object) {
393
+ need(arguments.length === 1);
394
+ const pair = qualifiedWrites.get(token);
395
+ need(pair);
396
+ pair.guard();
397
+ return pair;
398
+ }
399
+ /** Separate read generation; explicit recovery admission remains required by its actor. */
400
+ export function createAdmittedConfigureReplayTransport(token: object) {
401
+ need(
402
+ typeof token === "object" && token !== null && !replayCaptures.has(token),
403
+ );
404
+ replayCaptures.add(token);
405
+ need(arguments.length === 1);
406
+ const source = readOriginalConfigureWriteTransport(token);
407
+ const disposition = source.transport.postDisposition();
408
+ need(disposition === "REJECTED" || disposition === "FULFILLED_UNVERIFIED");
409
+ return bindQualified(source, token);
410
+ }
@@ -0,0 +1,11 @@
1
+ import { readOriginalConfigureAttempt } from "./configureAttemptAuthority.js";
2
+ import { need } from "../configure/request.js";
3
+ /** Actual returned initial/recovered output identity, never a receipt registration API. */
4
+ export function readAdmittedConfigureAcknowledgement(token: object) {
5
+ need(arguments.length === 1);
6
+ const attempt = readOriginalConfigureAttempt(token),
7
+ completed = attempt.completion;
8
+ need(completed);
9
+ completed.guard();
10
+ return completed.view;
11
+ }
@@ -0,0 +1,121 @@
1
+ import { readOriginalConfigureWriteTransport } from "../configure/transport.js";
2
+ import { need } from "../configure/request.js";
3
+ import { journalWorkForConfigureLineage } from "./configureJournalWork.js";
4
+ import type { CurrentEvidence } from "../preflight/grammar.js";
5
+ import type { checkConfigureRetention } from "./configureJournalData.js";
6
+ import type {
7
+ ConstructRenewalConfigurationReceiptV2Options,
8
+ RenewalConfigurationReceiptV2,
9
+ } from "../../../renewalV2/index.js";
10
+
11
+ type Pair = ReturnType<typeof readOriginalConfigureWriteTransport>;
12
+ export type ConfigureCompletion = Readonly<{
13
+ output: unknown;
14
+ receipt: unknown;
15
+ rawReceipt: unknown;
16
+ acknowledgement: Pair["preflight"]["acknowledgement"];
17
+ originalEntry: unknown;
18
+ configureEntry: unknown;
19
+ coversConfigure: unknown;
20
+ operationalAuthority: false;
21
+ }>;
22
+ export type ConfigureAttempt = {
23
+ pair: Pair;
24
+ started: boolean;
25
+ settled: boolean;
26
+ recoveryReserved: boolean;
27
+ freshEvidence: CurrentEvidence | null;
28
+ recoveryEvidence: CurrentEvidence | null;
29
+ response: Readonly<{
30
+ body: Record<string, unknown>;
31
+ transport: ConstructRenewalConfigurationReceiptV2Options["transport"];
32
+ }> | null;
33
+ receipt: RenewalConfigurationReceiptV2 | null;
34
+ rawReceipt: ConstructRenewalConfigurationReceiptV2Options | null;
35
+ retention: ReturnType<typeof checkConfigureRetention> | null;
36
+ completion: { view: ConfigureCompletion; guard: () => void } | null;
37
+ };
38
+ const attempts = new WeakMap<object, ConfigureAttempt>();
39
+ const recoveries = new WeakMap<
40
+ object,
41
+ { token: object; attempt: ConfigureAttempt }
42
+ >();
43
+ /** Only the original, internally constructed pair can create this private attempt. */
44
+ export function createConfigureWriteAttempt(token: object, pair: Pair) {
45
+ need(arguments.length === 2 && !attempts.has(token));
46
+ need(readOriginalConfigureWriteTransport(token) === pair);
47
+ const attempt: ConfigureAttempt = {
48
+ pair,
49
+ started: false,
50
+ settled: false,
51
+ recoveryReserved: false,
52
+ freshEvidence: null,
53
+ recoveryEvidence: null,
54
+ response: null,
55
+ receipt: null,
56
+ rawReceipt: null,
57
+ retention: null,
58
+ completion: null,
59
+ };
60
+ attempts.set(token, attempt);
61
+ return attempt;
62
+ }
63
+ export function readOriginalConfigureAttempt(token: object) {
64
+ need(arguments.length === 1);
65
+ const attempt = attempts.get(token);
66
+ need(attempt);
67
+ need(readOriginalConfigureWriteTransport(token) === attempt.pair);
68
+ return attempt;
69
+ }
70
+ /** Reserve original runtime custody synchronously, before any recovery await. */
71
+ export function takeOriginalConfigureRecovery(token: object, arity: number) {
72
+ const attempt = attempts.get(token);
73
+ need(attempt && !attempt.recoveryReserved);
74
+ attempt.recoveryReserved = true;
75
+ need(arity === 1);
76
+ need(readOriginalConfigureAttempt(token) === attempt);
77
+ need(
78
+ attempt.started &&
79
+ attempt.settled &&
80
+ attempt.freshEvidence !== null &&
81
+ attempt.completion === null &&
82
+ journalWorkForConfigureLineage(token).idle(),
83
+ );
84
+ const disposition = attempt.pair.transport.postDisposition();
85
+ need(disposition !== "NOT_STARTED" && disposition !== "PENDING");
86
+ need(
87
+ attempt.response !== null ||
88
+ attempt.receipt !== null ||
89
+ disposition === "REJECTED" ||
90
+ disposition === "FULFILLED_UNVERIFIED",
91
+ );
92
+ const recovery = Object.freeze({ operationalAuthority: false as const });
93
+ recoveries.set(recovery, { token, attempt });
94
+ return recovery;
95
+ }
96
+ export function readConfigureRecoveryAuthority(recovery: object) {
97
+ need(arguments.length === 1);
98
+ const current = recoveries.get(recovery);
99
+ need(current);
100
+ need(
101
+ readOriginalConfigureAttempt(current.token) === current.attempt &&
102
+ current.attempt.recoveryReserved &&
103
+ current.attempt.settled,
104
+ );
105
+ return current;
106
+ }
107
+ /** DATA only. Neither this view nor copied receipts can register recovery or ACK. */
108
+ export function readAdmittedConfigureWriteAttempt(token: object) {
109
+ need(arguments.length === 1);
110
+ const attempt = readOriginalConfigureAttempt(token);
111
+ const view = Object.freeze({
112
+ postDisposition: attempt.pair.transport.postDisposition(),
113
+ receiptKnown: attempt.receipt !== null,
114
+ receipt: attempt.receipt,
115
+ rawReceipt: attempt.rawReceipt,
116
+ returned: attempt.completion !== null,
117
+ operationalAuthority: false as const,
118
+ });
119
+ attempt.pair.guard();
120
+ return view;
121
+ }
@@ -1,3 +1,11 @@
1
+ import { types } from "node:util";
2
+ import { canonicalJournalEvent } from "../../../../../shared/renewalOperationJournal.js";
3
+ import { renewalSnapshot } from "../../../renewalReplacementSnapshot.js";
4
+ import {
5
+ captureConfigureHistory,
6
+ checkConfigureRetention,
7
+ object,
8
+ } from "./configureJournalData.js";
1
9
  import { readConfigureLineage } from "./configureLineage.js";
2
10
  import { ownedAwaitForInitialLineage } from "./ownedAwaitFactory.js";
3
11
  import { journalWorkForConfigureLineage } from "./configureJournalWork.js";
@@ -38,3 +46,150 @@ export async function assertConfigurePreflightFrontier(token: object) {
38
46
  requireConfigure(work.idle());
39
47
  readConfigureLineage(token);
40
48
  }
49
+
50
+ /** Fixed expected event DATA from the actor, verified against full stored events. */
51
+ export async function assertConfigureWriteFrontier(
52
+ token: object,
53
+ expectedEvents: readonly unknown[],
54
+ known: {
55
+ receiptJSON: string;
56
+ receiptBinding: string;
57
+ retention: ReturnType<typeof checkConfigureRetention>;
58
+ } | null = null,
59
+ ) {
60
+ const lineage = readConfigureLineage(token),
61
+ work = journalWorkForConfigureLineage(token);
62
+ const owned = ownedAwaitForInitialLineage(lineage.parentToken);
63
+ async function checked<T>(call: () => T | PromiseLike<T>) {
64
+ readConfigureLineage(token);
65
+ requireConfigure(work.idle());
66
+ const reply = await owned(call);
67
+ readConfigureLineage(token);
68
+ requireConfigure(work.idle());
69
+ return reply;
70
+ }
71
+ const canonical = [];
72
+ for (let i = 0; i < expectedEvents.length; i++) {
73
+ requireConfigure(i < 3);
74
+ canonical.push(
75
+ await checked(() =>
76
+ canonicalJournalEvent(
77
+ i + 1,
78
+ JSON.stringify(renewalSnapshot(expectedEvents[i])),
79
+ ),
80
+ ),
81
+ );
82
+ }
83
+ checkOperationLoad(
84
+ await checked(() => lineage.journal.loadAuthorizedOperation()),
85
+ lineage.reservation,
86
+ lineage.parent.basisJSON,
87
+ );
88
+ const history = await checked(() =>
89
+ lineage.journal.readAttempt({ attemptId: lineage.reservation.attemptId }),
90
+ );
91
+ const events = captureConfigureHistory(
92
+ history,
93
+ lineage.reservation,
94
+ canonical.length,
95
+ );
96
+ for (let i = 0; i < events.length; i++) {
97
+ requireConfigure(events[i].binding === canonical[i].binding);
98
+ matchConfigureDATA(
99
+ await checked(() =>
100
+ lineage.journal.readStageEvent({
101
+ attemptId: lineage.reservation.attemptId,
102
+ sequence: i === 0 ? 1 : i === 1 ? 2 : 3,
103
+ }),
104
+ ),
105
+ { ...events[i], dataJSON: canonical[i].json },
106
+ );
107
+ }
108
+ const ack = await checked(() =>
109
+ lineage.journal.readProviderAcknowledgement(),
110
+ );
111
+ if (known) {
112
+ const own = object(ack);
113
+ matchConfigureDATA(own.retention, known.retention);
114
+ checkConfigureRetention(
115
+ own.retention,
116
+ lineage.reservation,
117
+ events,
118
+ known.receiptBinding,
119
+ );
120
+ matchConfigureDATA(ack, {
121
+ retention: own.retention,
122
+ receiptJSON: known.receiptJSON,
123
+ });
124
+ } else matchConfigureDATA(ack, null);
125
+ // Final complete head read follows ACK and event inspection. This is not a lock.
126
+ matchConfigureDATA(
127
+ await checked(() =>
128
+ lineage.journal.readAttempt({ attemptId: lineage.reservation.attemptId }),
129
+ ),
130
+ { reservation: lineage.reservation, events },
131
+ );
132
+ return events;
133
+ }
134
+
135
+ /** Validate an existing prefix without adopting journal DATA as provider custody. */
136
+ export async function assertConfigureRecoveryPrefix(
137
+ token: object,
138
+ expectedEvents: readonly unknown[],
139
+ known: {
140
+ receiptJSON: string;
141
+ receiptBinding: string;
142
+ retention: ReturnType<typeof checkConfigureRetention> | null;
143
+ } | null,
144
+ ) {
145
+ const lineage = readConfigureLineage(token),
146
+ work = journalWorkForConfigureLineage(token);
147
+ const owned = ownedAwaitForInitialLineage(lineage.parentToken);
148
+ async function checked<T>(call: () => T | PromiseLike<T>) {
149
+ readConfigureLineage(token);
150
+ requireConfigure(work.idle());
151
+ const reply = await owned(call);
152
+ readConfigureLineage(token);
153
+ requireConfigure(work.idle());
154
+ return reply;
155
+ }
156
+ const history: unknown = await checked(() =>
157
+ lineage.journal.readAttempt({ attemptId: lineage.reservation.attemptId }),
158
+ );
159
+ const own = object(history);
160
+ requireConfigure(!types.isProxy(own.events) && Array.isArray(own.events));
161
+ const events = captureConfigureHistory(
162
+ history,
163
+ lineage.reservation,
164
+ own.events.length,
165
+ );
166
+ requireConfigure(events.length <= expectedEvents.length);
167
+ const ack: unknown = await checked(() =>
168
+ lineage.journal.readProviderAcknowledgement(),
169
+ );
170
+ let retention: ReturnType<typeof checkConfigureRetention> | null = null;
171
+ if (ack !== null) {
172
+ requireConfigure(known !== null);
173
+ const reply = object(ack);
174
+ retention = checkConfigureRetention(
175
+ reply.retention,
176
+ lineage.reservation,
177
+ events,
178
+ known.receiptBinding,
179
+ );
180
+ if (known.retention !== null)
181
+ matchConfigureDATA(retention, known.retention);
182
+ matchConfigureDATA(ack, { retention, receiptJSON: known.receiptJSON });
183
+ } else
184
+ requireConfigure(
185
+ (known === null || known.retention === null) && events.length < 3,
186
+ );
187
+ const verified = await checked(() =>
188
+ assertConfigureWriteFrontier(
189
+ token,
190
+ expectedEvents.slice(0, events.length),
191
+ retention && known ? { ...known, retention } : null,
192
+ ),
193
+ );
194
+ return { events: verified, retention };
195
+ }
@@ -246,3 +246,87 @@ export function checkParentAcknowledgement(
246
246
  },
247
247
  });
248
248
  }
249
+
250
+ /** Complete bounded configure history descriptors, without promoting DATA to custody. */
251
+ export function captureConfigureHistory(
252
+ raw: unknown,
253
+ reservation: OperationalReservationDATA,
254
+ count: number,
255
+ ) {
256
+ const own = closed(raw, ["reservation", "events"]);
257
+ requireConfigure(
258
+ Number.isInteger(count) &&
259
+ count >= 1 &&
260
+ count <= 3 &&
261
+ !types.isProxy(own.events) &&
262
+ Array.isArray(own.events) &&
263
+ Object.getPrototypeOf(own.events) === Array.prototype &&
264
+ own.events.length === count,
265
+ );
266
+ const events = Array.from({ length: count }, (_, index) => {
267
+ const descriptor = Object.getOwnPropertyDescriptor(
268
+ own.events,
269
+ String(index),
270
+ );
271
+ requireConfigure(
272
+ descriptor && descriptor.enumerable && "value" in descriptor,
273
+ );
274
+ const event = closed(descriptor.value, [
275
+ "operationId",
276
+ "attemptId",
277
+ "stage",
278
+ "sourcePayloadId",
279
+ "sequence",
280
+ "binding",
281
+ "payloadId",
282
+ "eventId",
283
+ ]);
284
+ return {
285
+ operationId: reservation.operationId,
286
+ attemptId: reservation.attemptId,
287
+ stage: "configure" as const,
288
+ sourcePayloadId: reservation.payloadId,
289
+ sequence: index + 1,
290
+ binding: text(event.binding),
291
+ payloadId: text(event.payloadId),
292
+ eventId: text(event.eventId),
293
+ };
294
+ });
295
+ requireConfigure(
296
+ new Set(events.map((e) => e.eventId)).size === count &&
297
+ new Set(events.map((e) => e.payloadId)).size === count &&
298
+ events.every((e) => e.payloadId !== reservation.payloadId),
299
+ );
300
+ matchConfigureDATA(raw, { reservation, events });
301
+ return events;
302
+ }
303
+ export function checkConfigureRetention(
304
+ raw: unknown,
305
+ reservation: OperationalReservationDATA,
306
+ events: ReturnType<typeof captureConfigureHistory>,
307
+ receiptBinding: string,
308
+ ) {
309
+ requireConfigure(events.length >= 2);
310
+ const own = object(raw),
311
+ receiptPayloadId = text(own.receiptPayloadId);
312
+ requireConfigure(
313
+ receiptPayloadId !== reservation.payloadId &&
314
+ !events.some((event) => event.payloadId === receiptPayloadId),
315
+ );
316
+ const expected = {
317
+ status: "retained" as const,
318
+ operationId: reservation.operationId,
319
+ schemaVersion: 1 as const,
320
+ stage: "configure" as const,
321
+ attemptId: reservation.attemptId,
322
+ sourcePayloadId: reservation.payloadId,
323
+ dispatchEventId: events[0].eventId,
324
+ dispatchPayloadId: events[0].payloadId,
325
+ responseEventId: events[1].eventId,
326
+ responsePayloadId: events[1].payloadId,
327
+ receiptPayloadId,
328
+ receiptBinding,
329
+ };
330
+ matchConfigureDATA(raw, expected);
331
+ return expected;
332
+ }
@@ -33,6 +33,22 @@ function construct(token: object) {
33
33
  }
34
34
  };
35
35
  },
36
+ async retain(receiptJSON: string) {
37
+ requireConfigure(arguments.length === 1);
38
+ gate();
39
+ pending++;
40
+ try {
41
+ const reply = await original.journal.retainProviderAcknowledgement({
42
+ attemptId: original.reservation.attemptId,
43
+ expectedSequence: 2,
44
+ receiptJSON,
45
+ });
46
+ gate();
47
+ return reply;
48
+ } finally {
49
+ pending--;
50
+ }
51
+ },
36
52
  idle() {
37
53
  requireConfigure(arguments.length === 0);
38
54
  gate();