@hearthlog/tooling 0.0.0-stage → 0.1.0

package/src/vite/config.ts

@@ -0,0 +1,310 @@
+import adapter from '@sveltejs/adapter-static';
+import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';
+import { sveltekit } from '@sveltejs/kit/vite';
+import tailwindcss from '@tailwindcss/vite';
+import Icons from 'unplugin-icons/vite'
+import { entityGeneratorPlugin } from './vite-plugin-entity-gen.js';
+import { tenantManifestPlugin } from './vite-plugin-tenant-manifest.js';
+import { workerAssetsPlugin } from './vite-plugin-worker-assets.js';
+import { readFileSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { join, resolve } from 'node:path';
+import { localGatewayOriginAllowed, readLocalLedgerCredentialSync } from '../dev/local-development.js';
+import {
+	e2eLedgerStubPlugin,
+	localAiDecisionsPlugin,
+	localInvoiceExtractionPlugin,
+	localInvoicePdfGatewayFallbackPlugin,
+	localInvoiceRendererPath,
+	localLedgerGatewayPath,
+	localLedgerOriginGuardPlugin,
+	localReceivedInvoiceFilesPlugin,
+} from './dev-plugins.js';
+
+import { defineConfig, type ProxyOptions, type UserConfig } from 'vite';
+
+function installedVersion(name: string): string {
+	try {
+		return JSON.parse(readFileSync(join('node_modules', name, 'package.json'), 'utf8')).version;
+	} catch {
+		return 'unknown';
+	}
+}
+
+function gitOutput(...args: string[]): string {
+	try {
+		return execFileSync('git', args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+	} catch {
+		return '';
+	}
+}
+
+const stackInfo = {
+	packages: Object.fromEntries(
+		[
+			'svelte',
+			'@sveltejs/kit',
+			'vite',
+			'typescript',
+			'tailwindcss',
+			'bits-ui',
+			'@tanstack/svelte-table',
+			'@tanstack/svelte-virtual',
+			'kysely',
+			'sqlocal',
+			'date-fns',
+		].map((name) => [name, installedVersion(name)]),
+	),
+	node: process.version.replace(/^v/, ''),
+	commit: gitOutput('rev-parse', '--short', 'HEAD'),
+	branch: gitOutput('rev-parse', '--abbrev-ref', 'HEAD'),
+	dirty: gitOutput('status', '--porcelain', '--untracked-files=no') !== '',
+};
+
+const buildTimestamp = process.env.STOR_BUILD_TIMESTAMP?.trim() || new Date().toISOString();
+// Tenant build selection: VITE_STOR_TENANT=bravo writes the site into
+// build/bravo (matching wrangler env.bravo assets.directory). The default
+// tenant keeps the historical ./build output used by the top-level Worker.
+const tenantId = process.env.VITE_STOR_TENANT?.trim() || 'st';
+const buildDirectory = process.env.STOR_BUILD_OUTPUT_ROOT?.trim() ||
+	(tenantId === 'st' ? 'build' : `build/${tenantId}`);
+const svelteKitOutDir = process.env.STOR_SVELTEKIT_OUT_DIR?.trim() || '.svelte-kit';
+// `pnpm build:generated` writes the site's boot shell and tenant module under .generated/sites/<id>/.
+const appTemplate = `.generated/sites/${tenantId}/app.html`;
+// The host files `pnpm build:generated` writes (see tooling/src/host/write-host.ts).
+const hostFiles = {
+	routes: '.generated/routes',
+	serviceWorker: '.generated/service-worker',
+	assets: '.generated/static',
+	appTemplate,
+};
+const tenantGeneratedModule = `.generated/sites/${tenantId}/tenant.ts`;
+
+/**
+ * Read a Worker-style secret for the local dev proxy. Vite only exposes
+ * `VITE_`-prefixed values to the client, so server-only credentials come from
+ * the process environment or the gitignored `.dev.vars` / `.env` files.
+ */
+function readDevVar(name: string): string | undefined {
+	const fromEnvironment = process.env[name]?.trim();
+	if (fromEnvironment) return fromEnvironment;
+	for (const file of ['.dev.vars', '.env']) {
+		try {
+			const line = readFileSync(file, 'utf8')
+				.split('\n')
+				.find((entry) => entry.trimStart().startsWith(`${name}=`));
+			if (!line) continue;
+			const value = line.slice(line.indexOf('=') + 1).trim();
+			if (value) return value.replace(/^(['"])(.*)\1$/, '$2');
+		} catch {
+			// The file is optional; try the next source.
+		}
+	}
+	return undefined;
+}
+
+export interface HearthlogConfigOptions {
+	/** Vitest options; only the repository that tests its packages passes them. */
+	test?: Record<string, unknown>;
+}
+
+/**
+ * The Vite configuration of a Hearthlog site: SvelteKit with the static adapter, Tailwind, icons, the site's
+ * manifest and entity plugins, and the local development stand-ins for the gateway Worker. A site's
+ * `vite.config.ts` calls this and nothing else.
+ */
+export function hearthlogConfig(options: HearthlogConfigOptions = {}) {
+return defineConfig(({ command, mode }): UserConfig => {
+	const localLedgerCredential =
+		command === 'serve' && mode === 'development'
+			? readLocalLedgerCredentialSync()
+			: undefined;
+	const isE2E = process.env.VITE_E2E === '1';
+	const usesSameOriginLedger = Boolean(localLedgerCredential) || isE2E;
+	// The dev proxy needs both: the renderer's address and its bearer token (from .dev.vars or the environment).
+	const invoiceRendererOrigin = readDevVar('INVOICE_RENDERER_ORIGIN');
+	const invoiceRendererToken =
+		command === 'serve' && mode === 'development' && invoiceRendererOrigin
+			? readDevVar('INVOICE_RENDERER_TOKEN')
+			: undefined;
+
+	const localLedgerProxy: Record<string, ProxyOptions> = localLedgerCredential
+		? {
+				[localLedgerGatewayPath]: {
+					target: localLedgerCredential.baseUrl,
+					changeOrigin: false,
+					ws: true,
+					rewrite: (path) =>
+						path.slice(localLedgerGatewayPath.length) || '/',
+					configure: (proxy) => {
+						proxy.on('proxyReq', (proxyRequest, request) => {
+							if (
+								!localGatewayOriginAllowed(
+									request.headers.origin,
+									request.headers.host,
+								)
+							) {
+								proxyRequest.destroy();
+								return;
+							}
+							proxyRequest.setHeader(
+								'Authorization',
+								`Bearer ${localLedgerCredential.token}`,
+							);
+							// The deployed Worker stamps the verified Access email; locally
+							// there is no Access, so use the same identity the client shows.
+							proxyRequest.setHeader('X-Ledger-Actor', 'local@localhost');
+							proxyRequest.removeHeader('Origin');
+						});
+						proxy.on('proxyReqWs', (proxyRequest, request) => {
+							if (
+								!localGatewayOriginAllowed(
+									request.headers.origin,
+									request.headers.host,
+								)
+							) {
+								proxyRequest.destroy();
+								return;
+							}
+							proxyRequest.setHeader(
+								'Authorization',
+								`Bearer ${localLedgerCredential.token}`,
+							);
+							proxyRequest.removeHeader('Origin');
+						});
+					},
+				},
+			}
+		: {};
+	const localInvoiceRendererProxy: Record<string, ProxyOptions> =
+		invoiceRendererToken
+			? {
+				[localInvoiceRendererPath]: {
+					target: invoiceRendererOrigin as string,
+					changeOrigin: true,
+					configure: (proxy) => {
+						proxy.on('proxyReq', (proxyRequest, request) => {
+							if (
+								!localGatewayOriginAllowed(
+									request.headers.origin,
+									request.headers.host,
+								)
+							) {
+								proxyRequest.destroy();
+								return;
+							}
+							proxyRequest.setHeader(
+								'Authorization',
+								`Bearer ${invoiceRendererToken}`,
+							);
+							proxyRequest.removeHeader('Origin');
+							proxyRequest.removeHeader('Referer');
+						});
+					},
+				},
+			}
+		: {};
+	const e2eLedgerProxy = isE2E ? {} : localLedgerProxy;
+	const devServerProxy =
+		(localLedgerCredential && !isE2E) || invoiceRendererToken
+			? { proxy: { ...e2eLedgerProxy, ...localInvoiceRendererProxy } }
+			: undefined;
+
+	return {
+		define: {
+			__BUILD_TIMESTAMP__: JSON.stringify(buildTimestamp),
+			__STACK_INFO__: JSON.stringify(stackInfo),
+			// The browser always uses a same-origin gateway. The ignored
+			// deployment credential stays in the Vite server process.
+			...(usesSameOriginLedger
+				? {
+						'import.meta.env.VITE_LEDGER_SERVICE_URL':
+							JSON.stringify(localLedgerGatewayPath),
+					}
+				: {}),
+			...(usesSameOriginLedger || command === 'build'
+				? { 'import.meta.env.VITE_LEDGER_AUTH_TOKEN': 'undefined' }
+				: {}),
+		},
+		server: {
+			...devServerProxy,
+			// Module and SDK sources live outside src/; Kit's default list omits them.
+			fs: { allow: [resolve('modules'), resolve('packages')] }
+		},
+		resolve: {
+			alias: {
+				// Dedicated namespace so a tenant build can swap in its generated module.
+				'$tenant/generated': resolve(tenantGeneratedModule),
+			},
+		},
+		cacheDir: process.env.STOR_VITE_CACHE_DIR?.trim() || 'node_modules/.vite',
+        plugins: [
+                tailwindcss(),
+                sveltekit({
+                        preprocess: vitePreprocess({ script: true }),
+                        outDir: svelteKitOutDir,
+                        files: hostFiles,
+                        // Registration is deliberately scheduled by #lib/pwa/registration
+                        // after local-store bootstrap; Kit's eager registration would
+                        // bypass it.
+                        serviceWorker: {
+                                register: false
+                        },
+                        adapter: adapter({
+                                pages: buildDirectory,
+                                assets: buildDirectory,
+                                fallback: 'index.html'
+                        }),
+                        compilerOptions: {
+                                experimental: {
+                                        async: true
+                                },
+                                warningFilter: (warning) => !warning.filename?.includes('node_modules') && !warning.code.startsWith('a11y')
+                        }
+                }),
+                entityGeneratorPlugin(),
+                tenantManifestPlugin(),
+                workerAssetsPlugin(svelteKitOutDir),
+                localLedgerOriginGuardPlugin(Boolean(localLedgerCredential)),
+                localInvoicePdfGatewayFallbackPlugin(Boolean(invoiceRendererToken)),
+                localReceivedInvoiceFilesPlugin(),
+                localInvoiceExtractionPlugin(),
+                localAiDecisionsPlugin(isE2E),
+                e2eLedgerStubPlugin(isE2E),
+                Icons({
+			compiler: 'svelte',
+		}),
+		{
+			name: 'configure-response-headers',
+			configureServer: (server) => {
+				server.middlewares.use((_req, res, next) => {
+					res.setHeader('Cross-Origin-Embedder-Policy', 'require-corp');
+					res.setHeader('Cross-Origin-Opener-Policy', 'same-origin');
+					next();
+				});
+			},
+			configurePreviewServer: (server) => {
+				server.middlewares.use((_req, res, next) => {
+					res.setHeader('Cross-Origin-Embedder-Policy', 'require-corp');
+					res.setHeader('Cross-Origin-Opener-Policy', 'same-origin');
+					next();
+				});
+			},
+		},
+	],
+	optimizeDeps: {
+		exclude: ['sqlocal', 'microlighter']
+	},
+	build: {
+		// Bundle Microlighter's lazy grammars, which Vite skips in dependencies by default.
+		dynamicImportVarsOptions: {
+			exclude: [/node_modules\/(?!microlighter\/|\.pnpm\/microlighter@)/],
+		},
+	},
+	worker: {
+		format: "es"
+	},
+		...(options.test ? { test: options.test } : {}),
+	};
+});
+}

package/src/vite/dev-plugins.ts

@@ -0,0 +1,338 @@
+/**
+ * The Vite plugins that stand in for the Worker during local development and the hermetic browser journeys:
+ * the Ledger gateway origin guard, the invoice PDF, received-file, and extraction routes, the AI decisions
+ * route, and the Ledger stub. None of them runs in a build.
+ */
+
+import type { Plugin } from 'vite';
+
+import { localGatewayOriginAllowed } from '../dev/local-development.js';
+
+export const localLedgerGatewayPath = '/api/ledger';
+export const localInvoiceRendererPath = '/api/invoice-generation';
+
+export function localLedgerOriginGuardPlugin(enabled: boolean): Plugin {
+	return {
+		name: 'local-ledger-origin-guard',
+		configureServer(server) {
+			if (!enabled) return;
+			server.middlewares.use((request, response, next) => {
+				if (!isLedgerGatewayRequest(request.url)) return next();
+				if (
+					localGatewayOriginAllowed(
+						request.headers.origin,
+						request.headers.host,
+					)
+				) {
+					return next();
+				}
+				response.statusCode = 403;
+				response.setHeader('Content-Type', 'application/json');
+				response.end(
+					JSON.stringify({
+						error: 'Cross-origin local Ledger requests are not allowed',
+						code: 'origin_not_allowed',
+					}),
+				);
+			});
+			server.httpServer?.prependListener('upgrade', (request, socket) => {
+				if (
+					!isLedgerGatewayRequest(request.url) ||
+					localGatewayOriginAllowed(
+						request.headers.origin,
+						request.headers.host,
+					)
+				) {
+					return;
+				}
+				request.url = '/__rejected-local-ledger-upgrade';
+				socket.write(
+					'HTTP/1.1 403 Forbidden\r\n' +
+						'Connection: close\r\n' +
+						'Content-Length: 0\r\n\r\n',
+				);
+				socket.destroy();
+			});
+		},
+	};
+}
+
+export function isLedgerGatewayRequest(url: string | undefined): boolean {
+	if (!url) return false;
+	const pathname = new URL(url, 'http://local.invalid').pathname;
+	return (
+		pathname === localLedgerGatewayPath ||
+		pathname.startsWith(`${localLedgerGatewayPath}/`)
+	);
+}
+
+/**
+ * Local dev runs the static app without the Stor Worker or R2. The cached
+ * `/api/invoice-generation/logs/*` routes therefore fall back to the
+ * stateless renderer (POST) and accept scoped cleanup (DELETE) locally, while
+ * production and staging always use the Worker's cache.
+ */
+export function localInvoicePdfGatewayFallbackPlugin(enabled: boolean): Plugin {
+	return {
+		name: 'local-invoice-pdf-gateway-fallback',
+		configureServer(server) {
+			if (!enabled) return;
+			server.middlewares.use((request, response, next) => {
+				if (!request.url) return next();
+				const method = request.method?.toUpperCase();
+				if (method !== 'POST' && method !== 'DELETE') return next();
+				const url = new URL(request.url, 'http://local.invalid');
+				const scoped = url.pathname.match(
+					/^\/api\/invoice-generation\/logs\/[0-9a-fA-F-]+\/(?:pdf|invoices\/[0-9a-zA-Z_-]+)$/,
+				);
+				if (!scoped) return next();
+				if (method === 'DELETE') {
+					response.statusCode = 204;
+					response.setHeader('Cache-Control', 'no-store');
+					response.end();
+					return;
+				}
+				request.url = `${localInvoiceRendererPath}/pdf${url.search}`;
+				next();
+			});
+		},
+	};
+}
+
+/**
+ * The app's Worker/R2 binding is absent in Vite dev. Keep original received
+ * PDF and ISDOC originals in this server process so the same-origin upload and
+ * preview flow can be exercised locally; the browser's IndexedDB copy remains
+ * the offline one.
+ */
+export function localReceivedInvoiceFilesPlugin(): Plugin {
+    const files = new Map<string, { bytes: Buffer; name: string; contentType: string }>();
+    const pdfRoute = /^\/api\/received-invoice-files\/v1\/logs\/[0-9a-fA-F-]{36}\/invoices\/[0-9a-fA-F-]{36}\/files\/[0-9a-fA-F-]{36}$/;
+    const isdocRoute = /^\/api\/received-invoice-files\/v1\/logs\/[0-9a-fA-F-]{36}\/invoices\/[0-9a-fA-F-]{36}\/isdoc\/[0-9a-fA-F-]{36}$/;
+    return {
+        name: 'local-received-invoice-files',
+        configureServer(server) {
+            server.middlewares.use(async (request, response, next) => {
+                if (!request.url) return next();
+                const url = new URL(request.url, 'http://local.invalid');
+                const isPdf = pdfRoute.test(url.pathname);
+                const isIsdoc = !isPdf && isdocRoute.test(url.pathname);
+                if (!isPdf && !isIsdoc) return next();
+                const maxBytes = isPdf ? 25 * 1024 * 1024 : 5 * 1024 * 1024;
+                const contentType = isPdf ? 'application/pdf' : 'application/xml; charset=utf-8';
+                const defaultName = isPdf ? 'invoice.pdf' : 'invoice.isdoc';
+                response.setHeader('Cache-Control', 'no-store');
+                response.setHeader('X-Content-Type-Options', 'nosniff');
+                if (request.method === 'GET') {
+                    const file = files.get(url.pathname);
+                    if (!file) { response.statusCode = 404; response.end('File not found'); return; }
+                    response.setHeader('Content-Type', file.contentType);
+                    response.setHeader('Content-Disposition', `${url.searchParams.get('download') === '1' ? 'attachment' : 'inline'}; filename="${file.name.replace(/["\\]/g, '_')}"`);
+                    response.end(file.bytes);
+                    return;
+                }
+                if (request.method !== 'PUT') { response.statusCode = 405; response.end(); return; }
+                const incomingType = request.headers['content-type']?.split(';', 1)[0].trim().toLowerCase();
+                const typeAccepted = isPdf
+                    ? incomingType === 'application/pdf'
+                    : ['application/xml', 'application/x-isdoc', 'text/xml'].includes(incomingType ?? '');
+                if (!typeAccepted) { response.statusCode = 415; response.end(isPdf ? 'Upload a PDF' : 'Upload ISDOC XML'); return; }
+                const chunks: Buffer[] = [];
+                let size = 0;
+                for await (const chunk of request) {
+                    size += chunk.length;
+                    if (size > maxBytes) { response.statusCode = 413; response.end('File too large'); return; }
+                    chunks.push(chunk);
+                }
+                const bytes = Buffer.concat(chunks);
+                if (!hasValidSignature(bytes, isPdf)) {
+                    response.statusCode = 415;
+                    response.end(isPdf ? 'Invalid PDF' : 'Invalid ISDOC XML');
+                    return;
+                }
+                let name = String(request.headers['x-stor-filename'] ?? defaultName);
+                try { name = decodeURIComponent(name); } catch { /* keep encoded value */ }
+                name = name.replace(/[\u0000-\u001f\u007f/\\]/g, '_').slice(0, 180) || defaultName;
+                if (!files.has(url.pathname)) files.set(url.pathname, { bytes, name, contentType });
+                response.setHeader('Content-Type', 'application/json');
+                response.end(JSON.stringify({ fileId: url.pathname.split('/').at(-1), size: files.get(url.pathname)!.bytes.length, etag: 'local' }));
+            });
+        },
+    };
+}
+
+/** Matches the Worker's upload signature checks for local dev. */
+export function hasValidSignature(bytes: Buffer, isPdf: boolean): boolean {
+    if (isPdf) return bytes.subarray(0, 5).toString() === '%PDF-';
+    let index = bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf ? 3 : 0;
+    while (index < bytes.length && [0x09, 0x0a, 0x0d, 0x20].includes(bytes[index]!)) index += 1;
+    return index < bytes.length && bytes[index] === 0x3c;
+}
+
+/**
+ * Local dev runs without the Worker, its Access session and its secrets. The
+ * extraction route answers 503 with the same error shape as the deployed
+ * Worker when no credential is configured, so the UI hides its AI button
+ * instead of parsing the SPA fallback. AI reading is exercised against a
+ * deployed environment where INVOICE_EXTRACTION_* is provisioned.
+ */
+export function localInvoiceExtractionPlugin(): Plugin {
+    const route = /^\/api\/received-invoice-extraction\/v1\/logs\/[0-9a-fA-F-]{36}$/;
+    return {
+        name: 'local-invoice-extraction',
+        configureServer(server) {
+            server.middlewares.use((request, response, next) => {
+                if (!request.url) return next();
+                const url = new URL(request.url, 'http://local.invalid');
+                if (!route.test(url.pathname)) return next();
+                response.setHeader('Cache-Control', 'no-store');
+                response.setHeader('X-Content-Type-Options', 'nosniff');
+                response.setHeader('Content-Type', 'application/json; charset=utf-8');
+                response.statusCode = 503;
+                response.end(JSON.stringify({
+                    code: 'extraction_unconfigured',
+                    error: 'AI invoice reading runs in the deployed Worker; complete the form manually in local development.',
+                }));
+            });
+        },
+    };
+}
+
+/**
+ * Local dev has no Workers AI binding. The decision route answers 503 with the
+ * deployed Worker's error shape, so the UI hides its suggestions. With
+ * VITE_E2E=1 it answers from a small deterministic table instead, keeping the
+ * browser journeys hermetic: known fixture names get a category at 0.95, and
+ * everything else is `none`.
+ */
+export function localAiDecisionsPlugin(deterministic: boolean): Plugin {
+    const route = /^\/api\/ai\/v1\/logs\/[0-9a-fA-F-]{36}\/decisions\/(category-pick|invoice-expense-type)$/;
+    const categories: Array<[RegExp, string]> = [
+        [/albert|billa|tesco|grocer/i, 'food'],
+        [/shell|fuel|taxi/i, 'transport'],
+        [/netflix|spotify/i, 'subscriptions'],
+        [/pharmacy|doctor/i, 'health'],
+    ];
+    const expenseTypes: Array<[RegExp, string]> = [
+        [/jetbrains|software|licen[cs]e/i, 'software'],
+        [/telecom|internet|mobile/i, 'telecom'],
+    ];
+    return {
+        name: 'local-ai-decisions',
+        configureServer(server) {
+            server.middlewares.use(async (request, response, next) => {
+                if (!request.url) return next();
+                const url = new URL(request.url, 'http://local.invalid');
+                const match = route.exec(url.pathname);
+                if (!match) return next();
+                response.setHeader('Cache-Control', 'no-store');
+                response.setHeader('X-Content-Type-Options', 'nosniff');
+                response.setHeader('Content-Type', 'application/json; charset=utf-8');
+                if (!deterministic) {
+                    response.statusCode = 503;
+                    response.end(JSON.stringify({
+                        code: 'ai_unconfigured',
+                        error: 'AI decisions run in the deployed Worker; choose values manually in local development.',
+                    }));
+                    return;
+                }
+                const body = await readJsonBody(request);
+                const items = Array.isArray(body?.items) ? body.items as Array<Record<string, unknown>> : [];
+                const table = match[1] === 'category-pick' ? categories : expenseTypes;
+                response.end(JSON.stringify({
+                    model: 'e2e-table',
+                    decisions: items.map((item) => {
+                        const text = `${item.name ?? ''} ${item.supplier ?? ''} ${item.description ?? ''}`;
+                        const hit = table.find(([pattern]) => pattern.test(text));
+                        return { id: item.id, option: hit ? hit[1] : 'none', probability: hit ? 0.95 : 0 };
+                    }),
+                }));
+            });
+        },
+    };
+}
+
+/**
+ * E2E runs without the Ledger Worker. The app still initializes its Ledger
+ * client (session, log selection, event downloads) before local data opens, so
+ * the dev server answers the read-only contract deterministically. Network
+ * sync is disabled in E2E, and reference tests overlay their own stateful
+ * browser-level mocks; this keeps `pnpm test` from depending on `ledger:dev`.
+ */
+export function e2eLedgerStubPlugin(enabled: boolean): Plugin {
+    const gateway = '/api/ledger';
+    // A UUID-shaped log id keeps the local file and PDF middlewares
+    // (received-invoice files, invoice generation, extraction) matching.
+    const logId = 'e2e00000-0000-4000-8000-000000000000';
+    const session = {
+        appId: 'e2e',
+        principalId: 'owner',
+        capabilities: ['action-metadata-v1', 'workspace-restore-v1', 'event-excision-v1'],
+    };
+    const logs = {
+        logs: [{ id: logId, name: 'default', headVersion: 0, lastUpdatedAt: null }],
+    };
+    return {
+        name: 'e2e-ledger-stub',
+        configureServer(server) {
+            if (!enabled) return;
+            server.middlewares.use(async (request, response, next) => {
+                if (!request.url) return next();
+                const url = new URL(request.url, 'http://local.invalid');
+                if (url.pathname !== gateway && !url.pathname.startsWith(`${gateway}/`)) {
+                    return next();
+                }
+                const method = (request.method ?? 'GET').toUpperCase();
+                const suffix = url.pathname.slice(gateway.length);
+                const respond = (status: number, body: unknown) => {
+                    response.statusCode = status;
+                    response.setHeader('Cache-Control', 'no-store');
+                    response.setHeader('Content-Type', 'application/json; charset=utf-8');
+                    response.end(JSON.stringify(body));
+                };
+                if (method === 'POST' && suffix.endsWith('/events')) {
+                    // Acknowledge appends so the durable outbox can drain without
+                    // a real Ledger. The stub is intentionally stateless: E2E
+                    // resets its local database per test, so replayed events
+                    // must not leak between tests.
+                    const body = await readJsonBody(request);
+                    const events = Array.isArray(body?.events) ? body.events : [];
+                    const actionId = typeof body?.actionId === 'string' ? body.actionId : undefined;
+                    const stored = events.map((event: Record<string, unknown>, index: number) => ({
+                        ...event,
+                        entityVersion: (Number(event.baseEntityVersion) || 0) + 1,
+                        version: index + 1,
+                        ...(actionId
+                            ? { action: { id: actionId, index, size: events.length } }
+                            : {}),
+                    }));
+                    respond(200, { newVersion: stored.length, events: stored });
+                    return;
+                }
+                if (method !== 'GET') return next();
+                let body: unknown;
+                if (suffix === '/session') body = session;
+                else if (suffix === '/logs') body = logs;
+                else if (suffix.endsWith('/events')) body = { events: [] };
+                else {
+                    respond(404, { error: 'Not found', code: 'not_found' });
+                    return;
+                }
+                respond(200, body);
+            });
+        },
+    };
+}
+
+export async function readJsonBody(request: import('node:http').IncomingMessage): Promise<Record<string, unknown> | undefined> {
+    const chunks: Buffer[] = [];
+    for await (const chunk of request) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    if (chunks.length === 0) return undefined;
+    try {
+        return JSON.parse(Buffer.concat(chunks).toString('utf8')) as Record<string, unknown>;
+    } catch {
+        return undefined;
+    }
+}