create-freeholder 0.0.0-bootstrap.0 → 0.2.0-beta.2

package/dist/template/deploy/update-preflight.md

@@ -0,0 +1,19 @@
+# Update preflight
+
+Nothing applies without preflight. `platform.preflightUpdate` (and Doctor
+`update.preflight`) run the same checks:
+
+1. **Signature.** A supplied `releases.json` must verify against the embedded
+   release public key. A bad signature is a hard stop.
+2. **Plugins.** Every installed plugin's `freeholder` range must fit the
+   target. A miss *names the plugin*.
+3. **Drift.** Live edits of core files mean this instance is a fork.
+4. **Environment.** Disk for a snapshot, Postgres 15+, required extensions,
+   storage adapter.
+5. **Shadow migration.** The live `public` tables are cloned into a temporary
+   schema, optional target SQL is applied there, then the schema is dropped.
+   The owner's data is not touched.
+6. **Downtime.** The estimate is the dry-run's own timing.
+
+This is not unattended apply (C10.06) and not the upgrade gate that boots the
+previous image (C10.07).

package/dist/template/deploy/update-status.md

@@ -0,0 +1,78 @@
+<!--
+Copyright (C) 2026 Tony Aly
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# The update read model
+
+*MASTER.md §39.10, checklist item C10.11.*
+
+§39.10 lists four entities and then says *"Four surfaces, one service layer"*.
+The admin screen (C10.20), the CLI (C10.21), MCP and the notification
+escalation (C10.22) must not each work out "how far behind am I" from the raw
+feed — four answers to that question is four chances to disagree about whether
+a business is exposed. They all read this.
+
+## `available_releases`
+
+What the signed feed offered, cached. Migration `0166_available_releases.sql`.
+
+Cached rather than fetched per read for one reason: **an owner asking "am I
+exposed?" must get an answer when the feed is unreachable**, and "I could not
+reach the feed" is a different sentence from "you are up to date".
+
+- Written by `platform.checkUpdates` after the feed verifies, in a fresh
+  transaction opened once the network is done — never one held across the
+  fetch.
+- Upserted by version, never insert-only: a release whose metadata is
+  corrected upstream corrects here too. A cache that can only grow will
+  happily keep telling an owner about a CVSS score that was withdrawn.
+- `verified` records whether the signature checked out *when the row was
+  written*, so a row can never be mistaken for a trusted one later.
+- The database repeats the feed parser's rule that a scored release must name
+  a severity band and an unscored one must not. A cache that can hold what the
+  parser rejects is not a cache.
+
+## The status line
+
+`platform.updateStatus` returns the one sentence §39.10 says must never be
+ambiguous, plus whether it should be shown in the danger colour.
+
+| Posture | Sentence | Urgent |
+|---|---|---|
+| `unknown` | "No update check has completed yet…" / "Update checks are off…" | no |
+| `current` | "Up to date" | no |
+| `behind` | "Update available — 0.3.0" | no |
+| `behind-security` | "2 security releases behind — CVSS 8.1" | **yes** |
+
+`unknown` is a real posture, not a failure. An instance that has never
+completed a check has not been told it is safe, and saying "Up to date"
+because the cache happens to be empty is exactly the silence §39.10 refuses.
+
+Channel filtering happens before the count. An instance on the `security`
+channel is not "behind" because a feature release exists. A release with no
+CVSS score is news, not exposure.
+
+## The rollback horizon
+
+§39.11: *"Once a later release contracts the schema, the releases before it are
+no longer reachable by an image swap. The admin states which version is the
+earliest one still reachable."*
+
+`earliestReachableVersion` is the newest `schema_breaking` release the instance
+has already passed, or `null` when nothing has contracted the schema. A
+breaking release the instance has not reached yet does not shorten its horizon.
+
+## Applicability, per row
+
+`platform.listAvailableReleases` marks each cached release `applicable` with a
+reason, using C10.02's `canApplyFrom` against `min_from_version`. A list of
+releases an owner cannot apply from their current version is a list that
+teaches them to ignore it.
+
+## Surfaces
+
+This item ships the model and its services only. The screens are C10.20, the
+CLI is C10.21, and MCP plus the email/SMS escalation are C10.22 — the split
+recorded in §43 on 2026-09-07, because one checklist line had become the
+deferred human surface of ten shipped items.

package/dist/template/deploy/update-targets.md

@@ -0,0 +1,90 @@
+<!--
+Copyright (C) 2026 Tony Aly
+SPDX-License-Identifier: Apache-2.0
+-->
+
+# What "update" means on your target
+
+*MASTER.md §39.8, checklist item C10.10.*
+
+Updating is a step in the recipe, not one script. Three of the Tier-1 targets
+mean genuinely different things by the word, and the difference decides what
+has to survive for a rollback to be possible at all.
+
+| Strategy | Targets | Update does | Rollback needs | Cutover takes |
+|---|---|---|---|---|
+| `image-swap` | `digitalocean-droplet`, `docker-selfhost` | Pull the new image digest and restart the container in place. | the previous image digest | seconds |
+| `deploy-hook` | `digitalocean-app`, `render`, `railway` | Hand the new image to the platform's deploy API and let it perform the swap. | the previous deploy spec | a minute or two |
+| `source-pull` | `replit` | Fetch source, install dependencies, rebuild and restart. | the previous commit | minutes |
+
+If you leave automatic updates on (C10.08), the third column is what your site
+does at 03:00. On Replit that is minutes of rebuild, not seconds of container
+restart, which is worth knowing before you decide.
+
+## Telling the platform which one you are
+
+```
+FREEHOLDER_RECIPE_TARGET=digitalocean-droplet
+```
+
+**Without it, an update migrates and smokes but swaps nothing.** It will look
+like it worked. `freeholder doctor` warns about this under `update.target`,
+because guessing a deploy strategy from the environment and then running a
+container command against it is how an update takes down a host nobody meant
+to touch.
+
+## Where the commands live
+
+`recipe.yaml` is the source of truth an owner reads:
+
+```yaml
+operations:
+  update: "docker compose -f deploy/docker-selfhost/infra/compose.yml pull && …"
+  rollback: "FREEHOLDER_IMAGE=$PREVIOUS_FREEHOLDER_IMAGE docker compose … up -d"
+update:
+  strategy: image-swap
+  rollback: compose pull the previous tag
+```
+
+A standalone build does not ship `deploy/`, so the same commands are embedded
+in `src/core/update/targets.ts`. `tests/core/update-targets.test.ts` fails if
+the two ever disagree — an updater that cannot find its own instructions at the
+moment it is asked to update is worse than one that never offered.
+
+The variables a rollback is given are the artifact its strategy needs:
+`PREVIOUS_FREEHOLDER_IMAGE`, `PREVIOUS_FREEHOLDER_APP_SPEC`,
+`PREVIOUS_FREEHOLDER_IMAGE_TAG` or `PREVIOUS_FREEHOLDER_TAG`.
+
+## The gate
+
+`scripts/recipe-update-actions.mjs` runs once per target inside the recipe
+matrix. §39.8: *"A recipe without a tested update path is not Tier 1, for the
+same reason one without a migration path is not."* It proves, per recipe:
+
+- the declared strategy is the one §39.8 assigns that target;
+- `operations.update` is actually that shape — a `deploy-hook` recipe cannot
+  quietly declare `image-swap`;
+- `operations.rollback` names a *previous* artifact, so it is a rollback and
+  not a redeploy of the same build;
+- the update pins an image tag, directly or through a script it runs;
+- since the 2026-09-21 readiness repair, `operations.backup` produces a
+  custom-format `pg_dump` (the format `deploy/update-apply.md` step 2 and the
+  droplet's `backup.sh` mandate, following a script the command delegates to)
+  and `operations.restore` is a `pg_restore` into a database. The repair
+  reopens the recipe path as a manual operator procedure *requiring a tested
+  backup and immutable image pins* — a rollback pin is only real if the data
+  it returns to still exists. The executable rehearsal itself is the
+  operator's step 7 of `deploy/recipe-verification.md`; this gate keeps a
+  recipe that dropped its backup from staying Tier 1 while nobody noticed.
+
+It does **not** call `doctl`, `render` or `railway`. A green build must not
+depend on a third party's API being up, and a CI run that really redeployed
+would be deploying from a pull request.
+
+### The bug this found
+
+Before this gate, all six recipes declared `strategy: image-swap` — including
+Replit, which has no image and rebuilds from source, and App Platform, which
+hands the image to `doctl`. The declaration was a comment nobody checked, and
+the updater would have run the right command for the wrong stated reason. Three
+of the six are now corrected.

package/dist/template/deploy/webhook-delivery.md

@@ -0,0 +1,36 @@
+# Outbound webhook delivery
+
+Freeholder treats every saved webhook URL as an unattended outbound-request
+boundary. A URL being owner-supplied does not make its eventual DNS answer
+safe.
+
+Immediately before every attempt, the delivery transport:
+
+1. requires HTTPS in production and refuses URL user-info;
+2. resolves all DNS answers without allowing the socket layer to resolve again;
+3. rejects the entire answer set if any IPv4 or IPv6 address is loopback,
+   private, link-local, carrier-grade NAT, multicast, documentation,
+   benchmarking, transition or otherwise non-global space;
+4. opens a fresh connection directly to the selected checked address while
+   retaining the original hostname for TLS certificate validation and `Host`;
+5. never follows redirects and bounds both time and retained response bytes.
+
+Local HTTP and loopback delivery are available only outside production so a
+developer can use a real receiver. Production has no per-subscription bypass.
+
+DNS failures and prohibited answers are ordinary failed delivery attempts:
+they appear in the owner-visible delivery ledger, retry with bounded backoff,
+and participate in automatic endpoint pausing. Payloads and signing secrets
+must never be copied into process logs while diagnosing transport failures.
+
+## Other externally supplied URLs
+
+The same address-pinned boundary protects remote catalogue indexes, imported
+ICS feeds, provider-supplied social media, and contribution hub/status-reply
+delivery. Those paths are not webhooks, but the risk is identical: content or
+configuration outside the process chooses where the server connects.
+
+Unlike a developer-created webhook receiver, these download paths do not gain
+a non-production loopback exception. Media and document responses are capped
+while streaming, redirects are refused, and account credentials are never
+attached to a provider-supplied media URL.

package/dist/template/drizzle.config.ts

@@ -0,0 +1,24 @@
+// Copyright (C) 2026 Tony Aly
+// SPDX-License-Identifier: Apache-2.0
+import { defineConfig } from "drizzle-kit";
+
+export default defineConfig({
+  dialect: "postgresql",
+  // Schema is owned per-module (MASTER.md §11) and by core. `*-schema.ts`
+  // holds tables that outgrew a single file (imports, audiences, broadcasts).
+  // First-party plugin tables are in the chain through 0163; sibling 0168_*
+  // migrations are not on this branch and must be folded in when they land.
+  schema: [
+    "./src/core/**/schema.ts",
+    "./src/core/**/*-schema.ts",
+    "./src/modules/**/schema.ts",
+    "./src/modules/**/*-schema.ts",
+    "./plugins/**/schema.ts",
+  ],
+  out: "./db/migrations",
+  dbCredentials: {
+    url:
+      process.env.DATABASE_URL ??
+      "postgres://postgres:postgres@localhost:5432/freeholder_dev",
+  },
+});

package/dist/template/eslint.config.mjs

@@ -0,0 +1,241 @@
+// Copyright (C) 2026 Tony Aly
+// SPDX-License-Identifier: Apache-2.0
+// Lint IS the architecture police (MASTER.md §2 principle 11, §15, §16):
+// every boundary rule agreed in the master doc that can be machine-checked
+// lives here, not in tribal knowledge.
+import tseslint from "typescript-eslint";
+
+// The gates are named arrays rather than written inline because ESLint's flat
+// config *replaces* a rule's options when a later block sets the same rule for
+// overlapping files — it does not merge them. Writing the i18n gate inline for
+// `src/ui/**` silently switched the money gate off there, which is the kind of
+// hole a gate is supposed to close rather than open. Composing the arrays
+// makes the overlap explicit and impossible to get wrong by accident.
+
+// Money gate (MASTER.md §15.4). Money is integer minor units; the only way it
+// becomes a float is division, rounding helpers, or float parsing. Adding and
+// subtracting minor units is correct and stays legal — this bans the
+// operations that lose a cent, not arithmetic.
+const MONEY_GATE = [
+  {
+    // `Minor` is this codebase's own universal suffix (amountMinor,
+    // totalMinor, shippingMinor…) — a division rule that misses it is inert
+    // against the very code it exists to guard.
+    selector:
+      'BinaryExpression[operator="/"] > Identifier[name=/([Cc]ents|[Mm]inorUnits|[Mm]inor|[Aa]mount)$/]',
+    message:
+      "Money is integer minor units (MASTER.md §15.4): dividing it produces a float. formatMoney() renders it without ever dividing.",
+  },
+  {
+    selector: 'CallExpression[callee.property.name="toFixed"]',
+    message:
+      "toFixed() rounds in floating point (MASTER.md §15.4). Format money with formatMoney().",
+  },
+  {
+    selector: 'CallExpression[callee.name="parseFloat"]',
+    message:
+      "parseFloat() introduces float error (MASTER.md §15.4). Money is parsed and stored as integer minor units.",
+  },
+  {
+    selector:
+      'CallExpression[callee.object.name="Number"][callee.property.name="parseFloat"]',
+    message:
+      "Number.parseFloat() introduces float error (MASTER.md §15.4). Money is parsed and stored as integer minor units.",
+  },
+];
+
+// The i18n gate (MASTER.md §15.3): user-facing text must pass through the
+// string layer. §2 principle 9 calls retrofitting i18n "the single most
+// expensive refactor a platform can face" — this is what keeps the retrofit
+// from being needed a second time.
+//
+// It catches the two shapes copy takes in JSX: a bare literal between tags,
+// and a literal handed to an attribute that is rendered or announced.
+//
+// Client components cannot call `t` — the catalogs are server-side and the
+// locale is resolved per request — so they take their strings as props. That
+// is what makes a rule this blunt workable.
+// Colour gate (CLAUDE.md non-negotiable: every colour comes from a semantic
+// token in src/core/design/tokens.ts). The tokens test proves the *palette*
+// clears WCAG AA in both schemes; this is what makes components actually use
+// it. It catches the two shapes a bypass takes: Tailwind's raw palette
+// (`text-white` on an inverting ground was a live AA failure) and arbitrary
+// values smuggling a literal (`bg-[#fff]`, `shadow-[…rgb(0_0_0/0.16)]`).
+const COLOR_GATE = [
+  {
+    selector:
+      "Literal[value=/(^|[\\s'\"])(bg|text|border|ring|outline|fill|stroke|from|via|to|divide|decoration|caret|accent)-(white|black|slate|gray|zinc|neutral|stone|red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose)([-0-9\\/]|$|[\\s'\"])/]",
+    message:
+      "Tailwind's raw palette bypasses the design tokens (CLAUDE.md). Use a semantic utility (bg-surface, text-ink, bg-danger, text-on-danger…) or add a token to src/core/design/tokens.ts.",
+  },
+  {
+    selector:
+      "Literal[value=/-\\[[^\\]]*(#[0-9a-fA-F]{3}|rgba?\\(|hsla?\\(|oklch\\()/]",
+    message:
+      "Arbitrary colour values bypass the design tokens (CLAUDE.md). Define the value once in src/core/design/tokens.ts and use its utility.",
+  },
+  {
+    selector:
+      'JSXAttribute[name.name="style"] Literal[value=/(#[0-9a-fA-F]{3,8}\\b|rgba?\\(|hsla?\\(|oklch\\()/]',
+    message:
+      "Inline style colour literals bypass the design tokens (CLAUDE.md). Use a semantic token from src/core/design/tokens.ts.",
+  },
+];
+
+const CONTACT_CREATE_IMPORT = {
+  name: "@/core/contacts/service",
+  importNames: ["createContact"],
+  message:
+    "Automated paths call contacts.resolve, never contacts.create (CLAUDE.md). Human entry lives in app/(admin) only.",
+};
+
+const CONTACT_CREATE_CALL = {
+  selector:
+    "CallExpression[callee.property.name='callAsSystem'][arguments.0.name='createContact']",
+  message:
+    "ctx.callAsSystem(createContact) is forbidden outside app/(admin). Use contacts.resolve.",
+};
+
+const I18N_GATE = [
+  {
+    // Two or more letters in a row: skips punctuation, arrows, dashes and the
+    // whitespace JSX is full of, catches every real sentence.
+    selector: "JSXText[value=/[A-Za-z]{2,}/]",
+    message:
+      'User-facing text must come from the string layer (MASTER.md §15.3). Use {t("some.key")} in a server component, or take the string as a prop in a client component.',
+  },
+  {
+    selector:
+      'JSXAttribute[name.name=/^(label|placeholder|title|alt|hint|summary|legend|aria-label|aria-description|aria-placeholder|aria-roledescription|aria-valuetext)$/] > Literal[value=/[A-Za-z]{2,}/]',
+    message:
+      "This attribute is read by a person or a screen reader, so it must come from the string layer (MASTER.md §15.3) rather than a literal.",
+  },
+];
+
+export default tseslint.config(
+  {
+    // `apps/**` is the Expo customer app (C10.23). It sits outside the root
+    // pnpm workspace with its own tsconfig, dependencies and CI job, so
+    // type-aware linting here would resolve its imports against the wrong
+    // project and report every one of them as missing.
+    ignores: [".next/**", ".work/**", "node_modules/**", "packages/**", "db/**", "apps/**"],
+  },
+  // Type-aware from here down. Several gates in §15 are statements about
+  // values, not syntax, and cannot be written without the type checker.
+  ...tseslint.configs.recommendedTypeChecked,
+  {
+    languageOptions: {
+      parserOptions: {
+        projectService: true,
+        tsconfigRootDir: import.meta.dirname,
+      },
+    },
+  },
+  {
+    // Config and script files live outside the TypeScript program.
+    files: ["**/*.mjs", "**/*.js"],
+    extends: [tseslint.configs.disableTypeChecked],
+  },
+  {
+    // Plugins carry money and render UI like everything else; leaving them
+    // outside the gates made them the one place a cent could quietly become
+    // a float. (packages/** stays out of the program entirely — it has its
+    // own builds — and is the documented residual hole.)
+    files: ["plugins/**/*.ts", "plugins/**/*.tsx"],
+    rules: {
+      "no-restricted-syntax": ["error", ...MONEY_GATE, ...COLOR_GATE, CONTACT_CREATE_CALL],
+      "no-restricted-imports": [
+        "error",
+        { paths: [CONTACT_CREATE_IMPORT] },
+      ],
+    },
+  },
+  {
+    files: ["src/**/*.ts", "src/**/*.tsx"],
+    rules: {
+      // Framework-free below app/: src/ is the application, app/ is the
+      // routing skin. A future framework migration must be a chore, not a
+      // rewrite.
+      "no-restricted-imports": [
+        "error",
+        {
+          paths: [CONTACT_CREATE_IMPORT],
+          patterns: [
+            {
+              group: ["next", "next/*"],
+              message:
+                "src/ is framework-agnostic (MASTER.md §10): Next.js imports belong in app/ only.",
+            },
+          ],
+        },
+      ],
+      "no-restricted-syntax": ["error", ...MONEY_GATE, ...COLOR_GATE, CONTACT_CREATE_CALL],
+    },
+  },
+  {
+    files: ["app/**/*.ts", "app/**/*.tsx"],
+    rules: {
+      // The server actions in app/**/*.ts are exactly the files that parse
+      // money out of FormData — the money gate must reach them, not just the
+      // rendered .tsx surfaces.
+      "no-restricted-syntax": ["error", ...MONEY_GATE, ...COLOR_GATE],
+      // Service-layer gate (MASTER.md §15.5): routes call services, never the
+      // database. Blocking only the schema modules left the front door open —
+      // a handler could take the Drizzle client itself and issue raw SQL,
+      // skipping permissions, validation, the audit trail and the timeline.
+      "no-restricted-imports": [
+        "error",
+        {
+          patterns: [
+            {
+              group: [
+                "@/core/db",
+                "@/core/db/*",
+                "@/core/*/schema",
+                "@/modules/*/schema",
+                "drizzle-orm",
+                "drizzle-orm/*",
+                "postgres",
+              ],
+              message:
+                "Route handlers never reach the database directly (MASTER.md §15.5) — call the service layer.",
+            },
+          ],
+        },
+      ],
+    },
+  },
+  {
+    // The rendered surfaces carry every gate. These globs overlap the src/
+    // and app/ blocks above, so the money and colour gates are restated here
+    // rather than lost — flat config replaces, it does not merge.
+    // `src/modules/**/*.tsx` is the block-rendering surface (cms render,
+    // forms, events, newsletters, proof): it ships user-facing markup like
+    // app/ does, so it carries the i18n gate like app/ does.
+    files: ["app/**/*.tsx", "src/ui/**/*.tsx", "src/modules/**/*.tsx"],
+    rules: {
+      "no-restricted-syntax": [
+        "error",
+        ...MONEY_GATE,
+        ...COLOR_GATE,
+        ...I18N_GATE,
+        CONTACT_CREATE_CALL,
+      ],
+    },
+  },
+  {
+    files: ["**/*.ts", "**/*.tsx"],
+    rules: {
+      // Core's contracts require async functions by signature — a service
+      // handler and a manifest's lazy loaders must return promises whether or
+      // not their body happens to await. The rule would push those toward
+      // hand-rolled Promise.resolve wrappers, which is worse code for no gain.
+      "@typescript-eslint/require-await": "off",
+      "@typescript-eslint/consistent-type-imports": "error",
+      "@typescript-eslint/no-unused-vars": [
+        "error",
+        { argsIgnorePattern: "^_", varsIgnorePattern: "^_" },
+      ],
+    },
+  },
+);

package/dist/template/freeholder.config.ts

@@ -0,0 +1,11 @@
+// Copyright (C) 2026 Tony Aly
+// SPDX-License-Identifier: Apache-2.0
+// This instance, declaratively (MASTER.md §17). No secrets here — see .env.
+import { defineConfig } from "@/core/config";
+
+export default defineConfig({
+  target: "local",
+  preset: "everything",
+  locales: ["en"],
+  baseCurrency: "USD",
+});

package/dist/template/gitignore.template

@@ -0,0 +1,48 @@
+# dependencies
+node_modules/
+.pnpm-store/
+
+# builds
+dist/
+build/
+.next/
+out/
+coverage/
+playwright-report/
+test-results/
+
+# environment & secrets
+.env
+.env.*
+!.env.example
+.freeholder-do-app*.yaml
+
+# local media, written by the dev-only storage adapter (§18: production media
+# lives in object storage, never on instance disk — this directory only ever
+# exists on a developer's machine and in test runs)
+.data/
+
+# logs & OS noise
+*.log
+.DS_Store
+Thumbs.db
+
+# editors
+.idea/
+.vscode/
+*.swp
+
+# local agent/session state (never product source or planning truth)
+.claude/
+.codex/
+.work/
+
+# typescript / next
+*.tsbuildinfo
+next-env.d.ts
+
+# Python host-tool bytecode
+__pycache__/
+
+# Private launch credentials and owner claim link
+.freeholder-launch/

package/dist/template/instrumentation.node.ts

@@ -0,0 +1,113 @@
+// Copyright (C) 2026 Tony Aly
+// SPDX-License-Identifier: Apache-2.0
+// Node-only process bootstrap. The shared instrumentation entrypoint imports
+// this module only after Next confirms that it is running the Node runtime.
+import { createGracefulShutdown } from "@/core/runtime/shutdown";
+
+const RETRY_MAX_MS = 30_000;
+const SHUTDOWN_TIMEOUT_MS = 35_000;
+let runtimeInitialization: Promise<void> | undefined;
+let lastFailureLogAt = 0;
+let shutdownInstalled = false;
+let runtimeAbort = new AbortController();
+
+function retryDelay(attempt: number): number {
+  return Math.min(1_000 * 2 ** Math.min(attempt, 5), RETRY_MAX_MS);
+}
+
+function wait(milliseconds: number, signal: AbortSignal): Promise<void> {
+  return new Promise((resolve) => {
+    const timer = setTimeout(done, milliseconds);
+    timer.unref?.();
+    signal.addEventListener("abort", done, { once: true });
+    function done() {
+      clearTimeout(timer);
+      signal.removeEventListener("abort", done);
+      resolve();
+    }
+  });
+}
+
+async function initializeRuntime(): Promise<void> {
+  let attempt = 0;
+  while (!runtimeAbort.signal.aborted) {
+    let phase = "migration";
+    try {
+      // Before boot, and before the first request: a fresh deploy otherwise
+      // starts against an empty database and answers 500 on every page.
+      const { migrateToLatest } = await import("@/core/migrate");
+      const result = await migrateToLatest();
+      console.log(
+        result.ran
+          ? "[freeholder] schema is up to date"
+          : `[freeholder] migrations skipped: ${result.reason}`,
+      );
+
+      phase = "module boot";
+      const { bootOnce } = await import("@/core/boot");
+      const { default: manifests } = await import("@/modules");
+      await bootOnce(manifests);
+
+      // Persist immutable manifest definitions after every module/plugin has
+      // registered its contribution.
+      phase = "onboarding synchronization";
+      const { db } = await import("@/core/db");
+      const { syncOnboardingDefinitions } = await import("@/core/demo/service");
+      await db().transaction((tx) => syncOnboardingDefinitions(tx));
+
+      phase = "demo seed";
+      const { initializePlayground } = await import("@/core/demo/playground");
+      await initializePlayground();
+      const { seedDemoIfRequested } = await import("@/modules/seed/boot");
+      await seedDemoIfRequested();
+
+      // Every definition exists before the worker mounts a queue.
+      phase = "job runtime";
+      const { startJobs } = await import("@/core/jobs");
+      await startJobs();
+      return;
+    } catch {
+      // A dependency outage must keep liveness green and readiness red. Retry
+      // idempotent initialization in-process so database recovery does not
+      // require an operator restart. Never print the caught error: SQL and
+      // provider errors may contain values that do not belong in logs.
+      const now = Date.now();
+      if (attempt === 0 || now - lastFailureLogAt >= 60_000) {
+        console.error(
+          `[freeholder] ${phase} unavailable; readiness is unavailable; retrying`,
+        );
+        lastFailureLogAt = now;
+      }
+      if (runtimeAbort.signal.aborted) return;
+      await wait(retryDelay(attempt), runtimeAbort.signal);
+      attempt += 1;
+    }
+  }
+}
+
+export async function stopNodeRuntime(): Promise<void> {
+  runtimeAbort.abort();
+  await runtimeInitialization?.catch(() => undefined);
+  const { stopJobs } = await import("@/core/jobs");
+  await stopJobs();
+  runtimeInitialization = undefined;
+}
+
+function installShutdownHandlers(): void {
+  if (process.env.NEXT_MANUAL_SIG_HANDLE !== "true" || shutdownInstalled) return;
+  shutdownInstalled = true;
+  const shutdown = createGracefulShutdown({
+    drain: stopNodeRuntime,
+    exit: (code) => process.exit(code),
+    timeoutMs: SHUTDOWN_TIMEOUT_MS,
+    log: (level, message) => console[level](message),
+  });
+  process.once("SIGINT", () => void shutdown.handle("SIGINT"));
+  process.once("SIGTERM", () => void shutdown.handle("SIGTERM"));
+}
+
+export function startNodeRuntime(): void {
+  installShutdownHandlers();
+  if (runtimeAbort.signal.aborted) runtimeAbort = new AbortController();
+  runtimeInitialization ??= initializeRuntime();
+}