@terreno/api 0.30.0 → 56.0.0-beta.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 (226) hide show
  1. package/dist/api.d.ts +10 -0
  2. package/dist/api.js +110 -361
  3. package/dist/auth.d.ts +26 -0
  4. package/dist/auth.js +100 -1
  5. package/dist/betterAuth.d.ts +5 -0
  6. package/dist/betterAuthSetup.js +23 -4
  7. package/dist/docLoader.js +12 -9
  8. package/dist/errors.d.ts +13 -0
  9. package/dist/errors.js +29 -1
  10. package/dist/index.d.ts +17 -1
  11. package/dist/index.js +29 -1
  12. package/dist/middleware.d.ts +7 -0
  13. package/dist/middleware.js +16 -1
  14. package/dist/openApiCompat.d.ts +10 -1
  15. package/dist/openApiCompat.js +115 -47
  16. package/dist/permissions.d.ts +27 -0
  17. package/dist/permissions.js +42 -1
  18. package/dist/plugins.d.ts +13 -0
  19. package/dist/plugins.js +35 -1
  20. package/dist/realtime/changeStreamWatcher.d.ts +100 -3
  21. package/dist/realtime/changeStreamWatcher.js +542 -137
  22. package/dist/realtime/realtimeApp.d.ts +2 -0
  23. package/dist/realtime/realtimeApp.js +73 -21
  24. package/dist/realtime/sessionRevalidation.d.ts +90 -0
  25. package/dist/realtime/sessionRevalidation.js +438 -0
  26. package/dist/realtime/socketAuth.d.ts +97 -0
  27. package/dist/realtime/socketAuth.js +272 -0
  28. package/dist/realtime/socketUser.d.ts +54 -0
  29. package/dist/realtime/socketUser.js +75 -5
  30. package/dist/realtime/types.d.ts +40 -0
  31. package/dist/secretProviders.d.ts +23 -0
  32. package/dist/secretProviders.js +9 -3
  33. package/dist/sync/executors.d.ts +198 -0
  34. package/dist/sync/executors.js +670 -0
  35. package/dist/sync/loadHarness.js +807 -0
  36. package/dist/sync/models.d.ts +216 -0
  37. package/dist/sync/models.js +644 -0
  38. package/dist/sync/mutationHandler.d.ts +97 -0
  39. package/dist/sync/mutationHandler.js +886 -0
  40. package/dist/sync/registry.d.ts +73 -0
  41. package/dist/sync/registry.js +223 -0
  42. package/dist/sync/routes.d.ts +62 -0
  43. package/dist/sync/routes.js +936 -0
  44. package/dist/sync/scripts/compactTombstones.d.ts +47 -0
  45. package/dist/sync/scripts/compactTombstones.js +270 -0
  46. package/dist/sync/serialize.d.ts +20 -0
  47. package/dist/{tests/bunSetup.js → sync/serialize.js} +35 -68
  48. package/dist/sync/socketHandlers.d.ts +54 -0
  49. package/dist/sync/socketHandlers.js +470 -0
  50. package/dist/sync/streams.d.ts +85 -0
  51. package/dist/sync/streams.js +221 -0
  52. package/dist/sync/syncApp.d.ts +29 -0
  53. package/dist/sync/syncApp.js +44 -0
  54. package/dist/sync/syncBatch.d.ts +71 -0
  55. package/dist/sync/syncBatch.js +252 -0
  56. package/dist/sync/syncSeqPlugin.d.ts +8 -0
  57. package/dist/sync/syncSeqPlugin.js +903 -0
  58. package/dist/sync/types.d.ts +254 -0
  59. package/dist/sync/types.js +9 -0
  60. package/dist/terrenoApp.js +90 -27
  61. package/dist/vendor/wesleytodd-openapi/index.d.ts +1 -1
  62. package/dist/vendor/wesleytodd-openapi/lib/ui.d.ts +2 -1
  63. package/package.json +7 -6
  64. package/src/__tests__/openApiCompat.test.ts +20 -0
  65. package/src/actions.openApi.test.ts +7 -10
  66. package/src/api.test.ts +12 -0
  67. package/src/api.ts +87 -295
  68. package/src/auth.test.ts +128 -176
  69. package/src/auth.ts +109 -0
  70. package/src/betterAuth.ts +6 -0
  71. package/src/betterAuthSetup.test.ts +34 -0
  72. package/src/betterAuthSetup.ts +20 -1
  73. package/src/docLoader.ts +3 -1
  74. package/src/errors.ts +33 -0
  75. package/src/expressServer.test.ts +7 -1
  76. package/src/index.ts +42 -0
  77. package/src/middleware.test.ts +40 -1
  78. package/src/middleware.ts +15 -0
  79. package/src/openApiCompat.ts +99 -45
  80. package/src/permissions.test.ts +75 -1
  81. package/src/permissions.ts +49 -0
  82. package/src/plugins.test.ts +54 -0
  83. package/src/plugins.ts +43 -0
  84. package/src/realtime/changeStreamWatcher.ts +552 -114
  85. package/src/realtime/realtime.test.ts +157 -0
  86. package/src/realtime/realtimeApp.ts +75 -11
  87. package/src/realtime/sessionRevalidation.test.ts +423 -0
  88. package/src/realtime/sessionRevalidation.ts +273 -0
  89. package/src/realtime/socketAuth.test.ts +355 -0
  90. package/src/realtime/socketAuth.ts +228 -0
  91. package/src/realtime/socketUser.ts +69 -0
  92. package/src/realtime/types.ts +40 -0
  93. package/src/secretProviders.test.ts +7 -1
  94. package/src/secretProviders.ts +15 -3
  95. package/src/sync/ensureSyncIndexes.test.ts +144 -0
  96. package/src/sync/executors.test.ts +882 -0
  97. package/src/sync/executors.ts +703 -0
  98. package/src/sync/integration.test.ts +1160 -0
  99. package/src/sync/loadHarness.ts +618 -0
  100. package/src/sync/models.ts +640 -0
  101. package/src/sync/mutationHandler.test.ts +1252 -0
  102. package/src/sync/mutationHandler.ts +850 -0
  103. package/src/sync/registry.ts +232 -0
  104. package/src/sync/routes.ts +812 -0
  105. package/src/sync/scripts/compactTombstones.test.ts +249 -0
  106. package/src/sync/scripts/compactTombstones.ts +145 -0
  107. package/src/sync/serialize.ts +48 -0
  108. package/src/sync/sessionRevalidationIntegration.test.ts +281 -0
  109. package/src/sync/socketHandlers.ts +320 -0
  110. package/src/sync/streams.ts +188 -0
  111. package/src/sync/sync.test.ts +582 -0
  112. package/src/sync/syncApp.ts +44 -0
  113. package/src/sync/syncBatch.ts +219 -0
  114. package/src/sync/syncFrontier.test.ts +494 -0
  115. package/src/sync/syncPhaseC.test.ts +718 -0
  116. package/src/sync/syncRoutes.test.ts +865 -0
  117. package/src/sync/syncSeqPlugin.ts +738 -0
  118. package/src/sync/syncSocket.test.ts +1440 -0
  119. package/src/sync/types.ts +270 -0
  120. package/src/terrenoApp.ts +37 -17
  121. package/src/tests/bunSetup.ts +8 -0
  122. package/tsconfig.json +4 -4
  123. package/tsconfig.typedoc.json +7 -1
  124. package/dist/__tests__/openApiCompat.test.js +0 -317
  125. package/dist/__tests__/versionCheckPlugin.test.d.ts +0 -1
  126. package/dist/__tests__/versionCheckPlugin.test.js +0 -597
  127. package/dist/actions.openApi.test.d.ts +0 -1
  128. package/dist/actions.openApi.test.js +0 -255
  129. package/dist/actions.test.d.ts +0 -1
  130. package/dist/actions.test.js +0 -1089
  131. package/dist/api.arrayOperations.test.d.ts +0 -1
  132. package/dist/api.arrayOperations.test.js +0 -878
  133. package/dist/api.asyncHandler.test.d.ts +0 -1
  134. package/dist/api.asyncHandler.test.js +0 -236
  135. package/dist/api.coverage.test.d.ts +0 -1
  136. package/dist/api.coverage.test.js +0 -194
  137. package/dist/api.errorPaths.test.d.ts +0 -1
  138. package/dist/api.errorPaths.test.js +0 -801
  139. package/dist/api.errors.test.d.ts +0 -1
  140. package/dist/api.errors.test.js +0 -185
  141. package/dist/api.hooks.test.d.ts +0 -1
  142. package/dist/api.hooks.test.js +0 -950
  143. package/dist/api.query.test.d.ts +0 -1
  144. package/dist/api.query.test.js +0 -948
  145. package/dist/api.test.d.ts +0 -1
  146. package/dist/api.test.js +0 -2820
  147. package/dist/auth.compile.test.d.ts +0 -1
  148. package/dist/auth.compile.test.js +0 -201
  149. package/dist/auth.coverage.test.d.ts +0 -1
  150. package/dist/auth.coverage.test.js +0 -202
  151. package/dist/auth.test.d.ts +0 -1
  152. package/dist/auth.test.js +0 -2286
  153. package/dist/betterAuth.test.d.ts +0 -1
  154. package/dist/betterAuth.test.js +0 -181
  155. package/dist/betterAuthApp.test.d.ts +0 -1
  156. package/dist/betterAuthApp.test.js +0 -242
  157. package/dist/betterAuthSetup.test.d.ts +0 -1
  158. package/dist/betterAuthSetup.test.js +0 -762
  159. package/dist/config.test.d.ts +0 -1
  160. package/dist/config.test.js +0 -353
  161. package/dist/configuration.test.d.ts +0 -1
  162. package/dist/configuration.test.js +0 -980
  163. package/dist/configurationPlugin.test.d.ts +0 -1
  164. package/dist/configurationPlugin.test.js +0 -827
  165. package/dist/consentApp.test.d.ts +0 -1
  166. package/dist/consentApp.test.js +0 -1415
  167. package/dist/docLoader.test.d.ts +0 -1
  168. package/dist/docLoader.test.js +0 -137
  169. package/dist/envConfigurationPlugin.test.d.ts +0 -1
  170. package/dist/envConfigurationPlugin.test.js +0 -369
  171. package/dist/errors.test.d.ts +0 -1
  172. package/dist/errors.test.js +0 -607
  173. package/dist/expressServer.test.d.ts +0 -1
  174. package/dist/expressServer.test.js +0 -1249
  175. package/dist/githubAuth.test.d.ts +0 -1
  176. package/dist/githubAuth.test.js +0 -1142
  177. package/dist/httpClient.test.d.ts +0 -1
  178. package/dist/httpClient.test.js +0 -1471
  179. package/dist/logger.test.d.ts +0 -1
  180. package/dist/logger.test.js +0 -685
  181. package/dist/middleware.test.d.ts +0 -1
  182. package/dist/middleware.test.js +0 -241
  183. package/dist/notifiers/googleChatNotifier.test.d.ts +0 -1
  184. package/dist/notifiers/googleChatNotifier.test.js +0 -298
  185. package/dist/notifiers/slackNotifier.test.d.ts +0 -1
  186. package/dist/notifiers/slackNotifier.test.js +0 -297
  187. package/dist/notifiers/zoomNotifier.test.d.ts +0 -1
  188. package/dist/notifiers/zoomNotifier.test.js +0 -373
  189. package/dist/openApi.test.d.ts +0 -1
  190. package/dist/openApi.test.js +0 -620
  191. package/dist/openApiBuilder.test.d.ts +0 -1
  192. package/dist/openApiBuilder.test.js +0 -601
  193. package/dist/openApiEtag.test.d.ts +0 -1
  194. package/dist/openApiEtag.test.js +0 -86
  195. package/dist/openApiValidator.test.d.ts +0 -1
  196. package/dist/openApiValidator.test.js +0 -761
  197. package/dist/permissions.middleware.test.d.ts +0 -1
  198. package/dist/permissions.middleware.test.js +0 -308
  199. package/dist/permissions.test.d.ts +0 -1
  200. package/dist/permissions.test.js +0 -439
  201. package/dist/plugins.test.d.ts +0 -1
  202. package/dist/plugins.test.js +0 -890
  203. package/dist/populate.test.d.ts +0 -1
  204. package/dist/populate.test.js +0 -373
  205. package/dist/realtime/realtime.test.d.ts +0 -10
  206. package/dist/realtime/realtime.test.js +0 -3982
  207. package/dist/requestContext.test.d.ts +0 -1
  208. package/dist/requestContext.test.js +0 -412
  209. package/dist/scriptRunner.test.d.ts +0 -1
  210. package/dist/scriptRunner.test.js +0 -386
  211. package/dist/secretProviders.test.d.ts +0 -1
  212. package/dist/secretProviders.test.js +0 -726
  213. package/dist/syncConsents.test.d.ts +0 -1
  214. package/dist/syncConsents.test.js +0 -522
  215. package/dist/terrenoApp.test.d.ts +0 -1
  216. package/dist/terrenoApp.test.js +0 -489
  217. package/dist/tests/bunSetup.d.ts +0 -1
  218. package/dist/tests/fixtures/compileAuthEntry.d.ts +0 -1
  219. package/dist/tests/fixtures/compileAuthEntry.js +0 -37
  220. package/dist/tests/testEnv.d.ts +0 -0
  221. package/dist/tests/testEnv.js +0 -6
  222. package/dist/transformers.test.d.ts +0 -1
  223. package/dist/transformers.test.js +0 -423
  224. package/dist/utils.test.d.ts +0 -1
  225. package/dist/utils.test.js +0 -242
  226. /package/dist/{__tests__/openApiCompat.test.d.ts → sync/loadHarness.d.ts} +0 -0
@@ -0,0 +1,850 @@
1
+ // noExplicitAny: the mutation handler operates generically across registered models
2
+ // biome-ignore-all lint/suspicious/noExplicitAny: the mutation handler operates generically across registered models
3
+ import type express from "express";
4
+ import {DateTime} from "luxon";
5
+ import mongoose from "mongoose";
6
+ import type {User} from "../auth";
7
+ import {APIError, isAPIError} from "../errors";
8
+ import {createFeatureFlaggedLogger, logger} from "../logger";
9
+ import {findOneOrNoneFor} from "../plugins";
10
+ import {
11
+ executeCreate,
12
+ executeDelete,
13
+ executeUpdate,
14
+ isExecutorConflictError,
15
+ runPostCreate,
16
+ runPostDelete,
17
+ runPostUpdate,
18
+ } from "./executors";
19
+ import {SYNC_MUTATION_LEASE_MS, SyncMutation, type SyncMutationDocument} from "./models";
20
+ import {findSyncEntryByCollectionTag, type SyncRegistryEntry} from "./registry";
21
+ import {serializeSyncDoc} from "./routes";
22
+ import {getScopeField} from "./streams";
23
+ import type {
24
+ SyncAck,
25
+ SyncMutateBatchResponse,
26
+ SyncMutateRequest,
27
+ SyncNack,
28
+ SyncNackCode,
29
+ } from "./types";
30
+
31
+ export type SyncMutationScopeResolver = (
32
+ user: User,
33
+ entry: SyncRegistryEntry
34
+ ) => Promise<string[]> | string[];
35
+
36
+ /**
37
+ * Per-mutation success traces (`Mutation applied`) are high-volume. Gate them behind
38
+ * `SYNC_DEBUG=true` so they stay silent by default even when Winston's console level is
39
+ * `debug`.
40
+ */
41
+ const syncDebugLog = createFeatureFlaggedLogger({
42
+ isEnabled: () => process.env.SYNC_DEBUG === "true",
43
+ });
44
+
45
+ /**
46
+ * C6 (M6): enforce write scope at the sync boundary regardless of consumer `preCreate`
47
+ * quality. For `owner` strategy, force/verify the owner field equals the authenticated
48
+ * user id; for `tenant` strategy, verify the incoming tenant value is in the user's
49
+ * memberships. Throws a 403 APIError (mapped to `unauthorized`) otherwise. A no-op for
50
+ * broadcast/custom scopes and for update data that does not touch the scope field.
51
+ */
52
+ const enforceWriteScope = async ({
53
+ entry,
54
+ user,
55
+ operation,
56
+ data,
57
+ scopeResolver,
58
+ }: {
59
+ entry: SyncRegistryEntry;
60
+ user: User;
61
+ operation: "create" | "update" | "delete";
62
+ data: Record<string, unknown> | undefined;
63
+ scopeResolver?: SyncMutationScopeResolver;
64
+ }): Promise<void> => {
65
+ if (operation === "delete") {
66
+ return;
67
+ }
68
+ const {scope} = entry.config;
69
+ if (typeof scope === "function" || scope.type === "broadcast") {
70
+ return;
71
+ }
72
+ const field = getScopeField(scope) as string;
73
+ const incoming = data?.[field];
74
+ if (scope.type === "owner") {
75
+ // Create must belong to the caller; an update may not move ownership to someone else.
76
+ if (operation === "create" && (incoming === undefined || incoming === null)) {
77
+ // preCreate typically injects ownerId; nothing to verify if absent here.
78
+ return;
79
+ }
80
+ if (incoming !== undefined && incoming !== null && String(incoming) !== String(user.id)) {
81
+ throw new APIError({
82
+ status: 403,
83
+ title: `Write scope violation on ${entry.collectionTag}: ${field} must be the caller`,
84
+ });
85
+ }
86
+ return;
87
+ }
88
+ // Tenant: the incoming value (create) or the changed value (update) must be a membership.
89
+ if (incoming === undefined || incoming === null) {
90
+ // Nothing to check against memberships yet. A create may legitimately omit the tenant
91
+ // field for `preCreate` to inject from the authenticated user (see the example
92
+ // projects router), and an update that does not touch the scope field leaves it
93
+ // alone. Task 9.21's "never file a document under `tenant:undefined`" guarantee is
94
+ // enforced by resolveStreamForDoc on the write path instead, which sees the value
95
+ // AFTER preCreate has run — inferring intent from the mere presence of a preCreate
96
+ // hook would let an unrelated one (logging, timestamps) silently reopen that hole.
97
+ return;
98
+ }
99
+ if (!scopeResolver) {
100
+ throw new APIError({
101
+ status: 500,
102
+ title: `Sync collection ${entry.collectionTag} is tenant-scoped but SyncApp has no getUserScopes resolver`,
103
+ });
104
+ }
105
+ const memberships = await scopeResolver(user, entry);
106
+ if (!memberships.map(String).includes(String(incoming))) {
107
+ throw new APIError({
108
+ status: 403,
109
+ title: `Write scope violation on ${entry.collectionTag}: ${field} ${String(incoming)} is not a membership`,
110
+ });
111
+ }
112
+ };
113
+
114
+ /**
115
+ * Shared mutation handler for the sync channel: `POST /sync/mutate` (HTTP fallback)
116
+ * and `sync:mutate` (socket) both delegate here.
117
+ *
118
+ * Idempotency (atomic claim): the handler inserts a SyncMutation ledger row with status
119
+ * `pending` (unique index on mutationId) *before* applying. A duplicate-key error means
120
+ * another delivery owns or already completed the mutation, so the handler polls the
121
+ * existing row and returns the recorded outcome instead of re-applying — closing the
122
+ * race where a socket retry and the HTTP fallback deliver the same mutation concurrently.
123
+ *
124
+ * Conflict rule: the client's `baseVersion` (the `_syncSeq` it last saw) is passed to
125
+ * executeUpdate as a seq concurrency check; a mismatch yields a `conflict` nack carrying
126
+ * the canonical serialized server document and its current seq.
127
+ *
128
+ * C5 crash resilience (FIX 6):
129
+ * - **Lease/takeover (M4).** A `pending` row carries `claimedAt`. If a server crashes
130
+ * between claiming the row and finalizing it, the mutationId would otherwise be wedged
131
+ * for the full 30-day TTL. A duplicate-claim attempt older than
132
+ * {@link SYNC_MUTATION_LEASE_MS} may take over via an atomic
133
+ * `findOneAndUpdate({_id, status: "pending", claimedAt: {$lt: cutoff}}, {$set: {claimedAt: now}})`
134
+ * and re-run the mutation as the new claimant. Because the original attempt may have
135
+ * already landed the write before crashing, the executor path tolerates that: a create
136
+ * that hits E11000 on the SAME `_id` reads the doc back and reports it as the ack instead
137
+ * of nacking; an update/delete whose current server seq already reflects this mutation's
138
+ * expected post-write seq (`baseVersion + 1`) is treated as already-applied and reported
139
+ * from the current doc rather than re-executed (which would otherwise spuriously conflict
140
+ * against the write it is itself retrying).
141
+ * - **Finalize-before-post-hooks (M5).** The pipeline is: document write → finalize the
142
+ * ledger `applied` (with the ack payload) → THEN run the model's post-hook
143
+ * (`postCreate`/`postUpdate`/`postDelete`). A post-hook throw is `logger.error`'d and
144
+ * reported back as an ack with a `warning` field — never converted into a nack, since the
145
+ * write (and its delta) already committed and rolling the client back would be a lie. If
146
+ * the `applied` finalize itself throws, the request is allowed to fail loudly (500); the
147
+ * client's transport retry lands on the lease-takeover path above, which resolves it from
148
+ * the ledger/doc state rather than double-applying.
149
+ */
150
+
151
+ /** Outcome of applying a sync mutation: an ack for the client, or a typed nack. */
152
+ export type SyncMutationOutcome = {type: "ack"; ack: SyncAck} | {type: "nack"; nack: SyncNack};
153
+
154
+ const PENDING_POLL_ATTEMPTS = 10;
155
+ const PENDING_POLL_INTERVAL_MS = 100;
156
+ const VALID_OPERATIONS = new Set(["create", "update", "delete"]);
157
+
158
+ /** Maximum mutations accepted in a single `sync:mutateBatch` / `POST /sync/mutate/batch` request. */
159
+ export const MAX_SYNC_MUTATIONS_PER_BATCH = 100;
160
+
161
+ const sleep = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));
162
+
163
+ const makeNack = (nack: SyncNack): SyncMutationOutcome => {
164
+ logger.info("[sync] Mutation nacked", {code: nack.code, mutationId: nack.mutationId});
165
+ return {nack, type: "nack"};
166
+ };
167
+
168
+ /**
169
+ * Load a document by id INCLUDING tombstones (`isDeletedPlugin` would otherwise filter a
170
+ * soft-deleted doc out) and serialize it for a sync payload. Returns undefined when the
171
+ * document is gone, the id does not cast, or the consumer's serializer throws — callers
172
+ * treat a missing `serverDoc` as "seq only", which is what the client needs to re-base.
173
+ */
174
+ const serializeLiveDoc = async ({
175
+ entry,
176
+ id,
177
+ request,
178
+ }: {
179
+ entry: SyncRegistryEntry;
180
+ id: string | undefined;
181
+ request: express.Request;
182
+ }): Promise<unknown> => {
183
+ if (!id) {
184
+ return undefined;
185
+ }
186
+ try {
187
+ const model = mongoose.model(entry.modelName);
188
+ const found = await model.find({_id: id, deleted: {$in: [true, false]}}).limit(1);
189
+ const doc = found[0] as mongoose.Document | undefined;
190
+ if (!doc) {
191
+ return undefined;
192
+ }
193
+ return await serializeSyncDoc({doc, entry, req: request});
194
+ } catch (error: unknown) {
195
+ logger.warn("[sync] Failed to serialize the server doc for a recorded conflict", {
196
+ collection: entry.collectionTag,
197
+ error: String(error),
198
+ id,
199
+ });
200
+ return undefined;
201
+ }
202
+ };
203
+
204
+ /**
205
+ * Reconstruct the outcome recorded on a finalized ledger row; undefined while pending.
206
+ *
207
+ * Task 9.21: the row stores no document data, so a recorded `conflicted` outcome
208
+ * re-serializes the LIVE document from `resultId`. Besides keeping PHI out of
209
+ * `syncmutations` for the ledger's 30-day TTL, this hands the client current server
210
+ * state rather than a snapshot frozen at first-conflict time.
211
+ */
212
+ const outcomeFromLedgerRow = async ({
213
+ entry,
214
+ request,
215
+ row,
216
+ }: {
217
+ entry: SyncRegistryEntry;
218
+ request: express.Request;
219
+ row: SyncMutationDocument;
220
+ }): Promise<SyncMutationOutcome | undefined> => {
221
+ if (row.status === "applied") {
222
+ return {
223
+ ack: {id: row.resultId ?? "", mutationId: row.mutationId, seq: row.resultSeq ?? 0},
224
+ type: "ack",
225
+ };
226
+ }
227
+ if (row.status === "conflicted") {
228
+ return makeNack({
229
+ code: "conflict",
230
+ message: row.error,
231
+ mutationId: row.mutationId,
232
+ serverDoc: await serializeLiveDoc({entry, id: row.resultId, request}),
233
+ serverSeq: row.resultSeq,
234
+ });
235
+ }
236
+ if (row.status === "failed") {
237
+ return makeNack({
238
+ code: (row.nackCode as SyncNackCode) ?? "error",
239
+ message: row.error,
240
+ mutationId: row.mutationId,
241
+ });
242
+ }
243
+ return undefined;
244
+ };
245
+
246
+ /**
247
+ * C5 (FIX 6) lease takeover: a `pending` row older than {@link SYNC_MUTATION_LEASE_MS}
248
+ * is assumed abandoned (the original claimant crashed between claiming the row and
249
+ * finalizing it) — atomically re-claim it via `findOneAndUpdate` so exactly one
250
+ * concurrent delivery wins the takeover. Returns the re-claimed row (with a bumped
251
+ * `claimedAt`) on success, or `undefined` if the row is not stale/pending (someone else
252
+ * is actively working it, or it already finalized).
253
+ */
254
+ const takeoverStaleLease = async (
255
+ mutationId: string
256
+ ): Promise<SyncMutationDocument | undefined> => {
257
+ const cutoff = DateTime.now().minus({milliseconds: SYNC_MUTATION_LEASE_MS}).toJSDate();
258
+ const claimed = await SyncMutation.findOneAndUpdate(
259
+ {claimedAt: {$lt: cutoff}, mutationId, status: "pending"},
260
+ {$set: {claimedAt: new Date()}},
261
+ {new: true}
262
+ );
263
+ return claimed ?? undefined;
264
+ };
265
+
266
+ /**
267
+ * Another delivery claimed this mutationId: poll the ledger row until its status leaves
268
+ * `pending` and return the recorded outcome. Before each poll, attempt a lease takeover
269
+ * (C5/FIX 6) — a `pending` row older than {@link SYNC_MUTATION_LEASE_MS} is assumed
270
+ * abandoned by a crashed claimant, so this delivery re-claims and re-applies it instead
271
+ * of waiting out the full poll budget (or worse, the 30-day TTL). If the row stays
272
+ * pending and un-stale past the timeout, nack `error` without modifying the row — the
273
+ * owning delivery will still finalize it.
274
+ */
275
+ const waitForRecordedOutcome = async ({
276
+ entry,
277
+ mutationId,
278
+ request,
279
+ user,
280
+ onTakeover,
281
+ }: {
282
+ entry: SyncRegistryEntry;
283
+ mutationId: string;
284
+ request: express.Request;
285
+ user: User;
286
+ /** Invoked with the re-claimed row when a stale lease is taken over. */
287
+ onTakeover: (row: SyncMutationDocument) => Promise<SyncMutationOutcome>;
288
+ }): Promise<SyncMutationOutcome> => {
289
+ for (let attempt = 0; attempt < PENDING_POLL_ATTEMPTS; attempt++) {
290
+ const row = await findOneOrNoneFor(SyncMutation, {mutationId});
291
+ if (row) {
292
+ if (String(row.userId) !== String(user.id)) {
293
+ return makeNack({
294
+ code: "unauthorized",
295
+ message: `Mutation ${mutationId} was submitted by another user`,
296
+ mutationId,
297
+ });
298
+ }
299
+ const outcome = await outcomeFromLedgerRow({entry, request, row});
300
+ if (outcome) {
301
+ return outcome;
302
+ }
303
+ if (row.status === "pending") {
304
+ const takenOver = await takeoverStaleLease(mutationId);
305
+ if (takenOver) {
306
+ logger.warn("[sync] Took over a stale mutation lease", {
307
+ mutationId,
308
+ staleForMs: Date.now() - new Date(row.claimedAt).getTime(),
309
+ });
310
+ return onTakeover(takenOver);
311
+ }
312
+ }
313
+ }
314
+ await sleep(PENDING_POLL_INTERVAL_MS);
315
+ }
316
+ return makeNack({
317
+ code: "error",
318
+ message: `Mutation ${mutationId} is still in flight`,
319
+ mutationId,
320
+ });
321
+ };
322
+
323
+ /**
324
+ * C5 (FIX 6): true when `error` is (or wraps, via `APIError.error` — see
325
+ * `executeCreate`'s `model.create()` catch, which wraps the raw Mongo driver
326
+ * error in an APIError before it ever reaches the caller) a MongoDB E11000
327
+ * duplicate-key error.
328
+ */
329
+ const isE11000Error = (error: unknown): boolean => {
330
+ const candidate = error as {code?: number; error?: unknown};
331
+ if (candidate?.code === 11000) {
332
+ return true;
333
+ }
334
+ const wrapped = candidate?.error as {code?: number} | undefined;
335
+ return wrapped?.code === 11000;
336
+ };
337
+
338
+ /**
339
+ * C5 (FIX 6): true when every key/value in `data` (the mutation's own
340
+ * intended write) is already present on `doc` — used alongside the
341
+ * expected-post-write-seq check to distinguish "this mutation's own write
342
+ * already landed" (safe to report as already-applied) from "a genuinely
343
+ * different write landed and happens to have advanced the seq by exactly
344
+ * one" (a real conflict; a seq match alone cannot tell these apart).
345
+ */
346
+ const docMatchesMutationData = (
347
+ doc: unknown,
348
+ data: Record<string, unknown> | undefined
349
+ ): boolean => {
350
+ if (!data) {
351
+ return true;
352
+ }
353
+ const asDocument = doc as {toObject?: () => Record<string, unknown>} | undefined;
354
+ const plain =
355
+ typeof asDocument?.toObject === "function"
356
+ ? asDocument.toObject()
357
+ : (doc as Record<string, unknown>);
358
+ return Object.entries(data).every(([key, value]) => {
359
+ const current = plain?.[key];
360
+ if (current instanceof Date && typeof value === "string") {
361
+ return current.toISOString() === new Date(value).toISOString();
362
+ }
363
+ return JSON.stringify(current) === JSON.stringify(value);
364
+ });
365
+ };
366
+
367
+ const nackCodeForError = (error: unknown): SyncNackCode => {
368
+ if (!isAPIError(error)) {
369
+ return "error";
370
+ }
371
+ if (error.status === 403 || error.status === 405) {
372
+ return "unauthorized";
373
+ }
374
+ if (error.status === 400 || error.status === 404 || error.status === 422) {
375
+ return "validation";
376
+ }
377
+ return "error";
378
+ };
379
+
380
+ /** Record a failed/conflicted outcome on the claimed ledger row and build the nack. */
381
+ const finalizeNack = async ({
382
+ claimedId,
383
+ entry,
384
+ error,
385
+ mutation,
386
+ request,
387
+ }: {
388
+ claimedId: mongoose.Types.ObjectId;
389
+ entry: SyncRegistryEntry;
390
+ error: unknown;
391
+ mutation: SyncMutateRequest;
392
+ request: express.Request;
393
+ }): Promise<SyncMutationOutcome> => {
394
+ // Duck-typed: `instanceof` breaks for Error subclasses in the compiled ES5 dist.
395
+ if (isExecutorConflictError(error)) {
396
+ let serverDoc: unknown;
397
+ try {
398
+ serverDoc = await serializeSyncDoc({
399
+ doc: error.doc as mongoose.Document,
400
+ entry,
401
+ req: request,
402
+ });
403
+ } catch (serializeError: unknown) {
404
+ logger.warn("[sync] Failed to serialize conflict server doc", {
405
+ error: String(serializeError),
406
+ mutationId: mutation.mutationId,
407
+ });
408
+ }
409
+ // Task 9.21: record only the pointer ({resultId, resultSeq}), never `serverDoc` —
410
+ // a duplicate delivery re-serializes the live document from `resultId`.
411
+ const resultId =
412
+ (error.doc as {_id?: unknown} | undefined)?._id !== undefined
413
+ ? String((error.doc as {_id: unknown})._id)
414
+ : mutation.id;
415
+ await SyncMutation.updateOne(
416
+ {_id: claimedId},
417
+ {
418
+ $set: {
419
+ error: error.title,
420
+ nackCode: "conflict",
421
+ resultId,
422
+ resultSeq: error.serverSeq,
423
+ status: "conflicted",
424
+ },
425
+ }
426
+ );
427
+ return makeNack({
428
+ code: "conflict",
429
+ message: error.title,
430
+ mutationId: mutation.mutationId,
431
+ serverDoc,
432
+ serverSeq: error.serverSeq,
433
+ });
434
+ }
435
+
436
+ const code = nackCodeForError(error);
437
+ const message = isAPIError(error) ? error.title : String(error);
438
+ if (code === "error") {
439
+ logger.warn("[sync] Mutation failed unexpectedly", {
440
+ collection: mutation.collection,
441
+ error: message,
442
+ mutationId: mutation.mutationId,
443
+ });
444
+ // Task 9.18: an `error`-class failure is non-deterministic (DB hiccup, replica
445
+ // step-down) — it is not a verdict on the mutation. Recording it `failed` would make
446
+ // it sticky for the ledger's 30-day TTL, so every replay of the same mutationId reads
447
+ // the nack back and the client's durable outbox retries forever without the mutation
448
+ // ever re-executing. Release the claim instead: the next delivery re-claims the
449
+ // mutationId and genuinely re-runs the write. Deterministic outcomes
450
+ // (validation/unauthorized/conflict) stay recorded — replaying those must not re-run.
451
+ await SyncMutation.deleteOne({_id: claimedId});
452
+ return makeNack({code, message, mutationId: mutation.mutationId});
453
+ }
454
+ await SyncMutation.updateOne(
455
+ {_id: claimedId},
456
+ {$set: {error: message, nackCode: code, status: "failed"}}
457
+ );
458
+ return makeNack({code, message, mutationId: mutation.mutationId});
459
+ };
460
+
461
+ /**
462
+ * C5 (FIX 6): read the doc back and report it as the ack for an ALREADY-APPLIED write —
463
+ * used both by the create-E11000 tolerance and the update/delete already-applied check.
464
+ * Finalizes the ledger `applied` from the doc's actual state (not assumed) before
465
+ * returning, exactly like the normal apply path, so a subsequent duplicate delivery
466
+ * reads back the same outcome.
467
+ */
468
+ const finalizeAlreadyApplied = async ({
469
+ claimedId,
470
+ doc,
471
+ mutation,
472
+ }: {
473
+ claimedId: mongoose.Types.ObjectId;
474
+ doc: mongoose.Document;
475
+ mutation: SyncMutateRequest;
476
+ }): Promise<{resultId: string; resultSeq: number}> => {
477
+ const resultId = String(doc._id);
478
+ const resultSeq = (doc as unknown as {_syncSeq?: number})._syncSeq ?? 0;
479
+ await SyncMutation.updateOne({_id: claimedId}, {$set: {resultId, resultSeq, status: "applied"}});
480
+ logger.info("[sync] Mutation already applied (lease-takeover tolerance)", {
481
+ collection: mutation.collection,
482
+ mutationId: mutation.mutationId,
483
+ seq: resultSeq,
484
+ });
485
+ return {resultId, resultSeq};
486
+ };
487
+
488
+ /**
489
+ * Apply a client mutation through the transport-agnostic executors (permissions,
490
+ * pre/post hooks, validation) against an ALREADY-CLAIMED ledger row (either a fresh claim
491
+ * or a lease takeover of an abandoned one — C5/FIX 6). Always finalizes the claimed row
492
+ * before returning so duplicate deliveries can read the outcome back.
493
+ *
494
+ * Reorder (M5): the document write finalizes the ledger `applied` BEFORE the model's
495
+ * post-hook runs. A post-hook throw is logged and reported as a `warning` on the ack —
496
+ * never converted into a nack, since the write already committed.
497
+ *
498
+ * Already-applied tolerance (M4, `isLeaseTakeover` only — a normal first attempt reports
499
+ * genuine conflicts/errors as usual): a lease takeover re-runs a mutation whose FIRST
500
+ * attempt may have already landed the write before crashing.
501
+ * - create: an E11000 on the same target `_id` is treated as success — the doc is read
502
+ * back and reported as the ack (a genuine `_id` collision from a DIFFERENT mutation is
503
+ * not expected for client-minted ids and is out of scope here).
504
+ * - update: re-checked reactively — if the executor's seq concurrency check throws a
505
+ * conflict whose `serverSeq` is EXACTLY `baseVersion + 1` (what this mutation's own
506
+ * write would have produced) while retrying via a lease takeover, that is treated as
507
+ * "this exact write already landed" rather than a genuine external conflict, and the
508
+ * current doc is reported as the ack instead of nacking.
509
+ * - delete: idempotent already (executeDelete on an already-deleted tombstone is a no-op
510
+ * success in this codebase's soft-delete model), so no special tolerance is needed.
511
+ */
512
+ const applyClaimedMutation = async ({
513
+ claimed,
514
+ entry,
515
+ mutation,
516
+ request,
517
+ user,
518
+ scopeResolver,
519
+ isLeaseTakeover = false,
520
+ }: {
521
+ claimed: SyncMutationDocument;
522
+ entry: SyncRegistryEntry;
523
+ mutation: SyncMutateRequest;
524
+ request: express.Request;
525
+ user: User;
526
+ scopeResolver?: SyncMutationScopeResolver;
527
+ /** True when `claimed` was re-claimed from a stale lease rather than freshly inserted. */
528
+ isLeaseTakeover?: boolean;
529
+ }): Promise<SyncMutationOutcome> => {
530
+ const mutationId = mutation.mutationId;
531
+
532
+ try {
533
+ // Task 9.18: resolving the model must be INSIDE the try — a MissingSchemaError thrown
534
+ // here would escape without finalizing the claimed row, wedging the mutationId
535
+ // `pending` for the whole lease window instead of nacking it.
536
+ const model = mongoose.model(entry.modelName);
537
+ // C6 (M6): sync-boundary write-scope backstop before any write pipeline runs.
538
+ await enforceWriteScope({
539
+ data: mutation.data,
540
+ entry,
541
+ operation: mutation.operation,
542
+ scopeResolver,
543
+ user,
544
+ });
545
+
546
+ let doc: mongoose.Document;
547
+ let postHook: (() => Promise<void>) | undefined;
548
+ if (mutation.operation === "create") {
549
+ const body: Record<string, unknown> = {...(mutation.data ?? {})};
550
+ if (mutation.id) {
551
+ body._id = mutation.id;
552
+ }
553
+ try {
554
+ const result = await executeCreate({
555
+ body,
556
+ model,
557
+ options: entry.options,
558
+ req: request,
559
+ skipPostHooks: true,
560
+ user,
561
+ });
562
+ doc = result.doc;
563
+ postHook = (): Promise<void> =>
564
+ runPostCreate({doc: result.doc, options: entry.options, request});
565
+ } catch (createError: unknown) {
566
+ // M4 (lease takeover only): an E11000 on the exact target _id is
567
+ // tolerated as "already applied" — a prior (crashed) attempt at
568
+ // THIS mutation landed the write before finalizing the ledger. A
569
+ // normal (non-takeover) first attempt reports the error as usual —
570
+ // client-minted UUIDs make a genuine unrelated _id collision
571
+ // vanishingly unlikely, so gating this on isLeaseTakeover keeps the
572
+ // tolerance scoped to its actual crash-recovery purpose.
573
+ if (isLeaseTakeover && isE11000Error(createError) && typeof mutation.id === "string") {
574
+ const existing = await findOneOrNoneFor(model, {_id: mutation.id});
575
+ if (existing) {
576
+ const {resultId, resultSeq} = await finalizeAlreadyApplied({
577
+ claimedId: claimed._id,
578
+ doc: existing as unknown as mongoose.Document,
579
+ mutation,
580
+ });
581
+ return {ack: {id: resultId, mutationId, seq: resultSeq}, type: "ack"};
582
+ }
583
+ }
584
+ throw createError;
585
+ }
586
+ } else if (mutation.operation === "update") {
587
+ try {
588
+ const result = await executeUpdate({
589
+ body: mutation.data ?? {},
590
+ concurrencyCheck: {baseSeq: mutation.baseVersion ?? 0, type: "seq"},
591
+ id: mutation.id as string,
592
+ model,
593
+ options: entry.options,
594
+ req: request,
595
+ skipPostHooks: true,
596
+ user,
597
+ });
598
+ doc = result.doc;
599
+ // biome-ignore lint/style/noNonNullAssertion: executeUpdate with skipPostHooks always returns cleanedBody/prevDoc.
600
+ const cleanedBody = result.cleanedBody!;
601
+ // biome-ignore lint/style/noNonNullAssertion: executeUpdate with skipPostHooks always returns cleanedBody/prevDoc.
602
+ const prevDoc = result.prevDoc!;
603
+ postHook = (): Promise<void> =>
604
+ runPostUpdate({cleanedBody, doc: result.doc, options: entry.options, prevDoc, request});
605
+ } catch (updateError: unknown) {
606
+ // M4 (lease takeover only): a conflict whose serverSeq is EXACTLY
607
+ // this mutation's own expected post-write seq COULD mean the write
608
+ // this very mutation intended already landed on a prior (crashed)
609
+ // attempt — but a seq match alone is ambiguous (any other write
610
+ // landing between the claim and the retry would also bump the seq
611
+ // by exactly one). Additionally require the current doc's fields to
612
+ // already contain every value this mutation's own `data` would have
613
+ // written — only THEN is it safe to treat as already-applied and
614
+ // report success; otherwise it is a genuine external conflict and
615
+ // must nack as usual, exactly like a normal (non-takeover) apply.
616
+ if (
617
+ isLeaseTakeover &&
618
+ isExecutorConflictError(updateError) &&
619
+ updateError.conflictType === "seq" &&
620
+ updateError.serverSeq === (mutation.baseVersion ?? 0) + 1 &&
621
+ docMatchesMutationData(updateError.doc, mutation.data)
622
+ ) {
623
+ const {resultId, resultSeq} = await finalizeAlreadyApplied({
624
+ claimedId: claimed._id,
625
+ doc: updateError.doc as mongoose.Document,
626
+ mutation,
627
+ });
628
+ return {ack: {id: resultId, mutationId, seq: resultSeq}, type: "ack"};
629
+ }
630
+ throw updateError;
631
+ }
632
+ } else {
633
+ const result = await executeDelete({
634
+ id: mutation.id as string,
635
+ model,
636
+ options: entry.options,
637
+ req: request,
638
+ skipPostHooks: true,
639
+ user,
640
+ });
641
+ doc = result.doc;
642
+ postHook = (): Promise<void> =>
643
+ runPostDelete({doc: result.doc, options: entry.options, request});
644
+ }
645
+
646
+ const resultId = String(doc._id);
647
+ const resultSeq = (doc as unknown as {_syncSeq?: number})._syncSeq ?? 0;
648
+ // M5: finalize the ledger BEFORE the post-hook runs — a post-hook throw
649
+ // must never make a committed write look like a failure.
650
+ await SyncMutation.updateOne(
651
+ {_id: claimed._id},
652
+ {$set: {resultId, resultSeq, status: "applied"}}
653
+ );
654
+ syncDebugLog.debug("[sync] Mutation applied", {
655
+ collection: mutation.collection,
656
+ mutationId,
657
+ seq: resultSeq,
658
+ });
659
+
660
+ let warning: string | undefined;
661
+ try {
662
+ await postHook();
663
+ } catch (postHookError: unknown) {
664
+ warning = errorMessageOf(postHookError);
665
+ logger.error("[sync] Post-hook failed after a committed mutation", {
666
+ collection: mutation.collection,
667
+ error: warning,
668
+ mutationId,
669
+ });
670
+ }
671
+ return {
672
+ ack: {id: resultId, mutationId, seq: resultSeq, ...(warning ? {warning} : {})},
673
+ type: "ack",
674
+ };
675
+ } catch (error: unknown) {
676
+ return finalizeNack({claimedId: claimed._id, entry, error, mutation, request});
677
+ }
678
+ };
679
+
680
+ const errorMessageOf = (error: unknown): string =>
681
+ isAPIError(error) ? error.title : error instanceof Error ? error.message : String(error);
682
+
683
+ /**
684
+ * Apply a client mutation through the transport-agnostic executors (permissions,
685
+ * pre/post hooks, validation) with an atomic idempotency claim. Always finalizes the
686
+ * claimed ledger row before returning so duplicate deliveries can read the outcome back.
687
+ */
688
+ export const applySyncMutation = async ({
689
+ user,
690
+ mutation,
691
+ req,
692
+ scopeResolver,
693
+ }: {
694
+ user: User;
695
+ mutation: SyncMutateRequest;
696
+ /** The real Express request when called over HTTP; hooks receive a `{user}` stub otherwise. */
697
+ req?: express.Request;
698
+ scopeResolver?: SyncMutationScopeResolver;
699
+ }): Promise<SyncMutationOutcome> => {
700
+ const mutationId = typeof mutation?.mutationId === "string" ? mutation.mutationId : "";
701
+ const validationNack = (message: string): SyncMutationOutcome =>
702
+ makeNack({code: "validation", message, mutationId});
703
+
704
+ if (!mutationId) {
705
+ return validationNack("mutationId is required");
706
+ }
707
+ if (!mutation.collection || typeof mutation.collection !== "string") {
708
+ return validationNack("collection is required");
709
+ }
710
+ if (!VALID_OPERATIONS.has(mutation.operation)) {
711
+ return validationNack(`Unknown operation: ${String(mutation.operation)}`);
712
+ }
713
+ if ((mutation.operation === "update" || mutation.operation === "delete") && !mutation.id) {
714
+ return validationNack(`id is required for ${mutation.operation} mutations`);
715
+ }
716
+ // C8: an update MUST carry an explicit baseVersion — omitting it would silently become
717
+ // a `baseSeq: 0` check (an accidental conflict against every non-fresh doc, or an
718
+ // accidental success against a seq-0 doc). Reject it as a client bug up front.
719
+ if (mutation.operation === "update" && typeof mutation.baseVersion !== "number") {
720
+ return validationNack("baseVersion is required for update mutations");
721
+ }
722
+
723
+ const entry = findSyncEntryByCollectionTag(mutation.collection);
724
+ if (!entry) {
725
+ return validationNack(`Unknown sync collection: ${mutation.collection}`);
726
+ }
727
+
728
+ const request = req ?? ({user} as unknown as express.Request);
729
+
730
+ // Atomic claim: inserting the pending row first means exactly one delivery applies.
731
+ let claimed: SyncMutationDocument;
732
+ try {
733
+ claimed = await SyncMutation.create({
734
+ claimedAt: new Date(),
735
+ mutationId,
736
+ status: "pending",
737
+ userId: String(user.id),
738
+ });
739
+ } catch (error: unknown) {
740
+ if ((error as {code?: number}).code !== 11000) {
741
+ throw error;
742
+ }
743
+ return waitForRecordedOutcome({
744
+ entry,
745
+ mutationId,
746
+ onTakeover: (takenOver) =>
747
+ applyClaimedMutation({
748
+ claimed: takenOver,
749
+ entry,
750
+ isLeaseTakeover: true,
751
+ mutation,
752
+ request,
753
+ scopeResolver,
754
+ user,
755
+ }),
756
+ request,
757
+ user,
758
+ });
759
+ }
760
+
761
+ return applyClaimedMutation({claimed, entry, mutation, request, scopeResolver, user});
762
+ };
763
+
764
+ /** Outcome of a batch validation pre-check (before any mutation is attempted). */
765
+ export type SyncBatchValidationOutcome =
766
+ | {ok: true}
767
+ | {ok: false; response: SyncMutateBatchResponse};
768
+
769
+ /**
770
+ * Up-front validation shared by both batch transports (HTTP and socket): reject an
771
+ * oversized batch or one with intra-batch duplicate mutationIds before anything is
772
+ * applied. On failure, returns a single-element `results` array carrying a
773
+ * `validation` nack for the offending mutation (or an empty-batch guard) — mirroring
774
+ * the shape callers expect from `applySyncMutationBatch`, but produced without
775
+ * touching the idempotency ledger since nothing was attempted.
776
+ */
777
+ export const validateSyncMutationBatch = (
778
+ mutations: SyncMutateRequest[]
779
+ ): SyncBatchValidationOutcome => {
780
+ if (mutations.length > MAX_SYNC_MUTATIONS_PER_BATCH) {
781
+ return {
782
+ ok: false,
783
+ response: {
784
+ results: [
785
+ makeNack({
786
+ code: "validation",
787
+ message: `Batch of ${mutations.length} exceeds the maximum of ${MAX_SYNC_MUTATIONS_PER_BATCH} mutations`,
788
+ mutationId: "",
789
+ }) as {type: "nack"; nack: SyncNack},
790
+ ],
791
+ },
792
+ };
793
+ }
794
+ const seen = new Set<string>();
795
+ for (const mutation of mutations) {
796
+ const mutationId = typeof mutation?.mutationId === "string" ? mutation.mutationId : "";
797
+ if (mutationId && seen.has(mutationId)) {
798
+ return {
799
+ ok: false,
800
+ response: {
801
+ results: [
802
+ makeNack({
803
+ code: "validation",
804
+ message: `Duplicate mutationId within batch: ${mutationId}`,
805
+ mutationId,
806
+ }) as {type: "nack"; nack: SyncNack},
807
+ ],
808
+ },
809
+ };
810
+ }
811
+ seen.add(mutationId);
812
+ }
813
+ return {ok: true};
814
+ };
815
+
816
+ /**
817
+ * Apply a batch of mutations strictly serially, in array order, reusing
818
+ * `applySyncMutation` per item — full reuse of the idempotency ledger, executors,
819
+ * permissions, and delta emission. Stops immediately at the first non-ack outcome
820
+ * (the user's hard requirement, INV-1): mutations after it are neither attempted nor
821
+ * ledgered, and are safe for the client to resend later (INV-3).
822
+ *
823
+ * Callers MUST run {@link validateSyncMutationBatch} first (oversized/duplicate
824
+ * rejection happens before any mutation is attempted); this function assumes the
825
+ * batch already passed that check.
826
+ */
827
+ export const applySyncMutationBatch = async ({
828
+ user,
829
+ mutations,
830
+ req,
831
+ scopeResolver,
832
+ }: {
833
+ user: User;
834
+ mutations: SyncMutateRequest[];
835
+ /** The real Express request when called over HTTP; hooks receive a `{user}` stub otherwise. */
836
+ req?: express.Request;
837
+ scopeResolver?: SyncMutationScopeResolver;
838
+ }): Promise<SyncMutateBatchResponse> => {
839
+ const results: SyncMutateBatchResponse["results"] = [];
840
+ for (const mutation of mutations) {
841
+ const outcome = await applySyncMutation({mutation, req, scopeResolver, user});
842
+ results.push(outcome);
843
+ if (outcome.type === "nack") {
844
+ // Stop-on-error: the client re-sends everything after this point, and
845
+ // INV-3's idempotency ledger makes that overlap safe.
846
+ break;
847
+ }
848
+ }
849
+ return {results};
850
+ };