@lowdefy/server-dev 6.0.0 → 7.0.0

package/lib/server/auth/createSystemContext.js

@@ -0,0 +1,73 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import path from 'node:path';
+import { createSystemContext as buildSystemContext } from '@lowdefy/api';
+import { getSecretsFromEnv } from '@lowdefy/node-utils';
+import { v4 as uuid } from 'uuid';
+
+import agents from '../../../build/plugins/agents.js';
+import appMeta from '../../build/appMeta.js';
+import config from '../../build/config.js';
+import connections from '../../../build/plugins/connections.js';
+import createHandleError from '../log/createHandleError.js';
+import createLogger from '../log/createLogger.js';
+import fileCache from '../fileCache.js';
+import i18nConfig from '../../build/i18n.js';
+import loadDynamicJsMap from '../loadDynamicJsMap.js';
+import notifications from '../../../build/plugins/notifications.js';
+import operators from '../../../build/plugins/operators/server.js';
+import scrubSecrets from '../scrubSecrets.js';
+import steps from '../../../build/plugins/steps.js';
+import websockets from '../../../build/plugins/websockets.js';
+
+const secrets = getSecretsFromEnv();
+
+// Builds a fresh system context per auth hook fire - the trusted internal
+// caller the BetterAuth engine uses to invoke hook endpoints. All fields are
+// startup singletons except the per-fire rid, logger, handleError, the
+// dynamic jsMap re-read (JIT rebuilds rewrite serverJsMap.js), and auth -
+// auth is threaded in by the caller (createHookDispatch) rather than
+// imported directly, since it comes from the same BetterAuth construction
+// that this factory is a dependency of (see createHookDispatch.js).
+function createSystemContext({ auth } = {}) {
+  const rid = uuid();
+  const buildDirectory = path.join(process.cwd(), 'build');
+  return buildSystemContext({
+    rid,
+    agents,
+    appMeta,
+    auth,
+    buildDirectory,
+    config,
+    configDirectory: process.env.LOWDEFY_DIRECTORY_CONFIG || process.cwd(),
+    connections,
+    createHandleError,
+    fileCache,
+    i18n: i18nConfig,
+    jsMap: loadDynamicJsMap(buildDirectory),
+    logger: createLogger({ rid }),
+    mode: 'dev',
+    notifications,
+    operators,
+    scrubSecrets,
+    secrets,
+    steps,
+    websockets,
+  });
+}
+
+export default createSystemContext;

package/lib/server/auth/getAuth.js

@@ -0,0 +1,46 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { getBetterAuth } from '@lowdefy/api';
+import { getSecretsFromEnv } from '@lowdefy/node-utils';
+
+import adapters from '../../../build/plugins/auth/adapters.js';
+import appMeta from '../../build/appMeta.js';
+import authJson from '../../build/auth.js';
+import createSystemContext from './createSystemContext.js';
+import lowdefyConfig from '../../build/config.js';
+import providers from '../../../build/plugins/auth/providers.js';
+
+// Returns the BetterAuth instance (memoized in @lowdefy/api), or null when
+// auth is not configured. dev: true relaxes cookies for plain-http localhost
+// and derives a per-app cookie prefix so parallel dev apps do not collide.
+function getAuth({ logger }) {
+  if (authJson.configured !== true) {
+    return null;
+  }
+  return getBetterAuth({
+    appMeta,
+    authJson,
+    config: lowdefyConfig,
+    createSystemContext,
+    dev: true,
+    logger,
+    plugins: { adapters, providers },
+    secrets: getSecretsFromEnv(),
+  });
+}
+
+export default getAuth;

package/lib/server/auth/getHeadlessUser.js

@@ -16,24 +16,25 @@
 
 import { HEADLESS_USER_COOKIE } from './headlessUser.js';
 
-// Decodes the headless renderer's user cookie (set by getBrowser.js openPage
-// on its own browser context, base64-encoded JSON) into the raw user object.
-// Returns just the user; getDevSession.js turns it into a session through
-// the same pipeline a real sign-in uses, so headless requests carry a
-// prod-shaped session while the developer's real browser (no cookie) is
-// unaffected.
+// Mirrors the e2e user-injection pattern (server-e2e/lib/server/auth/getUser.js):
+// the headless renderer sets a base64-JSON caller cookie on its own browser
+// context, so its /api/* fetches carry a pre-resolved caller while the
+// developer's real browser (no cookie) is unaffected. Returns { user, explicit }
+// as getBrowser.js wrote it, or null on miss - the caller floors the user's
+// shape via normalizeInjectedCaller. `explicit` is true when the tool call or
+// journey named the user, so createLowdefyContext lets it beat a dev mock user.
 function getHeadlessUser(c) {
   const cookieHeader = c.req.header('cookie') ?? '';
   const match = cookieHeader.match(new RegExp(`${HEADLESS_USER_COOKIE}=([^;]+)`));
   if (!match) {
-    return undefined;
+    return null;
   }
 
   try {
     const decoded = Buffer.from(decodeURIComponent(match[1]), 'base64').toString();
     return JSON.parse(decoded);
   } catch {
-    return undefined;
+    return null;
   }
 }
 

package/lib/server/auth/getHeadlessUser.test.mjs

@@ -0,0 +1,41 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import getHeadlessUser from './getHeadlessUser.js';
+
+function contextWithCookie(cookie) {
+  return { req: { header: (name) => (name === 'cookie' ? cookie : undefined) } };
+}
+
+function encode(value) {
+  return Buffer.from(JSON.stringify(value)).toString('base64');
+}
+
+test('getHeadlessUser reads the user and whether the caller named it', () => {
+  const caller = { user: { id: 'agent', roles: ['admin'] }, explicit: true };
+  expect(
+    getHeadlessUser(contextWithCookie(`other=1; lowdefy_headless_user=${encode(caller)}`))
+  ).toEqual(caller);
+});
+
+test('getHeadlessUser returns null with no headless cookie', () => {
+  expect(getHeadlessUser(contextWithCookie(undefined))).toBeNull();
+  expect(getHeadlessUser(contextWithCookie('other=1'))).toBeNull();
+});
+
+test('getHeadlessUser returns null for a cookie that is not base64 JSON', () => {
+  expect(getHeadlessUser(contextWithCookie('lowdefy_headless_user=%%%'))).toBeNull();
+});

package/lib/server/auth/getMockUser.js

@@ -14,14 +14,19 @@
   limitations under the License.
 */
 
+import { ConfigError } from '@lowdefy/errors';
 import { serializer } from '@lowdefy/helpers';
 
 import authJson from '../../build/auth.js';
 
-// Resolves the raw mock user object — LOWDEFY_DEV_USER env var first (the
-// `lowdefy dev --mock-user` flag sets it), then auth.dev.mockUser from the
-// build config. Returns just the user object; getDevSession.js turns it into
-// a session through the same pipeline a real sign-in uses.
+// dev.mockUser is a pre-resolved caller that substitutes for the whole
+// resolveAuthentication step - no auth engine, no session lookup, no
+// membership wall. Its roles are authoritative. LOWDEFY_DEV_USER takes
+// priority over auth.dev.mockUser from lowdefy.yaml.
+//
+// A dev mock user needs no auth stack behind it: auth.dev is a dev-only
+// concern, so an app whose only auth key is auth.dev runs signed out in
+// production and has this caller in the dev server.
 function getMockUser() {
   const mockUserJson = process.env.LOWDEFY_DEV_USER;
   let mockUser;
@@ -30,25 +35,24 @@ function getMockUser() {
     try {
       mockUser = JSON.parse(mockUserJson);
     } catch (error) {
-      throw new Error('Invalid JSON in LOWDEFY_DEV_USER environment variable.', { cause: error });
+      throw new ConfigError('Invalid JSON in LOWDEFY_DEV_USER environment variable.', {
+        cause: error,
+      });
     }
   } else {
     mockUser = authJson.dev?.mockUser;
   }
 
   if (!mockUser) {
-    return undefined;
-  }
-
-  if (authJson.configured !== true) {
-    throw new Error(
-      'Mock user configured but auth is not configured in lowdefy.yaml. ' +
-        'Add auth configuration to use mock user feature.'
-    );
+    return null;
   }
 
   // Deserialize to restore arrays from ~arr markers and remove other build markers
-  return serializer.deserialize(mockUser);
+  mockUser = serializer.deserialize(mockUser);
+
+  // The roles/attributes floor is applied at injection by
+  // normalizeInjectedCaller (createLowdefyContext.js) - return the raw user.
+  return mockUser;
 }
 
 export default getMockUser;

package/lib/server/auth/{getAuthConfig.js → getStrategies.js}

@@ -14,25 +14,27 @@
   limitations under the License.
 */
 
-import { getAuthConfig as getApiAuthConfig } from '@lowdefy/api';
+import { getAuthStrategies } from '@lowdefy/api';
 import { getSecretsFromEnv } from '@lowdefy/node-utils';
 
-import adapters from '../../../build/plugins/auth/adapters.js';
 import appMeta from '../../build/appMeta.js';
 import authJson from '../../build/auth.js';
-import callbacks from '../../../build/plugins/auth/callbacks.js';
-import events from '../../../build/plugins/auth/events.js';
-import providers from '../../../build/plugins/auth/providers.js';
+import strategyTypes from '../../../build/plugins/auth/strategies.js';
 
-function getAuthConfig({ logger }) {
-  return getApiAuthConfig({
+// Returns the API auth strategy verifiers (memoized in @lowdefy/api), or an
+// empty list when auth is not configured - resolveAuthentication tries them
+// in config order when no session resolves.
+function getStrategies({ logger }) {
+  if (authJson.configured !== true) {
+    return [];
+  }
+  return getAuthStrategies({
     appMeta,
     authJson,
-    dev: true,
     logger,
-    plugins: { adapters, callbacks, events, providers },
+    plugins: { strategies: strategyTypes },
     secrets: getSecretsFromEnv(),
   });
 }
 
-export default getAuthConfig;
+export default getStrategies;

package/lib/server/auth/headlessUser.js

@@ -15,12 +15,13 @@
 */
 
 // Shared between the headless renderer (getBrowser.js, which sets the cookie on
-// its browser context) and the dev session resolution (getHeadlessUser.js, which
+// its browser context) and the dev caller resolver (getHeadlessUser.js, which
 // decodes it) so the cookie name and injected user shape live in one place.
 const HEADLESS_USER_COOKIE = 'lowdefy_headless_user';
 
+// BetterAuth's session user carries `id`, never `sub`. attributes is floored to
+// {} by normalizeInjectedCaller at injection, so it is not spelled out here.
 const headlessUser = {
-  sub: 'lowdefy-headless',
   id: 'lowdefy-headless',
   name: 'Lowdefy Headless',
   roles: [],

package/lib/server/auth/journeyActor.js

@@ -0,0 +1,35 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import crypto from 'node:crypto';
+
+// Signs every journey cookie (journeyCookies.js): the headless renderer
+// (getBrowser.js) writes them on a journey actor's browser context, and the dev
+// server reads them back (getClientAddress.js for the actor address).
+//
+// Auth rate limits count attempts per client address, and every actor of every
+// journey reaches the dev server from the same machine, so each actor is given
+// its own address. The cookie carries it with a token minted once per dev
+// server process, so only the dev server's own headless browser can pick an
+// address: a cookie from anywhere else is ignored. The production server never
+// reads it. The token is kept on globalThis because the renderer and the
+// resolver may load as separate module instances in one process (Vite's SSR
+// module graph and Node's).
+const TOKEN_KEY = Symbol.for('lowdefy.devServer.journeyActorToken');
+globalThis[TOKEN_KEY] ??= crypto.randomBytes(32).toString('hex');
+const journeyActorToken = globalThis[TOKEN_KEY];
+
+export { journeyActorToken };

package/lib/server/auth/resolveHeadlessUser.test.mjs

@@ -19,7 +19,6 @@ import { headlessUser } from './headlessUser.js';
 
 test('resolveHeadlessUser returns the default roleless user when no user is given', () => {
   expect(resolveHeadlessUser({})).toEqual({
-    sub: 'lowdefy-headless',
     id: 'lowdefy-headless',
     name: 'Lowdefy Headless',
     roles: [],
@@ -32,7 +31,6 @@ test('resolveHeadlessUser returns the default roleless user when user is null',
 
 test('resolveHeadlessUser merges roles over the default, keeping the default id and name', () => {
   expect(resolveHeadlessUser({ user: { roles: ['user-admin'] } })).toEqual({
-    sub: 'lowdefy-headless',
     id: 'lowdefy-headless',
     name: 'Lowdefy Headless',
     roles: ['user-admin'],
@@ -45,7 +43,6 @@ test('resolveHeadlessUser keeps caller fields the app reads, like email and prof
       user: { id: 'agent', email: 'agent@example.com', profile: { name: 'Agent' } },
     })
   ).toEqual({
-    sub: 'lowdefy-headless',
     id: 'agent',
     name: 'Lowdefy Headless',
     email: 'agent@example.com',
@@ -58,7 +55,6 @@ test('resolveHeadlessUser does not mutate the default user between calls', () =>
   resolveHeadlessUser({ user: { id: 'first', roles: ['admin'] } });
 
   expect(resolveHeadlessUser({})).toEqual({
-    sub: 'lowdefy-headless',
     id: 'lowdefy-headless',
     name: 'Lowdefy Headless',
     roles: [],

package/lib/server/checkPageRecord.js

@@ -0,0 +1,44 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import hashConfigContent from './hashConfigContent.js';
+
+async function readHash({ filePath, readConfigFile }) {
+  try {
+    return hashConfigContent(await readConfigFile(filePath));
+  } catch {
+    // A file that cannot be read now (EACCES, or EBUSY on Windows during a
+    // save) is treated as changed; the rebuild reads it again and reports it.
+    return null;
+  }
+}
+
+// Whether the inputs of a page's last build are unchanged: 'current' when every
+// file it read still holds the content it read, else 'changed'. A build that
+// ran app code is always 'changed': app code can read anything, so its record
+// cannot be complete. Files are read through the build context's read cache,
+// so pages that share a file read it once per change event.
+async function checkPageRecord({ record, readConfigFile }) {
+  if (record.ranAppCode) return 'changed';
+  const recorded = [...record.files];
+  const hashes = await Promise.all(
+    recorded.map(([filePath]) => readHash({ filePath, readConfigFile }))
+  );
+  const unchanged = recorded.every(([, hash], index) => hashes[index] === hash);
+  return unchanged ? 'current' : 'changed';
+}
+
+export default checkPageRecord;

package/lib/server/contextMapBudget.js

@@ -0,0 +1,24 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+// Key and ref map entries the dev server's kept JIT build context may add
+// before it is recreated. Every page build adds entries to both maps and they
+// are released only with the context, so this bounds one dev server's memory.
+// Measured on the docs app: about 530 entries and 400-750 KB of retained heap
+// per page build, so this is about 90 page builds and 35-65 MB.
+const contextMapBudget = 48000;
+
+export default contextMapBudget;

package/lib/server/contextMapBudget.test.mjs

@@ -0,0 +1,98 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { jest } from '@jest/globals';
+
+// A budget one page build passes, so the next request recreates the context.
+jest.unstable_mockModule('./contextMapBudget.js', () => ({ default: 1 }));
+
+const { default: buildPageIfNeeded, getBuildContext } = await import('./jitPageBuilder.js');
+
+jest.setTimeout(30000);
+
+function writeJson(filePath, data) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify(data));
+}
+
+test('a build context past its map budget is recreated, and every page rebuilds on the new one', async () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'ldf-context-budget-'));
+  const buildDirectory = path.join(root, 'server', 'build');
+  const configDirectory = path.join(root, 'config');
+  writeJson(path.join(buildDirectory, 'idCounter.json'), { prefix: 'cfg1_', counter: 10 });
+  writeJson(path.join(buildDirectory, 'installedPluginPackages.json'), ['@lowdefy/blocks-basic']);
+  writeJson(path.join(buildDirectory, 'theme.json'), {});
+  const registry = {};
+  for (const pageId of ['a', 'b']) {
+    fs.mkdirSync(path.join(configDirectory, 'pages'), { recursive: true });
+    fs.writeFileSync(
+      path.join(configDirectory, 'pages', `${pageId}.yaml`),
+      `id: ${pageId}\ntype: Box\n`
+    );
+    registry[pageId] = {
+      pageId,
+      auth: { public: true },
+      refId: `ref-${pageId}`,
+      refPath: `pages/${pageId}.yaml`,
+    };
+  }
+  writeJson(path.join(buildDirectory, 'pageRegistry.json'), registry);
+  const request = (pageId) => buildPageIfNeeded({ pageId, buildDirectory, configDirectory });
+
+  expect(await request('a')).toEqual({ built: true, warnings: undefined });
+  const firstContext = getBuildContext(buildDirectory, configDirectory);
+  expect(await request('b')).toEqual({ built: true, warnings: undefined });
+  const secondContext = getBuildContext(buildDirectory, configDirectory);
+  expect(secondContext).not.toBe(firstContext);
+
+  // b was built past the budget too, so the next request recreates again and
+  // a, built two contexts ago, rebuilds.
+  expect(await request('a')).toEqual({ built: true, warnings: undefined });
+  expect(getBuildContext(buildDirectory, configDirectory)).not.toBe(secondContext);
+  fs.rmSync(root, { recursive: true, force: true });
+});
+
+test('a failed page build counts toward the budget', async () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'ldf-context-budget-'));
+  const buildDirectory = path.join(root, 'server', 'build');
+  const configDirectory = path.join(root, 'config');
+  writeJson(path.join(buildDirectory, 'idCounter.json'), { prefix: 'cfg1_', counter: 10 });
+  writeJson(path.join(buildDirectory, 'installedPluginPackages.json'), ['@lowdefy/blocks-basic']);
+  writeJson(path.join(buildDirectory, 'theme.json'), {});
+  fs.mkdirSync(path.join(configDirectory, 'pages'), { recursive: true });
+  fs.writeFileSync(
+    path.join(configDirectory, 'pages', 'broken.yaml'),
+    'id: broken\ntype: Box\nblocks:\n  - id: typo\n    type: Buton\n'
+  );
+  writeJson(path.join(buildDirectory, 'pageRegistry.json'), {
+    broken: {
+      pageId: 'broken',
+      auth: { public: true },
+      refId: 'ref-broken',
+      refPath: 'pages/broken.yaml',
+    },
+  });
+  const request = (pageId) => buildPageIfNeeded({ pageId, buildDirectory, configDirectory });
+
+  await expect(request('broken')).rejects.toThrow('Buton');
+  const firstContext = getBuildContext(buildDirectory, configDirectory);
+  await expect(request('broken')).rejects.toThrow('Buton');
+  expect(getBuildContext(buildDirectory, configDirectory)).not.toBe(firstContext);
+  fs.rmSync(root, { recursive: true, force: true });
+});

package/lib/server/continueJitKeys.js

@@ -0,0 +1,28 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { makeId } from '@lowdefy/build/dev';
+
+// JIT keys extend the config build's prefix with the dev server process's id, so
+// they never repeat a key of that build, of an earlier config build, or of another
+// process serving the same config build (a restarted server continues the build
+// the one before it served). Within a process the counter only moves forward, so
+// a recreated build context never repeats an earlier page build's key.
+function continueJitKeys({ idCounter, childId }) {
+  makeId.continueFrom({ prefix: `${idCounter.prefix}${childId}_`, counter: 0 });
+}
+
+export default continueJitKeys;

package/lib/server/continueJitKeys.test.mjs

@@ -0,0 +1,43 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { makeId } from '@lowdefy/build/dev';
+
+import continueJitKeys from './continueJitKeys.js';
+
+test('two dev server processes serving one config build never hand out the same key', () => {
+  const idCounter = { prefix: 'a1b2_', counter: 40 };
+
+  continueJitKeys({ idCounter, childId: 'aaaaaa' });
+  const first = [makeId.next(), makeId.next()];
+  continueJitKeys({ idCounter, childId: 'bbbbbb' });
+  const second = [makeId.next(), makeId.next()];
+
+  expect(first).toEqual(['a1b2_aaaaaa_1', 'a1b2_aaaaaa_2']);
+  expect(second).toEqual(['a1b2_bbbbbb_1', 'a1b2_bbbbbb_2']);
+});
+
+test('a recreated build context in the same process continues its keys', () => {
+  const idCounter = { prefix: 'c3d4_', counter: 40 };
+
+  continueJitKeys({ idCounter, childId: 'aaaaaa' });
+  const first = makeId.next();
+  continueJitKeys({ idCounter, childId: 'aaaaaa' });
+  const second = makeId.next();
+
+  expect(first).toBe('c3d4_aaaaaa_1');
+  expect(second).toBe('c3d4_aaaaaa_2');
+});

package/lib/server/createDataSessionEndedError.js

@@ -0,0 +1,33 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+
+import { HTTPException } from 'hono/http-exception';
+
+// A request whose verified data cookie names a session that has closed outlived its journey. The
+// verified token proves it came from a journey, so it is answered 410 and never falls back to the
+// app's own database. Thrown as an HTTPException, which the error handler sends as it is.
+function createDataSessionEndedError({ id }) {
+  const message = `Data session ${id} has ended; this request outlived its journey.`;
+  return new HTTPException(410, {
+    message,
+    res: new Response(JSON.stringify({ name: 'DataSessionEnded', message }), {
+      status: 410,
+      headers: { 'content-type': 'application/json' },
+    }),
+  });
+}
+
+export default createDataSessionEndedError;