create-flowdular 0.4.3 → 0.6.0

package/template/default/infra/vercel/README.md

@@ -0,0 +1,262 @@
+# Vercel deployment
+
+One command provisions the database, storage and keys, deploys to Vercel
+Production and prints a one-time token; the first workspace is then created in
+the browser.
+
+## Hobby or Pro
+
+|                                                                                                                                 | Hobby                                   | Pro                   |
+| ------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | --------------------- |
+| Work a request queues (agent runs, renders, notifications, imports, exports)                                                    | starts within seconds                   | starts within seconds |
+| Time-driven work (scheduled automations, retries and recovery after a lost lease, approval expiries, retention sweeps, digests) | next request or the daily 03:00 UTC run | within about a minute |
+| Longest agent run                                                                                                               | about 4 minutes                         | about 12 minutes      |
+| Allowed use                                                                                                                     | personal, non-commercial                | commercial            |
+
+On Hobby, an external scheduler can tick the worker every minute instead: have
+it call `GET https://<domain>/api/internal/worker/tick` with the header
+`Authorization: Bearer <CRON_SECRET>`. The secret then also lives at that third
+party.
+
+## Prerequisites
+
+1. Node.js 24 and pnpm 11, then `pnpm install` in this repository.
+2. A Vercel account. The repository does not need to be pushed: the command
+   uploads this directory.
+3. The Vercel CLI 62 or newer (verified with 62.2.0): `npm i -g vercel`.
+4. `vercel login`.
+
+## Deploy with one command
+
+1. `pnpm flowdular deploy plan vercel` checks the Vercel CLI and `.vercelignore`
+   and lists every step. It changes nothing.
+2. `pnpm flowdular deploy start vercel --apply` runs those steps. Answer the
+   Vercel prompts it shows while linking the project and adding Neon.
+
+Flags that matter:
+
+- `--project <name>` names the Vercel project to create or link.
+- `--scope <team>` picks the team when the account has several.
+- `--plan hobby|pro` sets the plan. Without it the command reads the team's plan
+  from `vercel whoami --json` (Enterprise counts as Pro). When that gives no
+  answer it sizes for Pro, and if Vercel then rejects the per-minute cron it
+  switches to Hobby and deploys once more.
+- `--origin https://erp.example.com` when production is served from your own
+  domain instead of `<project>.vercel.app`.
+- `--database-url-env NAME` uses an existing PostgreSQL instead of Neon. Run
+  `read -rs FD_OWNER_URL && export FD_OWNER_URL`, paste the owner URL (it stays
+  out of shell history), then pass `--database-url-env FD_OWNER_URL`. A URL is
+  never accepted on the command line. A database created by Flowdular 0.5 or
+  earlier is refused before anything is created; use a new database.
+- `--cron "<expression>"` overrides the worker schedule the plan sets.
+
+A rerun resumes after any failure and never regenerates a key that the backup or
+Vercel already holds. If the Vercel CLI fails after it created the deployment,
+for example with `Error: fetch failed` while streaming build logs, the command
+follows that deployment on Vercel for up to 15 minutes and carries on once it
+is Ready.
+
+## What it prints and what to back up
+
+1. Progress lines and the Vercel build output, with every secret value replaced
+   by `[redacted]`.
+2. A summary: the URL, the key backup path, the plan, the worker schedule, the
+   setup address, the setup token and the file that holds it.
+3. Copy `.flowdular/deploy/vercel-<project id>.env` (mode 0600) to a password
+   manager or encrypted storage off this machine. Vercel cannot show a sensitive
+   value again, so this file is the only readable copy of the keys.
+4. Until the first workspace exists, the setup token is kept in
+   `.flowdular/deploy/vercel-<project id>.setup-token` (mode 0600), written
+   before its SHA-256 is uploaded as `FD_SETUP_TOKEN_SHA256`. The command names
+   that file before it deploys and in every failure, so a failed run never loses
+   the token. A rerun before setup reuses it; the first run after setup deletes
+   the file and removes `FD_SETUP_TOKEN_SHA256` from Vercel.
+
+## Create the first workspace
+
+1. Open the printed address, `https://<domain>/setup`, and paste the setup token.
+2. Enter the workspace name and address, then your name, email and password.
+   The database step is skipped because the deployment provides it.
+3. Review and choose **Migrate and create workspace**.
+4. Choose **Go to sign in** and sign in. The app serves normally from the next
+   request, with no redeploy.
+5. Optional: connect an AI model key under Providers.
+
+## Check that it works
+
+1. `curl -s https://<domain>/api/ready` answers HTTP 200 with
+   `"status":"ready"`.
+2. The project's Cron Jobs settings page lists `/api/internal/worker/tick` with
+   `* * * * *` on Pro or `0 3 * * *` on Hobby.
+3. The project's Logs, filtered to `/api/internal/worker/tick`, show a tick
+   after each cron run and after each state-changing request.
+4. In the agents playground, queue a run and watch it finish. The worker badge
+   there reads "worker offline" on Vercel, because it reports the web Function,
+   which never runs workers; the run finishing is the check.
+
+## Move from Hobby to Pro
+
+1. Upgrade the team in the Vercel dashboard.
+2. `pnpm flowdular deploy start vercel --apply` reads Pro, sets
+   `FD_VERCEL_PLAN=pro` and redeploys. Pass `--plan pro` if it cannot read the
+   plan.
+3. If you set `FD_VERCEL_CRON_SCHEDULE` yourself, remove it with
+   `vercel env rm FD_VERCEL_CRON_SCHEDULE production --yes` and run step 2
+   again.
+
+## Redeploy after a code change
+
+1. `pnpm flowdular deploy start vercel --apply` deploys the working directory
+   and reuses everything else, or `vercel deploy --prod` deploys the code alone.
+2. A project connected to Git also deploys on every push to its production
+   branch.
+
+## Rotate CRON_SECRET
+
+1. Delete the `CRON_SECRET=` line from the key backup file.
+2. `vercel env rm CRON_SECRET production --yes`
+3. `pnpm flowdular deploy start vercel --apply` generates a new secret into the
+   backup, uploads it and redeploys. Vercel Cron uses it from that deployment.
+4. Give the new value to any external scheduler.
+
+## Manual path
+
+1. `vercel link` at the repository root, or import the project from the URL
+   `pnpm flowdular deploy plan vercel` prints. Select Node.js 24.
+2. Provision PostgreSQL and use the direct host, not a PgBouncer pooler: the
+   platform sends statement and lock timeouts as startup parameters, which a
+   pooler refuses.
+3. As the database owner, create `flowdular_runtime` and `flowdular_background`
+   without `SUPERUSER` or `BYPASSRLS` and grant what
+   `infra/docker/postgres/10-roles.sh` grants. The owner role is the migrator.
+4. Generate each stable key with `openssl rand -base64 32`, except
+   `FD_AUTH_MFA_KEY`: `openssl rand -base64 32 | tr '+/' '-_' | tr -d '='`.
+   Keep them in a 0600 file off the machine.
+5. Generate `CRON_SECRET` with `openssl rand -hex 32`.
+6. Add every Production variable below through stdin, for example
+   `printf '%s' "$VALUE" | vercel env add NAME production --sensitive`:
+   - `FD_DATABASE_ADAPTER=postgresql`
+   - `FD_DATABASE_URL` (runtime role), `FD_DATABASE_BACKGROUND_URL` (background
+     role), `FD_DATABASE_MIGRATOR_URL` (owner)
+   - `FD_DATABASE_TLS=verify-full`, plus `FD_DATABASE_TLS_CA` or
+     `FD_DATABASE_TLS_CA_FILE` when the server certificate is not publicly
+     trusted
+   - `FD_STORAGE_ADAPTER=vercel-blob` and `FD_STORAGE_MAX_OBJECT_BYTES=4194304`,
+     or `FD_STORAGE_ADAPTER=s3` with `FD_STORAGE_S3_BUCKET`,
+     `FD_STORAGE_S3_REGION`, `FD_STORAGE_S3_ACCESS_KEY_ID` and
+     `FD_STORAGE_S3_SECRET_ACCESS_KEY`
+   - `FD_AGENT_CREDENTIAL_KEY`, `FD_AGENT_RUN_GRANT_KEY`, `FD_AUTH_MFA_KEY`,
+     `FD_APPROVAL_GRANT_KEY`, `FD_AUTOMATIONS_CREDENTIAL_KEY`,
+     `FD_NOTIFICATIONS_SECRET_KEY`, `FD_WORKFLOWS_PAYLOAD_KEY`,
+     `FD_WORKFLOWS_CURSOR_KEY`, `FD_STORAGE_ENCRYPTION_KEY`,
+     `FD_CONNECTORS_SECRET_KEY`, `FD_AUDIT_ANCHOR_KEY`
+   - `CRON_SECRET`
+   - `FD_AUTH_PUBLIC_ORIGIN=https://<domain>`
+   - `FD_VERCEL_PLAN=hobby` or `pro`; optionally `FD_VERCEL_CRON_SCHEDULE` and
+     `FD_WORKER_TICK_WINDOW_MS`
+7. For Blob storage, `vercel storage create <name> --type blob --access private`,
+   then `vercel storage connect <store id> --environment production --yes`.
+8. Make a setup token and store only its hash:
+   `TOKEN=$(openssl rand -base64 32 | tr '+/' '-_' | tr -d '=')`, then
+   `printf '%s' "$TOKEN" | shasum -a 256 | cut -d' ' -f1 | tr -d '\n' | vercel env add FD_SETUP_TOKEN_SHA256 production --sensitive`.
+9. `vercel deploy --prod`.
+10. Open `https://<domain>/setup` and enter `$TOKEN`.
+
+Scope preview variables to a separate database, store, keys and setup token;
+otherwise preview code can migrate or mutate production data.
+
+## Tear down
+
+1. Delete the Neon database and every row in it with
+   `vercel integration resource remove <resource> --disconnect-all --yes`; the
+   resource name is on the project's Storage tab.
+2. `vercel storage delete <project>-files --type blob` deletes the Blob store
+   after a confirmation.
+3. `vercel project rm <project>`.
+4. Remove `.vercel`, and destroy every copy of the key backup once the data is
+   gone.
+
+## Troubleshooting
+
+- **"Hobby accounts are limited to daily cron jobs"**: the team is on Hobby and
+  the build asked for a tighter cron. Rerun with `--plan hobby`, or remove a
+  tighter `FD_VERCEL_CRON_SCHEDULE`.
+- **`/api/ready` answers 503**: the database or its role check failed. Check the
+  web Function logs, the three database URLs and that the Neon compute is up. A
+  500 on every path means boot failed, and the log line `platform boot failed`
+  names the cause, such as a missing `FD_SETUP_TOKEN_SHA256` while no workspace
+  exists.
+- **The setup page refuses the token**: use the token in
+  `.flowdular/deploy/vercel-<project id>.setup-token`, which every run before
+  setup reuses. If that file was deleted, the next run made a new token and only
+  that one works. Five wrong tries lock that instance for five minutes. If the page asks for the token again after a step, the request
+  reached another Function instance, which holds its own setup session; enter the
+  token again and repeat that step.
+- **`Failed to connect <owner>/<repo> to project` while linking**: harmless. The
+  command uploads this directory, so the deployment does not need Git; pushes
+  just do not deploy on their own. Connect the repository later in the
+  project's Settings, Git.
+- **Scheduled automations do not fire on Hobby**: between requests they wait
+  for the next request or the daily run. Move to Pro or add an external
+  scheduler (see [Hobby or Pro](#hobby-or-pro)).
+- **An agent run started over**: it outlived its tick, about 4 minutes on Hobby
+  or 12 on Pro, so Vercel stopped the Function and a later tick resumed the run
+  once its lease expired. Keep runs shorter or move to Pro.
+
+## How it runs
+
+Flowdular runs on Vercel as two Node.js Functions built from one server bundle.
+The `vercel.json` build command builds Octane, then writes a Build Output API
+artifact:
+
+- `functions/flowdular.func` serves HTTP with `FD_RUNTIME_ROLE=web`. It never
+  starts a module worker and never claims queued work.
+- `functions/worker.func` runs with `FD_RUNTIME_ROLE=tick` and answers only
+  `/api/internal/worker/tick`. Each tick starts every module worker, keeps them
+  running for one window and drains them before it answers.
+- `static` holds the public client assets. Pages stay behind Octane's
+  authentication.
+
+Two things tick the worker Function:
+
+- Vercel Cron calls the tick path with a 50 second window
+  (`FD_WORKER_TICK_WINDOW_MS`): every minute on Pro, once a day on Hobby.
+  Scheduled work and recovery of interrupted jobs run there.
+- After a state-changing `/api` request answers with a success status, the web
+  Function asks for a 15 second tick, so work a member just queued starts within
+  seconds instead of waiting for the next cron run. Repeated requests on one
+  instance ask at most once every 5 seconds, and a tick arriving while a window
+  is open joins it.
+
+Both callers present `CRON_SECRET` as a bearer token; the worker Function reads
+it as `FD_WORKER_TICK_SECRET`. Without a secret of at least 32 characters the
+worker Function refuses to boot.
+
+`FD_VERCEL_PLAN` sizes the build: the cron schedule, the worker Function's
+`maxDuration` (300 seconds on Hobby, 800 on Pro) and how long a tick waits for
+agent runs to finish (180 and 690 seconds). Until a workspace exists, the
+application answers only `/setup`, `/api/health`, `/api/ready` and the tick
+path, and each instance opens to everything on its next request after setup
+finishes.
+
+Cron runs only on the production deployment. A preview deployment ticks only
+from its own requests, and only when Deployment Protection lets the request
+through: enable Protection Bypass for Automation so the web Function can send
+`VERCEL_AUTOMATION_BYPASS_SECRET`.
+
+## Limits
+
+- A request or response body is capped at 4.5 MB, so keep
+  `FD_STORAGE_MAX_OBJECT_BYTES` at or below 4194304 until uploads go directly to
+  storage.
+- A tick drains its workers before it answers, within the worker Function's
+  `maxDuration`. An agent run claimed during the window keeps running for the
+  rest of the window and then up to 180 seconds on Hobby or 690 on Pro
+  (`FD_AGENT_WORKER_DRAIN_MS`). Work still running after that is stopped and
+  starts again from its input on a later tick once its lease expires, so a run
+  claimed at the end of a window is sure to finish only within 3 minutes on
+  Hobby and 11.5 on Pro.
+- `/api/ready` checks the database roles. It does not prove that ticks are
+  arriving; watch the Cron Jobs page and the worker Function logs.
+- The embedded sandbox and workspace file edits are local development features
+  and are not durable inside a Function.

package/template/default/infra/vercel/build.mjs

@@ -0,0 +1,214 @@
+import { spawnSync } from 'node:child_process';
+import {
+	cp,
+	lstat,
+	mkdir,
+	readdir,
+	readFile,
+	realpath,
+	rm,
+	writeFile,
+} from 'node:fs/promises';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const repositoryRoot = resolve(
+	dirname(fileURLToPath(import.meta.url)),
+	'../..',
+);
+const args = process.argv.slice(2);
+const rootFlag = args.indexOf('--root');
+const root = rootFlag < 0 ? repositoryRoot : resolve(args[rootFlag + 1] ?? '');
+const packageOnly = args.includes('--package-only');
+
+if (rootFlag >= 0 && !args[rootFlag + 1]) {
+	throw new Error('--root requires a directory.');
+}
+
+if (!packageOnly) {
+	const result = spawnSync('pnpm', ['build'], { cwd: root, stdio: 'inherit' });
+	if (result.error) throw result.error;
+	if (result.status !== 0) process.exit(result.status ?? 1);
+}
+
+const output = join(root, '.vercel/output');
+const functionRoot = join(output, 'functions/flowdular.func');
+const workerFunctionRoot = join(output, 'functions/worker.func');
+const WORKER_TICK_PATH = '/api/internal/worker/tick';
+/* Hobby runs cron at most once a day, fails a deployment with a tighter
+   schedule and caps a Function at 300 seconds; Pro and Enterprise run cron
+   every minute and allow 800. A tick's window plus the agent drain must end a
+   minute before maxDuration, or Vercel stops the Function mid-drain. */
+const PLANS = {
+	hobby: { schedule: '0 3 * * *', maxDuration: 300, agentDrainMs: 180_000 },
+	pro: { schedule: '* * * * *', maxDuration: 800, agentDrainMs: 690_000 },
+};
+const DRAIN_MARGIN_MS = 60_000;
+const planName = process.env.FD_VERCEL_PLAN?.trim() || 'pro';
+if (!Object.hasOwn(PLANS, planName)) {
+	throw new Error('FD_VERCEL_PLAN must be "hobby" or "pro".');
+}
+const plan = PLANS[planName];
+const cronSchedule =
+	process.env.FD_VERCEL_CRON_SCHEDULE?.trim() || plan.schedule;
+if (!/^\S+( \S+){4}$/.test(cronSchedule)) {
+	throw new Error(
+		'FD_VERCEL_CRON_SCHEDULE must be a five-field cron expression.',
+	);
+}
+const tickWindowMs = Number(
+	process.env.FD_WORKER_TICK_WINDOW_MS?.trim() || 50_000,
+);
+if (
+	tickWindowMs + plan.agentDrainMs + DRAIN_MARGIN_MS >
+	plan.maxDuration * 1000
+) {
+	throw new Error(
+		`FD_WORKER_TICK_WINDOW_MS leaves no time to drain agent runs within the ${plan.maxDuration} second ${planName} limit.`,
+	);
+}
+const staticRoot = join(output, 'static');
+const client = join(root, 'platform/dist/client');
+const server = join(root, 'platform/dist/server');
+
+async function assertInside(source, owner) {
+	const fromOwner = relative(await realpath(owner), await realpath(source));
+	if (!fromOwner || fromOwner.startsWith('..') || isAbsolute(fromOwner)) {
+		throw new Error(`${source} must stay inside ${owner}.`);
+	}
+}
+
+async function copyRegular(source, destination, owner = root) {
+	const entry = await lstat(source);
+	if (!entry.isFile() || entry.isSymbolicLink()) {
+		throw new Error(`${source} must be a regular file.`);
+	}
+	await assertInside(source, owner);
+	await mkdir(dirname(destination), { recursive: true });
+	await cp(source, destination);
+}
+
+async function copyOptional(source, destination) {
+	try {
+		await copyRegular(source, destination);
+	} catch (error) {
+		if (error.code !== 'ENOENT') throw error;
+	}
+}
+
+async function copyTree(source, destination) {
+	const entry = await lstat(source);
+	if (!entry.isDirectory() || entry.isSymbolicLink()) {
+		throw new Error(`${source} must be a directory.`);
+	}
+	await assertInside(source, root);
+	const pending = [source];
+	while (pending.length > 0) {
+		const directory = pending.pop();
+		for (const child of await readdir(directory, { withFileTypes: true })) {
+			const path = join(directory, child.name);
+			if (child.isDirectory()) pending.push(path);
+			else if (!child.isFile())
+				throw new Error(`${path} must be a regular file.`);
+		}
+	}
+	await cp(source, destination, { recursive: true, dereference: false });
+}
+
+await lstat(join(server, 'entry.js'));
+await lstat(join(client, 'assets'));
+try {
+	const vercelDirectory = await lstat(join(root, '.vercel'));
+	if (!vercelDirectory.isDirectory() || vercelDirectory.isSymbolicLink()) {
+		throw new Error('.vercel must be a directory inside the workspace.');
+	}
+} catch (error) {
+	if (error.code !== 'ENOENT') throw error;
+}
+await rm(output, { recursive: true, force: true });
+await mkdir(staticRoot, { recursive: true });
+await copyTree(join(client, 'assets'), join(staticRoot, 'assets'));
+for (const name of ['favicon.svg', 'og.png']) {
+	await copyOptional(join(client, name), join(staticRoot, name));
+}
+
+async function writeFunction(directory, runtimeRole) {
+	const tick = runtimeRole === 'tick';
+	await mkdir(directory, { recursive: true });
+	await copyTree(server, join(directory, 'platform/dist/server'));
+	await copyRegular(
+		join(root, 'platform/package.json'),
+		join(directory, 'platform/package.json'),
+	);
+	await copyRegular(
+		join(root, 'flowdular.json'),
+		join(directory, 'flowdular.json'),
+	);
+	for (const name of [
+		'flowdular.modules.lock.json',
+		'flowdular.module-sources.json',
+	]) {
+		await copyOptional(join(root, name), join(directory, name));
+	}
+	const modulesRoot = join(root, 'modules');
+	for (const entry of await readdir(modulesRoot, { withFileTypes: true })) {
+		if (!entry.isDirectory()) continue;
+		for (const name of ['module.json', 'spec/module.yaml']) {
+			await copyOptional(
+				join(modulesRoot, entry.name, name),
+				join(directory, 'modules', entry.name, name),
+			);
+		}
+	}
+	await copyRegular(
+		join(repositoryRoot, 'infra/vercel/handler.mjs'),
+		join(directory, 'handler.mjs'),
+		repositoryRoot,
+	);
+	await writeFile(
+		join(directory, '.vc-config.json'),
+		JSON.stringify({
+			runtime: 'nodejs24.x',
+			handler: 'handler.mjs',
+			launcherType: 'Nodejs',
+			maxDuration: tick ? plan.maxDuration : 300,
+			supportsResponseStreaming: true,
+			environment: {
+				NODE_ENV: 'production',
+				FD_DEPLOYMENT_TARGET: 'vercel',
+				FD_RUNTIME_ROLE: runtimeRole,
+				FD_TRUST_PROXY: 'true',
+				FD_AUTH_SECURE_COOKIE: 'true',
+				FD_DATABASE_POOL_MAX: '2',
+				...(tick
+					? { FD_AGENT_WORKER_DRAIN_MS: String(plan.agentDrainMs) }
+					: {}),
+			},
+		}) + '\n',
+	);
+}
+
+/* Two functions over one server build: the web function never runs a module
+   worker, and the worker function runs them only inside a tick. */
+await writeFunction(functionRoot, 'web');
+await writeFunction(workerFunctionRoot, 'tick');
+await writeFile(
+	join(output, 'config.json'),
+	JSON.stringify({
+		version: 3,
+		routes: [
+			{ src: `^${WORKER_TICK_PATH}$`, dest: '/worker' },
+			{ handle: 'filesystem' },
+			{ src: '/(.*)', dest: '/flowdular' },
+		],
+		crons: [{ path: WORKER_TICK_PATH, schedule: cronSchedule }],
+	}) + '\n',
+);
+
+/* The Build Output API function is self-contained. Static HTML is deliberately
+   excluded so the authenticated Octane route always owns page responses. */
+const manifest = JSON.parse(
+	await readFile(join(output, 'config.json'), 'utf8'),
+);
+if (manifest.version !== 3) throw new Error('Invalid Vercel build output.');
+console.log('Flowdular Vercel web artifact: .vercel/output');

package/template/default/infra/vercel/handler.mjs

@@ -0,0 +1,100 @@
+/* Vercel assigns a different origin to every preview. Read its own deployment
+   hostname before importing Octane, whose auth runtime captures the origin at boot. */
+process.env.NODE_ENV = 'production';
+process.env.FD_DEPLOYMENT_TARGET = 'vercel';
+process.env.FD_TRUST_PROXY = 'true';
+process.env.FD_AUTH_SECURE_COOKIE = 'true';
+if (!process.env.FD_AUTH_PUBLIC_ORIGIN && process.env.VERCEL_URL) {
+	const host = process.env.VERCEL_URL;
+	if (
+		!/^[-a-z0-9.]+$/i.test(host) ||
+		host.startsWith('.') ||
+		host.endsWith('.') ||
+		host.includes('..') ||
+		!host.includes('.')
+	) {
+		throw new Error('VERCEL_URL must be a hostname without a scheme or path.');
+	}
+	process.env.FD_AUTH_PUBLIC_ORIGIN = `https://${host}`;
+}
+
+/* Vercel Cron presents CRON_SECRET as its bearer token, so the tick secret is
+   that value unless the deployment names its own. */
+if (!process.env.FD_WORKER_TICK_SECRET && process.env.CRON_SECRET) {
+	process.env.FD_WORKER_TICK_SECRET = process.env.CRON_SECRET;
+}
+
+const { nodeHandler } = await import('./platform/dist/server/entry.js');
+
+const WORKER_TICK_PATH = '/api/internal/worker/tick';
+const KICK_INTERVAL_MS = 5_000;
+/* The worker function keeps running after this request hangs up: Vercel ends
+   an invocation on disconnect only for functions that opt into cancellation. */
+const KICK_HANDOFF_MS = 2_000;
+const REQUEST_CONTEXT = Symbol.for('@vercel/request-context');
+let lastKick = 0;
+
+function kickWorker(origin, secret) {
+	const now = Date.now();
+	if (now - lastKick < KICK_INTERVAL_MS) return Promise.resolve();
+	lastKick = now;
+	const headers = { authorization: `Bearer ${secret}` };
+	if (process.env.VERCEL_AUTOMATION_BYPASS_SECRET) {
+		headers['x-vercel-protection-bypass'] =
+			process.env.VERCEL_AUTOMATION_BYPASS_SECRET;
+	}
+	return fetch(new URL(WORKER_TICK_PATH, origin), {
+		method: 'POST',
+		headers,
+		signal: AbortSignal.timeout(KICK_HANDOFF_MS),
+	}).then(
+		(response) => response.body?.cancel(),
+		() => undefined,
+	);
+}
+
+/* The web function claims no queued work, so a request that changed state asks
+   the worker function for a short tick instead of leaving it to the next cron. */
+function withWorkerKick(handler) {
+	const origin = process.env.FD_AUTH_PUBLIC_ORIGIN;
+	const secret = process.env.FD_WORKER_TICK_SECRET;
+	if (process.env.FD_RUNTIME_ROLE !== 'web' || !origin || !secret) {
+		return handler;
+	}
+	return (request, response) => {
+		const waitUntil = globalThis[REQUEST_CONTEXT]?.get?.()?.waitUntil;
+		if (
+			waitUntil &&
+			!['GET', 'HEAD', 'OPTIONS'].includes(request.method) &&
+			request.url?.startsWith('/api/')
+		) {
+			waitUntil(
+				new Promise((resolve) => {
+					response.once('close', () => {
+						resolve(
+							response.statusCode < 400
+								? kickWorker(origin, secret)
+								: undefined,
+						);
+					});
+				}),
+			);
+		}
+		return handler(request, response);
+	};
+}
+
+/* Vercel terminates TLS before the function, and Octane's Node adapter builds
+   every request URL as http://<host>. An absolute https target keeps the
+   origin that same-origin checks compare against. */
+function withHttpsOrigin(handler) {
+	return (request, response) => {
+		const host = request.headers?.host;
+		if (host && request.url?.startsWith('/')) {
+			request.url = `https://${host}${request.url}`;
+		}
+		return handler(request, response);
+	};
+}
+
+export default withWorkerKick(withHttpsOrigin(nodeHandler));

package/template/default/modules/example/migrations/0001_example_core.up.sql

@@ -10,5 +10,5 @@ CREATE INDEX IF NOT EXISTS example_notes_tenant_created_idx ON example_notes (te
 ALTER TABLE example_notes ENABLE ROW LEVEL SECURITY;
 ALTER TABLE example_notes FORCE ROW LEVEL SECURITY;
 CREATE POLICY example_notes_tenant_policy ON example_notes
-  USING (tenant_id = current_setting('coreloom.tenant_id', true))
-  WITH CHECK (tenant_id = current_setting('coreloom.tenant_id', true));
+  USING (tenant_id = current_setting('flowdular.tenant_id', true))
+  WITH CHECK (tenant_id = current_setting('flowdular.tenant_id', true));

package/template/default/modules/example/module.json

@@ -4,7 +4,7 @@
 	"id": "example.core",
 	"package": "@app/module-example",
 	"version": "0.1.0",
-	"platformApi": "^0.1.0",
+	"platformApi": "^0.2.0",
 	"profile": "full",
 	"capabilities": ["api", "database", "client", "translations"],
 	"platform": {

package/template/default/modules/example/package.json

@@ -14,9 +14,9 @@
 		"test": "vitest run"
 	},
 	"dependencies": {
-		"octane": "0.1.51",
-		"segment-state": "0.2.1",
-		"@flowdular/sdk": "0.4.3"
+		"octane": "0.9.1",
+		"segment-state": "0.4.0",
+		"@flowdular/sdk": "0.6.0"
 	},
 	"devDependencies": {
 		"@tsrx/typescript-plugin": "0.3.120",

package/template/default/modules/example/spec/module.yaml

@@ -19,7 +19,7 @@ locales:
   - pl
 invariants:
   - Persistence runs on the shared asynchronous database contract. The module receives a leased handle from platform composition, never a driver or a connection string, and provides explicit SQL for every dialect it declares.
-  - The PostgreSQL notes table enables and forces row-level security with USING and WITH CHECK policies bound to transaction-local coreloom.tenant_id, and the runtime role holds neither SUPERUSER nor BYPASSRLS. Migrations use a separate lease.
+  - The PostgreSQL notes table enables and forces row-level security with USING and WITH CHECK policies bound to transaction-local flowdular.tenant_id, and the runtime role holds neither SUPERUSER nor BYPASSRLS. Migrations use a separate lease.
   - Every note is owned by exactly one tenant and every query uses the trusted tenant identifier.
 permissions:
   - id: example.notes.read

package/template/default/modules/example/src/services/migration.ts

@@ -16,8 +16,8 @@ CREATE INDEX IF NOT EXISTS example_notes_tenant_created_idx ON example_notes (te
 ALTER TABLE example_notes ENABLE ROW LEVEL SECURITY;
 ALTER TABLE example_notes FORCE ROW LEVEL SECURITY;
 CREATE POLICY example_notes_tenant_policy ON example_notes
-  USING (tenant_id = current_setting('coreloom.tenant_id', true))
-  WITH CHECK (tenant_id = current_setting('coreloom.tenant_id', true));
+  USING (tenant_id = current_setting('flowdular.tenant_id', true))
+  WITH CHECK (tenant_id = current_setting('flowdular.tenant_id', true));
 `;
 
 export const databaseMigrations: readonly DatabaseMigration[] = [

package/template/default/modules/example/tests/module.test.ts

@@ -61,7 +61,7 @@ describe('example.core migrations', () => {
 			const sql = migration.sql.postgresql ?? '';
 			expect(sql).toContain('ENABLE ROW LEVEL SECURITY');
 			expect(sql).toContain('FORCE ROW LEVEL SECURITY');
-			expect(sql).toContain("current_setting('coreloom.tenant_id', true)");
+			expect(sql).toContain("current_setting('flowdular.tenant_id', true)");
 			expect(sql).toContain('WITH CHECK');
 		}
 	});

package/template/default/package.json

@@ -9,7 +9,7 @@
 	},
 	"scripts": {
 		"dev": "node --env-file-if-exists=.env platform/scripts/dev.mjs",
-		"sandbox": "npx @flowdular/sandbox",
+		"sandbox": "flowdular-sandbox",
 		"typecheck": "pnpm -r --if-present typecheck",
 		"test": "pnpm -r --if-present test",
 		"format": "prettier --write .",
@@ -23,9 +23,10 @@
 		"build": "flowdular module sync --apply && pnpm --filter @app/platform build"
 	},
 	"devDependencies": {
+		"@flowdular/sandbox": "0.6.0",
 		"@tsrx/prettier-plugin": "0.3.120",
 		"prettier": "3.6.2",
-		"flowdular": "0.4.3",
+		"flowdular": "0.6.0",
 		"rulesync": "16.21.0"
 	}
 }