create-feltkit 0.3.1 → 0.3.2

package/template-managed/feltkit/_generated/api.ts

@@ -0,0 +1,9 @@
+/* Generated by `feltkit dev` / `feltkit codegen`. Do not edit; it is rewritten when feltkit/ changes. */
+/* eslint-disable */
+import { createApi } from "@feltdb/feltkit/client";
+import type * as app_module from "../app.js";
+import type * as items_module from "../items.js";
+import type * as system_module from "../system.js";
+
+/** Typed references to every query and mutation. Type-only imports: no backend code reaches the browser. */
+export const api = createApi<{ "app": typeof app_module; "items": typeof items_module; "system": typeof system_module }>();

package/template-managed/feltkit/app.ts

@@ -0,0 +1,40 @@
+import { feltkit, s } from "@feltdb/feltkit";
+
+/**
+ * A small inventory service whose state lives in Managed FeltDB.
+ *
+ * Nothing here knows where state lives: the same functions run on local FeltDB in
+ * development and tests, and on Managed FeltDB when FELTDB_URL, FELTDB_APPLICATION_ID and
+ * FELTDB_TOKEN are set (see README.md). No AppPort Services: an application that runs on
+ * Managed FeltDB declares every collection in its contract (`npm run contract`).
+ */
+export const app = feltkit({
+  name: "inventory",
+  roles: {
+    clerk: ["items.read", "items.write", "stock.adjust"],
+    auditor: ["items.read"],
+  },
+  dev: {
+    users: [
+      { id: "ada", name: "Ada Lovelace", roles: ["clerk"] },
+      { id: "grace", name: "Grace Hopper", roles: ["auditor"] },
+    ],
+  },
+});
+
+export const items = app.collection("items", {
+  sku: s.string({ minLength: 1, maxLength: 64 }),
+  name: s.string({ minLength: 1 }),
+  quantity: s.integer({ minimum: 0 }),
+  updatedAt: s.number(),
+});
+
+/** Every stock change, written in the same transaction as the item it changes. */
+export const movements = app.collection("movements", {
+  sku: s.string(),
+  delta: s.integer(),
+  quantityAfter: s.integer({ minimum: 0 }),
+  reason: s.string({ minLength: 1 }),
+  by: s.string(),
+  at: s.number(),
+});

package/template-managed/feltkit/items.ts

@@ -0,0 +1,55 @@
+import { s, fail } from "@feltdb/feltkit";
+import { app, items, movements } from "./app.js";
+
+const item = s.object({ id: s.string(), sku: s.string(), name: s.string(), quantity: s.integer(), updatedAt: s.number(), __version: s.integer() });
+
+export const list = app.query({
+  access: "items.read",
+  handler: (ctx) => ctx.db.find(items, {}, { orderBy: [{ field: "sku", direction: "asc" }], limit: 500 }),
+});
+
+export const get = app.query({
+  access: "items.read",
+  args: { sku: s.string() },
+  handler: async (ctx, { sku }) => (await ctx.db.find(items, { sku }, { limit: 1 }))[0] ?? null,
+});
+
+export const create = app.mutation({
+  access: "items.write",
+  args: { sku: s.string({ minLength: 1, maxLength: 64 }), name: s.string({ minLength: 1 }), quantity: s.integer({ minimum: 0 }) },
+  returns: s.string(),
+  capability: { name: "items.create", description: "Add an item to the inventory." },
+  handler: async (ctx, { sku, name, quantity }) => {
+    // The find is fenced: a concurrent create of the same SKU fails this commit with CONFLICT.
+    if ((await ctx.db.find(items, { sku }, { limit: 1 })).length) fail("CONFLICT", `An item with SKU ${sku} already exists.`);
+    const at = Date.now();
+    const id = await ctx.db.insert(items, { sku, name, quantity, updatedAt: at });
+    if (quantity > 0) await ctx.db.insert(movements, { sku, delta: quantity, quantityAfter: quantity, reason: "initial stock", by: ctx.auth.principal!.id, at });
+    return id;
+  },
+});
+
+export const adjust = app.mutation({
+  access: "stock.adjust",
+  args: { sku: s.string(), delta: s.integer(), reason: s.string({ minLength: 1 }) },
+  returns: item,
+  capability: { name: "stock.adjust", description: "Receive (positive delta) or remove (negative delta) stock for an item." },
+  handler: async (ctx, { sku, delta, reason }) => {
+    if (delta === 0) fail("INVALID_ARGUMENT", "delta must not be zero.");
+    const [current] = await ctx.db.find(items, { sku }, { limit: 1 });
+    if (!current) fail("NOT_FOUND", `No item with SKU ${sku}.`);
+    const quantity = current!.quantity + delta;
+    if (quantity < 0) fail("CONFLICT", `Only ${current!.quantity} of ${sku} in stock; cannot remove ${-delta}.`, { available: current!.quantity });
+    const at = Date.now();
+    // One FeltDB transaction: the item (fenced on the version read above) and its movement.
+    const updated = await ctx.db.patch(items, current!.id, { quantity, updatedAt: at });
+    await ctx.db.insert(movements, { sku, delta, quantityAfter: quantity, reason, by: ctx.auth.principal!.id, at });
+    return updated;
+  },
+});
+
+export const history = app.query({
+  access: "items.read",
+  args: { sku: s.string(), limit: s.optional(s.integer({ minimum: 1, maximum: 200 })) },
+  handler: (ctx, { sku, limit }) => ctx.db.find(movements, { sku }, { orderBy: [{ field: "at", direction: "desc" }], limit: limit ?? 50 }),
+});

package/template-managed/feltkit/system.ts

@@ -0,0 +1,14 @@
+import { app, items } from "./app.js";
+
+/**
+ * Verification for operators and deploy checks: answers only after an authenticated,
+ * bounded read of this application's state succeeds. It names the backend (its kind and
+ * origin), never a credential. `/_feltkit/health` is the unauthenticated liveness probe.
+ */
+export const status = app.query({
+  access: "items.read",
+  handler: async (ctx) => {
+    const sample = await ctx.db.find(items, {}, { limit: 1 });
+    return { environment: ctx.environment.name, storage: ctx.environment.storage, readable: true, empty: sample.length === 0 };
+  },
+});

package/template-managed/fly.toml

@@ -0,0 +1,28 @@
+# Fly.io deployment of the inventory service (`npm run deploy:fly -- --app <name>`).
+#
+# Managed FeltDB is an external service: nothing here provisions it. Non-secret settings
+# (FELTDB_URL, FELTDB_APPLICATION_ID) are passed at deploy from .feltdb/managed.json, and
+# FELTDB_TOKEN is a Fly secret imported from .env.local on stdin (scripts/deploy-fly.mjs).
+app = "feltkit-inventory"
+primary_region = "iad"
+
+[build]
+  dockerfile = "Dockerfile"
+
+[env]
+  PORT = "8080"
+  FELTDB_ENVIRONMENT = "production"
+
+[http_service]
+  internal_port = 8080
+  force_https = true
+  auto_stop_machines = "stop"
+  auto_start_machines = true
+  min_machines_running = 0
+
+  [[http_service.checks]]
+    grace_period = "30s"
+    interval = "15s"
+    method = "GET"
+    path = "/_feltkit/health"
+    timeout = "5s"

package/template-managed/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "feltkit-example-managed",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "description": "A FeltKit application whose state lives in Managed FeltDB.",
+  "scripts": {
+    "dev": "feltkit dev --no-frontend",
+    "build": "feltkit build",
+    "start": "feltkit start",
+    "test": "feltkit test",
+    "typecheck": "tsc --noEmit",
+    "contract": "feltkit contract",
+    "contract:check": "feltkit contract --check",
+    "managed:setup": "feltkit contract && feltdb init-managed --contract feltdb.contract.json --runtime-scopes minimal",
+    "managed:publish": "feltkit contract && feltdb publish --contract feltdb.contract.json",
+    "managed:session": "node scripts/managed-env.mjs session create --type service",
+    "managed:start": "feltkit build && node scripts/managed-env.mjs start",
+    "managed:test": "node scripts/managed-env.mjs --check && feltkit test tests/managed.live.test.ts",
+    "deploy:fly": "node scripts/deploy-fly.mjs"
+  },
+  "dependencies": {
+    "@feltdb/feltkit": "0.3.2"
+  },
+  "devDependencies": {
+    "@feltdb/core": "0.16.0",
+    "@types/node": "22.19.1",
+    "typescript": "5.9.3"
+  },
+  "overrides": {
+    "@appport/services": {
+      "@feltdb/core": "0.16.0"
+    }
+  }
+}

package/template-managed/scripts/deploy-fly.mjs

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+/**
+ * Deploy to Fly.io: the runtime key as a Fly secret (on stdin, never in a command line or
+ * output), the non-secret settings with the deploy, then `fly deploy` builds the Dockerfile.
+ *
+ *   npm run deploy:fly -- --app <fly-app-name>
+ *
+ * Needs `fly` (flyctl) signed in, and the managed settings `npm run managed:setup` wrote
+ * (.env.local) or the same variables in this process's environment.
+ */
+import { spawn, spawnSync } from "node:child_process";
+import { resolve } from "node:path";
+import { managedEnvironment, readEnvFile } from "./managed-env.mjs";
+
+function run(command, args, { input } = {}) {
+  return new Promise((done, fail) => {
+    const child = spawn(command, args, { stdio: [input === undefined ? "inherit" : "pipe", "inherit", "inherit"] });
+    child.once("error", fail);
+    if (input !== undefined) child.stdin.end(input);
+    child.once("exit", (code) => (code === 0 ? done() : fail(new Error(`${command} ${args[0]} ${args[1] ?? ""} exited with ${code}`))));
+  });
+}
+
+const args = process.argv.slice(2);
+const appIndex = args.indexOf("--app");
+const app = appIndex >= 0 ? args[appIndex + 1] : undefined;
+const target = app ? ["--app", app] : [];
+const fly = process.env.FLYCTL ?? "fly";
+
+if (spawnSync(fly, ["version"], { stdio: "ignore" }).status !== 0) {
+  console.error(`✗ ${fly} (flyctl) is not available. Install it (https://fly.io/docs/flyctl/install/) and sign in with \`fly auth login\`.`);
+  process.exit(2);
+}
+const { env, environment, problems } = managedEnvironment(process.env, readEnvFile(resolve(".env.local")));
+if (problems.length) {
+  console.error("✗ Managed FeltDB configuration is incomplete:");
+  for (const problem of problems) console.error(`  - ${problem}`);
+  process.exit(2);
+}
+try {
+  // Staged: applied by the deploy below, so the app never restarts with a half-updated set.
+  await run(fly, ["secrets", "import", "--stage", ...target], { input: `FELTDB_TOKEN=${env.FELTDB_TOKEN}\n` });
+  console.log("✓ FELTDB_TOKEN staged as a Fly secret");
+  await run(fly, [
+    "deploy", ...target,
+    "--env", `FELTDB_URL=${env.FELTDB_URL}`,
+    "--env", `FELTDB_APPLICATION_ID=${env.FELTDB_APPLICATION_ID}`,
+    "--env", `FELTDB_ENVIRONMENT=${environment}`,
+  ]);
+  console.log("✓ Deployed. Verify with `npm run managed:session` and GET /api/query/system:status (README.md, \"Verify\").");
+} catch (error) {
+  console.error(`✗ ${error.message}`);
+  process.exit(1);
+}

package/template-managed/scripts/managed-env.mjs

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+/**
+ * Run a FeltKit command against Managed FeltDB with the runtime configuration, and nothing else.
+ *
+ *   node scripts/managed-env.mjs start [--port 8080] [--host 0.0.0.0]
+ *   node scripts/managed-env.mjs session create --id ops --role clerk --type service
+ *   node scripts/managed-env.mjs --check          # validate the configuration, start nothing
+ *
+ * The configuration contract, the same on a laptop and in a container:
+ *
+ *   FELTDB_URL              Managed FeltDB API origin (https://api.feltdb.com)         required
+ *   FELTDB_APPLICATION_ID   the managed application (app_…)                            required
+ *   FELTDB_TOKEN            the application's runtime key: a secret                     required
+ *   FELTDB_ENVIRONMENT      the FeltDB environment, which is also FeltKit's             default production
+ *
+ * Values come from the process environment (a platform's secrets and config), else from
+ * `.env.local` (written by `feltdb init-managed`). The deploy-time control key
+ * (FELTDB_MANAGED_CONTROL_API_KEY) and browser variables (VITE_*) are never passed on: the
+ * running application does not need them. Nothing here prints a value.
+ */
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const REQUIRED = ["FELTDB_URL", "FELTDB_APPLICATION_ID", "FELTDB_TOKEN"];
+const NEVER_PASSED = /^(FELTDB_MANAGED_|VITE_|FELTDB_MODE$|FELTDB_NAMESPACE$)/;
+/** FeltKit commands that open an environment and take --env. */
+const ENVIRONMENT_COMMANDS = new Set(["start", "session", "inspect", "readiness", "operator", "model", "credential", "config"]);
+
+export function readEnvFile(file) {
+  const values = {};
+  if (!existsSync(file)) return values;
+  for (const raw of readFileSync(file, "utf8").split(/\r?\n/)) {
+    const line = raw.trim();
+    if (!line || line.startsWith("#")) continue;
+    const separator = line.indexOf("=");
+    if (separator < 1) continue;
+    values[line.slice(0, separator).trim()] = line.slice(separator + 1).trim().replace(/^(['"])(.*)\1$/, "$2");
+  }
+  return values;
+}
+
+/**
+ * The environment the FeltKit process gets, or the problems that stop it. Problems name the
+ * variable and what to do; they never include a value.
+ */
+export function managedEnvironment(processEnv, fileEnv = {}) {
+  const value = (name) => processEnv[name] || fileEnv[name] || "";
+  const problems = [];
+  for (const name of REQUIRED) {
+    if (!value(name)) problems.push(`${name} is not set. Run \`npm run managed:setup\` (writes .env.local), or set it from your platform's ${name === "FELTDB_TOKEN" ? "secret store" : "configuration"}.`);
+  }
+  const url = value("FELTDB_URL");
+  if (url) {
+    let parsed;
+    try { parsed = new URL(url); } catch { problems.push("FELTDB_URL is not a URL (expected https://api.feltdb.com)."); }
+    if (parsed && parsed.protocol !== "https:" && !["localhost", "127.0.0.1", "[::1]"].includes(parsed.hostname)) {
+      problems.push("FELTDB_URL must use https: the runtime key travels with every request.");
+    }
+  }
+  const environment = value("FELTDB_ENVIRONMENT") || "production";
+  if (environment === "development" || environment === "test") {
+    problems.push(`FELTDB_ENVIRONMENT is "${environment}", which FeltKit keeps on local FeltDB. Use production (default) or a deployed environment such as staging.`);
+  }
+  if (value("FELTKIT_ENV") && value("FELTKIT_ENV") !== environment) {
+    problems.push(`FELTKIT_ENV is "${value("FELTKIT_ENV")}" but FELTDB_ENVIRONMENT is "${environment}"; FeltKit runs in the FeltDB environment of the same name. Set one of them.`);
+  }
+  if (value("FELTKIT_STATE_DIR")) problems.push("FELTKIT_STATE_DIR is set: it selects local state, which contradicts Managed FeltDB. Unset it.");
+  const env = {};
+  for (const [name, entry] of Object.entries(processEnv)) if (!NEVER_PASSED.test(name)) env[name] = entry;
+  for (const name of REQUIRED) env[name] = value(name);
+  env.FELTDB_ENVIRONMENT = environment;
+  delete env.FELTKIT_ENV;
+  return { env, environment, problems };
+}
+
+function feltkitBin() {
+  const require = createRequire(join(process.cwd(), "package.json"));
+  return join(dirname(require.resolve("@feltdb/feltkit/package.json")), "bin", "feltkit.js");
+}
+
+async function main(argv) {
+  const { env, environment, problems } = managedEnvironment(process.env, readEnvFile(resolve(".env.local")));
+  if (problems.length) {
+    console.error("✗ Managed FeltDB configuration is incomplete:");
+    for (const problem of problems) console.error(`  - ${problem}`);
+    return 2;
+  }
+  if (argv[0] === "--check") {
+    console.log(`✓ Managed FeltDB configuration is complete (${new URL(env.FELTDB_URL).origin}, application ${env.FELTDB_APPLICATION_ID}, environment ${environment}).`);
+    return 0;
+  }
+  const args = [...argv];
+  if (ENVIRONMENT_COMMANDS.has(args[0]) && !args.includes("--env")) args.push("--env", environment);
+  const child = spawn(process.execPath, [feltkitBin(), ...args], { env, stdio: "inherit" });
+  // Forward shutdown signals so FeltKit stops cleanly (a platform sends SIGTERM).
+  for (const signal of ["SIGTERM", "SIGINT"]) process.on(signal, () => child.kill(signal));
+  return new Promise((done) => child.once("exit", (code, signal) => done(code ?? (signal ? 1 : 0))));
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === resolve(process.argv[1])) process.exitCode = await main(process.argv.slice(2));

package/template-managed/tests/config.test.ts

@@ -0,0 +1,91 @@
+/**
+ * The runtime configuration contract (scripts/managed-env.mjs) and the Fly deploy script, as
+ * processes, the way a laptop and a container run them. Nothing here reaches FeltDB.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { chmodSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const project = fileURLToPath(new URL("..", import.meta.url));
+const launcher = join(project, "scripts/managed-env.mjs");
+const deployFly = join(project, "scripts/deploy-fly.mjs");
+const TOKEN = "fdb_live_example_runtime_key_never_printed_0123456789";
+const CONTROL = "fdb_live_example_control_key_never_passed_0123456789";
+const complete = { FELTDB_URL: "https://api.feltdb.example", FELTDB_APPLICATION_ID: "app_example", FELTDB_TOKEN: TOKEN };
+
+/** Run a script in an empty directory (no .env.local), with exactly `env` plus PATH. */
+function run(script: string, args: string[], env: Record<string, string>, cwd = mkdtempSync(join(tmpdir(), "managed-config-"))) {
+  const result = spawnSync(process.execPath, [script, ...args], { cwd, env: { PATH: process.env.PATH!, ...env }, encoding: "utf8" });
+  return { code: result.status, output: `${result.stdout}${result.stderr}` };
+}
+
+test("a complete configuration passes, and the check prints no secret", () => {
+  const result = run(launcher, ["--check"], complete);
+  assert.equal(result.code, 0, result.output);
+  assert.match(result.output, /application app_example, environment production/);
+  assert.ok(!result.output.includes(TOKEN));
+});
+
+test("each missing or contradictory setting is refused by name, before anything starts", () => {
+  for (const name of ["FELTDB_URL", "FELTDB_APPLICATION_ID", "FELTDB_TOKEN"]) {
+    const { [name as keyof typeof complete]: _, ...rest } = complete;
+    const result = run(launcher, ["start"], rest);
+    assert.equal(result.code, 2, name);
+    assert.match(result.output, new RegExp(`${name} is not set`));
+  }
+  const cases: Array<[Record<string, string>, RegExp]> = [
+    [{ ...complete, FELTDB_URL: "http://api.feltdb.example" }, /must use https/],
+    [{ ...complete, FELTDB_URL: "not a url" }, /not a URL/],
+    [{ ...complete, FELTDB_ENVIRONMENT: "development" }, /keeps on local FeltDB/],
+    [{ ...complete, FELTKIT_ENV: "staging" }, /FELTKIT_ENV is "staging" but FELTDB_ENVIRONMENT is "production"/],
+    [{ ...complete, FELTKIT_STATE_DIR: "/data/state" }, /contradicts Managed FeltDB/],
+  ];
+  for (const [env, message] of cases) {
+    const result = run(launcher, ["start"], env);
+    assert.equal(result.code, 2, String(message));
+    assert.match(result.output, message);
+    assert.ok(!result.output.includes(TOKEN));
+  }
+  assert.equal(run(launcher, ["--check"], { ...complete, FELTDB_URL: "http://127.0.0.1:7700" }).code, 0, "plain http is allowed to a local authority");
+});
+
+test(".env.local fills in what the process does not set; the process environment wins", () => {
+  const cwd = mkdtempSync(join(tmpdir(), "managed-config-file-"));
+  writeFileSync(join(cwd, ".env.local"), `FELTDB_URL=https://from-file.example\nFELTDB_APPLICATION_ID=app_file\nFELTDB_TOKEN=${TOKEN}\nFELTDB_MANAGED_CONTROL_API_KEY=${CONTROL}\n`);
+  assert.match(run(launcher, ["--check"], {}, cwd).output, /from-file\.example, application app_file/);
+  assert.match(run(launcher, ["--check"], { FELTDB_APPLICATION_ID: "app_env" }, cwd).output, /application app_env/);
+});
+
+test("FeltKit receives the runtime settings and never the control key or browser variables", async () => {
+  const { managedEnvironment } = await import("../scripts/managed-env.mjs" as string);
+  const { env, problems } = managedEnvironment(
+    { PATH: "/bin", VITE_FELTDB_URL: "https://x", FELTDB_MANAGED_CONTROL_API_KEY: CONTROL, FELTKIT_ENV: "production" },
+    { ...complete, FELTDB_NAMESPACE: "ns", FELTDB_MODE: "remote" },
+  );
+  assert.deepEqual(problems, []);
+  assert.deepEqual(Object.keys(env).sort(), ["FELTDB_APPLICATION_ID", "FELTDB_ENVIRONMENT", "FELTDB_TOKEN", "FELTDB_URL", "PATH"]);
+  assert.equal(env.FELTDB_TOKEN, TOKEN);
+});
+
+test("the Fly deploy stages the key on stdin, never in a command line, and passes the rest with the deploy", () => {
+  const bin = mkdtempSync(join(tmpdir(), "fake-fly-"));
+  const log = join(bin, "calls.log");
+  // A stand-in for flyctl that records its arguments and stdin.
+  writeFileSync(join(bin, "fly"), `#!/bin/sh\nif [ "$1" = version ]; then exit 0; fi\necho "ARGS $*" >> "${log}"\nif [ "$1" = secrets ]; then echo "STDIN $(cat)" >> "${log}"; fi\n`);
+  chmodSync(join(bin, "fly"), 0o755);
+  const result = run(deployFly, ["--app", "my-inventory"], { ...complete, PATH: `${bin}:${process.env.PATH}` });
+  assert.equal(result.code, 0, result.output);
+  assert.ok(!result.output.includes(TOKEN));
+  const calls = readFileSync(log, "utf8").trim().split("\n");
+  assert.equal(calls[0], "ARGS secrets import --stage --app my-inventory");
+  assert.equal(calls[1], `STDIN FELTDB_TOKEN=${TOKEN}`);
+  assert.equal(calls[2], "ARGS deploy --app my-inventory --env FELTDB_URL=https://api.feltdb.example --env FELTDB_APPLICATION_ID=app_example --env FELTDB_ENVIRONMENT=production");
+  assert.ok(!calls.filter((c) => c.startsWith("ARGS")).some((c) => c.includes(TOKEN)), "the key never appears in a command line");
+  const missing = run(deployFly, [], { PATH: `${bin}:${process.env.PATH}` });
+  assert.equal(missing.code, 2);
+  assert.match(missing.output, /FELTDB_TOKEN is not set/);
+});

package/template-managed/tests/inventory.test.ts

@@ -0,0 +1,69 @@
+/**
+ * Run with `npm test` (`feltkit test`). Each test app gets its own local FeltDB instance in a
+ * temporary directory: the same functions that run on Managed FeltDB, without the network.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { createTestApp } from "@feltdb/feltkit/testing";
+import { api } from "../feltkit/_generated/api.js";
+
+test("clerks add items and adjust stock; every change is recorded with its item", async () => {
+  const t = await createTestApp();
+  try {
+    const ada = t.as("ada");
+    await ada.mutation(api.items.create, { sku: "BOLT-10", name: "M10 bolt", quantity: 100 });
+    const after = await ada.mutation(api.items.adjust, { sku: "BOLT-10", delta: -30, reason: "order 1" });
+    assert.equal(after.quantity, 70);
+    await ada.mutation(api.items.adjust, { sku: "BOLT-10", delta: 5, reason: "return" });
+
+    const item = await ada.query(api.items.get, { sku: "BOLT-10" });
+    assert.equal(item!.quantity, 75);
+    const history = await ada.query(api.items.history, { sku: "BOLT-10" });
+    assert.deepEqual(history.map((m) => [m.delta, m.quantityAfter, m.by]), [[5, 75, "ada"], [-30, 70, "ada"], [100, 100, "ada"]]);
+  } finally {
+    await t.close();
+  }
+});
+
+test("refusals change nothing: duplicate SKU, overdraft, unknown SKU, zero delta", async () => {
+  const t = await createTestApp();
+  try {
+    const ada = t.as("ada");
+    await ada.mutation(api.items.create, { sku: "NUT-10", name: "M10 nut", quantity: 3 });
+    await assert.rejects(ada.mutation(api.items.create, { sku: "NUT-10", name: "again", quantity: 1 }), { code: "CONFLICT" });
+    await assert.rejects(ada.mutation(api.items.adjust, { sku: "NUT-10", delta: -4, reason: "too many" }), { code: "CONFLICT" });
+    await assert.rejects(ada.mutation(api.items.adjust, { sku: "NOPE", delta: 1, reason: "x" }), { code: "NOT_FOUND" });
+    await assert.rejects(ada.mutation(api.items.adjust, { sku: "NUT-10", delta: 0, reason: "x" }), { code: "INVALID_ARGUMENT" });
+    await assert.rejects(ada.mutation(api.items.create, { sku: "NEG", name: "negative", quantity: -1 }), { code: "INVALID_ARGUMENT" });
+    assert.equal((await ada.query(api.items.get, { sku: "NUT-10" }))!.quantity, 3);
+    assert.equal((await ada.query(api.items.history, { sku: "NUT-10" })).length, 1, "only the initial stock");
+    assert.equal((await ada.query(api.items.list)).length, 1);
+  } finally {
+    await t.close();
+  }
+});
+
+test("auditors read but cannot change stock; anonymous callers can do neither", async () => {
+  const t = await createTestApp();
+  try {
+    await t.as("ada").mutation(api.items.create, { sku: "WASHER", name: "washer", quantity: 10 });
+    const grace = t.as("grace");
+    assert.equal((await grace.query(api.items.list)).length, 1);
+    await assert.rejects(grace.mutation(api.items.adjust, { sku: "WASHER", delta: -1, reason: "x" }), { code: "FORBIDDEN" });
+    await assert.rejects(t.query(api.items.list), { code: "UNAUTHORIZED" });
+  } finally {
+    await t.close();
+  }
+});
+
+test("the verification query reads through the configured backend and names no credential", async () => {
+  const t = await createTestApp();
+  try {
+    const status = await t.as("grace").query(api.system.status);
+    assert.equal(status.readable, true);
+    assert.equal(status.storage.kind, "local", "tests run on local FeltDB; deployed, this reads `remote`");
+    assert.equal(status.storage.durable, true);
+  } finally {
+    await t.close();
+  }
+});

package/template-managed/tests/managed.live.test.ts

@@ -0,0 +1,75 @@
+/**
+ * Against your Managed FeltDB application: the app as its own process, writes and reads, then
+ * the app killed and started again, and the state still there.
+ *
+ *   npm run managed:setup                               # once (or settings in the environment)
+ *   FELTKIT_MANAGED_LIVE=1 npm run managed:test
+ *
+ * Skipped unless FELTKIT_MANAGED_LIVE=1. Uses the settings scripts/managed-env.mjs resolves
+ * (process environment, else .env.local). Writes one item per run, with a SKU starting
+ * `live-test-`, and one service session (`live-test`); see README.md, "Clean up".
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { spawn, spawnSync } from "node:child_process";
+import { rmSync } from "node:fs";
+import { createServer } from "node:net";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const project = fileURLToPath(new URL("..", import.meta.url));
+const launcher = join(project, "scripts/managed-env.mjs");
+const live = process.env.FELTKIT_MANAGED_LIVE === "1";
+
+const freePort = () => new Promise<number>((done) => { const s = createServer(); s.listen(0, "127.0.0.1", () => { const { port } = s.address() as { port: number }; s.close(() => done(port)); }); });
+// The test runner's own environment (FELTKIT_ENV=test) is not the deployed application's.
+const { FELTKIT_ENV: _test, NODE_TEST_CONTEXT: _context, ...appEnv } = process.env;
+
+async function startApp() {
+  const port = await freePort();
+  const child = spawn(process.execPath, [launcher, "start", "--port", String(port)], { cwd: project, env: appEnv, stdio: ["ignore", "pipe", "pipe"], detached: true });
+  let output = "";
+  child.stdout!.on("data", (c) => { output += c; });
+  child.stderr!.on("data", (c) => { output += c; });
+  const exited = new Promise((done) => child.once("exit", done));
+  for (let i = 0; i < 600 && !/serving http/.test(output) && child.exitCode === null; i++) await new Promise((r) => setTimeout(r, 100));
+  assert.match(output, /serving http/, output);
+  assert.match(output, /State\s+remote https?:\/\//, "the app's state is remote");
+  return {
+    base: `http://127.0.0.1:${port}`,
+    kill: async () => { try { process.kill(-child.pid!, "SIGKILL"); } catch {} await exited; rmSync(join(project, ".feltkit/production/runtime.json"), { force: true }); },
+  };
+}
+
+test("Managed FeltDB: state written by one app process is there for the next", { skip: live ? false : "set FELTKIT_MANAGED_LIVE=1 (and your managed settings) to run against Managed FeltDB", timeout: 300_000 }, async () => {
+  assert.equal(spawnSync(process.execPath, [launcher, "--check"], { cwd: project, env: appEnv, stdio: "inherit" }).status, 0, "managed settings are complete");
+  assert.equal(spawnSync("npx", ["feltkit", "build"], { cwd: project, env: appEnv, stdio: "ignore" }).status, 0);
+  const session = spawnSync(process.execPath, [launcher, "session", "create", "--id", "live-test", "--role", "clerk", "--type", "service", "--ttl", "1"], { cwd: project, env: appEnv, encoding: "utf8" });
+  assert.equal(session.status, 0, session.stderr);
+  const token = session.stdout.match(/\b(fk[a-z]*_[A-Za-z0-9_-]{16,})/)?.[1];
+  assert.ok(token, "a session was issued");
+  const call = async (base: string, kind: string, name: string, args: unknown) => {
+    const response = await fetch(`${base}/api/${kind}/${name}`, { method: "POST", headers: { "content-type": "application/json", authorization: `Bearer ${token}` }, body: JSON.stringify({ args }) });
+    const body = (await response.json()) as { ok: boolean; value?: any; error?: { code: string; message: string } };
+    assert.equal(body.ok, true, JSON.stringify(body.error));
+    return body.value;
+  };
+
+  const sku = `live-test-${Date.now().toString(36)}`;
+  let app = await startApp();
+  try {
+    const status = await call(app.base, "query", "system:status", {});
+    assert.equal(status.storage.kind, "remote");
+    await call(app.base, "mutation", "items:create", { sku, name: "live test item", quantity: 10 });
+    assert.equal((await call(app.base, "mutation", "items:adjust", { sku, delta: -3, reason: "live test" })).quantity, 7);
+  } finally {
+    await app.kill();
+  }
+  app = await startApp();
+  try {
+    assert.equal((await call(app.base, "query", "items:get", { sku })).quantity, 7, "the state survived the app restart");
+    assert.deepEqual((await call(app.base, "query", "items:history", { sku })).map((m: { delta: number }) => m.delta), [-3, 10]);
+  } finally {
+    await app.kill();
+  }
+});

package/template-managed/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2023"],
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "isolatedModules": true,
+    "verbatimModuleSyntax": true,
+    "types": ["node"]
+  },
+  "include": ["feltkit", "tests"]
+}