@terreno/api 0.31.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 (250) hide show
  1. package/CHANGELOG.md +122 -2
  2. package/LICENSE +202 -21
  3. package/dist/api.d.ts +12 -3
  4. package/dist/api.js +110 -361
  5. package/dist/auth.d.ts +26 -0
  6. package/dist/auth.js +100 -1
  7. package/dist/betterAuth.d.ts +5 -0
  8. package/dist/betterAuthSetup.d.ts +1 -15
  9. package/dist/betterAuthSetup.js +29 -8
  10. package/dist/configurationPlugin.js +2 -2
  11. package/dist/docLoader.js +12 -9
  12. package/dist/errors.d.ts +13 -0
  13. package/dist/errors.js +29 -1
  14. package/dist/expressServer.js +5 -11
  15. package/dist/githubAuth.js +4 -1
  16. package/dist/index.d.ts +17 -1
  17. package/dist/index.js +29 -1
  18. package/dist/middleware.d.ts +7 -0
  19. package/dist/middleware.js +16 -1
  20. package/dist/openApiCompat.d.ts +10 -1
  21. package/dist/openApiCompat.js +115 -47
  22. package/dist/permissions.d.ts +27 -0
  23. package/dist/permissions.js +42 -1
  24. package/dist/plugins.d.ts +15 -3
  25. package/dist/plugins.js +36 -6
  26. package/dist/realtime/changeStreamWatcher.d.ts +100 -3
  27. package/dist/realtime/changeStreamWatcher.js +542 -137
  28. package/dist/realtime/realtimeApp.d.ts +3 -1
  29. package/dist/realtime/realtimeApp.js +75 -27
  30. package/dist/realtime/sessionRevalidation.d.ts +90 -0
  31. package/dist/realtime/sessionRevalidation.js +438 -0
  32. package/dist/realtime/socketAuth.d.ts +97 -0
  33. package/dist/realtime/socketAuth.js +272 -0
  34. package/dist/realtime/socketUser.d.ts +54 -0
  35. package/dist/realtime/socketUser.js +75 -5
  36. package/dist/realtime/types.d.ts +40 -0
  37. package/dist/secretProviders.d.ts +23 -0
  38. package/dist/secretProviders.js +9 -3
  39. package/dist/sync/executors.d.ts +198 -0
  40. package/dist/sync/executors.js +670 -0
  41. package/dist/sync/loadHarness.js +807 -0
  42. package/dist/sync/models.d.ts +216 -0
  43. package/dist/sync/models.js +644 -0
  44. package/dist/sync/mutationHandler.d.ts +97 -0
  45. package/dist/sync/mutationHandler.js +886 -0
  46. package/dist/sync/registry.d.ts +73 -0
  47. package/dist/sync/registry.js +223 -0
  48. package/dist/sync/routes.d.ts +62 -0
  49. package/dist/sync/routes.js +936 -0
  50. package/dist/sync/scripts/compactTombstones.d.ts +47 -0
  51. package/dist/sync/scripts/compactTombstones.js +270 -0
  52. package/dist/sync/serialize.d.ts +20 -0
  53. package/dist/{tests/bunSetup.js → sync/serialize.js} +35 -68
  54. package/dist/sync/socketHandlers.d.ts +54 -0
  55. package/dist/sync/socketHandlers.js +470 -0
  56. package/dist/sync/streams.d.ts +85 -0
  57. package/dist/sync/streams.js +221 -0
  58. package/dist/sync/syncApp.d.ts +29 -0
  59. package/dist/sync/syncApp.js +44 -0
  60. package/dist/sync/syncBatch.d.ts +71 -0
  61. package/dist/sync/syncBatch.js +252 -0
  62. package/dist/sync/syncSeqPlugin.d.ts +8 -0
  63. package/dist/sync/syncSeqPlugin.js +903 -0
  64. package/dist/sync/types.d.ts +254 -0
  65. package/dist/sync/types.js +9 -0
  66. package/dist/terrenoApp.js +90 -27
  67. package/dist/tests/models.d.ts +11 -27
  68. package/dist/tests/models.js +3 -5
  69. package/dist/tests/testHelper.d.ts +3 -9
  70. package/dist/vendor/wesleytodd-openapi/index.d.ts +1 -1
  71. package/dist/vendor/wesleytodd-openapi/lib/ui.d.ts +2 -1
  72. package/package.json +10 -8
  73. package/src/__tests__/openApiCompat.test.ts +20 -0
  74. package/src/actions.test.ts +12 -19
  75. package/src/actions.ts +2 -2
  76. package/src/api.coverage.test.ts +9 -7
  77. package/src/api.errorPaths.test.ts +1 -47
  78. package/src/api.test.ts +12 -0
  79. package/src/api.ts +98 -317
  80. package/src/auth.test.ts +128 -176
  81. package/src/auth.ts +109 -0
  82. package/src/betterAuth.ts +6 -0
  83. package/src/betterAuthSetup.test.ts +34 -0
  84. package/src/betterAuthSetup.ts +27 -8
  85. package/src/configurationPlugin.ts +2 -2
  86. package/src/consentApp.test.ts +12 -12
  87. package/src/docLoader.ts +3 -1
  88. package/src/errors.ts +33 -0
  89. package/src/expressServer.test.ts +7 -1
  90. package/src/expressServer.ts +5 -11
  91. package/src/githubAuth.ts +3 -1
  92. package/src/index.ts +42 -0
  93. package/src/middleware.test.ts +40 -1
  94. package/src/middleware.ts +15 -0
  95. package/src/models/versionConfig.ts +1 -1
  96. package/src/openApiBuilder.test.ts +9 -24
  97. package/src/openApiCompat.ts +99 -45
  98. package/src/openApiValidator.test.ts +0 -41
  99. package/src/permissions.test.ts +75 -1
  100. package/src/permissions.ts +49 -0
  101. package/src/plugins.test.ts +54 -14
  102. package/src/plugins.ts +47 -9
  103. package/src/populate.test.ts +16 -25
  104. package/src/realtime/changeStreamWatcher.ts +552 -114
  105. package/src/realtime/realtime.test.ts +157 -239
  106. package/src/realtime/realtimeApp.ts +80 -19
  107. package/src/realtime/sessionRevalidation.test.ts +423 -0
  108. package/src/realtime/sessionRevalidation.ts +273 -0
  109. package/src/realtime/socketAuth.test.ts +355 -0
  110. package/src/realtime/socketAuth.ts +228 -0
  111. package/src/realtime/socketUser.ts +69 -0
  112. package/src/realtime/types.ts +40 -0
  113. package/src/secretProviders.test.ts +7 -1
  114. package/src/secretProviders.ts +15 -3
  115. package/src/sync/ensureSyncIndexes.test.ts +144 -0
  116. package/src/sync/executors.test.ts +882 -0
  117. package/src/sync/executors.ts +703 -0
  118. package/src/sync/integration.test.ts +1160 -0
  119. package/src/sync/loadHarness.ts +618 -0
  120. package/src/sync/models.ts +640 -0
  121. package/src/sync/mutationHandler.test.ts +1252 -0
  122. package/src/sync/mutationHandler.ts +850 -0
  123. package/src/sync/registry.ts +232 -0
  124. package/src/sync/routes.ts +812 -0
  125. package/src/sync/scripts/compactTombstones.test.ts +249 -0
  126. package/src/sync/scripts/compactTombstones.ts +145 -0
  127. package/src/sync/serialize.ts +48 -0
  128. package/src/sync/sessionRevalidationIntegration.test.ts +281 -0
  129. package/src/sync/socketHandlers.ts +320 -0
  130. package/src/sync/streams.ts +188 -0
  131. package/src/sync/sync.test.ts +582 -0
  132. package/src/sync/syncApp.ts +44 -0
  133. package/src/sync/syncBatch.ts +219 -0
  134. package/src/sync/syncFrontier.test.ts +494 -0
  135. package/src/sync/syncPhaseC.test.ts +718 -0
  136. package/src/sync/syncRoutes.test.ts +865 -0
  137. package/src/sync/syncSeqPlugin.ts +738 -0
  138. package/src/sync/syncSocket.test.ts +1440 -0
  139. package/src/sync/types.ts +270 -0
  140. package/src/terrenoApp.ts +37 -17
  141. package/src/tests/bunSetup.ts +8 -0
  142. package/src/tests/models.ts +6 -8
  143. package/tsconfig.json +4 -4
  144. package/tsconfig.typedoc.json +7 -1
  145. package/dist/__tests__/openApiCompat.test.js +0 -317
  146. package/dist/__tests__/versionCheckPlugin.test.d.ts +0 -1
  147. package/dist/__tests__/versionCheckPlugin.test.js +0 -597
  148. package/dist/actions.openApi.test.d.ts +0 -1
  149. package/dist/actions.openApi.test.js +0 -253
  150. package/dist/actions.test.d.ts +0 -1
  151. package/dist/actions.test.js +0 -1087
  152. package/dist/api.arrayOperations.test.d.ts +0 -1
  153. package/dist/api.arrayOperations.test.js +0 -878
  154. package/dist/api.asyncHandler.test.d.ts +0 -1
  155. package/dist/api.asyncHandler.test.js +0 -236
  156. package/dist/api.coverage.test.d.ts +0 -1
  157. package/dist/api.coverage.test.js +0 -192
  158. package/dist/api.errorPaths.test.d.ts +0 -1
  159. package/dist/api.errorPaths.test.js +0 -887
  160. package/dist/api.errors.test.d.ts +0 -1
  161. package/dist/api.errors.test.js +0 -185
  162. package/dist/api.hooks.test.d.ts +0 -1
  163. package/dist/api.hooks.test.js +0 -950
  164. package/dist/api.query.test.d.ts +0 -1
  165. package/dist/api.query.test.js +0 -948
  166. package/dist/api.test.d.ts +0 -1
  167. package/dist/api.test.js +0 -2820
  168. package/dist/auth.compile.test.d.ts +0 -1
  169. package/dist/auth.compile.test.js +0 -201
  170. package/dist/auth.coverage.test.d.ts +0 -1
  171. package/dist/auth.coverage.test.js +0 -202
  172. package/dist/auth.test.d.ts +0 -1
  173. package/dist/auth.test.js +0 -2286
  174. package/dist/betterAuth.test.d.ts +0 -1
  175. package/dist/betterAuth.test.js +0 -181
  176. package/dist/betterAuthApp.test.d.ts +0 -1
  177. package/dist/betterAuthApp.test.js +0 -242
  178. package/dist/betterAuthSetup.test.d.ts +0 -1
  179. package/dist/betterAuthSetup.test.js +0 -762
  180. package/dist/config.test.d.ts +0 -1
  181. package/dist/config.test.js +0 -353
  182. package/dist/configuration.test.d.ts +0 -1
  183. package/dist/configuration.test.js +0 -980
  184. package/dist/configurationPlugin.test.d.ts +0 -1
  185. package/dist/configurationPlugin.test.js +0 -827
  186. package/dist/consentApp.test.d.ts +0 -1
  187. package/dist/consentApp.test.js +0 -1411
  188. package/dist/docLoader.test.d.ts +0 -1
  189. package/dist/docLoader.test.js +0 -137
  190. package/dist/envConfigurationPlugin.test.d.ts +0 -1
  191. package/dist/envConfigurationPlugin.test.js +0 -369
  192. package/dist/errors.test.d.ts +0 -1
  193. package/dist/errors.test.js +0 -607
  194. package/dist/expressServer.test.d.ts +0 -1
  195. package/dist/expressServer.test.js +0 -1249
  196. package/dist/githubAuth.test.d.ts +0 -1
  197. package/dist/githubAuth.test.js +0 -1142
  198. package/dist/httpClient.test.d.ts +0 -1
  199. package/dist/httpClient.test.js +0 -1471
  200. package/dist/logger.test.d.ts +0 -1
  201. package/dist/logger.test.js +0 -685
  202. package/dist/middleware.test.d.ts +0 -1
  203. package/dist/middleware.test.js +0 -241
  204. package/dist/notifiers/googleChatNotifier.test.d.ts +0 -1
  205. package/dist/notifiers/googleChatNotifier.test.js +0 -298
  206. package/dist/notifiers/slackNotifier.test.d.ts +0 -1
  207. package/dist/notifiers/slackNotifier.test.js +0 -297
  208. package/dist/notifiers/zoomNotifier.test.d.ts +0 -1
  209. package/dist/notifiers/zoomNotifier.test.js +0 -373
  210. package/dist/openApi.test.d.ts +0 -1
  211. package/dist/openApi.test.js +0 -620
  212. package/dist/openApiBuilder.test.d.ts +0 -1
  213. package/dist/openApiBuilder.test.js +0 -599
  214. package/dist/openApiEtag.test.d.ts +0 -1
  215. package/dist/openApiEtag.test.js +0 -86
  216. package/dist/openApiValidator.test.d.ts +0 -1
  217. package/dist/openApiValidator.test.js +0 -795
  218. package/dist/permissions.middleware.test.d.ts +0 -1
  219. package/dist/permissions.middleware.test.js +0 -308
  220. package/dist/permissions.test.d.ts +0 -1
  221. package/dist/permissions.test.js +0 -439
  222. package/dist/plugins.test.d.ts +0 -1
  223. package/dist/plugins.test.js +0 -902
  224. package/dist/populate.test.d.ts +0 -1
  225. package/dist/populate.test.js +0 -370
  226. package/dist/realtime/realtime.test.d.ts +0 -10
  227. package/dist/realtime/realtime.test.js +0 -4213
  228. package/dist/realtime/realtimeAppSetup.test.d.ts +0 -1
  229. package/dist/realtime/realtimeAppSetup.test.js +0 -213
  230. package/dist/requestContext.test.d.ts +0 -1
  231. package/dist/requestContext.test.js +0 -412
  232. package/dist/scriptRunner.test.d.ts +0 -1
  233. package/dist/scriptRunner.test.js +0 -386
  234. package/dist/secretProviders.test.d.ts +0 -1
  235. package/dist/secretProviders.test.js +0 -726
  236. package/dist/syncConsents.test.d.ts +0 -1
  237. package/dist/syncConsents.test.js +0 -522
  238. package/dist/terrenoApp.test.d.ts +0 -1
  239. package/dist/terrenoApp.test.js +0 -489
  240. package/dist/tests/bunSetup.d.ts +0 -1
  241. package/dist/tests/fixtures/compileAuthEntry.d.ts +0 -1
  242. package/dist/tests/fixtures/compileAuthEntry.js +0 -37
  243. package/dist/tests/testEnv.d.ts +0 -0
  244. package/dist/tests/testEnv.js +0 -6
  245. package/dist/transformers.test.d.ts +0 -1
  246. package/dist/transformers.test.js +0 -423
  247. package/dist/utils.test.d.ts +0 -1
  248. package/dist/utils.test.js +0 -242
  249. package/src/realtime/realtimeAppSetup.test.ts +0 -161
  250. /package/dist/{__tests__/openApiCompat.test.d.ts → sync/loadHarness.d.ts} +0 -0
@@ -0,0 +1,718 @@
1
+ // noExplicitAny: test model typing
2
+ // biome-ignore-all lint/suspicious/noExplicitAny: test model typing
3
+ import {beforeEach, describe, expect, it} from "bun:test";
4
+ import type express from "express";
5
+ import {model, Schema} from "mongoose";
6
+ import supertest from "supertest";
7
+ import type TestAgent from "supertest/lib/agent";
8
+ import type {ModelRouterOptions} from "../api";
9
+ import {addAuthRoutes, setupAuth, type User} from "../auth";
10
+ import {Permissions} from "../permissions";
11
+ import {createdUpdatedPlugin, type IsDeleted, isDeletedPlugin} from "../plugins";
12
+ import {DEFAULT_IGNORED_COLLECTIONS} from "../realtime/changeStreamWatcher";
13
+ import {authAsUser, getBaseServer, setupDb, UserModel} from "../tests";
14
+ import {SyncCounter, SyncKey, SyncMutation} from "./models";
15
+ import {
16
+ clearSyncRegistry,
17
+ ensureSyncIndexes,
18
+ findSyncEntryByCollectionTag,
19
+ registerSync,
20
+ type SyncRegistryEntry,
21
+ } from "./registry";
22
+ import {compactEntryTombstones} from "./scripts/compactTombstones";
23
+ import {SyncApp} from "./syncApp";
24
+ import {syncPlugin} from "./syncSeqPlugin";
25
+
26
+ /**
27
+ * Phase C route/scope tests: per-stream snapshot cursors (C2), legacy `_id` pagination
28
+ * (C3), write-scope enforcement + snapshot read parity (C6), and the C8 minors.
29
+ * C1 (frontier) and C4 (scope-move markers) have their own dedicated files.
30
+ */
31
+
32
+ interface PhaseCTodo extends IsDeleted {
33
+ _id: string;
34
+ title: string;
35
+ ownerId: string;
36
+ _syncSeq?: number;
37
+ }
38
+
39
+ const phaseCTodoSchema = new Schema<PhaseCTodo>({
40
+ ownerId: {description: "The owner", type: String},
41
+ title: {description: "The title", required: true, type: String},
42
+ });
43
+ phaseCTodoSchema.plugin(isDeletedPlugin);
44
+ phaseCTodoSchema.plugin(createdUpdatedPlugin);
45
+ phaseCTodoSchema.plugin(syncPlugin);
46
+ const PhaseCTodoModel = model<PhaseCTodo>("SyncPhaseCTodo", phaseCTodoSchema);
47
+
48
+ interface PhaseCProject extends IsDeleted {
49
+ _id: string;
50
+ title: string;
51
+ orgId: string;
52
+ _syncSeq?: number;
53
+ }
54
+
55
+ interface PhaseCNote extends IsDeleted {
56
+ _id: string;
57
+ title: string;
58
+ ownerId: string;
59
+ _syncSeq?: number;
60
+ }
61
+
62
+ /**
63
+ * Task 9.14: a STRING `_id` model — the shape synced models are designed around, since
64
+ * clients mint their own ids offline. The legacy (seq-0) stratum must page these by raw
65
+ * string comparison; casting the cursor to ObjectId either throws or matches nothing.
66
+ */
67
+ const phaseCNoteSchema = new Schema<PhaseCNote>({
68
+ _id: {description: "Client-minted string id", type: String},
69
+ ownerId: {description: "The owner", type: String},
70
+ title: {description: "The title", required: true, type: String},
71
+ });
72
+ phaseCNoteSchema.plugin(isDeletedPlugin);
73
+ phaseCNoteSchema.plugin(createdUpdatedPlugin);
74
+ phaseCNoteSchema.plugin(syncPlugin);
75
+ const PhaseCNoteModel = model<PhaseCNote>("SyncPhaseCNote", phaseCNoteSchema);
76
+
77
+ const phaseCProjectSchema = new Schema<PhaseCProject>({
78
+ orgId: {description: "The organization", type: String},
79
+ title: {description: "The title", required: true, type: String},
80
+ });
81
+ phaseCProjectSchema.plugin(isDeletedPlugin);
82
+ phaseCProjectSchema.plugin(createdUpdatedPlugin);
83
+ phaseCProjectSchema.plugin(syncPlugin);
84
+ const PhaseCProjectModel = model<PhaseCProject>("SyncPhaseCProject", phaseCProjectSchema);
85
+
86
+ const authedOptions = {
87
+ permissions: {
88
+ create: [Permissions.IsAuthenticated],
89
+ delete: [Permissions.IsAuthenticated],
90
+ list: [Permissions.IsAuthenticated],
91
+ read: [Permissions.IsAuthenticated],
92
+ update: [Permissions.IsAuthenticated],
93
+ },
94
+ } as unknown as ModelRouterOptions<any>;
95
+
96
+ // Per-user tenant membership, mutable so join tests can extend it.
97
+ const userOrgs = new Map<string, string[]>();
98
+
99
+ describe("Phase C sync routes", () => {
100
+ let app: express.Application;
101
+ let server: TestAgent;
102
+ let agent: TestAgent;
103
+ let notAdminId: string;
104
+
105
+ const ownerStream = (): string => `phaseCTodos|owner:${notAdminId}`;
106
+ const enc = encodeURIComponent;
107
+
108
+ beforeEach(async () => {
109
+ const [, notAdmin] = await setupDb();
110
+ notAdminId = String(notAdmin._id);
111
+ userOrgs.clear();
112
+ userOrgs.set(notAdminId, ["org1", "org2"]);
113
+
114
+ clearSyncRegistry();
115
+ registerSync({
116
+ config: {scope: {type: "owner"}},
117
+ model: PhaseCTodoModel as any,
118
+ options: authedOptions,
119
+ routePath: "/phaseCTodos",
120
+ });
121
+ registerSync({
122
+ config: {scope: {field: "orgId", type: "tenant"}},
123
+ model: PhaseCProjectModel as any,
124
+ options: authedOptions,
125
+ routePath: "/phaseCProjects",
126
+ });
127
+ registerSync({
128
+ config: {scope: {type: "owner"}},
129
+ model: PhaseCNoteModel as any,
130
+ options: authedOptions,
131
+ routePath: "/phaseCNotes",
132
+ });
133
+
134
+ await Promise.all([
135
+ PhaseCTodoModel.collection.deleteMany({}),
136
+ PhaseCNoteModel.collection.deleteMany({}),
137
+ PhaseCProjectModel.collection.deleteMany({}),
138
+ SyncCounter.deleteMany({}),
139
+ SyncKey.deleteMany({}),
140
+ SyncMutation.deleteMany({}),
141
+ ]);
142
+
143
+ app = getBaseServer();
144
+ setupAuth(app as any, UserModel as any);
145
+ addAuthRoutes(app as any, UserModel as any);
146
+ new SyncApp({
147
+ getUserScopes: (user: User, entry: SyncRegistryEntry) => {
148
+ // Custom-scoped entries (used by the $or snapshotFilter test) resolve their
149
+ // membership to the caller's own id (the custom scope value = ownerId).
150
+ if (typeof entry.config.scope === "function") {
151
+ return [String(user.id)];
152
+ }
153
+ return userOrgs.get(String(user.id)) ?? [];
154
+ },
155
+ }).register(app);
156
+ // Task 9.9: no manual `ensureIndexes()` anywhere in this setup — registering SyncApp
157
+ // enqueues the bookkeeping index builds, and this is the same await TerrenoApp.start()
158
+ // performs before listening.
159
+ await ensureSyncIndexes();
160
+
161
+ server = supertest(app);
162
+ agent = await authAsUser(app, "notAdmin");
163
+ });
164
+
165
+ // ── C2: per-stream cursors + /sync/streams ────────────────────────────────
166
+ describe("C2 — per-stream cursors and /sync/streams", () => {
167
+ it("GET /sync/streams returns owner + tenant streams reflecting memberships", async () => {
168
+ const res = await agent.get("/sync/streams").expect(200);
169
+ const streams: string[] = res.body.streams.map((s: any) => s.stream);
170
+ expect(streams).toContain(ownerStream());
171
+ expect(streams).toContain("phaseCProjects|tenant:org1");
172
+ expect(streams).toContain("phaseCProjects|tenant:org2");
173
+ // Every entry carries its collection tag.
174
+ for (const s of res.body.streams) {
175
+ expect(typeof s.collection).toBe("string");
176
+ }
177
+ });
178
+
179
+ it("requires authentication for /sync/streams", async () => {
180
+ await server.get("/sync/streams").expect(401);
181
+ });
182
+
183
+ it("catches two tenant streams to independent cursors (the flattened-cursor bug does NOT reproduce)", async () => {
184
+ // org1 has a high seq (many writes), org2 a low seq. Under the OLD flattened cursor,
185
+ // catching org1 to its head would strand org2 behind org1's cursor. Per-stream, each
186
+ // catches independently.
187
+ for (let i = 1; i <= 6; i++) {
188
+ await PhaseCProjectModel.create({orgId: "org1", title: `org1-${i}`});
189
+ }
190
+ await PhaseCProjectModel.create({orgId: "org2", title: "org2-only"});
191
+
192
+ const org1 = await agent
193
+ .get(`/sync/snapshot?stream=${enc("phaseCProjects|tenant:org1")}`)
194
+ .expect(200);
195
+ expect(org1.body.entities).toHaveLength(6);
196
+ expect(org1.body.cursor).toBe(6);
197
+
198
+ // org2's stream has its OWN counter — its single doc is seq 1, fully caught up
199
+ // regardless of org1's cursor being at 6.
200
+ const org2 = await agent
201
+ .get(`/sync/snapshot?stream=${enc("phaseCProjects|tenant:org2")}`)
202
+ .expect(200);
203
+ expect(org2.body.entities).toHaveLength(1);
204
+ expect(org2.body.entities[0].data.title).toBe("org2-only");
205
+ expect(org2.body.entities[0].seq).toBe(1);
206
+ expect(org2.body.cursor).toBe(1);
207
+ expect(org2.body.hasMore).toBe(false);
208
+ });
209
+
210
+ it("reflects a tenant join in /sync/streams (new stream becomes available)", async () => {
211
+ let res = await agent.get("/sync/streams").expect(200);
212
+ expect(res.body.streams.map((s: any) => s.stream)).not.toContain(
213
+ "phaseCProjects|tenant:org3"
214
+ );
215
+ // Join org3.
216
+ userOrgs.set(notAdminId, ["org1", "org2", "org3"]);
217
+ res = await agent.get("/sync/streams").expect(200);
218
+ expect(res.body.streams.map((s: any) => s.stream)).toContain("phaseCProjects|tenant:org3");
219
+ // And the newly-joined stream is now snapshottable.
220
+ await PhaseCProjectModel.create({orgId: "org3", title: "joined"});
221
+ const snap = await agent
222
+ .get(`/sync/snapshot?stream=${enc("phaseCProjects|tenant:org3")}`)
223
+ .expect(200);
224
+ expect(snap.body.entities[0].data.title).toBe("joined");
225
+ });
226
+
227
+ it("403s snapshotting a tenant stream the user does not belong to", async () => {
228
+ await agent.get(`/sync/snapshot?stream=${enc("phaseCProjects|tenant:orgOther")}`).expect(403);
229
+ });
230
+ });
231
+
232
+ // ── C3: legacy _id pagination ──────────────────────────────────────────────
233
+ describe("C3 — legacy _id-paged stratum", () => {
234
+ it("drains a large legacy stratum via legacyCursor then continues by seq (no infinite loop)", async () => {
235
+ // 1201 legacy docs (no _syncSeq) via raw insert; limit 500. The old first-page-only
236
+ // logic looped forever; the _id stratum drains deterministically.
237
+ const legacy = Array.from({length: 1201}, (_v, i) => ({
238
+ deleted: false,
239
+ name: undefined,
240
+ ownerId: notAdminId,
241
+ title: `legacy-${String(i).padStart(4, "0")}`,
242
+ }));
243
+ await PhaseCTodoModel.collection.insertMany(legacy as any);
244
+ // A couple of modern (stamped) docs after the legacy stratum.
245
+ await PhaseCTodoModel.create({ownerId: notAdminId, title: "modern-1"});
246
+ await PhaseCTodoModel.create({ownerId: notAdminId, title: "modern-2"});
247
+
248
+ const seen = new Set<string>();
249
+ let cursor = 0;
250
+ let legacyCursor: string | undefined;
251
+ let pages = 0;
252
+ const limit = 500;
253
+ // Simulate the client loop: echo legacyCursor until absent, then page by seq.
254
+ for (;;) {
255
+ pages += 1;
256
+ expect(pages).toBeLessThan(20); // termination guard
257
+ const qs = new URLSearchParams({limit: String(limit), stream: ownerStream()});
258
+ if (cursor > 0) {
259
+ qs.set("cursor", String(cursor));
260
+ }
261
+ if (legacyCursor !== undefined) {
262
+ qs.set("legacyCursor", legacyCursor);
263
+ }
264
+ const res = await agent.get(`/sync/snapshot?${qs.toString()}`).expect(200);
265
+ for (const e of res.body.entities) {
266
+ seen.add(e.id);
267
+ }
268
+ if (res.body.legacyCursor !== undefined) {
269
+ legacyCursor = res.body.legacyCursor;
270
+ continue;
271
+ }
272
+ // Legacy stratum drained; now paging by seq.
273
+ legacyCursor = undefined;
274
+ if (!res.body.hasMore) {
275
+ break;
276
+ }
277
+ cursor = res.body.cursor;
278
+ }
279
+ // All 1201 legacy + 2 modern docs delivered, none missed.
280
+ expect(seen.size).toBe(1203);
281
+ }, 30_000);
282
+
283
+ it("delivers a small legacy stratum then the seq stratum in order", async () => {
284
+ await PhaseCTodoModel.collection.insertMany([
285
+ {deleted: false, ownerId: notAdminId, title: "legacy-a"},
286
+ {deleted: false, ownerId: notAdminId, title: "legacy-b"},
287
+ ] as any);
288
+ await PhaseCTodoModel.create({ownerId: notAdminId, title: "stamped"});
289
+
290
+ const page1 = await agent
291
+ .get(`/sync/snapshot?stream=${enc(ownerStream())}&limit=10`)
292
+ .expect(200);
293
+ // First page is the legacy stratum (seq 0), with a legacyCursor.
294
+ expect(page1.body.entities.every((e: any) => e.seq === 0)).toBe(true);
295
+ expect(page1.body.legacyCursor).toBeDefined();
296
+ expect(page1.body.hasMore).toBe(true);
297
+
298
+ const page2 = await agent
299
+ .get(
300
+ `/sync/snapshot?stream=${enc(ownerStream())}&limit=10&legacyCursor=${enc(
301
+ page1.body.legacyCursor
302
+ )}`
303
+ )
304
+ .expect(200);
305
+ // Legacy stratum exhausted; falls through to seq paging (no legacyCursor).
306
+ expect(page2.body.legacyCursor).toBeUndefined();
307
+ const stamped = page2.body.entities.find((e: any) => e.data?.title === "stamped");
308
+ expect(stamped?.seq).toBe(1);
309
+ });
310
+
311
+ it("Task 9.14: a string-_id model with more legacy docs than the limit bootstraps completely", async () => {
312
+ // Non-hex, client-minted ids: casting the legacy cursor to ObjectId would throw
313
+ // (500), and a hex-shaped string id would compare across BSON types and match
314
+ // nothing — either way the stratum reported itself exhausted after one page and the
315
+ // remaining docs were silently skipped forever.
316
+ const noteStream = `phaseCNotes|owner:${notAdminId}`;
317
+ const total = 25;
318
+ const limit = 10;
319
+ await PhaseCNoteModel.collection.insertMany(
320
+ Array.from({length: total}, (_v, i) => ({
321
+ _id: `note-${String(i).padStart(3, "0")}`,
322
+ deleted: false,
323
+ ownerId: notAdminId,
324
+ title: `legacy note ${i}`,
325
+ })) as any
326
+ );
327
+ await PhaseCNoteModel.create({
328
+ _id: "note-modern",
329
+ ownerId: notAdminId,
330
+ title: "stamped note",
331
+ });
332
+
333
+ const seen = new Set<string>();
334
+ let cursor = 0;
335
+ let legacyCursor: string | undefined;
336
+ for (let page = 0; page < 12; page++) {
337
+ const qs = new URLSearchParams({limit: String(limit), stream: noteStream});
338
+ if (cursor > 0) {
339
+ qs.set("cursor", String(cursor));
340
+ }
341
+ if (legacyCursor !== undefined) {
342
+ qs.set("legacyCursor", legacyCursor);
343
+ }
344
+ const res = await agent.get(`/sync/snapshot?${qs.toString()}`).expect(200);
345
+ for (const entity of res.body.entities) {
346
+ seen.add(entity.id);
347
+ }
348
+ if (res.body.legacyCursor !== undefined) {
349
+ legacyCursor = res.body.legacyCursor;
350
+ continue;
351
+ }
352
+ legacyCursor = undefined;
353
+ if (!res.body.hasMore) {
354
+ break;
355
+ }
356
+ cursor = res.body.cursor;
357
+ }
358
+ expect(seen.size).toBe(total + 1);
359
+ expect(seen.has("note-000")).toBe(true);
360
+ expect(seen.has("note-024")).toBe(true);
361
+ expect(seen.has("note-modern")).toBe(true);
362
+ });
363
+
364
+ it("Task 9.14: 400s (not 500s) on a malformed legacyCursor for an ObjectId-keyed model", async () => {
365
+ await PhaseCTodoModel.collection.insertMany([
366
+ {deleted: false, ownerId: notAdminId, title: "legacy-a"},
367
+ ] as any);
368
+ await agent
369
+ .get(`/sync/snapshot?stream=${enc(ownerStream())}&legacyCursor=not-an-object-id`)
370
+ .expect(400);
371
+ });
372
+ });
373
+
374
+ // ── C6: write-scope enforcement + snapshot read parity ─────────────────────
375
+ describe("C6 — write-scope enforcement + read parity", () => {
376
+ const create = (mutationId: string, data: Record<string, unknown>) => ({
377
+ collection: "phaseCTodos",
378
+ data,
379
+ mutationId,
380
+ operation: "create",
381
+ });
382
+
383
+ it("nacks unauthorized a create with a foreign ownerId (owner scope)", async () => {
384
+ const res = await agent
385
+ .post("/sync/mutate")
386
+ .send(create("c6-owner-foreign", {ownerId: "someoneElse", title: "x"}))
387
+ .expect(403);
388
+ expect(res.body.nack.code).toBe("unauthorized");
389
+ expect(await PhaseCTodoModel.countDocuments({title: "x"})).toBe(0);
390
+ });
391
+
392
+ it("allows a create with the caller's own ownerId", async () => {
393
+ const res = await agent
394
+ .post("/sync/mutate")
395
+ .send(create("c6-owner-self", {ownerId: notAdminId, title: "mine"}))
396
+ .expect(200);
397
+ expect(res.body.ack.mutationId).toBe("c6-owner-self");
398
+ });
399
+
400
+ it("nacks unauthorized a tenant create for a non-member org", async () => {
401
+ const res = await agent
402
+ .post("/sync/mutate")
403
+ .send({
404
+ collection: "phaseCProjects",
405
+ data: {orgId: "orgNotMine", title: "sneaky"},
406
+ mutationId: "c6-tenant-foreign",
407
+ operation: "create",
408
+ })
409
+ .expect(403);
410
+ expect(res.body.nack.code).toBe("unauthorized");
411
+ });
412
+
413
+ it("allows a tenant create for a member org", async () => {
414
+ await agent
415
+ .post("/sync/mutate")
416
+ .send({
417
+ collection: "phaseCProjects",
418
+ data: {orgId: "org1", title: "ours"},
419
+ mutationId: "c6-tenant-member",
420
+ operation: "create",
421
+ })
422
+ .expect(200);
423
+ });
424
+
425
+ it("snapshot omits per-doc read-denied docs but still advances the cursor past them", async () => {
426
+ // A read permission that denies odd-titled docs.
427
+ clearSyncRegistry();
428
+ registerSync({
429
+ config: {scope: {type: "owner"}},
430
+ model: PhaseCTodoModel as any,
431
+ options: {
432
+ ...authedOptions,
433
+ permissions: {
434
+ ...(authedOptions as any).permissions,
435
+ read: [
436
+ (_method: any, _user: any, doc?: any) => {
437
+ if (!doc) {
438
+ return true;
439
+ }
440
+ return !String(doc.title).endsWith("-secret");
441
+ },
442
+ ],
443
+ },
444
+ } as unknown as ModelRouterOptions<any>,
445
+ routePath: "/phaseCTodos",
446
+ });
447
+
448
+ await PhaseCTodoModel.create({ownerId: notAdminId, title: "visible-1"});
449
+ await PhaseCTodoModel.create({ownerId: notAdminId, title: "hidden-secret"});
450
+ await PhaseCTodoModel.create({ownerId: notAdminId, title: "visible-2"});
451
+
452
+ const res = await agent.get(`/sync/snapshot?stream=${enc(ownerStream())}`).expect(200);
453
+ const titles = res.body.entities.map((e: any) => e.data.title);
454
+ expect(titles).toEqual(["visible-1", "visible-2"]);
455
+ // The cursor advanced past the denied doc (seq 3), so it is never re-fetched.
456
+ expect(res.body.cursor).toBe(3);
457
+ });
458
+
459
+ it("advances the cursor past a full page of read-denied docs so bootstrap terminates", async () => {
460
+ // A read permission denying every "denied-*" doc, so a whole page can be dropped.
461
+ clearSyncRegistry();
462
+ registerSync({
463
+ config: {scope: {type: "owner"}},
464
+ model: PhaseCTodoModel as any,
465
+ options: {
466
+ ...authedOptions,
467
+ permissions: {
468
+ ...(authedOptions as any).permissions,
469
+ read: [
470
+ (_method: any, _user: any, doc?: any) => {
471
+ if (!doc) {
472
+ return true;
473
+ }
474
+ return !String(doc.title).startsWith("denied-");
475
+ },
476
+ ],
477
+ },
478
+ } as unknown as ModelRouterOptions<any>,
479
+ routePath: "/phaseCTodos",
480
+ });
481
+
482
+ // 5 contiguous denied docs (more than the page limit of 2) then one visible doc.
483
+ for (let i = 1; i <= 5; i++) {
484
+ await PhaseCTodoModel.create({ownerId: notAdminId, title: `denied-${i}`});
485
+ }
486
+ await PhaseCTodoModel.create({ownerId: notAdminId, title: "visible"});
487
+
488
+ const seenTitles: string[] = [];
489
+ let cursor = 0;
490
+ let pages = 0;
491
+ for (;;) {
492
+ pages += 1;
493
+ expect(pages).toBeLessThan(10); // termination guard: the old cursor logic looped forever
494
+ const qs = new URLSearchParams({limit: "2", stream: ownerStream()});
495
+ if (cursor > 0) {
496
+ qs.set("cursor", String(cursor));
497
+ }
498
+ const res = await agent.get(`/sync/snapshot?${qs.toString()}`).expect(200);
499
+ for (const entity of res.body.entities) {
500
+ seenTitles.push(entity.data?.title ?? `tombstone:${entity.id}`);
501
+ }
502
+ // Every page consumes seqs, so the cursor always moves forward.
503
+ expect(res.body.cursor).toBeGreaterThan(cursor);
504
+ cursor = res.body.cursor;
505
+ if (!res.body.hasMore) {
506
+ break;
507
+ }
508
+ }
509
+ // Denied docs are never leaked, and the cursor ends at the stream head.
510
+ expect(seenTitles).toEqual(["visible"]);
511
+ expect(cursor).toBe(6);
512
+ });
513
+
514
+ it("composes a custom-scope $or snapshotFilter with $and (does not clobber deleted/seq)", async () => {
515
+ // A custom scope whose snapshotFilter is an $or; the route must $and it with the
516
+ // deleted/seq clauses so tombstones and seq bounds still apply.
517
+ clearSyncRegistry();
518
+ registerSync({
519
+ config: {
520
+ scope: (doc: Record<string, unknown>) => String(doc.ownerId),
521
+ snapshotFilter: () => ({$or: [{ownerId: notAdminId}, {ownerId: "shared"}]}),
522
+ },
523
+ model: PhaseCTodoModel as any,
524
+ options: authedOptions,
525
+ routePath: "/phaseCTodos",
526
+ });
527
+ const mine = await PhaseCTodoModel.create({ownerId: notAdminId, title: "mine"});
528
+ await PhaseCTodoModel.create({ownerId: "shared", title: "shared"});
529
+ await PhaseCTodoModel.create({ownerId: "other", title: "other"});
530
+ // Soft-delete one so the tombstone path is exercised under the $or filter.
531
+ mine.deleted = true;
532
+ await mine.save();
533
+
534
+ const customStream = `phaseCTodos|custom:${notAdminId}`;
535
+ const res = await agent.get(`/sync/snapshot?stream=${enc(customStream)}`).expect(200);
536
+ const byTitle = new Map(res.body.entities.map((e: any) => [e.id, e]));
537
+ // "other" is excluded by the $or filter; "mine" appears as a tombstone (data null).
538
+ const titles = res.body.entities
539
+ .filter((e: any) => !e.deleted)
540
+ .map((e: any) => e.data.title)
541
+ .sort();
542
+ expect(titles).toEqual(["shared"]);
543
+ const tombstone = byTitle.get(String(mine._id)) as any;
544
+ expect(tombstone?.deleted).toBe(true);
545
+ expect(tombstone?.data).toBeNull();
546
+ });
547
+
548
+ it("throws on a query updateOne with upsert:true (m8)", async () => {
549
+ const doc = await PhaseCTodoModel.create({ownerId: notAdminId, title: "u"});
550
+ // upsert:true on a synced model must throw at the plugin layer.
551
+ let threw = false;
552
+ try {
553
+ await PhaseCTodoModel.updateOne({_id: doc._id}, {$set: {title: "u2"}}, {upsert: true});
554
+ } catch (error) {
555
+ threw = true;
556
+ expect(String(error)).toMatch(/upsert/i);
557
+ }
558
+ expect(threw).toBe(true);
559
+ });
560
+
561
+ it("nacks validation an update with baseVersion omitted (C8)", async () => {
562
+ const doc = await PhaseCTodoModel.create({ownerId: notAdminId, title: "needs base"});
563
+ const res = await agent
564
+ .post("/sync/mutate")
565
+ .send({
566
+ collection: "phaseCTodos",
567
+ data: {title: "changed"},
568
+ id: String(doc._id),
569
+ mutationId: "c8-no-base",
570
+ operation: "update",
571
+ // baseVersion intentionally omitted
572
+ })
573
+ .expect(422);
574
+ expect(res.body.nack.code).toBe("validation");
575
+ expect(res.body.nack.message).toMatch(/baseVersion/i);
576
+ });
577
+ });
578
+
579
+ // ── C8: minors ─────────────────────────────────────────────────────────────
580
+ describe("C8 — minors", () => {
581
+ it("returns an idempotent ack when deleting an already-deleted doc (not 404/validation)", async () => {
582
+ const doc = await PhaseCTodoModel.create({ownerId: notAdminId, title: "to delete"});
583
+ const first = await agent
584
+ .post("/sync/mutate")
585
+ .send({
586
+ collection: "phaseCTodos",
587
+ id: String(doc._id),
588
+ mutationId: "c8-del-1",
589
+ operation: "delete",
590
+ })
591
+ .expect(200);
592
+ expect(first.body.ack).toBeDefined();
593
+
594
+ // Second delete of the (now soft-deleted) doc, distinct mutationId: idempotent ack.
595
+ const second = await agent
596
+ .post("/sync/mutate")
597
+ .send({
598
+ collection: "phaseCTodos",
599
+ id: String(doc._id),
600
+ mutationId: "c8-del-2",
601
+ operation: "delete",
602
+ })
603
+ .expect(200);
604
+ expect(second.body.ack).toBeDefined();
605
+ expect(second.body.ack.id).toBe(String(doc._id));
606
+ });
607
+
608
+ it("passes 'read' (not 'list') to the modelRouter responseHandler for single-entity sync serialization", async () => {
609
+ const seenMethods: string[] = [];
610
+ clearSyncRegistry();
611
+ registerSync({
612
+ config: {scope: {type: "owner"}},
613
+ model: PhaseCTodoModel as any,
614
+ options: {
615
+ ...authedOptions,
616
+ responseHandler: (value: any, method: string) => {
617
+ seenMethods.push(method);
618
+ return method === "read" ? {shape: "read", title: value.title} : value;
619
+ },
620
+ } as unknown as ModelRouterOptions<any>,
621
+ routePath: "/phaseCTodos",
622
+ });
623
+ await PhaseCTodoModel.create({ownerId: notAdminId, title: "rh"});
624
+ const res = await agent.get(`/sync/snapshot?stream=${enc(ownerStream())}`).expect(200);
625
+ expect(seenMethods).toContain("read");
626
+ expect(seenMethods).not.toContain("list");
627
+ expect(res.body.entities[0].data).toEqual({shape: "read", title: "rh"});
628
+ });
629
+
630
+ it("rejects a duplicate collectionTag at registration", () => {
631
+ clearSyncRegistry();
632
+ registerSync({
633
+ config: {scope: {type: "owner"}},
634
+ model: PhaseCTodoModel as any,
635
+ options: authedOptions,
636
+ routePath: "/dupTag",
637
+ });
638
+ // A different model under the SAME tag must be rejected (the tag, not the model,
639
+ // is the duplicate). PhaseCProjectModel's valid tenant scope passes the field check
640
+ // so registration reaches the duplicate-tag guard.
641
+ expect(() =>
642
+ registerSync({
643
+ config: {scope: {field: "orgId", type: "tenant"}},
644
+ model: PhaseCProjectModel as any,
645
+ options: authedOptions,
646
+ routePath: "/dupTag",
647
+ })
648
+ ).toThrow(/already registered/i);
649
+ });
650
+ });
651
+
652
+ // ── C7: change-stream watcher ignores sync bookkeeping collections ──────────
653
+ describe("C7 — watcher ignores sync bookkeeping collections", () => {
654
+ it("adds the sync bookkeeping collections to the watcher's default ignore list", () => {
655
+ // The watcher's change-stream pipeline excludes these collections, so their own
656
+ // internal writes (counter $inc, ledger rows, scope-move markers, key material)
657
+ // never drive fan-out or get reprocessed as deltas.
658
+ for (const coll of ["synccounters", "syncmutations", "syncscopemoves", "synckeys"]) {
659
+ expect(DEFAULT_IGNORED_COLLECTIONS).toContain(coll);
660
+ }
661
+ });
662
+ });
663
+
664
+ // ── Task 9.15: retention watermark end-to-end ───────────────────────────────
665
+ describe("Task 9.15 — retention watermark drives re-bootstrap", () => {
666
+ /** The registered entry with retention forced to 0 so "now" is already past it. */
667
+ const zeroRetentionEntry = (collectionTag: string): SyncRegistryEntry => {
668
+ const entry = findSyncEntryByCollectionTag(collectionTag);
669
+ if (!entry) {
670
+ throw new Error(`${collectionTag} is not registered`);
671
+ }
672
+ return {...entry, config: {...entry.config, retentionDays: 0}};
673
+ };
674
+
675
+ it("a cursor older than the compaction watermark re-bootstraps and converges", async () => {
676
+ // Three docs; the middle one is deleted (seq 4) and then compacted away. A client
677
+ // whose cursor sits at 2 — above the retention floor the OLD min(seq) computation
678
+ // would have reported, but below the deletion — must be told to re-bootstrap.
679
+ const keep = await PhaseCTodoModel.create({ownerId: notAdminId, title: "keep"}); // seq 1
680
+ const doomed = await PhaseCTodoModel.create({ownerId: notAdminId, title: "doomed"}); // seq 2
681
+ await PhaseCTodoModel.create({ownerId: notAdminId, title: "later"}); // seq 3
682
+ doomed.deleted = true;
683
+ await doomed.save(); // seq 4 — the tombstone the stale cursor never saw
684
+
685
+ const stream = ownerStream();
686
+ // Nothing compacted yet: no retention gap to enforce.
687
+ const before = await agent.get(`/sync/snapshot?stream=${enc(stream)}&cursor=2`).expect(200);
688
+ expect(before.body.oldestRetainedSeq).toBe(0);
689
+
690
+ const counts = await compactEntryTombstones(zeroRetentionEntry("phaseCTodos"));
691
+ expect(counts.tombstones).toBe(1);
692
+
693
+ const after = await agent.get(`/sync/snapshot?stream=${enc(stream)}&cursor=2`).expect(200);
694
+ // The watermark is the reaped tombstone's seq, so the client's rule
695
+ // (cursor > 0 && cursor < oldestRetainedSeq) fires.
696
+ expect(after.body.oldestRetainedSeq).toBe(4);
697
+ expect(after.body.cursor).toBeLessThan(after.body.oldestRetainedSeq + 1);
698
+
699
+ // Re-bootstrapping from 0 converges on live state with the deleted doc absent.
700
+ const rebootstrap = await agent
701
+ .get(`/sync/snapshot?stream=${enc(stream)}&cursor=0`)
702
+ .expect(200);
703
+ const ids = rebootstrap.body.entities.map((e: any) => e.id).sort();
704
+ expect(ids).toEqual(
705
+ [String(keep._id), String((await PhaseCTodoModel.findOne({title: "later"}))?._id)].sort()
706
+ );
707
+ expect(rebootstrap.body.entities.some((e: any) => e.id === String(doomed._id))).toBe(false);
708
+ });
709
+
710
+ it("a live never-deleted early doc no longer pins the retention floor", async () => {
711
+ // The OLD computation returned min(retained seq) = 1 here, so every client with a
712
+ // cursor of 0 was told there was a retention gap it could not have missed.
713
+ await PhaseCTodoModel.create({ownerId: notAdminId, title: "early and alive"});
714
+ const res = await agent.get(`/sync/snapshot?stream=${enc(ownerStream())}`).expect(200);
715
+ expect(res.body.oldestRetainedSeq).toBe(0);
716
+ });
717
+ });
718
+ });