@fantastic.dev/better-stripe 0.63.0 → 0.64.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 (174) hide show
  1. package/CHANGELOG.md +11 -0
  2. package/README.md +19 -1
  3. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts +550 -0
  4. package/dist/client/connect/payoutAdoptionTestHelpers.d.ts.map +1 -1
  5. package/dist/client/connect/payoutExecutionTestHelpers.d.ts +275 -0
  6. package/dist/client/connect/payoutExecutionTestHelpers.d.ts.map +1 -1
  7. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts +582 -32
  8. package/dist/client/connect/payoutLargeAdoptionTestHelpers.d.ts.map +1 -1
  9. package/dist/client/connect/payoutSyncTestHelpers.d.ts +291 -16
  10. package/dist/client/connect/payoutSyncTestHelpers.d.ts.map +1 -1
  11. package/dist/client/financialOwnership.d.ts +2 -2
  12. package/dist/client/financialOwnership.d.ts.map +1 -1
  13. package/dist/client/financialOwnership.js +2 -2
  14. package/dist/client/financialOwnership.js.map +1 -1
  15. package/dist/client/payoutRevisionMigration.d.ts +37 -0
  16. package/dist/client/payoutRevisionMigration.d.ts.map +1 -0
  17. package/dist/client/payoutRevisionMigration.js +49 -0
  18. package/dist/client/payoutRevisionMigration.js.map +1 -0
  19. package/dist/client/publicTypes.d.ts +2 -0
  20. package/dist/client/publicTypes.d.ts.map +1 -1
  21. package/dist/client/reversalObservations.d.ts +62 -0
  22. package/dist/client/reversalObservations.d.ts.map +1 -0
  23. package/dist/client/reversalObservations.js +79 -0
  24. package/dist/client/reversalObservations.js.map +1 -0
  25. package/dist/component/_generated/api.d.ts +28 -0
  26. package/dist/component/_generated/api.d.ts.map +1 -1
  27. package/dist/component/_generated/api.js.map +1 -1
  28. package/dist/component/_generated/component.d.ts +354 -0
  29. package/dist/component/_generated/component.d.ts.map +1 -1
  30. package/dist/component/balanceFunding/internal/actions.d.ts +11 -11
  31. package/dist/component/balanceFunding/mutations.d.ts +16 -16
  32. package/dist/component/balanceFunding/stateHandlers.d.ts +8 -8
  33. package/dist/component/connect/mutations.d.ts.map +1 -1
  34. package/dist/component/connect/mutations.js +2 -0
  35. package/dist/component/connect/mutations.js.map +1 -1
  36. package/dist/component/connect/reversalClaims.d.ts.map +1 -1
  37. package/dist/component/connect/reversalClaims.js +10 -1
  38. package/dist/component/connect/reversalClaims.js.map +1 -1
  39. package/dist/component/earnings/triggers.d.ts +408 -16
  40. package/dist/component/earnings/triggers.d.ts.map +1 -1
  41. package/dist/component/financialObservations/transferSchema.d.ts +1 -0
  42. package/dist/component/financialObservations/transferSchema.d.ts.map +1 -1
  43. package/dist/component/financialObservations/transferSchema.js +1 -0
  44. package/dist/component/financialObservations/transferSchema.js.map +1 -1
  45. package/dist/component/payoutRelease/queries.d.ts +2 -2
  46. package/dist/component/payoutRelease/queries.d.ts.map +1 -1
  47. package/dist/component/payoutRevisionJournal/mutations.d.ts +15 -0
  48. package/dist/component/payoutRevisionJournal/mutations.d.ts.map +1 -0
  49. package/dist/component/payoutRevisionJournal/mutations.js +11 -0
  50. package/dist/component/payoutRevisionJournal/mutations.js.map +1 -0
  51. package/dist/component/payoutRevisionJournal/schema.d.ts +45 -0
  52. package/dist/component/payoutRevisionJournal/schema.d.ts.map +1 -0
  53. package/dist/component/payoutRevisionJournal/schema.js +22 -0
  54. package/dist/component/payoutRevisionJournal/schema.js.map +1 -0
  55. package/dist/component/payoutRevisionJournal/state.d.ts +36 -0
  56. package/dist/component/payoutRevisionJournal/state.d.ts.map +1 -0
  57. package/dist/component/payoutRevisionJournal/state.js +111 -0
  58. package/dist/component/payoutRevisionJournal/state.js.map +1 -0
  59. package/dist/component/payoutRevisionMigration/mutations.d.ts +36 -0
  60. package/dist/component/payoutRevisionMigration/mutations.d.ts.map +1 -0
  61. package/dist/component/payoutRevisionMigration/mutations.js +126 -0
  62. package/dist/component/payoutRevisionMigration/mutations.js.map +1 -0
  63. package/dist/component/payoutRevisionMigration/queries.d.ts +38 -0
  64. package/dist/component/payoutRevisionMigration/queries.d.ts.map +1 -0
  65. package/dist/component/payoutRevisionMigration/queries.js +39 -0
  66. package/dist/component/payoutRevisionMigration/queries.js.map +1 -0
  67. package/dist/component/payoutRevisionMigration/schema.d.ts +115 -0
  68. package/dist/component/payoutRevisionMigration/schema.d.ts.map +1 -0
  69. package/dist/component/payoutRevisionMigration/schema.js +52 -0
  70. package/dist/component/payoutRevisionMigration/schema.js.map +1 -0
  71. package/dist/component/payoutSnapshots/legacyRevisionWriter.d.ts +4 -0
  72. package/dist/component/payoutSnapshots/legacyRevisionWriter.d.ts.map +1 -0
  73. package/dist/component/payoutSnapshots/legacyRevisionWriter.js +33 -0
  74. package/dist/component/payoutSnapshots/legacyRevisionWriter.js.map +1 -0
  75. package/dist/component/payoutSnapshots/revisions.d.ts.map +1 -1
  76. package/dist/component/payoutSnapshots/revisions.js +23 -29
  77. package/dist/component/payoutSnapshots/revisions.js.map +1 -1
  78. package/dist/component/processingCostReconciliation/rollback.d.ts +1 -1
  79. package/dist/component/refundSync/mutations.d.ts +1 -1
  80. package/dist/component/refundSync/mutations.d.ts.map +1 -1
  81. package/dist/component/reversalObservations/capture.d.ts +6 -0
  82. package/dist/component/reversalObservations/capture.d.ts.map +1 -0
  83. package/dist/component/reversalObservations/capture.js +96 -0
  84. package/dist/component/reversalObservations/capture.js.map +1 -0
  85. package/dist/component/reversalObservations/indexSlice.d.ts +29 -0
  86. package/dist/component/reversalObservations/indexSlice.d.ts.map +1 -0
  87. package/dist/component/reversalObservations/indexSlice.js +101 -0
  88. package/dist/component/reversalObservations/indexSlice.js.map +1 -0
  89. package/dist/component/reversalObservations/integrity.d.ts +25 -0
  90. package/dist/component/reversalObservations/integrity.d.ts.map +1 -0
  91. package/dist/component/reversalObservations/integrity.js +19 -0
  92. package/dist/component/reversalObservations/integrity.js.map +1 -0
  93. package/dist/component/reversalObservations/mutations.d.ts +37 -0
  94. package/dist/component/reversalObservations/mutations.d.ts.map +1 -0
  95. package/dist/component/reversalObservations/mutations.js +181 -0
  96. package/dist/component/reversalObservations/mutations.js.map +1 -0
  97. package/dist/component/reversalObservations/pagination.d.ts +34 -0
  98. package/dist/component/reversalObservations/pagination.d.ts.map +1 -0
  99. package/dist/component/reversalObservations/pagination.js +31 -0
  100. package/dist/component/reversalObservations/pagination.js.map +1 -0
  101. package/dist/component/reversalObservations/queries.d.ts +221 -0
  102. package/dist/component/reversalObservations/queries.d.ts.map +1 -0
  103. package/dist/component/reversalObservations/queries.js +114 -0
  104. package/dist/component/reversalObservations/queries.js.map +1 -0
  105. package/dist/component/reversalObservations/references.d.ts +17 -0
  106. package/dist/component/reversalObservations/references.d.ts.map +1 -0
  107. package/dist/component/reversalObservations/references.js +95 -0
  108. package/dist/component/reversalObservations/references.js.map +1 -0
  109. package/dist/component/reversalObservations/schema.d.ts +525 -0
  110. package/dist/component/reversalObservations/schema.d.ts.map +1 -0
  111. package/dist/component/reversalObservations/schema.js +92 -0
  112. package/dist/component/reversalObservations/schema.js.map +1 -0
  113. package/dist/component/reversalObservations/selectors.d.ts +3 -0
  114. package/dist/component/reversalObservations/selectors.d.ts.map +1 -0
  115. package/dist/component/reversalObservations/selectors.js +8 -0
  116. package/dist/component/reversalObservations/selectors.js.map +1 -0
  117. package/dist/component/reversalObservations/state.d.ts +34 -0
  118. package/dist/component/reversalObservations/state.d.ts.map +1 -0
  119. package/dist/component/reversalObservations/state.js +34 -0
  120. package/dist/component/reversalObservations/state.js.map +1 -0
  121. package/dist/component/schema.d.ts +275 -0
  122. package/dist/component/schema.js +10 -0
  123. package/dist/component/schema.js.map +1 -1
  124. package/dist/component/usage/allowance.fixtures.d.ts +291 -16
  125. package/dist/component/usage/allowance.fixtures.d.ts.map +1 -1
  126. package/dist/component/usageCredits/accounting.fixtures.d.ts +275 -0
  127. package/dist/component/usageCredits/accounting.fixtures.d.ts.map +1 -1
  128. package/docs/README.md +2 -1
  129. package/docs/client-api.md +6 -0
  130. package/docs/financial-observations.md +51 -8
  131. package/docs/payout-revision-migration.md +54 -0
  132. package/docs/react-workflows-audit.md +73 -2
  133. package/docs/usage-example.md +4 -0
  134. package/package.json +3 -2
  135. package/src/client/financialOwnership.ts +2 -2
  136. package/src/client/payoutRevisionMigration.test.ts +40 -0
  137. package/src/client/payoutRevisionMigration.ts +96 -0
  138. package/src/client/publicTypes.ts +15 -0
  139. package/src/client/reversalObservations.test.ts +69 -0
  140. package/src/client/reversalObservations.ts +151 -0
  141. package/src/component/_generated/api.ts +28 -0
  142. package/src/component/_generated/component.ts +423 -0
  143. package/src/component/connect/mutations.ts +2 -0
  144. package/src/component/connect/reversalClaims.ts +13 -1
  145. package/src/component/financialObservations/transferSchema.ts +1 -0
  146. package/src/component/payoutRevisionJournal/mutations.ts +11 -0
  147. package/src/component/payoutRevisionJournal/schema.ts +34 -0
  148. package/src/component/payoutRevisionJournal/state.ts +141 -0
  149. package/src/component/payoutRevisionMigration/mutations.ts +135 -0
  150. package/src/component/payoutRevisionMigration/queries.ts +50 -0
  151. package/src/component/payoutRevisionMigration/schema.ts +51 -0
  152. package/src/component/payoutSnapshots/legacy-revisions.test.ts +246 -0
  153. package/src/component/payoutSnapshots/legacyRevisionWriter.ts +39 -0
  154. package/src/component/payoutSnapshots/revision-journal-callbacks.test.ts +160 -0
  155. package/src/component/payoutSnapshots/revision-journal-held.test.ts +94 -0
  156. package/src/component/payoutSnapshots/revision-journal.test.ts +310 -0
  157. package/src/component/payoutSnapshots/revision-migration.test.ts +128 -0
  158. package/src/component/payoutSnapshots/revisions.ts +22 -30
  159. package/src/component/reversalObservations/boundaries.test.ts +62 -0
  160. package/src/component/reversalObservations/capture-integrity.test.ts +119 -0
  161. package/src/component/reversalObservations/capture.ts +129 -0
  162. package/src/component/reversalObservations/continuation.test.ts +131 -0
  163. package/src/component/reversalObservations/indexSlice.ts +124 -0
  164. package/src/component/reversalObservations/integrity.ts +31 -0
  165. package/src/component/reversalObservations/lifecycle.test.ts +81 -0
  166. package/src/component/reversalObservations/mutations.ts +211 -0
  167. package/src/component/reversalObservations/pagination.ts +40 -0
  168. package/src/component/reversalObservations/provenance.test.ts +167 -0
  169. package/src/component/reversalObservations/queries.ts +121 -0
  170. package/src/component/reversalObservations/references.ts +134 -0
  171. package/src/component/reversalObservations/schema.ts +100 -0
  172. package/src/component/reversalObservations/selectors.ts +9 -0
  173. package/src/component/reversalObservations/state.ts +42 -0
  174. package/src/component/schema.ts +18 -0
@@ -0,0 +1,94 @@
1
+ // @vitest-environment edge-runtime
2
+ import { convexTest } from "convex-test";
3
+ import { makeFunctionReference } from "convex/server";
4
+ import { expect, it } from "vitest";
5
+ import { schema, modules } from "../../test.js";
6
+ const activate = makeFunctionReference<"mutation">(
7
+ "payoutRevisionJournal/mutations:activateAccount",
8
+ );
9
+ const accountId = "acct_held";
10
+ it.each([
11
+ {
12
+ name: "financial duplicate",
13
+ revision: 4,
14
+ financialRisk: 3,
15
+ risk: 3,
16
+ duplicate: "financial",
17
+ reason: "legacy_ambiguous",
18
+ },
19
+ {
20
+ name: "risk duplicate",
21
+ revision: 4,
22
+ financialRisk: 3,
23
+ risk: 3,
24
+ duplicate: "risk",
25
+ reason: "legacy_ambiguous",
26
+ },
27
+ {
28
+ name: "disagreement",
29
+ revision: 4,
30
+ financialRisk: 3,
31
+ risk: 2,
32
+ reason: "legacy_disagreement",
33
+ },
34
+ {
35
+ name: "NaN",
36
+ revision: NaN,
37
+ financialRisk: 3,
38
+ risk: 3,
39
+ reason: "legacy_invalid",
40
+ },
41
+ {
42
+ name: "infinity",
43
+ revision: Infinity,
44
+ financialRisk: 3,
45
+ risk: 3,
46
+ reason: "legacy_invalid",
47
+ },
48
+ {
49
+ name: "fraction",
50
+ revision: 4.5,
51
+ financialRisk: 3,
52
+ risk: 3,
53
+ reason: "legacy_invalid",
54
+ },
55
+ {
56
+ name: "unsafe risk",
57
+ revision: 4,
58
+ financialRisk: 0.5,
59
+ risk: 0.5,
60
+ reason: "legacy_invalid",
61
+ },
62
+ ])(
63
+ "holds $name and preserves both legacy tables exactly",
64
+ async ({ revision, financialRisk, risk, duplicate, reason }) => {
65
+ const t = convexTest(schema, modules);
66
+ await t.run(async (ctx) => {
67
+ const f = { accountId, revision, riskRevision: financialRisk };
68
+ const r = { accountId, riskRevision: risk };
69
+ await ctx.db.insert("payoutFinancialRevisions", f);
70
+ await ctx.db.insert("payoutRiskRevisions", r);
71
+ if (duplicate === "financial")
72
+ await ctx.db.insert("payoutFinancialRevisions", f);
73
+ if (duplicate === "risk") await ctx.db.insert("payoutRiskRevisions", r);
74
+ });
75
+ const snapshot = () =>
76
+ t.run(async (ctx) => ({
77
+ financial: await ctx.db.query("payoutFinancialRevisions").take(5),
78
+ risk: await ctx.db.query("payoutRiskRevisions").take(5),
79
+ }));
80
+ const before = await snapshot();
81
+ expect(await t.mutation(activate, { accountId })).toEqual({
82
+ accountId,
83
+ status: "held",
84
+ reason,
85
+ });
86
+ expect(await snapshot()).toEqual(before);
87
+ expect(
88
+ await t.run((ctx) => ctx.db.query("payoutRevisionJournal").take(5)),
89
+ ).toEqual([]);
90
+ expect(
91
+ await t.run((ctx) => ctx.db.query("payoutRiskEvents").take(5)),
92
+ ).toEqual([]);
93
+ },
94
+ );
@@ -0,0 +1,310 @@
1
+ import { convexTest } from "convex-test";
2
+ import { makeFunctionReference } from "convex/server";
3
+ import { expect, it } from "vitest";
4
+ import { schema, modules } from "../../test.js";
5
+ import { financialRevision, riskRevision } from "./revisions.js";
6
+
7
+ const activate = makeFunctionReference<"mutation">(
8
+ "payoutRevisionJournal/mutations:activateAccount",
9
+ );
10
+ const payout = makeFunctionReference<"mutation">(
11
+ "connect/mutations:upsertPayout",
12
+ );
13
+ const transfer = makeFunctionReference<"mutation">(
14
+ "connect/mutations:upsertTransfer",
15
+ );
16
+ const accountId = "acct_journal";
17
+ const makeTest = () => convexTest(schema, modules);
18
+
19
+ it("activates a risk-only legacy account without changing its distinct readers or old rows", async () => {
20
+ const t = makeTest();
21
+ const original = await t.run(async (ctx) => {
22
+ const id = await ctx.db.insert("payoutRiskRevisions", {
23
+ accountId,
24
+ riskRevision: 7,
25
+ });
26
+ return ctx.db.get("payoutRiskRevisions", id);
27
+ });
28
+ expect(await t.mutation(activate, { accountId })).toMatchObject({
29
+ status: "activated",
30
+ });
31
+ expect(await t.run((ctx) => financialRevision(ctx, accountId))).toEqual({
32
+ revision: 0,
33
+ riskRevision: 0,
34
+ });
35
+ expect(await t.run((ctx) => riskRevision(ctx, accountId))).toBe(7);
36
+ await t.mutation(payout, {
37
+ stripePayoutId: "po_journal",
38
+ accountId,
39
+ amount: 10,
40
+ currency: "usd",
41
+ status: "pending",
42
+ arrivalDate: "2026-10-18",
43
+ });
44
+ expect(await t.run((ctx) => financialRevision(ctx, accountId))).toEqual({
45
+ revision: 1,
46
+ riskRevision: 8,
47
+ });
48
+ expect(await t.run((ctx) => riskRevision(ctx, accountId))).toBe(8);
49
+ expect(
50
+ await t.run((ctx) => ctx.db.query("payoutRiskRevisions").take(2)),
51
+ ).toEqual([original]);
52
+ });
53
+
54
+ it("preserves the physical canonical fence range across positive funding", async () => {
55
+ const t = makeTest();
56
+ await t.mutation(activate, { accountId });
57
+ const fence = () =>
58
+ t.run((ctx) =>
59
+ ctx.db
60
+ .query("payoutRevisionJournal")
61
+ .withIndex("by_account_fence_revision", (q) =>
62
+ q.eq("accountId", accountId).eq("fenceStream", true),
63
+ )
64
+ .take(5),
65
+ );
66
+ const before = await fence();
67
+ await t.mutation(transfer, {
68
+ stripeTransferId: "tr_journal",
69
+ sourceChargeId: "ch_journal",
70
+ destinationAccountId: accountId,
71
+ amount: 10,
72
+ currency: "usd",
73
+ role: "store",
74
+ status: "paid",
75
+ });
76
+ expect(await fence()).toEqual(before);
77
+ expect(await t.run((ctx) => financialRevision(ctx, accountId))).toEqual({
78
+ revision: 1,
79
+ riskRevision: 0,
80
+ });
81
+ expect(
82
+ await t.run((ctx) => ctx.db.query("payoutRiskEvents").take(5)),
83
+ ).toEqual([]);
84
+ });
85
+
86
+ it.each([
87
+ {
88
+ name: "contradictory baseline",
89
+ change: { financialRiskRevision: 3, riskRevision: 99 },
90
+ },
91
+ { name: "standalone bump", change: { kind: "bump" as const } },
92
+ ])(
93
+ "rejects $name without falling back to an invented legacy authority",
94
+ async ({ change }) => {
95
+ const t = makeTest();
96
+ await t.run(async (ctx) => {
97
+ const legacyFinancialId = await ctx.db.insert(
98
+ "payoutFinancialRevisions",
99
+ { accountId, revision: 0, riskRevision: 0 },
100
+ );
101
+ await ctx.db.insert("payoutRevisionJournal", {
102
+ accountId,
103
+ revision: 0,
104
+ riskRevision: 0,
105
+ financialRiskRevision: 0,
106
+ financialPresent: true,
107
+ fenceStream: true,
108
+ kind: "baseline",
109
+ legacyFinancialId,
110
+ ...change,
111
+ });
112
+ });
113
+ await expect(
114
+ t.run((ctx) => financialRevision(ctx, accountId)),
115
+ ).rejects.toThrow(/journal/);
116
+ },
117
+ );
118
+
119
+ it.each([
120
+ {
121
+ name: "financial sequence gap",
122
+ revision: 2,
123
+ riskRevision: 0,
124
+ fenceStream: false,
125
+ },
126
+ {
127
+ name: "unfenced risk increase",
128
+ revision: 1,
129
+ riskRevision: 1,
130
+ fenceStream: false,
131
+ },
132
+ {
133
+ name: "missing risk increase",
134
+ revision: 1,
135
+ riskRevision: 0,
136
+ fenceStream: true,
137
+ },
138
+ ])(
139
+ "rejects a latest $name atomically",
140
+ async ({ revision, riskRevision: riskCounter, fenceStream }) => {
141
+ const t = makeTest();
142
+ await t.mutation(activate, { accountId });
143
+ await t.run((ctx) =>
144
+ ctx.db.insert("payoutRevisionJournal", {
145
+ accountId,
146
+ revision,
147
+ riskRevision: riskCounter,
148
+ financialRiskRevision: riskCounter,
149
+ financialPresent: true,
150
+ fenceStream,
151
+ kind: "bump",
152
+ }),
153
+ );
154
+ await expect(
155
+ t.mutation(payout, {
156
+ stripePayoutId: "po_invalid",
157
+ accountId,
158
+ amount: 10,
159
+ currency: "usd",
160
+ status: "pending",
161
+ arrivalDate: "2026-10-18",
162
+ }),
163
+ ).rejects.toThrow(/journal/);
164
+ expect(await t.run((ctx) => ctx.db.query("payouts").take(1))).toEqual([]);
165
+ expect(
166
+ await t.run((ctx) => ctx.db.query("payoutRiskEvents").take(1)),
167
+ ).toEqual([]);
168
+ },
169
+ );
170
+
171
+ it.each([
172
+ { name: "absent", financial: undefined, risk: undefined },
173
+ {
174
+ name: "financial only",
175
+ financial: { revision: 4, riskRevision: 3 },
176
+ risk: undefined,
177
+ },
178
+ { name: "risk only", financial: undefined, risk: 7 },
179
+ { name: "equal pair", financial: { revision: 4, riskRevision: 3 }, risk: 3 },
180
+ {
181
+ name: "signed counters",
182
+ financial: { revision: -4, riskRevision: -3 },
183
+ risk: -3,
184
+ },
185
+ {
186
+ name: "risk above financial",
187
+ financial: { revision: 2, riskRevision: 7 },
188
+ risk: 7,
189
+ },
190
+ {
191
+ name: "negative financial zero",
192
+ financial: { revision: -0, riskRevision: -0 },
193
+ risk: 0,
194
+ },
195
+ {
196
+ name: "negative risk zero",
197
+ financial: { revision: 0, riskRevision: 0 },
198
+ risk: -0,
199
+ },
200
+ ])(
201
+ "preserves both readers and the next real bump for $name",
202
+ async ({ financial, risk }) => {
203
+ const t = makeTest();
204
+ await t.run(async (ctx) => {
205
+ if (financial)
206
+ await ctx.db.insert("payoutFinancialRevisions", {
207
+ accountId,
208
+ ...financial,
209
+ });
210
+ if (risk !== undefined)
211
+ await ctx.db.insert("payoutRiskRevisions", {
212
+ accountId,
213
+ riskRevision: risk,
214
+ });
215
+ });
216
+ const readers = () =>
217
+ t.run(async (ctx) => ({
218
+ financial: await financialRevision(ctx, accountId),
219
+ risk: await riskRevision(ctx, accountId),
220
+ }));
221
+ const legacy = () =>
222
+ t.run(async (ctx) => ({
223
+ financial: await ctx.db.query("payoutFinancialRevisions").take(5),
224
+ risk: await ctx.db.query("payoutRiskRevisions").take(5),
225
+ }));
226
+ const before = await readers();
227
+ const oldRows = await legacy();
228
+ expect(await t.mutation(activate, { accountId })).toMatchObject({
229
+ status: "activated",
230
+ });
231
+ expect(await readers()).toEqual(before);
232
+ expect(await t.mutation(activate, { accountId })).toMatchObject({
233
+ status: "unchanged",
234
+ });
235
+ await t.mutation(payout, {
236
+ stripePayoutId: "po_parity",
237
+ accountId,
238
+ amount: 1,
239
+ currency: "usd",
240
+ status: "pending",
241
+ arrivalDate: "2026-10-18",
242
+ });
243
+ expect(await readers()).toEqual({
244
+ financial: {
245
+ revision: (financial?.revision ?? 0) + 1,
246
+ riskRevision: (risk ?? financial?.riskRevision ?? 0) + 1,
247
+ },
248
+ risk: (risk ?? financial?.riskRevision ?? 0) + 1,
249
+ });
250
+ expect(await legacy()).toEqual(oldRows);
251
+ },
252
+ );
253
+
254
+ it.each(["financial", "risk"])(
255
+ "activates safe MAX %s counters but rolls back an overflowing source write",
256
+ async (field) => {
257
+ const t = makeTest();
258
+ await t.run(async (ctx) => {
259
+ const riskRevision = field === "risk" ? Number.MAX_SAFE_INTEGER : 0;
260
+ await ctx.db.insert("payoutFinancialRevisions", {
261
+ accountId,
262
+ revision: field === "financial" ? Number.MAX_SAFE_INTEGER : 0,
263
+ riskRevision,
264
+ });
265
+ await ctx.db.insert("payoutRiskRevisions", { accountId, riskRevision });
266
+ });
267
+ await t.mutation(activate, { accountId });
268
+ const before = await t.run((ctx) =>
269
+ ctx.db.query("payoutRevisionJournal").take(5),
270
+ );
271
+ await expect(
272
+ t.mutation(payout, {
273
+ stripePayoutId: "po_overflow",
274
+ accountId,
275
+ amount: 1,
276
+ currency: "usd",
277
+ status: "pending",
278
+ arrivalDate: "2026-10-18",
279
+ }),
280
+ ).rejects.toThrow();
281
+ expect(
282
+ await t.run((ctx) => ctx.db.query("payoutRevisionJournal").take(5)),
283
+ ).toEqual(before);
284
+ expect(await t.run((ctx) => ctx.db.query("payouts").take(5))).toEqual([]);
285
+ expect(
286
+ await t.run((ctx) => ctx.db.query("payoutRiskEvents").take(5)),
287
+ ).toEqual([]);
288
+ },
289
+ );
290
+
291
+ it("rejects an active journal with its baseline fence missing", async () => {
292
+ const t = makeTest();
293
+ await t.run((ctx) =>
294
+ ctx.db.insert("payoutRiskRevisions", { accountId, riskRevision: 0 }),
295
+ );
296
+ await t.run((ctx) =>
297
+ ctx.db.insert("payoutRevisionJournal", {
298
+ accountId,
299
+ revision: 1,
300
+ riskRevision: 0,
301
+ financialRiskRevision: 0,
302
+ financialPresent: true,
303
+ fenceStream: false,
304
+ kind: "bump",
305
+ }),
306
+ );
307
+ await expect(t.run((ctx) => riskRevision(ctx, accountId))).rejects.toThrow(
308
+ /journal/,
309
+ );
310
+ });
@@ -0,0 +1,128 @@
1
+ // @vitest-environment edge-runtime
2
+ import { convexTest } from "convex-test";
3
+ import { makeFunctionReference } from "convex/server";
4
+ import { expect, it } from "vitest";
5
+ import { schema, modules } from "../../test.js";
6
+ const begin = makeFunctionReference<"mutation">(
7
+ "payoutRevisionMigration/mutations:begin",
8
+ );
9
+ const resume = makeFunctionReference<"mutation">(
10
+ "payoutRevisionMigration/mutations:resume",
11
+ );
12
+ it("resumes a server-owned inventory, deduplicates accounts and holds conflicting legacy authorities", async () => {
13
+ const t = convexTest(schema, modules);
14
+ await t.run(async (ctx) => {
15
+ await ctx.db.insert("payoutFinancialRevisions", {
16
+ accountId: "acct_good",
17
+ revision: 4,
18
+ riskRevision: 3,
19
+ });
20
+ await ctx.db.insert("payoutRiskRevisions", {
21
+ accountId: "acct_good",
22
+ riskRevision: 3,
23
+ });
24
+ await ctx.db.insert("payoutFinancialRevisions", {
25
+ accountId: "acct_conflict",
26
+ revision: 1,
27
+ riskRevision: 2,
28
+ });
29
+ await ctx.db.insert("payoutRiskRevisions", {
30
+ accountId: "acct_conflict",
31
+ riskRevision: 1,
32
+ });
33
+ await ctx.db.insert("transfers", {
34
+ stripeTransferId: "tr_inventory",
35
+ destinationAccountId: "acct_source_only",
36
+ amount: 1,
37
+ currency: "usd",
38
+ status: "paid",
39
+ role: "store",
40
+ });
41
+ });
42
+ let state = await t.mutation(begin, { operationKey: "pass-one" });
43
+ expect(await t.mutation(begin, { operationKey: "pass-one" })).toEqual(state);
44
+ const first = await t.mutation(resume, { jobId: state._id, expectedStep: 0 });
45
+ expect(first.step).toBe(1);
46
+ expect(
47
+ await t.mutation(resume, { jobId: state._id, expectedStep: 0 }),
48
+ ).toEqual(first);
49
+ await expect(
50
+ t.mutation(resume, { jobId: state._id, expectedStep: 99 }),
51
+ ).rejects.toThrow(/step/i);
52
+ state = first;
53
+ for (let n = 0; n < 100 && state.status !== "finished"; n++)
54
+ state = await t.mutation(resume, {
55
+ jobId: state._id,
56
+ expectedStep: state.step,
57
+ });
58
+ expect(state).toMatchObject({
59
+ status: "finished",
60
+ visited: 3,
61
+ activated: 2,
62
+ held: 1,
63
+ unchanged: 0,
64
+ });
65
+ expect(
66
+ await t.run((ctx) => ctx.db.query("payoutRevisionJournal").take(10)),
67
+ ).toHaveLength(2);
68
+ expect(
69
+ await t.run((ctx) => ctx.db.query("payoutFinancialRevisions").take(10)),
70
+ ).toHaveLength(2);
71
+ expect(
72
+ await t.run((ctx) => ctx.db.query("payoutRiskEvents").take(10)),
73
+ ).toEqual([]);
74
+ });
75
+
76
+ it("records a held oversized account by source reference without copying its key into result rows", async () => {
77
+ const t = convexTest(schema, modules);
78
+ const accountId = "a".repeat(900_100);
79
+ const sourceId = await t.run((ctx) =>
80
+ ctx.db.insert("payoutRiskRevisions", { accountId, riskRevision: 0 }),
81
+ );
82
+ let state = await t.mutation(begin, { operationKey: "large-key" });
83
+ for (let n = 0; n < 100 && state.status !== "finished"; n++)
84
+ state = await t.mutation(resume, {
85
+ jobId: state._id,
86
+ expectedStep: state.step,
87
+ });
88
+ expect(state).toMatchObject({ status: "finished", held: 1, activated: 0 });
89
+ const results = await t.run((ctx) =>
90
+ ctx.db.query("payoutRevisionMigrationResults").take(5),
91
+ );
92
+ expect(results).toHaveLength(1);
93
+ expect(results[0]).toMatchObject({
94
+ sourceId,
95
+ sourceTable: "payoutRiskRevisions",
96
+ reason: "representation_unavailable",
97
+ });
98
+ expect(results[0].accountId).toBeUndefined();
99
+ expect(JSON.stringify(results[0]).length).toBeLessThan(1024);
100
+ });
101
+
102
+ it.each([
103
+ { phase: 0.5 },
104
+ { scanned: Number.MAX_SAFE_INTEGER },
105
+ { visited: -1 },
106
+ ])(
107
+ "rejects invalid persisted job state %j before activation",
108
+ async (change) => {
109
+ const t = convexTest(schema, modules);
110
+ await t.run((ctx) =>
111
+ ctx.db.insert("payoutFinancialRevisions", {
112
+ accountId: "acct_invalid_job",
113
+ revision: 0,
114
+ riskRevision: 0,
115
+ }),
116
+ );
117
+ const job = await t.mutation(begin, { operationKey: "invalid-job" });
118
+ await t.run((ctx) =>
119
+ ctx.db.patch("payoutRevisionMigrations", job._id, change),
120
+ );
121
+ await expect(
122
+ t.mutation(resume, { jobId: job._id, expectedStep: 0 }),
123
+ ).rejects.toThrow(/migration/i);
124
+ expect(
125
+ await t.run((ctx) => ctx.db.query("payoutRevisionJournal").take(2)),
126
+ ).toEqual([]);
127
+ },
128
+ );
@@ -1,9 +1,10 @@
1
+ import { journalHead, appendRevision } from "../payoutRevisionJournal/state.js";
1
2
  import type { Infer } from "convex/values";
2
3
  import type { riskKind } from "./schema.js";
3
4
  import type { Triggers } from "convex-helpers/server/triggers";
4
5
  import type { DataModel, Doc } from "../_generated/dataModel.js";
5
6
  import type { MutationCtx, QueryCtx } from "../_generated/server.js";
6
- import { addSummaryAmounts as add } from "../earnings/arithmetic.js";
7
+ import { bumpLegacyRevision } from "./legacyRevisionWriter.js";
7
8
  import {
8
9
  transferFingerprint,
9
10
  payoutClaimFingerprint,
@@ -12,6 +13,14 @@ export async function financialRevision(
12
13
  ctx: QueryCtx | MutationCtx,
13
14
  accountId: string,
14
15
  ) {
16
+ const canonical = await journalHead(ctx, accountId);
17
+ if (canonical)
18
+ return canonical.financialPresent
19
+ ? {
20
+ revision: canonical.revision,
21
+ riskRevision: canonical.financialRiskRevision,
22
+ }
23
+ : { revision: 0, riskRevision: 0 };
15
24
  const row = await ctx.db
16
25
  .query("payoutFinancialRevisions")
17
26
  .withIndex("by_account", (q) => q.eq("accountId", accountId))
@@ -23,6 +32,10 @@ export async function riskRevision(
23
32
  ctx: QueryCtx | MutationCtx,
24
33
  accountId: string,
25
34
  ) {
35
+ const canonical = await journalHead(ctx, accountId, true);
36
+ if (canonical) return canonical.riskRevision;
37
+ if (await journalHead(ctx, accountId))
38
+ throw new Error("Canonical payout revision journal has no risk fence.");
26
39
  const risk = await ctx.db
27
40
  .query("payoutRiskRevisions")
28
41
  .withIndex("by_account", (q) => q.eq("accountId", accountId))
@@ -38,38 +51,17 @@ async function bump(
38
51
  key: string,
39
52
  removed = false,
40
53
  ) {
41
- const row = await ctx.db
42
- .query("payoutFinancialRevisions")
43
- .withIndex("by_account", (q) => q.eq("accountId", accountId))
44
- .unique();
45
- const fence = await ctx.db
46
- .query("payoutRiskRevisions")
47
- .withIndex("by_account", (q) => q.eq("accountId", accountId))
48
- .unique();
49
- if (row && fence && row.riskRevision !== fence.riskRevision)
50
- throw new Error("Financial risk revisions disagree.");
51
- const next = {
52
- revision: add(row?.revision ?? 0, 1),
53
- riskRevision: add(
54
- fence?.riskRevision ?? row?.riskRevision ?? 0,
55
- risk ? 1 : 0,
56
- ),
57
- };
58
- if (row) await ctx.db.patch("payoutFinancialRevisions", row._id, next);
59
- else await ctx.db.insert("payoutFinancialRevisions", { accountId, ...next });
60
- if (!fence)
61
- await ctx.db.insert("payoutRiskRevisions", {
62
- accountId,
63
- riskRevision: next.riskRevision,
64
- });
65
- else if (risk)
66
- await ctx.db.patch("payoutRiskRevisions", fence._id, {
67
- riskRevision: next.riskRevision,
68
- });
54
+ const canonical = await journalHead(ctx, accountId);
55
+ let riskCounter: number;
56
+ if (canonical)
57
+ riskCounter = (await appendRevision(ctx, canonical, risk)).riskRevision;
58
+ else {
59
+ riskCounter = await bumpLegacyRevision(ctx, accountId, risk);
60
+ }
69
61
  if (risk)
70
62
  await ctx.db.insert("payoutRiskEvents", {
71
63
  accountId,
72
- riskRevision: next.riskRevision,
64
+ riskRevision: riskCounter,
73
65
  kind,
74
66
  key,
75
67
  ...(removed ? { removed: true } : {}),
@@ -0,0 +1,62 @@
1
+ // @vitest-environment edge-runtime
2
+ import { convexTest } from "convex-test";
3
+ import { makeFunctionReference } from "convex/server";
4
+ import { expect, it } from "vitest";
5
+ import { schema, modules } from "../../test.js";
6
+ import { claimReversalSlicesDefinition } from "../connect/reversalClaims.js";
7
+ const payload = makeFunctionReference<"query">(
8
+ "reversalObservations/queries:payload",
9
+ );
10
+ it("preserves exact near-limit source payloads without appending diagnostic annotations", async () => {
11
+ const t = convexTest(schema, modules);
12
+ const operationId = "op_" + "x".repeat(1_000_000);
13
+ await t.run((ctx) =>
14
+ claimReversalSlicesDefinition.handler(ctx, {
15
+ operationId,
16
+ sourceChargeId: "ch_large",
17
+ mode: { kind: "full" },
18
+ }),
19
+ );
20
+ const source = await t.run((ctx) =>
21
+ ctx.db.query("transferReversalOps").first(),
22
+ );
23
+ const result = await t.query(payload, {
24
+ operationId: source!._id,
25
+ version: "original",
26
+ });
27
+ expect(result.payload.operationId === operationId).toBe(true);
28
+ expect(Object.keys(result.payload).sort()).toEqual([
29
+ "_creationTime",
30
+ "_id",
31
+ "operationId",
32
+ "slices",
33
+ "sourceChargeId",
34
+ ]);
35
+ });
36
+ it("retains every original ref across the 64-slot boundary", async () => {
37
+ const t = convexTest(schema, modules);
38
+ await t.run(async (ctx) => {
39
+ for (let i = 0; i < 65; i++)
40
+ await ctx.db.insert("transfers", {
41
+ stripeTransferId: `tr_boundary_${i}`,
42
+ sourceChargeId: "ch_boundary",
43
+ destinationAccountId: `acct_boundary_${i}`,
44
+ amount: 1,
45
+ currency: "usd",
46
+ status: "paid",
47
+ role: "store",
48
+ });
49
+ });
50
+ await t.run((ctx) =>
51
+ claimReversalSlicesDefinition.handler(ctx, {
52
+ operationId: "op_boundary",
53
+ sourceChargeId: "ch_boundary",
54
+ mode: { kind: "full" },
55
+ }),
56
+ );
57
+ const chunks = await t.run((ctx) =>
58
+ ctx.db.query("reversalObservationRefs").take(5),
59
+ );
60
+ expect(chunks.map((x) => x.refs.length)).toEqual([64, 1]);
61
+ expect(chunks.flatMap((x) => x.refs).filter(Boolean)).toHaveLength(65);
62
+ });