@terreno/api 56.0.0-beta.0 → 57.0.0-beta.1

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 (64) hide show
  1. package/CHANGELOG.md +2 -122
  2. package/LICENSE +21 -202
  3. package/dist/api.d.ts +3 -2
  4. package/dist/auth.js +21 -25
  5. package/dist/betterAuthSetup.d.ts +15 -1
  6. package/dist/betterAuthSetup.js +4 -6
  7. package/dist/configurationPlugin.js +2 -2
  8. package/dist/expressServer.js +11 -5
  9. package/dist/githubAuth.js +1 -4
  10. package/dist/plugins.d.ts +7 -6
  11. package/dist/plugins.js +24 -8
  12. package/dist/realtime/changeStreamWatcher.d.ts +1 -1
  13. package/dist/realtime/changeStreamWatcher.js +0 -2
  14. package/dist/realtime/realtimeApp.d.ts +1 -1
  15. package/dist/realtime/realtimeApp.js +16 -8
  16. package/dist/realtime/types.d.ts +14 -0
  17. package/dist/sync/executors.js +14 -14
  18. package/dist/sync/models.js +1 -1
  19. package/dist/sync/registry.d.ts +4 -4
  20. package/dist/sync/registry.js +1 -1
  21. package/dist/sync/socketHandlers.d.ts +1 -1
  22. package/dist/sync/syncSeqPlugin.js +25 -29
  23. package/dist/tests/models.d.ts +27 -11
  24. package/dist/tests/models.js +5 -3
  25. package/dist/tests/testHelper.d.ts +9 -3
  26. package/package.json +5 -6
  27. package/src/actions.test.ts +19 -12
  28. package/src/actions.ts +2 -2
  29. package/src/api.coverage.test.ts +7 -9
  30. package/src/api.errorPaths.test.ts +47 -1
  31. package/src/api.errors.test.ts +32 -23
  32. package/src/api.ts +22 -12
  33. package/src/auth.test.ts +251 -1
  34. package/src/auth.ts +25 -23
  35. package/src/betterAuthSetup.ts +7 -7
  36. package/src/configuration.test.ts +59 -38
  37. package/src/configurationPlugin.test.ts +72 -42
  38. package/src/configurationPlugin.ts +2 -2
  39. package/src/consentApp.test.ts +12 -12
  40. package/src/expressServer.ts +11 -5
  41. package/src/githubAuth.ts +1 -3
  42. package/src/middleware.test.ts +16 -0
  43. package/src/models/versionConfig.ts +1 -1
  44. package/src/openApiBuilder.test.ts +24 -9
  45. package/src/openApiValidator.test.ts +41 -0
  46. package/src/permissions.middleware.test.ts +73 -81
  47. package/src/permissions.test.ts +35 -25
  48. package/src/plugins.test.ts +74 -29
  49. package/src/plugins.ts +29 -11
  50. package/src/populate.test.ts +25 -16
  51. package/src/realtime/changeStreamWatcher.ts +1 -4
  52. package/src/realtime/realtime.test.ts +239 -0
  53. package/src/realtime/realtimeApp.ts +15 -8
  54. package/src/realtime/realtimeAppSetup.test.ts +159 -0
  55. package/src/realtime/types.ts +14 -0
  56. package/src/secretProvidersGcpClient.test.ts +66 -0
  57. package/src/sync/executors.ts +16 -14
  58. package/src/sync/models.ts +2 -1
  59. package/src/sync/registry.ts +6 -8
  60. package/src/sync/socketHandlers.ts +1 -3
  61. package/src/sync/syncFrontier.test.ts +2 -2
  62. package/src/sync/syncSeqPlugin.test.ts +446 -0
  63. package/src/sync/syncSeqPlugin.ts +43 -51
  64. package/src/tests/models.ts +8 -6
@@ -1,5 +1,3 @@
1
- // noExplicitAny: model router options are generic across all models
2
- // biome-ignore-all lint/suspicious/noExplicitAny: model router options are generic across all models
3
1
  import type {Model} from "mongoose";
4
2
  import type {ModelRouterOptions} from "../api";
5
3
  import {logger} from "../logger";
@@ -21,7 +19,7 @@ export interface SyncRegistryEntry {
21
19
  /** Sync configuration from modelRouter options */
22
20
  config: SyncConfig;
23
21
  /** Full modelRouter options (for responseHandler, permissions, etc.) */
24
- options: ModelRouterOptions<any>;
22
+ options: ModelRouterOptions<unknown>;
25
23
  }
26
24
 
27
25
  const syncRegistry: SyncRegistryEntry[] = [];
@@ -57,20 +55,20 @@ export const trackSyncIndexCreation = (promise: Promise<void>): void => {
57
55
  * - `syncPlugin` is required so every write stamps a per-stream `_syncSeq`;
58
56
  * - owner/tenant scope fields must exist on the schema.
59
57
  */
60
- export const registerSync = ({
58
+ export const registerSync = <T>({
61
59
  model,
62
60
  routePath,
63
61
  config,
64
62
  options,
65
63
  }: {
66
- model: Model<any>;
64
+ model: Model<T>;
67
65
  routePath: string;
68
66
  config: SyncConfig;
69
- options: ModelRouterOptions<any>;
67
+ options: ModelRouterOptions<T>;
70
68
  }): void => {
71
69
  const name = model.modelName;
72
70
  const deletedPath = model.schema.path("deleted");
73
- if (!deletedPath || deletedPath.instance !== "Boolean") {
71
+ if (deletedPath?.instance !== "Boolean") {
74
72
  throw new Error(
75
73
  `Model ${name} has a sync config but no soft delete support. ` +
76
74
  "Apply isDeletedPlugin to the schema — sync catch-up requires delete tombstones."
@@ -112,7 +110,7 @@ export const registerSync = ({
112
110
  collectionTag,
113
111
  config,
114
112
  modelName: name,
115
- options,
113
+ options: options as unknown as ModelRouterOptions<unknown>,
116
114
  routePath,
117
115
  });
118
116
 
@@ -1,5 +1,3 @@
1
- // noExplicitAny: Socket.io handler signatures require dynamic args
2
- // biome-ignore-all lint/suspicious/noExplicitAny: Socket.io handler signatures require dynamic args
3
1
  import type {Server} from "socket.io";
4
2
 
5
3
  import type {User} from "../auth";
@@ -61,7 +59,7 @@ export interface SyncSocketLike extends SocketWithDecodedToken {
61
59
  join: (room: string) => Promise<void> | void;
62
60
  leave: (room: string) => Promise<void> | void;
63
61
  emit: (event: string, payload: unknown) => void;
64
- on: (event: string, handler: (...args: any[]) => any) => void;
62
+ on: (event: string, handler: (...args: never[]) => void | Promise<void>) => void;
65
63
  }
66
64
 
67
65
  /**
@@ -52,11 +52,11 @@ let insertManyProbe: (() => Promise<void>) | null = null;
52
52
 
53
53
  // Registered AFTER syncPlugin so it runs once the batch's seqs are claimed but before
54
54
  // the documents commit — the exact window a snapshot must not page across (C1).
55
- frontierSchema.pre("insertMany", async (next: any) => {
55
+ // Mongoose 9: pre hooks no longer receive `next` — use async/await only.
56
+ frontierSchema.pre("insertMany", async () => {
56
57
  if (insertManyProbe) {
57
58
  await insertManyProbe();
58
59
  }
59
- next();
60
60
  });
61
61
 
62
62
  // Registered AFTER syncPlugin so a save can fail once the seq (and, before the fix, the
@@ -0,0 +1,446 @@
1
+ import {beforeAll, beforeEach, describe, expect, it} from "bun:test";
2
+ import {type Model, model, Schema} from "mongoose";
3
+ import type {ModelRouterOptions} from "../api";
4
+ import {createdUpdatedPlugin, type IsDeleted, isDeletedPlugin} from "../plugins";
5
+ import {setupDb} from "../tests";
6
+ import {SyncCounter, SyncScopeMove} from "./models";
7
+ import {clearSyncRegistry, registerSync} from "./registry";
8
+ import {syncPlugin} from "./syncSeqPlugin";
9
+ import type {SyncConfig} from "./types";
10
+
11
+ /**
12
+ * Failure-path coverage for the `_syncSeq` plugin: the guards and recovery branches that
13
+ * the happy-path suites (sync.test, syncFrontier.test, syncPhaseC.test) never reach —
14
+ * schema contract violations, unregistered models, `$eq`/`$in` `_id` filters, confirm and
15
+ * release failures, reaped-claim re-stamping, and the non-tenant scope kinds
16
+ * (custom resolver / broadcast) on the query-write path.
17
+ */
18
+
19
+ interface SeqTenantThing extends IsDeleted {
20
+ _id: string;
21
+ name: string;
22
+ orgId?: string;
23
+ _syncSeq?: number;
24
+ _syncPrevStream?: string | null;
25
+ }
26
+
27
+ interface SeqCustomThing extends IsDeleted {
28
+ _id: string;
29
+ name: string;
30
+ workspaceId: string;
31
+ _syncSeq?: number;
32
+ }
33
+
34
+ interface SeqBroadcastThing extends IsDeleted {
35
+ _id: string;
36
+ name: string;
37
+ _syncSeq?: number;
38
+ _syncPrevStream?: string | null;
39
+ }
40
+
41
+ const tenantSchema = new Schema<SeqTenantThing>({
42
+ name: {description: "The name of the thing", required: true, type: String},
43
+ orgId: {description: "The organization this thing belongs to", type: String},
44
+ });
45
+ tenantSchema.plugin(isDeletedPlugin);
46
+ tenantSchema.plugin(createdUpdatedPlugin);
47
+ tenantSchema.plugin(syncPlugin);
48
+ // Registered AFTER syncPlugin so the save fails once its seq is claimed and registered —
49
+ // the window the error middleware releases the claim in.
50
+ tenantSchema.pre("save", function () {
51
+ if (this.name === "kaboom") {
52
+ throw new Error("simulated post-claim save failure");
53
+ }
54
+ });
55
+ const TenantModel = model<SeqTenantThing>("SeqPluginTenantThing", tenantSchema);
56
+
57
+ const customSchema = new Schema<SeqCustomThing>({
58
+ name: {description: "The name of the thing", required: true, type: String},
59
+ workspaceId: {description: "The workspace this thing belongs to", required: true, type: String},
60
+ });
61
+ customSchema.plugin(isDeletedPlugin);
62
+ customSchema.plugin(createdUpdatedPlugin);
63
+ customSchema.plugin(syncPlugin);
64
+ const CustomModel = model<SeqCustomThing>("SeqPluginCustomThing", customSchema);
65
+
66
+ const broadcastSchema = new Schema<SeqBroadcastThing>({
67
+ name: {description: "The name of the thing", required: true, type: String},
68
+ });
69
+ broadcastSchema.plugin(isDeletedPlugin);
70
+ broadcastSchema.plugin(createdUpdatedPlugin);
71
+ broadcastSchema.plugin(syncPlugin);
72
+ const BroadcastModel = model<SeqBroadcastThing>("SeqPluginBroadcastThing", broadcastSchema);
73
+
74
+ /** Carries syncPlugin but is never registered: every hook must no-op on it. */
75
+ const unregisteredSchema = new Schema<SeqBroadcastThing>({
76
+ name: {description: "The name of the thing", required: true, type: String},
77
+ });
78
+ unregisteredSchema.plugin(isDeletedPlugin);
79
+ unregisteredSchema.plugin(createdUpdatedPlugin);
80
+ unregisteredSchema.plugin(syncPlugin);
81
+ const UnregisteredModel = model<SeqBroadcastThing>(
82
+ "SeqPluginUnregisteredThing",
83
+ unregisteredSchema
84
+ );
85
+
86
+ const stubOptions = {
87
+ permissions: {create: [], delete: [], list: [], read: [], update: []},
88
+ } as unknown as ModelRouterOptions<SeqTenantThing>;
89
+
90
+ const TENANT_TAG = "seqPluginTenantThings";
91
+ const CUSTOM_TAG = "seqPluginCustomThings";
92
+ const BROADCAST_TAG = "seqPluginBroadcastThings";
93
+
94
+ type LooseUpdateOne = (
95
+ filter: Record<string, unknown>,
96
+ update: Record<string, unknown>,
97
+ options?: Record<string, unknown>
98
+ ) => Promise<{modifiedCount?: number}>;
99
+
100
+ type LooseFindOneAndUpdate = (
101
+ filter: Record<string, unknown>,
102
+ update: unknown,
103
+ options?: Record<string, unknown>
104
+ ) => Promise<unknown>;
105
+
106
+ /**
107
+ * Make the pending-claim `$pull` that `confirmSyncSeqs`/`releaseSyncSeqs` issue either
108
+ * throw or report "nothing cleared" (the reaped-lease signature), optionally only for one
109
+ * stream. Returns the restore function.
110
+ */
111
+ const stubPendingPull = ({
112
+ behavior,
113
+ stream,
114
+ }: {
115
+ behavior: "throw" | "reaped";
116
+ stream?: string;
117
+ }): (() => void) => {
118
+ const original = SyncCounter.updateOne.bind(SyncCounter) as unknown as LooseUpdateOne;
119
+ const stub = (async (
120
+ filter: Record<string, unknown>,
121
+ update: Record<string, unknown>,
122
+ options?: Record<string, unknown>
123
+ ) => {
124
+ const isPull = Boolean(update) && Object.hasOwn(update, "$pull");
125
+ if (isPull && (!stream || filter.stream === stream)) {
126
+ if (behavior === "throw") {
127
+ throw new Error("simulated pending-claim $pull failure");
128
+ }
129
+ const result = await original(filter, update, options);
130
+ return {...result, modifiedCount: 0};
131
+ }
132
+ return original(filter, update, options);
133
+ }) as unknown as typeof SyncCounter.updateOne;
134
+ Object.assign(SyncCounter, {updateOne: stub});
135
+ return () => {
136
+ Object.assign(SyncCounter, {updateOne: original});
137
+ };
138
+ };
139
+
140
+ /** Make a seq claim fail, optionally only for one stream. Returns the restore function. */
141
+ const stubClaimFailure = ({stream}: {stream?: string}): (() => void) => {
142
+ const original = SyncCounter.findOneAndUpdate.bind(
143
+ SyncCounter
144
+ ) as unknown as LooseFindOneAndUpdate;
145
+ const stub = (async (
146
+ filter: Record<string, unknown>,
147
+ update: unknown,
148
+ options?: Record<string, unknown>
149
+ ) => {
150
+ if (!stream || filter.stream === stream) {
151
+ throw new Error("simulated claim failure");
152
+ }
153
+ return original(filter, update, options);
154
+ }) as unknown as typeof SyncCounter.findOneAndUpdate;
155
+ Object.assign(SyncCounter, {findOneAndUpdate: stub});
156
+ return () => {
157
+ Object.assign(SyncCounter, {findOneAndUpdate: original});
158
+ };
159
+ };
160
+
161
+ /**
162
+ * Replace the raw-collection `updateOne` the reaped-claim re-stamp uses, so it can be made
163
+ * to match nothing or throw. Returns the restore function.
164
+ */
165
+ const stubRawUpdateOne = <T>({
166
+ behavior,
167
+ model: target,
168
+ }: {
169
+ behavior: "noMatch" | "throw";
170
+ model: Model<T>;
171
+ }): (() => void) => {
172
+ const collection = target.collection;
173
+ const original = collection.updateOne.bind(collection) as unknown as LooseUpdateOne;
174
+ // Only the re-stamp writes `{$set: {_syncSeq}}` and nothing else; Mongoose's own
175
+ // `doc.save()` goes through the same collection method and must still land.
176
+ const isRestamp = (update: Record<string, unknown>): boolean => {
177
+ const set = update.$set;
178
+ if (Object.keys(update).length !== 1 || typeof set !== "object" || set === null) {
179
+ return false;
180
+ }
181
+ const keys = Object.keys(set);
182
+ return keys.length === 1 && keys[0] === "_syncSeq";
183
+ };
184
+ const stub = (async (
185
+ filter: Record<string, unknown>,
186
+ update: Record<string, unknown>,
187
+ options?: Record<string, unknown>
188
+ ) => {
189
+ if (!isRestamp(update)) {
190
+ return original(filter, update, options);
191
+ }
192
+ if (behavior === "throw") {
193
+ throw new Error("simulated re-stamp failure");
194
+ }
195
+ return {matchedCount: 0, modifiedCount: 0};
196
+ }) as unknown as typeof collection.updateOne;
197
+ Object.assign(collection, {updateOne: stub});
198
+ return () => {
199
+ Object.assign(collection, {updateOne: original});
200
+ };
201
+ };
202
+
203
+ describe("syncPlugin schema contract", () => {
204
+ it("throws when the schema disabled its versionKey", () => {
205
+ const schema = new Schema(
206
+ {name: {description: "The name of the thing", type: String}},
207
+ {versionKey: false}
208
+ );
209
+ expect(() => schema.plugin(syncPlugin)).toThrow(/requires a versionKey/);
210
+ });
211
+ });
212
+
213
+ describe("syncPlugin on an unregistered model", () => {
214
+ beforeAll(async () => {
215
+ await setupDb();
216
+ clearSyncRegistry();
217
+ });
218
+
219
+ beforeEach(async () => {
220
+ await UnregisteredModel.collection.deleteMany({});
221
+ });
222
+
223
+ it("stamps nothing and blocks nothing: save, hydration, query-write and insertMany all no-op", async () => {
224
+ const doc = await UnregisteredModel.create({name: "unstamped"});
225
+ expect(doc._syncSeq).toBeUndefined();
226
+ // post("init") must bail out without resolving a stream for an unregistered model.
227
+ const hydrated = await UnregisteredModel.findById(doc._id);
228
+ expect(hydrated?._syncSeq).toBeUndefined();
229
+ // A non-_id query-write is only rejected for registered models.
230
+ await UnregisteredModel.updateOne({name: "unstamped"}, {$set: {name: "renamed"}});
231
+ expect((await UnregisteredModel.findById(doc._id))?.name).toBe("renamed");
232
+ const inserted = await UnregisteredModel.insertMany([{name: "a"}, {name: "b"}]);
233
+ expect(inserted).toHaveLength(2);
234
+ expect(inserted.every((entry) => entry._syncSeq === undefined)).toBe(true);
235
+ });
236
+ });
237
+
238
+ describe("syncPlugin write-path failure and recovery branches", () => {
239
+ beforeAll(async () => {
240
+ await setupDb();
241
+ await SyncCounter.ensureIndexes();
242
+ clearSyncRegistry();
243
+ registerSync({
244
+ config: {scope: {field: "orgId", type: "tenant"}} as SyncConfig,
245
+ model: TenantModel,
246
+ options: stubOptions,
247
+ routePath: `/${TENANT_TAG}`,
248
+ });
249
+ registerSync({
250
+ config: {
251
+ scope: (doc: Record<string, unknown>) => String(doc.workspaceId),
252
+ snapshotFilter: () => ({}),
253
+ } as SyncConfig,
254
+ model: CustomModel,
255
+ options: stubOptions,
256
+ routePath: `/${CUSTOM_TAG}`,
257
+ });
258
+ registerSync({
259
+ config: {scope: {type: "broadcast"}} as SyncConfig,
260
+ model: BroadcastModel,
261
+ options: stubOptions,
262
+ routePath: `/${BROADCAST_TAG}`,
263
+ });
264
+ });
265
+
266
+ beforeEach(async () => {
267
+ // deleteMany is blocked on synced models; clear via the native collections.
268
+ await TenantModel.collection.deleteMany({});
269
+ await CustomModel.collection.deleteMany({});
270
+ await BroadcastModel.collection.deleteMany({});
271
+ await SyncCounter.deleteMany({});
272
+ await SyncScopeMove.deleteMany({});
273
+ });
274
+
275
+ // ── m9: single-`_id` filter shapes ────────────────────────────────────────
276
+ it("accepts an `_id: {$eq}` filter and rejects `_id: {$in}` and a null `_id`", async () => {
277
+ const doc = await TenantModel.create({name: "n", orgId: "org1"});
278
+ const createSeq = doc._syncSeq as number;
279
+ await TenantModel.updateOne({_id: {$eq: doc._id}}, {$set: {name: "eq-renamed"}});
280
+ const reloaded = await TenantModel.findById(doc._id);
281
+ expect(reloaded?.name).toBe("eq-renamed");
282
+ expect(reloaded?._syncSeq).toBe(createSeq + 1);
283
+
284
+ await expect(
285
+ TenantModel.updateOne({_id: {$in: [doc._id]}}, {$set: {name: "x"}}).exec()
286
+ ).rejects.toThrow(/must target a single document by _id/);
287
+ await expect(TenantModel.updateOne({_id: null}, {$set: {name: "x"}}).exec()).rejects.toThrow(
288
+ /must target a single document by _id/
289
+ );
290
+ });
291
+
292
+ // ── C1: confirm failures never fail the user's write ──────────────────────
293
+ it("a confirm failure after save is logged, not surfaced", async () => {
294
+ const doc = await TenantModel.create({name: "n", orgId: "org1"});
295
+ const restore = stubPendingPull({behavior: "throw"});
296
+ try {
297
+ doc.name = "renamed";
298
+ await doc.save();
299
+ } finally {
300
+ restore();
301
+ }
302
+ expect((await TenantModel.findById(doc._id))?.name).toBe("renamed");
303
+ });
304
+
305
+ it("a confirm failure after a query write is logged, not surfaced", async () => {
306
+ const doc = await TenantModel.create({name: "n", orgId: "org1"});
307
+ const restore = stubPendingPull({behavior: "throw"});
308
+ try {
309
+ await TenantModel.updateOne({_id: doc._id}, {$set: {name: "renamed"}});
310
+ } finally {
311
+ restore();
312
+ }
313
+ expect((await TenantModel.findById(doc._id))?.name).toBe("renamed");
314
+ });
315
+
316
+ it("a confirm failure after insertMany is logged, not surfaced", async () => {
317
+ const restore = stubPendingPull({behavior: "throw"});
318
+ try {
319
+ await TenantModel.insertMany([
320
+ {name: "im-1", orgId: "org1"},
321
+ {name: "im-2", orgId: "org1"},
322
+ ]);
323
+ } finally {
324
+ restore();
325
+ }
326
+ const docs = await TenantModel.find({orgId: "org1"});
327
+ expect(docs).toHaveLength(2);
328
+ expect(docs.every((entry) => typeof entry._syncSeq === "number")).toBe(true);
329
+ });
330
+
331
+ it("insertMany of an empty batch claims nothing", async () => {
332
+ await TenantModel.insertMany([]);
333
+ expect(await SyncCounter.countDocuments({})).toBe(0);
334
+ });
335
+
336
+ // ── Task 9.13: a failed save releases its claim ───────────────────────────
337
+ it("a release failure after a failed save is logged, not surfaced", async () => {
338
+ const restore = stubPendingPull({behavior: "throw"});
339
+ try {
340
+ await expect(TenantModel.create({name: "kaboom", orgId: "org1"})).rejects.toThrow(
341
+ /simulated post-claim save failure/
342
+ );
343
+ } finally {
344
+ restore();
345
+ }
346
+ expect(await TenantModel.collection.countDocuments({})).toBe(0);
347
+ });
348
+
349
+ // ── Task 9.17: reaped-claim re-stamping ───────────────────────────────────
350
+ it("a re-stamp that matches no document releases its claim and leaves the doc below the frontier", async () => {
351
+ const doc = await TenantModel.create({name: "n", orgId: "org1"});
352
+ const claimedSeq = doc._syncSeq as number;
353
+ const restorePull = stubPendingPull({behavior: "reaped"});
354
+ const restoreRaw = stubRawUpdateOne({behavior: "noMatch", model: TenantModel});
355
+ try {
356
+ doc.name = "renamed";
357
+ await doc.save();
358
+ } finally {
359
+ restoreRaw();
360
+ restorePull();
361
+ }
362
+ // The re-stamp never landed, so the in-memory doc keeps the seq its own save stamped.
363
+ expect(doc._syncSeq).toBe(claimedSeq + 1);
364
+ });
365
+
366
+ it("a re-stamp whose own confirm is reaped keeps the new seq on the document", async () => {
367
+ const doc = await TenantModel.create({name: "n", orgId: "org1"});
368
+ const savedSeq = doc._syncSeq as number;
369
+ const restore = stubPendingPull({behavior: "reaped"});
370
+ try {
371
+ doc.name = "renamed";
372
+ await doc.save();
373
+ } finally {
374
+ restore();
375
+ }
376
+ const reStamped = doc._syncSeq as number;
377
+ expect(reStamped).toBeGreaterThan(savedSeq + 1);
378
+ expect((await TenantModel.findById(doc._id))?._syncSeq).toBe(reStamped);
379
+ });
380
+
381
+ it("a re-stamp that throws leaves the document's own seq in place", async () => {
382
+ const doc = await TenantModel.create({name: "n", orgId: "org1"});
383
+ const claimedSeq = doc._syncSeq as number;
384
+ const restorePull = stubPendingPull({behavior: "reaped"});
385
+ const restoreRaw = stubRawUpdateOne({behavior: "throw", model: TenantModel});
386
+ try {
387
+ doc.name = "renamed";
388
+ await doc.save();
389
+ } finally {
390
+ restoreRaw();
391
+ restorePull();
392
+ }
393
+ expect(doc._syncSeq).toBe(claimedSeq + 1);
394
+ });
395
+
396
+ // ── C4: scope-move marker failures ────────────────────────────────────────
397
+ it("a scope-move marker whose seq claim fails writes no marker and never fails the move", async () => {
398
+ const doc = await TenantModel.create({name: "n", orgId: "org1"});
399
+ const restore = stubClaimFailure({stream: `${TENANT_TAG}|tenant:org1`});
400
+ try {
401
+ doc.orgId = "org2";
402
+ await doc.save();
403
+ } finally {
404
+ restore();
405
+ }
406
+ expect(await SyncScopeMove.countDocuments({entityId: String(doc._id)})).toBe(0);
407
+ expect((await TenantModel.findById(doc._id))?.orgId).toBe("org2");
408
+ });
409
+
410
+ it("a scope-move marker whose confirm fails still writes the marker", async () => {
411
+ const doc = await TenantModel.create({name: "n", orgId: "org1"});
412
+ const restore = stubPendingPull({behavior: "throw", stream: `${TENANT_TAG}|tenant:org1`});
413
+ try {
414
+ doc.orgId = "org2";
415
+ await doc.save();
416
+ } finally {
417
+ restore();
418
+ }
419
+ const markers = await SyncScopeMove.find({entityId: String(doc._id)});
420
+ expect(markers).toHaveLength(1);
421
+ expect(markers[0].fromStream).toBe(`${TENANT_TAG}|tenant:org1`);
422
+ });
423
+
424
+ // ── query-write scope resolution for non-tenant scope kinds ───────────────
425
+ it("a custom scope resolver resolves the query-write's stream from the merged document", async () => {
426
+ const doc = await CustomModel.create({name: "n", workspaceId: "w1"});
427
+ await CustomModel.updateOne({_id: doc._id}, {$set: {workspaceId: "w2"}});
428
+ const reloaded = await CustomModel.findById(doc._id);
429
+ expect(reloaded?._syncSeq).toBe(1);
430
+ const markers = await SyncScopeMove.find({entityId: String(doc._id)});
431
+ expect(markers).toHaveLength(1);
432
+ expect(markers[0].fromStream).toBe(`${CUSTOM_TAG}|custom:w1`);
433
+ expect(markers[0].toStream).toBe(`${CUSTOM_TAG}|custom:w2`);
434
+ });
435
+
436
+ it("a broadcast scope stamps the single all-stream and never reports a move", async () => {
437
+ const doc = await BroadcastModel.create({name: "n"});
438
+ await BroadcastModel.updateOne({_id: doc._id}, {$set: {name: "renamed"}});
439
+ const reloaded = await BroadcastModel.findById(doc._id);
440
+ expect(reloaded?._syncSeq).toBe((doc._syncSeq as number) + 1);
441
+ expect(reloaded?._syncPrevStream ?? null).toBeNull();
442
+ expect(await SyncScopeMove.countDocuments({})).toBe(0);
443
+ const counter = await SyncCounter.findOne({stream: `${BROADCAST_TAG}|all`});
444
+ expect(counter?.seq).toBe(2);
445
+ });
446
+ });
@@ -1,14 +1,7 @@
1
1
  // noExplicitAny: Schema/Query generics must be loose to accept arbitrary consumer schemas
2
2
  // biome-ignore-all lint/suspicious/noExplicitAny: Schema/Query generics must be loose to accept arbitrary consumer schemas
3
- import type {
4
- CallbackWithoutResultAndOptionalError,
5
- ClientSession,
6
- Model,
7
- Query,
8
- Schema,
9
- } from "mongoose";
3
+ import type {ClientSession, Model, Query, Schema} from "mongoose";
10
4
  import {logger} from "../logger";
11
- import {isVersionError} from "./executors";
12
5
  import {claimSyncSeqs, confirmSyncSeqs, releaseSyncSeqs, SyncScopeMove} from "./models";
13
6
  import {findSyncEntryByModelName, type SyncRegistryEntry} from "./registry";
14
7
  import {
@@ -442,70 +435,69 @@ export const syncPlugin = (schema: Schema<any, any, any, any>): void => {
442
435
  this.$locals[INITIAL_STREAM_KEY] = pending.currentStream;
443
436
  });
444
437
 
445
- // Task 9.13: an optimistic-concurrency loss (`VersionError`) matched no document, so the
446
- // seq claimed in pre('save') will never be stamped on anything. Cancel it instead of
447
- // letting it hold the stable frontier down for the full pending-claim lease — a lost
448
- // update race is now an EXPECTED outcome, not a crash, and must not stall catch-up for
449
- // every other client on the stream.
438
+ // Any save that claimed a seq in pre('save') but then failed (VersionError, E11000,
439
+ // simulated/hook failure, etc.) never stamped that seq. Release it so the stable
440
+ // frontier is not held for the full pending-claim lease.
441
+ //
442
+ // Mongoose 9 / Kareem 3: async error middleware must `throw error` (or return a
443
+ // rejected promise). Calling `next(error)` after an async hook returns a Promise
444
+ // leaves an orphaned rejection that Bun reports as an unhandled error between tests,
445
+ // even when the caller correctly awaited `save().catch(...)`.
446
+ // Keep arity ≥ 3 so Kareem still classifies this as error middleware.
450
447
  schema.post(
451
448
  "save",
452
- async function (error: any, doc: any, next: (err?: Error) => void): Promise<void> {
449
+ async function (error: any, doc: any, _next: (err?: Error) => void): Promise<void> {
453
450
  const locals = (this?.$locals ?? doc?.$locals) as Record<string, unknown> | undefined;
454
451
  const pending = locals?.[PENDING_COMMIT_KEY] as PendingSaveCommit | undefined;
455
452
  if (locals) {
456
453
  locals[PENDING_COMMIT_KEY] = undefined;
457
454
  }
458
- if (pending?.claim.registered && isVersionError(error)) {
455
+ if (pending?.claim.registered) {
459
456
  await releaseSyncSeqs({seqs: pending.claim.seqs, stream: pending.currentStream}).catch(
460
457
  (releaseError: unknown) => {
461
- logger.error("[sync] Failed to release the seq claim of a version-conflicted save", {
458
+ logger.error("[sync] Failed to release seq claim after failed save", {
462
459
  error: String(releaseError),
463
460
  stream: pending.currentStream,
464
461
  });
465
462
  }
466
463
  );
467
464
  }
468
- next(error);
465
+ throw error;
469
466
  }
470
467
  );
471
468
 
469
+ // Mongoose 9 insertMany pre hooks are async (no `next` callback) and receive docs + options.
472
470
  schema.pre(
473
471
  "insertMany",
474
- async function (
475
- next: CallbackWithoutResultAndOptionalError,
476
- docs: Record<string, unknown>[],
477
- options?: {session?: ClientSession | null}
478
- ) {
479
- try {
480
- const model = this as unknown as Model<any>;
481
- const entry = findSyncEntryByModelName(model.modelName);
482
- if (!entry || !Array.isArray(docs) || docs.length === 0) {
483
- return next();
484
- }
485
- const session = options?.session ?? null;
486
- const byStream = new Map<string, Record<string, unknown>[]>();
487
- for (const doc of docs) {
488
- const stream = writableStreamForObject(entry, doc);
489
- const group = byStream.get(stream) ?? [];
490
- group.push(doc);
491
- byStream.set(stream, group);
492
- }
493
- for (const [stream, group] of byStream) {
494
- // The claim joins the caller's session so a transactional insertMany gets true
495
- // counter+write atomicity (and registers no pending entry to confirm).
496
- const claim = await claimSyncSeqs({count: group.length, session, stream});
497
- group.forEach((doc, index) => {
498
- doc._syncPrevStream = null;
499
- doc._syncSeq = claim.seqs[index];
500
- });
501
- }
502
- // C1: the confirm belongs in post('insertMany') — confirming here would let the
503
- // stable frontier (and therefore a snapshot cursor) advance past seqs whose
504
- // documents have not committed yet, stranding them below every catch-up cursor.
505
- return next();
506
- } catch (error: unknown) {
507
- return next(error as Error);
472
+ async function (docs: any | Array<any>, options?: {session?: ClientSession | null}) {
473
+ const docsArray = Array.isArray(docs)
474
+ ? (docs as Record<string, unknown>[])
475
+ : [docs as Record<string, unknown>];
476
+ const model = this as unknown as Model<any>;
477
+ const entry = findSyncEntryByModelName(model.modelName);
478
+ if (!entry || docsArray.length === 0) {
479
+ return;
480
+ }
481
+ const session = options?.session ?? null;
482
+ const byStream = new Map<string, Record<string, unknown>[]>();
483
+ for (const doc of docsArray) {
484
+ const stream = writableStreamForObject(entry, doc);
485
+ const group = byStream.get(stream) ?? [];
486
+ group.push(doc);
487
+ byStream.set(stream, group);
488
+ }
489
+ for (const [stream, group] of byStream) {
490
+ // The claim joins the caller's session so a transactional insertMany gets true
491
+ // counter+write atomicity (and registers no pending entry to confirm).
492
+ const claim = await claimSyncSeqs({count: group.length, session, stream});
493
+ group.forEach((doc, index) => {
494
+ doc._syncPrevStream = null;
495
+ doc._syncSeq = claim.seqs[index];
496
+ });
508
497
  }
498
+ // C1: the confirm belongs in post('insertMany') — confirming here would let the
499
+ // stable frontier (and therefore a snapshot cursor) advance past seqs whose
500
+ // documents have not committed yet, stranding them below every catch-up cursor.
509
501
  }
510
502
  );
511
503