@ketvietlab/ketjs 0.1.2 → 0.1.5

package/dist/server/boot.js

@@ -1,16 +1,16 @@
-// Booting an app: the sequence every deployment repeats, written once.
+// Booting a deployment: the sequence every deployment repeats, written once.
 //
-// Before this, running a KetSuite-shaped app meant ~150 lines of hand-written boot
-// in the app itself — open a database, migrate, register functions, install a
-// bootstrap set, decide who the request is, build the theme, mount the framework's
+// Before this, running a KetSuite-shaped deployment meant ~150 lines of hand-written boot
+// in the deployment itself — open a database, migrate, register functions,
+// decide who the request is, build the theme, mount the framework's
 // own routes, print something useful, shut down cleanly. Every one of those lines
-// is app-agnostic, and every second app would have copied them, drift included.
+// is deployment-agnostic, and every second deployment would have copied them, drift included.
 //
-// What stays with the app is what only the app knows: which modules it ships, which
+// What stays with the deployment is what only it knows: which modules it ships, which
 // function turns a path into a page, which extra routes it serves, and how to open
-// a datastore that is not SQLite. Those arrive through `AppSpec.serve` as data
+// a datastore that is not SQLite. Those arrive through `DeploymentSpec.serve` as data
 // rather than as a closure the framework has to trust.
-import { createAppRegistry } from '../kernel/apps.js';
+import { withoutVersion } from './assets.js';
 import { translator } from '../kernel/i18n.js';
 import { KetError } from '../kernel/errors.js';
 import { createTheme } from '../theme/render.js';
@@ -18,27 +18,32 @@ import { agentDescriptor } from '../agent/capabilities.js';
 import { migrateOne } from '../data/fleet.js';
 import { callFn } from './fn.js';
 import { createKetServer } from './http.js';
-import { createSessions, dbSessionStore } from './session.js';
+import { createSessions, dbSessionStore, scopeForSession } from './session.js';
 import { createTenants, singleTenant } from './tenants.js';
 import { createJoints } from '../theme/joints.js';
 import { buildMenu } from '../kernel/menu.js';
 import { createAdapterPool } from '../data/pool.js';
 import { document, json, text, withHeaders } from './respond.js';
 import { join, isAbsolute } from 'node:path';
-import { html, each } from '@ketvietlab/ketjs-view';
+import { html, each, renderToString } from '@ketvietlab/ketjs-view';
 import { sqliteStore } from './config.js';
 import { bootRuntime } from './runtime.js';
+import { traceOf } from './log/index.js';
 import { namespacedStorage, storageFromConfig } from './storage/index.js';
+import { randomBytes } from 'node:crypto';
 export { page, fragment, navigablePage, isNavigationRequest, text, bytes, streamed, raw, withHeaders, } from './respond.js';
 export { json } from './respond.js';
 /**
- * Opens, migrates, installs, serves. Returns before listening is announced so a
+ * Opens, migrates, and serves. Returns before listening is announced so a
  * caller can print its own banner, or a test can boot on port 0 and never print.
  */
-export async function bootApp(spec, o = {}) {
+export async function bootDeployment(spec, o = {}) {
     const serve = spec.serve ?? {};
     const log = o.log ?? console.log;
-    const { config, modules, manifest } = await bootRuntime(spec, o);
+    // `o.log` above is the boot-progress printer this function has always taken;
+    // `logSink` is the deployment's operational sink. Different things, and the
+    // older name is public API, so the new one is the one that gets qualified.
+    const { config, modules, manifest, log: logSink, logger } = await bootRuntime(spec, o);
     const baseStorage = await (serve.openStorage ?? storageFromConfig)(config);
     const storages = new Map();
     const storageFor = (key) => {
@@ -50,31 +55,15 @@ export async function bootApp(spec, o = {}) {
         }
         return storage;
     };
-    /**
-     * An empty database is not a useful one to look at, so a first run installs
-     * enough to see something. A database that has been used is left exactly as it
-     * is — and with tenants, "first run" is per tenant rather than per deployment.
-     */
-    const bootstrap = config.bootstrapApps ?? serve.bootstrap ?? [];
-    const bootstrapInto = async (key, apps) => {
-        if (!bootstrap.length || (await apps.enabled()).size !== 0)
-            return;
-        for (const name of bootstrap)
-            await apps.install(name);
-        log(`  first run${key ? ` [${key}]` : ''}, installed: ${[...(await apps.enabled())].sort().join(', ')}`);
-    };
     // Opened here only when there is one. With tenants there is no single datastore,
     // and a nullable field says that more honestly than a default one would.
     const adapter = serve.tenants ? null : await (serve.openStore ?? sqliteStore)(config);
-    let apps = null;
     if (adapter) {
         if (config.migrateOnBoot) {
             const ops = await migrateOne(adapter, manifest);
             if (ops.length)
                 log(`  migrate: ${ops.length} operation(s)`);
         }
-        apps = await createAppRegistry(manifest, adapter, { autoInstall: config.autoInstall });
-        await bootstrapInto('', apps);
     }
     /**
      * How a request finds its database. One datastore is the degenerate case of the
@@ -89,33 +78,36 @@ export async function bootApp(spec, o = {}) {
      * also the isolation you want: a session id from one tenant simply is not in
      * another's table.
      *
-     * An app serving every tenant from one domain cannot do that, because reading
-     * the session needs the database and knowing the database needs the session. It
-     * passes `sessions.store` instead — one shared store, with the tenant recorded
-     * on the session. Both work; the framework assumes neither.
+     * A deployment serving every tenant from one domain must still resolve the tenant
+     * before reading the cookie — for example from a trusted gateway assertion, path,
+     * or explicit header. It may pass `sessions.store` as one shared identity store;
+     * every record is then tenant-bound, and a session never selects a datastore.
      */
     const sharedStore = serve.sessions?.store ?? null;
+    const configuredSessionSecret = serve.sessions?.secret || config.secret;
+    const generatedTenantSecret = serve.sessions && serve.tenants && !configuredSessionSecret ? randomBytes(32).toString('base64url') : null;
     const sessionOpts = serve.sessions
         ? {
-            ...(config.secret ? { secret: config.secret } : {}),
             secure: config.host !== '127.0.0.1' && config.host !== 'localhost',
             ...serve.sessions,
+            ...(configuredSessionSecret ? { secret: configuredSessionSecret } : {}),
+            ...(generatedTenantSecret ? { secret: generatedTenantSecret, ephemeralSecret: true } : {}),
         }
         : null;
     const makeSessions = sessionOpts
-        ? (a) => createSessions({ ...sessionOpts, store: sharedStore ?? dbSessionStore(a) })
+        ? (a, tenant) => createSessions({
+            ...sessionOpts,
+            ...(sharedStore && tenant !== undefined ? { tenant } : {}),
+            store: sharedStore ?? dbSessionStore(a),
+        })
         : null;
-    // Single datastore: one Sessions, built now. Tenants: one per tenant, built on
-    // first touch — unless a shared store was supplied, in which case it is one
-    // again and every tenant hands back the same instance.
+    // Single datastore: one Sessions, built now. Tenant deployments expose one
+    // lease-safe facade per tenant. Facades may share a backing store, but remain
+    // distinct so every record and administrative operation stays tenant-bound.
     const sessions = makeSessions && adapter ? await makeSessions(adapter) : null;
-    // Built per tenant, because which templates exist depends on what is installed.
-    const islandRegistry = (live) => {
-        const disabled = new Set(live.disabledModules ?? []);
+    const islandRegistry = () => {
         const registry = {};
         for (const module of modules) {
-            if (disabled.has(module.name))
-                continue;
             for (const [name, definition] of Object.entries(module.islands))
                 registry[name] = definition.view;
         }
@@ -132,21 +124,16 @@ export async function bootApp(spec, o = {}) {
             }),
         };
     // Fills are KTL, so they translate the way templates do.
-    const jointFactory = (live, locale) => createJoints(live, { translate: translate(locale), islands: islandRegistry(live) });
+    const jointFactory = (live, locale) => createJoints(live, { translate: translate(locale), islands: islandRegistry() });
     const tenants = serve.tenants
         ? createTenants({
             spec: serve.tenants,
             pool: createAdapterPool({
-                create: (key) => {
-                    const made = serve.tenants.open(key, config);
-                    // The pool wants an Adapter now; opening is the adapter's own job.
-                    return made;
-                },
+                create: (key) => serve.tenants.open(key, config),
                 ...(serve.tenants.max !== undefined ? { max: serve.tenants.max } : {}),
                 ...(serve.tenants.idleMs !== undefined ? { idleMs: serve.tenants.idleMs } : {}),
             }),
             manifest,
-            autoInstall: config.autoInstall,
             ...(config.migrateOnBoot
                 ? {
                     prepare: async (key, a) => {
@@ -156,39 +143,72 @@ export async function bootApp(spec, o = {}) {
                     },
                 }
                 : {}),
-            onFirstTouch: (key, made) => bootstrapInto(key, made),
             ...(makeSessions ? { sessions: makeSessions } : {}),
             joints: jointFactory,
             ...themeFactory,
         })
         : singleTenant({
             adapter: adapter,
-            apps: apps,
             manifest,
             joints: jointFactory,
             ...themeFactory,
             sessions,
         });
     /**
-     * Sessions, when the app asks for them. Absent, the header shim stays and the
-     * banner keeps saying so — an app that has not wired auth yet should look like
+     * Sessions, when the deployment asks for them. Absent, the header shim stays and the
+     * banner keeps saying so — a deployment that has not wired auth yet should look like
      * one rather than quietly appear to have it.
      */
     /** This request's tenant's sessions — the same instance for all, when shared. */
     const sessionsOf = (url, req) => sessions ? Promise.resolve(sessions) : tenants.ofRequest(url, req, async (t) => t.sessions);
     // One cookie lookup per request even though scope, permissions and actor all
     // depend on it. With tenant databases this also avoids three separate leases.
+    const authenticationEnabled = Boolean(makeSessions || serve.resolveIdentity);
     const sessionRecords = new WeakMap();
     const sessionRecordOf = (url, req) => {
-        if (!makeSessions)
+        if (!authenticationEnabled)
             return Promise.resolve(null);
         let record = sessionRecords.get(req);
         if (!record) {
-            record = sessionsOf(url, req).then(async (manager) => {
+            record = tenants.ofRequest(url, req, async (tenant) => {
+                const identity = await serve.resolveIdentity?.({
+                    adapter: tenant.adapter,
+                    manifest: tenant.live,
+                    url,
+                    req,
+                });
+                if (identity) {
+                    const companies = [...new Set(identity.companies)];
+                    if (!identity.userId ||
+                        !companies.length ||
+                        !identity.company ||
+                        !companies.includes(identity.company))
+                        return null;
+                    const now = Date.now();
+                    return {
+                        id: `request:${identity.userId}`,
+                        userId: identity.userId,
+                        companies,
+                        company: identity.company,
+                        branch: identity.branch ?? null,
+                        branches: identity.branches ?? null,
+                        securityVersion: identity.securityVersion ?? 0,
+                        revision: 0,
+                        createdAt: now,
+                        expiresAt: now,
+                    };
+                }
+                const manager = await sessionsOf(url, req);
                 const raw = (await manager?.of(req)) ?? null;
                 if (!raw || !manager || !serve.resolveSession)
                     return raw;
-                const resolved = await tenants.ofRequest(url, req, (tenant) => serve.resolveSession({ adapter: tenant.adapter, manifest: tenant.live, record: raw, url, req }));
+                const resolved = await serve.resolveSession({
+                    adapter: tenant.adapter,
+                    manifest: tenant.live,
+                    record: raw,
+                    url,
+                    req,
+                });
                 if (!resolved) {
                     await manager.store.destroy(raw.id);
                     return null;
@@ -221,22 +241,30 @@ export async function bootApp(spec, o = {}) {
      * a session id issued by one tenant is not a row in another's table at all.
      */
     const scopeOf = async (url, req) => {
-        if (!makeSessions) {
+        if (!authenticationEnabled) {
             const list = (h) => (req.headers[h] ?? '')
                 .split(',')
                 .map((s) => s.trim())
                 .filter(Boolean);
             const company = req.headers['x-ket-company'] ?? config.defaultCompany;
             const companies = list('x-ket-companies');
+            const branches = list('x-ket-branch');
             return {
                 company,
                 companies: companies.length ? [...new Set([company, ...companies])] : null,
                 branch: req.headers['x-ket-current-branch'] ?? null,
-                branches: list('x-ket-branch') || null,
+                // An absent development header means unrestricted, matching Scope's
+                // null/undefined contract. `[]` is reserved for callers that explicitly
+                // construct a scope with no readable branches.
+                branches: branches.length ? branches : null,
             };
         }
-        const s = await sessionsOf(url, req);
-        return s?.scopeOf(await sessionRecordOf(url, req)) ?? { company: null };
+        const record = await sessionRecordOf(url, req);
+        if (!record) {
+            const s = await sessionsOf(url, req);
+            return s?.scopeOf(null) ?? { company: null };
+        }
+        return scopeForSession(record) ?? { company: null };
     };
     /**
      * A locale is only ever one the deployment ships a catalogue for.
@@ -251,30 +279,71 @@ export async function bootApp(spec, o = {}) {
         config.defaultLocale,
         config.fallbackLocale,
     ]);
+    const requestLocales = new WeakMap();
     const localeOf = (url, req) => {
-        const asked = [
-            url.searchParams.get('lang'),
-            ...(req.headers['accept-language'] ?? '')
-                .split(',')
-                .map((part) => part.split(';')[0]?.trim())
-                .flatMap((tag) => (tag ? [tag, tag.split('-')[0]] : [])),
-        ];
-        return asked.find((l) => l && known.has(l)) ?? config.defaultLocale;
+        const query = url.searchParams.get('lang');
+        const header = req.headers['accept-language'] ?? '';
+        const held = requestLocales.get(req);
+        if (held?.query === query && held.header === header)
+            return held.locale;
+        let locale = query && known.has(query) ? query : null;
+        if (!locale) {
+            for (const part of header.split(',')) {
+                const tag = part.split(';')[0]?.trim();
+                if (!tag)
+                    continue;
+                if (known.has(tag)) {
+                    locale = tag;
+                    break;
+                }
+                const base = tag.split('-')[0];
+                if (base && known.has(base)) {
+                    locale = base;
+                    break;
+                }
+            }
+        }
+        const resolved = locale ?? config.defaultLocale;
+        requestLocales.set(req, { query, header, locale: resolved });
+        return resolved;
+    };
+    const translators = new Map();
+    const translate = (locale) => {
+        const cached = translators.get(locale);
+        if (cached)
+            return cached;
+        const made = Object.freeze(translator(manifest, locale, { fallback: config.fallbackLocale }));
+        if (known.has(locale))
+            translators.set(locale, made);
+        return made;
     };
-    const translate = (locale) => translator(manifest, locale, { fallback: config.fallbackLocale });
     /**
-     * Every installed module's stylesheets, in dependency order, so a module that
-     * extends another loads after it and can override it. The app used to name two
-     * files belonging to another module by hand — which meant knowing that module's
-     * file layout, and going on linking them after it was uninstalled.
+     * Every composed module's stylesheets, in dependency order, so a module that
+     * extends another loads after it and can override it. A deployment does not
+     * name another module's files by hand, so it never needs to know that module's
+     * internal file layout.
      */
-    const styles = async (req) => tenants.ofRequest(new URL('http://x/'), req, async (t) => {
-        const on = await t.apps.enabled();
-        const hrefs = manifest.styles.filter((s) => on.has(s.by)).map((s) => s.href);
-        return html `${each(hrefs, (h) => h, (h) => html `<link rel="stylesheet" href=${h}>`)}`;
+    const styles = async (_req) => html `${each(manifest.styles.map((style) => style.href), (href) => href, (href) => html `<link rel="stylesheet" href=${href}>`)}`;
+    /**
+     * The context a call's records carry.
+     *
+     * Correlation and actor are hashed here rather than by the sink, so a raw value
+     * never becomes a record in the first place: the framework does not export those,
+     * and a log aggregator is an export.
+     */
+    const callLog = (tenant, scope, actor, correlationId) => logger.child({
+        // The tenant the lease already resolved, rather than resolving it a second
+        // time: `keyOf` throws for a host this deployment does not serve, and a
+        // logger must never be the thing that decides a request fails.
+        tenant: tenant || null,
+        trace: traceOf(correlationId, config.secret),
+        actor: traceOf(actor, config.secret),
+        company: scope.company,
     });
     const ctx = {
         manifest,
+        deploymentName: spec.name,
+        clientCompatibility: serve.clientCompatibility ?? null,
         config,
         scopeOf,
         localeOf,
@@ -291,11 +360,37 @@ export async function bootApp(spec, o = {}) {
             // The sidebar's search is in the URL like every other list's, so a filtered
             // menu is a link and the back button walks out of it.
             const q = url.searchParams.get('menu')?.trim() || undefined;
-            return tenants.ofRequest(url, req, async (t) => buildMenu(t.live, { allow, translate: (k) => _(k), active: url.pathname, q }));
+            // Someone who may call an inspection capability is looking, not working, and
+            // `for` describes work. Narrowing their sidebar would hide the very thing
+            // they were let in to see.
+            const inspecting = allow !== null && (spec.navigation?.audit ?? []).some((key) => allow.includes(key));
+            return tenants.ofRequest(url, req, async (t) => buildMenu(t.live, {
+                allow,
+                translate: (k) => _(k),
+                locale: _.locale,
+                active: url.pathname,
+                q,
+                groups: spec.navigation?.groups,
+                demote: spec.navigation?.demote,
+                // Searching is how someone reaches a surface that is not their daily
+                // work, so the search results are the permitted tree, not the narrowed
+                // one. Hiding what a person typed the name of would be a bug.
+                intent: !inspecting && !q,
+            }));
+        },
+        reportsOf: async (url, req, target) => {
+            const allow = await allowFor(url, req);
+            return tenants.ofRequest(url, req, async (t) => Object.values(t.live.reports).filter((report) => t.live.routes['/reports/{report}/{id}'] !== undefined &&
+                report.target === target &&
+                (allow === null || allow.includes(report.source))));
+        },
+        navigation: spec.navigation ?? null,
+        allows: async (name, url, req) => {
+            const allow = await allowFor(url, req);
+            return allow === null || allow.includes(name);
         },
         live: (req) => tenants.ofRequest(new URL('http://x/'), req, async (t) => t.live),
-        appsOf: (req) => tenants.ofRequest(new URL('http://x/'), req, (t) => t.apps.list()),
-        callUnchecked: async (name, input, url, req) => {
+        callUnchecked: async (name, input, url, req, options) => {
             const scope = await scopeOf(url, req);
             const actor = await actorOf(url, req);
             return tenants.ofRequest(url, req, async (t) => (await callFn(name, input, {
@@ -303,10 +398,39 @@ export async function bootApp(spec, o = {}) {
                 manifest: t.live,
                 scope,
                 actor,
+                idempotencyKey: options?.idempotencyKey,
+                idempotencyNamespace: options?.idempotencyNamespace,
+                idempotencyDigest: options?.idempotencyDigest,
+                correlationId: options?.correlationId,
+                queueNotify: config.queueNotify,
+                log: callLog(t.key, scope, actor, options?.correlationId),
+            })).value);
+        },
+        callUncheckedForVerifiedCompany: async (name, input, companyId, url, req, options) => {
+            const company = companyId.trim();
+            if (!company)
+                throw new KetError({
+                    code: 'E_VERIFIED_COMPANY_REQUIRED',
+                    module: 'server',
+                    message: 'a verified company is required for company-scoped dispatch',
+                    hint: 'authenticate the external credential and derive one company before dispatching the function',
+                });
+            const actor = await actorOf(url, req);
+            const verifiedScope = { company, companies: [company], branch: null, branches: null };
+            return tenants.ofRequest(url, req, async (t) => (await callFn(name, input, {
+                adapter: t.adapter,
+                manifest: t.live,
+                scope: verifiedScope,
+                actor,
+                idempotencyKey: options?.idempotencyKey,
+                idempotencyNamespace: options?.idempotencyNamespace,
+                idempotencyDigest: options?.idempotencyDigest,
+                correlationId: options?.correlationId,
                 queueNotify: config.queueNotify,
+                log: callLog(t.key, verifiedScope, actor, options?.correlationId),
             })).value);
         },
-        call: async (name, input, url, req) => {
+        call: async (name, input, url, req, options) => {
             // One lease for the whole call: the scope and the allow-list are resolved
             // outside it, so a session lookup never holds a pooled connection.
             const scope = await scopeOf(url, req);
@@ -318,17 +442,19 @@ export async function bootApp(spec, o = {}) {
                 scope,
                 allow,
                 actor,
+                idempotencyKey: options?.idempotencyKey,
+                idempotencyNamespace: options?.idempotencyNamespace,
+                idempotencyDigest: options?.idempotencyDigest,
+                correlationId: options?.correlationId,
                 queueNotify: config.queueNotify,
+                log: callLog(t.key, scope, actor, options?.correlationId),
             })).value);
         },
     };
     /**
      * Module-contributed routes and assets.
      *
-     * Both are looked up per request against the LIVE manifest rather than mounted
-     * once at boot. That costs a set lookup and buys the property the app model
-     * claims: switching a module off stops its routes answering and stops its
-     * stylesheet being served, without a restart.
+     * Both are mounted from the immutable deployment manifest.
      */
     const routeHandlers = new Map();
     for (const [path, entry] of Object.entries(manifest.routes))
@@ -336,16 +462,10 @@ export async function bootApp(spec, o = {}) {
     const moduleRoutes = {};
     for (const [path, entry] of Object.entries(manifest.routes)) {
         moduleRoutes[path] = async (url, req, params) => {
-            const on = await tenants.ofRequest(url, req, (t) => t.apps.enabled());
-            if (!on.has(entry.by)) {
-                return text(`${path} belongs to "${entry.by}", which is not installed on this database`, {
-                    status: 404,
-                });
-            }
             // Closed unless the module said otherwise. A browser is sent to the sign-in
             // page carrying where it was going; anything else gets the status, because a
             // redirect to an HTML form is a useless answer to a fetch().
-            if (makeSessions && !entry.anonymous) {
+            if (authenticationEnabled && !entry.anonymous) {
                 if (!(await sessionRecordOf(url, req))) {
                     const wantsHtml = String(req.headers.accept ?? '').includes('text/html');
                     return wantsHtml
@@ -359,23 +479,20 @@ export async function bootApp(spec, o = {}) {
         };
     }
     /**
-     * A module's assets, resolved per request so that switching the module off stops
-     * them being served — without a restart, and without the app knowing where any
-     * module keeps its files.
+     * A module's assets, resolved without exposing module file layout to the deployment.
      */
     const assetMount = {
         prefix: '/_ket/asset/',
-        resolve: async (rest, url, req) => {
+        resolve: async (rest, _url, _req) => {
             const slash = rest.indexOf('/');
             if (slash <= 0)
                 return null;
             const owner = rest.slice(0, slash);
-            const file = rest.slice(slash + 1);
+            // A version segment names the bytes, not a directory — see assets.ts.
+            const file = withoutVersion(rest.slice(slash + 1));
             const dir = manifest.assets[owner];
             if (!dir || !file || file.startsWith('..') || isAbsolute(file))
                 return null;
-            if (!(await tenants.ofRequest(url, req, (t) => t.apps.enabled())).has(owner))
-                return null;
             return join(dir, file);
         },
     };
@@ -391,30 +508,67 @@ export async function bootApp(spec, o = {}) {
         .filter(([, f]) => f.anonymous)
         .map(([k]) => k);
     const allowFor = async (url, req) => {
-        if (!makeSessions)
+        if (!authenticationEnabled)
             return null; // no login exists yet; the shim is the identity
+        const audience = await serve.resolveAudience?.(url, req);
+        const customAudience = Boolean(audience && audience !== 'anonymous' && audience !== 'staff');
         const record = await sessionRecordOf(url, req);
-        if (!record)
+        if (!record) {
             return anonymousFns; // a stranger, not an administrator
+        }
+        // A custom bearer audience is fail-closed unless the deployment explicitly
+        // maps it to exact functions. This lets Channel routes call their domain
+        // functions without turning a POS/customer token into a staff session.
         if (!serve.permissions)
-            return null;
-        const granted = await serve.permissions(ctx, record.userId);
-        return granted === null ? null : [...new Set([...anonymousFns, ...granted])];
+            return customAudience ? [] : null;
+        const granted = await serve.permissions(ctx, record.userId, url, req);
+        return granted === null ? (customAudience ? [] : null) : [...new Set([...anonymousFns, ...granted])];
     };
     const pages = serve.pages;
+    const previewPath = pages?.previewPath ?? '/_ket/preview';
+    /**
+     * A preview is a request at that one path carrying a token, and only when the
+     * deployment named something to answer it — otherwise the path is an ordinary
+     * miss rather than a preview that silently renders nothing.
+     */
+    const isPreviewRequest = (url) => !!pages?.previewResolve && url.pathname === previewPath && !!url.searchParams.get('token');
     if (pages && !manifest.functions[pages.resolve]) {
         throw new KetError({
             code: 'E_PAGE_RESOLVER_MISSING',
             module: spec.name,
-            message: `app "${spec.name}" resolves pages with "${pages.resolve}", which no installed module declares`,
-            hint: `add the module that owns "${pages.resolve.split('.')[0]}" to the app, or drop serve.pages`,
+            message: `deployment "${spec.name}" resolves pages with "${pages.resolve}", which no composed module declares`,
+            hint: `add the module that owns "${pages.resolve.split('.')[0]}" to the deployment, or drop serve.pages`,
+        });
+    }
+    if (pages?.previewResolve && !manifest.functions[pages.previewResolve]) {
+        throw new KetError({
+            code: 'E_PREVIEW_RESOLVER_MISSING',
+            module: spec.name,
+            message: `deployment "${spec.name}" resolves previews with "${pages.previewResolve}", which no composed module declares`,
+            hint: `add the module that owns "${pages.previewResolve.split('.')[0]}", or drop serve.pages.previewResolve`,
+        });
+    }
+    if (pages?.previewPath && !pages.previewPath.startsWith('/_ket/')) {
+        throw new KetError({
+            code: 'E_PREVIEW_PATH_UNRESERVED',
+            module: spec.name,
+            message: `deployment "${spec.name}" serves previews at "${pages.previewPath}", which a published page could claim`,
+            hint: 'keep the preview path under /_ket/, the namespace no page may be published in',
+        });
+    }
+    if (pages?.menuResolve && !manifest.functions[pages.menuResolve]) {
+        throw new KetError({
+            code: 'E_MENU_RESOLVER_MISSING',
+            module: spec.name,
+            message: `deployment "${spec.name}" resolves navigation with "${pages.menuResolve}", which no composed module declares`,
+            hint: `add the module that owns "${pages.menuResolve.split('.')[0]}", or drop serve.pages.menuResolve`,
         });
     }
     if (pages?.siteResolve && !manifest.functions[pages.siteResolve]) {
         throw new KetError({
             code: 'E_SITE_RESOLVER_MISSING',
             module: spec.name,
-            message: `app "${spec.name}" resolves sites with "${pages.siteResolve}", which no installed module declares`,
+            message: `deployment "${spec.name}" resolves sites with "${pages.siteResolve}", which no composed module declares`,
         });
     }
     for (const selected of availableThemes)
@@ -422,7 +576,7 @@ export async function bootApp(spec, o = {}) {
             throw new KetError({
                 code: 'E_PAGE_REGION_MISSING',
                 module: spec.name,
-                message: `app "${spec.name}" navigates through region "${pages.region}", which theme "${selected.name}" does not render`,
+                message: `deployment "${spec.name}" navigates through region "${pages.region}", which theme "${selected.name}" does not render`,
                 hint: `add a "${pages.region}" template, or remove serve.pages.region to keep full navigation`,
             });
         }
@@ -453,16 +607,25 @@ export async function bootApp(spec, o = {}) {
             throw new KetError({
                 code: 'E_ROUTE_RESERVED',
                 module: spec.name,
-                message: `app "${spec.name}" claims "${path}", which is reserved`,
+                message: `deployment "${spec.name}" claims "${path}", which is reserved`,
                 hint: '/_ket/ belongs to the framework: health, the agent descriptor, streams and assets',
             });
         }
+        const reservation = Object.entries(manifest.routePrefixes).find(([prefix]) => path.startsWith(prefix));
+        if (reservation) {
+            throw new KetError({
+                code: 'E_ROUTE_RESERVED',
+                module: spec.name,
+                message: `deployment "${spec.name}" claims "${path}", inside the prefix reserved by "${reservation[1]}"`,
+                hint: 'reserved API routes must be declared by modules through the published route factory',
+            });
+        }
         const owner = manifest.routes[path]?.by;
         if (owner) {
             throw new KetError({
                 code: 'E_ROUTE_CLASH',
                 module: spec.name,
-                message: `module "${owner}" and app "${spec.name}" both serve "${path}"`,
+                message: `module "${owner}" and deployment "${spec.name}" both serve "${path}"`,
                 hint: 'two owners cannot share one path — rename one, or keep the route in its module',
             });
         }
@@ -470,6 +633,15 @@ export async function bootApp(spec, o = {}) {
     const server = await createKetServer({
         manifest,
         adapter,
+        log: logger,
+        ...(serve.streamStore ? { streamStore: serve.streamStore } : {}),
+        ...(serve.streamTimeoutMs === undefined ? {} : { streamTimeoutMs: serve.streamTimeoutMs }),
+        ...(serve.streamPollMs === undefined ? {} : { streamPollMs: serve.streamPollMs }),
+        ...(serve.resolveStream
+            ? { resolveStream: (id, url, req) => serve.resolveStream(ctx, id, url, req) }
+            : {}),
+        ...(serve.maxJsonBodyBytes !== undefined ? { maxJsonBodyBytes: serve.maxJsonBodyBytes } : {}),
+        ...(serve.rateLimit ? { rateLimit: (url, req) => serve.rateLimit(ctx, url, req) } : {}),
         /**
          * The HTTP layer gets a pool whose leases go through the tenant runtime, not
          * the raw one.
@@ -489,6 +661,66 @@ export async function bootApp(spec, o = {}) {
                 resolveDatastore: (url, req) => tenants.keyOf(url, req),
             }
             : {}),
+        /**
+         * The page a person gets when the answer is no.
+         *
+         * A permission failure used to hand a browser the same JSON a client gets:
+         * a code, a function key and a hint about a CLI, on a bare page with no way
+         * back. That is a fine answer for a program and a dead end for a person, and
+         * the person is the one who arrived by clicking something.
+         *
+         * The markup uses the same `data-ui` hooks the design system already styles,
+         * and loads the deployment's own stylesheets, so this is the product's error
+         * screen rather than a second visual language living in the framework.
+         */
+        renderErrorPage: async ({ code, status, url, req }) => {
+            const _ = translate(localeOf(url, req));
+            const text = (key, fallback) => {
+                const found = _(key);
+                return found && found !== key ? found : fallback;
+            };
+            const kind = code === 'E_FN_NOT_PERMITTED' ? 'forbidden' : status === 404 ? 'missing' : 'failed';
+            const copy = {
+                forbidden: {
+                    title: text('backend.error.forbidden.title', 'Bạn không có quyền mở màn hình này'),
+                    message: text('backend.error.forbidden.message', 'Tài khoản của bạn không được cấp quyền cho màn hình này. Nếu đây là việc bạn cần làm, hãy đề nghị quản trị viên cấp thêm quyền.'),
+                },
+                missing: {
+                    title: text('backend.error.missing.title', 'Không tìm thấy màn hình này'),
+                    message: text('backend.error.missing.message', 'Đường dẫn này không còn tồn tại, hoặc chưa bao giờ tồn tại trong bản triển khai đang chạy.'),
+                },
+                failed: {
+                    title: text('backend.error.failed.title', 'Màn hình này không mở được'),
+                    message: text('backend.error.failed.message', 'Đã có lỗi khi dựng màn hình. Thử lại; nếu vẫn vậy, gửi mã lỗi bên dưới cho người phụ trách hệ thống.'),
+                },
+            }[kind];
+            const back = text('backend.error.back', 'Quay lại trang đầu');
+            // Only hooks the design system already declares and styles. The one rule
+            // below centres the block on an otherwise empty page, and is inline because
+            // an error page has to render even when a stylesheet is what went wrong.
+            const head = html `${await styles(req)}<style>
+        .ket-error-page {
+          display: grid;
+          min-block-size: 100dvh;
+          place-items: center;
+          padding: 2rem;
+        }
+      </style>`;
+            const body = html `<main class="ket-error-page">
+        <div data-ui="error" role="alert">
+          <p data-ui="error-code">${code}</p>
+          <p data-ui="error-message">${copy.title}</p>
+          <p data-ui="error-hint">${copy.message}</p>
+          <p>
+            <a data-ui="action" data-variant="primary" data-size="default" href="/admin">
+              <span data-ui="action-label">${back}</span>
+            </a>
+          </p>
+        </div>
+      </main>`;
+            // Same shape every other document takes: doctype, then the rendered tree.
+            return `<!doctype html>${renderToString(ctx.document({ lang: localeOf(url, req), title: copy.title, head, body }))}`;
+        },
         resolveLocale: localeOf,
         resolveScope: scopeOf,
         resolveAllow: allowFor,
@@ -510,7 +742,7 @@ export async function bootApp(spec, o = {}) {
                         return null;
                     const chosen = site?.theme ?? fallbackTheme.name;
                     const allowed = availableThemes.find((theme) => theme.name === chosen);
-                    if (!allowed || t.live.disabledModules?.includes(allowed.name))
+                    if (!allowed)
                         return null;
                     const locale = site?.locale ?? localeOf(url, req);
                     const key = `${t.key}::${t.live.order.join(',')}::${allowed.name}::${locale}`;
@@ -529,12 +761,20 @@ export async function bootApp(spec, o = {}) {
          * The storefront: a path becomes a page, and a page becomes its sections.
          *
          * The lookup runs through callFn like anything else, so the company filter and
-         * the app-installed check apply to a public page exactly as they do to an API
+         * the composed manifest applies to a public page exactly as it does to an API
          * call — the front of the site is not a second door with different rules.
          */
         ...(pages
             ? {
                 ...(pages.region ? { pageRegion: pages.region } : {}),
+                pagePrivate: (url) => isPreviewRequest(url),
+                siteTokens: async (url, req) => {
+                    const resolved = await siteOf(url, req);
+                    const tokens = resolved?.tokens;
+                    return tokens && typeof tokens === 'object' && !Array.isArray(tokens)
+                        ? tokens
+                        : null;
+                },
                 pageScope: async (url, req) => {
                     const resolvedSite = await siteOf(url, req);
                     const site = {
@@ -546,7 +786,11 @@ export async function bootApp(spec, o = {}) {
                     // It was hardcoded there, which made i18n untrue on the first tag of every
                     // storefront page.
                     const locale = resolvedSite?.locale ?? localeOf(url, req);
-                    const row = (await ctx.call(pages.resolve, { path: url.pathname, ...(resolvedSite?.id ? { siteId: resolvedSite.id } : {}) }, url, req));
+                    // A preview reads by token, not by path: the draft has no address
+                    // on the site yet, which is the whole reason a link is needed.
+                    const row = (isPreviewRequest(url)
+                        ? await ctx.call(pages.previewResolve, { token: url.searchParams.get('token') ?? '' }, url, req)
+                        : await ctx.call(pages.resolve, { path: url.pathname, ...(resolvedSite?.id ? { siteId: resolvedSite.id } : {}) }, url, req));
                     if (!row) {
                         const _ = translate(locale);
                         return {
@@ -556,11 +800,22 @@ export async function bootApp(spec, o = {}) {
                             sections: [],
                         };
                     }
+                    // Navigation belongs to the site, not to the page, so it is resolved
+                    // beside it rather than carried by it. The framework names no
+                    // module: the deployment says which function answers, the way it
+                    // already does for the site and the page.
+                    const menu = pages.menuResolve && resolvedSite?.id
+                        ? ((await ctx.call(pages.menuResolve, { siteId: resolvedSite.id }, url, req)) ?? [])
+                        : [];
                     return {
                         site,
                         locale,
-                        page: { id: row.id, path: url.pathname, title: row.title },
-                        meta: {},
+                        menu,
+                        page: { id: row.id, path: row.path ?? url.pathname, title: row.title },
+                        // Whatever the resolver says describes this page. The framework
+                        // does not name the fields — a module owns them and decides what
+                        // is public; this only stops hardcoding the answer to "nothing".
+                        meta: row.meta ?? {},
                         sections: typeof row.layout === 'string' ? JSON.parse(row.layout) : row.layout,
                     };
                 },
@@ -569,16 +824,13 @@ export async function bootApp(spec, o = {}) {
         routes: {
             ...moduleRoutes,
             ...appRoutes,
-            // The framework's own two, mounted last so an app cannot shadow them by accident.
-            // Both answer for the tenant that asked: "which apps are on" has no
-            // deployment-wide answer once there is more than one database.
+            // The framework's own two, mounted last so a deployment cannot shadow them.
             '/_ket/health': async (url, req) => tenants.ofRequest(url, req, async (t) => json({
                 ok: true,
-                app: spec.name,
+                deployment: spec.name,
                 database: t.adapter.name,
                 ...(t.key ? { tenant: t.key } : {}),
-                apps: [...(await t.apps.enabled())].sort(),
-                orphans: await t.apps.orphans(),
+                modules: manifest.order,
                 locales: Object.keys(manifest.messages ?? {}),
             })),
             '/_ket/agent': async (url, req) => tenants.ofRequest(url, req, async (t) => json(agentDescriptor(t.live))),
@@ -586,20 +838,14 @@ export async function bootApp(spec, o = {}) {
     });
     const port = await server.listen(config.port);
     const banner = async () => {
-        // With tenants there is no deployment-wide list of installed apps, and the
-        // banner says which mode it is in rather than inventing one.
-        const enabled = apps ? [...(await apps.enabled())].sort() : [];
         const at = `http://${config.host}:${port}`;
-        // A "site" row only means something if a path can become a page; an app that
+        // A "site" row only means something if a path can become a page; a deployment that
         // declares its own "/" route would otherwise be listed twice, once wrongly.
         const paths = new Map();
         if (pages)
             paths.set('/', 'site');
-        // Module routes belong on the banner too, and only while installed — the list
-        // is what the deployment actually serves, not what it could serve.
-        for (const [p, r] of Object.entries(manifest.routes))
-            if (enabled.includes(r.by))
-                paths.set(p, p.replace(/^\//, ''));
+        for (const p of Object.keys(manifest.routes))
+            paths.set(p, p.replace(/^\//, ''));
         for (const p of Object.keys(appRoutes))
             paths.set(p, p.replace(/^\//, '') || 'site');
         const rows = [
@@ -613,7 +859,7 @@ export async function bootApp(spec, o = {}) {
                     ? adapter.name + (config.databaseUrl ? '' : ` (${config.sqliteFile})`)
                     : `${(await tenants.keys()).length} tenant(s), one database each`,
             ],
-            ['apps installed', apps ? enabled.join(', ') || '(none)' : 'per tenant'],
+            ['modules', manifest.order.join(', ') || '(none)'],
             ['locales', Object.keys(manifest.messages ?? {}).join(', ') || '(none)'],
             [
                 'identity',
@@ -621,13 +867,10 @@ export async function bootApp(spec, o = {}) {
                     ? `sessions (${sessions ? sessions.store.name : 'one per tenant'})`
                     : 'X-Ket-Company header',
             ],
-            // Silence here would be the wrong kind: a module that declared install:'auto'
-            // and did not arrive should say why, not look broken.
-            ...(config.autoInstall ? [] : [['auto-install', 'off (KET_AUTO_INSTALL=0)']]),
         ];
         const w = Math.max(...rows.map((r) => r[0].length));
         const note = makeSessions
-            ? (sessions?.ephemeralSecret ?? !config.secret)
+            ? (sessions?.ephemeralSecret ?? !configuredSessionSecret)
                 ? `\n  KET_SECRET is not set, so a signing key was generated for this process.` +
                     `\n  Sessions will not survive a restart and will not work across pods.`
                 : ''
@@ -642,12 +885,28 @@ export async function bootApp(spec, o = {}) {
         if (adapter)
             await adapter.close();
         await tenants.close();
+        // Last, and after everything that might still have something to say. A buffered
+        // sink that is closed first loses precisely the records describing the shutdown.
+        logger.info('shutdown');
+        await logSink.flush?.();
+        await logSink.close?.();
+    };
+    return {
+        name: spec.name,
+        manifest,
+        adapter,
+        tenants,
+        config,
+        streams: server.streams,
+        logger,
+        port,
+        banner,
+        close,
     };
-    return { name: spec.name, manifest, adapter, apps, tenants, config, port, banner, close };
 }
-/** bootApp, plus the banner and the signal handling a long-running process wants. */
-export async function serveApp(spec, o = {}) {
-    const booted = await bootApp(spec, o);
+/** bootDeployment, plus the banner and the signal handling a long-running process wants. */
+export async function serveDeployment(spec, o = {}) {
+    const booted = await bootDeployment(spec, o);
     console.log(await booted.banner());
     for (const signal of ['SIGINT', 'SIGTERM']) {
         process.on(signal, () => {