@terreno/api 58.0.0-beta.1 → 58.0.0-beta.3

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.
package/CHANGELOG.md CHANGED
@@ -20,6 +20,99 @@ Upgrade notes for consumer action live in [`mcp-server/src/docs/upgrades/`](mcp-
20
20
 
21
21
  Unreleased changes live in [`changelog/unreleased/`](changelog/unreleased/). Add one Markdown file per feature (see that directory's README) instead of editing this section.
22
22
 
23
+ ## [58.0.0-beta.3] - 2026-11-03
24
+
25
+ Upgrade note: [`mcp-server/src/docs/upgrades/58.0.0-beta.3.md`](mcp-server/src/docs/upgrades/58.0.0-beta.3.md).
26
+
27
+ ### Breaking
28
+
29
+ - Terreno 58 targets Expo SDK 58 (`~58.0.14`), React Native `0.88.0`, and React `19.3.0`. `@terreno/ui` peers `react-native` `0.88.0`. Native catalog moves with the SDK: `react-native-gesture-handler` `~3.3.0`, `react-native-reanimated` `4.7.1` + `react-native-worklets` `0.13.0`, `react-native-screens` `~4.30.0`, `react-native-webview` `14.0.1`, `@sentry/react-native` `~8.28.0`, `@shopify/flash-list` `2.3.2`, `@shopify/react-native-skia` `2.14.0`. Rebuild dev clients and store binaries.
30
+ - Expo Router 58: set `export const unstable_settings = {initialRouteName}` on the layout instead of passing `initialRouteName` to `<Slot>` / navigators. `SidebarNavigation` ignores the prop.
31
+ - Expo Router 58 static rendering: a custom `app/+html.tsx` must render `headNodes` and `bodyNodes` from `useServerDocumentContext()` (`expo-router/html`), or exported pages ship without their JavaScript. `example-frontend` is updated.
32
+ - React Native 0.88 generated types: type refs as `ViewInstance`, `TextInstance`, `ScrollViewInstance`, and `TextInputInstance` (`Box.scrollRef`, `TextField.inputRef`, `Text` `ref`).
33
+ - `create-terreno-app` scaffolds Expo `~58.0.14`, React Native `0.88.0`, and React `19.3.0`.
34
+ - The Terreno 58 native module baseline lands in `example-frontend` and `demo`: `@stripe/stripe-react-native` 0.81.0, `react-native-purchases` and `react-native-purchases-ui` 10.12.2, `expo-device`, `expo-crypto`, `expo-local-authentication`, `expo-system-ui`, and `expo-build-properties` (Android Kotlin 2.2.21 and `compileSdkVersion` 37 pins). Rebuild every dev client and store binary. `react-native-otp-verify` is left out because it does not support the New Architecture. The demo has a hidden **Native Modules** page that shows each module's version and whether the running binary links it. See the 58.0.0 upgrade note.
35
+ - `TerrenoApp` turns HTTP rate limiting on by default. Omitting `rateLimit` now mounts the limiter with the memory store (auth 20 / 15 min, api 600 / 15 min). Pass `rateLimit: false` to turn it off. On Cloud Run pass `rateLimit: {trustProxy: 1}` so unauthenticated traffic keys by client IP. See the 58.0.0 upgrade note.
36
+ - `@terreno/admin-frontend` no longer takes an RTK `api`. The `api` prop is removed from every admin component (`AdminProvider`, `AdminShellLayout`, `AdminHome`, `AdminModelList`, `AdminModelTable`, `AdminModelForm`, `AdminScreenRouter`, `ConfigurationScreen`, `DocumentStorageBrowser`, `ConsentHistory`, comms, jobs, org, consent, and announcement screens, and widget props), and admin hooks drop their `api` argument (`useAdminConfig(apiBase)`, `useAdminScripts(apiBase)`, `useAdminRoles(apiBase)`, `useConfigurationApi({basePath})`, `useDocumentStorageApi(basePath)`, `useConsentHistory(baseUrl)`, `useOrganizationsApi(basePath)`, `useCommsDashboardApi()`, `useJobsDashboardApi()`, and the `useAiObservability*Api()` hooks).
37
+ - `useAdminApi(api, routePath, modelName)` is removed. Use `useAdminModelApi(routePath, modelName)`, which keeps the same hook names and calls the same `/admin/{routePath}` URLs through the admin fetch client. `AdminApi`, `EndpointBuilder`, and admin `injectEndpoints` are gone; `@reduxjs/toolkit` and `react-redux` are no longer peers of admin-frontend.
38
+ - `AdminProvider` is now the required auth binding for every admin request, including ObjectId and API-only model CRUD. Cookie SPAs pass `credentials="same-origin"`; embedded apps pass `apiOrigin` and `getAuthHeaders`. Product screens that reuse admin components wrap them in `AdminProvider`. See the 58.0.0 upgrade guide.
39
+ - Removed the legacy RTK realtime path. Use `sync` on `modelRouter` with `@terreno/syncdb` for live collection updates. `RealtimeApp`, `SyncApp`, socket auth, `sync:delta`, and admin `admin:model.changed` events are unchanged. See the 58.0.0 upgrade note.
40
+ - `@terreno/api`: `modelRouter` no longer accepts `realtime` (now a TypeScript error), and the change stream no longer emits the `sync` websocket event. Removed `RealtimeConfig`, `RealtimeEvent`, `DocumentSubscription`, `QuerySubscription`, `registerRealtime`, `getRealtimeRegistry`, `findRegistryEntryByCollection`, `findRegistryEntryByRoutePath`, `updateRealtimeRegistryOptions`, `clearRealtimeRegistry`, `RealtimeRegistryEntry`, the query-subscription store (`addQuerySubscription`, `removeQuerySubscription`, `removeAllSocketQueries`, `getQuerySubscriptionsForCollection`, `computeQueryId`, `clearQueryStore`), and `MAX_MODEL_SUBSCRIPTIONS` / `MAX_DOCUMENT_SUBSCRIPTIONS` / `MAX_QUERY_SUBSCRIPTIONS`. Sockets no longer handle `subscribe:model`, `subscribe:document`, or `subscribe:query`.
41
+ - `@terreno/rtk`: removed `realtimeList`, `realtimeDocument`, `setRealtimeSocket`, `getRealtimeSocket`, `useSyncConnection`, and the `RealtimeEvent` type. The rest of `@terreno/rtk` (including `useSocketConnection` and `useRealtimeDebug`) is removed in the same release; see `remove-rtk.md`.
42
+ - Removed `@terreno/rtk` and every Redux dependency (`@reduxjs/toolkit`, `react-redux`, `redux-persist`, `@rtk-query/codegen-openapi`). `@terreno/rtk` is not published for 58. `@terreno/syncdb` is the only frontend data, request, and session layer. Follow `docs/how-to/migrate-rtk-to-syncdb.md`, which maps every removed export to its replacement, and the 58.0.0 upgrade note.
43
+ - Apps upgrading from `@terreno/rtk` must install `expo-constants` and `expo-network` themselves (rtk depended on them; `@terreno/syncdb` lists them as optional peers), plus the optional peers for the features they use: `better-auth`, `@better-auth/expo`, `@better-auth/passkey`, `@openfeature/web-sdk`, `@openfeature/react-sdk`, `@modelcontextprotocol/client`. See the upgrade note.
44
+ - `@terreno/syncdb` adds `@terreno/syncdb/api` (`createApiClient`, `ApiError`), request hooks in `@terreno/syncdb/react` (`ApiClientProvider`, `useApiQuery`, `useLazyApiQuery`, `useApiMutation`, `useSocketEvent`), `@terreno/syncdb/config` (`baseUrl`, `baseWebsocketsUrl`, `appHeaders`), `@terreno/syncdb/auth` (`createBetterAuthClient`, `SessionProvider`, `useSession`, `jwtAuthAdapter`, `useJwtAuth`, token-expiry helpers), `@terreno/syncdb/flags` (`useFeatureFlags`, `useTerrenoFeatureFlags` on the sync socket), `@terreno/syncdb/app` (`useUpgradeCheck`, `hasPermission`, `canOpenAdminPage`, `installDevConsoleLogger`, `useMCPTools`), and `@terreno/syncdb/buildNumber`.
45
+ - `terreno-syncdb-codegen --api-out` generates typed hooks for every non-synced OpenAPI operation (same names as the RTK codegen), replacing `@rtk-query/codegen-openapi`. `bun run sdk` writes `store/apiSdk.ts`.
46
+ - `@terreno/ui` `ConsentNavigator`, `AnnouncementNavigator`, `useConsentForms`, `useSubmitConsent`, `useAnnouncements`, and `useAcknowledgeAnnouncement` take a request `client` instead of an RTK `api`.
47
+ - `GptHistory` (`gpt/histories`) is a synced collection and keeps its ObjectId `_id` (no migration). `McpServiceToken` (`mcp/service-tokens`, read-only) is a synced collection with String ids; run `mcpServiceTokenStringIdsMigration` (`@terreno/api`) before deploying 58 frontends.
48
+ - `create-terreno-app`, the `terreno_bootstrap` prompt, and the `terreno_generate_screen` tool scaffold apps without Redux or `@terreno/rtk`. The terreno-mcp-local `get_rtk_state` tool, the MCP resource `terreno://docs/rtk`, and `terreno state --slice rtk` are removed; use `get_syncdb_state` and `terreno state`.
49
+
50
+ ### Added
51
+
52
+ - `DataTable` columns size themselves when `width` is omitted. Each auto column starts at the wider of its header and its content (sampled from at most 50 rows, measured with a canvas on web and estimated on native), clamped to 80–360px, and auto columns grow to fill the table's container. Columns that set `width` keep it. `DataTableColumn.width` is now optional.
53
+ - `@terreno/syncdb` `createSyncDb({idFormats})` mints 24-hex ObjectIds for a collection set to `"objectId"`, so a model that keeps Mongoose's default ObjectId `_id` can sync without migrating its ids. `mutate()` throws on an explicit non-hex id for such a collection. `generateObjectId` and the `SyncIdFormat` type are exported.
54
+ - Sync `validation` nacks carry an optional `reason`: `invalid_id` when an ObjectId-keyed collection gets a non-hex id (rejected before the mutation is claimed), and `id_collision` when a create names an `_id` another document holds. A collision never touches the existing document and its message never names the holder. The ledger records the reason (`SyncMutation.nackReason`) so a redelivery replays it.
55
+ - `GET /sync/entities` leaves out non-hex ids for an ObjectId-keyed model instead of answering 400, so a rejected create queued for repair cannot fail the rest of the repair batch.
56
+
57
+ ### Changed
58
+
59
+ - The repository's agent rules now generate with rulesync 17 (up from 9). The root rule `.rulesync/rules/00-root.md` now generates `AGENTS.md`, which Devin and other AGENTS.md readers load, in place of `.devin/rules/00-root.md`. Never edit `AGENTS.md` by hand: edit the root rule and run `bun run rules`. The examples that existed only in the old hand-edited `AGENTS.md` (syncdb and RTK SDK usage) moved into the root rule, so `CLAUDE.md`, the Cursor root rule, and Copilot instructions get them too. Links in the root rule now resolve from the repository root. Generated Copilot hooks use the portable `command` field. Generated Copilot subagents no longer list `agent/runSubagent` as their only tool, so they get every default tool. Generated skills carry their `license`, `disable-model-invocation`, and Devin `triggers` frontmatter.
60
+ - `@terreno/syncdb/auth` `SessionProvider`: `logout()` no longer clears the session before the server answers. The session stays in the state until `authClient.signOut()` finishes (`signOutTimeoutMs`, default 10 seconds), and then it is cleared. Meanwhile the new `isSigningOut` state (`useSession().isSigningOut`) is true; `isLoading` is left alone, so a navigator gated on it keeps its screen. Before, a login screen that opened at once could find the still-live session and sign the user straight back in. A sign-out that fails or times out checks the session first. A session that is still live, or a cookie or native session the server cannot be asked about, stays signed in, and `error` is set to `SIGN_OUT_FAILED_MESSAGE` ("Couldn't sign out. Check your connection and try again."). A web bearer client, which drops its token before the request leaves, ends signed out. The global `auth/logout` action (a refused session) now ends signed out even when the sign-out request fails. With `apisToReset` (57.17.0), `logout()` purges the cache when the session clears, not when it is dispatched: a purge at dispatch refetched every mounted screen mid-sign-out, and a refetch that could not reach the server answered 401 and signed the user out even though the sign-out failed. A failed sign-out keeps both the session and the cache. The global `auth/logout` action still purges at once (only the first of several in flight) and again when the session clears. A sign-in for another user that lands while a sign-out is in flight is kept; a sign-out that started signed out asks `getSession` first, so a restore of the session it revoked is cleared. Show `selectBetterAuthIsSigningOut` on the sign-out control and `selectBetterAuthError` after a failed sign-out.
61
+
62
+ ### Removed
63
+
64
+ - `@terreno/ui` no longer exports the `Filter` and `FilterProps` aliases deprecated in 57.7.0. Import `DropdownPanel` and `DropdownPanelProps` instead. `FilterSelectMenu`, `FilterBoolean`, `FilterAccordion`, and `FilterChangesBadge` keep their names.
65
+
66
+ ### Fixed
67
+
68
+ - `@terreno/syncdb`: logging out while `syncDb.start()` is still running no longer loses local writes or logs errors. `start()` now resolves the web encryption key from `GET /sync/key` before it loads the store, so the flush in `stop()` never needs the network after the session has ended. A `stop()` or `signOut()` call now cancels a `start()` that is running or queued ahead of it, so the transport never connects without a session. A failed key fetch is now retried on the next save instead of failing every save for the rest of the session.
69
+
70
+ ## [58.0.0-beta.2] - 2026-11-03
71
+
72
+ Upgrade note: [`mcp-server/src/docs/upgrades/58.0.0-beta.2.md`](mcp-server/src/docs/upgrades/58.0.0-beta.2.md).
73
+
74
+ ### Breaking
75
+
76
+ - Terreno 58 targets Expo SDK 58 (`~58.0.14`), React Native `0.88.0`, and React `19.3.0`. `@terreno/ui` peers `react-native` `0.88.0`. Native catalog moves with the SDK: `react-native-gesture-handler` `~3.3.0`, `react-native-reanimated` `4.7.1` + `react-native-worklets` `0.13.0`, `react-native-screens` `~4.30.0`, `react-native-webview` `14.0.1`, `@sentry/react-native` `~8.28.0`, `@shopify/flash-list` `2.3.2`, `@shopify/react-native-skia` `2.14.0`. Rebuild dev clients and store binaries.
77
+ - Expo Router 58: set `export const unstable_settings = {initialRouteName}` on the layout instead of passing `initialRouteName` to `<Slot>` / navigators. `SidebarNavigation` ignores the prop.
78
+ - Expo Router 58 static rendering: a custom `app/+html.tsx` must render `headNodes` and `bodyNodes` from `useServerDocumentContext()` (`expo-router/html`), or exported pages ship without their JavaScript. `example-frontend` is updated.
79
+ - React Native 0.88 generated types: type refs as `ViewInstance`, `TextInstance`, `ScrollViewInstance`, and `TextInputInstance` (`Box.scrollRef`, `TextField.inputRef`, `Text` `ref`).
80
+ - `create-terreno-app` scaffolds Expo `~58.0.14`, React Native `0.88.0`, and React `19.3.0`.
81
+ - The Terreno 58 native module baseline lands in `example-frontend` and `demo`: `@stripe/stripe-react-native` 0.81.0, `react-native-purchases` and `react-native-purchases-ui` 10.12.2, `expo-device`, `expo-crypto`, `expo-local-authentication`, `expo-system-ui`, and `expo-build-properties` (Android Kotlin 2.2.21 and `compileSdkVersion` 37 pins). Rebuild every dev client and store binary. `react-native-otp-verify` is left out because it does not support the New Architecture. The demo has a hidden **Native Modules** page that shows each module's version and whether the running binary links it. See the 58.0.0 upgrade note.
82
+ - `TerrenoApp` turns HTTP rate limiting on by default. Omitting `rateLimit` now mounts the limiter with the memory store (auth 20 / 15 min, api 600 / 15 min). Pass `rateLimit: false` to turn it off. On Cloud Run pass `rateLimit: {trustProxy: 1}` so unauthenticated traffic keys by client IP. See the 58.0.0 upgrade note.
83
+ - `@terreno/admin-frontend` no longer takes an RTK `api`. The `api` prop is removed from every admin component (`AdminProvider`, `AdminShellLayout`, `AdminHome`, `AdminModelList`, `AdminModelTable`, `AdminModelForm`, `AdminScreenRouter`, `ConfigurationScreen`, `DocumentStorageBrowser`, `ConsentHistory`, comms, jobs, org, consent, and announcement screens, and widget props), and admin hooks drop their `api` argument (`useAdminConfig(apiBase)`, `useAdminScripts(apiBase)`, `useAdminRoles(apiBase)`, `useConfigurationApi({basePath})`, `useDocumentStorageApi(basePath)`, `useConsentHistory(baseUrl)`, `useOrganizationsApi(basePath)`, `useCommsDashboardApi()`, `useJobsDashboardApi()`, and the `useAiObservability*Api()` hooks).
84
+ - `useAdminApi(api, routePath, modelName)` is removed. Use `useAdminModelApi(routePath, modelName)`, which keeps the same hook names and calls the same `/admin/{routePath}` URLs through the admin fetch client. `AdminApi`, `EndpointBuilder`, and admin `injectEndpoints` are gone; `@reduxjs/toolkit` and `react-redux` are no longer peers of admin-frontend.
85
+ - `AdminProvider` is now the required auth binding for every admin request, including ObjectId and API-only model CRUD. Cookie SPAs pass `credentials="same-origin"`; embedded apps pass `apiOrigin` and `getAuthHeaders`. Product screens that reuse admin components wrap them in `AdminProvider`. See the 58.0.0 upgrade guide.
86
+ - Removed the legacy RTK realtime path. Use `sync` on `modelRouter` with `@terreno/syncdb` for live collection updates. `RealtimeApp`, `SyncApp`, socket auth, `sync:delta`, and admin `admin:model.changed` events are unchanged. See the 58.0.0 upgrade note.
87
+ - `@terreno/api`: `modelRouter` no longer accepts `realtime` (now a TypeScript error), and the change stream no longer emits the `sync` websocket event. Removed `RealtimeConfig`, `RealtimeEvent`, `DocumentSubscription`, `QuerySubscription`, `registerRealtime`, `getRealtimeRegistry`, `findRegistryEntryByCollection`, `findRegistryEntryByRoutePath`, `updateRealtimeRegistryOptions`, `clearRealtimeRegistry`, `RealtimeRegistryEntry`, the query-subscription store (`addQuerySubscription`, `removeQuerySubscription`, `removeAllSocketQueries`, `getQuerySubscriptionsForCollection`, `computeQueryId`, `clearQueryStore`), and `MAX_MODEL_SUBSCRIPTIONS` / `MAX_DOCUMENT_SUBSCRIPTIONS` / `MAX_QUERY_SUBSCRIPTIONS`. Sockets no longer handle `subscribe:model`, `subscribe:document`, or `subscribe:query`.
88
+ - `@terreno/rtk`: removed `realtimeList`, `realtimeDocument`, `setRealtimeSocket`, `getRealtimeSocket`, `useSyncConnection`, and the `RealtimeEvent` type. The rest of `@terreno/rtk` (including `useSocketConnection` and `useRealtimeDebug`) is removed in the same release; see `remove-rtk.md`.
89
+ - Removed `@terreno/rtk` and every Redux dependency (`@reduxjs/toolkit`, `react-redux`, `redux-persist`, `@rtk-query/codegen-openapi`). `@terreno/rtk` is not published for 58. `@terreno/syncdb` is the only frontend data, request, and session layer. Follow `docs/how-to/migrate-rtk-to-syncdb.md`, which maps every removed export to its replacement, and the 58.0.0 upgrade note.
90
+ - `@terreno/syncdb` adds `@terreno/syncdb/api` (`createApiClient`, `ApiError`), request hooks in `@terreno/syncdb/react` (`ApiClientProvider`, `useApiQuery`, `useLazyApiQuery`, `useApiMutation`, `useSocketEvent`), `@terreno/syncdb/config` (`baseUrl`, `baseWebsocketsUrl`, `appHeaders`), `@terreno/syncdb/auth` (`createBetterAuthClient`, `SessionProvider`, `useSession`, `jwtAuthAdapter`, `useJwtAuth`, token-expiry helpers), `@terreno/syncdb/flags` (`useFeatureFlags`, `useTerrenoFeatureFlags` on the sync socket), `@terreno/syncdb/app` (`useUpgradeCheck`, `hasPermission`, `canOpenAdminPage`, `installDevConsoleLogger`, `useMCPTools`), and `@terreno/syncdb/buildNumber`.
91
+ - `terreno-syncdb-codegen --api-out` generates typed hooks for every non-synced OpenAPI operation (same names as the RTK codegen), replacing `@rtk-query/codegen-openapi`. `bun run sdk` writes `store/apiSdk.ts`.
92
+ - `@terreno/ui` `ConsentNavigator`, `AnnouncementNavigator`, `useConsentForms`, `useSubmitConsent`, `useAnnouncements`, and `useAcknowledgeAnnouncement` take a request `client` instead of an RTK `api`.
93
+ - `GptHistory` (`gpt/histories`) is a synced collection and keeps its ObjectId `_id` (no migration). `McpServiceToken` (`mcp/service-tokens`, read-only) is a synced collection with String ids; run `mcpServiceTokenStringIdsMigration` (`@terreno/api`) before deploying 58 frontends.
94
+ - `create-terreno-app`, the `terreno_bootstrap` prompt, and the `terreno_generate_screen` tool scaffold apps without Redux or `@terreno/rtk`. The terreno-mcp-local `get_rtk_state` tool, the MCP resource `terreno://docs/rtk`, and `terreno state --slice rtk` are removed; use `get_syncdb_state` and `terreno state`.
95
+
96
+ ### Added
97
+
98
+ - `DataTable` columns size themselves when `width` is omitted. Each auto column starts at the wider of its header and its content (sampled from at most 50 rows, measured with a canvas on web and estimated on native), clamped to 80–360px, and auto columns grow to fill the table's container. Columns that set `width` keep it. `DataTableColumn.width` is now optional.
99
+ - `@terreno/syncdb` `createSyncDb({idFormats})` mints 24-hex ObjectIds for a collection set to `"objectId"`, so a model that keeps Mongoose's default ObjectId `_id` can sync without migrating its ids. `mutate()` throws on an explicit non-hex id for such a collection. `generateObjectId` and the `SyncIdFormat` type are exported.
100
+ - Sync `validation` nacks carry an optional `reason`: `invalid_id` when an ObjectId-keyed collection gets a non-hex id (rejected before the mutation is claimed), and `id_collision` when a create names an `_id` another document holds. A collision never touches the existing document and its message never names the holder. The ledger records the reason (`SyncMutation.nackReason`) so a redelivery replays it.
101
+ - `GET /sync/entities` leaves out non-hex ids for an ObjectId-keyed model instead of answering 400, so a rejected create queued for repair cannot fail the rest of the repair batch.
102
+
103
+ ### Changed
104
+
105
+ - The repository's agent rules now generate with rulesync 17 (up from 9). The root rule `.rulesync/rules/00-root.md` now generates `AGENTS.md`, which Devin and other AGENTS.md readers load, in place of `.devin/rules/00-root.md`. Never edit `AGENTS.md` by hand: edit the root rule and run `bun run rules`. The examples that existed only in the old hand-edited `AGENTS.md` (syncdb and RTK SDK usage) moved into the root rule, so `CLAUDE.md`, the Cursor root rule, and Copilot instructions get them too. Links in the root rule now resolve from the repository root. Generated Copilot hooks use the portable `command` field. Generated Copilot subagents no longer list `agent/runSubagent` as their only tool, so they get every default tool. Generated skills carry their `license`, `disable-model-invocation`, and Devin `triggers` frontmatter.
106
+ - `@terreno/syncdb/auth` `SessionProvider`: `logout()` no longer clears the session before the server answers. The session stays in the state until `authClient.signOut()` finishes (`signOutTimeoutMs`, default 10 seconds), and then it is cleared. Meanwhile the new `isSigningOut` state (`useSession().isSigningOut`) is true; `isLoading` is left alone, so a navigator gated on it keeps its screen. Before, a login screen that opened at once could find the still-live session and sign the user straight back in. A sign-out that fails or times out checks the session first. A session that is still live, or a cookie or native session the server cannot be asked about, stays signed in, and `error` is set to `SIGN_OUT_FAILED_MESSAGE` ("Couldn't sign out. Check your connection and try again."). A web bearer client, which drops its token before the request leaves, ends signed out. The global `auth/logout` action (a refused session) now ends signed out even when the sign-out request fails. With `apisToReset` (57.17.0), `logout()` purges the cache when the session clears, not when it is dispatched: a purge at dispatch refetched every mounted screen mid-sign-out, and a refetch that could not reach the server answered 401 and signed the user out even though the sign-out failed. A failed sign-out keeps both the session and the cache. The global `auth/logout` action still purges at once (only the first of several in flight) and again when the session clears. A sign-in for another user that lands while a sign-out is in flight is kept; a sign-out that started signed out asks `getSession` first, so a restore of the session it revoked is cleared. Show `selectBetterAuthIsSigningOut` on the sign-out control and `selectBetterAuthError` after a failed sign-out.
107
+
108
+ ### Removed
109
+
110
+ - `@terreno/ui` no longer exports the `Filter` and `FilterProps` aliases deprecated in 57.7.0. Import `DropdownPanel` and `DropdownPanelProps` instead. `FilterSelectMenu`, `FilterBoolean`, `FilterAccordion`, and `FilterChangesBadge` keep their names.
111
+
112
+ ### Fixed
113
+
114
+ - `@terreno/syncdb`: logging out while `syncDb.start()` is still running no longer loses local writes or logs errors. `start()` now resolves the web encryption key from `GET /sync/key` before it loads the store, so the flush in `stop()` never needs the network after the session has ended. A `stop()` or `signOut()` call now cancels a `start()` that is running or queued ahead of it, so the transport never connects without a session. A failed key fetch is now retried on the next save instead of failing every save for the rest of the session.
115
+
23
116
  ## [58.0.0-beta.1] - 2026-11-02
24
117
 
25
118
  Upgrade note: [`mcp-server/src/docs/upgrades/58.0.0-beta.1.md`](mcp-server/src/docs/upgrades/58.0.0-beta.1.md).
@@ -0,0 +1,14 @@
1
+ import type mongoose from "mongoose";
2
+ /**
3
+ * True for a 24-character hex string. Stricter than `mongoose.isValidObjectId`, which also
4
+ * accepts any 12-character string as raw ObjectId bytes.
5
+ */
6
+ export declare const isObjectIdHex: (id: unknown) => id is string;
7
+ /**
8
+ * True when the model keys documents by ObjectId. Synced ObjectId models take client-minted
9
+ * ObjectId hex ids (syncdb `idFormats: {collection: "objectId"}`); String-keyed models take
10
+ * any id shape (syncdb's UUID default).
11
+ */
12
+ export declare const isObjectIdKeyed: (model: {
13
+ schema?: mongoose.Schema;
14
+ }) => boolean;
@@ -0,0 +1,17 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.isObjectIdKeyed = exports.isObjectIdHex = void 0;
4
+ const OBJECT_ID_HEX = /^[0-9a-fA-F]{24}$/;
5
+ /**
6
+ * True for a 24-character hex string. Stricter than `mongoose.isValidObjectId`, which also
7
+ * accepts any 12-character string as raw ObjectId bytes.
8
+ */
9
+ const isObjectIdHex = (id) => typeof id === "string" && OBJECT_ID_HEX.test(id);
10
+ exports.isObjectIdHex = isObjectIdHex;
11
+ /**
12
+ * True when the model keys documents by ObjectId. Synced ObjectId models take client-minted
13
+ * ObjectId hex ids (syncdb `idFormats: {collection: "objectId"}`); String-keyed models take
14
+ * any id shape (syncdb's UUID default).
15
+ */
16
+ const isObjectIdKeyed = (model) => model.schema?.path("_id")?.instance === "ObjectId";
17
+ exports.isObjectIdKeyed = isObjectIdKeyed;
@@ -169,6 +169,7 @@ export interface SyncMutationDocument {
169
169
  collectionTag?: string;
170
170
  status: SyncMutationStatus;
171
171
  nackCode?: string;
172
+ nackReason?: string;
172
173
  resultId?: string;
173
174
  resultSeq?: number;
174
175
  error?: string;
@@ -362,6 +362,10 @@ const syncMutationSchema = new mongoose_1.Schema({
362
362
  description: "Nack code recorded for rejected mutations (conflict/unauthorized/validation/error)",
363
363
  type: String,
364
364
  },
365
+ nackReason: {
366
+ description: "Why a validation nack rejected the mutation's entity id (id_collision/invalid_id)",
367
+ type: String,
368
+ },
365
369
  resultId: {
366
370
  description: "The affected document id, recorded when the mutation is applied or conflicts; a " +
367
371
  "duplicate delivery of a conflict re-serializes the live document from this id",
@@ -13,6 +13,7 @@ const permissions_1 = require("../permissions");
13
13
  const plugins_1 = require("../plugins");
14
14
  const adminBroadcastScope_1 = require("./adminBroadcastScope");
15
15
  const adminWindowMutation_1 = require("./adminWindowMutation");
16
+ const entityIds_1 = require("./entityIds");
16
17
  const executors_1 = require("./executors");
17
18
  const models_1 = require("./models");
18
19
  const registry_1 = require("./registry");
@@ -191,6 +192,7 @@ const outcomeFromLedgerRow = async ({ entry, mutation, request, row, scopeResolv
191
192
  code: row.nackCode ?? "error",
192
193
  message: row.error,
193
194
  mutationId: row.mutationId,
195
+ ...(row.nackReason ? { reason: row.nackReason } : {}),
194
196
  });
195
197
  }
196
198
  return undefined;
@@ -281,6 +283,21 @@ const isE11000Error = (error) => {
281
283
  const wrapped = candidate?.error;
282
284
  return wrapped?.code === 11000;
283
285
  };
286
+ /** The `APIError.code` a create gets when its client-minted `_id` already exists. */
287
+ const ID_COLLISION_CODE = "sync-id-collision";
288
+ /**
289
+ * True when an E11000 (raw, or wrapped by the executor) is on the `_id` index rather than
290
+ * some other unique index the model declares.
291
+ */
292
+ const isIdDuplicateKeyError = (error) => {
293
+ if (!isE11000Error(error)) {
294
+ return false;
295
+ }
296
+ const candidate = error;
297
+ const raw = [candidate, candidate.error, candidate.cause].find((value) => value?.code === 11000);
298
+ const keys = Object.keys(raw?.keyPattern ?? raw?.keyValue ?? {});
299
+ return keys.length === 1 && keys[0] === "_id";
300
+ };
284
301
  /**
285
302
  * C5 (FIX 6): true when every key/value in `data` (the mutation's own
286
303
  * intended write) is already present on `doc` — used alongside the
@@ -364,6 +381,7 @@ const finalizeNack = async ({ claimedId, entry, error, mutation, request, }) =>
364
381
  }
365
382
  const code = nackCodeForError(error);
366
383
  const message = (0, errors_1.isAPIError)(error) ? error.title : String(error);
384
+ const reason = (0, errors_1.isAPIError)(error) && error.code === ID_COLLISION_CODE ? "id_collision" : undefined;
367
385
  if (code === "error") {
368
386
  logger_1.logger.warn("[sync] Mutation failed unexpectedly", {
369
387
  collection: mutation.collection,
@@ -380,8 +398,15 @@ const finalizeNack = async ({ claimedId, entry, error, mutation, request, }) =>
380
398
  await models_1.SyncMutation.deleteOne({ _id: claimedId });
381
399
  return makeNack({ code, message, mutationId: mutation.mutationId });
382
400
  }
383
- await models_1.SyncMutation.updateOne({ _id: claimedId }, { $set: { error: message, nackCode: code, status: "failed" } });
384
- return makeNack({ code, message, mutationId: mutation.mutationId });
401
+ await models_1.SyncMutation.updateOne({ _id: claimedId }, {
402
+ $set: {
403
+ error: message,
404
+ nackCode: code,
405
+ status: "failed",
406
+ ...(reason ? { nackReason: reason } : {}),
407
+ },
408
+ });
409
+ return makeNack({ code, message, mutationId: mutation.mutationId, ...(reason ? { reason } : {}) });
385
410
  };
386
411
  /**
387
412
  * C5 (FIX 6): read the doc back and report it as the ack for an ALREADY-APPLIED write —
@@ -541,6 +566,18 @@ const applyClaimedMutationInContext = async ({ claimed, entry, mutation, request
541
566
  return { ack: { id: resultId, mutationId, seq: resultSeq }, type: "ack" };
542
567
  }
543
568
  }
569
+ // Another document already holds the client-minted `_id`. The unique index kept it
570
+ // from being overwritten; reject the create for good (validation is terminal on the
571
+ // client) without naming the holder, which may belong to another user.
572
+ if (isIdDuplicateKeyError(createError)) {
573
+ throw new errors_1.APIError({
574
+ cause: createError,
575
+ code: ID_COLLISION_CODE,
576
+ disableExternalErrorTracking: true,
577
+ status: 400,
578
+ title: "Entity id already exists",
579
+ });
580
+ }
544
581
  throw createError;
545
582
  }
546
583
  }
@@ -688,6 +725,18 @@ const applySyncMutation = async ({ user, mutation, req, scopeResolver, syncOptio
688
725
  if (!entry) {
689
726
  return validationNack(`Unknown sync collection: ${mutation.collection}`);
690
727
  }
728
+ // An ObjectId-keyed collection can only hold 24-hex ids. Rejecting anything else here
729
+ // keeps a client-minted UUID from reaching Mongoose as a CastError, which would nack as a
730
+ // retryable `error` and replay forever.
731
+ const model = mongoose_1.default.models[entry.modelName];
732
+ if (mutation.id && model && (0, entityIds_1.isObjectIdKeyed)(model) && !(0, entityIds_1.isObjectIdHex)(mutation.id)) {
733
+ return makeNack({
734
+ code: "validation",
735
+ message: `${mutation.collection} ids must be 24-character hex ObjectIds`,
736
+ mutationId,
737
+ reason: "invalid_id",
738
+ });
739
+ }
691
740
  const request = req ?? { user };
692
741
  // Atomic claim: inserting the pending row first means exactly one delivery applies.
693
742
  let claimed;
@@ -14,6 +14,7 @@ const permissions_1 = require("../permissions");
14
14
  const plugins_1 = require("../plugins");
15
15
  const adminBroadcastScope_1 = require("./adminBroadcastScope");
16
16
  const adminWindowAccess_1 = require("./adminWindowAccess");
17
+ const entityIds_1 = require("./entityIds");
17
18
  const models_1 = require("./models");
18
19
  const registry_1 = require("./registry");
19
20
  const serialize_1 = require("./serialize");
@@ -162,18 +163,17 @@ const parseNonNegativeInt = (raw, name, fallback) => {
162
163
  };
163
164
  /**
164
165
  * Task 9.14: the legacy cursor is a raw `_id` string, so it must be compared in the
165
- * model's OWN `_id` BSON type. Synced models are designed around client-minted string
166
+ * model's OWN `_id` BSON type. Synced models default to client-minted string
166
167
  * `_id`s: casting those to `ObjectId` either throws (non-hex ids) or — worse — silently
167
168
  * compares across BSON types and matches nothing, so the legacy stratum reported itself
168
169
  * exhausted after one page and the remaining documents were never bootstrapped.
169
170
  * Only ObjectId-keyed models get the cast; a malformed cursor for one is a 400, not a 500.
170
171
  */
171
172
  const legacyCursorClause = ({ model, legacyCursorIn, }) => {
172
- const idInstance = model.schema?.path("_id")?.instance;
173
- if (idInstance !== "ObjectId") {
173
+ if (!(0, entityIds_1.isObjectIdKeyed)(model)) {
174
174
  return { _id: { $gt: legacyCursorIn } };
175
175
  }
176
- if (!mongoose_1.default.isValidObjectId(legacyCursorIn)) {
176
+ if (!(0, entityIds_1.isObjectIdHex)(legacyCursorIn)) {
177
177
  throw new errors_1.APIError({ status: 400, title: `Invalid legacyCursor: ${legacyCursorIn}` });
178
178
  }
179
179
  return { _id: { $gt: new mongoose_1.default.Types.ObjectId(legacyCursorIn) } };
@@ -322,23 +322,18 @@ const pageSeqStratum = async ({ model, scopeFilter, cursor, limit, frontierSeq,
322
322
  exports.MAX_ENTITY_FETCH = 100;
323
323
  /**
324
324
  * Task 9.27: `_id: {$in: ids}` leaves the cast to Mongoose, so one non-hex id against an
325
- * ObjectId-keyed model threw a CastError that surfaced as a 500 for what is purely bad
326
- * caller input. Validate up front and name the offending ids in a 400. Models with
327
- * client-minted string `_id`s (the syncdb default, see `legacyCursorClause`) take any shape.
325
+ * ObjectId-keyed model threw a CastError that surfaced as a 500. A non-hex id cannot name a
326
+ * document of such a model, so it is dropped and comes back absent, which is the true answer.
327
+ * Failing the whole request instead would wedge a client's repair batch: a create the server
328
+ * rejected for a bad id is queued for repair under that id, and every other id in the batch
329
+ * would never load. Models with client-minted string `_id`s (see `legacyCursorClause`) take
330
+ * any shape.
328
331
  */
329
332
  const castEntityIds = ({ model, ids, }) => {
330
- const idInstance = model.schema?.path("_id")?.instance;
331
- if (idInstance !== "ObjectId") {
333
+ if (!(0, entityIds_1.isObjectIdKeyed)(model)) {
332
334
  return ids;
333
335
  }
334
- const invalid = ids.filter((id) => !mongoose_1.default.isValidObjectId(id));
335
- if (invalid.length > 0) {
336
- throw new errors_1.APIError({
337
- status: 400,
338
- title: `Invalid ids for ${model.modelName}: ${invalid.join(",")}`,
339
- });
340
- }
341
- return ids.map((id) => new mongoose_1.default.Types.ObjectId(id));
336
+ return ids.filter(entityIds_1.isObjectIdHex).map((id) => new mongoose_1.default.Types.ObjectId(id));
342
337
  };
343
338
  /**
344
339
  * Serve one snapshot page for one stream: membership/permission checks, frontier and
@@ -178,6 +178,12 @@ export interface SyncAck {
178
178
  warning?: string;
179
179
  }
180
180
  export type SyncNackCode = "conflict" | "unauthorized" | "validation" | "error" | "rate_limited";
181
+ /**
182
+ * Why a `validation` nack rejected a mutation, when the cause is the entity id itself.
183
+ * `id_collision`: a create named an `_id` that already exists. `invalid_id`: the id is not a
184
+ * 24-character hex ObjectId for an ObjectId-keyed collection.
185
+ */
186
+ export type SyncNackReason = "id_collision" | "invalid_id";
181
187
  /** Rejected mutation. Conflict nacks carry the canonical server document. */
182
188
  export interface SyncNack {
183
189
  mutationId: string;
@@ -187,6 +193,8 @@ export interface SyncNack {
187
193
  /** The server document's current `_syncSeq` (conflict nacks). */
188
194
  serverSeq?: number;
189
195
  message?: string;
196
+ /** Set on `validation` nacks caused by the entity id (see {@link SyncNackReason}). */
197
+ reason?: SyncNackReason;
190
198
  /**
191
199
  * Minimum time (ms) the client should wait before retrying, filled by the
192
200
  * server with the remaining rate-limit window (`rate_limited` nacks only).
package/package.json CHANGED
@@ -13,7 +13,7 @@
13
13
  "@modelcontextprotocol/node": "^2.0.0",
14
14
  "@modelcontextprotocol/server": "^2.0.0",
15
15
  "@sentry/bun": "^11.0.0",
16
- "@terreno/test": "58.0.0-beta.1",
16
+ "@terreno/test": "58.0.0-beta.3",
17
17
  "@thream/socketio-jwt": "^3.1.4",
18
18
  "@types/qs": "^6.14.0",
19
19
  "ajv": "8.20.0",
@@ -51,7 +51,7 @@
51
51
  "devDependencies": {
52
52
  "@biomejs/biome": "^2.3.6",
53
53
  "@modelcontextprotocol/client": "^2.0.0",
54
- "@terreno/syncdb": "58.0.0-beta.1",
54
+ "@terreno/syncdb": "58.0.0-beta.3",
55
55
  "@types/bun": "^1.4.0",
56
56
  "@types/cors": "^2.8.17",
57
57
  "@types/express": "^5.0.6",
@@ -86,6 +86,13 @@
86
86
  "types": "./dist/tests/openApiResponseSchema.d.ts"
87
87
  }
88
88
  },
89
+ "files": [
90
+ "LICENSE",
91
+ "CHANGELOG.md",
92
+ "dist/**/*",
93
+ "src/**/*",
94
+ ".ai/**/*"
95
+ ],
89
96
  "homepage": "https://github.com/TerrenoLabs/terreno#readme",
90
97
  "keywords": [
91
98
  "rest",
@@ -141,5 +148,5 @@
141
148
  "updateSnapshot": "bun test --update-snapshots"
142
149
  },
143
150
  "types": "dist/index.d.ts",
144
- "version": "58.0.0-beta.1"
151
+ "version": "58.0.0-beta.3"
145
152
  }
@@ -0,0 +1,18 @@
1
+ import type mongoose from "mongoose";
2
+
3
+ const OBJECT_ID_HEX = /^[0-9a-fA-F]{24}$/;
4
+
5
+ /**
6
+ * True for a 24-character hex string. Stricter than `mongoose.isValidObjectId`, which also
7
+ * accepts any 12-character string as raw ObjectId bytes.
8
+ */
9
+ export const isObjectIdHex = (id: unknown): id is string =>
10
+ typeof id === "string" && OBJECT_ID_HEX.test(id);
11
+
12
+ /**
13
+ * True when the model keys documents by ObjectId. Synced ObjectId models take client-minted
14
+ * ObjectId hex ids (syncdb `idFormats: {collection: "objectId"}`); String-keyed models take
15
+ * any id shape (syncdb's UUID default).
16
+ */
17
+ export const isObjectIdKeyed = (model: {schema?: mongoose.Schema}): boolean =>
18
+ (model.schema?.path("_id") as {instance?: string} | undefined)?.instance === "ObjectId";
@@ -440,6 +440,7 @@ export interface SyncMutationDocument {
440
440
  collectionTag?: string;
441
441
  status: SyncMutationStatus;
442
442
  nackCode?: string;
443
+ nackReason?: string;
443
444
  resultId?: string;
444
445
  resultSeq?: number;
445
446
  error?: string;
@@ -493,6 +494,11 @@ const syncMutationSchema = new Schema<SyncMutationDocument>(
493
494
  "Nack code recorded for rejected mutations (conflict/unauthorized/validation/error)",
494
495
  type: String,
495
496
  },
497
+ nackReason: {
498
+ description:
499
+ "Why a validation nack rejected the mutation's entity id (id_collision/invalid_id)",
500
+ type: String,
501
+ },
496
502
  resultId: {
497
503
  description:
498
504
  "The affected document id, recorded when the mutation is applied or conflicts; a " +
@@ -908,6 +908,90 @@ describe("applySyncMutation", () => {
908
908
  expect(nack.message).toContain("Unknown sync collection");
909
909
  });
910
910
 
911
+ it("nacks invalid_id for a non-hex id on an ObjectId-keyed collection, for every operation", async () => {
912
+ const doc = await MutStuffModel.create({name: "keyed", ownerId: owner.id});
913
+ const badIds = [crypto.randomUUID(), "abcdefghijkl", `${String(doc._id)}0`];
914
+ for (const [index, id] of badIds.entries()) {
915
+ for (const operation of ["create", "update", "delete"] as const) {
916
+ const mutationId = `m-bad-id-${operation}-${index}`;
917
+ const nack = expectNack(
918
+ await applySyncMutation({
919
+ mutation: {
920
+ baseVersion: 1,
921
+ collection: "mutStuff",
922
+ data: {name: "bad id", ownerId: owner.id},
923
+ id,
924
+ mutationId,
925
+ operation,
926
+ },
927
+ user: owner,
928
+ })
929
+ );
930
+ assert.equal(nack.code, "validation");
931
+ assert.equal(nack.reason, "invalid_id");
932
+ // Rejected before the claim: nothing to replay, nothing written.
933
+ assert.equal(await SyncMutation.countDocuments({mutationId}), 0);
934
+ }
935
+ }
936
+ assert.equal(await MutStuffModel.countDocuments({}), 1);
937
+ });
938
+
939
+ it("accepts any id shape on a String-keyed collection", async () => {
940
+ clearSyncRegistry();
941
+ registerSync({
942
+ config: {scope: {type: "owner"}},
943
+ model: MutOtherModel,
944
+ options: ownerOptions,
945
+ routePath: "/mutOther",
946
+ });
947
+ const id = crypto.randomUUID();
948
+ const ack = expectAck(
949
+ await applySyncMutation({
950
+ mutation: {
951
+ collection: "mutOther",
952
+ data: {name: "uuid", ownerId: owner.id},
953
+ id,
954
+ mutationId: "m-uuid-ok",
955
+ operation: "create",
956
+ },
957
+ user: owner,
958
+ })
959
+ );
960
+ assert.equal(ack.id, id);
961
+ await MutOtherModel.collection.deleteMany({});
962
+ });
963
+
964
+ it("nacks id_collision when a create names an _id another document holds", async () => {
965
+ const taken = await MutStuffModel.create({name: "theirs", ownerId: stranger.id});
966
+ const create = (): Promise<SyncMutationOutcome> =>
967
+ applySyncMutation({
968
+ mutation: {
969
+ collection: "mutStuff",
970
+ data: {name: "mine", ownerId: owner.id},
971
+ id: String(taken._id),
972
+ mutationId: "m-collision",
973
+ operation: "create",
974
+ },
975
+ user: owner,
976
+ });
977
+
978
+ const nack = expectNack(await create());
979
+ assert.equal(nack.code, "validation");
980
+ assert.equal(nack.reason, "id_collision");
981
+ assert.equal(nack.message, "Entity id already exists");
982
+ assert.notInclude(JSON.stringify(nack), stranger.id);
983
+ const stored = await MutStuffModel.findById(taken._id);
984
+ assert.equal(stored?.name, "theirs");
985
+ assert.equal(stored?.ownerId, stranger.id);
986
+
987
+ // A duplicate delivery replays the recorded nack, reason included.
988
+ const replayed = expectNack(await create());
989
+ assert.equal(replayed.reason, "id_collision");
990
+ const row = await SyncMutation.findOne({mutationId: "m-collision"});
991
+ assert.equal(row?.status, "failed");
992
+ assert.equal(row?.nackReason, "id_collision");
993
+ });
994
+
911
995
  it("nacks validation when an update omits baseVersion", async () => {
912
996
  const doc = await MutStuffModel.create({name: "no base", ownerId: owner.id});
913
997
  const nack = expectNack(
@@ -15,6 +15,7 @@ import {
15
15
  prepareAdminWindowMutation,
16
16
  withAdminWindowMutationRequestContext,
17
17
  } from "./adminWindowMutation";
18
+ import {isObjectIdHex, isObjectIdKeyed} from "./entityIds";
18
19
  import {
19
20
  executeCreate,
20
21
  executeDelete,
@@ -35,6 +36,7 @@ import type {
35
36
  SyncMutateRequest,
36
37
  SyncNack,
37
38
  SyncNackCode,
39
+ SyncNackReason,
38
40
  } from "./types";
39
41
 
40
42
  export type SyncMutationScopeResolver = (
@@ -314,6 +316,7 @@ const outcomeFromLedgerRow = async ({
314
316
  code: (row.nackCode as SyncNackCode) ?? "error",
315
317
  message: row.error,
316
318
  mutationId: row.mutationId,
319
+ ...(row.nackReason ? {reason: row.nackReason as SyncNackReason} : {}),
317
320
  });
318
321
  }
319
322
  return undefined;
@@ -431,6 +434,25 @@ const isE11000Error = (error: unknown): boolean => {
431
434
  return wrapped?.code === 11000;
432
435
  };
433
436
 
437
+ /** The `APIError.code` a create gets when its client-minted `_id` already exists. */
438
+ const ID_COLLISION_CODE = "sync-id-collision";
439
+
440
+ /**
441
+ * True when an E11000 (raw, or wrapped by the executor) is on the `_id` index rather than
442
+ * some other unique index the model declares.
443
+ */
444
+ const isIdDuplicateKeyError = (error: unknown): boolean => {
445
+ if (!isE11000Error(error)) {
446
+ return false;
447
+ }
448
+ const candidate = error as {cause?: unknown; error?: unknown; keyPattern?: unknown};
449
+ const raw = [candidate, candidate.error, candidate.cause].find(
450
+ (value) => (value as {code?: number} | undefined)?.code === 11000
451
+ ) as {keyPattern?: Record<string, unknown>; keyValue?: Record<string, unknown>} | undefined;
452
+ const keys = Object.keys(raw?.keyPattern ?? raw?.keyValue ?? {});
453
+ return keys.length === 1 && keys[0] === "_id";
454
+ };
455
+
434
456
  /**
435
457
  * C5 (FIX 6): true when every key/value in `data` (the mutation's own
436
458
  * intended write) is already present on `doc` — used alongside the
@@ -535,6 +557,8 @@ const finalizeNack = async ({
535
557
 
536
558
  const code = nackCodeForError(error);
537
559
  const message = isAPIError(error) ? error.title : String(error);
560
+ const reason: SyncNackReason | undefined =
561
+ isAPIError(error) && error.code === ID_COLLISION_CODE ? "id_collision" : undefined;
538
562
  if (code === "error") {
539
563
  logger.warn("[sync] Mutation failed unexpectedly", {
540
564
  collection: mutation.collection,
@@ -553,9 +577,16 @@ const finalizeNack = async ({
553
577
  }
554
578
  await SyncMutation.updateOne(
555
579
  {_id: claimedId},
556
- {$set: {error: message, nackCode: code, status: "failed"}}
580
+ {
581
+ $set: {
582
+ error: message,
583
+ nackCode: code,
584
+ status: "failed",
585
+ ...(reason ? {nackReason: reason} : {}),
586
+ },
587
+ }
557
588
  );
558
- return makeNack({code, message, mutationId: mutation.mutationId});
589
+ return makeNack({code, message, mutationId: mutation.mutationId, ...(reason ? {reason} : {})});
559
590
  };
560
591
 
561
592
  /**
@@ -777,6 +808,18 @@ const applyClaimedMutationInContext = async ({
777
808
  return {ack: {id: resultId, mutationId, seq: resultSeq}, type: "ack"};
778
809
  }
779
810
  }
811
+ // Another document already holds the client-minted `_id`. The unique index kept it
812
+ // from being overwritten; reject the create for good (validation is terminal on the
813
+ // client) without naming the holder, which may belong to another user.
814
+ if (isIdDuplicateKeyError(createError)) {
815
+ throw new APIError({
816
+ cause: createError,
817
+ code: ID_COLLISION_CODE,
818
+ disableExternalErrorTracking: true,
819
+ status: 400,
820
+ title: "Entity id already exists",
821
+ });
822
+ }
780
823
  throw createError;
781
824
  }
782
825
  } else if (effectiveMutation.operation === "update") {
@@ -946,6 +989,18 @@ export const applySyncMutation = async ({
946
989
  if (!entry) {
947
990
  return validationNack(`Unknown sync collection: ${mutation.collection}`);
948
991
  }
992
+ // An ObjectId-keyed collection can only hold 24-hex ids. Rejecting anything else here
993
+ // keeps a client-minted UUID from reaching Mongoose as a CastError, which would nack as a
994
+ // retryable `error` and replay forever.
995
+ const model = mongoose.models[entry.modelName];
996
+ if (mutation.id && model && isObjectIdKeyed(model) && !isObjectIdHex(mutation.id)) {
997
+ return makeNack({
998
+ code: "validation",
999
+ message: `${mutation.collection} ids must be 24-character hex ObjectIds`,
1000
+ mutationId,
1001
+ reason: "invalid_id",
1002
+ });
1003
+ }
949
1004
 
950
1005
  const request = req ?? ({user} as unknown as express.Request);
951
1006
 
@@ -13,6 +13,7 @@ import {
13
13
  resolveAdminBroadcastQueryFilter,
14
14
  } from "./adminBroadcastScope";
15
15
  import {canUseAdminBroadcastWindow} from "./adminWindowAccess";
16
+ import {isObjectIdHex, isObjectIdKeyed} from "./entityIds";
16
17
  import {
17
18
  computeStableFrontier,
18
19
  getCompactedThroughSeq,
@@ -256,7 +257,7 @@ const parseNonNegativeInt = (raw: unknown, name: string, fallback: number): numb
256
257
 
257
258
  /**
258
259
  * Task 9.14: the legacy cursor is a raw `_id` string, so it must be compared in the
259
- * model's OWN `_id` BSON type. Synced models are designed around client-minted string
260
+ * model's OWN `_id` BSON type. Synced models default to client-minted string
260
261
  * `_id`s: casting those to `ObjectId` either throws (non-hex ids) or — worse — silently
261
262
  * compares across BSON types and matches nothing, so the legacy stratum reported itself
262
263
  * exhausted after one page and the remaining documents were never bootstrapped.
@@ -269,11 +270,10 @@ const legacyCursorClause = ({
269
270
  model: SyncedModel;
270
271
  legacyCursorIn: string;
271
272
  }): Record<string, unknown> => {
272
- const idInstance = (model.schema?.path("_id") as {instance?: string} | undefined)?.instance;
273
- if (idInstance !== "ObjectId") {
273
+ if (!isObjectIdKeyed(model)) {
274
274
  return {_id: {$gt: legacyCursorIn}};
275
275
  }
276
- if (!mongoose.isValidObjectId(legacyCursorIn)) {
276
+ if (!isObjectIdHex(legacyCursorIn)) {
277
277
  throw new APIError({status: 400, title: `Invalid legacyCursor: ${legacyCursorIn}`});
278
278
  }
279
279
  return {_id: {$gt: new mongoose.Types.ObjectId(legacyCursorIn)}};
@@ -473,9 +473,12 @@ export const MAX_ENTITY_FETCH = 100;
473
473
 
474
474
  /**
475
475
  * Task 9.27: `_id: {$in: ids}` leaves the cast to Mongoose, so one non-hex id against an
476
- * ObjectId-keyed model threw a CastError that surfaced as a 500 for what is purely bad
477
- * caller input. Validate up front and name the offending ids in a 400. Models with
478
- * client-minted string `_id`s (the syncdb default, see `legacyCursorClause`) take any shape.
476
+ * ObjectId-keyed model threw a CastError that surfaced as a 500. A non-hex id cannot name a
477
+ * document of such a model, so it is dropped and comes back absent, which is the true answer.
478
+ * Failing the whole request instead would wedge a client's repair batch: a create the server
479
+ * rejected for a bad id is queued for repair under that id, and every other id in the batch
480
+ * would never load. Models with client-minted string `_id`s (see `legacyCursorClause`) take
481
+ * any shape.
479
482
  */
480
483
  const castEntityIds = ({
481
484
  model,
@@ -484,18 +487,10 @@ const castEntityIds = ({
484
487
  ids: string[];
485
488
  model: SyncedModel;
486
489
  }): (string | mongoose.Types.ObjectId)[] => {
487
- const idInstance = (model.schema?.path("_id") as {instance?: string} | undefined)?.instance;
488
- if (idInstance !== "ObjectId") {
490
+ if (!isObjectIdKeyed(model)) {
489
491
  return ids;
490
492
  }
491
- const invalid = ids.filter((id) => !mongoose.isValidObjectId(id));
492
- if (invalid.length > 0) {
493
- throw new APIError({
494
- status: 400,
495
- title: `Invalid ids for ${model.modelName}: ${invalid.join(",")}`,
496
- });
497
- }
498
- return ids.map((id) => new mongoose.Types.ObjectId(id));
493
+ return ids.filter(isObjectIdHex).map((id) => new mongoose.Types.ObjectId(id));
499
494
  };
500
495
 
501
496
  /**
@@ -1021,12 +1021,16 @@ describe("sync routes", () => {
1021
1021
  // Task 9.27(b): bad caller input on the repair-fetch endpoint used to come back as a 500
1022
1022
  // (CastError) or, worse, a truncated 200 the client read as "those entities are gone".
1023
1023
  describe("GET /sync/entities input validation (Task 9.27)", () => {
1024
- it("400s (not 500s) for ids that cannot be cast to the model's _id type", async () => {
1024
+ it("returns ids that cannot be cast to the model's _id type as absent (not a 500)", async () => {
1025
1025
  const doc = await RouteStuffModel.create({name: "real", ownerId: notAdminId});
1026
+ // A rejected client-minted UUID create is queued for repair under that id; it must not
1027
+ // fail the rest of the repair batch.
1026
1028
  const res = await agent
1027
- .get(`/sync/entities?collection=routeStuff&ids=${doc._id},not-an-object-id`)
1028
- .expect(400);
1029
- expect(res.body.title).toMatch(/not-an-object-id/);
1029
+ .get(
1030
+ `/sync/entities?collection=routeStuff&ids=${doc._id},not-an-object-id,${crypto.randomUUID()},abcdefghijkl`
1031
+ )
1032
+ .expect(200);
1033
+ expect(res.body.entities.map((e: SnapshotEntity) => e.id)).toEqual([String(doc._id)]);
1030
1034
  });
1031
1035
 
1032
1036
  it("400s instead of silently truncating an over-cap id list", async () => {
package/src/sync/types.ts CHANGED
@@ -199,6 +199,13 @@ export interface SyncAck {
199
199
 
200
200
  export type SyncNackCode = "conflict" | "unauthorized" | "validation" | "error" | "rate_limited";
201
201
 
202
+ /**
203
+ * Why a `validation` nack rejected a mutation, when the cause is the entity id itself.
204
+ * `id_collision`: a create named an `_id` that already exists. `invalid_id`: the id is not a
205
+ * 24-character hex ObjectId for an ObjectId-keyed collection.
206
+ */
207
+ export type SyncNackReason = "id_collision" | "invalid_id";
208
+
202
209
  /** Rejected mutation. Conflict nacks carry the canonical server document. */
203
210
  export interface SyncNack {
204
211
  mutationId: string;
@@ -208,6 +215,8 @@ export interface SyncNack {
208
215
  /** The server document's current `_syncSeq` (conflict nacks). */
209
216
  serverSeq?: number;
210
217
  message?: string;
218
+ /** Set on `validation` nacks caused by the entity id (see {@link SyncNackReason}). */
219
+ reason?: SyncNackReason;
211
220
  /**
212
221
  * Minimum time (ms) the client should wait before retrying, filled by the
213
222
  * server with the remaining rate-limit window (`rate_limited` nacks only).
package/biome.jsonc DELETED
@@ -1,22 +0,0 @@
1
- {
2
- "$schema": "./node_modules/@biomejs/biome/configuration_schema.json",
3
- "extends": ["../biome.jsonc"],
4
- "files": {
5
- "includes": [
6
- "package.json",
7
- "src/**/*.ts",
8
- "src/**/*.tsx",
9
- "e2e/**/*.ts",
10
- "!!src/populate.ts",
11
- "!!**/node_modules",
12
- "!!node_modules",
13
- "!!**/dist",
14
- "!!dist",
15
- "!!**/build",
16
- "!!build",
17
- "!!**/coverage",
18
- "!!coverage"
19
- ]
20
- },
21
- "root": true
22
- }
package/bunfig.toml DELETED
@@ -1,10 +0,0 @@
1
- [test]
2
- preload = ["./src/tests/testEnv.ts", "./src/tests/bunSetup.ts"]
3
- root = "./src"
4
- coverage = true
5
- coveragePathIgnorePatterns = ["dist/**", "**/*.test.ts", "**/*.isolated.ts", "**/isolated/**", "**/tests/**", "**/vendor/**", "../**"]
6
- # Enforced by scripts/check-coverage.ts; Bun parses this key but does not
7
- # fail the run when coverage is below threshold. See
8
- # https://github.com/oven-sh/bun/issues/7367 and https://github.com/oven-sh/bun/pull/27933.
9
- coverageThreshold = { line = 95, function = 95 }
10
-
package/bunfig.unit.toml DELETED
@@ -1,3 +0,0 @@
1
- [test]
2
- root = "./src"
3
- preload = []
package/e2e/smoke.ts DELETED
@@ -1,193 +0,0 @@
1
- /**
2
- * Real-process smoke for @terreno/api. Run `bun e2e/smoke.ts` after `bun run compile`.
3
- *
4
- * The smoke re-runs this file with `serve` as a child process: a minimal TerrenoApp built from
5
- * the compiled package with one modelRouter model, on a free port, against `smokeMongoUri()`.
6
- * The parent then checks over real HTTP that `/health` answers, a user can sign up, and that
7
- * user can create and list a document. Exits non-zero on the first failed check.
8
- */
9
- import {
10
- freePort,
11
- type SpawnedProcess,
12
- smokeMongoUri,
13
- spawnUntilReady,
14
- stopSmokeMongo,
15
- } from "@terreno/test";
16
- import type express from "express";
17
- import {DateTime} from "luxon";
18
- import type {Schema} from "mongoose";
19
-
20
- const SERVE_ARG = "serve";
21
-
22
- interface SmokeWidget {
23
- _id: string;
24
- name: string;
25
- ownerId: string;
26
- }
27
-
28
- /**
29
- * Child: the compiled API with auth, one owner-scoped model, and a health plugin. The API is
30
- * imported here, not at the top, so the parent process never loads it.
31
- */
32
- const serve = async (): Promise<void> => {
33
- const {createdUpdatedPlugin, logger, modelRouter, OwnerQueryFilter, Permissions, TerrenoApp} =
34
- await import("@terreno/api");
35
- const {default: mongoose} = await import("mongoose");
36
- const {default: passportLocalMongoose} = await import("passport-local-mongoose");
37
-
38
- const userSchema = new mongoose.Schema({
39
- admin: {default: false, description: "Whether the user is an admin", type: Boolean},
40
- email: {description: "Sign-in email", type: String},
41
- name: {description: "Display name", type: String},
42
- });
43
- userSchema.plugin(passportLocalMongoose as unknown as (schema: Schema, options: object) => void, {
44
- usernameCaseInsensitive: true,
45
- usernameField: "email",
46
- });
47
- userSchema.plugin(createdUpdatedPlugin);
48
- const User = mongoose.model("User", userSchema);
49
-
50
- const widgetSchema = new mongoose.Schema({
51
- name: {description: "Widget name", required: true, type: String},
52
- ownerId: {description: "User who owns the widget", ref: "User", type: String},
53
- });
54
- widgetSchema.plugin(createdUpdatedPlugin);
55
- const Widget = mongoose.model("Widget", widgetSchema);
56
-
57
- const widgetRouter = modelRouter("/widgets", Widget, {
58
- permissions: {
59
- create: [Permissions.IsAuthenticated],
60
- delete: [],
61
- list: [Permissions.IsAuthenticated],
62
- read: [Permissions.IsOwner],
63
- update: [],
64
- },
65
- preCreate: (body, req) => {
66
- const user = req.user as unknown as {_id: string};
67
- return {...(body as {name: string}), ownerId: String(user._id)};
68
- },
69
- queryFilter: OwnerQueryFilter,
70
- });
71
-
72
- const healthPlugin = {
73
- register: (app: express.Application): void => {
74
- app.get("/health", (_req, res) => {
75
- res.json({healthy: mongoose.connection.readyState === 1});
76
- });
77
- },
78
- };
79
-
80
- await mongoose.connect(process.env.MONGO_URI as string);
81
- const app = new TerrenoApp({
82
- loggingOptions: {logRequests: false},
83
- userModel: User as unknown as ConstructorParameters<typeof TerrenoApp>[0]["userModel"],
84
- })
85
- .register(widgetRouter)
86
- .register(healthPlugin);
87
- app.start();
88
- await app.whenReady();
89
- logger.info(`[apiSmoke] serving on port ${process.env.PORT}`);
90
- };
91
-
92
- const expectStatus = async (res: Response, status: number, step: string): Promise<unknown> => {
93
- const body = await res.text();
94
- if (res.status !== status) {
95
- throw new Error(`${step}: expected ${status}, got ${res.status}: ${body}`);
96
- }
97
- return body ? JSON.parse(body) : undefined;
98
- };
99
-
100
- /** Parent: boots the child and walks the happy path over HTTP. */
101
- const run = async (): Promise<void> => {
102
- const startedAt = DateTime.now();
103
- const port = await freePort();
104
- const baseUrl = `http://127.0.0.1:${port}`;
105
- let server: SpawnedProcess | undefined;
106
-
107
- try {
108
- server = await spawnUntilReady({
109
- cmd: [process.execPath, __filename, SERVE_ARG],
110
- env: {
111
- MONGO_URI: await smokeMongoUri({databaseName: "apiSmoke"}),
112
- PORT: String(port),
113
- REFRESH_TOKEN_SECRET: "api-smoke-refresh-secret",
114
- SESSION_SECRET: "api-smoke-session-secret",
115
- TOKEN_ISSUER: "api-smoke",
116
- TOKEN_SECRET: "api-smoke-token-secret",
117
- },
118
- timeoutMs: 20000,
119
- url: `${baseUrl}/health`,
120
- });
121
-
122
- const health = (await expectStatus(await fetch(`${baseUrl}/health`), 200, "GET /health")) as {
123
- healthy: boolean;
124
- };
125
- if (!health.healthy) {
126
- throw new Error("GET /health: server reports unhealthy");
127
- }
128
- console.info("✅ GET /health is healthy");
129
-
130
- const email = `api-smoke-${startedAt.toMillis()}@example.com`;
131
- const signup = (await expectStatus(
132
- await fetch(`${baseUrl}/auth/signup`, {
133
- body: JSON.stringify({email, password: "api-smoke-password-1"}),
134
- headers: {"Content-Type": "application/json"},
135
- method: "POST",
136
- }),
137
- 200,
138
- "POST /auth/signup"
139
- )) as {data: {token: string; userId: string}};
140
- const headers = {
141
- Authorization: `Bearer ${signup.data.token}`,
142
- "Content-Type": "application/json",
143
- };
144
- console.info("✅ POST /auth/signup returns a token");
145
-
146
- const created = (await expectStatus(
147
- await fetch(`${baseUrl}/widgets`, {
148
- body: JSON.stringify({name: "Smoke widget"}),
149
- headers,
150
- method: "POST",
151
- }),
152
- 201,
153
- "POST /widgets"
154
- )) as {data: SmokeWidget};
155
- if (created.data.ownerId !== String(signup.data.userId)) {
156
- throw new Error(`POST /widgets: ownerId ${created.data.ownerId} is not the new user`);
157
- }
158
- console.info("✅ POST /widgets creates an owned widget");
159
-
160
- const listed = (await expectStatus(
161
- await fetch(`${baseUrl}/widgets`, {headers}),
162
- 200,
163
- "GET /widgets"
164
- )) as {data: SmokeWidget[]};
165
- if (!listed.data.some((widget) => widget._id === created.data._id)) {
166
- throw new Error("GET /widgets: the created widget is missing from the list");
167
- }
168
- console.info("✅ GET /widgets lists it");
169
- } catch (error: unknown) {
170
- if (server) {
171
- console.error(`--- server output ---\n${server.output()}`);
172
- }
173
- throw error;
174
- } finally {
175
- await server?.stop();
176
- await stopSmokeMongo();
177
- }
178
-
179
- console.info(`api smoke passed in ${DateTime.now().diff(startedAt).toMillis()} ms`);
180
- };
181
-
182
- const main = process.argv[2] === SERVE_ARG ? serve : run;
183
- main().then(
184
- () => {
185
- if (main === run) {
186
- process.exit(0);
187
- }
188
- },
189
- (error: unknown) => {
190
- console.error(`❌ ${error instanceof Error ? error.message : String(error)}`);
191
- process.exit(1);
192
- }
193
- );
package/tsconfig.json DELETED
@@ -1,19 +0,0 @@
1
- {
2
- "compilerOptions": {
3
- "allowJs": true,
4
- "declaration": true,
5
- "isolatedModules": true,
6
- "lib": ["es2023"],
7
- "module": "nodenext",
8
- "noImplicitAny": false,
9
- "noImplicitReturns": true,
10
- "outDir": "./dist",
11
- "rootDir": "./src",
12
- "skipLibCheck": true,
13
- "strict": true,
14
- "target": "es2023",
15
- "types": ["bun", "node"]
16
- },
17
- "exclude": ["node_modules", "**/*.test.ts", "**/*.isolated.ts", "src/isolated", "src/tests", "src/migrations/cli.ts"],
18
- "include": ["src"]
19
- }
@@ -1,14 +0,0 @@
1
- {
2
- "extends": "./tsconfig.json",
3
- "compilerOptions": {
4
- "noEmit": true,
5
- "composite": false,
6
- "incremental": false,
7
- "declaration": false,
8
- "declarationMap": false
9
- },
10
- "exclude": [
11
- "node_modules",
12
- "dist"
13
- ]
14
- }
@@ -1,13 +0,0 @@
1
- {
2
- "extends": "./tsconfig.json",
3
- "exclude": [
4
- "node_modules",
5
- "src/tests.ts",
6
- "src/tests/**",
7
- "**/*.test.ts",
8
- "**/*.isolated.ts",
9
- "src/isolated",
10
- "src/sync/loadHarness.ts",
11
- "src/migrations/cli.ts"
12
- ]
13
- }