serve.ts

// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.

import { Args, Command, Flags } from '@oclif/core';
import path from 'path';
import fs from 'fs';
import net from 'net';
import chalk, { chalkStderr } from 'chalk';
import { bundleRequire } from 'bundle-require';
import { loadConfig, BUNDLE_REQUIRE_EXTERNALS } from '../utils/config.js';
import { mergeBootConfig } from '../utils/merge-boot-config.js';
import { provisionTelemetryDatasource, standaloneTelemetryPrimary } from '../utils/telemetry-datasource.js';
import { isHostConfig, shouldBootWithLibrary } from '../utils/plugin-detection.js';
import { readInternalArtifactPath, readInternalConfigOutputPath } from '../utils/internal-artifact-channel.js';
import { makeDirectorySync } from '../utils/make-directory.js';
// The precedence's last rung — whether the cwd config takes part — decided by
// the SAME predicate the supervisors print their `Config:` row by (#21501).
import { cwdConfigJoinsBoot } from '../utils/artifact-precedence.js';
import {
  resolveDriverType,
  resolveStorageDefinition,
  loadTursoDriverFactory,
  isTursoDriverId,
  MissingDriverPackageError,
  UnsupportedDriverError,
} from '../utils/storage-driver.js';
// [ADR-0105 D1] `resolveMultiOrgEnabled` is deliberately NOT imported here: the
// posture is the authoritative knob and `resolveTenancyPosture()` already folds
// the legacy boolean in as its unset-fallback. serve's last direct reader of the
// boolean was the banner, and that was exactly the drift #4801 fixed.
import { readEnvWithDeprecation, resolveTenancyPosture, resolveAllowDegradedTenancy, isMcpServerEnabled, stampSearchPinyinEnabled, isModuleNotFoundError } from '@objectstack/types';
import { PLATFORM_CAPABILITY_TOKENS, PLATFORM_ALWAYS_ON_CAPABILITIES, RETIRED_PLATFORM_CAPABILITY_GUIDANCE } from '@objectstack/spec/kernel';
// [#22301] The `requires` token → provider table and its exact identity match,
// shared with `@objectstack/verify`'s `bootStack` — see `Serve.CAPABILITY_PROVIDERS`
// — and, beside it, which tokens a served boot mounts (`requires` plus the
// always-on slate) and what it constructs each provider with.
import {
  CAPABILITY_PROVIDERS,
  providesCapability,
  resolveServedCapabilities,
  resolveCapabilityArgument,
  materializeStackPlugin,
  STACK_TIER_PRESETS,
  CAPABILITY_TO_TIER as SHARED_CAPABILITY_TO_TIER,
  resolveStackTiers,
  resolveAuthSecret,
  resolvePlatformAuthComposition,
  stackSuppliesAuthPlugin,
  stackDeclaresOrganizationRecordPage,
  isDevelopmentBoot,
  type CapabilitySpec,
} from '@objectstack/core';
// The posture vocabulary, read from the package that DEFINES it (#5359) — the
// boot gate's fix list enumerates the accepted values, and a second literal
// list would be free to drift the day a posture is added.
import { TENANCY_POSTURES, type TenancyPosture } from '@objectstack/spec/security';
// #17329 — the PUBLISHED settlement contract, READ rather than re-derived, so
// the `objectstack:seed-settled` announcement below asks the one component that
// knows whether this boot's seeding has come to rest. The service is registered
// by the runtime this command itself boots (`@objectstack/runtime`'s
// `declareSeedSource`); `packages/cli` never registers or mutates it — the
// contract is deliberately read-only, because a consumer that could edit the
// tally could certify itself.
import {
  SEED_SETTLEMENT_SERVICE,
  type ISeedSettlementService,
  type SeedSettlementSnapshot,
  type SeedSuppressionReason,
} from '@objectstack/spec/contracts';
import { missingProviderMessage } from '../utils/capability-preflight.js';
// The deployment's product name, for `AuthPlugin` — the same resolver the email
// capability's template context reads (`resolveEmailCapabilityArg`), so the two
// cannot disagree. Both moved to `@objectstack/plugin-email` beside the mail
// provider vocabulary they read (#22301; see the re-exports at the foot of this
// file). The capability loop still loads `EmailServicePlugin` itself with a bare
// `import()`, resolved against THIS CLI's own realpath — its bundled copy always
// wins, never the host app's — and reads the email and SMS readers off that
// module. Contrast `importConfigPlugin` below, which IS host-anchored: an
// app-declared package wins there (per commit 5a90c56d1).
import { resolveDeploymentAppName } from '@objectstack/plugin-email';
import { createHash } from 'node:crypto';
import { resolveObjectStackHome } from '@objectstack/runtime';
import { LOG_LEVELS, resolveLogLevel, readLogLevelEnv } from '../utils/log-level.js';
// The ONE port contract — range, reader and refusal prose — shared with the two
// commands that spawn this one (#12673). `serve`'s own door below calls it
// exactly as `dev` and `start` call it, and it is the only place the range is
// declared; see the module docblock for why it is not an oclif flag `parse`.
import {
  describePortSource,
  parseRequestedPort,
  formatInvalidPortNotice,
  portTextReadNotice,
  MAX_PORT,
  type PortInputSource,
} from '../utils/port-contract.js';
// The ONE dev-TLS contract, shared with `dev` (which spawns this command) so the
// protocol the parent derives and the protocol this process actually binds come
// from a single reader (#16804). ⛔ Nothing about certificates is declared in
// this file, and ⛔ nothing anywhere generates one — see that module's header.
import {
  devTlsCertFlag,
  devTlsKeyFlag,
  resolveDevTlsIntent,
  readDevTlsMaterial,
  listenerProtocol,
  colorizeDevTlsNotice,
  type DevTlsMaterial,
  type ListenerProtocol,
} from '../utils/dev-tls-contract.js';
import { BootLogCapture, isVerboseBootLevel } from '../utils/boot-log-capture.js';
import { graftAuthoredRuntimeMembers, isAppPluginLike } from '../utils/graft-runtime-hooks.js';
// [ADR-0130 D4 / option B, #15006] Every read below that keys off a
// PACKAGE-OWNED collection goes through this seam, so an option-B artifact
// (flattened top level gone, `packages[]` carrying everything once) reaches
// the same decision — and so the acceptance probe can CALL the decision
// instead of re-implementing it.
import {
  shouldAutoRegisterObjectQL,
  shouldAutoRegisterStorageDriver,
  stackDeclaresMetadata,
  bundleDeclaresTranslations,
  resolveStackCollection,
  stackDeclaredCapabilities,
  stackBootPlugins,
} from '../utils/stack-collections.js';
import { redactConnectionUrl, describeDriverConnection, describeDriverSqliteFile } from '../utils/connection-display.js';
import { captureServedDatabaseFile, watchServedDatabaseFile } from '../utils/served-database-file.js';
// The posture prose `os serve` and `os doctor` BOTH print, declared once
// (#12492) — and, since #12579, the multi-org runtime SPELLING those two
// commands put in front of the same operator, declared once with it.
//
// Renamed on import so `Serve.ORGANIZATIONS_RUNTIME_PKG` below keeps its own
// NAME: separate pins address that static by name, and only the spelling moved.
import {
  ORGANIZATIONS_RUNTIME_PKG as SHARED_ORGANIZATIONS_RUNTIME_PKG,
  TENANCY_POSTURE_FIX_HINTS,
} from '../utils/tenancy-posture-hints.js';
// Shared with @objectstack/verify and the dogfood multi-org probes (#4700) —
// node-only, hence the `/node` subpath rather than the edge-safe root export.
import {
  createHostImporter,
  hostImportFailureKind,
  isDeclaredByHost,
  packageNameFromSpecifier,
  readHostDeclaration,
  type HostDeclaration,
  type HostImporter,
  type HostImportFailureKind,
} from '@objectstack/types/node';
import {
  printHeader,
  printKV,
  printSuccess,
  printError,
  printStep,
  printInfo,
  printServerReady,
  printBootDiagnostics,
  type AutomationReadySummary,
  type HttpServerComposition,
  type SeedSourceSummary,
} from '../utils/format.js';
// [#16630] The reader half of the degraded-boot data path — the kernel's own
// missing-core-service list, fetched, never re-derived. See its header.
import { readMissingCoreServices } from '../utils/degraded-capabilities.js';
import { redirectStdoutToStderr } from '../utils/json-stdout.js';
import {
  CONSOLE_PATH,
  resolveConsolePath,
  hasConsoleDist,
  decideConsoleMount,
  formatConsoleShaDriftWarning,
  formatConsoleShaDriftRefusal,
  formatConsoleDistMissingWarning,
  createConsoleStaticPlugin,
  createConsoleNotBuiltPlugin,
  createConsoleShaDriftRefusalPlugin,
  createRuntimeAssetsPlugin,
  type ConsoleShaDrift,
} from '../utils/console.js';
// [#22579] The project's `.env*` files, loaded by the one function `os migrate`'s
// boot (`bootSchemaStack`) loads them through too.
import { loadProjectEnvFiles } from '../utils/schema-migrate.js';
// Metric NAMES and the metrics-service name, from the package that owns both.
// `buildServeObservability()` below reaches the same package through a dynamic
// `import()` with a "not installed — silently skip" catch; this STATIC import
// adds no new failure mode on top of it, and the measurement is written down
// so the next reader does not have to re-derive it: `@objectstack/runtime` is
// imported statically a few lines above, its index re-exports
// `./observability/index.js`, and that module statically imports
// `@objectstack/observability` for `OBSERVABILITY_METRICS_SERVICE`. So loading
// this command already requires the package to resolve; the dynamic form there
// is about the exporter CLASSES, not about reachability.
import { SEMCONV, OBSERVABILITY_METRICS_SERVICE, type MetricsRegistry } from '@objectstack/observability';

// ---------------------------------------------------------------------------
// Observability bootstrap for `objectstack serve`
//
// Reads OS_OBS_* env vars and returns a `{ metrics, errorReporter }` block
// to hand off to `createDispatcherPlugin`. Default is fully noop so the
// CLI imposes no runtime cost when observability isn't configured.
//
// Env knobs — the SAME names are also read by the cloud host
// (`apps/cloud/server/observability.ts`, cloud repo), so keep the two in sync
// if you tweak NAMES. That duty is live, not stale prose: the cloud file reads
// these as `process.env` lookups — measured on #15295 for every knob listed
// below EXCEPT `OS_OTLP_FLUSH_MS`, which was added on this side afterwards and
// has never been measured against that repository: treat that one as
// unverified rather than mirrored.
//
// ⛔ NAMES only — the DEFAULTS differ on purpose, and unifying them is a
// telemetry regression rather than a tidy-up: `OS_OBS_SERVICE_NAME` defaults
// to `objectstack` here and to `objectstack-cloud` there because two
// deployments are two services; collapsing them merges both into one series.
//
// The canonical home for this list is `@objectstack/observability` — the
// package BOTH sides already import (statically, a few lines above; the cloud
// file imports it too) — not these comments pointing at each other, which
// is how the duty decayed to begin with: it is one-sided today, the cloud file
// carries no reciprocal sentence, so nobody renaming a name over there is
// prompted to come back here. Until the list lives in that package, this block
// is it, and moving the cloud half is a change in the cloud repo (#17693).
//
// ⚠️ And the carriers are not two but three:
// `content/docs/deployment/environment-variables.mdx` (`## Observability`)
// publishes this same list with types and defaults, and it is the one most
// readers reach first. Its `OS_OBS_SERVICE_NAME` row states the framework
// default with no note that the cloud host differs on purpose, so the
// NAMES-only rule above has to be honoured there too. Fixing that page is out
// of this block's scope; the caveat rides with the canonical-home decision
// (#17693).
//   OS_OBS_EXPORTER       noop (default) | console | json | otlp
//   OS_OTLP_ENDPOINT      OTLP/HTTP root, e.g. https://otlp.grafana.net/otlp
//   OS_OTLP_HEADERS       comma-separated Key=Value; values may be URL-encoded
//                         (Grafana ships `Authorization=Basic%20<base64>`)
//   OS_OBS_SERVICE_NAME   resource attr, default `objectstack`
//   OS_OBS_DEPLOYMENT_ENV resource attr, default `production`
//   OS_OTLP_FLUSH_MS      buffer flush interval (default 10000)
// ---------------------------------------------------------------------------

function parseObsHeaders(spec: string | undefined): Record<string, string> {
  if (!spec) return {};
  const out: Record<string, string> = {};
  for (const pair of spec.split(',')) {
    const i = pair.indexOf('=');
    if (i < 0) continue;
    const k = pair.slice(0, i).trim();
    const raw = pair.slice(i + 1).trim();
    if (!k) continue;
    let v = raw;
    try { v = decodeURIComponent(raw); } catch { /* keep raw */ }
    out[k] = v;
  }
  return out;
}

async function buildServeObservability(): Promise<{ metrics: any; errorReporter: any } | undefined> {
  const exporter = (process.env.OS_OBS_EXPORTER ?? 'noop').toLowerCase();
  if (exporter === 'noop') return undefined; // dispatcher falls back to its own NoopMetricsRegistry
  let mod: any;
  try {
    mod = await import('@objectstack/observability');
  } catch {
    return undefined; // observability pkg not installed — silently skip
  }
  try {
    let metrics: any;
    if (exporter === 'console' || exporter === 'json') {
      metrics = new mod.ConsoleMetricsRegistry();
    } else if (exporter === 'otlp') {
      const endpoint = process.env.OS_OTLP_ENDPOINT;
      if (!endpoint) {
        console.warn('[observability] OS_OBS_EXPORTER=otlp but OS_OTLP_ENDPOINT is empty — falling back to noop');
        return undefined;
      }
      const resource = {
        'service.name': process.env.OS_OBS_SERVICE_NAME ?? 'objectstack',
        'deployment.environment': process.env.OS_OBS_DEPLOYMENT_ENV ?? 'production',
      };
      metrics = new mod.OtlpHttpMetricsRegistry({
        endpoint,
        headers: parseObsHeaders(process.env.OS_OTLP_HEADERS),
        resource,
        onError: (err: unknown) => {
          console.warn('[observability] OTLP export failed:', (err as any)?.message ?? err);
        },
      });
      const flushMs = Number(process.env.OS_OTLP_FLUSH_MS ?? '10000');
      if (flushMs > 0) {
        const timer = setInterval(() => {
          (metrics as any).flush?.().catch(() => { /* swallowed via onError */ });
        }, flushMs);
        if (typeof (timer as any).unref === 'function') (timer as any).unref();
      }
    } else {
      return undefined;
    }
    const errorReporter = new mod.ConsoleErrorReporter();
    return { metrics, errorReporter };
  } catch (err) {
    console.warn('[observability] init failed; falling back to noop:', (err as any)?.message ?? err);
    return undefined;
  }
}

// Probe whether a TCP port can be bound right now.
const isPortAvailable = (port: number): Promise<boolean> => {
  return new Promise((resolve) => {
    const server = net.createServer();
    server.once('error', () => {
      resolve(false);
    });
    server.once('listening', () => {
      server.close(() => resolve(true));
    });
    server.listen(port);
  });
};

/**
 * How far past `startPort` the dev auto-shift search walks before giving up.
 *
 * ⚠️ This is a SPAN, not a count: the search probes `startPort` itself and then
 * every port up to and including `startPort + PORT_SEARCH_SPAN`, so the number
 * of ports actually probed is `PORT_SEARCH_SPAN + 1`. Both numbers are read
 * from this one constant — by the loop below and by
 * {@link formatExhaustedPortSearchNotice}, which states the range to the
 * operator. ⛔ Never hand-write either number anywhere else: an off-by-one
 * inside a diagnostic that exists to be accurate is the defect it was added to
 * fix (#12620).
 */
const PORT_SEARCH_SPAN = 100;

/**
 * The one thing {@link getAvailablePort} does to the outside world, injectable
 * so its exhausted path can be driven without binding a socket.
 *
 * ⛔ The alternative is a test that holds 101 real ports: slow, flaky, and
 * hostile to a shared many-agent container whose ephemeral range is already
 * crowded (#12441 measured that contention costing a suite a red run). The
 * production call site passes nothing and gets {@link isPortAvailable}.
 */
type PortProbe = (port: number) => Promise<boolean>;

/**
 * Helper to find available port (dev convenience — see the gated caller).
 *
 * A plain contiguous `port++` walk: `startPort`, `startPort + 1`, … with **no
 * skip**. ⚠️ Nearby cards have described this search as hopping over ports; it
 * does not, and a diagnostic written from that reading would be wrong.
 */
export class PortSearchExhaustedError extends Error {
  /** The first port probed — the walk's own record of it, not the caller's. */
  readonly startPort: number;
  /** The last port probed. Inclusive, and derived from {@link PORT_SEARCH_SPAN}. */
  readonly lastPort: number;
  /** How many ports were probed: every one of them, and every one busy. */
  readonly probedCount: number;

  constructor(startPort: number) {
    // ⭐ The message is UNCHANGED from the plain `Error` this replaces. It is
    // the sentence the notice carries verbatim, so it is not the class's to
    // reword — the type is added to say WHICH failure this is, not to say it
    // differently.
    super(`Could not find an available port starting from ${startPort}`);
    this.name = 'PortSearchExhaustedError';
    this.startPort = startPort;
    this.lastPort = startPort + PORT_SEARCH_SPAN;
    this.probedCount = PORT_SEARCH_SPAN + 1;
  }
}

export const getAvailablePort = async (
  startPort: number,
  probe: PortProbe = isPortAvailable,
): Promise<number> => {
  let port = startPort;
  while (!(await probe(port))) {
    port++;
    if (port > startPort + PORT_SEARCH_SPAN) {
      throw new PortSearchExhaustedError(startPort);
    }
  }
  return port;
};

/**
 * The notice for a search that ran out of ports (#12620).
 *
 * ## The fallthrough is deliberate; the SILENCE was the defect
 *
 * When {@link getAvailablePort} exhausts its span the caller swallows the throw
 * and binds `requestedPort` anyway — which is defensible on its own terms: a
 * dev whose whole next span is busy arguably wants the requested port attempted
 * rather than a hard refusal. ⛔ Whether it should refuse instead is #11113's
 * production/development policy split and is deliberately NOT decided here;
 * nothing in this function changes what `os serve` does.
 *
 * What is not defensible is doing it in silence. This is the one shape in the
 * whole port policy where the operator gets **neither** half of the legibility
 * work this family has landed: the production `Port … is already in use` line
 * lives in the `else if` this boot never enters, and #12543's drift notice is
 * gated on `port !== requestedPort`, which on this path is false because the
 * assignment never happened. The boot then dies on the kernel's raw error with
 * the accurate explanation discarded one line earlier.
 *
 * ## ⭐ It CARRIES the thrown message; it does not paraphrase it
 *
 * `Could not find an available port starting from ${startPort}` already names
 * the problem exactly. Rewriting it into a fresh sentence would create a second
 * spelling of one fact, free to drift from the first. So the caught error's own
 * `message` is the headline, verbatim, and every other line here adds a
 * DIFFERENT fact: how wide the search was, what happens next, and what to do.
 *
 * `cause` is typed `unknown` and rendered defensively rather than narrowed to
 * `Error`: the point is to carry whatever text the seam actually produced, and
 * a probe that rejects with a non-`Error` must not turn this notice into
 * `[object Object]`.
 *
 * ## CHANNEL — measured, not chosen (#7915)
 *
 * The caller writes this through `printDiagnostic`, straight to **stderr**.
 * `stdout` is the JSON-RPC channel whenever the stdio MCP transport is mounted,
 * where one non-frame line reaches a conforming client as a transport error;
 * `serve-stdio-stdout-purity.e2e.test.ts` exists to pin exactly that.
 */
export function formatExhaustedPortSearchNotice(requestedPort: number, cause: unknown): string {
  // ⭐ The thrown text, carried — not restated. See the docblock.
  const thrown = cause instanceof Error ? cause.message : String(cause);

  // ⚠️ The `catch` this feeds catches EVERY rejection, not only an exhausted
  // walk, and the two cannot share a body. `isPortAvailable` rejects
  // synchronously with `ERR_SOCKET_BAD_PORT` whenever it is handed a port
  // outside 0–65535 — reachable by a walk that starts high enough to cross the
  // ceiling. (⚠️ It used to be reachable a second way, from `--port` text that
  // `parseInt` turned into `NaN`; since #12662 that value is refused before
  // this policy runs, so a crossing walk is the only route left. The branch
  // below is unchanged: the walk route still reaches it.) On that path
  // nothing was exhausted, so a body claiming a probed range would
  // print `NaN–NaN` and assert a search that never ran. A diagnostic that
  // exists to be accurate does not get to guess, so the span sentence is
  // reached only through the error that actually carries the span.
  if (!(cause instanceof PortSearchExhaustedError)) {
    return (
      '\n'
      + chalk.yellow(`  ⚠ ${thrown}\n`)
      + chalk.dim('     The development port search could not run to completion, so this server\n')
      + chalk.dim(`     is falling back to the port it was asked for (${requestedPort}). If that port is\n`)
      + chalk.dim('     taken the bind that follows will fail with a raw EADDRINUSE from the\n')
      + chalk.dim('     kernel, and this notice is the only place that says why.')
    );
  }

  // Every number below is the ERROR's own, recorded by the walk that failed —
  // never re-derived here from `requestedPort`, which is a second source that
  // could disagree with the first.
  const { startPort, lastPort, probedCount } = cause;
  return (
    '\n'
    + chalk.yellow(`  ⚠ ${thrown}\n`)
    + chalk.dim(`     Development auto-shift probed ${probedCount} ports (${startPort}–${lastPort}) and every\n`)
    + chalk.dim(`     one was busy, so this server is falling back to ${startPort} — the port the\n`)
    + chalk.dim('     search has just proven is taken. The bind that follows will almost\n')
    + chalk.dim('     certainly fail with a raw EADDRINUSE from the kernel, and this notice\n')
    + chalk.dim('     is the only place that says why.\n')
    + chalk.dim(`     Free a port in ${startPort}–${lastPort}, or pick another via PORT=<port> (or --port <port>).`)
  );
}

/**
 * The port the HTTP server ACTUALLY bound, read off the transport that bound it
 * (#13062).
 *
 * ## The defect this closes
 *
 * `serve` used to publish the port it was ASKED for on all three of the
 * channels that ANNOUNCE an address — the `objectstack:listening` IPC message,
 * the ready banner's `API:` row (through {@link resolveAuthBaseUrl}), and
 * `runtime.<environment>.<project>.json`. For every port but one the requested
 * and the bound value coincide, which is why it stayed invisible; for `0` they
 * CANNOT coincide. `MIN_PORT = 0` is legal on purpose — `utils/port-contract.ts` says
 * so in its own words, from its own measurement, that 0 is "a REQUEST, not an
 * error", and `listen(0)` binds a kernel-assigned port. So `os serve --port 0`
 * announced `{ port: 0 }`, printed `API: http://localhost:0/` and wrote
 * `"port": 0`: three channels naming an address nothing is listening on, and
 * nothing anywhere erroring.
 *
 * ## Where the answer comes from, and why it is not a second measurement
 *
 * `IHttpServer.getPort?()` is a DECLARED contract member
 * (`@objectstack/spec/contracts`): *"after `listen()` resolves, implementations
 * that provide this member MUST return the real bound port — in particular when
 * `listen(0)` requested an ephemeral port"*. The Hono transport fills it from
 * `@hono/node-server`'s own listening callback (`info.port`, the socket's
 * `address().port`). So this asks the one component that KNOWS instead of
 * re-deriving the number from the request — the same rule
 * {@link formatExhaustedPortSearchNotice} follows just above, where every number
 * printed is the failing walk's own record rather than a recomputation.
 *
 * ## The fallback IS today's behaviour, deliberately
 *
 * A boot with no transport (`--server=false`), a host that mounts a transport
 * not implementing the optional member, or an answer that cannot be a bound
 * port, all return `requestedPort` — exactly what every channel published
 * before this function existed. This repair may not narrow what boots.
 *
 * ⚠️ On the first of those — no transport at all — the number names nothing
 * that listens, so `serve` publishes it on no channel (#23743): the publish
 * site is gated on {@link resolveHttpServerComposition}, not on this value.
 *
 * ⛔ `0` is NOT accepted as an ANSWER here, though it is a legal REQUEST: no
 * socket is ever bound to port 0, so a transport reporting it has not listened
 * yet (`HonoHttpServer.getPort()` falls back to its constructor argument until
 * `listen()` resolves), and republishing it is the defect itself.
 */
export function resolveBoundPort(
  kernel: { getService?: (name: string) => unknown } | undefined,
  requestedPort: number,
): number {
  const server = readComposedHttpServer(kernel) as { getPort?: () => unknown } | undefined;
  if (typeof server?.getPort !== 'function') return requestedPort;
  let reported: unknown;
  try {
    reported = server.getPort();
  } catch {
    return requestedPort;
  }
  if (typeof reported !== 'number' || !Number.isInteger(reported)) return requestedPort;
  if (reported <= 0 || reported > MAX_PORT) return requestedPort;
  return reported;
}

/**
 * The HTTP server this boot composed: the kernel's `http.server` service, or
 * `undefined` when nothing registered one.
 *
 * The ONE read behind both {@link resolveBoundPort} (which port the transport
 * bound) and {@link resolveHttpServerComposition} (whether there is a
 * transport at all), so the banner's address and the banner's decision to
 * print one cannot come from two different answers.
 *
 * `http.server` is the CANONICAL service name; `http-server` is a deprecated
 * alias for the same instance (#4251) that new code must not read. ⚠️
 * `getService` THROWS when nothing registered the name — it does not return
 * undefined — hence the `try`, not a `?.` chain alone.
 */
export function readComposedHttpServer(
  kernel: { getService?: (name: string) => unknown } | undefined,
): unknown {
  try {
    return kernel?.getService?.('http.server') ?? undefined;
  } catch {
    return undefined;
  }
}

/**
 * Whether this boot serves HTTP, for the ready banner's address rows (#23623).
 *
 * Read off the booted kernel, not off `--server`: under `--no-server` a config
 * can still mount its own `HonoServerPlugin` (serve skips only its own
 * auto-wired one), and then an `http.server` is registered and its address is
 * real. `serverFlag` only says WHY there is none, so the banner names
 * `--no-server` when that flag is what left the boot without one, and not
 * otherwise.
 */
export function resolveHttpServerComposition(
  kernel: { getService?: (name: string) => unknown } | undefined,
  serverFlag: boolean,
): HttpServerComposition {
  if (readComposedHttpServer(kernel) !== undefined) return 'composed';
  return serverFlag ? 'not-composed' : 'skipped-by-no-server';
}

/**
 * The plugin that mounts `/api/v1/mcp` (and `/api/v1/mcp/skill`): the runtime
 * dispatcher, `createDispatcherPlugin` in `@objectstack/runtime`. The same
 * name `HonoServerPlugin` asks the kernel about before it warns that no data
 * or discovery API is mounted.
 */
export const MCP_ROUTE_OWNER_PLUGIN = 'com.objectstack.runtime.dispatcher';

/**
 * Whether the plugin that mounts the MCP route is composed on this boot
 * (#23743), for the ready banner's `MCP:` row.
 *
 * ## The defect this closes
 *
 * `os serve objectstack.config.ts --no-server` with a config that mounts its
 * own `HonoServerPlugin` printed `MCP: http://localhost:PORT/api/v1/mcp` and
 * its connect hint, and `GET /api/v1/mcp` answered 404 while
 * `/api/v1/data/<object>` answered 401: the transport listened, the route did
 * not exist. The dispatcher that mounts it is composed only inside `serve`'s
 * `if (flags.server)` block, and the row was gated on `http.server` (#23623)
 * and on the MCP switch, neither of which says whether the route is mounted.
 *
 * ## Why this read
 *
 * Read off the booted kernel, like {@link readComposedHttpServer}, so a config
 * that mounts its own dispatcher is answered too. The dispatcher registers no
 * service (it only consumes `http.server`), so the kernel's plugin registry is
 * the read: `hasPlugin` answers for every `kernel.use()` already made, and by
 * the time the banner prints every one has been. The dispatcher mounts the
 * route in its own `start()` only when an `http.server` is registered, so the
 * caller pairs this with a composed transport.
 *
 * `false` when the kernel cannot answer (no `hasPlugin`, or it throws): an
 * unanswerable question must not print a URL an AI client will be pointed at.
 */
export function readComposedMcpRouteOwner(
  kernel: { hasPlugin?: (name: string) => boolean } | undefined,
): boolean {
  try {
    return typeof kernel?.hasPlugin === 'function' && kernel.hasPlugin(MCP_ROUTE_OWNER_PLUGIN) === true;
  } catch {
    return false;
  }
}

/**
 * The period of {@link holdKernelOnlyProcess}'s handle: the largest delay a
 * Node timer accepts (2^31 - 1 ms, about 24.8 days). Its callback does nothing,
 * so the period decides only how rarely the event loop wakes for it.
 */
const KERNEL_ONLY_HOLD_PERIOD_MS = 0x7fffffff;

/**
 * Keep a boot that composes no HTTP transport alive until its kernel stops
 * (#23744).
 *
 * ## The defect this closes
 *
 * `os serve objectstack.config.ts --no-server --preset minimal`, in production
 * with no `OS_DATABASE_URL`, printed its ready banner ending `Press Ctrl+C to
 * stop` and then exited 0 by itself, milliseconds later, with no signal and
 * without its kernel ever shutting down. On a composed boot the HTTP listener
 * holds the event loop. With none composed, nothing this command owns did. The
 * same command stayed up whenever the storage driver happened to keep a
 * connection pool (`--dev --no-server`, or `--no-server` with
 * `OS_DATABASE_URL` set): measured, the only ref'd handle on those boots was
 * the SQL driver's pool-reaping interval. So whether a kernel-only boot stayed
 * up depended on the driver, and nothing decided it.
 *
 * ## Why "stay up" and not "run and exit"
 *
 * - The banner says `Press Ctrl+C to stop`.
 * - The kernel is built to own the process: under `gracefulShutdown` a signal
 *   drains it and then exits.
 * - The platform's background loops are `unref()`ed on purpose, so they never
 *   keep a process alive by themselves (`DispatchLoop` in `@objectstack/core`).
 *   The host decides the lifetime.
 * - The run-and-exit kernel boot already exists, and is explicit:
 *   `OS_MIGRATE_AND_EXIT=1` shuts the kernel down and exits before any banner.
 *
 * ## The mechanism
 *
 * One ref'd interval whose callback does nothing. It is a handle, not a
 * timeout: it ends nothing and decides nothing. The kernel's own shutdown
 * releases it (`onShutdown`), so the kernel's signal handling stays the only
 * thing that ends the process, with the kernel's exit code. ⛔ No signal
 * listener here: the kernel installs its own, and a second one is how one
 * SIGTERM used to exit a process more than once (#22286).
 *
 * Returns the handle, for the pin that reads it.
 */
export function holdKernelOnlyProcess(
  kernel: { onShutdown(handler: () => Promise<void>): void },
): ReturnType<typeof setInterval> {
  const hold = setInterval(() => {}, KERNEL_ONLY_HOLD_PERIOD_MS);
  kernel.onShutdown(async () => {
    clearInterval(hold);
  });
  return hold;
}

/**
 * The `objectstack:listening` IPC message the `os dev` parent waits for.
 *
 * Sent only when an HTTP transport is composed (#23743): its documented
 * meaning is "The HTTP server is bound", so a boot that binds none sends no
 * such message rather than one naming a port nothing listens on.
 */
export interface ListeningMessage {
  type: 'objectstack:listening';
  port: number;
  url: string;
}

/**
 * The `objectstack:seed-settled` IPC message — "this boot's seeding has come to
 * rest" (#17329).
 *
 * ## The defect this closes
 *
 * `✓ Server is ready` is true about the HTTP SERVER and says nothing about the
 * APP. `AppPlugin` races its inline seed against a soft budget
 * (`OS_INLINE_SEED_BUDGET_MS`, default 8s); over budget it hands the rest to a
 * detached promise and the kernel starts anyway. So the banner can print, the
 * parent can proceed, and eighty seconds later the continuation emits its error
 * wall — and a parent that merely spawned the child has no readable signal that
 * distinguishes that boot from one that seeded cleanly before the banner. Which
 * side wins is decided by whether the seed fits its budget on a contended box,
 * so the same command on the same corpus disagrees between two containers.
 *
 * Every signal that WOULD distinguish them — the over-budget warning, the error
 * wall, the completion summary — arrives on the child's inherited stdio. Reading
 * it costs the boot its TTY. This message is the same fact on the channel the
 * parent already holds.
 *
 * ## When it is sent, and the one guarantee that makes it waitable
 *
 * Exactly once per boot, and never before {@link ListeningMessage}: seeding that
 * settles DURING `runtime.start()` (the ordinary in-budget boot) is latched and
 * released after {@link publishBoundPort} has driven its three channels, so a
 * parent that waits for `objectstack:listening` first can never miss this one by
 * being late. See {@link createSeedSettlementAnnouncer}.
 *
 * On a boot that binds no HTTP server no {@link ListeningMessage} is sent at
 * all (#23743), and this one still is — it is then the boot's only message. A
 * kernel-only boot still seeds, and a parent waiting for the settle must not
 * hang for want of a listening message that is never coming.
 *
 * ## ⭐ `suppressed` is what keeps a waiting parent from hanging forever
 *
 * Two deployment shapes register a seed source and then deliberately never run
 * it, so `app:seeded` never fires and the contract's `pending` stays above zero
 * for the life of the process: **multi-tenant** (seeds replay per organization
 * on `sys_organization` insert) and **`skipSeedData`** (an `os migrate` planning
 * boot that must not write). A message keyed on `pending === 0` would never be
 * sent in either, and its absence would be indistinguishable from a boot still
 * writing — the exact ambiguity this card exists to end, one level up.
 *
 * So the predicate is {@link SeedSettlementSnapshot.inFlight}, not `pending`:
 * *nothing is still writing*. Both modes reach `inFlight === 0` inside Phase 2
 * `start()` (`suppress()` decrements the in-flight tally and records the reason),
 * so the message is sent on those boots too — carrying the reasons, so a
 * consumer can say **why** no rows landed instead of waiting for rows that were
 * never coming. An empty `suppressed` with an empty `sources` is the third
 * honest answer: this kernel has no seed pipeline at all.
 */
export interface SeedSettledMessage {
  type: 'objectstack:seed-settled';
  /**
   * Whether every source that REPORTED an outcome reported a clean one — no
   * rejected records, no dropped references, no install that came up empty.
   *
   * ⛔ Read it against {@link sources}, never alone: it is a verdict on what the
   * seed summary contains, and a source that finished by throwing may record no
   * outcome at all. `true` over an empty {@link sources} means "nothing reported
   * a problem", which on a suppressed boot is simply "nothing ran".
   */
  ok: boolean;
  /**
   * One entry per source this boot deliberately did not run. Non-empty means
   * rows these datasets describe were never written by this process, and no
   * later signal is coming for them.
   */
  suppressed: readonly SeedSuppressionReason[];
  /** Per-source counts — the same array the banner's `Seeds:` row renders. */
  sources: SeedSourceSummary[];
}

/**
 * Read the published settlement tally off the kernel this command booted.
 *
 * `undefined` means no seed pipeline registered on this kernel — a FACT by
 * `kernel:ready`, since every source is declared in Phase 2 `start()`, and
 * therefore an answer ("nothing to wait for") rather than a not-yet. ⚠️
 * `getService` THROWS on an unregistered name rather than returning undefined,
 * hence the `try`.
 */
export function readSeedSettlement(
  kernel: { getService?: (name: string) => unknown } | undefined,
): SeedSettlementSnapshot | undefined {
  try {
    const svc = kernel?.getService?.(SEED_SETTLEMENT_SERVICE) as ISeedSettlementService | undefined;
    if (!svc || typeof svc.snapshot !== 'function') return undefined;
    const snapshot = svc.snapshot();
    // A tally that does not answer the one question is the same as no tally.
    if (typeof snapshot?.inFlight !== 'number') return undefined;
    return snapshot;
  } catch {
    return undefined;
  }
}

/**
 * Has this boot's seeding come to rest?
 *
 * ⛔ NOT `pending === 0`. `pending` counts suppressed sources forever by design
 * (see {@link SeedSettledMessage}), so keying on it would hang every
 * multi-tenant and `skipSeedData` boot. The question a parent is actually asking
 * is "is anything still writing", and that is `inFlight`.
 *
 * An absent snapshot is settled: no seed pipeline registered, so nothing is
 * outstanding and nothing more is coming.
 */
export function seedingHasSettled(snapshot: SeedSettlementSnapshot | undefined): boolean {
  return !snapshot || snapshot.inFlight === 0;
}

/** Build the message from the two things the kernel already knows. */
export function composeSeedSettledMessage(
  snapshot: SeedSettlementSnapshot | undefined,
  sources: SeedSourceSummary[] | undefined,
): SeedSettledMessage {
  const list = sources ?? [];
  return {
    type: 'objectstack:seed-settled',
    ok: list.every((s) => s.rejected === 0 && (s.droppedRefs ?? 0) === 0 && !s.emptyInstall),
    suppressed: snapshot ? [...snapshot.suppressed] : [],
    sources: list,
  };
}

/** What {@link createSeedSettlementAnnouncer} needs from its host. */
export interface SeedSettlementChannels {
  /** The live tally — re-read per use, never cached (the contract says so). */
  readSettlement: () => SeedSettlementSnapshot | undefined;
  /** The per-source counts the banner renders, or `undefined` if none ran. */
  readSummary: () => SeedSourceSummary[] | undefined;
  /** Sends {@link SeedSettledMessage}, when an IPC channel is open. */
  announceSettled: (message: SeedSettledMessage) => void;
}

/**
 * The latch that turns "seeding settled" into ONE message, in the one order it
 * is safe to send it in.
 *
 * ## Why a latch rather than a call at the settle point
 *
 * The two clocks this card is about run in EITHER order, and both have to work:
 *
 * ```text
 * in-budget  seed settles ─▶ kernel:ready ─▶ publishBoundPort ─▶ (release) ─▶ send
 * over-budget            kernel:ready ─▶ publishBoundPort ─▶ (release) … ─▶ app:seeded ─▶ send
 * ```
 *
 * {@link check} is called from both the `app:seeded` and `kernel:ready` hooks;
 * {@link release} is called once, after {@link publishBoundPort} has driven its
 * three channels. Before the release nothing is sent, so a settle that happened
 * during `runtime.start()` cannot overtake `objectstack:listening`; after it,
 * the first `check` that finds nothing in flight sends and closes the latch.
 *
 * ⛔ The `kernel:ready` leg is not redundant with `app:seeded`. A suppressed
 * boot (multi-tenant, `skipSeedData`) NEVER fires `app:seeded` — `emitSeedSettled`
 * lives only on the branch that actually seeds — so `kernel:ready` is the only
 * hook that runs on those boots, and dropping it is exactly how a waiting parent
 * would hang forever there.
 *
 * ⛔ And it is not a poll. Every leg is an event the kernel already emits; the
 * latch only decides which of them is allowed to be the one that speaks.
 */
export function createSeedSettlementAnnouncer(channels: SeedSettlementChannels): {
  /** Re-evaluate: send iff released, not yet sent, and nothing in flight. */
  check: () => void;
  /** Open the gate — call AFTER the bound-port channels have been driven. */
  release: () => void;
} {
  let released = false;
  let sent = false;

  const check = () => {
    if (!released || sent) return;
    const snapshot = channels.readSettlement();
    if (!seedingHasSettled(snapshot)) return;
    sent = true;
    channels.announceSettled(composeSeedSettledMessage(snapshot, channels.readSummary()));
  };

  return {
    check,
    release: () => {
      released = true;
      check();
    },
  };
}

/**
 * The three channels {@link publishBoundPort} drives — declared in the ONE
 * order it is safe to drive them in, which is also the order the fields are
 * listed here.
 */
export interface BoundPortChannels {
  /**
   * Writes `runtime.<environment>.<project>.json`. ⛔ Must COMPLETE before
   * either announcement below: it is the file both of them send a consumer to.
   * Best-effort: when it cannot be written the boot goes on, and the real
   * channel says so once, naming the file (#24091).
   */
  writeRuntimeState: (published: { port: number; url: string }) => void;
  /**
   * Prints the ready banner, whose `API:` row names the same address when an
   * HTTP server is composed (#23623), and the boot diagnostics under it. ⛔ Must COMPLETE before the IPC message below:
   * the `os dev` parent prints its MCP connect block on that message, into the
   * same terminal (#22410).
   */
  printBanner: () => void;
  /** Sends {@link ListeningMessage}, when an IPC channel is open. LAST — see above. */
  announceListening: (message: ListeningMessage) => void;
}

/**
 * Publish the bound port on all three channels, in the one order that is safe.
 *
 * Driven only when an HTTP transport is composed (#23743): a boot with none has
 * no bound port to publish, and prints the banner alone.
 *
 * ## The bug this shape exists to make impossible
 *
 * `os serve` announces its address on three channels: the runtime state file
 * `runtime.<environment>.<project>.json`, the `objectstack:listening` IPC
 * message, and the ready banner. Two of those are ANNOUNCEMENTS a consumer
 * reacts to; the third is the FILE those consumers then open. Published in the order they
 * happened to be written — banner, IPC, file — every consumer that believes an
 * announcement races a file that is not there yet:
 *
 * ```text
 * banner  ─▶ a supervisor sees "ready" and opens runtime.env_local.<project>.json
 * IPC     ─▶ the `os dev` parent sees the port
 * file    ─────────────────────────▶ ...written here. The ENOENT already happened.
 * ```
 *
 * ⛔ Not hypothetical, and ⛔ not a test artefact. The e2e that pins #13062's
 * claim (`serve-publishes-bound-port.e2e.test.ts`) is an ORDINARY consumer — it
 * waits for the banner AND the IPC message, then reads the file — and it
 * ejected 14 PRs from the shared merge queue in a rolling 24 hours (10
 * independent hits, #13158) with `ENOENT: ... runtime.env_local.json` — the
 * name that file carried then, before {@link runtimeStateFileName} keyed it by
 * project as well. A real supervisor written the same way loses the same race;
 * all a loaded machine does is deschedule the child between the announcement
 * and the write, which is why it read as a flake for a day.
 *
 * ⛔ The repair is NOT to make the reader poll. A consumer that must poll after
 * being told "ready" was told "ready" too early — polling spreads the defect
 * into every consumer forever and hides it from the one place that can fix it.
 * The producer owns the ordering: **write the file, THEN announce it.**
 *
 * ## The second race: two processes, one terminal (#22410)
 *
 * The IPC message is not only a fact for a program. The `os dev` parent prints
 * its MCP connect block (`🤖 MCP server — connect a coding agent:` and its
 * Endpoint / Skill / Connect / Disable rows) the moment the message arrives,
 * into the terminal this process writes its banner to. Sent BEFORE the banner,
 * the two processes wrote that terminal at once: measured under a pty on the
 * Build-with-Claude-Code tutorial project, 6 of 7 boots printed the block
 * above or inside the banner, 2 of them with banner lines inside the block, and
 * one probe boot printed the whole credential and plugin section between
 * `Skill` and `Connect`.
 *
 * So the banner comes SECOND and the message LAST. That makes the order
 * causal, not timed: the banner is written synchronously (a terminal is
 * synchronous stdio on POSIX, and `keepStderrNonBlocking` leaves a TTY
 * alone), so every banner byte is in the terminal before the message is sent,
 * and the parent prints only on receipt. ⛔ No sleep or timer orders anything
 * here. The message's shape is unchanged; it arrives a banner's print later.
 *
 * ## Why the channels are injected rather than called inline
 *
 * The ORDER is the contract here, and an order is only pinned by a test that
 * can observe it. Passing the channels in lets
 * `serve-bound-port-publish-order.test.ts` record the sequence and go red
 * DETERMINISTICALLY the day it is reversed. An end-to-end test cannot do that:
 * it can only lose the race often enough for someone to notice — which is
 * precisely the year-of-flakes this replaces.
 */
export function publishBoundPort(
  boundPort: number,
  channels: BoundPortChannels,
  boundProtocol: ListenerProtocol = 'http',
): void {
  // ⭐ The SOCKET's own address, so the scheme has to be the one the socket
  // actually speaks (#16804). Both consumers of this `url` open it: the runtime
  // state file is what an external supervisor or health check dials, and the
  // IPC message is what the `os dev` parent learns the server from. Under
  // `--cert`/`--key` a hardcoded `http://` here would hand both of them an
  // address that answers a TLS handshake error — a machine-readable surface
  // saying something untrue about the process that wrote it. ⛔ Unlike the
  // canonical origin, this is NOT overridable by `OS_AUTH_URL`: that variable
  // names where a deployment is REACHED, and this line names what was BOUND.
  const url = `${boundProtocol}://localhost:${boundPort}`;
  // 1 ─ THE FILE FIRST. Both announcements below send a consumer to it.
  channels.writeRuntimeState({ port: boundPort, url });
  // 2 ─ The banner: a human, or a supervisor tailing stdout, reads the same
  //     address — and by now the state file it names is on disk.
  channels.printBanner();
  // 3 ─ IPC LAST: the `os dev` parent learns the real port without polling,
  //     and prints its MCP connect block under a banner that has finished (#22410).
  channels.announceListening({ type: 'objectstack:listening', port: boundPort, url });
}

/**
 * The identity a runtime state file is keyed by: the ROOT OF THE PROJECT this
 * process is serving, folded into one filename-safe component.
 *
 * ## The collision this ends, DRIVEN rather than reasoned (#15733)
 *
 * The state file used to be `runtime.<environment>.json`, and both halves of
 * that name are machine-global. {@link resolveObjectStackHome} takes NO
 * arguments — it reads `OS_HOME`, else `~/.objectstack` — and an environment
 * id is not a project identity, so two different projects on one machine, both
 * in the ordinary `local` environment, wrote ONE file. Two real boots, two
 * project roots, one home:
 *
 * ```text
 * project A boots  → runtime.env_local.json = { pid 9301, port 42693 }
 * project B boots  → runtime.env_local.json = { pid 9345, port 46175 }
 * A asks "is my server running, and where?"
 *                  → answered pid 9345 on :46175 — which is B — while A's own
 *                    server is still alive and still listening on 42693.
 * A shuts down     → its exit handler deletes the file that by then described
 *                    B, so B serves on with no supervision record at all.
 * ```
 *
 * Those are one defect seen twice: the NAME carried no answer to *whose*
 * server this is, so every project addressed the same file. Keying it by the
 * served app's root gives each project its own — a reader that finds a file
 * has found its own, and a process cleaning up on exit removes only its own.
 *
 * ⛔ NOT repaired by putting an identity in the PAYLOAD instead. #15374 ruled
 * that one deliberately: the identity of the file a process is serving is a
 * property of THAT PROCESS, and a payload key would turn a best-effort
 * supervision file into an identity contract while STILL leaving two projects
 * overwriting and deleting each other's records. The key is the defect; the
 * payload is unchanged here.
 *
 * ## Why the name carries a readable half as well as a digest
 *
 * The digest is what makes the name unique; the slug is what makes a home
 * directory legible to whoever is standing in front of it. A directory
 * answering `runtime.env_local.<12 hex>.json` twice tells a reader nothing
 * about which one is theirs, and answering that question is this file's whole
 * job. The slug is DERIVED, never trusted: uniqueness rests on the digest
 * alone, so a project root whose basename sanitises away to nothing is still
 * keyed correctly — it just reads as the digest.
 *
 * ⚠️ Boundary, stated rather than fixed: the key is the resolved path, not the
 * realpath, so two symlinked spellings of ONE project key differently (each
 * spelling gets its own file, and each is internally consistent). Two boots of
 * the SAME project also still share a file — that is the same-project case,
 * which is #15374's in-process watch, not this one.
 *
 * ⚠️ Second boundary, and the one an OUT-OF-TREE reader has to replicate to
 * find the record: WHICH root this is handed is {@link servedAppRootOrCwd},
 * which {@link anchorServedApp} sets to the CONFIG'S OWN DIRECTORY only when
 * that config exists and that directory carries a `package.json`, and to
 * `process.cwd()` otherwise. So one app served from two working directories
 * with no manifest beside its config keys TWO files, and a supervisor that
 * reconstructs the name out of tree has to apply that same rule rather than
 * assume the config's directory. That fallback is #11185's and is deliberate:
 * a directory that declares nothing is not anchored at, because anchoring
 * there could only turn a working boot into an `undeclared` refusal.
 */
export function projectStateKey(servedAppRoot: string): string {
  const absolute = path.resolve(servedAppRoot);
  const digest = createHash('sha256').update(absolute).digest('hex').slice(0, 12);
  const slug = path.basename(absolute).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 24);
  return slug.length > 0 ? `${slug}-${digest}` : digest;
}

/**
 * The runtime state file's name: `runtime.<environment>.<project>.json`.
 *
 * Both components are identities the file has to carry, and neither is
 * sufficient alone — the environment id keeps a staging boot from answering
 * for a local one, and {@link projectStateKey} keeps ANOTHER PROJECT's local
 * boot from answering for this one.
 *
 * ⚠️ A reader that hard-codes the old `runtime.<environment>.json` now gets
 * ENOENT rather than a stale or foreign record. That is the intended trade: a
 * missing file is a loud, correct answer to "is my server running", where the
 * name it replaces could only give a confident wrong one.
 */
export function runtimeStateFileName(environmentId: string, servedAppRoot: string): string {
  return `runtime.${environmentId}.${projectStateKey(servedAppRoot)}.json`;
}

/**
 * The real channels: the same three writes this command has always done.
 *
 * Each leg keeps its OWN `try` — a boot must not die because a supervision file
 * could not be written or because an IPC channel had already closed, and one
 * leg failing must not cost the other two. The ORDER changed (commit faff497fd),
 * and a state file that could not be written is now said once on stderr
 * (#24091); a closed IPC channel is still the ordinary `os serve` case, silent.
 */
export function runtimeBoundPortChannels(printBanner: () => void): BoundPortChannels {
  return {
    writeRuntimeState: ({ port, url }) => {
      // Named the moment it is known, so the catch below can say WHICH file
      // was not written (#24091).
      let attemptedFile: string | undefined;
      try {
        const environmentId = process.env.OS_ENVIRONMENT_ID ?? 'env_local';
        // Keyed by the SERVED APP'S ROOT as well as the environment, so two
        // projects on one machine stop addressing one file (#15733). The root
        // is the one this command already anchored for host resolution; a
        // caller reaching these channels outside a boot gets the CWD, which is
        // what every path in that situation already resolves against.
        const runtimeFile = path.join(
          resolveObjectStackHome(),
          runtimeStateFileName(environmentId, servedAppRootOrCwd()),
        );
        attemptedFile = runtimeFile;
        // Bounded (#23858): an `OS_HOME` that can never be made — a name under
        // `/proc` — is refused here at once, and the catch below lets the boot
        // go on without the file, saying so. Node's recursive mkdir looped on
        // it after the bind and before the banner, holding the event loop, so
        // the server never announced itself.
        makeDirectorySync(path.dirname(runtimeFile));
        fs.writeFileSync(runtimeFile, JSON.stringify({
          pid: process.pid,
          port,
          url,
          environmentId,
          startedAt: new Date().toISOString(),
        }, null, 2));
        const cleanupRuntimeFile = () => { try { fs.rmSync(runtimeFile, { force: true }); } catch { /* noop */ } };
        process.on('exit', cleanupRuntimeFile);
      } catch (error) {
        // Best-effort, NOT silent (#24091). The file stays optional — a boot
        // must not die for a supervision file — but both announcements that
        // follow (the banner, the IPC message) send a consumer to it, so a
        // refusal swallowed here told a supervisor "ready" and then answered
        // its read with nothing. One line, naming the file and the operating
        // system's own error, carried verbatim rather than paraphrased.
        //
        // Said ONCE: `run()` publishes the bound port at exactly one site, so
        // this leg runs once per boot. Channel: `console.warn`, i.e. stderr,
        // like every other boot warning in this file — stdout belongs to the
        // stdio MCP transport's JSON-RPC frames (#7915).
        const thrown = error instanceof Error ? error.message : String(error);
        console.warn(chalk.yellow(
          `  ⚠ Runtime state file not written: ${attemptedFile ?? '(its path could not be resolved)'} — ${thrown}. ` +
            'The server runs on without it, so a supervisor that reads it will not find this process there; ' +
            'point OS_HOME at a directory this process can write.',
        ));
      }
    },
    announceListening: (message) => {
      try {
        if (typeof process.send === 'function') process.send(message);
      } catch { /* IPC channel closed — best-effort */ }
    },
    printBanner,
  };
}

/**
 * The real {@link SeedSettlementChannels} for a booted kernel (#17329).
 *
 * Kept OUT of {@link BoundPortChannels} deliberately. Those three are one
 * ordered publication of ONE number and {@link publishBoundPort} exists to drive
 * them in the one safe order; this is a different fact arriving on a different
 * clock, often minutes later. Folding it in would have made the seam either
 * asynchronous or a liar.
 *
 * Best-effort like its sibling: a closed or absent IPC channel is the ordinary
 * `os serve` case, not an error, and a throw here would be a supervision
 * nicety taking a healthy server down.
 */
export function runtimeSeedSettlementChannels(
  kernel: { getService?: (name: string) => unknown } | undefined,
): SeedSettlementChannels {
  return {
    readSettlement: () => readSeedSettlement(kernel),
    readSummary: () => {
      try {
        const s: unknown = kernel?.getService?.('seed-summary');
        return Array.isArray(s) && s.length > 0 ? (s as SeedSourceSummary[]) : undefined;
      } catch {
        return undefined;
      }
    },
    announceSettled: (message) => {
      try {
        if (typeof process.send === 'function') process.send(message);
      } catch { /* IPC channel closed — best-effort */ }
    },
  };
}

/**
 * Tell the `os dev` parent that the boot was refused for the v17
 * organization-ownership shape, and wait until the message is handed to the
 * channel — the child exits right after, and a message still queued would be
 * lost. Answers whether it was sent; a closed channel is the ordinary
 * `os serve` case.
 */
async function announceOrganizationOwnershipRequired(tables: string[]): Promise<boolean> {
  const { ORGANIZATION_OWNERSHIP_REQUIRED_MESSAGE } = await import('../utils/dev-organization-ownership-upgrade.js');
  return new Promise((resolve) => {
    try {
      process.send!({ type: ORGANIZATION_OWNERSHIP_REQUIRED_MESSAGE, tables }, undefined, {}, (error) => resolve(!error));
    } catch {
      resolve(false);
    }
  });
}

const hostImporters = new Map<string, HostImporter>();

/**
 * The root of the app this process is serving — resolved once by
 * {@link anchorServedApp}, and the default resolution base for every
 * host-anchored load in this file.
 *
 * `undefined` until `run()` has resolved the config path, and for any caller
 * that reaches {@link importFromHost} / {@link Serve.importConfigPlugin}
 * outside a boot (a unit test, an out-of-tree embedder). Both fall back to
 * `process.cwd()` through {@link servedAppRootOrCwd}, which is the base this
 * file used unconditionally before — so a load that somehow runs before the
 * anchor is set behaves exactly as it did, never worse.
 */
let servedAppRoot: string | undefined;

/**
 * The served app's root, or the CWD when no boot has anchored one.
 *
 * Read as a FUNCTION at each use, never captured into a module-scope `const`:
 * the value is not knowable at module-evaluation time (it comes from the
 * command's own argument), and a captured copy would silently freeze the
 * pre-boot answer into every load site.
 */
function servedAppRootOrCwd(): string {
  return servedAppRoot ?? process.cwd();
}

/**
 * Resolve the served app's config path **and anchor host resolution at it**.
 *
 * ── Why the app root is the CONFIG's directory, not the CWD (#11185) ────────
 *
 * `serve` takes the config as an ARGUMENT, so `objectstack serve
 * /srv/app/objectstack.config.ts` is a supported invocation and the app being
 * served need not be the directory the operator happened to stand in. Every
 * host-anchored load resolved from `process.cwd()` regardless, so with that
 * invocation the CLI read the WRONG `package.json`: an app-declared optional
 * service — `@objectstack/service-cluster` and its driver, the enterprise
 * organizations runtime, anything a customer installs — was classified
 * `undeclared`, fell through to the framework-side fallback, and boot died with
 *
 *     Cannot find package '@objectstack/service-cluster': the host app does not
 *     declare it.
 *       host app: <the cwd, which is not the app at all>
 *
 * while the app's own `node_modules` carried the package the whole time. That
 * is #10645's outage with the base wrong for a different reason: #10645 fixed
 * the IMPORTER (bare `import()` → {@link importFromHost}), this fixes the BASE
 * that importer is handed.
 *
 * This function is also the only place `run()` computes the config path, on
 * purpose. The anchor cannot be "forgotten" or written too late by a future
 * author, because the value every later line needs — the absolute config path —
 * is produced by the same call that sets it.
 *
 * ── Why the fallback is conditional, and the one row that MOVES ───────────
 *
 * A resolution base is only useful if a `package.json` is there to be read
 * (`readHostDeclaration` reads a MANIFEST — reachability is deliberately not
 * the contract, #4719). So the config's directory is adopted only when it
 * actually holds one, and otherwise the CWD is kept:
 *
 *   • config beside the app's manifest, CWD = that app  → unchanged (same dir)
 *   • config beside the app's manifest, CWD = elsewhere → FIXED: the app wins
 *   • config in a manifest-less subdirectory of the app → unchanged (CWD)
 *   • no config at all (artifact boot, `<cwd>/dist/…`)  → unchanged (CWD)
 *
 * Those four rows are unchanged. A FIFTH one is NOT, and this comment will not
 * claim otherwise — an absolute here ("no layout that resolves today resolves
 * differently") reads to the next author as a licence to skip the check:
 *
 *   • config beside the app's manifest, CWD = elsewhere, the CWD's manifest
 *     DECLARES the package and the served app's does NOT → the load moves off
 *     the declared leg onto the fallback leg: it still succeeds wherever that
 *     fallback can reach the package, and refuses where it cannot.
 *
 * MEASURED. Before: hostRoot was the CWD, so `declared` was true and
 * `hostRequire.resolve` found the package under the CWD's `node_modules`.
 * After: hostRoot is the served app, `declared` is false, and the load goes to
 * `createHostImporter`'s fallback — which is a bare `import()` written in THIS
 * file, because `importFromHost` now hands the helper its own resolution base
 * (`fallbackImport`, commit a4cb7817f; it used to resolve from `@objectstack/types`
 * instead). Node ESM walks `node_modules` UPWARD from there, so the common
 * shape survives: in a hoisted monorepo whose ROOT
 * manifest declares the package while the served `apps/foo/package.json` does
 * not, that walk reaches the same hoisted store and boot is what it always
 * was — only the leg changed. It genuinely refuses only where the walk cannot
 * reach the package: a global / `npx` CLI serving an app elsewhere, with the
 * optional service installed only beside the operator. Remedy for anyone who
 * lands there — declare the package in the SERVED app's own `package.json`,
 * which is what #4719 asks for regardless.
 *
 * So this narrows one row toward the declaration #4719 already requires; it
 * widens nothing. The app root is the directory that DECLARES — a directory
 * with no manifest declares nothing, which is why anchoring at one is not
 * attempted: it could only turn a working boot into an `undeclared` refusal.
 */
function anchorServedApp(configArg: string): { configPath: string; configExists: boolean } {
  const configPath = path.resolve(process.cwd(), configArg);
  const configExists = fs.existsSync(configPath);
  const configDir = path.dirname(configPath);
  servedAppRoot =
    configExists && fs.existsSync(path.join(configDir, 'package.json'))
      ? configDir
      : process.cwd();
  return { configPath, configExists };
}

/**
 * Host-anchored dynamic import: load a package **as the app being served
 * declares it**, falling back to the CLI's own resolution when the app does not
 * declare it (`createHostImporter`, `@objectstack/types/node`).
 *
 * Node ESM resolves a bare `import(pkg)` against the IMPORTER's own realpath.
 * The CLI is reached through a workspace/`link:` dependency, so that realpath is
 * inside the FRAMEWORK workspace: a bare import can only see what the framework
 * itself installed. A package supplied by the app being served — an app-declared
 * one such as `@objectstack/organizations` (open core since ADR-0132; a
 * commercial deployment resolves that same name to its own private build), a
 * distribution one such as `@objectstack/service-cluster`, or anything a customer
 * installs into their own project — is invisible to it no matter what the host
 * app declares.
 *
 * #4719: "resolve from the host root" means "resolve what the host root
 * DECLARES". The host lookup was a CJS require, CJS honours NODE_PATH, and the
 * pnpm bin shim exports NODE_PATH pointing at the hoisted workspace store — so
 * anything transitively reachable from anywhere in the workspace resolved as if
 * the app had declared it, and whether the ADR-0093 D5 wall fired came down to
 * how the process was launched. The declaration is the contract; reachability is
 * not. This helper only moves where a module resolves FROM; it does not widen
 * what `serve` will accept.
 *
 * ── Why this is a MODULE-SCOPE FUNCTION DECLARATION, not a `const` ───────────
 *
 * It used to be `const importFromHost = createHostImporter(hostRoot)` bound
 * partway down the boot method, so it existed only BELOW its own binding — and a
 * load written above that line was NOT a compile error. The author simply wrote
 * a bare `import()`, which resolves from the CLI and works fine in a dev checkout
 * where everything is hoisted into one `node_modules`. It breaks only in a real
 * distribution layout, at boot, in production. That shipped TWICE:
 *
 *   • cloud#1013 — the binding sat below the AUTH block, so the enterprise
 *     organizations load resolved in the framework workspace, never found the
 *     then-cloud-private package, and every walled-posture deployment hit the
 *     ADR-0093 D5 fail-fast and exited 1.
 *   • #10645 — the binding sat below the CLUSTER block, so `serve` could not load
 *     an app-declared `@objectstack/service-cluster*` at all: on the published EE
 *     image `OS_CLUSTER_DRIVER=redis` died at boot with `Cannot find package
 *     '@objectstack/service-cluster'`, and compose's
 *     `service_completed_successfully` took the whole stack down with it.
 *
 * Hoisting the binding fixed each instance and left the CLASS open: the next load
 * added above the new line reproduces it exactly, and no author has any reason to
 * know where that line is. A function declaration at module scope is hoisted over
 * the ENTIRE module, so "above the definition" is no longer a state this file can
 * be in — every line of `serve.ts`, in any order, reaches the same host-anchored
 * importer (commit 3d7deb700).
 *
 * `serve-cluster-host-resolution.test.ts` is the detection backstop: it scans
 * this file for every app-declarable optional load and fails on a bare one.
 *
 * ── What the UNDECLARED leg resolves from, and why it is stated here (commit a4cb7817f) ─
 *
 * `createHostImporter` has two legs. The DECLARED one resolves out of the served
 * app's own `node_modules`, anchored by `hostRoot`. The UNDECLARED one falls back
 * to "the importing package's own resolution" — and which package that IS depends
 * entirely on where the `import()` is physically WRITTEN, because Node ESM
 * resolves a bare specifier against the module containing the call.
 *
 * Omit `fallbackImport` and that call is the default one inside
 * `@objectstack/types`, so the fallback sees only what THAT package declares.
 * MEASURED in this checkout, `import.meta.resolve` from each base:
 *
 *     specifier                    from packages/cli   from packages/types
 *     @objectstack/plugin-auth     OK                  MISS
 *     @objectstack/plugin-audit    OK                  MISS
 *     chalk                        OK                  MISS
 *     @objectstack/spec            OK                  OK    ← types' one dep
 *
 * Commit 46d34ab7c made the base an explicit parameter for exactly that reason, and its
 * other two callers (`@objectstack/verify`'s `bootStack`, the `packages/qa/
 * dogfood` enterprise probe) pass theirs. This file was the one that did not, so
 * its undeclared leg resolved from a package it has nothing to do with. That was
 * harmless only by accident — every specifier reaching it today is app-supplied
 * and resolves from NEITHER base — and the next CLI-declared package loaded here
 * would have silently missed the CLI's own dependencies. Passing the base widens
 * the undeclared leg's reach to exactly what `packages/cli` itself declares, and
 * to nothing else: the #4719 declaration gate on the DECLARED leg is untouched,
 * so no app gains a way to load something it has not declared.
 *
 * The base is a FUNCTION and not a `parentURL` string because both string
 * spellings were measured wrong — `import.meta.resolve`'s parent argument is
 * silently ignored without a flag, and `createRequire().resolve` re-opens the
 * `NODE_PATH` hole #4719 closed. `@objectstack/types/node` carries both
 * measurements; do not re-derive them here.
 *
 * @param hostRoot Directory holding the served app's `package.json`. Defaults to
 * {@link servedAppRootOrCwd} — the directory `serve` read the app's
 * `objectstack.config.ts` from, which is the app's own root and NOT necessarily
 * the process CWD (#11185). The default is what makes this helper correct from
 * every line of the file without an author having to know a root exists: the
 * same reason commit 3d7deb700 made it a hoisted declaration rather than a binding.
 */
function importFromHost(specifier: string, hostRoot: string = servedAppRootOrCwd()): Promise<any> {
  // Memoised per root so one boot shares a single host `require`, exactly as the
  // one mid-function `const` did before it was hoisted out here.
  let importer = hostImporters.get(hostRoot);
  if (!importer) {
    importer = createHostImporter(hostRoot, {
      // THIS module's own resolver, written HERE (commits 46d34ab7c and a4cb7817f) — see the
      // "what the undeclared leg resolves from" note above for why it has to be
      // a function in the calling module and not a URL string.
      fallbackImport: (fallbackSpecifier) => import(/* webpackIgnore: true */ fallbackSpecifier),
    });
    hostImporters.set(hostRoot, importer);
  }
  return importer(specifier);
}

export default class Serve extends Command {
  static override description = 'Start ObjectStack server. Reads `objectstack.config.ts` if present; otherwise falls back to `dist/objectstack.json` (or OS_ARTIFACT_PATH, including http(s):// URLs) as a portable artifact.';

  static override args = {
    // [#24191] `ignoreStdin`: oclif otherwise fills an omitted positional from
    // a line already waiting on stdin (`tryStdin`), and with the stdio MCP
    // transport that line is the client's `initialize`, written at spawn. It
    // became the config path, the boot fell back to the artifact without the
    // config, and the request was never answered. Stdin belongs to the
    // transport; the config path comes from argv or the default.
    config: Args.string({ description: 'Configuration file path', required: false, default: 'objectstack.config.ts', ignoreStdin: true }),
  };

  static override flags = {
    port: Flags.string({ char: 'p', description: 'Server port', default: readEnvWithDeprecation('OS_PORT', 'PORT', { silent: true }) ?? '3000' }),
    dev: Flags.boolean({ description: 'Run in development mode (load devPlugins)' }),
    ui: Flags.boolean({ description: 'Enable the bundled Console portal at /_console/, served from @objectstack/console (default: true)', default: true, allowNo: true }),
    console: Flags.boolean({
      description: 'Mount the Console UI at /_console/ when the package is installed (default: true).',
      default: true,
      allowNo: true,
    }),
    server: Flags.boolean({ description: 'Start HTTP server plugin', default: true, allowNo: true }),
    prebuilt: Flags.boolean({ description: 'Skip esbuild/bundle-require — load config as native ESM (production mode)', default: false }),
    preset: Flags.string({
      description: 'Plugin tier preset: minimal | default | full (overridden by config.tiers if set)',
      // [#22371] The keys of the table `resolveStackTiers` reads — the same
      // options `os migrate security-catalog-overlays --preset` offers.
      options: Object.keys(STACK_TIER_PRESETS),
    }),
    'log-level': Flags.string({
      description: 'Kernel logger level. Defaults to $OS_LOG_LEVEL / $LOG_LEVEL, else `warn` so flow/hook execution failures surface (ADR-0032). Boot-phase warnings are replayed under the startup banner; `debug`/`info` stream the whole boot live instead. Use `silent` to fully quiet the runtime.',
      options: [...LOG_LEVELS],
    }),
    verbose: Flags.boolean({ char: 'v', description: 'Verbose output — shortcut for --log-level debug.' }),
    // #16804 — developer-supplied TLS, declared through the shared contract so
    // `dev` (which spawns this command) and `serve` cannot drift on the flag
    // names, the prose, or what half a pair means.
    cert: devTlsCertFlag(),
    key: devTlsKeyFlag(),
  };

  /**
   * Capabilities auto-added to every app's `requires` for every preset
   * EXCEPT `minimal`. These form the foundation that every server-side
   * runtime expects to exist (background work, settings persistence,
   * transactional mail, file uploads, notifications). Apps may still list
   * these in `requires:` explicitly — duplicates are de-duped.
   *
   * `messaging` is foundational because, post-ADR-0030, notifications flow
   * through a single ingress (`NotificationService.emit`): collaboration
   * `@mention` / assignment (plugin-audit) and the `notify` flow node deliver
   * via the messaging pipeline, and the Console bell reads its materialization
   * (`sys_inbox_message`). Without it those notifications silently no-op.
   *
   * Opt out: `objectstack serve --preset minimal`.
   *
   * DERIVED from `@objectstack/spec`'s `PLATFORM_ALWAYS_ON_CAPABILITIES`, where
   * the slate and its per-entry rationale now live. This used to BE the
   * declaration, under a comment noting that cloud / multi-environment hosts
   * "mirror this list on their per-project kernels" — with nothing making that
   * true. They had diverged: the hosted slate was missing `sms`, `messaging` and
   * `analytics`, so an app that worked under `objectstack serve` silently lost
   * dataset previews and `notify` deliveries once hosted (cloud#925, #3786).
   *
   * Kept as a re-export rather than deleted so `Serve.ALWAYS_ON_CAPABILITIES`
   * stays a stable handle for existing callers and tests — one declaration, two
   * readers.
   */
  static readonly ALWAYS_ON_CAPABILITIES: readonly string[] = PLATFORM_ALWAYS_ON_CAPABILITIES;

  /**
   * The `plugins[]`-wired multi-org runtime this command loads when the
   * resolved tenancy posture is walled (ADR-0105 D12) — declared ONCE, here.
   *
   * `serve` is the only runtime that prints this package name AT OPERATORS (the
   * install remedy, the fatal refusal, the degraded-boot warning), and the
   * spec-owned provenance roster `PLATFORM_PLUGIN_WIRED_RUNTIMES` is what makes
   * the name answerable as real rather than fabricated — #10921 is the case
   * where a fabricated `@objectstack/framework` sat next to the real
   * `@objectstack/organizations` in published docs for months, indistinguishable.
   * Spelled inline at the resolution site, the name was a second copy under no
   * check at all: the roster's own header calls that "a second description
   * nobody checks", and a roster cannot pin a spelling it cannot see. Read from
   * here, it is one declaration with a drift pin over it —
   * `serve-capability-vocabulary.test.ts` asserts this value is a roster KEY
   * (#11614), so a rename on either side fails a test instead of silently
   * pointing operators at a package that does not exist.
   *
   * Exposed as a static for the same reason ALWAYS_ON_CAPABILITIES above is:
   * one declaration, two readers — the boot path and the pin.
   *
   * ── The ⛔ that stood here, and how it ended ──────────────────────────────
   *
   * ⚠️ Until #12579 this read: MUST stay a string LITERAL in this file, because
   * `serve-cluster-host-resolution.test.ts` sweeps `serve.ts` for every dynamic
   * `import()`, resolves the organizations load — spelled
   * `const organizationsPkg = Serve.ORGANIZATIONS_RUNTIME_PKG;` — one hop to
   * this static and then reads the literal. Written as `= SOME_IMPORTED_CONST`
   * the specifier stopped resolving and that load dropped OUT of the swept
   * population rather than failing inside it: the silent-vacuity failure #11614
   * paid for once. That was not reasoned, it was MEASURED — #12492 tried exactly
   * that rewrite and the named half of the sweep's vacuity guard refused it, by
   * name.
   *
   * ⭐ It stopped being true at `1ca763b60` (#12533, PR #12582), which taught
   * `resolveIdentifier()` a third hop: an import alias to a literal in a sibling
   * module of the SAME package. `= SOME_IMPORTED_CONST` is now a shape it
   * resolves, and that is pinned rather than inferred — against the REAL
   * `../utils/tenancy-posture-hints.ts` read through this file's own scan
   * context, in the case named "resolves an alias to a literal in a REAL sibling
   * module of packages/cli", and again in "resolves `static readonly MEMBER =
   * <alias>` — the shape the refactor writes", which is the shape this
   * declaration now carries.
   *
   * ⛔ Both halves stay recorded rather than the note deleted, because a reader
   * who meets neither re-derives the dead constraint from the shape and puts the
   * ⛔ back.
   *
   * ── What this declaration is now ─────────────────────────────────────────
   *
   * ⭐ The spelling is declared ONCE, in `../utils/tenancy-posture-hints.ts` —
   * the neutral module `os doctor` reads too — and this static is assigned from
   * it (#12579, maintainer ruling 2026-08-27, Option A). It is the same shape
   * `ALWAYS_ON_CAPABILITIES` above already carries: a stable handle over a
   * declaration that lives elsewhere. Until that ruling this was a second
   * LITERAL held EQUAL by an assertion — site 8 of
   * `serve-organizations-message-spelling.test.ts`, retired in the same diff,
   * because with one declaration an equality pin has no subject.
   *
   * Two things outlive that decision, and neither moved:
   *
   *   · This static keeps its NAME. `test/serve-capability-vocabulary.test.ts`
   *     pins it as a roster KEY and the sweep resolves the load THROUGH it, both
   *     addressing `Serve.ORGANIZATIONS_RUNTIME_PKG`; only the spelling moved
   *     out. ⛔ Rename the member and those read something that is not there.
   *   · ⛔ The gap is NEVER closed in the other direction — see the ⛔ on
   *     `ORGANIZATIONS_RUNTIME_PKG` in `../utils/tenancy-posture-hints.ts`.
   *     `os doctor` must not depend on a `serve` command's export in order to
   *     spell a package name (#12464's coupling ruling, which none of this
   *     touches).
   *
   * ⚠️ This assignment is the alias hop's FIRST LIVE CONSUMER, which is a cost
   * as well as the point: narrowing that hop is now a LIVE regression rather
   * than a synthetic one. It is written down once, where whoever narrows it will
   * be standing — the suite docblock over the hop's own cases in
   * `serve-cluster-host-resolution.test.ts`.
   *
   * This single-sources the SPELLING and nothing else. Which postures load the
   * runtime, and what each of the two failure stages means, stay exactly where
   * they are; the roster is deliberately not a resolution registry.
   */
  static readonly ORGANIZATIONS_RUNTIME_PKG = SHARED_ORGANIZATIONS_RUNTIME_PKG;

  /**
   * Auto-registered plugin tiers. Plugins explicitly listed in
   * `config.plugins` are always loaded — tiers only gate the optional
   * auto-registration blocks below (AIService, I18n, UI portals, etc.).
   *
   * [#22371] A handle over `STACK_TIER_PRESETS` (`@objectstack/core`), where the
   * tier rule now lives beside the auth gate it feeds: `os migrate
   * security-catalog-overlays` answers that gate as this command does. One
   * declaration, several readers — ⛔ never a second copy here.
   */
  static readonly TIER_PRESETS: Readonly<Record<string, readonly string[]>> = STACK_TIER_PRESETS;

  /**
   * True when a dynamic `import()` / `require.resolve()` failed because the
   * module is simply NOT INSTALLED — as opposed to the module being present but
   * throwing while it loads (a real crash). Checking `err.code` FIRST is the
   * #1595 fix: ESM reports a missing package as `err.code ===
   * 'ERR_MODULE_NOT_FOUND'` with the human message `Cannot find package '...'`.
   *
   * Thin delegate to the shared classifier in `@objectstack/types` — one owner
   * across the CLI's optional-plugin guards, the capability resolver, and
   * (at its next framework pin bump) cloud's objectos-runtime loader, so the
   * parallel loaders can't drift apart and re-introduce that bug (#1597, #3265).
   */
  static isModuleNotFoundError(err: unknown): boolean {
    return isModuleNotFoundError(err);
  }

  /**
   * Resolve HOW an optional, separately-published service plugin (e.g.
   * `@objectstack/service-ai`, `@objectstack/service-ai-studio`) should load,
   * from explicit INTENT rather than mere package presence (#1597).
   *
   * Two orthogonal axes decide the outcome — the app's declared intent and the
   * license TIER (an orthogonal DENY):
   *
   *   tierAllowed=false               → 'off'      never load (CE / `tiers` sans the feature)
   *   required=true  (+ tierAllowed)  → 'required' MUST load; a missing package is fail-fast
   *   declared=true  (+ tierAllowed)  → 'auto'     opt-in convenience; best-effort load
   *   neither declared nor required   → 'off'      skip, with NO speculative import
   *
   * `required` is an explicit capability declaration (`requires: [...]`), NOT
   * "the package happens to be installed". `declared` means the host app listed
   * the package in its OWN package.json — a deliberate authoring act, the opt-in
   * path — resolved WITHOUT importing anything. The caller maps the result:
   * 'required'/'auto' → attempt load (fail-fast only when 'required'); 'off' → skip.
   */
  static resolveOptionalPluginLoad(opts: {
    tierAllowed: boolean;
    required: boolean;
    declared: boolean;
  }): 'required' | 'auto' | 'off' {
    if (!opts.tierAllowed) return 'off';
    if (opts.required) return 'required';
    if (opts.declared) return 'auto';
    return 'off';
  }

  /**
   * Is this `plugins: [...]` entry a RELATIVE module specifier — `./x.js`,
   * `../x.js`, `.`, `..` (and their backslash spellings, which Node's URL
   * resolution normalises to the same thing)?
   *
   * Deliberately NARROWER than `packageNameFromSpecifier(s) === undefined`,
   * which also answers "not a package" for every BASE-INDEPENDENT spelling —
   * an absolute POSIX path, a `file://` URL, a Windows drive path, `node:`,
   * `data:`. Those resolve to the same module no matter who imports them, so
   * they are none of this predicate's business; only a specifier whose meaning
   * depends on WHICH FILE does the importing is.
   *
   * A bare `local-plugin.js` is NOT relative and is not matched: ESM reads it
   * as a package name, and so does this file — it reaches the declaration
   * branches below and gets #4719's "declare it in that app's package.json"
   * answer, which is the correct one for a bare specifier.
   */
  static isRelativePluginSpecifier(pluginSpecifier: string): boolean {
    return /^\.\.?(?:[\\/]|$)/.test(pluginSpecifier);
  }

  /**
   * The refusal text for a relative `plugins: [...]` entry — one owner, so the
   * string a user reads is CHOSEN and pinned rather than assembled at a call
   * site (the same discipline `importConfigPlugin`'s failure wrapper follows).
   *
   * It names both spellings that DO resolve from the served app, because a
   * refusal that only says "no" leaves the author exactly as stuck as the
   * silence it replaced. `new URL(spec, import.meta.url).href` is the second
   * one written the way an author actually wants it: the CONFIG computes the
   * absolute URL from its own location, so a plugin file sitting next to
   * `objectstack.config.ts` loads without publishing it as a package — using
   * only resolution that already works today.
   */
  static relativePluginSpecifierRefusal(pluginSpecifier: string): string {
    // Quoted the way a config author writes it — single quotes unless the
    // specifier itself would break them, in which case JSON's escaping is
    // correct JS too. A backslash spelling (`.\\x.js`) takes that branch, so
    // the suggested line stays copy-pasteable rather than silently dropping
    // the escape.
    const q = /^[^'\\\r\n]*$/.test(pluginSpecifier)
      ? `'${pluginSpecifier}'`
      : JSON.stringify(pluginSpecifier);
    return [
      `Refused the plugin entry ${q} in \`plugins: [...]\`: a RELATIVE path there is`,
      `resolved against the CLI's own installation directory, never against your app — so`,
      `it can never load a file from your project. This spelling has never worked; it used`,
      `to fail with a "Cannot find module" naming a path inside the CLI's install directory.`,
      '',
      'Use one of the two spellings that resolve from your app:',
      '',
      "  1. a package name your app DECLARES in its own package.json:",
      "         plugins: ['@mycompany/crm']        (then: pnpm add @mycompany/crm)",
      '',
      '  2. an absolute path, or a file:// URL the config computes for itself:',
      `         plugins: [new URL(${q}, import.meta.url).href]`,
    ].join('\n');
  }

  /**
   * Load one `plugins: [...]` entry of the served app's own config that is
   * written as a STRING (commit 9cc6777d3).
   *
   * This is the most app-owned specifier in the whole file — it is supplied by
   * the app being served, and `plugins: [...]` is THE documented way to extend a
   * deployment. It used to be loaded with a bare `import()`, which Node ESM
   * resolves against the IMPORTER's realpath: this CLI's. So an app that writes
   * `plugins: ['@acme/my-plugin']` and DECLARES `@acme/my-plugin` in its own
   * package.json could only be served where that package happened to be hoisted
   * somewhere the CLI could see it — true in a dev checkout, false in a real
   * distribution layout. Same mechanism as cloud#1013 and #10645, but on the
   * surface users are explicitly told to use.
   *
   * ── Why this WAS three branches, and why it is now two (commits 9cc6777d3 → a4cb7817f) ─
   *
   * The three-branch shape existed because handing every specifier to
   * `importFromHost` was MEASURED not to be a superset of a bare `import()` —
   * in two ways, both of which would have taken working deployments away:
   *
   *   1. A RELATIVE specifier changes base. `createHostImporter` passes a
   *      non-package specifier through to an `import()` that physically lives in
   *      `@objectstack/types`, and ESM resolves a relative specifier against the
   *      module CONTAINING the call — so `'./local-plugin.js'` would resolve
   *      against `@objectstack/types/dist/` instead of this file's directory.
   *      STILL TRUE, and still why the non-package branch below stays here
   *      rather than being folded into the helper. (Commit e598b1cbc has since landed a RULING on
   *      the relative spelling itself: it is refused above, before any base is
   *      chosen. The remaining non-package spellings — an absolute path, a
   *      `file://` URL, a `node:` builtin — mean the same module from every
   *      base, so keeping them local costs nothing and removes the one way a
   *      future relative spelling this file's refusal does not recognise could
   *      be silently re-based inside `@objectstack/types`.)
   *   2. An UNDECLARED bare name changed base the same way, and that one bit.
   *      `createHostImporter`'s fallback is documented as "the importing
   *      package's own resolution", but the import it fell back to also lived
   *      in `@objectstack/types`, which under a pnpm-isolated layout sees only
   *      `@objectstack/types`'s own dependencies. Measured from an app that
   *      declares nothing: `@objectstack/plugin-auth`, `@objectstack/plugin-
   *      audit` and `chalk` resolve from THIS package and failed through the
   *      host importer. An app that writes `plugins: ['@objectstack/plugin-
   *      auth']` without declaring it — a spelling this repo's own fixtures use
   *      — booted, and would have stopped booting. So this method asked the
   *      declaration itself and kept a local `import()` for the undeclared leg.
   *
   *      ⇒ NO LONGER TRUE. Commit 46d34ab7c made the base a parameter and commit a4cb7817f made
   *      `importFromHost` pass it, so the helper's undeclared leg now runs THIS
   *      file's own `import()` — the identical call this method used to make
   *      inline. The workaround's reason is gone, so the workaround is gone with
   *      it, and the declaration has ONE owner again (`readHostDeclaration`,
   *      inside the helper) instead of being asked here and again there.
   *
   * The collapse was measured case by case before it was written, and every case
   * lands on the same module and the same error as the three-branch shape did:
   *
   *   • app DECLARES it, resolvable there  → the app's copy (unchanged leg).
   *   • app DECLARES it, not installed     → `declared-unresolvable`, the
   *     "repair the INSTALL" remedy — never a fallback (unchanged leg).
   *   • app does NOT declare it, resolvable from this CLI → the CLI's copy, via
   *     `fallbackImport`, which is `import()` written in this module. Byte-for-
   *     byte the resolution the deleted branch performed.
   *   • app does NOT declare it, present but throwing while it evaluates → the
   *     crash propagates untouched. Both the deleted branch and the helper gate
   *     on the SAME predicate (`isModuleNotFoundError`, one owner in
   *     `@objectstack/types`), so "present but broken" is still never
   *     reinterpreted as an absence.
   *   • app does NOT declare it, resolvable nowhere → the #4719 "declare it in
   *     that app's package.json" text. The deleted shape reached that by failing
   *     a local `import()` and then RE-ENTERING the helper purely for the
   *     wording; one call now does both, so the specifier is attempted once
   *     instead of twice.
   *
   * Nothing about WHICH plugins are accepted changes, in either edit: this only
   * moves where one resolves FROM. The #4719 declaration gate is untouched, and
   * no undeclared package gains a way in that it did not already have.
   *
   * ── The relative branch is REFUSED, not resolved (commit e598b1cbc) ────────
   *
   * A relative entry is the one spelling that can never mean what its author
   * meant. It is resolved against THIS file's directory — the installed CLI's
   * `@objectstack/cli/dist/commands/` — so the served app's root never enters
   * the resolution at all. Measured from a fixture app that really does carry
   * `local-plugin.js` next to its config: `'./local-plugin.js'` resolves to
   * `<cli>/src/commands/local-plugin.js` and the app's own file is never seen,
   * while `'..'` LOADS this package's own command barrel. The boot loop then
   * catches the failure, prints one red line naming a path inside the CLI, and
   * serves the app WITHOUT the plugin — so the deployment looks healthy and is
   * quietly missing the extension it declared.
   *
   * Ruled at triage, landed as commit e598b1cbc: refuse it, naming the two spellings that work.
   * That expands no accepted set — the spelling has never loaded an app's file
   * — and turns a diagnostic about the CLI's internals into an answer the
   * author can act on. Resolving relative entries against the SERVED APP's root
   * instead is a capability addition with no measured pull (no doc, example or
   * test in this repo uses the spelling); it stays a decision for a maintainer,
   * and this refusal is where that request would come from.
   *
   * @param pluginSpecifier The string as the app wrote it in `plugins: [...]`.
   * @param hostRoot Root of the served app; defaults to
   * {@link servedAppRootOrCwd}, the same value `serve`'s boot path computes and
   * passes explicitly at its own call site (#11185).
   */
  static async importConfigPlugin(pluginSpecifier: string, hostRoot?: string): Promise<any> {
    const root = hostRoot ?? servedAppRootOrCwd();
    // Refused BEFORE the try, and deliberately not wrapped in the
    // `Failed to import plugin '<spec>': …` text below: nothing was imported,
    // and calling a refusal an import failure sends the author looking for a
    // missing file. The refusal names the specifier itself.
    if (Serve.isRelativePluginSpecifier(pluginSpecifier)) {
      throw new Error(Serve.relativePluginSpecifierRefusal(pluginSpecifier));
    }
    try {
      // `await` inside the `try` rather than a bare `return`: a returned promise
      // would settle OUTSIDE it and skip the diagnostic wrapper below.
      if (packageNameFromSpecifier(pluginSpecifier) === undefined) {
        return await import(/* webpackIgnore: true */ pluginSpecifier);
      }
      return await importFromHost(pluginSpecifier, root);
    } catch (importError: any) {
      // The wrapper lives with the load it describes, so the composed
      // user-facing string is testable rather than assembled at the call site
      // (the triage commit 9cc6777d3 landed requires this text be CHOSEN, not drift).
      throw new Error(`Failed to import plugin '${pluginSpecifier}': ${importError.message}`);
    }
  }

  /**
   * Tier-gated capability tokens → the tier each one opens when listed in
   * `requires`. These have no CAPABILITY_PROVIDERS entry — their loading is
   * resolved by dedicated blocks in run() (`ai`/`ai-studio` by the intent-driven
   * AI block (#1597), `i18n`/`ui`/`auth` by their tier blocks).
   *
   * [#22371] A handle over `CAPABILITY_TO_TIER` (`@objectstack/core`), for the
   * reason `TIER_PRESETS` gives.
   */
  static readonly CAPABILITY_TO_TIER: Readonly<Record<string, string>> = SHARED_CAPABILITY_TO_TIER;

  /**
   * Is one of `identities` ALREADY loaded — i.e. did the app supply this
   * capability's provider itself, so the resolver must not load a second one?
   *
   * A handle over `providesCapability` (`@objectstack/core`), where the rule and
   * its history (#7652: exact identities, never substrings) now live — the
   * verification handle (`@objectstack/verify`) applies the same rule, and it
   * cannot import this package (#22301). Kept as a static so every existing
   * caller and test keeps its spelling: one declaration, several readers.
   */
  static readonly providesCapability: (plugins: readonly unknown[], identities: readonly string[]) => boolean =
    providesCapability;

  /**
   * Identities of the local-install surface (`MarketplaceInstallLocalPlugin`),
   * matched EXACTLY by {@link Serve.providesCapability}.
   *
   * Used by the offline arm of the marketplace wiring (#8343) to leave a host
   * config that already wires its own install-local strictly alone. Declared
   * here rather than inline so the same drift test that pins
   * CAPABILITY_PROVIDERS can pin these against the real plugin.
   */
  static readonly INSTALL_LOCAL_IDENTITIES: readonly string[] = [
    'com.objectstack.runtime.marketplace-install-local',
    'MarketplaceInstallLocalPlugin',
  ];

  /**
   * Identities of the server-pushed runtime-config surface
   * (`RuntimeConfigPlugin`), matched EXACTLY by {@link Serve.providesCapability}.
   *
   * Same job as {@link Serve.INSTALL_LOCAL_IDENTITIES}, one plugin over, and
   * the stakes are higher: `RuntimeConfigPlugin` carries the host's branding
   * (product name, logo, PWA colors) AND the open-core `resolveFeatures` seam.
   * `kernel.use` keys by name (`Kernel.use` -> `this.plugins.set(name, meta)`),
   * so an unguarded mount does not double-mount — it REPLACES, and a host that
   * wired its own would lose its white-label chrome and its distribution's
   * feature policy at once, reporting the framework defaults instead.
   */
  static readonly RUNTIME_CONFIG_IDENTITIES: readonly string[] = [
    'com.objectstack.runtime.runtime-config',
    'RuntimeConfigPlugin',
  ];

  /**
   * Identities of the marketplace BROWSE surface (`MarketplaceProxyPlugin`),
   * matched EXACTLY by {@link Serve.providesCapability}.
   *
   * Cloud-arm counterpart of {@link Serve.INSTALL_LOCAL_IDENTITIES} (#8357).
   * The host's instance carries its own `controlPlaneUrl`, its public-snapshot
   * base URL and its LRU cache tuning — none of which the CLI's auto-wiring
   * can know, because it constructs from `resolveCloudUrl()` alone.
   */
  static readonly MARKETPLACE_PROXY_IDENTITIES: readonly string[] = [
    'com.objectstack.runtime.marketplace-proxy',
    'MarketplaceProxyPlugin',
  ];

  /**
   * Identities of the same-origin cloud-connection surface
   * (`CloudConnectionPlugin`, built by `createCloudConnectionPlugin`), matched
   * EXACTLY by {@link Serve.providesCapability}.
   *
   * Both spellings matter here for a reason the other three do not have: the
   * host reaches this plugin through a FACTORY, so the only class name in
   * play is the one the factory returns. `createCloudConnectionPlugin` is not
   * an identity — a factory function is not what lands in the kernel.
   */
  static readonly CLOUD_CONNECTION_IDENTITIES: readonly string[] = [
    'com.objectstack.cloud.connection',
    'CloudConnectionPlugin',
  ];

  /**
   * Constructor options for the `RuntimeConfigPlugin` the marketplace wiring
   * mounts — ONE object, shared by both arms on purpose (#8389).
   *
   * The offline arm's payload is meant to be the cloud arm's payload minus
   * whatever the runtime genuinely lacks, and `features.marketplace` is now
   * derived per request from the serving app's route table (#8356) rather than
   * declared here. So the difference between the two arms must come from what
   * is MOUNTED, never from a second copy of these options drifting away from
   * the first. Two literals would let exactly that happen silently.
   *
   * `controlPlaneUrl: ''` is deliberate and is NOT the trap
   * {@link Serve.OFFLINE_CONTROL_PLANE} exists for: `RuntimeConfigPlugin`'s
   * constructor special-cases the empty string as "stay on this origin" and
   * bypasses `resolveCloudUrl()` entirely, while `MarketplaceInstallLocalPlugin`
   * re-resolves what it is handed and would substitute the PUBLIC default
   * cloud. The two neighbouring mounts therefore need DIFFERENT spellings of
   * "no cloud"; harmonising them in either direction breaks one of them.
   */
  static readonly RUNTIME_CONFIG_OPTIONS: Readonly<{
    controlPlaneUrl: string;
    singleEnvironment: boolean;
    installLocal: boolean;
  }> = Object.freeze({
    controlPlaneUrl: '',
    singleEnvironment: true,
    installLocal: true,
  });

  /**
   * The `controlPlaneUrl` the offline install-local mount is constructed with.
   *
   * A named constant rather than an inline `'off'` so a test can assert the
   * property the call site depends on — `resolveCloudUrl(this) === ''`. The
   * tempting value is the empty `marketplaceUrl` the wiring block already
   * holds, and it is wrong in a way no local reading reveals: `resolveCloudUrl`
   * treats `''` as "unset" and substitutes the PUBLIC default cloud, so an
   * air-gapped runtime's catalog branch would dial out instead of answering
   * 503. Spelled as one of the documented disable sentinels, it resolves to
   * no cloud at all.
   */
  static readonly OFFLINE_CONTROL_PLANE = 'off';

  /**
   * Which half of the marketplace wiring this boot should mount (#8343).
   *
   * Pure + static so the decision is readable and testable on its own, the
   * same reason {@link Serve.providesCapability} is: the call site sits deep
   * inside `run()` behind a dynamic import, where the only way to observe a
   * mounting rule is to boot a kernel.
   *
   * The two arms are deliberately asymmetric, because the two surfaces need
   * different things:
   *
   *  - `cloudSurfaces` — the ARM SELECTOR, not a mount decision: true when this
   *    boot takes the cloud-connected arm at all (proxy + install-local +
   *    cloud-connection + runtime-config). Those surfaces *are* the control
   *    plane's client, so a resolved URL is their precondition. WHICH of them
   *    the CLI actually mounts is carried by the four `cloud*` flags below.
   *  - `offlineInstallLocal` — the air-gapped install surface. Its inline
   *    branch reads no URL at all, so a control plane is precisely what it
   *    does NOT need; gating it on one is what left a self-hosted EE box with
   *    no install route at all.
   *  - `offlineRuntimeConfig` — the server-pushed runtime config that lets the
   *    Console DISCOVER the above (#8389). Also reads no control plane: it
   *    reports this origin (`controlPlaneUrl: ''`), and since #8356
   *    `features.marketplace` is derived from the serving app's route table,
   *    so on a runtime with no proxy it reports `false` by observation. That
   *    derivation is what unblocked this mount: before it, reporting
   *    install-local truthfully would have cost a false browse claim, which is
   *    why #8343 shipped the offline arm with install-local ALONE and left the
   *    working route undiscoverable.
   *
   * The two offline flags are computed INDEPENDENTLY rather than sharing one
   * gate, because each guards a different host-owned plugin and the two
   * host configurations are not the same configuration. A host that wires its
   * own install-local (so this rule leaves it alone) may still have no
   * runtime-config at all — that box has the #8389 defect just as much as an
   * unconfigured one, and one shared gate would silently exclude it.
   *
   * `isRuntimeHostKernel` is restated here (the call site checks it too, to
   * skip the dynamic import) so this function is the whole rule in one place:
   * the cloud distribution wires its own marketplace on the host kernel, so
   * NO arm mounts there.
   *
   * ## The cloud arm honours the host too (#8357)
   *
   * Every mount on BOTH arms is now per-surface, under the same
   * `providesCapability` rule: the CLI's auto-wiring is a FALLBACK for hosts
   * that wire nothing, never a second opinion about a surface the host already
   * composed. `objectos-ee`'s single-environment config is exactly such a host
   * — it wires proxy, install-local, cloud-connection and runtime-config
   * itself — and it is NOT covered by the `isRuntimeHostKernel` guard above,
   * which detects `ObjectOSEnvironmentPlugin`: only the `OS_MULTI_TENANT`
   * branch constructs one, via `createObjectOSStack`. Hanging this rule off
   * that sentinel would leave the shipped single-environment shape unguarded.
   *
   * What this fixes is PRECEDENCE, not a live downgrade — say it plainly,
   * because the two read alike and only one is true. Measured on this tree:
   * the CLI's wiring block runs several hundred lines BEFORE `config.plugins`
   * are registered, and `Kernel.use` -> `this.plugins.set(name, meta)`
   * overwrites by name, so today the host's instance is the one that survives
   * — the CLI's is constructed, registered and then dropped. The host winning
   * is therefore an ACCIDENT OF ORDERING between two blocks that never mention
   * each other, not a rule anything states or pins; it inverts silently if
   * either block moves, and on a kernel whose `use` rejects duplicates
   * (`LiteKernel` throws) it is the HOST's registration that fails instead.
   * Checking presence makes the outcome independent of all of that, and stops
   * the CLI constructing four plugins it is about to discard.
   */
  static planMarketplaceWiring(input: {
    isRuntimeHostKernel: boolean;
    marketplaceUrl: string;
    plugins: readonly unknown[];
  }): {
    cloudSurfaces: boolean;
    cloudProxy: boolean;
    cloudInstallLocal: boolean;
    cloudConnection: boolean;
    cloudRuntimeConfig: boolean;
    offlineInstallLocal: boolean;
    offlineRuntimeConfig: boolean;
  } {
    const NO_CLOUD_ARM = {
      cloudSurfaces: false,
      cloudProxy: false,
      cloudInstallLocal: false,
      cloudConnection: false,
      cloudRuntimeConfig: false,
    } as const;

    if (input.isRuntimeHostKernel) {
      return { ...NO_CLOUD_ARM, offlineInstallLocal: false, offlineRuntimeConfig: false };
    }
    if (input.marketplaceUrl) {
      return {
        cloudSurfaces: true,
        // Each surface is guarded on its OWN presence, never on a shared gate:
        // a host may compose any subset of the four (objectos-ee wires
        // runtime-config unconditionally but the other three only when it has
        // a resolved cloud URL), and one gate would either overwrite what the
        // host did wire or withhold what it did not.
        cloudProxy: !Serve.providesCapability(input.plugins, Serve.MARKETPLACE_PROXY_IDENTITIES),
        cloudInstallLocal: !Serve.providesCapability(input.plugins, Serve.INSTALL_LOCAL_IDENTITIES),
        cloudConnection: !Serve.providesCapability(input.plugins, Serve.CLOUD_CONNECTION_IDENTITIES),
        cloudRuntimeConfig: !Serve.providesCapability(input.plugins, Serve.RUNTIME_CONFIG_IDENTITIES),
        offlineInstallLocal: false,
        offlineRuntimeConfig: false,
      };
    }
    return {
      ...NO_CLOUD_ARM,
      // A host config that wires its own install-local keeps it — see the
      // call site for why replacing it would be a silent downgrade.
      offlineInstallLocal: !Serve.providesCapability(input.plugins, Serve.INSTALL_LOCAL_IDENTITIES),
      // Same rule, same reason, for the runtime-config surface — replacing a
      // host's own would drop its branding and its resolveFeatures policy.
      offlineRuntimeConfig: !Serve.providesCapability(input.plugins, Serve.RUNTIME_CONFIG_IDENTITIES),
    };
  }

  /**
   * Registry of `requires` token → built-in service-plugin provider for the
   * standalone serve path — a handle over `CAPABILITY_PROVIDERS`
   * (`@objectstack/core`), where the table, its per-row notes and its drift
   * pins' subject now live (#22301): `@objectstack/verify`'s `bootStack` mounts
   * the providers an app's `requires` names through the same table, and it
   * cannot import this package. Adding a built-in capability is an edit THERE.
   *
   * Kept as a static for the reason `ALWAYS_ON_CAPABILITIES` above is: a stable
   * handle for existing callers and tests — one declaration, several readers,
   * ⛔ never a second copy.
   */
  static readonly CAPABILITY_PROVIDERS: Record<string, CapabilitySpec> = CAPABILITY_PROVIDERS;

  async run(): Promise<void> {
    // `metadata` is oclif's record of WHERE each flag's value came from.
    // `metadata.flags.port.setFromDefault` is the only signal that separates a
    // `--port` the operator typed from a value the flag's `default` read out of
    // `OS_PORT`/`PORT`, and the port refusal below has to name which (#12662).
    const { args, flags, metadata } = await this.parse(Serve);

    // ── stdout belongs to the protocol, never to diagnostics (#7915) ──
    // Everything `serve` and the kernel it boots would write to stdout is
    // forwarded to stderr, for the whole life of the process. Held, never
    // released: this is not a window, it is the process's output policy.
    //
    // WHY, and why UNCONDITIONALLY. With `OS_MCP_STDIO_ENABLED=true` the MCP
    // stdio transport owns stdout, and that protocol is newline-delimited JSON:
    // a conforming client `JSON.parse`s every line it reads, so each banner or
    // log line reaches it as a transport error. Measured on the #7915 repro
    // (#7645 had to be fixed first for the channel to carry anything at all):
    // the `initialize` result arrived on line 517, behind 516 lines of banner
    // and kernel log — which reads as "the transport is broken".
    //
    // The tempting fix is "redirect when the stdio transport is active". It is
    // the wrong one: a conditional needs a reliable signal at the moment each
    // line prints — before the config is read, before the plugin is loaded —
    // and it fails SILENTLY and in the worse direction when that signal is
    // wrong or late. A frame-corrupting line that appears only in some boots is
    // far harder to find than one that always does. Banners, boot progress and
    // kernel logs are diagnostics, not program output; stderr is where a CLI
    // puts diagnostics, mounted transport or not, and in a terminal it costs
    // nothing because both streams render.
    //
    // Covers writers this file does not own — `ObjectLogger` routes
    // debug/info/warn to `process.stdout` directly (packages/core), and stray
    // `console.log`s live in several packages the boot touches (the
    // `[StandaloneStack] no compiled artifact …` line is one). That is why the
    // redirection is on the STREAM: `LoggerConfig` has a level but no
    // destination knob, so there is nothing else to point at stderr. Same route
    // `--json` takes for the same reason (commit 2b641ddd4, `utils/json-stdout.ts`).
    //
    // The MCP transport is the one writer that must still reach the real
    // stdout, and it holds its own channel to it (`packages/mcp`,
    // protocol-stdout.ts) rather than depending on who booted it.
    redirectStdoutToStderr();

    // Colour follows the stream the text actually lands on. `chalk`'s default
    // level is decided from stdout, so with the lines above moved to stderr a
    // `serve > log` in a terminal would print an uncoloured banner to a TTY,
    // and a `serve 2> log` would write ANSI escapes into the file. Both are
    // cosmetic, both are wrong, and one assignment fixes them: every writer in
    // this process shares the same chalk instance.
    chalk.level = chalkStderr.level;

    /**
     * Whether the boot-quiet window (further down) is currently open.
     *
     * Declared here rather than beside the window because {@link printDiagnostic}
     * reads it, and this command's first human line prints long before the
     * window opens.
     */
    let bootQuiet = false;

    /**
     * One human line from `serve`, written straight to **stderr** (#7915).
     *
     * Every `console.log` in this command was one of these: a banner line, a
     * boot-progress note, an error explanation — diagnostics, all of them. They
     * are written explicitly rather than left to the redirect above so the
     * stream choice is visible at the call site; the redirect stays because it
     * also covers the writers this file does not own.
     *
     * Suppressed while the boot-quiet window is open, exactly as `console.log`
     * was: that window exists to keep the banner readable, and moving the
     * stream must not turn a quiet boot into a noisy one.
     */
    const printDiagnostic = (text = '') => {
      if (!bootQuiet) process.stderr.write(text + '\n');
    };

    // When --dev is passed, set NODE_ENV early so any runtime modules
    // imported below (and any deps that branch on NODE_ENV at import
    // time) see development mode. We deliberately do NOT inherit
    // NODE_ENV from the parent `os dev` spawn — see the note in
    // commands/dev.ts for why.
    //
    // The `else` branch is `os serve`'s side of #11113. `os start` already
    // defaults NODE_ENV to 'production' on the unset case, but it does so on
    // `localEnv` — a child environment assembled for a SPAWN (start.ts:347).
    // `serve` runs in-process, so there is no child env to default; the
    // equivalent has to mutate `process.env.NODE_ENV` itself. It has to
    // happen HERE, at the same point the --dev branch above already sets it,
    // and for the identical reason: every `await import(...)` below, and
    // every `NODE_ENV !== 'production'` (or equivalent) gate downstream —
    // plugin-auth's localhost trusted-origin CSRF substitution, its Origin
    // synthesis, its auth-secret fallback and OTP-deliverability check;
    // plugin-dev's production boot guard; the SQL driver's auto-DDL guard;
    // service-settings' crypto-key mode; the seed loader's env scoping — must
    // observe the default, not the raw unset value. Full survey in #11113.
    // An operator who never exported NODE_ENV is booting a real deployment,
    // not asking to be treated as development — this is `os serve` agreeing
    // with `os start` on that, one line, for the whole gate family at once.
    if (flags.dev) {
      if (!process.env.NODE_ENV) process.env.NODE_ENV = 'development';
    } else if (!process.env.NODE_ENV) {
      process.env.NODE_ENV = 'production';
    }

    // ── The port has to BE a port before anything is done with it (#12662) ──
    // `--port abc` used to leave this line as `NaN`, travel through the whole
    // port policy below, and reach the real `listen()`, which refused it with
    // `ERR_SOCKET_BAD_PORT: options.port should be >= 0 and < 65536` — an error
    // naming an internal option, raised from a code path with no connection to
    // the flag the operator typed. `--port 99999` parses fine and died the same
    // way at the same place.
    //
    // ⭐ This sits BEFORE `portAutoShiftAllowed`, and that placement IS the
    // coverage argument: the dev auto-shift branch, the production refusal in
    // the `else if`, and a boot that enters neither are all downstream of this
    // line, so one check covers all three. It is also ahead of every socket —
    // nothing above probes, binds, or resolves anything.
    //
    // The three reported inputs converge here too, which is the other half of
    // the argument. `PORT` and `OS_PORT` never reach flag parsing: they are read
    // by the flag's `default`, and oclif runs no flag `parse` on a default
    // (measured — see {@link describePortSource}). A validating
    // `Flags.integer({ min, max })` would therefore have guarded `--port` alone
    // and left the other two dying exactly as before.
    const portSource = describePortSource(metadata.flags.port?.setFromDefault === true);
    const parsedPort = parseRequestedPort(flags.port);
    if (parsedPort === null) {
      // One write, then exit — for the reason spelled out at the production
      // refusal below: `this.exit(1)` reaches `process.exit` without draining a
      // piped stdout, so a multi-call diagnostic loses its tail.
      printDiagnostic(formatInvalidPortNotice(flags.port, portSource));
      this.exit(1);
    }
    const requestedPort = parsedPort;

    // ── The TLS pair, refused here for the same reason the port is (#16804) ──
    // Ahead of every socket and every import that branches on the protocol, and
    // BEFORE `resolveAuthBaseUrl` is consulted anywhere: the canonical origin's
    // fallback tail is derived from this answer, so a pair that will not be
    // honoured must never reach the resolver as if it would be.
    const tlsIntent = resolveDevTlsIntent(flags);
    if (tlsIntent.kind === 'incomplete') {
      printDiagnostic(colorizeDevTlsNotice(tlsIntent.notice));
      this.exit(1);
    }
    /**
     * The scheme this process will actually speak — `https` only when a
     * certificate and a key were BOTH given. Every origin this boot advertises
     * is built from it, and there is no other way to set it.
     */
    const boundProtocol: ListenerProtocol = listenerProtocol(tlsIntent);
    /**
     * PEM bytes for the listener, read HERE so an unreadable certificate is
     * refused by the process that would have bound the socket, naming the flag
     * and the path — ⛔ never degraded to a plain-http listener (see
     * `formatUnreadableDevTlsFileNotice`).
     */
    let tlsMaterial: DevTlsMaterial | undefined;
    if (tlsIntent.kind === 'requested') {
      try {
        tlsMaterial = readDevTlsMaterial(tlsIntent);
      } catch (e: any) {
        printDiagnostic(colorizeDevTlsNotice(String(e?.message ?? e)));
        this.exit(1);
      }
    }

    // ── …and it has to BE the port the text SAYS, or say otherwise (#12674) ──
    // `parseInt` is kept as the reader (#12662's ruling: nothing that boots
    // today may be refused), and its tolerance changes the answer rather than
    // the spelling — `--port 3e3` selects port 3, `--port 0x0BB8` selects 3000.
    // The boot then succeeds on a port nobody named, which is the harm: not a
    // strange value being accepted, but a server listening somewhere the
    // operator never asked for and nothing saying so.
    //
    // ⭐ Placement completes the three-way split rather than adding a fourth
    // path. A value that cannot be a port has already exited above, so the
    // refusal and this notice can never both fire; and this sits AHEAD of
    // `portAutoShiftAllowed`, so it states the port that was ASKED FOR while
    // #12543's drift notice, a few lines down, states the one that was taken
    // instead. It also runs before the boot-quiet window opens, so — like its
    // siblings — it survives a boot that dies later.
    const textReadNotice = portTextReadNotice(flags.port, portSource, requestedPort);
    if (textReadNotice) printDiagnostic(textReadNotice);

    let port = requestedPort;
    // Port-conflict policy differs by mode:
    //
    //  • Dev (`os dev`, or NODE_ENV=development): hop to the next free port
    //    so several example apps can run side-by-side without manual config.
    //
    //  • Production (`os start`): NEVER silently drift off the configured
    //    port. A drifted port breaks reverse-proxy upstreams, better-auth
    //    callback URLs, and CORS trusted-origins in ways that surface as
    //    opaque 403/502s with no obvious cause. Fail loudly so the operator
    //    frees the port (or sets PORT / --port) before anything boots.
    const portAutoShiftAllowed = flags.dev || process.env.NODE_ENV === 'development';
    if (portAutoShiftAllowed) {
      try {
        port = await getAvailablePort(requestedPort);
      } catch (searchExhausted) {
        // ── The FALLTHROUGH is CORRECT; its SILENCE was the defect (#12620) ──
        // This `catch` used to read `// Ignore — fall through and try the
        // requested port`, and it did exactly that: it discarded an error whose
        // message already named the problem exactly, then fell through and
        // bound the port the search had just proven was taken. The boot died on
        // the kernel's raw EADDRINUSE with nothing anywhere explaining it —
        // this is the one path in the whole port policy that reaches NEITHER
        // half of the family's legibility work. The `else if` below owns the
        // production wording and is never entered here; #12543's drift notice
        // sits under `port !== requestedPort` a few lines down and is false
        // here, because the assignment above threw before it could happen.
        //
        // ⛔ The fallthrough itself stays. Whether an exhausted search should
        // refuse instead is #11113's production/development policy split, and
        // answering it here would be answering a different card.
        printDiagnostic(formatExhaustedPortSearchNotice(requestedPort, searchExhausted));
      }
      if (port !== requestedPort) {
        // ── The shift is CORRECT; its SILENCE was the defect (#12543) ────
        // Auto-shifting is the whole point of this branch and it stays exactly
        // as it is — #11113 owns the other half of the policy, where a busy
        // port is a refusal instead. What was missing is that the hop happened
        // with nothing marking it: the ready banner prints the port that was
        // BOUND, and no line anywhere said it was not the port that was ASKED
        // FOR.
        //
        // A reader holding only the bound port has to already know the
        // requested one and compare the two by hand. That is not a
        // hypothetical cost: five landed consumer-side PRs each re-derived it
        // from this command's banner (a bind probe, the shared `runServe()`
        // read-back, three spawners, a security probe). This line is the only
        // place that holds BOTH numbers for free, so it says both.
        //
        // ⭐ Three facts, not one — what was asked for, that it could not be
        // had, and what was taken instead. A line naming only the bound port
        // is what the banner already prints, and it leaves the comparison
        // undone.
        //
        // CHANNEL — measured, not chosen (#7915). `stdout` is the JSON-RPC
        // channel whenever the stdio MCP transport is mounted, where a single
        // non-frame line reaches the client as a transport error; that is what
        // `serve-stdio-stdout-purity.e2e.test.ts` exists to pin. So this goes
        // through `printDiagnostic` — straight to **stderr**, the same helper,
        // the same stream and the same point in the boot as the production
        // refusal in the `else` branch just below, which is this notice's
        // counterpart under the other half of the same policy.
        //
        // TIMING — also measured. This runs BEFORE the boot-quiet window
        // opens (`bootQuiet` is still `false` here; it is assigned from
        // `verboseBoot` several hundred lines down), so unlike a boot-phase
        // `logger.warn` — which that window captures and replays only after a
        // banner has printed, and only if the boot ever reaches one — this
        // line cannot be swallowed, and it survives a boot that dies later. A
        // drifted port is a plausible CAUSE of such a death, so the notice has
        // to outlive it.
        printDiagnostic(
          '\n'
          + chalk.yellow(`  ⚠ Port ${requestedPort} is in use — serving on ${port} instead.\n`)
          + chalk.dim(`     Development auto-shift: ${requestedPort} was not free, so this server took\n`)
          + chalk.dim(`     the next one that was (${port}). Anything still pointed at ${requestedPort} — a\n`)
          + chalk.dim('     proxy, an OAuth callback URL, another terminal, a test harness — is\n')
          + chalk.dim(`     talking to whatever holds ${requestedPort}, not to this server.`),
        );
      }
    } else if (!(await isPortAvailable(requestedPort))) {
      // One write, for the reason spelled out at the "Nothing to serve" exit
      // below: `this.exit(1)` reaches `process.exit` without draining a piped
      // stdout, so a multi-call diagnostic loses its tail. Same defect, same
      // shape — this one is fixed by construction (the e2e that measured the
      // truncation drives the other exit; reaching this one needs a busy port in
      // production mode).
      printDiagnostic(
        '\n'
        + chalk.red(`  ✗ Port ${requestedPort} is already in use.\n`)
        + chalk.dim('     ObjectStack does not auto-select a different port in production mode:\n')
        + chalk.dim('     a drifted port silently breaks reverse-proxy, OAuth callback, and CORS config.\n')
        + chalk.dim('     Free the port, or pick another via PORT=<port> (or --port <port>).'),
      );
      this.exit(1);
    }

    // Load .env files following Vite/Next.js convention: dotenv-flow, mode
    // `development` under `--dev`, else `NODE_ENV` (`production` when unset).
    // [#22579] Through `loadProjectEnvFiles`, the load `os migrate`'s one-shot
    // boot runs, so the two boots cannot read different files for one project;
    // `utils/boot-preparation-parity.test.ts` holds every preparation step to that.
    loadProjectEnvFiles(process.cwd(), { dev: flags.dev });

    // ── Tenancy-posture boot gate (#5359) ────────────────────────────
    // Resolve the posture ONCE, here, and refuse an unrecognized value
    // EXPLICITLY — before a config is read, before a plugin is loaded,
    // before the kernel bootstraps.
    //
    // `resolveTenancyPosture()` throws on an unrecognized value and its
    // message says "Refusing to boot". Reaching that refusal by letting the
    // throw escape from wherever the first read happened to sit made the
    // refusal arrive wrong in two ways:
    //
    //   • serve's first read sat inside the broad AuthPlugin `try` further
    //     down, whose catch only warns. So the first thing an operator saw
    //     for a typo'd env var was
    //     `⚠ AuthPlugin failed to load: Invalid OS_TENANCY_POSTURE="…"` —
    //     an env-spelling mistake disguised as a plugin-loading problem.
    //   • Boot then continued, degraded and without plugin-auth, through the
    //     whole capability slate (persisting a generated dev crypto key to
    //     disk on the way) until the next UNGUARDED read — ObjectQL's
    //     `SchemaRegistry` constructor, during kernel Phase 1 — aborted
    //     `runtime.start()` and surfaced as a bare `printError`: the
    //     resolver's sentence with no prescription and no ADR reference.
    //
    // Reading it here makes the refusal the FIRST thing that happens and
    // gives it the ADR-0093 D5 shape: an explicit FATAL carrying a fix list,
    // and `process.exit(1)` rather than a throw — a throw is what the
    // swallowing catch below turns back into a warning.
    //
    // Placement is load-bearing twice over:
    //   • AFTER the `.env` load above — OS_TENANCY_POSTURE is routinely set in
    //     a `.env` file, and a gate above that load would read it as unset,
    //     pass, and hand the invalid value straight back to the swallowing path.
    //   • OUTSIDE every `try` in this method, so nothing can demote it.
    //
    // Every later read of the posture — serve's own below, AuthPlugin's
    // `createTenancyService({ requested: resolveTenancyPosture() })`,
    // ObjectQL's `SchemaRegistry` — is downstream of this gate, so none of
    // them can be the one that reports a typo'd posture.
    const postureGate = resolveTenancyPostureOrRefusal();
    if (!postureGate.ok) {
      console.error(postureGate.fatal);
      process.exit(1);
    }
    const tenancyPosture = postureGate.posture;

    // [#22371] `--dev`, or NODE_ENV exactly `development` — `isDevelopmentBoot`
    // (`@objectstack/core`), the reading the auth secret's development fallback
    // is decided by here and in `os migrate security-catalog-overlays --dev`.
    const isDev = isDevelopmentBoot(flags.dev);

    // Resolves the config path AND anchors every host-anchored load in this
    // file at the app that owns it (#11185) — one call, so the anchor cannot be
    // written too late or left out. See `anchorServedApp`.
    const { configPath: absolutePath, configExists } = anchorServedApp(args.config!);
    const relativeConfig = path.relative(process.cwd(), absolutePath);

    // ── Artifact-first fallback ──────────────────────────────────────
    // If the user did not author an `objectstack.config.ts`, but a
    // compiled artifact is reachable (explicit OS_ARTIFACT_PATH —
    // including http(s):// URLs — or the canonical
    // `<cwd>/dist/objectstack.json`), boot from that artifact alone.
    // This is the same capability previously hard-coded in the tenant
    // runtime's own `objectstack.config.ts` — that app is `apps/objectos` in
    // the separate `objectstack-ai/cloud` repo, NOT a path in this one — and
    // lifted into the framework so any project can `objectstack start`
    // against just a `dist/objectstack.json`.
    let useArtifactFallback = false;
    let useEmptyBoot = false;
    /**
     * #21501 — the compiled artifact a CONFIG boot loaded as its app bundle,
     * as the ready banner displays it; set only when one did. A non-host
     * config's standalone stack serves its metadata from that bundle, so the
     * banner's `Artifact:` row names it; a host config (its `plugins` hold
     * code) boots its own module and the row stays `Config:`.
     */
    let configBootBundle: string | undefined;

    // ── Artifact-pinned boot (#8368) ─────────────────────────────────
    // `OS_ARTIFACT_URL` names the artifact BY REFERENCE — an https:// URL
    // fetched at boot, or a file:// URL read directly (the volume-mount
    // workflow) — with an optional SRI-style `#sha256=` integrity pin in the
    // fragment. It is resolved here, before anything else looks for an
    // artifact, and it wins over every local lookup.
    //
    // THE precedence is written once, in `utils/artifact-precedence.ts`; the
    // supervisors (`os start`, `os dev`) resolve through it and hand their
    // answer down on `OS_INTERNAL_ARTIFACT_PATH`, the CLI's private
    // parent-to-child channel. This process reads the channels in this order:
    // the reference, then the supervisor's answer, then the operator's
    // OS_ARTIFACT_PATH. The answer sits BELOW the reference only because a
    // supervisor never sends both (one holding `--artifact`, which outranks the
    // reference, removes OS_ARTIFACT_URL from this env), and ABOVE the
    // operator's OS_ARTIFACT_PATH (which the supervisor no longer overwrites on
    // the way down, so only a higher rung keeps `--artifact` beating an
    // exported OS_ARTIFACT_PATH). See `utils/internal-artifact-channel.ts` for
    // why the CLI stopped writing the operator's knob at all.
    //
    // Beating OS_ARTIFACT_PATH is not a nicety, it is the acceptance
    // criterion: the official runtime image sets
    // `ENV OS_ARTIFACT_PATH=/srv/app/objectstack.json`, so on a container that
    // carries no app at all that variable is always set and always points at a
    // file that does not exist. Without this precedence, "runtime container +
    // one env var" would refuse with "the artifact named by OS_ARTIFACT_PATH
    // does not exist" and the feature would be unreachable exactly where it
    // was designed to be used.
    //
    // It also wins over an `objectstack.config.ts` that happens to be in the
    // cwd. Setting this variable is an explicit instruction to boot a specific
    // published artifact; silently preferring whatever source tree the process
    // is standing in would make the deployed app depend on the container's
    // working directory.
    //
    // The resolver hands back a LOCAL path — remote bytes are materialised
    // under `<home>/artifacts` — so nothing downstream of this line ever sees
    // the URL. That is what keeps a pre-signed reference out of the banner,
    // the metadata service's artifact-source record and every log line, and it
    // also means the bytes that were hashed are the bytes that boot.
    let pinnedArtifact: { localPath: string; display: string } | undefined;
    const artifactUrlEnv = process.env.OS_ARTIFACT_URL;
    if (artifactUrlEnv && artifactUrlEnv.trim() !== '') {
      const runtimeMod = await import('@objectstack/runtime');
      const { resolveArtifactReference, resolveArtifactFetchTimeoutMs, resolveObjectStackHome } = runtimeMod;
      try {
        const resolved = await resolveArtifactReference(artifactUrlEnv, {
          homeDir: resolveObjectStackHome(),
          fetchTimeoutMs: resolveArtifactFetchTimeoutMs(process.env),
          // The cache-fallback warning must survive the boot-quiet window —
          // "this instance is serving cached content" is the one degraded-boot
          // note an operator must not miss.
          warn: (m) => process.stderr.write(chalk.yellow(m) + '\n'),
        });
        pinnedArtifact = { localPath: resolved.localPath, display: resolved.display };
        printDiagnostic();
        printDiagnostic(chalk.dim(
          `  Artifact (OS_ARTIFACT_URL): ${resolved.display}`
          + ` [${resolved.origin}${resolved.expectedSha256 ? `, sha256 verified` : ', unpinned'}]`,
        ));
        useArtifactFallback = true;
      } catch (err: any) {
        // Every message from the resolver is already scrubbed of the URL's
        // credential-bearing parts, so it is printed verbatim. ONE write, for
        // the reason spelled out at the "Nothing to serve" exit below.
        printDiagnostic(
          '\n'
          + chalk.red(`  ✗ Cannot boot from OS_ARTIFACT_URL.\n`)
          + chalk.dim('     ') + String(err?.message ?? err).split('\n').join('\n     ') + '\n'
          + '\n'
          + chalk.dim('     The boot is refused rather than degraded — container orchestration\n')
          + chalk.dim('     should retry, and a runtime told to serve one specific artifact must\n')
          + chalk.dim('     never invent a different one.'),
        );
        this.exit(1);
      }
    }

    // ── The supervisor's answer outranks a cwd config (#21501) ───────────
    // Read ONCE; every use below is this value. A cwd `objectstack.config.ts`
    // is the LOWEST source, so it takes part in this boot only when the
    // supervisor's answer IS that config's own compiled output (the path
    // `os dev`, a bare `os start` in a project, and the documented
    // `os start --artifact ./dist/objectstack.json` all take). Any other answer
    // boots ALONE, exactly as it boots from a directory with no config.
    //
    // MEASURED before this read existed, both legs from a project directory
    // whose config's `dist/objectstack.json` held a DIFFERENT stack:
    // `os dev -a X` and `os start --artifact X` printed `Artifact: X` and served
    // that `dist/objectstack.json` (the config boot's standalone stack read the
    // conventional path, never the channel), and `os start --artifact X` beside
    // a config with no `dist/` served the config itself. The same commands
    // from a directory with no config served X.
    const supervisorArtifact = readInternalArtifactPath();
    const configJoins = cwdConfigJoinsBoot({
      configExists,
      configPath: absolutePath,
      artifact: pinnedArtifact ? { kind: 'reference' }
        : supervisorArtifact
          // Where the supervisor compiles the cwd config, when it is not the
          // conventional path (`os dev` under a local OS_ARTIFACT_PATH): the
          // artifact there is that config's own compiled output too.
          ? { kind: 'path', path: supervisorArtifact, configCompiledTo: readInternalConfigOutputPath() }
          : { kind: 'none' },
    });

    if (!configJoins && !pinnedArtifact) {
      const { resolveDefaultArtifactPath } = await import('@objectstack/runtime');
      // A supervising `os start` / `os dev` passes its already-resolved answer
      // as the explicit override — the same position `OS_ARTIFACT_PATH` used to
      // occupy when the supervisor wrote it, so a named-but-missing artifact is
      // still a loud refusal rather than a silent empty boot.
      const artifactSource = resolveDefaultArtifactPath(supervisorArtifact);
      if (!artifactSource) {
        // Quick-start mode: `objectstack start` lets the user boot an
        // empty kernel with no config and no artifact, then install apps
        // from the marketplace via the Console. The CLI signals this by
        // setting OS_BOOT_EMPTY=1 in the child env.
        if (process.env.OS_BOOT_EMPTY === '1') {
          useEmptyBoot = true;
        } else {
          // Say WHERE it looked. "Not found" alone cannot distinguish the two
          // things that actually happen — a typo'd filename and the wrong cwd
          // (running from a monorepo root instead of the app folder) — and the
          // second is the common one, which listing the searched paths makes
          // self-evident. This stays an ERROR rather than degrading into an
          // empty boot: `os serve` was told to load something, and inventing a
          // zero-object platform instead would hide the mistake behind a
          // running server. Booting with no app at all is a real, supported
          // thing (`os serve` on a config with no metadata, or `os start`) —
          // but it is a stated intent, not a guess made on the user's behalf.
          // ONE write, deliberately. `this.exit(1)` unwinds to oclif's
          // `process.exit`, which does NOT wait for a piped stdout to drain — so
          // a diagnostic split across several `console.log` calls gets
          // truncated mid-message, and the reader loses exactly the part that
          // says where to look. (Measured: as separate calls, only the first two
          // lines survived a pipe.) An error whose tail can vanish is the #4012
          // shape all over again; assembling it into a single write keeps it
          // inside one pipe-buffer flush.
          printDiagnostic(
            chalk.red('  ✗ Nothing to serve — no config and no compiled artifact.') + '\n'
            + chalk.dim(`     Looked for a config at:    ${absolutePath}\n`)
            + chalk.dim(`     Looked for an artifact at: ${path.resolve(process.cwd(), 'dist/objectstack.json')}\n`)
            + chalk.dim('     Neither OS_ARTIFACT_URL nor OS_ARTIFACT_PATH is set.\n')
            + '\n'
            + chalk.dim('     Hint: `objectstack init` scaffolds a new project;\n')
            + chalk.dim('           `objectstack start` boots an app-less kernel against your marketplace;\n')
            + chalk.dim('           `objectstack build` (or OS_ARTIFACT_PATH) supplies a compiled artifact;\n')
            + chalk.dim('           OS_ARTIFACT_URL=https://…/objectstack.json boots a published artifact\n')
            + chalk.dim('           by reference (optionally pinned with #sha256=<64 hex chars>).\n')
            + chalk.dim('           Already have a project? Check your working directory.'),
          );
          this.exit(1);
        }
      }
      useArtifactFallback = true;
    }

    // Quiet loading — only show a single spinner line
    printDiagnostic();
    if (useEmptyBoot) {
      printDiagnostic(chalk.dim('  No objectstack.config.ts or artifact found — booting empty kernel...'));
    } else if (pinnedArtifact) {
      printDiagnostic(chalk.dim('  Booting from the artifact named by OS_ARTIFACT_URL (default host)...'));
    } else if (useArtifactFallback && configExists) {
      // Never "No objectstack.config.ts found" when one is sitting right there:
      // say it is deliberately not loaded, and why.
      printDiagnostic(chalk.dim(
        `  ${relativeConfig} is not loaded — the artifact resolved for this boot outranks it; booting from that artifact (default host)...`,
      ));
    } else if (useArtifactFallback) {
      printDiagnostic(chalk.dim('  No objectstack.config.ts found — booting from artifact (default host)...'));
    } else {
      printDiagnostic(chalk.dim(`  Loading ${relativeConfig}...`));
    }

    // Track loaded plugins for summary
    const loadedPlugins: string[] = [];
    const shortPluginName = (raw: string) => {
      // Map verbose internal IDs to short display names
      if (raw.includes('objectql')) return 'ObjectQL';
      if (raw.includes('driver') && raw.includes('memory')) return 'MemoryDriver';
      if (raw.startsWith('plugin.app.')) return raw.replace('plugin.app.', '').split('.').pop() || raw;
      if (raw.includes('hono')) return 'HonoServer';
      return raw;
    };
    const trackPlugin = (name: string) => { loadedPlugins.push(shortPluginName(name)); };

    // Track resolved storage driver + connection target for the startup banner.
    // The value lands here raw when it came from this command's own
    // OS_DATABASE_URL fallback and already-redacted when it came from probing a
    // registered driver, so it is redacted at print time — `redactConnectionUrl`
    // is idempotent, so the second pass over an already-clean URL is a no-op.
    let resolvedDriverLabel: string | undefined;
    let resolvedDatabaseUrl: string | undefined;
    // The on-disk SQLite file this boot serves, when it serves one. Kept apart
    // from `resolvedDatabaseUrl` on purpose: that value is a string for a
    // human and may be redacted or labelled, while this one is handed to
    // `stat` — see `describeDriverSqliteFile`.
    let servedSqliteFilePath: string | undefined;
    // #21733 — the file-backed native SQLite database a composed STANDALONE
    // stack declared as its `default` datasource, read BEFORE the kernel boots
    // so the `telemetry` sibling can be provisioned next to it (step 2 below).
    // `servedSqliteFilePath` cannot serve: on this path it is only learned by
    // probing the booted kernel. Unset for every other boot and every other kind.
    let standaloneSqlitePrimary: string | undefined;

    // Resolve the kernel logger level up front. It decides more than the
    // logger's own threshold: it decides whether the boot-quiet window below
    // runs at all, so it has to be known BEFORE the window opens rather than
    // at the `new Runtime(...)` call further down.
    const bootLogLevel = resolveLogLevel({
      verbose: flags.verbose,
      flag: flags['log-level'],
      envLevel: readLogLevelEnv(),
    });
    // `--verbose` / `--log-level debug|info` asks to watch the boot happen.
    // Blanking stdout through it would be the flag defeating itself, so at
    // those levels the window never opens and boot output streams live — the
    // banner just prints at the end of it (#4012).
    const verboseBoot = isVerboseBootLevel(bootLogLevel);

    // Save original console/stdout methods — we'll suppress noise during boot.
    // `origStdoutWrite` is the redirected write installed at the top of `run()`,
    // NOT the real stdout: restoring it hands the stream back to the stderr
    // forwarder, which is where every diagnostic belongs (#7915).
    const originalConsoleLog = console.log;
    const originalConsoleDebug = console.debug;
    const origStdoutWrite = process.stdout.write.bind(process.stdout);
    // Everything the quiet window intercepts lands here instead of being
    // dropped on the floor, so boot-phase `logger.warn` survives to be
    // replayed under the banner (#4012).
    const bootLogs = new BootLogCapture();
    /** Diagnostics to replay, or `undefined` when the boot had nothing to say. */
    const collectBootDiagnostics = () => {
      const lines = bootLogs.diagnostics();
      return lines.length > 0 ? { lines, dropped: bootLogs.droppedCount } : undefined;
    };

    const restoreOutput = () => {
      bootQuiet = false;
      process.stdout.write = origStdoutWrite;
      console.log = originalConsoleLog;
      console.debug = originalConsoleDebug;
    };

    try {
      // ── Hold back runtime noise during boot ───────────────────────
      // Multiple sources write to stdout during startup:
      //   • Pino-pretty (direct process.stdout.write)
      //   • ObjectLogger browser fallback (console.log)
      //   • SchemaRegistry (console.log)
      // We intercept stdout entirely, then restore after runtime.start().
      //
      // Intercepted is not discarded (#4012): `ObjectLogger` routes `warn` to
      // stdout — only `error`/`fatal` go to stderr — so dropping these bytes
      // dropped every boot-phase warning a plugin logged, on both `os serve`
      // and `os dev` (which inherits this child's stdio), at every log level.
      // The chatter still never reaches the banner; the kernel-logger records
      // among it are buffered and replayed once the banner has printed.
      bootQuiet = !verboseBoot;
      if (!verboseBoot) {
        process.stdout.write = (chunk: any, ...rest: any[]) => {
          if (bootQuiet) {
            bootLogs.write(chunk, typeof rest[0] === 'string' ? rest[0] : undefined);
            // Honor the write callback so a caller awaiting drain still resumes.
            const cb = rest.find((a) => typeof a === 'function');
            if (cb) cb();
            return true;
          }
          return (origStdoutWrite as any)(chunk, ...rest);
        };
        console.log = (...args: any[]) => { if (!bootQuiet) originalConsoleLog(...args); };
        console.debug = (...args: any[]) => { if (!bootQuiet) originalConsoleDebug(...args); };
      }

      // Load configuration
      // --prebuilt: load as native ESM (no esbuild, no bundle-require) —
      // intended for production where the config has been compiled to dist/.
      // --artifact-fallback: skip config loading entirely; the default-host
      // helper will synthesize a stack from the artifact JSON below.
      const { mod } = useArtifactFallback
        ? { mod: { default: {} as any } }
        : flags.prebuilt
          ? { mod: await import(absolutePath.startsWith('/') ? `file://${absolutePath}` : absolutePath) }
          : await bundleRequire({ filepath: absolutePath, external: BUNDLE_REQUIRE_EXTERNALS });

      let config = mod.default || mod;

      if (!useArtifactFallback && !config) {
        throw new Error(`No default export found in ${args.config}`);
      }

      // Preserve module-level named exports (e.g. the `onEnable` runtime hook
      // and `functions`) that would otherwise be dropped when we unwrap
      // `mod.default`. Without this AppPlugin can never invoke runtime hooks
      // declared as `export const onEnable = ...` alongside the default
      // `defineStack(...)` export.
      if (mod.default != null && config !== mod) {
        const merged: any = { ...config };
        for (const key of Object.keys(mod)) {
          if (key === 'default' || key in merged) continue;
          merged[key] = (mod as any)[key];
        }
        config = merged;
      }

      // Package docs (ADR-0046): flat `src/docs/*.md` are collected into the
      // stack at COMPILE time (compile.ts step 3d). The config-load path here
      // re-derives metadata from `defineStack(...)`, which never carries the
      // markdown docs — so without this, `os dev`/`os serve` against a config
      // serves ZERO docs (GET /meta/doc empty) even though `os build` produces
      // them and an artifact boot serves them. Mirror compile's collection so
      // docs render under /docs/<name> in dev exactly as from a built artifact.
      // Collection only (no lint-fail): docs are additive; never block boot.
      //
      // [#18431] The same mirroring, one level down: a `src/<pkg>/docs/`
      // directory naming one of this config's `packages[]` entries is collected
      // onto THAT package's body (ADR-0130 D4 option B), exactly where
      // `os build` puts it. `AppPlugin` REGISTERS each body — it hands the
      // whole artifact to `getService('manifest').register()`, which runs
      // `resolveArtifactPackageOrder` and `registerApp(body)` per body, and
      // `registerMetadataCollections` enumerates `docs` — so dev serves them as
      // an artifact boot does. Leaving this half out would re-open the asymmetry
      // the paragraph above exists to close — `os build` producing docs that
      // `os dev` cannot show.
      //
      // [#22405] WHERE the flat set lands is `placeCollectedDocs`'s decision,
      // the one `os build` makes: on a multi-package config it rides the body
      // of the package whose id is the stack's `manifest.id`. With no owner (no
      // `packages[]`, or a `manifest.id` naming no single entry) it stays on the
      // top level, exactly as `os build` keeps it. Inline top-level docs never
      // move; the name dedupe below runs only over what stays.
      //
      // [#22521] This is PLACEMENT, not the residual rule, and it stays: what
      // remains on the top level of a multi-package config is registered under
      // `manifest.id` with a warning by the metadata door's one residual rule
      // (`AppPlugin` → `MetadataPlugin.registerUnclaimedTopLevel`). Measured
      // with this placement withheld, the flat pages of a stack whose
      // `manifest.id` names one package are still served under that id, but as
      // a residual, so the config boot warns where the artifact boot of the same
      // project — whose `os build` placed them on the body — does not.
      if (!useArtifactFallback) {
        try {
          const { collectDocsFromSrc, placeCollectedDocs } = await import('../utils/collect-docs.js');
          const collected = collectDocsFromSrc(absolutePath, (config as any)?.packages);
          const inline = Array.isArray((config as any).docs) ? (config as any).docs : [];
          // `collectDocsFromSrc`'s `docs` IS the flat set; the top-level set is
          // inline first, as `collectAndLintDocs` returns it to `os build`.
          const placed = placeCollectedDocs(config, {
            docs: [...inline, ...collected.docs],
            flatDocs: collected.docs,
            packageDocs: collected.packageDocs,
          });
          if (collected.docs.length > 0 && placed.docs.length > 0) {
            const byName = new Map<string, any>();
            for (const d of placed.docs) {
              if (d?.name) byName.set(d.name, d);
            }
            config = { ...config, docs: Array.from(byName.values()) };
          }
          if (placed.packages !== (config as any).packages) config = { ...config, packages: placed.packages };
        } catch {
          /* docs are additive — never block boot on collection */
        }
      }

      // Boot-mode dispatch: this open-core CLI only supports `standalone`
      // (and the artifact-fallback shortcut). Cloud / multi-environment
      // boot modes live in a separate distribution and are no longer
      // resolved from this package.
      if (useArtifactFallback || shouldBootWithLibrary(config)) {
        // The boot stack returns only `{plugins, api}` — preserve the
        // original stack metadata (notably `requires`, `analyticsCubes`,
        // `tiers`) so the capability resolver further down can read it.
        const originalConfig = config;
        const resolvedMode = config.bootMode ?? process.env.OS_MODE ?? 'standalone';
        if (useArtifactFallback) {
          // Artifact-only boot — no objectstack.config.ts authored.
          // When `useEmptyBoot` is set the user asked for a quick-start
          // ("objectstack start" with nothing to load); skip the
          // "missing artifact" error and assemble a bare kernel that
          // can later install marketplace apps at runtime.
          const { createDefaultHostConfig } = await import('@objectstack/runtime');
          const defaultHostInput = {
            requireArtifact: !useEmptyBoot,
            dev: isDev,
            // #8368: the already-fetched, already-verified LOCAL copy. Passing
            // it explicitly (rather than re-deriving from the environment) is
            // what stops the loader from fetching the URL a second time — a pin
            // that verifies one response while a different response boots would
            // verify nothing.
            // Same reasoning one rung down: when no reference is in play, a
            // supervisor's resolved answer is handed over explicitly instead of
            // being re-derived from the environment.
            ...(pinnedArtifact
              ? { artifactPath: pinnedArtifact.localPath }
              : supervisorArtifact ? { artifactPath: supervisorArtifact } : {}),
          };
          const bootResult = await createDefaultHostConfig(defaultHostInput);
          // #21733 — the `default` database this stack declared, for the
          // telemetry sibling (step 2). The same input the host config was
          // built from: the database resolution reads the artifact only for a
          // declared default datasource, and the empty boot's synthesized stub
          // declares none, so the artifact rung `createDefaultHostConfig`
          // settles internally cannot answer differently.
          standaloneSqlitePrimary = await standaloneTelemetryPrimary(defaultHostInput);
          // [#4002] `api` merges per key — see mergeBootConfig. A shallow spread
          // let the boot builder's two scoping keys wipe the author's whole `api`
          // block, silently dropping `requireAuth` / `enforceProjectMembership`.
          config = mergeBootConfig(originalConfig as any, bootResult as any) as any;
        } else if (resolvedMode === 'standalone') {
          const { createStandaloneStack } = await import('@objectstack/runtime');
          // Anchor the default sqlite database under the project folder
          // (next to objectstack.config.ts) instead of the global
          // ~/.objectstack home, so per-project data stays per-project.
          const standaloneInput = {
            ...(config.standalone ?? {}),
            projectRoot: (config.standalone?.projectRoot ?? path.dirname(absolutePath)),
            // #2229: dev enables the native-better-sqlite3 → wasm → in-memory
            // step-down in the shared datasource factory; prod fails loudly.
            dev: isDev,
            // #21501: a supervised config boot serves the supervisor's answer
            // (here always the config's own compiled output — `configJoins`),
            // handed over explicitly. Left to the standalone stack's own
            // fallback, an exported OS_ARTIFACT_PATH would outrank
            // `os start --artifact ./dist/objectstack.json` in this process.
            ...(supervisorArtifact ? { artifactPath: supervisorArtifact } : {}),
          };
          const bootResult = await createStandaloneStack(standaloneInput);
          // #21733 — the `default` database the stack just declared, resolved
          // by the runtime's own pre-boot resolution over the SAME input, for
          // the telemetry sibling (step 2).
          standaloneSqlitePrimary = await standaloneTelemetryPrimary(standaloneInput);
          // #21501 — did the standalone stack load a compiled artifact as this
          // app's bundle? Its AppPlugin over the bundle is the proof (it is
          // pushed only when the bundle loaded, and a non-host config carries
          // no plugin of its own). If so, the ready banner names THAT file:
          // the metadata served came from it, not from the config module. The
          // path is the runtime's own ladder over the same explicit input the
          // stack was handed — never a copy of it.
          if (Array.isArray((bootResult as any)?.plugins) && (bootResult as any).plugins.some(isAppPluginLike)) {
            const { resolveDefaultArtifactPath, redactArtifactUrl } = await import('@objectstack/runtime');
            const loaded = resolveDefaultArtifactPath(supervisorArtifact);
            if (loaded) {
              configBootBundle = /^https?:\/\//i.test(loaded)
                ? redactArtifactUrl(loaded)
                : (path.relative(process.cwd(), loaded) || loaded);
            }
          }
          // [#4002] Per-key `api` merge — see mergeBootConfig.
          config = mergeBootConfig(originalConfig as any, bootResult as any) as any;
        } else {
          throw new Error(
            `Boot mode '${resolvedMode}' is not available in the open-core CLI.\n`
            + `Only 'standalone' is supported here. Cloud / multi-environment hosts ship\n`
            + `from a separate distribution. Either switch to bootMode='standalone' or use\n`
            + `the cloud-aware CLI.`,
          );
        }
      }

      // ── Resolve plugin tiers ──────────────────────────────────────
      // Precedence: config.requires (capability declarations) >
      //             config.tiers > --preset > built-in default.
      //
      // `requires: ['ai', 'automation', ...]` is the recommended
      // app-level way to declare platform dependencies. The CLI
      // expands each capability name into the matching tier so the
      // optional auto-registration blocks below light up without
      // extra flags. Explicitly-listed `config.plugins` always load
      // and shadow any capability resolution (i.e. an explicit
      // instance wins over the auto-loader).
      const presetName = flags.preset ?? (isDev ? 'default' : 'default');
      // [#22301] WHICH tokens a served boot mounts providers for is ONE rule,
      // `resolveServedCapabilities` (`@objectstack/core`), read by this command,
      // by `@objectstack/verify`'s `bootStack` and by `os migrate plan`'s
      // declaration boot, so an app's tests mount the services its users'
      // server mounts. In its order: the tokens the stack declares, as
      // `stackDeclaredCapabilities` reads them (the top-level list, otherwise
      // each package body's, #22288), deduplicated; `email` when `auth` is
      // declared; the host defaults below; the always-on slate
      // (`Serve.ALWAYS_ON_CAPABILITIES`) unless `--preset minimal`; and `job`
      // and `queue` moved ahead of the tokens that schedule background work.
      // Its `declared` set carries the "required" INTENT (#1597): a declared
      // capability whose provider cannot be provided is a hard boot error,
      // whereas a token the platform appended stays best-effort (warn +
      // continue) — that half is this command's own, in the resolver below.
      //
      // The two host defaults are this process's own decisions, read from its
      // environment, so they are handed to the rule rather than made by it:
      //
      //  - MCP is a default-on core capability: serve `/api/v1/mcp` unless
      //    `OS_MCP_SERVER_ENABLED=false` opts out. The dispatcher gates the route
      //    on the SAME decision point (`isMcpServerEnabled`), so serving the
      //    route without also loading the MCP plugin would 501 every request
      //    (#2698: the default must yield a connectable MCP endpoint). Explicit
      //    `requires: ['mcp']` in config works regardless of the env var.
      //  - Pinyin search recall (#2486): locale-gated platform capability. When
      //    `OS_SEARCH_PINYIN_ENABLED` is unset, the default derives from the
      //    stack's configured locales (any `zh-*` → on), and the resolved
      //    decision is stamped back into the env var — every later consumer
      //    (each engine's SchemaRegistry provisioning the `__search` companion
      //    column, the plugin's own gate) reads the same answer via the no-arg
      //    `resolveSearchPinyinEnabled()`. The shared `stampSearchPinyinEnabled`
      //    helper is also what `createStandaloneStack` stamps from the compiled
      //    artifact, so serve/dev and `os migrate plan`/`apply` cannot compute
      //    different schema views of the same source tree (#3955).
      const hostDefaults: string[] = [];
      if (isMcpServerEnabled()) hostDefaults.push('mcp');
      if (stampSearchPinyinEnabled((config as any).i18n)) hostDefaults.push('pinyin-search');
      const served = resolveServedCapabilities(stackDeclaredCapabilities(config), { preset: presetName, hostDefaults });
      const requires: string[] = [...served.tokens];
      const declaredRequires: ReadonlySet<string> = served.declared;
      // Capability → tier: any capability that is gated by a tier
      // (Serve.CAPABILITY_TO_TIER) automatically opens that tier when listed
      // in `requires`. Capabilities NOT in that map (e.g. `automation`,
      // `analytics`, `audit`) bypass tier gating and are loaded directly by
      // the capability-resolver block further down.
      //
      // [#22288] `tiers` is package-owned like `requires`, and no boot path
      // lays it over the top level (`createStandaloneStack` does not carry it),
      // so a package's own `tiers` were ignored on `os serve`, `os dev` and
      // `os start` alike. Same rule as `requires` above.
      const declaredTiers = resolveStackCollection(config, 'tiers') as string[];
      // [#22371] The precedence itself — declared tiers, else the preset's, plus
      // the tier each `requires` token opens — is `resolveStackTiers`
      // (`@objectstack/core`), the rule the auth gate below is fed by in this
      // command and in `os migrate security-catalog-overlays` alike.
      const tiers: Set<string> = resolveStackTiers({ declaredTiers, requires, preset: presetName });
      const tierEnabled = (t: string) => tiers.has(t);
      const requiresCapability = (c: string) => requires.includes(c);

      // Import ObjectStack runtime
      const { Runtime } = await import('@objectstack/runtime');

      // The kernel logger level. Honors --verbose / --log-level and
      // $OS_LOG_LEVEL / $LOG_LEVEL, defaulting to `warn` so flow/hook
      // execution failures surface even when the CLI manages its own output
      // (ADR-0032 "fail loudly"; see #1533). `--log-level silent` restores the
      // fully-quiet behavior. Resolved above the boot-quiet window, which
      // keys off it too (#4012).
      const loggerConfig = { level: bootLogLevel };

      // The root of the app being served: where its `package.json` and
      // `objectstack.config.ts` live. `importFromHost` (module scope, top of this
      // file) anchors every app-declarable optional load here, and defaults to
      // this same value, so a load written ANYWHERE in this method — above this
      // line included — resolves from the app rather than the CLI. That
      // reachability is the point: see the helper's own note for the two shipped
      // instances (cloud#1013, #10645) that a mid-function binding cost.
      //
      // NOT `process.cwd()`: the config is an ARGUMENT, so the app being served
      // is the directory that config was read from, which need not be the
      // directory the operator stood in (#11185). `anchorServedApp` resolved it
      // at the top of this method; this reads the same answer rather than
      // recomputing a second one, so the file has ONE notion of the app root.
      //
      // #4719: what the host root DECLARES is the contract; being merely
      // reachable through a hoisted workspace store is not, and is refused.
      const hostRoot = servedAppRootOrCwd();

      // Cluster wiring: env-driven driver selection (mirrors OS_DATABASE_URL).
      // The remote driver self-registers on import; import it dynamically so it
      // works in BOTH config-boot and compiled-artifact mode. Open-core ships
      // only the in-memory driver — remote drivers (e.g. redis) come from the EE
      // distribution. An absent driver does NOT fall back to the in-memory
      // cluster: `clusterConfig` still names it and `defineCluster()` raises
      // its documented error (cluster.mdx §8.1). The only documented downgrade
      // here is a multi-node GATE DENIAL, below. (#13330 — this sentence said
      // the opposite for as long as the silent catch below agreed with it.)
      let clusterConfig: { driver: string; url?: string } | undefined;
      // The gate's verdict, held for the operator-facing telemetry emitted near
      // the end of boot (#12667). The gate is consulted exactly once per
      // process and its answer is otherwise consumed on the spot by the boot
      // warning, so a second consult later would be a second question, not a
      // second reading of the same one. `undefined` means the gate was never
      // consulted — a single-node boot — and nothing is emitted.
      let multiNodeVerdict: MultiNodeGateVerdict | undefined;
      const __clusterDriver = process.env.OS_CLUSTER_DRIVER?.trim();
      if (__clusterDriver && __clusterDriver !== 'memory') {
        // Multi-node authorization gate (open mechanism): a distribution (e.g.
        // an EE license) may deny multi-node. On denial this file drops the
        // remote driver and leaves `clusterConfig` unset, so the Runtime falls
        // back to the in-process driver.
        //
        // ⛔ That is NOT the same as "the boot survives", and this comment used
        // to say it was ("never brick"). Measured on #14116: when the operator
        // ALSO declared a multi-node topology (`OS_CLUSTER_REPLICAS > 1` /
        // `OS_EXPECT_MULTI_NODE=true`), the in-process fallback then trips the
        // split-brain guard in `ClusterServicePlugin.init` and the boot is
        // REFUSED. The refusal is correct — N replicas on per-process locks is
        // exactly the silent corruption that guard exists to stop — but a
        // denial and a declared topology together mean refuse, not degrade.
        // The warning below says so.
        // Dynamic, non-literal specifier so the CLI does not statically depend
        // on the cluster package (mirrors the remote-driver import below).
        //
        // Loaded through `importFromHost`, NOT a bare `import()`: the cluster
        // packages ship with a distribution and are declared by the APP, so they
        // live in the app's node_modules, while a bare import resolves against
        // the CLI's own realpath and can only see the framework's. Measured on
        // the EE image: the CLI's `node_modules/@objectstack/` held 48 packages
        // and neither cluster one, so this line threw `Cannot find package
        // '@objectstack/service-cluster'` and took the whole boot down — while
        // app-side code loaded the very same package fine.
        const __clusterPkg: string = '@objectstack/service-cluster';
        // The whole namespace, not just the gate: the DRIVER REGISTRY read
        // further down has to come from this same module instance, because
        // that is the instance `defineCluster()` consults (#13330).
        const __clusterModule = (await importFromHost(__clusterPkg)) as {
          checkMultiNodeAllowed: (requested?: number) => MultiNodeGateVerdict;
          /** Optional: an app on a pre-#13330 `service-cluster` does not have it. */
          listClusterDrivers?: () => string[];
          // Optional: an app may pin an older service-cluster that predates
          // the mount helper (#13537); `?.` below keeps that boot walking.
          mountMultiNodeGateFromHost?: (
            importer: (specifier: string) => Promise<unknown>,
          ) => Promise<unknown>;
        };
        const { checkMultiNodeAllowed, mountMultiNodeGateFromHost } = __clusterModule;
        // [#13537] Mount the distribution's gate on EVERY boot route, BEFORE
        // consulting it. Registration used to depend on one app config file
        // executing (the EE config calling `registerMultiNodeGate`), so the
        // thin-extension and artifact-direct routes booted with no gate at
        // all — and the gate then defaulted to allow. The helper imports the
        // gate-carrying distribution packages through this file's own
        // host-anchored importer (passed as a value, so every carrier load
        // resolves from the served app per #4719 — same guarantee as the
        // `importFromHost` call above, just exercised inside the package that
        // owns the carrier list). Best-effort: with no distribution installed
        // nothing mounts, and the gate's fail-closed default answers below.
        //
        // ⚠️ Resolved against #13330's namespace read on main: the mount helper
        // is destructured from THE SAME `__clusterModule`, so the instance that
        // registers is provably the instance `checkMultiNodeAllowed` and
        // `listClusterDrivers` are read from. Re-importing the package for the
        // mount would have re-opened the split this file just closed.
        try { await mountMultiNodeGateFromHost?.(importFromHost); }
        catch { /* never brick the boot for an add-on — the check below fails closed */ }
        // Ask the gate about the topology the operator actually DECLARED.
        // Calling zero-arg leaves `requested` undefined, which a cap-aware gate
        // has nothing to clamp against — so the licensed-overflow verdict was
        // unreachable from here, not merely unread.
        //
        // `OS_CLUSTER_REPLICAS` is a **declared desired count**, identical in
        // every replica, not a live membership count — no membership count
        // exists at boot (see the gate module's own note). For an *advisory*
        // message that is the right input by construction: the operator is being
        // told about the configuration they wrote. It is NOT sufficient input
        // for enforcement, which is why enforcement is a separate mechanism.
        //
        // `Number(undefined)` is `NaN`, which the gate normalizes to "not
        // declared" — normalization lives at the seam on purpose, so there is
        // deliberately no `?? 0` or pre-parse here.
        const __gate = checkMultiNodeAllowed(Number(process.env.OS_CLUSTER_REPLICAS));
        // Held for BOTH branches below: an outright denial is as much an
        // operator-facing reading as a licensed overflow, and only one of the
        // two currently reaches a log line an operator is likely to still have.
        multiNodeVerdict = __gate;
        if (!__gate.allowed) {
          console.warn(
            `[cluster] multi-node not authorized (${__gate.reason ?? 'denied'}) — ` +
            `falling back to the in-process cluster driver. If this deployment ALSO ` +
            `declared a multi-node topology (OS_CLUSTER_REPLICAS>1 / OS_EXPECT_MULTI_NODE=true), ` +
            `the split-brain guard refuses the boot rather than run replicas on per-process ` +
            `locks — drop the declaration to run single-node, or license the capability. ` +
            `Remove OS_CLUSTER_DRIVER to silence.`,
          );
        } else {
          // Licensed-overflow advisory: the cluster IS entitled to run, it just
          // asked for more nodes than it paid for. Distinct from the denial
          // above, and deliberately not a downgrade.
          const __capAdvisory = formatMultiNodeCapAdvisory(__gate);
          if (__capAdvisory) console.warn(__capAdvisory);
          // Same host-anchored resolution as the gate above — the shipped
          // drivers (`-redis`, `-postgres`, …) are app-declared too.
          //
          // ── Why this is no longer a silent catch (#13330) ────────────────
          //
          // A driver package's entire contract is a load-time SIDE EFFECT:
          // `registerClusterDriver('<driver>', …)` into the module-scope
          // registry of `@objectstack/service-cluster`, which `defineCluster()`
          // reads two statements below. Whether that side effect landed is a
          // fact about THIS process, so it is read here rather than assumed.
          //
          // It used to be assumed. The catch was silent on two stated grounds —
          // "may already be registered by the loaded config" and "an absent
          // driver is a documented fall-back to the in-memory cluster" — and a
          // single EE boot measured both wrong at once:
          //
          //   • the load SUCCEEDED and the registration was invisible. The
          //     declared leg of `importFromHost` resolved with CommonJS
          //     semantics, so the driver ran as its `.cjs` build and registered
          //     into a SECOND instance of the registry, while the ESM Runtime
          //     read the first. Fixed at the seam (`@objectstack/types/node`);
          //     this reading is what makes any residual split audible instead
          //     of arriving as "not registered" one line later.
          //   • an absent driver falls back to nothing HERE — `clusterConfig`
          //     below names the driver either way, so `defineCluster()` raises
          //     its documented error (cluster.mdx §8.1). That is left exactly
          //     as it is: downgrading to in-memory instead would boot a silent
          //     single node for an operator who explicitly asked for a remote
          //     driver, and on the multi-replica deployments this matters for,
          //     the ADR-0010 split-brain guard throws on that downgrade anyway.
          //     What changes is only that the reason is no longer swallowed.
          //
          // Nothing below throws: every branch is a diagnosis printed ahead of
          // behaviour that is unchanged.
          let __driverLoadError: unknown;
          try {
            await importFromHost(`@objectstack/service-cluster-${__clusterDriver}`);
          } catch (err) {
            __driverLoadError = err;
          }
          // `undefined` ⇒ the app's `@objectstack/service-cluster` predates
          // `listClusterDrivers`, so the registry cannot be read from here.
          // That is NOT MEASURED — it is not "registered" and not "missing",
          // and no branch below claims either.
          const __registeredDrivers =
            typeof __clusterModule.listClusterDrivers === 'function'
              ? __clusterModule.listClusterDrivers()
              : undefined;
          const __driverVisible =
            __registeredDrivers === undefined
              ? undefined
              : __registeredDrivers.indexOf(__clusterDriver) >= 0;
          if (__driverVisible !== true) {
            if (__driverLoadError !== undefined) {
              // Resolution failures carry a kind and are already worded for an
              // operator by `createHostImporter`; anything else RESOLVED and
              // then crashed while evaluating. Swallowing the second is how a
              // driver with a broken dependency reported as "not registered",
              // sending operators to look for a package already installed.
              const __kind = hostImportFailureKind(__driverLoadError);
              if (__kind !== undefined) {
                console.warn(
                  `[cluster] driver "${__clusterDriver}" was requested but could not be ` +
                  `loaded (${__kind}):\n${
                    __driverLoadError instanceof Error
                      ? __driverLoadError.message
                      : String(__driverLoadError)
                  }`,
                );
              } else {
                console.warn(
                  `[cluster] driver "${__clusterDriver}" resolved but threw while loading — ` +
                  `this is the driver package's own failure, not a missing package:`,
                  __driverLoadError,
                );
              }
            } else if (__driverVisible === false) {
              // Loaded cleanly and still not in the registry: two live
              // instances of `@objectstack/service-cluster` in one process,
              // which is a PHYSICAL-copy split no resolver condition can merge.
              console.warn(
                `[cluster] driver "${__clusterDriver}" loaded but did not register: ` +
                `@objectstack/service-cluster-${__clusterDriver} evaluated without error, yet the ` +
                `registry this boot reads holds [${__registeredDrivers?.join(', ') || 'nothing'}]. ` +
                `Two instances of @objectstack/service-cluster are live in this process and the ` +
                `driver registered into the other one — look for two physical copies (a version ` +
                `skew between the app and the framework, or a bundled one). Importing ` +
                `"@objectstack/service-cluster-${__clusterDriver}" from objectstack.config.ts ` +
                `registers into the instance the Runtime reads.`,
              );
            }
          }
          clusterConfig = { driver: __clusterDriver, url: process.env.OS_REDIS_URL };
        }
      }
      const runtime = new Runtime({
        kernel: {
            logger: loggerConfig
        },
        cluster: clusterConfig as any,
      });
      const kernel = runtime.getKernel();

      // ── The deployment's SDUI component manifest (#20312, ADR-0080 §5) ──
      // Resolved ONCE, beside the served config, through the same resolver the
      // authoring commands use (the project's own sdui.manifest.json, then the
      // copy @objectstack/console ships), and registered under the key the save
      // door reads per publish — where every html page's `source` is compiled
      // against it and its `requires` stamped and checked. Registered before any
      // plugin inits, so no plugin can see the kernel without it. No manifest:
      // nothing is registered, one line says what that costs, and the boot goes on.
      {
        const { SDUI_MANIFEST_SERVICE } = await import('@objectstack/metadata-protocol');
        const { registerDeploymentSduiManifest } = await import('../utils/sdui-manifest.js');
        const sduiManifestLine = registerDeploymentSduiManifest(
          (manifest) => { kernel.registerService(SDUI_MANIFEST_SERVICE, manifest); },
          path.dirname(absolutePath),
        );
        if (sduiManifestLine) console.warn(chalk.yellow(`  ⚠ ${sduiManifestLine}`));
      }

      // Load plugins from configuration, and merge devPlugins if in dev mode —
      // `stackBootPlugins` [#22371], the list `os migrate
      // security-catalog-overlays --dev` composes too.
      let plugins: any[] = stackBootPlugins(config, flags.dev);

      // 1. Auto-register ObjectQL Plugin if objects define but plugins missing
      // [#15006] The whole gate — the `objects` read AND the already-composed
      // check — is `shouldAutoRegisterObjectQL`. It answers exactly as the two
      // inline expressions did for every stack that boots today, and resolves
      // `packages[]` when the flattened top level is absent, which is the shape
      // that used to boot with NO QUERY ENGINE and throw nothing.
      if (shouldAutoRegisterObjectQL(config, plugins)) {
         try {
           const { ObjectQLPlugin } = await import('@objectstack/objectql');
           await kernel.use(new ObjectQLPlugin());
           trackPlugin('ObjectQL');
         } catch (e: any) {
           // silent
         }
      }

      // ADR-0057 §3.6 — the `telemetry` sibling datasource, provisioned next to
      // a file-backed SQLite primary by EVERY serving boot through ONE helper
      // (`provisionTelemetryDatasource`, #21733): the config-load fallback in
      // step 2 below and the standalone stack right after it. Dev default-on;
      // `OS_TELEMETRY_DB=0` opts out, `OS_TELEMETRY_DB=<path>` opts in anywhere
      // (incl. serve) — `resolveTelemetryDbPath` is the rule, never restated here.
      const provisionTelemetry = async (primaryPath: string | undefined): Promise<void> => {
        const telemetryPath = await provisionTelemetryDatasource({
          primaryPath,
          env: process.env,
          dev: isDev,
          use: (plugin) => kernel.use(plugin as any),
          warn: (m) => console.warn(chalk.yellow(m)),
        });
        if (telemetryPath) {
          trackPlugin('TelemetryDatasource');
          printDiagnostic(chalk.dim(`  telemetry datasource: ${telemetryPath} (lifecycle-classed system data; OS_TELEMETRY_DB=0 to disable)`));
        }
      };

      // 2. Auto-register storage driver
      // Priority:
      //   1. OS_DATABASE_DRIVER env var (explicit override)
      //   2. URL scheme inferred from OS_DATABASE_URL
      //        mongodb://, mongodb+srv://       → mongodb
      //        postgres://, postgresql://       → postgres
      //        mysql://, mysql2://              → mysql
      //        libsql://, http(s):// + .turso.  → turso
      //        wasm-sqlite://, *.wasm.db        → sqlite-wasm
      //        memory://, mingo://              → REFUSED (the retired in-memory engine)
      //        file:, sqlite:, *.db, :memory:   → sqlite (SQLite's own in-memory mode)
      //   3. Default: dev SQLite (native → wasm → in-memory step-down); prod none
      //
      // Kind-resolution and construction live in utils/storage-driver.ts so the
      // whole dispatch is unit-testable (storage-driver.test.ts). #3276: a
      // `memory` selection never falls through to the dev SQLite `:memory:`
      // default in silence — it used to build the mingo InMemoryDriver, and since
      // the engine's retirement as a boot store it is refused (fatal, below).
      // A DefaultDatasourcePlugin counts as a driver provider (#3826): the
      // standalone stack now DECLARES its `default` datasource and connects it
      // at boot through the datasource connection service, so building a
      // storage driver here would construct a duplicate pool the engine then
      // discards as already-registered.
      // [#15006] Same seam, same reason — see the ObjectQL gate above. The
      // driver-provider duck-typing moved into it with the read it guards.
      //
      // [#23573] Whether this step declared NOTHING (production, no URL, no
      // driver plugin by name). Only recorded here: this step cannot tell a
      // boot that fails anyway from one whose own plugin registers a driver
      // the name test misses, so the verdict waits for the no-storage boot
      // guard at the end of Phase 1 (registered last, before runtime.start()).
      let productionResolvedNoStorage = false;
      if (shouldAutoRegisterStorageDriver(config, plugins)) {
         const databaseUrl = process.env.OS_DATABASE_URL;
         const driverType = resolveDriverType(process.env.OS_DATABASE_DRIVER, databaseUrl);
         // libSQL/Turso's credential is the only one that does NOT ride inside the
         // URL (`--database-auth-token`, forwarded by `os start` / `os dev` as
         // OS_DATABASE_AUTH_TOKEN; TURSO_AUTH_TOKEN is the vendor's own name, kept
         // as-is per Prime Directive #9's third-party exceptions).
         const databaseAuthToken = process.env.OS_DATABASE_AUTH_TOKEN || process.env.TURSO_AUTH_TOKEN;

         try {
           // #3826: the fallback no longer constructs a driver — it declares
           // the `default` datasource and lets the runtime's
           // DefaultDatasourcePlugin connect it at boot through the shared
           // DatasourceConnectionService (one connect path, one failure
           // verdict incl. OS_ALLOW_DRIVER_CONNECT_FAILURE, retained status in
           // Setup → Datasources). URL→config translation stays host-side in
           // resolveStorageDefinition. The dev sqlite step-down (#2229) and
           // the loosen-only self-heal (#2186, via config.autoMigrate) now run
           // inside the factory at connect.
           const { DefaultDatasourcePlugin } = await import('@objectstack/runtime');
           const resolution = resolveStorageDefinition(driverType, { databaseUrl, isDev, authToken: databaseAuthToken });
           if (resolution) {
             // #5602: libSQL/Turso is the one kind the shared open-core factory
             // cannot build — `@objectstack/driver-turso` is an OPTIONAL peer, so
             // the CLI loads it here and injects it through the plugin's documented
             // host-factory seam. Everything else about the boot is unchanged: same
             // connect path, same bootCritical verdict, same escape hatch. A missing
             // package throws MissingDriverPackageError BEFORE the plugin exists, so
             // the operator sees the install command rather than a connect failure —
             // and never a silent SQLite fallback.
             const hostFactory = isTursoDriverId(resolution.driverId)
               ? await loadTursoDriverFactory()
               : undefined;
             await kernel.use(new DefaultDatasourcePlugin(
               { driver: resolution.driverId, config: resolution.config },
               { dev: isDev, ...(hostFactory ? { factory: hostFactory } : {}) },
             ));
             trackPlugin(resolution.trackName);
             resolvedDriverLabel = resolution.label;
             resolvedDatabaseUrl = resolution.displayUrl;
             servedSqliteFilePath = resolution.sqliteFilePath;

             // ADR-0057 §3.6 (#2834 ②): the dedicated `telemetry` datasource
             // next to an explicit SQLite primary (`sqliteFilePath`, unset for
             // every other kind AND the dev-default `:memory:` store). The ONE
             // provision, shared with the standalone boot below.
             await provisionTelemetry(resolution.sqliteFilePath);
           } else {
             productionResolvedNoStorage = true;
           }
         } catch (e: any) {
           // "declared ≠ enforced" guard (#3276-class): a selection the CLI
           // RECOGNIZED but cannot honour must fail LOUDLY, never silently fall
           // through to the SQLite default and ignore the engine that was asked for.
           // Re-throw so run()'s fatal handler restores output, prints the
           // actionable message, and exits 1 (in dev AND prod). All OTHER driver
           // construction errors keep the prior best-effort silent behavior.
           //   • UnsupportedDriverError — a selection with no usable definition
           //     (`--database-driver turso` with no URL to connect to, an unknown
           //     spelling, or the retired in-memory engine's spelling). The
           //     `memory://` / `mingo://` refusal is the same class, raised by
           //     `resolveDriverType` above this `try` and fatal the same way.
           //   • MissingDriverPackageError (#5602) — the optional driver package for
           //     a `libsql://` selection is not installed. Fatal for the same reason
           //     and with the same remedy shape: the message carries the exact
           //     install command, and there is deliberately no SQLite fallback.
           if (e instanceof UnsupportedDriverError) throw e;
           if (e instanceof MissingDriverPackageError) throw e;
           // Same class of fatal (#3724): a driver that refuses to run in this
           // deployment's tenancy mode — driver-mongodb has no row-level tenant
           // isolation and rejects a non-`single` posture. Swallowing it would
           // boot the server with NO driver at all, burying "your database
           // cannot isolate tenants" under a later, unrelated failure. Matched
           // by `code` (duck-typed) so the CLI keeps no dependency on the
           // driver package and cross-realm `instanceof` can't bite.
           if (e?.code === 'MONGODB_MULTI_TENANT_UNSUPPORTED') throw e;
           // silent
         }
      } else if (standaloneSqlitePrimary !== undefined) {
        // #21733 — the standalone stack's `default` datasource is a file-backed
        // SQLite database (resolved by the runtime's own pre-boot resolution in
        // the boot-mode dispatch above), so it gets the same sibling the
        // config-load fallback provisions, under the same rule.
        await provisionTelemetry(standaloneSqlitePrimary);
      }

      // 3. Auto-register AppPlugin if config contains app definitions
      // (objects / manifest / apps / flows / apis). Even host/aggregator
      // configs (those whose `plugins` array contains instantiated plugins)
      // need this wrap when they ALSO carry top-level metadata — otherwise
      // top-level `flows`, `objects`, etc. never reach the ObjectQL registry
      // and downstream services like AutomationServicePlugin start with 0 flows.
      // `examples/app-showcase` is the in-repo worked example of exactly that
      // shape: its `plugins[]` holds instantiated connector plugins while the
      // stack still declares top-level `objects` / `apps` / `flows` / `apis`
      // (`serve-host-config-security-registrar.pin.test.ts` records an `os dev`
      // boot of it).
      //
      // To avoid double-registration when the host already wraps itself with
      // an AppPlugin, we skip if any plugin in `plugins[]` is already an
      // AppPlugin instance. That branch keys on the SHAPE — a `plugins[]` that
      // already holds an AppPlugin instance — and never on a named app, so it
      // is checked structurally below.
      const hasAppPluginAlready = plugins.some(isAppPluginLike);
      // [#15006] The same predicate `schema-migration-plugins.ts` runs after its
      // own second `loadConfig` (B4) — folded into one seam rather than left as
      // two copies whose comment already said they were the same.
      const configHasMetadata = stackDeclaresMetadata(config);

      // ── Decide the dev-only artifact door BEFORE the wrap (commit 957f7bb45) ──
      // On a HOST config `os dev` composes TWO writers over ONE stack: the
      // `new AppPlugin(config)` wrap below, over the config MODULE, and the
      // dev-only HMR `MetadataPlugin` further down, over the compiled twin
      // (`dist/objectstack.json`) the `os dev` supervisor produced from that
      // same module. Measured on a real `os dev` boot of a host config: the
      // door loads the artifact first and the wrap's ADR-0057 block registers
      // last, so the WRAP's copy wins the cold boot — and the door's copy
      // replaces it on the first artifact reload, so the winner CHANGES
      // mid-run without a restart. ⚠️ The two copies differ by PROVENANCE and
      // by FRESHNESS, not by parsing: on a config boot `defineStack()` is
      // strict by default and runs the same `ObjectStackDefinitionSchema`
      // parse the door runs, so the wrap's copy already carries the schema
      // defaults and input transforms. What it lacks is the ADR-0010 stamp,
      // and it never refreshes while the door's copy reloads on every
      // recompile. Maintainer ruling (2026-08-29, #12892): the
      // door owns the registration route; two permanent writers with matched
      // shapes was refused as an end state. So the composition that runs the
      // door declares it, here, exactly as `createStandaloneStack` does for
      // the artifact boot.
      //
      // The door instance is CONSTRUCTED here rather than at its `kernel.use`
      // site so that ONE value decides both facts — the wrap's registrar and
      // the door's existence — instead of two expressions free to drift.
      // Declaring the option with no door composed would be strictly worse
      // than the divergence it removes: measured on `os serve` over the same
      // host config, a metadata service is present and this wrap is its ONLY
      // writer, so the four security collections would then have no registrar
      // at all — the silent hole #12892 measured on the artifact boot.
      //
      // `hasMetadataPlugin` is read here instead of at the `kernel.use` site
      // and the answer is identical: `plugins` is not mutated between the two
      // points except by the AppPlugin append below, and an AppPlugin is not a
      // MetadataPlugin.
      let devArtifactDoor: any;
      if (isDev && flags.server && !plugins.some((p: any) => p?.constructor?.name === 'MetadataPlugin')) {
        try {
          const { resolveDefaultArtifactPath } = await import('@objectstack/runtime');
          // `os dev` is the only caller that reaches here, and it is a
          // supervisor: read its channel, or the artifact this HMR watcher
          // polls would silently drift to `<cwd>/dist/objectstack.json`
          // whenever `os dev --artifact <elsewhere>` was used.
          const hmrArtifactPath = resolveDefaultArtifactPath(readInternalArtifactPath());
          // ⛔ RESOLVING IS NOT EXISTING, and the difference decides who
          // registers the four security collections. Under `os dev` the
          // supervisor writes its channel unconditionally, so
          // `readInternalArtifactPath()` always answers and
          // `resolveDefaultArtifactPath` hands an explicitly named path back
          // VERBATIM, with no existence check (packages/runtime/src/
          // default-host.ts — only the conventional `<cwd>/dist/…` fallback is
          // stat'ed). Compose a door over a path that is not there and it
          // starts EMPTY and SILENT by design: `MetadataPlugin`'s local-file
          // load is `{ optional: true }` and answers ENOENT with an `info`
          // line, registering nothing (packages/metadata/src/plugin.ts). The
          // wrap below would then have deferred to a door that never writes,
          // and `positions` / `permissions` / `capabilities` / `sharingRules`
          // would end the boot with ZERO registrars — green, quiet, and worse
          // than the divergence this whole block exists to remove. So the
          // door is composed only when its bytes are on disk NOW; a named but
          // missing artifact leaves the wrap as the single registrar, exactly
          // as before this decision existed.
          //
          // The trade this makes, stated rather than discovered later: on that
          // boot nothing reloads the named artifact if it later appears,
          // because the plugin that would watch it is the one not composed.
          // That is the right way round. The alternative — compose the door
          // anyway and only withhold the registrar — keeps a dev convenience by
          // re-creating the TWO-WRITER divergence this block exists to remove:
          // the watcher picks the artifact up if it later appears, and then
          // registers a second copy behind a wrap that already registered its
          // own. That boot still gets a `MetadataPlugin` — the host-config door
          // below (#22989), which names no artifact, so it watches and
          // registers none, and which mounts the dev HMR SSE endpoint under
          // `NODE_ENV=development` in this door's place. The reload is missing
          // only where `os dev` was pointed at an artifact that is not there
          // (`--artifact` skips auto-compile), and the warning below says so by
          // name.
          if (hmrArtifactPath && !/^https?:\/\//i.test(hmrArtifactPath)) {
            if (!fs.existsSync(hmrArtifactPath)) {
              console.warn(chalk.yellow(
                `  ⚠ Dev artifact reload not enabled: no compiled artifact at ${hmrArtifactPath}`
                + '\n    Stack-declared security metadata stays with the app wrap, its registrar on every'
                + '\n    boot without a door.',
              ));
            } else {
              const { MetadataPlugin } = await import('@objectstack/metadata');
              // Mirror the standalone stack's dev config exactly
              // (packages/runtime/src/standalone-stack.ts): declarative
              // metadata is loaded from the compiled artifact — no source-file
              // scanner (redundant + EMFILE-prone) — and `artifactWatch` polls
              // the single artifact file so an `os dev` recompile broadcasts a
              // reload over the SSE stream.
              devArtifactDoor = new MetadataPlugin({
                watch: false,
                artifactWatch: true,
                artifactSource: { mode: 'local-file', path: hmrArtifactPath },
              });
            }
          }
        } catch (e: any) {
          console.warn(chalk.yellow(`  ⚠ Dev metadata-HMR endpoint not enabled: ${e?.message}`));
        }
      }

      // ── The metadata door of a HOST config with no artifact door (#22989) ──
      // A host config never reaches `createStandaloneStack`, the composition
      // that gives every other config boot `@objectstack/metadata`'s
      // `MetadataPlugin`. So unless the dev artifact door above composed, its
      // `metadata` slot fell to the kernel's in-memory core fallback, which has
      // no `matchEndpoint`: every `apis` endpoint the stack declares answered
      // `404 ENDPOINT_NOT_FOUND` on `os serve` (and on `os start`, whose
      // `serve` child takes this branch), while `os dev` over the compiled twin
      // matched it. Maintainer ruling (#22989, option A): such a composition
      // gets a `MetadataPlugin` with NO `artifactSource`, so the slot is a
      // `MetadataManager` on both doors and the AppPlugin wrap's registration
      // fills its endpoint index.
      //
      // What this door does and does not do, measured on `examples/app-showcase`:
      //   • `bootstrap: 'lazy'` skips the filesystem priming pass the default
      //     `eager` mode runs when no artifact is named. The artifact door this
      //     mirrors loads its artifact and never runs that pass; with no
      //     artifact the pass would scan `rootDir/<type>/` and register a
      //     second, differently stamped copy of whatever it found beside the
      //     wrap's (it finds 0 items under the showcase).
      //   • `rootDir` is the served app's root (`hostRoot`), the root
      //     `createStandaloneStack` hands its own door as `projectRoot`, so the
      //     repository it attaches sits under the app, never under whatever
      //     directory the operator stood in. Attaching writes nothing at boot.
      //   • It registers NONE of the stack's metadata: with no artifact it
      //     reads nothing of it. The wrap below therefore stays the single
      //     registrar of `positions` / `permissions` / `capabilities` /
      //     `sharingRules`, and its `securityMetadataRegistrar` stays the
      //     default `'app-plugin'`. ⛔ Never `'artifact-door'` for this door:
      //     that would leave the four collections with no registrar at all.
      //   • A composition that already holds a `MetadataPlugin` (its own, or
      //     the dev door above) is left alone. A config that is not a host
      //     config got one from the standalone stack already.
      let hostConfigMetadataDoor: any;
      if (
        !devArtifactDoor
        && isHostConfig(config)
        && !plugins.some((p: any) => p?.name === 'com.objectstack.metadata' || p?.constructor?.name === 'MetadataPlugin')
      ) {
        const { MetadataPlugin } = await import('@objectstack/metadata');
        hostConfigMetadataDoor = new MetadataPlugin({
          watch: false,
          config: { bootstrap: 'lazy' },
          rootDir: hostRoot,
        });
      }
      // ORDERING (#4085 → #4131/ADR-0116): the wrap is APPENDED to `plugins`
      // rather than registered here — but the append is no longer what makes
      // the boot correct. AppPlugin now DECLARES its ordering contract
      // (`optionalDependencies: ['com.objectstack.engine.objectql']`,
      // `requiresServices: ['manifest']`), so the kernel hoists the engine
      // ahead of it in every slot, and a composition that genuinely lacks a
      // manifest provider fails as a named ordering error instead of the
      // mislabelled "Service 'manifest' is async - use await" crash #4085
      // produced. Appending is kept so both boot paths (config-derived wrap
      // here, `createStandaloneStack`'s own AppPlugin) share one plugin
      // order and one story in the boot logs.
      if (!hasAppPluginAlready && configHasMetadata) {
        try {
            const { AppPlugin } = await import('@objectstack/runtime');
            // The registrar is DECLARED by this composition, never inferred by
            // AppPlugin — see the `devArtifactDoor` block above. Default
            // (`'app-plugin'`) whenever no artifact door composes, which is
            // every non-dev boot of a host config — including every boot that
            // composes `hostConfigMetadataDoor`, which reads no artifact and
            // so registers none of the stack.
            plugins = [...plugins, new AppPlugin(
              config,
              undefined,
              devArtifactDoor ? { securityMetadataRegistrar: 'artifact-door' } : {},
            )];
        } catch (e: any) {
            // Non-fatal — the platform still boots, just without this app's
            // metadata. But it must SAY so: this catch was silent, and the two
            // things it swallows (a malformed envelope AppPlugin rejects by
            // construction, an unresolvable @objectstack/runtime) both leave a
            // server answering with zero objects and no stated reason — the
            // same class of invisible boot failure as #4085 itself.
            console.warn(chalk.yellow(
              `  ⚠ Skipped registering the app defined in this config: ${e?.message ?? e}\n`
              + '    Its objects/flows will NOT be served. Fix the config (or pin an AppPlugin in `plugins`).',
            ));
        }
      } else if (hasAppPluginAlready) {
        // #4095 — skipping the wrap above also discards the authored module's
        // CODE. On the config-boot path the bundle already in `plugins[]` came
        // from `createStandaloneStack()` reading `dist/objectstack.json`, and a
        // JSON artifact cannot carry a function: the app booted with every
        // `script` action DECLARED and no handler registered, so each one 404'd
        // at dispatch. Move the executable members onto that bundle (the
        // bundle's own value always wins, so a host that wrapped itself on
        // purpose is untouched) and say so out loud when they have nowhere to go
        // — that silent drop is what hid this.
        // Success is silent: on the config-boot path this is now the normal
        // route by which handlers reach the engine, and the observable proof is
        // that the actions dispatch.
        const graft = graftAuthoredRuntimeMembers(plugins, config);
        if (graft.orphaned.length > 0) {
          console.warn(chalk.yellow(
            `  ⚠ ${relativeConfig} exports ${graft.orphaned.join(' / ')} but no app bundle claimed `
            + `${graft.orphaned.length === 1 ? 'it' : 'them'}`
            + `${graft.reason === 'ambiguous-app-plugin'
              ? ' — several apps are registered and the config declares no manifest.id to match'
              : ' — no registered app bundle has a matching manifest.id'}`
            + '. Action handlers registered there will NOT be reachable (they 404 at dispatch).',
          ));
        }
      }

      // 3b. Auto-register I18nServicePlugin if config contains translations/i18n
      // This ensures i18n REST routes work out of the box without manual plugin registration.
      const hasI18nPlugin = plugins.some(
        (p: any) => p.name === 'com.objectstack.service.i18n'
            || p.constructor?.name === 'I18nServicePlugin'
      );
      // Check the top-level config AND any nested AppPlugin bundles in the
      // `plugins` array — a host/aggregator config may define no translations
      // of its own and instead compose several `new AppPlugin(...)` entries,
      // each carrying its own. Keyed on that shape, not on a named app.
      // [#15006] `bundleDeclaresTranslations` is that same shape-keyed check plus
      // the `packages[]` leg: `translations` is package-owned and `i18n` is an
      // envelope key a translations-only stack never sets, so an option-B artifact
      // reached this gate with neither and the REST i18n routes silently did not
      // exist. MEASURED on the acceptance probe, not inferred.
      const anyAppPluginHasTranslations = plugins.some((p: any) => {
        if (!p) return false;
        // AppPlugin instances expose their bundle on `.bundle`
        if (p.bundle && bundleDeclaresTranslations(p.bundle)) return true;
        return false;
      });
      const configHasTranslations = (
        bundleDeclaresTranslations(config)
        || anyAppPluginHasTranslations
      );
      if (!hasI18nPlugin && configHasTranslations && tierEnabled('i18n')) {
        // Dynamic import with variable to prevent tsc from resolving the optional package.
        // Host-anchored: `packages/cli` does NOT declare @objectstack/service-i18n,
        // so a bare import here resolves against the CLI's own realpath and can
        // only ever find the package by workspace hoisting — the same defect
        // class that cost cloud#1013 and #10645 (commit 3d7deb700). An app that does not
        // declare it still falls back to the CLI's resolution, so the quiet-skip
        // path below is unchanged.
        //
        // Declared OUTSIDE the `try` so the catch can NAME the package it is
        // reporting on: a diagnosis that cannot say which package it is about
        // is the thing this site was fixed to stop printing.
        const i18nPkg = '@objectstack/service-i18n';
        try {
          const { I18nServicePlugin } = await importFromHost(i18nPkg);
          const i18nCfg = config.i18n || config.manifest?.i18n || {};
          await kernel.use(new I18nServicePlugin({
            defaultLocale: i18nCfg.defaultLocale,
            fallbackLocale: i18nCfg.fallbackLocale || i18nCfg.defaultLocale || 'en',
          }));
          trackPlugin('I18nService');
        } catch (i18nErr) {
          // NOT a re-throw and never becomes one: a missing
          // @objectstack/service-i18n is a supported configuration (the kernel
          // pre-injects `createMemoryI18n` for the unprovided `i18n` core
          // service), so the tolerance stays and only the SILENCE goes. This
          // catch used to discard the classification `createHostImporter`
          // produced, which made "you did not install the optional package"
          // and "the package you DO declare is broken" the same event — the
          // #13463 class, repaired at the cluster-driver load two blocks up by
          // PR #14042 and left standing here.
          console.warn(formatI18nLoadDiagnostic(i18nPkg, i18nErr));
        }
      } else if (!hasI18nPlugin && !configHasTranslations) {
        // No translations and no explicit i18n plugin — this is fine, kernel fallback works
      }

      // ── Observability backends (#9832) ──────────────────────────────────
      // Auto-wire observability from env so production deployments can ship
      // metrics / errors to OTLP backends (Grafana Cloud, Honeycomb, …)
      // without app-level glue. Falls back to noop when OS_OBS_EXPORTER is
      // unset / unknown — zero-cost when off, and never crashes boot if
      // exporter init throws.
      //
      // Built EXACTLY ONCE per serve process, and this is the only call site.
      // The dispatcher block further down reads THIS binding rather than
      // calling again: a second `buildServeObservability()` would construct a
      // SECOND exporter — for `OS_OBS_EXPORTER=otlp` two
      // `OtlpHttpMetricsRegistry` instances with two independent flush timers,
      // double-exporting every series to the same backend.
      //
      // Registered as a SERVICE here — ahead of the transport (immediately
      // below), the dispatcher, and the capability providers (cache, storage)
      // — because every consumer resolves the canonical chain (explicit
      // option → `observability:metrics` service → nothing) inside its OWN
      // `init()`, and the kernel runs all of Phase 1 in resolved order with
      // registration order preserved between plugins that have no edge
      // (`resolvePluginOrder`). Registering after a consumer is registering
      // too late: that consumer has already fallen through to its no-op and
      // will never look again. This is exactly what `ObservabilityServicePlugin`'s
      // own JSDoc tells hosts to do ("Register this plugin BEFORE any plugin
      // that wants to consume the services").
      //
      // Deliberately NOT gated on `flags.server`: cache and storage are
      // registered on the `--no-server` path too, and their metrics are just
      // as real there.
      //
      // Registered ONLY when a backend is actually configured. An all-noop
      // registration would still be truthy at every consumer's step 2 and
      // would arm the transport's per-request middleware seam on deployments
      // that export nothing — the per-request cost #9650 deliberately kept off
      // an unconfigured deployment.
      const observability = await buildServeObservability();
      // Skip if the config already mounts its own — `ctx.registerService`
      // throws on a duplicate name, which would turn a host that wired its own
      // backends into a boot failure.
      const configHasObservabilityService = plugins.some(
        (p: any) => p.name === 'com.objectstack.observability.service'
            || p.constructor?.name === 'ObservabilityServicePlugin'
      );
      if (observability && !configHasObservabilityService) {
        try {
          const { ObservabilityServicePlugin } = await import('@objectstack/runtime');
          await kernel.use(new ObservabilityServicePlugin({
            metrics: observability.metrics,
            errors: observability.errorReporter,
          }));
          trackPlugin('ObservabilityService');
        } catch {
          // @objectstack/runtime unavailable — every consumer keeps its no-op
          // default, exactly as before this block existed.
        }
      }

      // Add HTTP server plugin BEFORE config plugins so that the
      // http-server service is available for any plugin that needs it
      // during init/start (e.g. AuthPlugin).
      // Skip if config already contains a HonoServerPlugin to avoid
      // duplicate registration.
      const configHasHonoServer = plugins.some(
        (p: any) => p.name === 'com.objectstack.server.hono' || p.constructor?.name === 'HonoServerPlugin'
      );

      if (flags.server && !configHasHonoServer) {
        try {
          const { HonoServerPlugin } = await import('@objectstack/plugin-hono-server');
          // `tls` is `undefined` unless --cert/--key were both given and both
          // files read (#16804) — the adapter then binds a TLS listener with
          // the same fetch handler. ⛔ Nothing here generates a certificate.
          const serverPlugin = new HonoServerPlugin({
            port,
            tls: tlsMaterial ? { cert: tlsMaterial.cert, key: tlsMaterial.key } : undefined,
          });
          await kernel.use(serverPlugin);
          trackPlugin('HonoServer');
        } catch (e: any) {
          console.warn(chalk.yellow(`  ⚠ HTTP server plugin not available: ${e.message}`));
        }
      }

      // ── Dev-only: metadata HMR SSE endpoint for host/aggregator configs ──
      //
      // Host configs (their `plugins[]` holds instantiated Plugin objects) skip
      // the standalone stack — see `shouldBootWithLibrary()`. That stack is
      // where every other config gets `@objectstack/metadata`'s MetadataPlugin,
      // and MetadataPlugin is what registers `GET /api/v1/dev/metadata-events`
      // in its start(). So when serving a host config with no door the
      // Console's dev metadata-HMR reloader hit a 404 and the page never
      // auto-reloaded after a recompile. (A host config with no artifact door
      // now gets the artifact-less `hostConfigMetadataDoor` instead, #22989,
      // which mounts the same endpoint under development and reloads nothing.)
      //
      // Compose a lightweight, artifact-sourced MetadataPlugin here so the
      // endpoint exists regardless of boot shape. Guards:
      //   • `isDev` only — production / cloud host deployments are untouched.
      //   • `flags.server` — pointless without an HTTP server to mount it on.
      //   • skipped when a MetadataPlugin is already present (the standalone /
      //     artifact-fallback paths compose their own upstream).
      //   • skipped when no local compiled artifact resolves to source from.
      // Registered AFTER the HonoServer plugin so the `http-server` service
      // (and its `getRawApp()`) is available when MetadataPlugin.start() mounts
      // the route.
      //
      // The instance was resolved and constructed next to the AppPlugin wrap
      // (search `devArtifactDoor`) because the wrap's
      // `securityMetadataRegistrar` has to be decided from the SAME value;
      // only the `kernel.use` stays here, where the ordering requirement is.
      // The catch is the pre-existing one and keeps its pre-existing message.
      // ⛔ It is deliberately NOT the place to warn that the four security
      // collections went unregistered: `Kernel.use` only validates the plugin
      // and registers it by name (packages/core/src/kernel.ts) — `init` and
      // `start` run later, in `bootstrap` — so for a MetadataPlugin that was
      // constructed successfully a few hundred lines above, on a kernel still
      // `idle`, this path does not fire. The registrar hand-off is decided by
      // whether `devArtifactDoor` exists at all, and the case that genuinely
      // loses a door — a named artifact that is not on disk — warns at the
      // construction site, where the missing path can be named.
      if (devArtifactDoor) {
        try {
          await kernel.use(devArtifactDoor);
          trackPlugin('Metadata');
        } catch (e: any) {
          console.warn(chalk.yellow(`  ⚠ Dev metadata-HMR endpoint not enabled: ${e?.message}`));
        }
      }
      // [#22989] The host-config door with no artifact, at the same site and
      // for the same ordering reason; it exists only when `devArtifactDoor`
      // does not, so a boot composes at most one of the two. No catch: this
      // door is the `metadata` slot's occupant, and a boot that cannot compose
      // it must fail, not fall back to the matcher-less core fallback quietly.
      if (hostConfigMetadataDoor) {
        await kernel.use(hostConfigMetadataDoor);
        trackPlugin('Metadata');
      }

      // Serve /runtime/assets/* unconditionally — branding logos, favicons,
      // and other static runtime assets must resolve even when the Console
      // dist hasn't been built yet.  The directory is resolved as:
      //   1. OS_RUNTIME_ASSETS_DIR env var (explicit override)
      //   2. process.cwd() + '/assets' (when CLI cwd is a runtime/ package)
      // No route is mounted when the directory does not exist. That is not
      // silent (#22071): once the boot settles, the plugin warns for every
      // loaded app's branding logo / favicon under /runtime/assets/ it will not
      // serve, naming the directory searched and which of the two it came from.
      const runtimeAssetsDirFromEnv = process.env.OS_RUNTIME_ASSETS_DIR?.trim();
      const runtimeAssetsDir = runtimeAssetsDirFromEnv || path.resolve(process.cwd(), 'assets');
      await kernel.use(createRuntimeAssetsPlugin(
        runtimeAssetsDir,
        runtimeAssetsDirFromEnv ? 'OS_RUNTIME_ASSETS_DIR' : 'cwd',
      ));

      // Unknown-environment hostname guard.
      //
      // Activation only: everything the guard decides, and why, lives on
      // `createUnknownHostnameGuardPlugin()` below — exported (#9442) so the
      // middleware, bypass matrix and refusal alike, is reachable from a test
      // without booting a real `os serve`.
      //
      // Activated only when OS_ROOT_DOMAIN is set (e.g. "objectos.ai"); with no
      // root domain there is no platform-host namespace to guard, so nothing is
      // installed and every hostname passes through as before.
      const __rootDomain = (process.env.OS_ROOT_DOMAIN || '').trim().toLowerCase();
      if (__rootDomain) {
        const guardPlugin: any = createUnknownHostnameGuardPlugin({ rootDomain: __rootDomain });
        try {
          await kernel.use(guardPlugin);
          trackPlugin('UnknownHostnameGuard');
        } catch {
          // Best-effort.
        }
      }

      // 5. Marketplace browse/install + runtime-config — auto-wired from the
      // open `@objectstack/cloud-connection` package, gated on a resolved
      // cloud URL.
      //
      // History: ADR-0006 Phase 4 deleted the framework's DUPLICATE copies
      // (which lived in `@objectstack/runtime`) because the canonical
      // implementation then lived in the cloud distribution. ADR-0008 then
      // open-sourced that client surface into `@objectstack/cloud-connection`
      // (Apache-2.0, framework-side), so the CLI can wire it again WITHOUT
      // crossing the open-core boundary — there is no longer a cloud-only
      // copy to duplicate. This restores marketplace for `objectstack start`
      // empty-boot, which advertises "boot an empty kernel against your
      // marketplace" but, with no config/artifact, has no host to carry the
      // wiring (the only place it can come from is the CLI itself).
      //
      // Mirrors the objectos-ee single-env host wiring: the CLOUD-DEPENDENT
      // surfaces (proxy + cloud-connection + runtime-config) only when
      // `resolveCloudUrl()` is truthy. Each plugin self-registers its own
      // Setup nav bundle in start(), so no manual bundle registration is
      // needed here.
      //
      // install-local is DELIBERATELY NOT on that gate (#8343). It is the
      // documented air-gapped path — `os package install ./dist/objectstack.json`
      // hands the compiled artifact over inline, and `handleInstall`'s inline
      // branch never reads `this.cloudUrl` at all — so gating it on a control
      // plane withheld it from the one deployment that cannot have one. A
      // self-hosted EE box could not install a package by ANY route: measured
      // on objectos-ee 4.0.5-rc.1, both GET and POST /marketplace/install-local
      // 404, while its own /runtime/config advertised `installLocal: true`.
      // Note `off` is not an unusual choice there but the SHIPPED DEFAULT --
      // that image's compose file reads `OS_CLOUD_URL: ${OS_CLOUD_URL:-off}`,
      // so every self-hosted stack that does not override it landed here.
      // The package README states the intended contract in as many words —
      // "`OS_CLOUD_URL=off` disables every remote call; air-gapped installs
      // keep working via inline manifests handed to `install-local`" — so the
      // gate contradicted the contract rather than expressing it.
      //
      // What "preserving the vanilla marketplace-less `objectstack dev`" is
      // worth here, measured rather than assumed: a plain `objectstack dev`
      // sets NO OS_CLOUD_URL, and `resolveCloudUrl()` then returns
      // DEFAULT_CLOUD_URL — truthy — so it already mounts install-local (and
      // its "Installed Apps" nav) today. The only runs this changes are those
      // that explicitly opted out (`off`/`none`/`local`/`disabled`), and for
      // them the nav-ownership rule in marketplace-ui.ts ("the entry lives and
      // dies with the capability -> no dead page") is SATISFIED, not violated:
      // the entry now appears exactly when a working offline install surface
      // is behind it. Nothing that makes a remote call mounts under `off`.
      //
      // SKIPPED in runtime/host-kernel mode: the cloud distribution
      // (objectos-stack) wires its own MarketplaceProxyPlugin on the host
      // kernel, so auto-wiring here would double-mount. Detect runtime mode by
      // ObjectOSEnvironmentPlugin (same signal the AuthPlugin guard below
      // uses); OS_CLOUD_URL alone is NOT a reliable signal -- a regular
      // `objectstack dev` app sets it precisely to enable the marketplace.
      const isRuntimeHostKernel = plugins.some(
        (p: any) => p?.name === 'com.objectstack.runtime.objectos-environment'
          || p?.constructor?.name === 'ObjectOSEnvironmentPlugin'
      );
      if (!isRuntimeHostKernel) {
        try {
          const ccPkg = '@objectstack/cloud-connection';
          const {
            MarketplaceProxyPlugin,
            MarketplaceInstallLocalPlugin,
            RuntimeConfigPlugin,
            createCloudConnectionPlugin,
            resolveCloudUrl,
          } = await import(/* webpackIgnore: true */ ccPkg);
          const marketplaceUrl = resolveCloudUrl();
          const wiring = Serve.planMarketplaceWiring({ isRuntimeHostKernel, marketplaceUrl, plugins });
          if (wiring.cloudSurfaces) {
            // Every mount here is guarded on what the HOST already wired
            // (#8357), the same rule and the same idiom the offline arm below
            // uses. `kernel.use` keys by name, so an unguarded mount is not a
            // harmless double-mount: one of the two instances is discarded,
            // and WHICH one depends on registration order rather than on any
            // stated rule. The host composed its instance deliberately, with
            // arguments the CLI cannot reconstruct from `resolveCloudUrl()`
            // alone — a distinct control plane, a custom install storageDir, a
            // credential path, cache tuning — so the host's is the one that
            // must stand. See `planMarketplaceWiring` for the measurement.
            let mountedAny = false;
            if (wiring.cloudProxy) {
              await kernel.use(new MarketplaceProxyPlugin({ controlPlaneUrl: marketplaceUrl }));
              mountedAny = true;
            }
            if (wiring.cloudInstallLocal) {
              await kernel.use(new MarketplaceInstallLocalPlugin({ controlPlaneUrl: marketplaceUrl }));
              mountedAny = true;
            }
            // Same-origin /cloud-connection/* surface (status + device-code
            // bind + control-plane catalog views) in single-environment mode.
            if (wiring.cloudConnection) {
              await kernel.use(createCloudConnectionPlugin({ singleEnvironment: true, controlPlaneUrl: marketplaceUrl }));
              mountedAny = true;
            }
            // Server-pushed runtime config so the Console knows marketplace +
            // install-local are live (same-origin; install into THIS kernel).
            if (wiring.cloudRuntimeConfig) {
              await kernel.use(new RuntimeConfigPlugin({ ...Serve.RUNTIME_CONFIG_OPTIONS }));
              mountedAny = true;
            }
            // Report the banner line only when this block actually mounted
            // something. A host that wires the whole set gets no entry from
            // here — it will report its own plugins through the config-plugin
            // loader — and an unconditional `trackPlugin` would otherwise
            // credit the CLI with a mount it did not make.
            if (mountedAny) trackPlugin('Marketplace');
          } else if (wiring.offlineInstallLocal || wiring.offlineRuntimeConfig) {
            // Cloud explicitly disabled -> mount the OFFLINE surfaces only:
            // the install route, and the runtime config that makes it
            // discoverable. Neither dials out. Each is mounted under its own
            // flag, because a host may already provide one and not the other.
            //
            // OFFLINE_CONTROL_PLANE, never the `''` sitting in `marketplaceUrl`:
            // the plugin re-resolves whatever it is handed through
            // `resolveCloudUrl()`, which treats an EMPTY string as "unset" and
            // falls back to the PUBLIC DEFAULT_CLOUD_URL — pointing an
            // air-gapped runtime's catalog branch at cloud.objectos.ai, the
            // opposite of what `off` asked for. See the constant's own note.
            //
            // The presence check is load-bearing, not defensive: `kernel.use`
            // keys plugins by name, so mounting unconditionally would let this
            // `off`-pinned instance REPLACE a host config's own install-local
            // that was constructed with an explicit control-plane URL —
            // silently downgrading that host's catalog capability. A host that
            // wires its own keeps it.
            if (wiring.offlineInstallLocal) {
              await kernel.use(new MarketplaceInstallLocalPlugin({ controlPlaneUrl: Serve.OFFLINE_CONTROL_PLANE }));
              trackPlugin('MarketplaceInstallLocal');
            }
            // ...and the runtime config that lets the Console SEE it (#8389).
            //
            // Without this, #8343's fix left an air-gapped box in a state that
            // reads as "feature missing" from every UI: a working
            // /api/v1/marketplace/install-local route and NO
            // /api/v1/runtime/config at all, so the SPA cannot learn the route
            // exists and renders no install affordance for a capability that
            // works. Discovery is half of shipping the capability.
            //
            // #8343 could not mount this here: the plugin hardcoded
            // `features.marketplace: true`, so telling the Console the truth
            // about install-local meant asserting a browse capability that is
            // definitively absent on this runtime — trading the reported bug
            // for its mirror image. #8356 removed that constraint by deriving
            // the flag from the serving app's route table, so this mount now
            // reports `installLocal: true` AND `marketplace: false` on its own,
            // with no knob and nothing for the wiring to keep in step.
            //
            // Guarded for the same reason the install-local mount above is:
            // `kernel.use` keys by name, so an unconditional mount REPLACES a
            // host's own RuntimeConfigPlugin — silently dropping the branding
            // and the resolveFeatures policy it was constructed with. A host
            // that wires its own keeps it.
            if (wiring.offlineRuntimeConfig) {
              await kernel.use(new RuntimeConfigPlugin({ ...Serve.RUNTIME_CONFIG_OPTIONS }));
              trackPlugin('RuntimeConfig');
            }
          }
        } catch (err: any) {
          console.warn(chalk.yellow(`  \u26a0 Marketplace/cloud-connection wiring failed: ${err?.message ?? err}`));
        }
      }

      // 5c. Auto-register PlatformObjectsPlugin. It carries platform
      // infrastructure every served kernel needs: the `sys_migration`
      // data-migration flag ledger + fresh-datastore attestation (#4243 —
      // without it the engine's deployment gates read "no ledger" and fall
      // back to the lax legacy posture), the `sys_secret` cipher store
      // (#4270 — the engine's secret-field write path and the datasource
      // credential binder fail CLOSED without it; the crypto wiring below
      // assumes the table exists), and the platform-default
      // translation bundles (Setup App + metadata-type configuration
      // forms). Without the latter, Setup nav labels and metadata-admin
      // form labels fall back to English literals even when
      // Accept-Language requests another locale.
      const hasPlatformObjectsPlugin = plugins.some(
        (p: any) => p?.name === 'com.objectstack.platform-objects'
          || p?.constructor?.name === 'PlatformObjectsPlugin'
      );
      if (!hasPlatformObjectsPlugin) {
        try {
          const platformPkg = '@objectstack/platform-objects/plugin';
          const { PlatformObjectsPlugin } = await import(/* webpackIgnore: true */ platformPkg);
          await kernel.use(new PlatformObjectsPlugin());
          trackPlugin('PlatformObjects');
        } catch (err: any) {
          console.warn(chalk.yellow(`  ⚠ PlatformObjectsPlugin auto-inject failed: ${err?.message ?? err}`));
        }
      }

      // 5c-bis. [#21498] Auto-register MigrationRecoveryPlugin beside the
      // journal it reads. PlatformObjectsPlugin registers
      // `sys_migration_journal` on every served kernel because ADR-0119 D2
      // requires recovery to be discoverable "with zero host wiring"; this is
      // the half that discovers. Its `kernel:ready` scan reports every run
      // that started and never concluded, naming `os migrate resume --run …`,
      // and its `migration-plans` registry is where a plan's owner hands the
      // plan over so the scan can say the run IS resumable. On a database with
      // no interrupted run the scan prints nothing.
      //
      // Guarded like the block above: a host config that composes its own
      // instance keeps it, and the kernel never holds two registries.
      const hasMigrationRecoveryPlugin = plugins.some(
        (p: any) => p?.name === 'com.objectstack.migration-recovery'
          || p?.constructor?.name === 'MigrationRecoveryPlugin'
      );
      if (!hasMigrationRecoveryPlugin) {
        try {
          const { MigrationRecoveryPlugin } = await import('@objectstack/runtime');
          await kernel.use(new MigrationRecoveryPlugin());
          trackPlugin('MigrationRecovery');
        } catch (err: any) {
          console.warn(chalk.yellow(`  ⚠ MigrationRecoveryPlugin auto-inject failed: ${err?.message ?? err}`));
        }
      }

      // 5c-ter. [ADR-0131 D10 item 5] The v18 boot refusal, beside the
      // recovery scan: it refuses to start a database still in the v17
      // organization-ownership shape whose ceremony marker is not verified,
      // or one whose ceremony ran and did not verify, naming `os migrate
      // organization-ownership`. It judges in its own `start()`, right after
      // the engine's (the additive schema sync the ceremony waits for), and
      // ahead of every plugin that writes rows at start — so a refused boot
      // writes none. Composed HERE, before the auth family and the app
      // plugins (which also declare it in `optionalDependencies`), on served
      // kernels only —
      // ⛔ never in `createStandaloneStack`, which every CLI data and schema
      // boot shares, the ceremony's own boot among them. A host that composes
      // its own instance keeps it; a guard that cannot be composed fails the
      // boot rather than leave the database unjudged (no escape hatch, D10).
      const hasOrganizationOwnershipGuard = plugins.some(
        (p: any) => p?.name === 'com.objectstack.organization-ownership-boot-guard'
          || p?.constructor?.name === 'OrganizationOwnershipBootGuardPlugin'
      );
      if (!hasOrganizationOwnershipGuard) {
        const { OrganizationOwnershipBootGuardPlugin } = await import('@objectstack/runtime');
        // A development boot's refusal names the ceremony with `--dev`, so the
        // ceremony boots the way this one did (its secret, .env* files and
        // `telemetry` sibling).
        await kernel.use(new OrganizationOwnershipBootGuardPlugin({ dev: isDev }));
        trackPlugin('OrganizationOwnershipBootGuard');
      }

      // 5d. Auto-register AuthPlugin (and paired Security/Audit) when the
      // 'auth' tier is enabled and no auth plugin is already configured.
      // The Console expects /api/v1/auth/* to be served by better-auth via
      // @objectstack/plugin-auth. Without this block, running
      // `objectstack dev` on a vanilla user stack would 404 on
      // login/register flows.
      //
      // [#22371] WHETHER this block composes is ONE rule,
      // `resolvePlatformAuthComposition` (`@objectstack/core`), which
      // `os migrate security-catalog-overlays` asks too: the security plugin
      // paired below declares its shipped permission sets on its manifest, so
      // this gate decides which names the cold boot's catalog check holds
      // against the environment. The gate, in order: the stack mounts no
      // AuthPlugin of its own, the `auth` tier is on, the composition is not a
      // host kernel, and an auth secret resolves. The first two skip this block
      // silently — the `if` below asks them through the rule's own predicate
      // and tier set — and the last two are reported inside it, as before; HOW
      // the plugins are constructed stays this command's.
      const hasAuthPlugin = stackSuppliesAuthPlugin(plugins);
      const authComposition = resolvePlatformAuthComposition({
        plugins,
        tiers,
        // In dev, the rule falls back to a stable local secret so users don't
        // have to set OS_AUTH_SECRET just to try the login/register flow.
        secret: resolveAuthSecret({ isDev }),
      });
      if (!hasAuthPlugin && tierEnabled('auth')) {
        try {
          const authPkg = '@objectstack/plugin-auth';
          const { AuthPlugin } = await import(/* webpackIgnore: true */ authPkg);

          // Guard: in cloud-connected runtime mode (e.g. objectos worker)
          // the host kernel is a pure routing shell. Auth is owned by each
          // per-project kernel (`ArtifactKernelFactory` injects an
          // `AuthPlugin` per project against the project's own DB so users
          // persist and stay isolated per subdomain). Injecting a host-level
          // AuthPlugin here would compete with the per-project one — its
          // shared OS_AUTH_SECRET would erroneously validate cookies across
          // unrelated projects. Refuse to inject in runtime mode.
          //
          // Detect runtime mode by the presence of ObjectOSEnvironmentPlugin
          // (added by createObjectOSStack). OS_CLOUD_URL alone is NOT a
          // reliable signal — a regular `objectstack dev` app may set it
          // just to enable the marketplace proxy yet still want its own
          // local AuthPlugin.
          if (!authComposition.composes && authComposition.reason === 'host-kernel') {
            console.warn(chalk.yellow(
              '  ⚠ AuthPlugin skipped on host kernel — runtime mode (ObjectOSEnvironmentPlugin detected).\n' +
              '    Auth is owned per-project by ArtifactKernelFactory in the cloud distribution.'
            ));
          } else if (!authComposition.composes) {
            console.warn(chalk.yellow('  ⚠ AuthPlugin skipped — set OS_AUTH_SECRET to enable authentication in production'));
          } else {
            const secret = authComposition.secret;
            // Resolution is UNCHANGED (same chain, same precedence) — the seam
            // additionally reports where the value came from and whether it
            // parses, so an unusable one can be said out loud instead of
            // vanishing into an empty catch (#10202).
            const baseUrlResolution = resolveAuthBaseUrl(port, boundProtocol);
            const baseUrl = baseUrlResolution.value;

            const socialProviders: Record<string, { clientId: string; clientSecret: string }> = {};
            if (process.env.GOOGLE_CLIENT_ID && process.env.GOOGLE_CLIENT_SECRET)
              socialProviders.google = { clientId: process.env.GOOGLE_CLIENT_ID, clientSecret: process.env.GOOGLE_CLIENT_SECRET };
            if (process.env.GITHUB_CLIENT_ID && process.env.GITHUB_CLIENT_SECRET)
              socialProviders.github = { clientId: process.env.GITHUB_CLIENT_ID, clientSecret: process.env.GITHUB_CLIENT_SECRET };

            // Trusted origins (CSRF). better-auth uses a `*` glob that
            // does NOT cross dot-separators, so `http://localhost:*` does
            // not cover `http://<sub>.localhost:*`. Build the allow-list
            // explicitly:
            //   - explicit `OS_TRUSTED_ORIGINS` (comma-separated) wins
            //   - else dev / preview defaults below
            const trustedOrigins: string[] = [];
            const explicitTrusted = process.env.OS_TRUSTED_ORIGINS?.trim();
            if (explicitTrusted) {
              explicitTrusted.split(',').map(s => s.trim()).filter(Boolean).forEach(o => {
                if (!trustedOrigins.includes(o)) trustedOrigins.push(o);
              });
            }
            // Always add the configured baseUrl so first-party redirects work.
            // An unusable value is NOT silently dropped (#10202): the catch that
            // used to stand here was the only witness that the configured base
            // URL could not be parsed, and it discarded that witness. Boot then
            // continued with this deployment's own origin missing from the CSRF
            // allow-list, health/ready still answering 200, and the operator's
            // first news of it a browser-side 403 INVALID_ORIGIN naming nothing.
            const unusableBaseUrlDiagnostic = formatUnusableAuthBaseUrlDiagnostic(baseUrlResolution);
            if (baseUrlResolution.baseOrigin !== null) {
              if (!trustedOrigins.includes(baseUrlResolution.baseOrigin)) {
                trustedOrigins.push(baseUrlResolution.baseOrigin);
              }
            } else if (unusableBaseUrlDiagnostic) {
              console.warn(chalk.yellow(unusableBaseUrlDiagnostic));
            }
            // Preview-mode subdomain wildcards (`<commit>--<pid>.<base>`).
            // Honour `OS_PREVIEW_BASE_DOMAINS` (used by the cloud preview routing)
            // and add `http://*.<base>:*` patterns.
            const previewMode = (process.env.OS_PREVIEW_MODE ?? '').trim().toLowerCase();
            const isPreviewMode = previewMode === '1' || previewMode === 'true' || previewMode === 'yes';
            if (isPreviewMode) {
              const baseDomains = (process.env.OS_PREVIEW_BASE_DOMAINS
                ?? 'preview.objectstack.ai,localhost')
                .split(',').map(s => s.trim()).filter(Boolean);
              for (const dom of baseDomains) {
                const isLoopback = dom === 'localhost' || dom.endsWith('.localhost');
                const scheme = isLoopback ? 'http' : 'https';
                const portSuffix = isLoopback ? ':*' : '';
                const wildcard = `${scheme}://*.${dom}${portSuffix}`;
                if (!trustedOrigins.includes(wildcard)) trustedOrigins.push(wildcard);
              }
            }
            // Dev convenience: keep `http://localhost:*` so plain
            // `localhost:<port>` still works for non-preview Console.
            if (isDev && !trustedOrigins.includes('http://localhost:*')) {
              trustedOrigins.push('http://localhost:*');
            }
            // Per-project subdomains: when OS_ROOT_DOMAIN is set (multi-
            // project hosting under `*.<root>`), every project hostname
            // must be trusted by better-auth or sign-up/sign-in is
            // rejected with "Invalid origin". Mirrors the OS_COOKIE_DOMAIN
            // wildcard semantics — they are always set together.
            const rootDomain = readEnvWithDeprecation('OS_ROOT_DOMAIN', 'ROOT_DOMAIN', { silent: true })?.trim();
            if (rootDomain) {
              const wildcard = `https://*.${rootDomain}`;
              if (!trustedOrigins.includes(wildcard)) trustedOrigins.push(wildcard);
            }

            // [ADR-0108 / #3723] Nothing to wire: the organization-role
            // vocabulary is closed (owner/admin/delegated_admin/member). A
            // stack's declared `position` / `permission` names are NOT org
            // roles — they are positions, assigned through `sys_user_position`
            // or an invitation carrying placement (ADR-0105 D8).
            await kernel.use(new AuthPlugin({
              secret,
              baseUrl,
              // The deployment's product name, from the resolver the email
              // capability's template context uses: the auth emails'
              // `{{appName}}` and the TOTP issuer. Unpassed, auth answered
              // 'ObjectStack' whatever `OS_APP_NAME` said.
              appName: resolveDeploymentAppName((config as any).email ?? {}, process.env, (config as any).appName),
              socialProviders: Object.keys(socialProviders).length > 0 ? socialProviders : undefined,
              trustedOrigins: trustedOrigins.length ? trustedOrigins : undefined,
              // The stack's `server.trustProxy`, the same authored value the
              // dispatcher's inbound rate limiter receives below: whether the
              // ADR-0069 D5 IP allow-list and the D7 login audit may believe
              // X-Forwarded-For / X-Real-IP when establishing a client address.
              // Undeclared, both judge the transport's peer address.
              trustProxy: (config as any).server?.trustProxy === true,
              // Enable the admin plugin by default so the Setup app's
              // ban/unban/set-password/impersonate/set-role row actions
              // resolve to real endpoints. The plugin self-gates by role
              // (only users whose `role` column is `admin` can hit
              // /admin/* endpoints), so leaving it on for everyone is
              // safe. Opt-out via OS_AUTH_ADMIN=false.
              //
              // twoFactor stays opt-in until the Console login UI ships the
              // complete TOTP challenge flow. Enabling only the backend plugin
              // lets users enroll but can leave them unable to finish login.
              //
              // (api-key plugin: not yet shipped by better-auth — generic
              // CRUD on `sys_api_key` handles row creation in the meantime.)
              plugins: {
                admin: String(process.env.OS_AUTH_ADMIN ?? 'true').toLowerCase() !== 'false',
                twoFactor: String(process.env.OS_AUTH_TWO_FACTOR ?? 'false').toLowerCase() === 'true',
                // ADR-0069 D1: reject breached passwords (Have I Been Pwned).
                // Opt-in; the auth Settings toggle (password_reject_breached) is
                // the primary control, OS_AUTH_PASSWORD_REJECT_BREACHED the
                // operator override (env wins in buildPluginList()).
                passwordRejectBreached:
                  String(process.env.OS_AUTH_PASSWORD_REJECT_BREACHED ?? 'false').toLowerCase() === 'true',
                // #2766/#2780 — phone-number sign-in (phone+password always;
                // OTP sign-in/reset once the sms capability has a deliverable
                // provider). Opt-in: without this env the config flag had no
                // `objectstack serve` switch at all.
                phoneNumber:
                  String(process.env.OS_AUTH_PHONE_NUMBER_ENABLED ?? 'false').toLowerCase() === 'true',
              },
              advanced: process.env.OS_COOKIE_DOMAIN
                ? ({
                    crossSubDomainCookies: {
                      enabled: true,
                      domain: process.env.OS_COOKIE_DOMAIN,
                    },
                  } as any)
                : undefined,
              // One default record page per object per deployment (ruling A on
              // objectstack#23015). When the app this boot serves declares its
              // own `sys_organization` default record page, the deployment is
              // composed without plugin-auth's; otherwise plugin-auth's page
              // registers as before. One yes/no on the app's own declaration,
              // the predicate `DevPlugin` asks too — no ordering, no
              // precedence, and no second switch for the author to keep in step.
              registerOrganizationRecordPage: !stackDeclaresOrganizationRecordPage(config, plugins),
            }));
            trackPlugin('Auth');

            // ADR-0048 — the platform apps (Setup/Account) moved out of
            // plugin-auth's manifest into their own one-app packages. Register
            // each after AuthPlugin (best-effort; skipped if not installed).
            // NOTE: @objectstack/studio is intentionally NOT default-loaded — the
            // console ships a dedicated Studio surface at /_console/studio/<pkg>/<pillar>,
            // so Studio no longer needs to exist as a navigable app tile.
            for (const [appPkg, factory] of [
              ['@objectstack/setup', 'createSetupAppPlugin'],
              ['@objectstack/account', 'createAccountAppPlugin'],
            ] as const) {
              try {
                const appMod: any = await import(/* webpackIgnore: true */ appPkg);
                await kernel.use(appMod[factory]());
                trackPlugin(appPkg);
              } catch {
                // best-effort — the app package is optional
              }
            }

            // Pair: OrganizationsPlugin (multi-org) — must register BEFORE
            // SecurityPlugin. The multi-org runtime (`organization_id`
            // auto-stamp, per-org seed replay, multi-org default-org bootstrap)
            // lives in the `@objectstack/organizations` package (ADR-0105 D12
            // as amended by ADR-0132; it registers the historical `org-scoping`
            // service SecurityPlugin probes at start() to keep vs strip the
            // wildcard `tenant_isolation` RLS — so registration order matters).
            // Without it, deployments are single-org: the open member-management
            // basics (plugin-auth's default-org bootstrap + better-auth
            // invitations) still work.
            // ⚠️ ONE NAME, TWO PACKAGES (ADR-0132 D3): the framework publishes
            // an Apache-2.0 package of that name (`packages/plugins/organizations`),
            // and a commercial deployment resolves the same name to a private,
            // licence-gated subclass of it through its own `workspace:*`
            // declaration. `serve` does not choose between them and must not
            // try — the host app's own manifest decides, which is exactly what
            // the host-anchored importer below reads (#4719).
            // [ADR-0105 D1] Key off the resolved POSTURE, not the legacy boolean.
            // Both walled postures (`group` and `isolated`) need this package:
            // gating on `OS_MULTI_ORG_ENABLED` alone would let
            // `OS_TENANCY_POSTURE=group` skip the load AND the fail-fast below,
            // silently degrading to an unwalled single-org deployment — the exact
            // ADR-0049 class this guard exists to close.
            // #5359 — reuse the value the boot gate resolved at the top of
            // `run()`. Re-invoking the resolver here is what put the throw
            // inside this swallowing `try` in the first place; by the time
            // control reaches this line the posture is known-valid.
            const multiTenant = tenancyPosture !== 'single';
            if (multiTenant) {
              // #4818 — TWO STAGES, TWO FAILURES, TWO DIAGNOSES. `import` and
              // `kernel.use(new mod.OrganizationsPlugin())` used to share one
              // `try`, so anything the plugin threw while CONSTRUCTING or
              // MOUNTING was reported as "@objectstack/organizations could not
              // be loaded" — i.e. as an absent package — and was swallowed by
              // OS_ALLOW_DEGRADED_TENANCY. Those are different facts with
              // different remedies (install it vs. address what the plugin
              // reported), and the escape hatch only ever meant "the capability
              // is ABSENT and I accept the degradation".
              //
              // The classifier is WHICH STAGE THREW — deliberately not the
              // error's shape. The framework must not know any of the plugin's
              // private refusal semantics (a layering violation that would need
              // updating per refusal reason), and the package is loaded through
              // `importFromHost`, so CLI and plugin may hold different module
              // instances: `instanceof` and named `code` checks are both
              // fragile here. Stage is the only classifier that needs to know
              // nothing about the plugin's internals.
              // #11614 — the spelling comes from the class-level declaration the
              // spec roster pins, not from a fresh literal at the resolution site.
              const organizationsPkg = Serve.ORGANIZATIONS_RUNTIME_PKG;
              let orgMod: any;
              // ── Stage 1: import. Failure here = the package is ABSENT. ──
              try {
                // Resolve from the HOST APP (cloud#1013). This package is
                // APP-DECLARED (ADR-0132 D3 — which build of the name a
                // deployment gets is the host manifest's call, not `serve`'s):
                // it is installed in the served app's node_modules, never in
                // the framework workspace the CLI's own realpath points at, so a
                // bare import here could never find it — `objectstack serve`
                // failed the fail-fast below on EVERY self-hosted walled-posture
                // deployment, and the only way past it was
                // OS_ALLOW_DEGRADED_TENANCY=1, i.e. exactly the unwalled state D5
                // exists to prevent. The host app declares the package; this
                // resolves it from there.
                orgMod = await importFromHost(organizationsPkg);
              } catch (orgErr) {
                // ADR-0093 D5 — degraded tenancy fails fast. Multi-org was
                // requested but the organizations package can't provide tenant
                // isolation: `tenant_isolation` RLS would be stripped and every
                // org boundary inert. A deployment that asked for isolation must
                // NOT serve traffic pretending to have it (ADR-0049 at the
                // deployment layer). Refuse to boot unless the operator has
                // explicitly opted into the degraded state.
                //
                // process.exit (not throw): this catch sits inside the broad
                // AuthPlugin try below, which swallows errors — a throw would be
                // caught and boot would silently continue degraded, which is the
                // exact footgun this guard closes.
                const cause = orgErr instanceof Error ? orgErr.message : String(orgErr);
                if (!resolveAllowDegradedTenancy()) {
                  // #4719 — TWO ABSENCES, TWO REMEDIES. Until the host lookup was
                  // gated on the host's declaration, both arrived here as one
                  // MODULE_NOT_FOUND and got one piece of advice: "declare it in
                  // the app's package.json". For an operator who HAD declared it
                  // and whose install was pruned, that sent them to re-read a
                  // file that was already correct. The importer now says which
                  // one it is, so this text can too.
                  const declaration = readHostDeclaration(organizationsPkg, hostRoot);
                  const remedy = formatOrganizationsInstallRemedy(
                    hostImportFailureKind(orgErr),
                    declaration,
                  );
                  console.error(
                    chalk.red(formatOrganizationsAbsentFatal(tenancyPosture, remedy, cause)),
                  );
                  process.exit(1);
                }
                // Explicitly opted into degraded operation — boot, but brand it
                // loudly. The `tenancy` service also reports `degraded: true` to
                // /auth/config and the Setup dashboard so it stays visible.
                console.warn(chalk.yellow(formatDegradedTenancyWarning(tenancyPosture)));
                // Degraded boot: `orgMod` stays undefined, so stage 2 below is
                // skipped. Nothing was loaded, so nothing can be mounted.
              }

              // ── Stage 2: construct + mount. Failure here = the package IS
              // present and the plugin itself declined. Report what it said,
              // verbatim, and exit unconditionally: OS_ALLOW_DEGRADED_TENANCY
              // does not cover this (#4818). Honouring it here would move
              // whatever gate the plugin is enforcing onto an env var. ──
              if (orgMod) {
                try {
                  await kernel.use(new orgMod.OrganizationsPlugin());
                  trackPlugin('Organizations');
                } catch (mountErr) {
                  // The framework does NOT interpret this error — it does not
                  // know why the plugin refused and must not guess a cause.
                  // Surface the plugin's own words (plus any `code` it carries,
                  // printed generically) and let them be the authority.
                  const mountMessage = mountErr instanceof Error ? mountErr.message : String(mountErr);
                  const mountCode = (mountErr as any)?.code;
                  // process.exit (not throw): this sits inside the broad
                  // AuthPlugin try below, which swallows errors — a throw would
                  // be caught and boot would continue with the wall inactive.
                  console.error(
                    chalk.red(
                      formatOrganizationsMountFatal(tenancyPosture, mountMessage, mountCode),
                    ),
                  );
                  process.exit(1);
                }
              }
            }

            // Pair: SecurityPlugin (RBAC) — optional
            try {
              const securityPkg = '@objectstack/plugin-security';
              const { SecurityPlugin, appSecurityPluginOptions } = await import(/* webpackIgnore: true */ securityPkg);
              // ADR-0056 D7 — honor an app-declared default profile. A stack
              // permission set marked `isDefault` becomes the baseline for
              // users with no explicit grants. The SecurityPlugin's own scan
              // only sees its built-in sets, so the declared name is passed
              // through explicitly (undefined → built-in default).
              //
              // [#7001] Resolved through the SHARED helper rather than
              // open-coded here. This was the only boot path that did it at
              // all: `@objectstack/verify`'s `bootStack` constructed a vanilla
              // `new SecurityPlugin()`, so an app's own dogfood suite ran
              // against a boot without the profile the CLI gave its users. The
              // two now agree by construction — one helper, one call shape, and
              // `serve-verify-security-parity.contract.test.ts` fails if either
              // side open-codes its way back out.
              await kernel.use(new SecurityPlugin(appSecurityPluginOptions(config)));
              trackPlugin('Security');
            } catch {
              // optional
            }

            // Pair: AuditPlugin — optional
            //
            // [#9863 / #9864] Registered with NO options, so record-view
            // auditing (`readAudit`) is off on this path. The one way an app
            // turns it on today is to put its own
            // `new AuditPlugin({ readAudit: … })` in the stack's `plugins`
            // array, which this file registers further down — AFTER this line.
            // Both instances carry the name `com.objectstack.audit`, so the
            // app's supersedes this one and the opt-in takes effect.
            //
            // That is a DECLARED contract now, not the accident #9863 found it
            // as: duplicate registration by name overwrites — last-one-wins,
            // with a `warn` naming both versions — identically on both kernels,
            // stated in `packages/core/src/plugin-registration.ts` and pinned
            // against `ObjectKernel` AND `LiteKernel` by
            // `packages/core/src/plugin-registration.contract.test.ts` (#9864,
            // maintainer ruling 2026-08-19, option B). Before that ruling the
            // behaviour was undeclared, untested and order-dependent, and
            // `LiteKernel.use()` threw on the very same input.
            //
            // ⚠️ The dependency is on the ORDER as much as on the overwrite:
            // this registration must stay ABOVE the stack's `plugins` loop, or
            // the CLI's option-less instance would supersede the app's
            // configured one instead — silently turning record-view auditing
            // back OFF for every deployment that had opted in. That order is no
            // longer held by this comment alone:
            // `serve-audit-registration.contract.test.ts` fails on the
            // inversion, and on the two facts below.
            //
            // ⚠️ It is also AUTH-GATED, which nothing had written down. This
            // pair is registered by the `5d. Auto-register AuthPlugin (and
            // paired Security/Audit)` branch, so an app that supplies its own
            // AuthPlugin — or a production boot with no auth secret, or a host
            // kernel — never reaches this line at all. There the app's
            // `plugins` entry is the ONLY AuditPlugin and no supersede happens.
            // The supersede is how the opt-in survives one particular boot
            // shape; it is not the mechanism the opt-in is built on.
            //
            // [#9863, ruled 2026-08-20] NO `appAuditPluginOptions(config)`.
            // The open question was whether to mirror the `SecurityPlugin`
            // helper six lines up. Four measurements say no:
            //
            //   • #7001's REASON DOES NOT TRANSFER. That helper exists so two
            //     boot paths could not disagree about one plugin's options.
            //     `@objectstack/verify`'s `bootStack` constructs no AuditPlugin
            //     at all and does not depend on `@objectstack/plugin-audit`, so
            //     audit has exactly one boot path with an opinion and there is
            //     no disagreement for a shared helper to close.
            //   • IT WOULD HAVE NOTHING TO READ. `appSecurityPluginOptions`
            //     derives from `config.permissions`, an already-declared spec
            //     surface. There is no `audit` key in the stack schema and no
            //     object-metadata audit field, so an audit helper means minting
            //     an authorable surface, not reading one.
            //   • THAT SURFACE IS THE SHAPE #8992 ALREADY REFUSED for the
            //     object-metadata spelling (maintainer ruling 2026-08-16): a
            //     declaration that survives in a deployment which never
            //     installs the plugin — the import below is best-effort — i.e.
            //     config that READS as audited and records nothing. On a
            //     compliance surface that is worse than an absent feature.
            //   • IT WOULD BE A SECOND SURFACE THAT SILENTLY LOSES TO THE
            //     FIRST. An app setting both would have its config-derived
            //     options superseded by its own `plugins` entry, by the very
            //     contract above — a new footgun on the same capability.
            //
            // Measured pull for the surface: zero `readAudit` call sites in the
            // repo outside `plugin-audit` itself. The reachability story is
            // instead DOCUMENTED, now that #9864 made it a contract rather than
            // the accident #9863 found: `content/docs/permissions/
            // record-view-auditing.mdx` and the plugin README both spell the
            // `plugins`-array opt-in and the `Plugin superseded:` line it logs.
            //
            // If the ruling is ever revisited, the site to argue about is
            // `Serve.CAPABILITY_PROVIDERS.audit` — the `requires:` resolver is
            // NOT auth-gated and already carries the `configKey` mechanism
            // `analytics` uses — not this line.
            try {
              const auditPkg = '@objectstack/plugin-audit';
              const { AuditPlugin } = await import(/* webpackIgnore: true */ auditPkg);
              await kernel.use(new AuditPlugin());
              trackPlugin('Audit');
            } catch {
              // optional
            }
          }
        } catch (err: unknown) {
          const msg = err instanceof Error ? err.message : String(err);
          if (!Serve.isModuleNotFoundError(err)) {
            console.warn(chalk.yellow(`  ⚠ AuthPlugin failed to load: ${msg}`));
          }
          // @objectstack/plugin-auth not installed — login/register endpoints unavailable
        }
      }

      if (plugins.length > 0) {
        for (const plugin of plugins) {
          try {
            // [#22301] What an entry becomes — a string is a package specifier,
            // a plain bundle (no `init`) is wrapped into `AppPlugin`, an instance
            // is itself — is ONE rule, `materializeStackPlugin` (`@objectstack/
            // core`), which `@objectstack/verify`'s `bootStack` mounts the same
            // array by. Only the loading is this boot's own:
            const pluginToLoad: any = await materializeStackPlugin(plugin, {
              // Host-anchored, NOT a bare `import()`: this specifier comes from
              // the served app's own config, so what the app DECLARES about it is
              // the contract (commit 9cc6777d3). The helper carries the failure wrapper too.
              // (Spelled as the boot loop's own call: two source pins —
              // `serve-config-plugin-host-resolution.test.ts` and
              // `serve-config-plugin-relative-refusal.test.ts` — hold this
              // loop to routing every string entry through the helper.)
              importSpecifier: async (plugin) => await Serve.importConfigPlugin(plugin, hostRoot),
              wrapBundle: async (bundle) => {
                try {
                  const { AppPlugin } = await import('@objectstack/runtime');
                  return new AppPlugin(bundle);
                } catch {
                  // Fall through to kernel.use which will report the error
                  return bundle;
                }
              },
            });

            // [#9863 / #9864] The superseding half of the pair documented at
            // the `AuditPlugin` auto-registration above: a stack plugin whose
            // `name` matches one auto-registered earlier REPLACES it, by
            // declared contract (`packages/core/src/plugin-registration.ts`),
            // with a `warn` naming both versions. That is how an app supplies
            // options to a plugin this CLI mounts without them.
            await kernel.use(pluginToLoad);
            const pluginName = plugin.name || plugin.constructor?.name || 'unnamed';
            trackPlugin(pluginName);
          } catch (e: any) {
            console.error(chalk.red(`  ✗ Failed to load plugin: ${e.message}`));
          }
        }
      }

      // Register REST API and Dispatcher plugins (consume http.server + protocol services)
      //
      // [#22202] The REST API plugin is composed on EVERY boot; only the
      // dispatcher and the no-auth refusal below ride `flags.server`. The REST
      // plugin is not only a route mounter: its `init()` registers
      // `sys_import_job`, the object its async-import routes persist to, and
      // schema sync creates tables only for the objects registered in THIS
      // boot. While the whole plugin rode the listener flag, a `--no-server`
      // `OS_MIGRATE_AND_EXIT=1` run provisioned one table fewer than the server
      // boot it prepares for (measured on `examples/app-todo`: 69 tables
      // against 70, `sys_import_job` the only difference), so a deployment that
      // migrated "kernel only" and then served with schema sync off had no
      // import-job table at all.
      //
      // Composed here, it behaves like the service plugins composed above
      // (storage, settings, sharing, auth, i18n …): its object registers
      // whatever the flag says, and with no `http.server` its `start()` mounts
      // nothing and says so in one `warn`. `--no-server` still means "kernel
      // only": no HTTP server plugin, no dispatcher, no route.
      // `test/serve-migrate-exit-schema-parity.integration.test.ts` pins the
      // table-set equality.
      //
      // Read environment-scoping config from the stack's top-level `api` field
      // (e.g. { api: { enableProjectScoping: true, projectResolution: 'auto' } }).
      // Forwarded to both REST and Dispatcher plugins so they mount scoped
      // routes consistently.
      const apiConfig = (config as any).api ?? {};
      const enableProjectScoping = apiConfig.enableProjectScoping ?? false;
      const projectResolution = apiConfig.projectResolution ?? 'auto';
      // [#3963] Anonymous access to object data is denied unconditionally —
      // there is no `api.requireAuth` opt-out any more (auth is a kernel
      // concern; every legitimately session-less surface derives its own narrow
      // authorization from a declaration instead).
      //
      // The CLI used to hand an EXPLICIT fail-open to a stack with no auth at
      // all, reasoning that nobody could authenticate against it so denying
      // would brick its data API. Under A1 that inverts the conclusion: a stack
      // with no auth has no security model, so it must not serve a data API —
      // and it should say so at boot instead of quietly serving object data to
      // the internet. Auth availability = the tier auto-registers it OR the
      // stack mounts AuthPlugin explicitly.
      if (flags.server && !(tierEnabled('auth') || hasAuthPlugin)) {
        throw new Error(
          'This stack mounts no auth, so no caller can authenticate — and anonymous access to object '
          + 'data is always denied, with no setting that turns that off, which would leave the data API unusable.\n'
          + 'Fix it one of two ways:\n'
          + `  • enable auth — add the 'auth' tier (or mount AuthPlugin in \`plugins\`);\n`
          + '  • or serve without the data API — run with --no-server, or drop the REST/dispatcher plugins.\n'
          + "Publishing a genuinely public surface does not need anonymous data access: use a public form "
          + "view, a share link, or `book.audience: 'public'`.",
        );
      }

      try {
        const { createRestApiPlugin } = await import('@objectstack/rest');
        await kernel.use(
          createRestApiPlugin({ api: { api: { enableProjectScoping, projectResolution } } as any }),
        );
        trackPlugin('RestAPI');
      } catch (e: any) {
        // @objectstack/rest is optional
      }

      if (flags.server) {
        // Per-project membership (sys_environment_member 403 gate) is, by
        // default, ON whenever project-scoping is on. A host can opt OUT
        // (env-native auth IS the membership — ADR-0135 D9) by setting
        // `api.enforceProjectMembership: false`. Undefined → dispatcher default.
        const enforceProjectMembership = apiConfig.enforceProjectMembership;
        // [#4910] The stack's top-level `server:` block — deliberately narrow:
        // only keys with a consumer are declared, and both of these have one in
        // the dispatcher's inbound rate limiter. Read here, like the `api:` block
        // above and for the same reason: this is the single place the authored
        // stack is turned into plugin configuration.
        //
        // NOTE the budget is deliberately NOT validated here. An unusable one
        // (`maxRequests: 0`) throws out of `createInboundRateLimitMiddleware`
        // during the dispatcher plugin's `init()`, which the kernel runs at
        // BOOTSTRAP — outside the optional-plugin `catch` below, which only
        // guards the `import`/`use` registration. So a nonsense budget fails the
        // boot with a prescriptive message instead of silently disarming the
        // limiter or, worse, silently dropping the whole dispatcher.
        const serverConfig = (config as any).server ?? {};
        const rateLimitConfig = {
            ...(serverConfig.security?.rateLimit ? { budget: serverConfig.security.rateLimit } : {}),
            trustProxy: serverConfig.trustProxy === true,
        };

        // Register Dispatcher plugin (auth, graphql, analytics, packages, hub, storage, automation)
        try {
          const { createDispatcherPlugin } = await import('@objectstack/runtime');
          // `observability` is the ONE block built above (#9832), reused
          // here rather than rebuilt: a second `buildServeObservability()`
          // call would stand up a second exporter with its own flush timer.
          // Passing it explicitly keeps the dispatcher on step 1 of the
          // resolution chain, so its behaviour is unchanged by the service
          // registration above — and because `armHttpRequestCounter` latches
          // per server object (#9835), the transport having armed the same
          // registry in Phase 1 makes this plugin's arming a no-op instead of
          // a second observer on the same series.
          await kernel.use(
            createDispatcherPlugin({
              scoping: { enableProjectScoping, projectResolution },
              enforceProjectMembership,
              observability,
              rateLimit: rateLimitConfig,
            }),
          );
          trackPlugin('Dispatcher');
        } catch (e: any) {
          // optional
        }
      }

      // 4. Auto-register AIServicePlugin if not already loaded by config plugins.
      // Registered AFTER Dispatcher so that the ai:routes hook listener is
      // already in place when AIServicePlugin.start() fires the hook.
      const hasAIPlugin = plugins.some(
        (p: any) => p.name === 'com.objectstack.service-ai'
            || p.constructor?.name === 'AIServicePlugin'
      );
      // `importFromHost` (module scope, hoisted over this whole file — it is no
      // longer "declared above" anything, which is the point) resolves optional
      // plugin packages from the HOST APP's context — the app being served
      // declares them as deps, including private packages like
      // @objectstack/service-ai-studio that the framework CLI itself does not
      // depend on.
      // [CE AI opt-in] Auto-register the headless AI service ONLY when the host
      // app DECLARES the AI service (or the cloud AI Studio that builds on it).
      // Declaration is the edition boundary: a Community-Edition app that omits
      // both gets no AI service, no
      // agents, and no `services.ai` in discovery (so the console hides its AI
      // surface), while MCP and every other capability are unaffected. Gating on
      // a *declared* dep — not mere resolvability — makes this reliable in a
      // workspace/monorepo, where the package stays hoist-resolvable when undeclared.
      //
      // #4719 — this used to be a local re-implementation of that read. It was
      // right, and it was the ONLY place in the boot path that asked the question
      // the right way: the organizations load two blocks up asked
      // "does it resolve", which a hoisted store answered yes to regardless. Both
      // now go through the one owner in `@objectstack/types/node`, so "declared"
      // cannot mean two different things in one file (Prime Directive #12).
      const hostDeclaresDependency = (pkg: string): boolean => isDeclaredByHost(pkg, hostRoot);
      // `wantsAiService` is the AUTO (opt-in) signal: the host app listed the base
      // AI service — or the Studio that builds on it — in its OWN package.json. This
      // is a package.json READ (a deliberate authoring act), not a speculative
      // import: gating on a *declared* dep, not mere resolvability, is reliable in a
      // workspace/monorepo where a package stays hoist-resolvable when undeclared.
      // Studio implies the base service (it attaches via the `ai:ready` hook the base
      // fires; the base is a transitive dep of Studio, so it stays resolvable).
      const wantsAiService =
        hostDeclaresDependency('@objectstack/service-ai')
        || hostDeclaresDependency('@objectstack/service-ai-studio');

      // Load an optional, separately-published service plugin by INTENT (#1597).
      // `required` (from an explicit `requires: [...]` capability) makes a missing
      // OR crashing package a HARD boot error — a declared-but-broken capability
      // must fail-fast, never boot silently degraded (the outer boot catch prints
      // the message and exits 1). `auto` (the package is merely DECLARED as a dep)
      // is best-effort: a genuine crash is surfaced loudly, an absent package is the
      // expected quiet skip. Presence is never inferred by importing-and-catching —
      // the caller already decided to attempt this from intent, so the module-not-
      // found test only WORDS the failure, it never decides whether to load.
      // Returns true when the plugin was registered.
      const loadOptionalServicePlugin = async (
        pkg: string,
        exportName: string,
        opts: { required: boolean; label: string; track: string; capability: string },
      ): Promise<boolean> => {
        try {
          const mod: any = await importFromHost(pkg);
          const Ctor = mod[exportName];
          if (typeof Ctor !== 'function') {
            const detail = `${pkg} did not export ${exportName}`;
            if (opts.required) {
              throw new Error(`[${opts.label}] required but ${detail}.`);
            }
            console.warn(chalk.yellow(`  ⚠ ${opts.label}: ${detail} — skipping`));
            return false;
          }
          await kernel.use(new Ctor());
          trackPlugin(opts.track);
          return true;
        } catch (err: unknown) {
          if (opts.required) {
            const msg = err instanceof Error ? err.message : String(err);
            throw new Error(
              // #3366 — an absent provider is classified by edition: a cloud-only
              // capability (e.g. `ai` → @objectstack/service-ai) says so instead of
              // the un-followable "add it to your dependencies". Same wording the
              // `os build` preflight prints, so boot and preflight read identically.
              Serve.isModuleNotFoundError(err)
                ? missingProviderMessage(opts.capability)
                : `[${opts.label}] failed to start: ${msg}`,
            );
          }
          // auto (opt-in): non-fatal. A real crash is surfaced; a missing package is
          // the expected "not installed" path and stays quiet.
          if (!Serve.isModuleNotFoundError(err)) {
            const msg = err instanceof Error ? err.message : String(err);
            console.error(`[${opts.label}] failed to start: ${msg}`);
          }
          return false;
        }
      };

      // Base AI service — enable from declared INTENT, not package presence (#1597):
      //   • `requires: ['ai']` (or `['ai-studio']`, which implies the base) ⇒ required
      //     → a missing/broken package aborts startup (fail-fast).
      //   • package declared in the app's package.json (but not required) ⇒ auto
      //     → load best-effort.
      //   • otherwise ⇒ skip, with NO speculative import.
      // The `ai` tier is the orthogonal DENY: a Community-Edition deployment whose
      // `tiers` omit `ai` never loads it, whatever the intent — so a CE app that
      // omits AI gets no AI service, no agents, and no `services.ai` in discovery
      // (the console hides its AI surface), while every other capability is unaffected.
      const aiRequired =
        declaredRequires.has('ai') || declaredRequires.has('ai-studio');
      const aiDecision = Serve.resolveOptionalPluginLoad({
        tierAllowed: tierEnabled('ai'),
        required: aiRequired,
        declared: wantsAiService,
      });
      if (!hasAIPlugin && aiDecision !== 'off') {
        // AIServicePlugin auto-detects its LLM provider from environment
        // (AI_GATEWAY_MODEL, OPENAI_API_KEY, ANTHROPIC_API_KEY,
        // GOOGLE_GENERATIVE_AI_API_KEY) — no adapter to construct here.
        const aiLoaded = await loadOptionalServicePlugin(
          '@objectstack/service-ai',
          'AIServicePlugin',
          { required: aiDecision === 'required', label: 'AI', track: 'AIService', capability: 'ai' },
        );

        // AI Studio (AI-driven metadata authoring / "online development") builds on
        // the base service and attaches via its `ai:ready` hook, so only attempt it
        // once the base actually loaded. It is NOT part of the open-source framework:
        //   • `requires: ['ai-studio']` ⇒ required → fail-fast if the private package
        //     is absent (an app that advertises Studio must ship it).
        //   • package declared but not required ⇒ auto (best-effort).
        //   • otherwise ⇒ skip — this is the control-plane host path (such a host
        //     ships no Studio and MUST boot clean, cloud#107): not declared + not
        //     required ⇒ no import, no error.
        if (aiLoaded) {
          const hasAIStudio = plugins.some(
            (p: any) => p.name === 'com.objectstack.service-ai-studio'
                || p.constructor?.name === 'AIStudioPlugin'
          );
          if (!hasAIStudio) {
            const studioDecision = Serve.resolveOptionalPluginLoad({
              tierAllowed: tierEnabled('ai'),
              required: declaredRequires.has('ai-studio'),
              declared: hostDeclaresDependency('@objectstack/service-ai-studio'),
            });
            if (studioDecision !== 'off') {
              await loadOptionalServicePlugin(
                '@objectstack/service-ai-studio',
                'AIStudioPlugin',
                { required: studioDecision === 'required', label: 'AI Studio', track: 'AIStudio', capability: 'ai-studio' },
              );
            }
          }
        }
      }

      // 5. Capability resolver — auto-load service plugins declared in
      // `requires: [...]` that are NOT tier-gated. Each entry of
      // Serve.CAPABILITY_PROVIDERS maps a token to a package + factory; if the
      // user already provided an explicit instance via `plugins: [...]` we
      // skip (explicit wins). Adding a new built-in capability = one entry on
      // the static registry + its token in the spec vocabulary (#3265).
      const CAPABILITY_PROVIDERS = Serve.CAPABILITY_PROVIDERS;

      // Providers THIS resolver has already mounted, by instance. The app's
      // own `plugins[]` alone stopped being the whole answer once two tokens
      // named one provider: `marketplace` and `package-registry` both resolve
      // to PackageServicePlugin, so an app declaring `marketplace` would have
      // the always-on `package-registry` mount a second instance, which
      // `kernel.use` answers by name with a `Plugin superseded` warn (#19387,
      // measured). Pushed only after a successful `kernel.use`, so a provider
      // that failed to load under one token is still attempted — with that
      // token's own required/best-effort semantics — under the next.
      const resolverMounted: unknown[] = [];

      // Exact identity comparison, NOT substring containment — a consumer named
      // after the capability it consumes must never be mistaken for its
      // provider (#7652). See Serve.providesCapability.
      const hasPluginMatching = (identities: readonly string[]) =>
        Serve.providesCapability(plugins, identities) || Serve.providesCapability(resolverMounted, identities);

      for (const cap of requires) {
        const spec = CAPABILITY_PROVIDERS[cap];
        if (!spec) {
          // No provider in this runtime. Tier-gated tokens (ai/ai-studio/i18n/
          // ui/auth) are handled by their dedicated blocks above; other KNOWN
          // vocabulary tokens are provided elsewhere (`hierarchy-security` via
          // an explicit enterprise plugin in `plugins[]`, `ai-seat`/`governance`
          // by cloud's objectos-runtime) — stay quiet for those. An UNKNOWN
          // declared token is a typo that was previously ignored SILENTLY
          // (#3265) — warn loudly. Warn-first: intended to become a hard error
          // once the vocabulary proves complete (Prime Directive #12).
          //
          // A force-appended ALWAYS_ON token must never land here, because it
          // passes both conjuncts below and would mount nothing without a word
          // (#19387: `package-registry` did exactly that). That is pinned before
          // it ships rather than warned about after: every slate token keys a
          // CAPABILITY_PROVIDERS entry or a CAPABILITY_TO_TIER tier
          // (`serve-capability-vocabulary.test.ts`), and `@objectstack/spec` and
          // this package release in one fixed version group.
          if (declaredRequires.has(cap) && !PLATFORM_CAPABILITY_TOKENS.includes(cap)) {
            // A RETIRED token (e.g. `reports`, #20102) is not a typo: say what
            // replaced it, in the same words `defineStack` refuses it with.
            const retired = Object.prototype.hasOwnProperty.call(RETIRED_PLATFORM_CAPABILITY_GUIDANCE, cap)
              ? RETIRED_PLATFORM_CAPABILITY_GUIDANCE[cap]
              : undefined;
            console.warn(chalk.yellow(
              retired
                ? `  ⚠ ${retired} It was ignored.`
                : `  ⚠ requires: "${cap}" is not a known platform capability — check for a typo. It was ignored.`,
            ));
          }
          continue;
        }
        if (hasPluginMatching(spec.identities)) continue;

        try {
          const mod: any = await import(/* webpackIgnore: true */ spec.pkg);
          const Ctor = mod[spec.export];
          if (!Ctor) {
            console.warn(chalk.yellow(`  ⚠ Capability "${cap}": ${spec.pkg} did not export ${spec.export}`));
            continue;
          }
          // [#22301] WHAT the provider is constructed with is ONE rule,
          // `resolveCapabilityArgument` (`@objectstack/core`), which
          // `@objectstack/verify`'s `bootStack` reads too: `automation` gets the
          // app's root (#3016 — declarative connector file refs resolve from
          // the project folder, next to objectstack.config.ts, never from the
          // working directory); `analytics` the stack's cubes, the top level
          // first and then the package bodies (#22288); `email` and `sms` the
          // deployment's mail and SMS configuration, read by the readers their
          // own packages export off `mod` (env beats config); `storage` its
          // local root. The mail and SMS readers THROW on a configuration no
          // transport can deliver through (#5087, #5132, #5713) — the catch
          // below turns that into the boot failure / loud error it should be,
          // never a log transport substituted behind the operator's back.
          const resolved = resolveCapabilityArgument(cap, {
            stack: config,
            packageRoot: path.dirname(absolutePath),
            providerModule: mod,
            env: process.env,
          });
          const arg: any = resolved.argument;
          if (resolved.localStorageRoot && !isDev) {
            // Storage is in the default capability slate, and a host that
            // configured no backend gets the local-disk driver. In production
            // mode say so once, loudly, so the operator points storage at
            // S3 / GCS / Azure before shipping (data on a single pod is
            // volatile / non-replicated). Names only the channels that
            // actually work — `config.storage` was in this sentence and was
            // never read (framework#4167).
            console.warn(chalk.yellow(
              `  ⚠ StorageServicePlugin using local driver (${resolved.localStorageRoot}) — switch to S3/GCS/Azure for production (set OS_STORAGE_* or configure storage in Setup → Settings).`,
            ));
          }
          const provider = arg !== undefined ? new Ctor(arg) : new Ctor();
          await kernel.use(provider);
          resolverMounted.push(provider);
          trackPlugin(spec.export);

          if (spec.extras) {
            for (const ex of spec.extras) {
              if (hasPluginMatching(ex.identities)) continue;
              try {
                const exMod: any = await import(/* webpackIgnore: true */ ex.pkg);
                const ExCtor = exMod[ex.export];
                if (ExCtor) {
                  const extra = new ExCtor();
                  await kernel.use(extra);
                  resolverMounted.push(extra);
                  trackPlugin(ex.export);
                }
              } catch {
                // optional extra — silently skip
              }
            }
          }
        } catch (err: unknown) {
          const msg = err instanceof Error ? err.message : String(err);
          const missing = Serve.isModuleNotFoundError(err);
          // Fail-fast (#1597) for capabilities the app EXPLICITLY declared in
          // `requires`: one that can't be provided — its provider package absent, or
          // its plugin throwing while it starts — is a hard boot error, not a warning
          // to scroll past (declared ≠ enforced, Prime Directive #10). The outer boot
          // catch prints the message and exits 1. Platform-injected convenience
          // defaults (ALWAYS_ON, mcp, pinyin-search, auth→email, queue/job) stay
          // best-effort: absent ⇒ warn, crash ⇒ error, boot continues.
          if (declaredRequires.has(cap)) {
            throw new Error(
              // #3366 — edition-aware message via the shared classifier (same
              // wording the `os build` preflight prints). For these CAPABILITY_
              // PROVIDERS tokens (all open-edition) that's the `pnpm add` hint;
              // the cloud-only tokens surface their edition boundary instead.
              missing
                ? missingProviderMessage(cap)
                : `Capability "${cap}" (${spec.pkg}) failed to start: ${msg}`,
            );
          }
          if (!missing) {
            console.error(`[Capability:${cap}] failed to load ${spec.pkg}: ${msg}`);
          } else {
            console.warn(chalk.yellow(`  ⚠ Capability "${cap}" (auto-enabled default) not installed — skipping ${spec.pkg}`));
          }
        }
      }

      // Shared dev crypto provider for ALL of sys_secret (datasource creds
      // below + secret fields after start). One instance ⇒ one key, so every
      // encrypted secret decrypts under the same provider. Created lazily by
      // whichever block runs first.
      let sharedCryptoProvider: any = undefined;

      // ── External Datasource Federation (ADR-0015) ─────────────────
      // Federation (introspect / draft / import / validate of external
      // tables) ships in the open framework.
      try {
        const dsMod: any = await import('@objectstack/service-datasource');
        const { ExternalDatasourceServicePlugin } = dsMod;

        if (
          ExternalDatasourceServicePlugin &&
          !hasPluginMatching(['com.objectstack.service-external-datasource', 'ExternalDatasourceServicePlugin'])
        ) {
          await kernel.use(new ExternalDatasourceServicePlugin());
          trackPlugin('ExternalDatasourceServicePlugin');
        }

        // Gate 2 (ADR-0015 §5.2): on kernel:ready, validate every federated
        // object against its remote table and apply the datasource's
        // `external.validation.onMismatch` policy. No-op when the
        // `external-datasource` service isn't registered (federation unused).
        const { createExternalValidationPlugin } = await import('@objectstack/runtime');
        if (
          createExternalValidationPlugin &&
          !hasPluginMatching(['com.objectstack.external-validation', 'ExternalValidationPlugin'])
        ) {
          await kernel.use(createExternalValidationPlugin());
          trackPlugin('ExternalValidationPlugin');
        }
      } catch (err: unknown) {
        const msg = err instanceof Error ? err.message : String(err);
        if (!Serve.isModuleNotFoundError(err)) {
          console.error(`[Datasource] federation wiring failed: ${msg}`);
        }
      }

      // ── Runtime Datasource Admin (ADR-0015 Addendum) ──────────────
      // The "Add Datasource" wizard backend: list / test / create / update /
      // remove datasources defined in the UI at runtime. This is open-source
      // *mechanism* (`@objectstack/service-datasource`); the tier line
      // falls on which ICryptoProvider / driver factory a host injects, not on
      // whether the UI can manage datasources. Mounted by default so a
      // self-host runtime is a complete low-code platform out of the box.
      //
      // Credentials are bound through the SAME crypto provider used for
      // `secret` fields below (`sharedCryptoProvider`), so every secret in
      // `sys_secret` (settings, secret fields, datasource creds) shares one
      // key. Wired BEFORE runtime.start() so the plugin's kernel:ready boot
      // rehydration (which decrypts persisted creds) has its binder ready.
      try {
        const adminMod: any = await import('@objectstack/service-datasource');
        const {
          DatasourceAdminServicePlugin,
          createDefaultDatasourceDriverFactory,
          createDatasourceSecretBinder,
          registerDatasourceAdminRoutes,
        } = adminMod;

        if (
          DatasourceAdminServicePlugin &&
          !hasPluginMatching(['com.objectstack.service-datasource-admin', 'DatasourceAdminServicePlugin'])
        ) {
          // Lazy data-engine surface for the secret store (resolved per call
          // so it works whether the engine is registered as 'data' or
          // 'objectql', and regardless of init ordering).
          const resolveEngine = (): any =>
            kernel.getService?.('data') ?? kernel.getService?.('objectql');
          const lazySecretEngine = {
            insert: (o: string, d: any, opt?: any) => resolveEngine()?.insert(o, d, opt),
            delete: (o: string, opt?: any) => resolveEngine()?.delete(o, opt),
            find: (o: string, q?: any) => resolveEngine()?.find(o, q),
          };

          // Fail-closed binder over the shared dev crypto provider. If the
          // provider can't be created, leave `secrets` undefined — the plugin
          // then rejects secret-bearing create/update instead of storing
          // cleartext (by design).
          let secrets: any = undefined;
          try {
            const { LocalCryptoProvider } = await import(
              /* webpackIgnore: true */ '@objectstack/service-settings'
            );
            // First block to touch `sharedCryptoProvider` (still undefined
            // here), so create it directly; the secret-field wiring below
            // reuses this instance so every sys_secret shares one key.
            sharedCryptoProvider = new LocalCryptoProvider();
            secrets = createDatasourceSecretBinder({
              engine: lazySecretEngine,
              cryptoProvider: sharedCryptoProvider,
            });
          } catch (cryptoErr: any) {
            // Best-effort fail-closed: leave `secrets` undefined so the plugin
            // rejects secret-bearing create/update rather than storing
            // cleartext. A production deployment with no stable key still
            // aborts boot loudly at the secret-field wiring below (where
            // LocalCryptoProvider's "Refusing to start in production" error is
            // rethrown), so we don't duplicate that abort here.
            console.warn(
              chalk.yellow(
                `  ⚠ datasource admin: no CryptoProvider (${cryptoErr?.message ?? cryptoErr}); secret-bearing datasource create/update will fail closed`,
              ),
            );
          }

          await kernel.use(
            new DatasourceAdminServicePlugin({
              driverFactory: createDefaultDatasourceDriverFactory(),
              secrets,
            }),
          );
          trackPlugin('DatasourceAdminServicePlugin');

          // REST routes under /api/v1/datasources, mounted by a tiny plugin
          // during its init (same pattern as the hostname guard above). What
          // it reads, and which warning a boot without a server gets, lives
          // on `createDatasourceAdminRoutesPlugin()` below.
          await kernel.use(createDatasourceAdminRoutesPlugin(registerDatasourceAdminRoutes));
          trackPlugin('DatasourceAdminRoutes');

          if (isDev) {
            printDiagnostic(
              chalk.dim('  ↪ datasource admin: runtime UI lifecycle wired (/api/v1/datasources)'),
            );
          }
        }
      } catch (err: unknown) {
        const msg = err instanceof Error ? err.message : String(err);
        if (!Serve.isModuleNotFoundError(err)) {
          console.error(`[Datasource] runtime-UI admin wiring failed: ${msg}`);
        }
      }

      // ── UI portals ────────────────────────────────────────────────
      // In dev mode, the bundled Console portal is enabled by default
      // (use --no-ui to disable). Always serve the pre-built `dist/` — no
      // Vite dev server, no extra port.
      const enableUI = flags.ui && tierEnabled('ui');

      if (enableUI) {
        // Pre-detect Console availability. The `--no-console` flag (or
        // OS_DISABLE_CONSOLE=1 env var) lets a host opt out of the Console
        // entirely — useful for control-plane deployments where the
        // runtime Console is meaningless.
        const consoleEnabled = flags.console && process.env.OS_DISABLE_CONSOLE !== '1';
        // Resolution reports objectui-SHA drift instead of warning about it
        // itself, so the decision below owns the single message about it.
        // (Boxed so the assignment made inside `onDrift` is visible to
        // control-flow analysis after the call returns.)
        const driftBox: { value: ConsoleShaDrift | null } = { value: null };
        const consolePath = consoleEnabled
          ? resolveConsolePath({ onDrift: (d) => { driftBox.value = d; } })
          : null;
        const consoleDrift = driftBox.value;
        const { mount: consoleWillMount, refusedForDrift } = decideConsoleMount({
          hasDist: !!(consolePath && hasConsoleDist(consolePath)),
          drift: consoleDrift,
          isDev,
        });

        // ── Console portal ──────────────────────────────────────────
        // The opinionated, fork-ready runtime console (`@objectstack/console`,
        // the build of objectstack-ai/objectui's console app this framework
        // vendors at its `.objectui-sha` pin) mounts under `/_console/`. When
        // present, it owns the root `/` redirect (preferred default UI). It is
        // optional — we only mount it when the package resolves and a
        // pre-built `dist/` is present, and — in dev — only when that build
        // matches the repo's objectui pin (#7752). Every other boot that wants
        // a Console gets a responder on those same routes instead, so
        // `/_console/` answers `503` naming the remedy its boot message prints
        // rather than a bare 404 (#22420): the drift refusal; a package with no
        // `dist/`; no package at all (`consolePath` null). Only `--no-ui` /
        // `--no-console` mount nothing, by the operator's own choice.
        if (consolePath && consoleWillMount) {
          if (consoleDrift) {
            console.warn(chalk.yellow(formatConsoleShaDriftWarning(consoleDrift)));
          }
          const consoleDistPath = path.join(consolePath, 'dist');
          await kernel.use(createConsoleStaticPlugin(consoleDistPath, { isDev }));
          trackPlugin('ConsoleUI');
        } else if (refusedForDrift && consoleDrift) {
          console.error(chalk.red(formatConsoleShaDriftRefusal(consoleDrift)));
          await kernel.use(createConsoleShaDriftRefusalPlugin(consoleDrift));
          trackPlugin('ConsoleShaDriftRefused');
        } else if (consoleEnabled) {
          console.warn(chalk.yellow(formatConsoleDistMissingWarning(consolePath)));
          await kernel.use(createConsoleNotBuiltPlugin(consolePath));
          trackPlugin('ConsoleNotBuilt');
        }
      }

      // ── Artifact-pinned boot: migration policy (#8368, acceptance #5) ──
      // Only on the OS_ARTIFACT_URL path. On this path "upgrade the app" is an
      // env change plus a restart, with nobody at a terminal to read a drift
      // warning at the moment it matters — so safe changes are applied and a
      // destructive one refuses the boot instead of being warned about and
      // skipped. Every other boot keeps the standing production policy
      // untouched (schema is never auto-altered under NODE_ENV=production).
      //
      // Registered as a plugin whose `kernel:ready` hook runs the gate: Phase 3
      // is after every plugin's start() — so ObjectQL's schema sync has already
      // created tables and added columns — and before Phase 4 opens the HTTP
      // socket. A throw from a boot-path hook propagates and fails the boot, so
      // "refuse to boot" is literal: the port never binds.
      if (pinnedArtifact) {
        const artifactDisplay = pinnedArtifact.display;
        await kernel.use({
          name: 'com.objectstack.cli.artifact-boot-migration-gate',
          version: '1.0.0',
          init: async (ctx: any) => {
            ctx.hook('kernel:ready', async () => {
              const { findSqlDriverForKernel } = await import('../utils/schema-migrate.js');
              const { runArtifactBootMigrationGate } = await import('../utils/artifact-boot-migration.js');
              const verdict = await runArtifactBootMigrationGate({
                driver: findSqlDriverForKernel(kernel),
                artifactDisplay,
                info: (m) => printDiagnostic(chalk.dim(m)),
                warn: (m) => console.warn(chalk.yellow(m)),
              });
              if (!verdict.ok) {
                // Restore stdout before the refusal so the boot-quiet window
                // cannot swallow the one message that explains the exit.
                restoreOutput();
                console.error('\n' + verdict.refusal);
                throw new Error(
                  `Refusing to boot: ${verdict.destructive.length} destructive schema change(s) `
                  + `required by the artifact named by OS_ARTIFACT_URL. `
                  + `Run 'os migrate apply --allow-destructive' deliberately, then restart.`,
                );
              }
            });
          },
        } as any);
        trackPlugin('ArtifactBootMigrationGate');
      }

      // ── Seed-settlement announcer (#17329) ─────────────────────────
      // `✓ Server is ready` is true about the HTTP server and says nothing
      // about the app: past the inline seed budget the rest of the seed runs
      // detached, so the banner, and any parent that waits for it, can be
      // eighty seconds ahead of a hundred-line error wall. This is the hop that
      // makes the settle readable OFF the child's stdio — a second IPC message
      // beside `objectstack:listening`, on the channel `os dev` already holds.
      //
      // ⛔ The producer is NOT new and NOT ours: `@objectstack/runtime` already
      // declares every seed source and settles it at the exact moment its
      // boot-time write is done, publishing the tally under the spec's
      // `seed-settlement` contract. This registers no service and mutates
      // nothing — it subscribes to two hooks the kernel already fires and reads
      // a snapshot it already publishes.
      //
      // ⭐ Registered as a plugin because `hook` is reachable from a plugin
      // context and nowhere else — `ObjectKernel.context` is private, and
      // sniffing past that to reach it would be the coupling the published
      // contract exists to avoid. Same shape as the artifact gate above.
      const seedSettlement = createSeedSettlementAnnouncer(runtimeSeedSettlementChannels(kernel));
      await kernel.use({
        name: 'com.objectstack.cli.seed-settlement-announcer',
        version: '1.0.0',
        init: async (ctx: any) => {
          // Both legs are load-bearing and neither is redundant:
          //   `app:seeded`  — the ONLY signal on the over-budget path, where the
          //                   settle lands after the banner (and after
          //                   `kernel:ready`). Fires once per config app, so it
          //                   asks the tally rather than counting itself.
          //   `kernel:ready`— the only hook that runs at all on a multi-tenant
          //                   or `skipSeedData` boot, where the source is
          //                   SUPPRESSED and `app:seeded` never fires. Also the
          //                   in-budget fast path, where seeding was already
          //                   done before this line.
          ctx.hook('app:seeded', () => { seedSettlement.check(); });
          ctx.hook('kernel:ready', () => { seedSettlement.check(); });
        },
      } as any);
      // ⛔ Deliberately NOT `trackPlugin`ed. That list feeds the banner's
      // `Plugins:` count and name row, and this subscriber is an internal wiring
      // detail of the CLI's own announcement — putting it there would grow a
      // published banner surface on every boot to report a thing an operator
      // cannot act on.

      // ── No-storage boot guard (#23573) ─────────────────────────────
      // Step 2 recorded that this production boot declared no storage. Whether
      // that is fatal is only known once every plugin's init() has run, since a
      // stack plugin the name test missed may register a driver there. This is
      // the LAST plugin registered, so its init() runs after every other init()
      // and before any start() (resolvePluginOrder keeps insertion order; no
      // plugin names this one as a dependency). It reads the one map ObjectQL
      // adopts `driver.*` services from at its start(), plus any driver the
      // engine already holds.
      //   • a driver is there                ⇒ nothing to say.
      //   • none, and the auth service runs under the 'single' posture ⇒ refuse
      //     before any start(). AuthPlugin.start() creates the Default
      //     Organization there, which needs a driver, and no driver can arrive
      //     before it: AppPlugin orders ObjectQL and auth ahead of every stack
      //     plugin, so a driver registered in any start() comes too late.
      //     Without this, the boot died there with a driver error, after an
      //     objectql ERROR naming a datasource nobody declared.
      //   • none otherwise                   ⇒ ONE line, and the boot goes on.
      //     Worded as of the end of init, because a start() (a module's
      //     onEnable) may still register a driver and some such stacks boot.
      // ⛔ Not `trackPlugin`ed, for the announcer's reason above.
      if (productionResolvedNoStorage) {
        // ONE list, rendered as the refusal's bullets and as the line's sentence.
        const noStorageRemedies = [
          'set OS_DATABASE_URL (e.g. file:./data/app.db, or a postgres:// or mysql:// URL)',
          "mount a storage driver in the stack's plugins (e.g. new DriverPlugin(driver) from @objectstack/runtime)",
          'run with --dev (an in-memory SQLite store, for development)',
        ];
        await kernel.use({
          name: 'com.objectstack.cli.no-storage-boot-guard',
          version: '1.0.0',
          init: async (ctx: any) => {
            const services: Map<string, any> = ctx.getServices();
            const engine = services.get('objectql');
            const hasDriver = [...services.keys()].some((name) => name.startsWith('driver.'))
              || (typeof engine?.getDefaultDriverName === 'function'
                && engine.getDefaultDriverName() !== undefined);
            if (hasDriver) return;
            if (services.has('auth') && services.get('tenancy')?.posture === 'single') {
              restoreOutput();
              console.error(chalk.red(
                '\n  ✖ This production serve has no storage: no recognized OS_DATABASE_URL declared a\n'
                + '    default datasource, and no plugin registered a storage driver by the end of plugin\n'
                + "    init. The auth service runs under the 'single' tenancy posture, and its start()\n"
                + '    creates the Default Organization, which needs a driver.\n\n'
                + '    Fix one of:\n'
                + noStorageRemedies.map((remedy) => `      • ${remedy}\n`).join(''),
              ));
              throw new Error(
                'Refusing to boot: this production serve has no storage, and its auth service needs a '
                + 'driver when it starts. Set OS_DATABASE_URL, mount a storage driver plugin, or run with --dev.',
              );
            }
            console.warn(chalk.yellow(
              '  ⚠ No storage: no recognized OS_DATABASE_URL, and no plugin registered a storage driver by '
              + 'the end of plugin init, so objects have no store unless a plugin registers one when it '
              + `starts. Fix: ${noStorageRemedies[0]}; ${noStorageRemedies[1]}; or ${noStorageRemedies[2]}.`,
            ));
          },
        } as any);
      }

      // Boot the runtime
      await runtime.start();

      // Brief delay to allow logger writes to flush before restoring stdout
      await new Promise(r => setTimeout(r, 100));
      restoreOutput();

      // ── Secret-field CryptoProvider wiring (host composition root) ──
      // objectql's `secret` field type encrypts on write to `sys_secret`
      // and fails closed when no ICryptoProvider is registered. objectql
      // must NOT depend on a crypto implementation (layering), so the
      // host injects one here. Dev/self-host gets a LocalCryptoProvider
      // (AES-256-GCM keyed off `OS_SECRET_KEY` or a persisted dev key);
      // production hosts swap this for a KMS/Vault-backed provider (e.g.
      // via an env-gated branch or a dedicated plugin) before secrets are
      // written. We resolve the data engine by its registered service name
      // and feature-detect `setCryptoProvider` so older engines / alternate
      // data services degrade gracefully (writing a secret then fails
      // closed, as designed, rather than silently storing cleartext).
      try {
        const dataEngine: any =
          kernel.getService?.('data') ?? kernel.getService?.('objectql');
        if (dataEngine && typeof dataEngine.setCryptoProvider === 'function') {
          if (!sharedCryptoProvider) {
            const { LocalCryptoProvider } = await import(
              /* webpackIgnore: true */ '@objectstack/service-settings'
            );
            // In production LocalCryptoProvider throws when no stable key
            // (OS_SECRET_KEY / persisted file) is available — the fail-loud
            // guard against silently minting an ephemeral key and losing
            // every sys_secret value after a restart. Let that error be loud:
            // secret writes must not proceed under an unstable key.
            sharedCryptoProvider = new LocalCryptoProvider();
          }
          dataEngine.setCryptoProvider(sharedCryptoProvider);
          if (isDev) {
            printDiagnostic(
              chalk.dim(
                '  ↪ secret fields: LocalCryptoProvider wired (dev) — set OS_SECRET_KEY and swap for KMS/Vault in production',
              ),
            );
          }
        }
      } catch (err: any) {
        const msg = String(err?.message ?? err);
        if (msg.includes('Refusing to start in production')) {
          // Fail-loud config error: print the actionable guidance verbatim.
          console.error(chalk.red(msg));
          throw err;
        }
        // Otherwise non-fatal: without a provider, secret writes fail closed
        // by design. Surface a hint so operators know why a `secret` field
        // write might reject.
        console.warn(
          chalk.yellow(
            `  ⚠ secret fields: no CryptoProvider wired (${msg}); writing a secret field will fail closed`,
          ),
        );
      }

      // ── Migrate-and-exit short-circuit ─────────────────────────────
      // Out-of-band migration mode: the caller (e.g.
      // `apps/cloud/scripts/migrate.ts`, which lives in the separate
      // `objectstack-ai/cloud` repo and is NOT a path in this one) just
      // wants the kernel bootstrap (ObjectQLPlugin → schema sync →
      // metadata hydration) to run once against the configured database,
      // then exit. The HTTP server has already bound `port` at this point
      // but we never accept a request — shutdown immediately so the
      // deploy pipeline can move on.
      if (process.env.OS_MIGRATE_AND_EXIT === '1') {
        // This path exits before the banner, so it has to replay the boot
        // diagnostics itself — a deploy pipeline is precisely where a
        // degraded-boot warning must not vanish (#4012).
        const migrateDiagnostics = collectBootDiagnostics();
        if (migrateDiagnostics) printBootDiagnostics(migrateDiagnostics);
        printDiagnostic(chalk.green(`✓ Migration complete (${loadedPlugins.length} plugins started against ${resolvedDatabaseUrl ? redactConnectionUrl(resolvedDatabaseUrl) : 'configured DB'})`));
        try {
          await kernel.shutdown();
        } catch (err: any) {
          console.warn(chalk.yellow(`  ⚠ shutdown warning: ${err?.message ?? err}`));
        }
        process.exit(0);
      }

      // ── Driver introspection ──────────────────────────────────────
      // When the driver was registered by an app preset / per-project
      // factory (EnvironmentKernelFactory) instead of serve.ts's own
      // OS_DATABASE_URL fallback, `resolvedDriverLabel` is still
      // unset. Probe well-known service names so the banner can show
      // *something* useful regardless of who wired the driver.
      if (!resolvedDriverLabel) {
        try {
          const probe = describeRegisteredDriver(kernel);
          if (probe) {
            resolvedDriverLabel = probe.label;
            resolvedDatabaseUrl = probe.url;
            servedSqliteFilePath = probe.sqliteFile;
          }
        } catch {
          // best-effort only
        }
      }

      // Surface the dev admin seeded this boot (if any) in the banner. The
      // seed runs in-process during runtime.start() under serve's boot-quiet
      // window, so plugin-auth records the result on the `auth` service and
      // we print it here, after stdout is restored. Visible in both
      // `serve --dev` and `os dev` (the child's stdout is inherited).
      let seededAdmin: { email: string; password: string } | undefined;
      try {
        const authSvc: any = kernel.getService?.('auth');
        if (authSvc?.devSeedResult?.email) seededAdmin = authSvc.devSeedResult;
      } catch { /* auth service not present — nothing to show */ }

      // ── Automation wiring summary (2026-07-17 third-party eval) ─────
      // A flow that silently failed to arm logs nothing at all, so no amount of
      // log plumbing answers "did my flows arm?" — the binding STATE has to be
      // read off the live engine. Collect it here (after restore) and surface it
      // in the banner: declared-but-engine-missing, unbound triggered flows, and
      // bound-but-dead (unknown object) flows.
      // [#22288] Counted by `resolveStackCollection`'s rule, so a flow a
      // package declares is counted: the "declared but the automation engine is
      // not enabled" line used to stay silent for every multi-package app.
      const automationSummary = collectAutomationSummary(
        kernel,
        resolveStackCollection(config, 'flows').length,
      );

      // ── Seed outcome summary (#3415/#3430) ─────────────────────────
      // SeedLoader's own result logs are `info`, under the default warn
      // level — a fixture could lose 90% of its rows, or a marketplace
      // package rehydrate onto a fresh DB with zero rows, all with zero
      // terminal signal. (The boot-quiet window hid them at every level on
      // top of that until #4012.) AppPlugin and the
      // marketplace rehydrate/heal path stash a per-source entry on the
      // kernel; print them here, loudly when rows dropped or an install
      // came up empty.
      let seedSummary: SeedSourceSummary[] | undefined;
      try {
        const s: any = kernel.getService?.('seed-summary');
        if (Array.isArray(s) && s.length > 0) seedSummary = s;
      } catch { /* no seeds ran — nothing to show */ }

      // ── Degraded-capabilities readout (#16630) ─────────────────────
      // The banner and the kernel's `System started with degraded
      // capabilities. Missing core services: …` warning used to be two
      // statements about one boot with NO data path between them — printed
      // from two packages, and the louder one (`✓ Server is ready`) was the
      // wrong one. This read IS that path: the same kernel handle the two
      // reads above use, the same `getService` accessor, and the kernel's own
      // list handed on untouched. ⛔ Nothing here decides which services count
      // as core — that judgement stays in one place, `ServiceRequirementDef`.
      // Absent on every healthy boot, where the banner is unchanged.
      const missingCoreServices = readMissingCoreServices(kernel);

      // ── Multi-node licence reading → telemetry (#12667) ────────────
      // The advisory the gate produced at boot, published where a deployment's
      // metrics pipeline already looks. Emitted HERE, after every plugin has
      // been registered, so a host that mounts its own
      // `ObservabilityServicePlugin` is covered as well as serve's own
      // auto-wired one — the auto-wire block runs long before the config
      // plugins, and resolving there would have reached only half the hosts.
      //
      // ⛔ Visibility only. This publishes the SAME advisory verdict the boot
      // warning renders as prose; it refuses nothing, counts no peers, and must
      // never be reworded into a claim that it does. See
      // `describeMultiNodeCapTelemetry` for why a real membership count is not
      // available to this process at all.
      if (multiNodeVerdict) emitMultiNodeCapTelemetry(kernel, multiNodeVerdict);

      // ── The port this process ACTUALLY bound (#13062) ─────────────
      // Read ONCE, here, and handed to every channel that announces an address:
      // the ready banner below, the `objectstack:listening` IPC message and
      // `runtime.<environment>.<project>.json`. Those three were three outputs
      // of ONE number, and that number was the port that had been REQUESTED
      // — equal to the bound one for every value except the one where it can never be
      // (`--port 0`), which is how all three came to announce `localhost:0`
      // with nothing erroring.
      //
      // ⭐ One read, not three. Three call sites would be free to disagree, and
      // what this repairs is exactly a set of channels that agreed with each
      // other while disagreeing with the socket.
      const boundPort = resolveBoundPort(kernel, port);
      // [#23623] …and whether there is a transport at all, from the same read
      // ({@link readComposedHttpServer}). On a boot with none, the banner's
      // address rows give way to one line saying so (#23623), and nothing is
      // published on the two machine channels either (#23743): see the
      // publish site below. ⭐ ONE predicate for all three channels, so the
      // banner, the IPC message and the state file cannot disagree about
      // whether there is an address at all.
      const httpServer = resolveHttpServerComposition(kernel, flags.server);
      // [#23743] …and whether `/api/v1/mcp` is mounted, for the banner's `MCP:`
      // row. A composed transport is not enough: the route's owner is the
      // runtime dispatcher, which this command composes only under `--server`,
      // so a config that mounts its own `HonoServerPlugin` under `--no-server`
      // listens while `/api/v1/mcp` answers 404. See
      // {@link readComposedMcpRouteOwner}.
      const mcpRouteMounted = httpServer === 'composed' && readComposedMcpRouteOwner(kernel);

      // ── Clean startup summary ──────────────────────────────────────
      // #8978 — the Config:/Artifact: row must name what actually booted,
      // never `relativeConfig` unconditionally (see resolveBannerConfigRow).
      //
      // ⭐ A THUNK, not a call (commit faff497fd). The banner is one of the three
      // bound-port channels, and {@link publishBoundPort} owns the order the
      // three fire in — the state file has to be on disk before anything
      // announces the address that names it. Nothing INSIDE this literal
      // changed, and nothing in it is async, so deferring it to the call a few
      // lines below is a pure move.
      const printBanner = () => printServerReady({
        // #10646 — the banner used to take `port` and compose
        // `http://localhost:<port>` itself, which is where this process
        // LISTENS, not where an operator can reach it. On the EE 4.1.0 compose
        // stack that address is `expose`-only (no `ports:` mapping, and less
        // reachable still under `--scale app=N`) while Caddy publishes `:80`
        // and `OS_AUTH_URL` is already `http://localhost` — so the Console link
        // 404'd at the shell and the `MCP:` line customers paste into an AI
        // client could never connect.
        //
        // Resolved through the runtime's OWN chain, not a banner-local copy of
        // it: `resolveAuthBaseUrl` is the same function whose `baseOrigin` is
        // pushed onto the CSRF allow-list a few hundred lines above, so the
        // banner cannot disagree with what the deployment actually trusts. It
        // reads only `process.env` and the port, so calling it here changes
        // nothing about what is bound or advertised — this is printed text.
        //
        // `boundPort` is the port the server ACTUALLY bound — read back off the
        // transport that bound it ({@link resolveBoundPort}), not the number
        // this process was asked for. So the `http://localhost:<port>` tail of
        // the chain still names the right address in the local dev loop,
        // including under `--port 0`, where the requested value can never be
        // the bound one. `baseOrigin` is `null` when the chain produced
        // something unparseable; the banner then prints paths with no origin
        // rather than a confident wrong URL.
        externalBaseOrigin: resolveAuthBaseUrl(boundPort, boundProtocol).baseOrigin,
        // #23623 — whether any address above is served at all. See `httpServer`
        // a few lines up.
        httpServer,
        ...resolveBannerConfigRow({ relativeConfig, useArtifactFallback, pinnedArtifact, configBootBundle }),
        isDev,
        pluginCount: loadedPlugins.length,
        pluginNames: loadedPlugins,
        uiEnabled: enableUI,
        consolePath: loadedPlugins.includes('ConsoleUI') ? CONSOLE_PATH : undefined,
        driverLabel: resolvedDriverLabel,
        databaseUrl: resolvedDatabaseUrl ? redactConnectionUrl(resolvedDatabaseUrl) : undefined,
        // [ADR-0105 D1] #4801 — the banner reads the SAME resolver the runtime
        // wiring above keys off (`resolveTenancyPosture()`), not the legacy
        // boolean `resolveMultiOrgEnabled()`. With `OS_TENANCY_POSTURE=isolated`
        // and `OS_MULTI_ORG_ENABLED` unset, the boolean says `false` while the
        // wall is up — the banner printed `single-tenant` on the same screen
        // that listed `Organizations` in the plugin table (cloud#1020). A
        // diagnostic surface that disagrees with the runtime costs every later
        // investigation an extra lap.
        // #5359 — the value the boot gate resolved once at the top of `run()`,
        // not a fresh parse. The banner reading the resolver directly was also
        // the LAST line of defence against an invalid posture, which made a
        // diagnostic surface load-bearing for a safety property; the gate above
        // owns that refusal now, and this row just reports what it decided.
        tenancyPosture,
        seededAdmin,
        // #17556 — read straight off the definition this process booted, the
        // same object `config.devPlugins` is read from twenty lines up. The
        // platform describes the account it seeded; only the APPLICATION knows
        // which of its audiences shows something, and these two keys are how it
        // says so. `printServerReady` gates them on `isDev` and scrubs them —
        // they are author-controlled text reaching a terminal.
        devLogins: Array.isArray((config as any)?.devLogins) ? (config as any).devLogins : undefined,
        devHint: typeof (config as any)?.devHint === 'string' ? (config as any).devHint : undefined,
        automation: automationSummary,
        seeds: seedSummary,
        // #17329 — read HERE, inside the banner thunk, so it is the tally as of
        // the moment the banner prints rather than one sampled earlier in the
        // boot. On the over-budget path `seedSummary` above is `undefined` —
        // the summary is recorded only when the load FINISHES — so without this
        // the transcript of a boot whose seed is still writing is
        // byte-identical to one that declared no seeds at all, which is how
        // this defect hid: the louder the seed went on to fail, the more
        // complete the omission looked at the moment it was read.
        seedSettlement: readSeedSettlement(kernel),
        // #16630 — what the kernel already knows about this boot, so the ready
        // line can say what state it is ready in. `undefined` on a healthy
        // boot, where the ready block prints exactly what it always has.
        missingCoreServices,
        // #4012 — every boot-phase `logger.warn` the quiet window intercepted,
        // replayed here. Without this the window is a drain: the ADR-0110 D5
        // `[action-governance]` inventory, degraded-boot notices and flow
        // binding failures all reached stdout and none reached a terminal.
        bootDiagnostics: collectBootDiagnostics(),
        // #3167 — surface the default-on MCP endpoint in the dev loop, where an
        // AI client can connect to operate the running app. Same decision point
        // that auto-loads the plugin + gates the route. It is not the whole
        // answer: with no HTTP server composed nothing serves the route, and
        // the banner drops the row on `httpServer` (#23623); with a server but
        // no dispatcher, the route is not mounted and answers 404, so the row
        // also needs `mcpRouteMounted` (#23743).
        mcpEnabled: isMcpServerEnabled() && mcpRouteMounted,
      });

      // ── Publish the actually-bound port ────────────────────────────
      // `boundPort` here is the port the HTTP server actually bound, read back
      // off the transport ({@link resolveBoundPort}) — ⛔ NOT `port`, the number
      // this process was ASKED for. This comment used to claim `port` was the
      // bound one, and it was not: the two part company whenever `listen()`
      // CHOSE the port rather than accepting it — under `--port 0` always, and
      // whenever the transport's own bind walked past a port taken between this
      // command's probe and that `listen()`. (Past a DEV auto-shift `port` is
      // already right, because `getAvailablePort()` reassigned it; that is the
      // reading under which the old sentence looked true.) Publish the bound
      // one so supervisors and the `os dev` parent never have to guess:
      //   • runtime.json: a small state file under OS_HOME for external
      //     supervisors / health checks (pid + port + url).
      //   • the ready banner, whose `API:` row names the same address (when an
      //     HTTP server is composed; with none it prints no address, #23623).
      //   • IPC: when spawned with an 'ipc' channel (as `os dev` does), the
      //     parent learns the real port without polling.
      //
      // ⭐ That list is in ORDER, and the order is the whole point (commit faff497fd):
      // the file is written BEFORE either channel announces the address that
      // sends a consumer to it, and the banner is printed whole BEFORE the
      // message that makes the `os dev` parent print into the same terminal
      // (#22410). {@link publishBoundPort} carries both races the old orders
      // lost, and the reason neither repair is a reader-side poll or a timer.
      //
      // [#23743] …and all of that only when a transport BOUND a port. With
      // none composed (`--no-server` and no config-mounted transport, or a
      // transport plugin that did not load), `boundPort` is the REQUESTED
      // number — {@link resolveBoundPort} falls back to it by design — and
      // nothing listens there. `objectstack:listening` is documented as "The
      // HTTP server is bound" (`content/docs/deployment/cli.mdx`), so such a
      // boot sends no such message, and it writes no runtime state file either:
      // that file's whole payload answers "is my server running, and where?",
      // and a missing file is the loud, correct answer when there is none
      // ({@link runtimeStateFileName}). ⛔ No "unbound" record instead: the
      // payload stays the one shape every reader already parses. The banner
      // still prints, and says once that no address is served (#23623).
      // ⭐ Gated on the SAME `httpServer` the banner's address rows read, so
      // the three channels cannot disagree about whether there is an address.
      if (httpServer === 'composed') {
        publishBoundPort(boundPort, runtimeBoundPortChannels(printBanner), boundProtocol);
      } else {
        printBanner();
      }

      // ── …and one beat later, whether the APP is ready too (#17329) ──
      // ⭐ AFTER the line above, and that is the whole of the ordering
      // contract: a parent that waits for `objectstack:listening` and only then
      // starts listening for the settle can never miss it, because nothing is
      // sent before this call. On the ordinary in-budget boot seeding settled
      // minutes of CPU ago and this releases the latched message immediately;
      // past the budget it arms and the `app:seeded` hook speaks later.
      //
      // [#23743] On a boot that binds no HTTP server no `objectstack:listening`
      // is sent at all, and this message is still sent: it is then the boot's
      // only message. A kernel-only boot still seeds, and a parent waiting for
      // the settle must not wait forever for a message that is never coming —
      // the rule {@link SeedSettledMessage} exists for.
      //
      // ⛔ NOT a fourth channel inside `publishBoundPort`. Those three are one
      // publication of ONE number, ordered so the file exists before anything
      // names it; this is a different fact on a different clock that frequently
      // has not happened yet.
      seedSettlement.release();

      // ── Watch the served database file's identity ──────────────────
      // Deleting the data directory under a running server (`rm -rf
      // .objectstack/data`, what `demo:reset` does) unlinks the inode without
      // touching this process: SQLite keeps serving the now-invisible file,
      // health keeps answering 200, and a later boot creates a brand-new
      // database at the same path. From then on every filesystem inspection of
      // that path describes a DIFFERENT file than this server answers from —
      // which is how "the row I edited had no effect" and "the user who just
      // authenticated is not in the database" become simultaneously true
      // readings of a healthy deployment.
      //
      // Started only once the boot is otherwise complete, so a failure here
      // can never be mistaken for a boot problem, and only when an on-disk
      // SQLite file is actually being served. It refuses nothing and reports
      // once — see `served-database-file.ts` for why both.
      if (servedSqliteFilePath) {
        const openedDatabaseFile = captureServedDatabaseFile(servedSqliteFilePath);
        if (openedDatabaseFile) {
          watchServedDatabaseFile({
            opened: openedDatabaseFile,
            // `error`, and to stderr: by the degradation-log-level rule this is
            // the durability/consistency class — the system keeps looking
            // normal while what it claims is persisted is not at the path it
            // names.
            onDiverged: (message) => { console.error(chalk.red(message)); },
          });
        }
      }

      // Kernel already registers SIGINT/SIGTERM handlers during bootstrap.
      // No duplicate handler needed here — just keep the process alive.
      //
      // [#23744] On a composed boot the HTTP listener is what keeps it alive.
      // With no transport composed (the SAME `httpServer` the banner and the
      // publish site above read), nothing this command owns held the event
      // loop: the process exited 0 milliseconds after a banner ending `Press
      // Ctrl+C to stop`, unless the storage driver happened to keep a pool.
      // Hold it until the kernel stops — see {@link holdKernelOnlyProcess}.
      if (httpServer !== 'composed') holdKernelOnlyProcess(kernel);

    } catch (error: any) {
      restoreOutput();
      printDiagnostic();
      // [ADR-0131 D10, development exception] A development child of `os dev`
      // refused for the v17 organization-ownership shape tells its parent,
      // which copies the development database, upgrades it in place and boots
      // it again (`utils/dev-organization-ownership-upgrade.ts`) — so the
      // refusal is not printed as this boot's failure. Any other boot refuses
      // as before, naming the ceremony.
      //
      // The guard refuses from its `start()` (before any plugin writes a row),
      // so the kernel hands it on as the `cause` of its own start-failure
      // error: the refusal is looked for down the chain, and its own text is
      // what this boot prints.
      const { isOrganizationOwnershipBootRefusal } = await import('@objectstack/runtime');
      let ownershipRefusal: { tables: readonly string[]; message: string } | undefined;
      for (let cause: unknown = error, depth = 0; !ownershipRefusal && cause && typeof cause === 'object' && depth < 8; depth++) {
        if (isOrganizationOwnershipBootRefusal(cause)) ownershipRefusal = cause;
        cause = (cause as { cause?: unknown }).cause;
      }
      if (ownershipRefusal && isDev && typeof process.send === 'function') {
        const sent = await announceOrganizationOwnershipRequired([...ownershipRefusal.tables]);
        if (sent) this.exit(1);
      }
      printError(ownershipRefusal?.message || error.message || String(error));
      // A boot that died is when its warnings matter most, and the banner that
      // would normally carry them never printed (#4012).
      const diagnostics = collectBootDiagnostics();
      if (diagnostics) printBootDiagnostics(diagnostics);
      if (process.env.DEBUG) console.error(chalk.dim(error.stack));
      this.exit(1);
    }
  }

}

/**
 * The plugin that mounts the datasource admin REST routes (`/api/v1/datasources`,
 * `registerDatasourceAdminRoutes` from `@objectstack/service-datasource`) onto
 * the composed HTTP server, from its own `init()`. Exported (#24022) so that
 * `init` is reachable from a test against a real kernel, as
 * {@link createUnknownHostnameGuardPlugin}'s is.
 *
 * ## The read
 *
 * The server is read through {@link readComposedHttpServer}: `http.server`
 * only, inside a `try`, because the kernel's `getService` THROWS on a name
 * nothing registered. The `getService?.(…) ?? getService?.(…)` chain this
 * replaced never reached its `??`: on a boot with no server (`--no-server`)
 * the throw landed in the registration `catch`, which printed "route
 * registration failed" with the kernel's "composition/ordering fault" text
 * when nothing was at fault.
 *
 * ## Which warning prints, and when
 *
 * - No server composed: the plugin's own degrade line, once. It is kept under
 *   `--no-server` on purpose. The banner says why there is no server; this
 *   line names the surface that leaves unmounted, beside the same boot's
 *   other "not mounted" lines (REST API, runtime config, marketplace
 *   install). A config can still compose its own server under that flag, and
 *   then the routes mount. It never says "ordering fault".
 * - A server composed, and registration throws: "route registration failed"
 *   with the error. That is a genuine fault and stays loud.
 *
 * `optionalDependencies` orders the Hono server plugin ahead when it is
 * composed (ADR-0116), so an absent server at this `init` is final for it.
 */
export function createDatasourceAdminRoutesPlugin(
  registerRoutes: (server: any, ctx: any, basePath: string) => void,
) {
  return {
    name: 'com.objectstack.cli.datasource-admin-routes',
    version: '1.0.0',
    optionalDependencies: ['com.objectstack.server.hono'],
    init: async (ctx: any): Promise<void> => {
      const httpServer: any = readComposedHttpServer(ctx);
      if (!httpServer || typeof httpServer.get !== 'function') {
        ctx.logger?.warn?.('[datasource-admin] http.server unavailable; REST routes not installed');
        return;
      }
      try {
        registerRoutes(httpServer, ctx, '/api/v1');
      } catch (routeErr: any) {
        ctx.logger?.warn?.(`[datasource-admin] route registration failed: ${routeErr?.message ?? routeErr}`);
      }
    },
  };
}

/**
 * What {@link createUnknownHostnameGuardPlugin} is constructed with.
 */
export interface UnknownHostnameGuardOptions {
  /**
   * The platform apex, e.g. `objectos.ai` — `OS_ROOT_DOMAIN` in production.
   * Normalized here (trim + lowercase) as well as at the call site, so the guard
   * cannot be constructed with a casing the `Host` comparison would then miss.
   */
  rootDomain: string;
  /**
   * Reads the cloud control-plane URL for the `/_console` redirect branch.
   *
   * A FUNCTION, not a string, and called PER REQUEST — that is what production
   * does (`process.env.OS_CLOUD_URL` was read inside the middleware, not at
   * install time), and extracting the seam must not quietly move the read to
   * construction time. Defaults to the same env read.
   */
  readCloudUrl?: () => string;
}

/** The plugin object {@link createUnknownHostnameGuardPlugin} returns. */
export interface UnknownHostnameGuardPlugin {
  name: string;
  version: string;
  optionalDependencies: string[];
  init: (ctx: any) => Promise<void>;
}

/**
 * Subdomains that bypass the guard, plus the apex (`''`).
 *
 * Exported so a test iterates the SAME list the middleware branches on. A copy
 * in the test would go stale the day a subdomain is added here: the new one
 * would ship uncovered while the suite stayed green.
 */
export const UNKNOWN_HOSTNAME_GUARD_RESERVED_SUBDOMAINS: ReadonlySet<string> = new Set([
  '', 'cloud', 'www', 'api', 'docs', 'admin', 'app',
]);

/**
 * Health and readiness paths that always pass through, whatever the hostname.
 *
 * Load-bearing, not a nicety: Cloudflare's container probe (and any upstream
 * load balancer) hits whatever `Host` header is currently bound to the worker,
 * so a 404 here would kill the container. Exported for the same reason as the
 * reserved list — a probe path added here is covered the moment it is added.
 */
export const UNKNOWN_HOSTNAME_GUARD_HEALTH_PATHS: readonly string[] = [
  '/api/v1/health', '/api/v1/ready', '/health',
];

/**
 * The unknown-environment hostname guard, as a mountable plugin (#9442).
 *
 * In multi-tenant cloud deployments (e.g. *.objectos.ai), every public hostname
 * is expected to map to a `sys_environment` row whose `hostname` column matches
 * the request `Host`. Without this guard, an unknown subdomain like
 * `demo-xxx.objectos.ai` happily renders the control-plane Console SPA (served
 * statically by createConsoleStaticPlugin), making the deployment look like an
 * empty env rather than a missing one. It answers a clear 404 instead.
 *
 * The bypass matrix, in the order the middleware applies it:
 *
 *   1. no `Host` header, or a host outside `rootDomain` (custom domains,
 *      localhost, *.workers.dev) — pass through, unjudged;
 *   2. a reserved subdomain or the apex ({@link
 *      UNKNOWN_HOSTNAME_GUARD_RESERVED_SUBDOMAINS}) — pass through, except that
 *      a cloud-connected runtime redirects `/_console` to the control plane so
 *      the Console picks an environment rather than dying on a 404 login;
 *   3. `/_admin`, `/_admin/*` and `/.well-known/*` — always through, so cert
 *      flows are not broken;
 *   4. {@link UNKNOWN_HOSTNAME_GUARD_HEALTH_PATHS} — always through;
 *   5. no env-registry service, or a registry read that throws — through. Every
 *      failure mode falls through rather than refusing;
 *   6. registry hit — through. Registry MISS is the only refusal.
 *
 * Implemented as a Plugin so the middleware is wired during init (when
 * `http.server` is available) and BEFORE start() runs on the Console static
 * plugin / route-registering plugins. Phase 1 `init()` is the REQUIREMENT, not
 * a convenience: Hono composes the handlers a request matched in REGISTRATION
 * order, so a route registered ahead of this middleware answers and never calls
 * `next()`, and the guard never runs for that path. Route registration starts
 * in Phase 2 `start()` (createConsoleStaticPlugin mounts the Console there) and
 * continues in the `kernel:ready` hooks registered from it (HonoServerPlugin's
 * current-user endpoints, plugin-auth's terminal `/api/v1/auth/*`), while both
 * kernels run every plugin's `init()` before the first `start()`
 * (`LiteKernel.bootstrap`, `ObjectKernel.bootstrap`) — so an install from
 * `init()` is ahead of all of it.
 *
 * ⛔ "Added before kernel:listening" is NOT the condition, however natural it
 * reads. `kernel:ready`, `kernel:bootstrapped` and `kernel:listening` all fire
 * strictly AFTER Phase 2, so a guard installed from one of those hooks is
 * registered behind every route and observes NOTHING — no error, no log, no
 * refusal (#9745, measured across three install points). A refusal surface that
 * gates nothing is the failure this guard exists to prevent, so anything
 * modelled on it installs during `init()`. Both directions are pinned in
 * `serve-unknown-hostname-guard.test.ts`.
 *
 * The env-registry is resolved lazily per request on purpose: it is
 * registered by ObjectOSEnvironmentPlugin's init, and the guard must not depend
 * on plugin ordering to work.
 *
 * ⛔ The refusal `c.json({ ... }, 404)` inside the middleware must stay an
 * INLINE OBJECT LITERAL. `scripts/check-route-envelope.mjs` judges the object
 * literal passed to `c.json(...)`; an identifier or a call expression reads to
 * it as a relayed body it must not police. Hoisting that body into a helper —
 * even into this file — leaves the file discovered (the `c.json(` call is still
 * here) while every counter reads zero, so the `{}` entry this file carries in
 * `PLUGIN_ROUTE_MODULES` keeps passing and stops asserting: the #9364
 * conformance pin goes vacuous, silently, with the gate green.
 */
export function createUnknownHostnameGuardPlugin(
  options: UnknownHostnameGuardOptions,
): UnknownHostnameGuardPlugin {
  const rootDomain = (options.rootDomain || '').trim().toLowerCase();
  const readCloudUrl = options.readCloudUrl ?? (() => process.env.OS_CLOUD_URL || '');
  const RESERVED = UNKNOWN_HOSTNAME_GUARD_RESERVED_SUBDOMAINS;
  const HEALTH_PATHS = UNKNOWN_HOSTNAME_GUARD_HEALTH_PATHS;
  return {
    name: 'com.objectstack.cli.unknown-hostname-guard',
    version: '1.0.0',
    // init() resolves the `http.server` service the hono server plugin
    // provides — order-if-present so the middleware install is
    // deterministic (ADR-0116, #4471). Soft: without a server plugin the
    // guard degrades on purpose (warn + not installed).
    optionalDependencies: ['com.objectstack.server.hono'],
    init: async (ctx: any) => {
      try {
        const httpServer: any = readComposedHttpServer(ctx);
        const rawApp = httpServer?.getRawApp?.();
        if (!rawApp || typeof rawApp.use !== 'function') {
          ctx.logger?.warn?.('[unknown-hostname-guard] http.server unavailable; guard not installed');
          return;
        }
        const getEnvRegistry = () => {
          try {
            return ctx.getService?.('env-registry') ?? null;
          } catch {
            return null;
          }
        };
        rawApp.use('*', async (c: any, next: any) => {
          const rawHost = c.req.header('host') || '';
          const host = rawHost.split(':')[0].toLowerCase();
          if (!host) return next();
          const isPlatformHost = host === rootDomain || host.endsWith('.' + rootDomain);
          if (!isPlatformHost) return next();
          const sub = host === rootDomain ? '' : host.slice(0, -(rootDomain.length + 1));
          const head = sub.split('.').pop() || '';
          const p = c.req.path;
          if (RESERVED.has(sub) || RESERVED.has(head)) {
            // A browser loading the Console on a bare/reserved platform host
            // (the apex or `www`/`app`/… — none bind a tenant env) gets the
            // Console SPA, but its `/api/v1/auth/*` calls 404 (no env → no
            // auth) → a dead "Auth request failed with status 404" login.
            // When this runtime is cloud-connected (`OS_CLOUD_URL` set), send
            // Console requests to the cloud control plane to pick/open an
            // environment instead. A self-hosted single-env runtime (no
            // `OS_CLOUD_URL`) keeps the prior pass-through. Non-console paths
            // (infra, health, /api) fall through below unchanged.
            const cloudUrl = readCloudUrl().trim();
            if (cloudUrl && (p === '/_console' || p.startsWith('/_console/'))) {
              return c.redirect(`${cloudUrl.replace(/\/+$/, '')}/_console/`, 302);
            }
            return next();
          }
          if (p.startsWith('/_admin/') || p === '/_admin' || p.startsWith('/.well-known/')) {
            return next();
          }
          // Health and readiness endpoints must always answer 200
          // regardless of whether the requested hostname maps to
          // an env — Cloudflare's container probe (and any
          // upstream load balancer) hits whatever Host header is
          // currently bound to the worker. Returning 404 here on
          // an unmapped hostname would kill the container.
          if (HEALTH_PATHS.includes(p)) {
            return next();
          }
          // Resolve env-registry lazily on each request — it may
          // not be registered yet at init() time (registered by
          // ObjectOSEnvironmentPlugin's init which runs in plugin
          // dependency order; we don't want to rely on ordering).
          const registry: any = getEnvRegistry();
          if (!registry || typeof registry.resolveByHostname !== 'function') {
            return next();
          }
          try {
            const hit = await registry.resolveByHostname(host);
            if (hit) return next();
          } catch {
            return next();
          }
          // Content negotiation: browsers (Accept: text/html) get
          // a clean 404 page; API clients (curl/fetch with JSON
          // accept) get a structured error body.
          const accept = (c.req.header('accept') || '').toLowerCase();
          const wantsHtml = accept.includes('text/html');
          if (wantsHtml) {
            const safeHost = host.replace(/[<>&"']/g, (ch: string) => ((({
              '<': '&lt;', '>': '&gt;', '&': '&amp;', '"': '&quot;', "'": '&#39;',
            } as Record<string, string>)[ch]) ?? ch));
            const html = `<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width,initial-scale=1" />
<title>404 — Environment not found</title>
<style>
  :root { color-scheme: light dark; }
  * { box-sizing: border-box; }
  html, body { height: 100%; margin: 0; }
  body {
    font: 16px/1.5 -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
    background: #fafafa;
    color: #111111;
    display: grid;
    place-items: center;
    padding: 24px;
  }
  @media (prefers-color-scheme: dark) {
    body { background: #0b0b0c; color: #e8e8e8; }
    .card { background: #141417; border-color: #26262b; }
    .host { background: #1c1c20; border-color: #2d2d33; color: #d0d0d0; }
    .muted { color: #8b8b94; }
    a { color: #6ea8fe; }
  }
  .card {
    max-width: 520px;
    width: 100%;
    background: #fff;
    border: 1px solid #e6e6e6;
    border-radius: 12px;
    padding: 32px;
    box-shadow: 0 1px 2px rgba(0,0,0,.04);
    text-align: center;
  }
  .code { font: 600 64px/1 ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; margin: 0; letter-spacing: -2px; }
  h1 { font-size: 20px; margin: 16px 0 8px; font-weight: 600; }
  p { margin: 8px 0; }
  .muted { color: #666666; font-size: 14px; }
  .host {
    display: inline-block;
    margin-top: 16px;
    padding: 6px 12px;
    background: #f4f4f5;
    border: 1px solid #e4e4e7;
    border-radius: 6px;
    font: 13px ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
    color: #444444;
    word-break: break-all;
  }
  a { color: #2563eb; text-decoration: none; }
  a:hover { text-decoration: underline; }
</style>
</head>
<body>
  <main class="card">
    <p class="code">404</p>
    <h1>Environment not found</h1>
    <p class="muted">No ObjectStack environment is bound to this hostname.</p>
    <div class="host">${safeHost}</div>
    <p class="muted" style="margin-top:24px">
      If you own this domain, bind it to an environment in the
      <a href="https://cloud.objectos.ai/">ObjectStack Cloud console</a>.
    </p>
  </main>
</body>
</html>`;
            return c.html(html, 404);
          }
          // The declared `BaseResponseSchema` refusal envelope. This
          // used to answer `{ error: 'environment_not_found', message,
          // hostname }` — the pre-#3675 dialect, where `error` is a bare
          // string so `body.error.message` reads `undefined`, with two
          // stray top-level keys beside it. `hostname` is context and
          // moved into `error.details`, which `ApiErrorSchema` declares
          // for exactly that; the code is now the ADR-0112
          // SCREAMING_SNAKE spelling of the same condition, in the
          // semantic slot consumers branch on.
          return c.json(
            {
              success: false,
              error: {
                code: 'ENVIRONMENT_NOT_FOUND',
                message: `No environment is bound to hostname '${host}'.`,
                details: { hostname: host },
              },
            },
            404,
          );
        });
        ctx.logger?.info?.('[unknown-hostname-guard] installed', { rootDomain });
      } catch (err: any) {
        ctx.logger?.warn?.('[unknown-hostname-guard] install failed', { error: err?.message ?? err });
      }
    },
  };
}

/**
 * What the tenancy-posture boot gate decided (#5359).
 *
 * A verdict object rather than a throw: the caller is `serve`'s `run()`, and the
 * whole point of the gate is that the refusal must NOT travel as an exception —
 * an exception is exactly what the broad AuthPlugin `try` downgraded to a
 * warning while boot carried on unwalled.
 */
export type TenancyPostureGateVerdict =
  | { ok: true; posture: TenancyPosture }
  | { ok: false; fatal: string };

/**
 * Resolve the deployment's requested tenancy posture, or produce the FATAL text
 * that refuses the boot (#5359).
 *
 * `resolveTenancyPosture()` (`@objectstack/types`) is the authority on the
 * vocabulary and already refuses an unrecognized value — this wrapper does NOT
 * re-decide that, it only changes HOW the refusal travels and what it says.
 *
 * Why the wrapper exists at all: the resolver's refusal is a `throw`, and serve
 * used to take it wherever the first read happened to be. The first read sat
 * inside the broad AuthPlugin `try`, whose catch prints
 * `⚠ AuthPlugin failed to load: …` and continues — so a misspelled env var was
 * announced as a plugin problem, boot proceeded degraded through the whole
 * capability slate, and the real sentence only reached the operator much later,
 * bare, from a generic `printError`. The exit code was right; nothing else was.
 *
 * The message follows ADR-0093 D5's shape (the sibling refusal in this file, for
 * an unavailable multi-org runtime): name the fact, say it is refusing to boot,
 * say why the alternative is unacceptable, then prescribe every way out.
 */
export function resolveTenancyPostureOrRefusal(): TenancyPostureGateVerdict {
  try {
    return { ok: true, posture: resolveTenancyPosture() };
  } catch (err) {
    const raw = (globalThis as { process?: { env?: Record<string, string | undefined> } })
      .process?.env?.OS_TENANCY_POSTURE;
    const cause = err instanceof Error ? err.message : String(err);
    const fixes = TENANCY_POSTURES.map((posture) => {
      const hint = TENANCY_POSTURE_FIX_HINTS[posture];
      return `      • set OS_TENANCY_POSTURE=${posture}${hint ? ` — ${hint}` : ''}`;
    }).join('\n');
    return {
      ok: false,
      fatal: chalk.red(
        `\n  ✖ FATAL: OS_TENANCY_POSTURE=${JSON.stringify(String(raw ?? ''))} is not a recognized tenancy posture.\n`
        + '    Refusing to boot. Falling back to a default would silently drop the organization wall a\n'
        + '    walled deployment asked for — a posture typo must never be the thing that removes it\n'
        + '    (ADR-0105 D1; same refusal contract as ADR-0093 D5).\n\n'
        // Deliberately NOT "no port has been bound": serve probes port
        // availability (bind + immediate close) just above this gate, so that
        // sentence would be false in the letter while true in the spirit. What
        // is exactly true is the part an operator needs — no application code
        // ran and nothing ever served a request.
        + '    No config has been loaded, no plugin has been mounted, and the HTTP server was\n'
        + '    never started — this deployment has not served a single request.\n\n'
        + '    Fix one of:\n'
        + `${fixes}\n`
        + '      • unset OS_TENANCY_POSTURE entirely — the posture then derives from OS_MULTI_ORG_ENABLED\n'
        + '        (true ⇒ isolated, anything else ⇒ single).\n\n'
        + '    Checked the process environment and every .env file dotenv-flow loaded for this mode,\n'
        + '    so a stale value in a committed `.env*` is as likely a source as the shell.\n\n'
        + `    cause: ${cause}\n`,
      ),
    };
  }
}


/**
 * The diagnosis the optional i18n service load prints when it fails — a
 * DIAGNOSIS ahead of behaviour that does not change (#14042's rule, applied at
 * the one site its repair did not reach).
 *
 * The catch this feeds used to be bare. That was defensible on its stated
 * ground — a missing `@objectstack/service-i18n` is a supported configuration,
 * not a failure — and wrong about what it discarded: `createHostImporter`
 * classifies WHY a host import failed, and an empty catch throws that
 * classification away along with the absence it was written for. The two are
 * not the same event. A package the app DECLARES and that then fails to load
 * (a pruned install, a dist never built, a publish with no loadable entry)
 * reaches this catch as silence indistinguishable from "you never installed the
 * optional thing" — which is how a broken install reads as a deliberate opt-out.
 *
 * ⛔ It does NOT re-throw, and must not start to: the tolerance IS the point of
 * the catch. `i18n` is a `core` service with a kernel fallback
 * (`CORE_FALLBACK_FACTORIES` in `@objectstack/core` pre-injects
 * `createMemoryI18n` for every unprovided core service), it has no
 * `Serve.CAPABILITY_PROVIDERS` entry, and `requires: ['i18n']` opens the tier
 * without ever reaching the fail-fast branch that makes a missing provider a
 * hard boot error. So this is a FUNCTIONAL degradation in the AGENTS.md sense —
 * the deployment is visibly smaller and nothing that claims to persist is lost
 * — which is why it is `warn` and not `error`, and why the consequence is
 * stated before the diagnosis rather than after it.
 *
 * ## The kind wording is the importer's, deliberately
 *
 * Only the kind TOKEN is interpolated here; every word of remedy comes from
 * `err.message`, which `createHostImporter` composes per kind
 * (`undeclaredMessage` / `unresolvableMessage` / `noLoadableEntryMessage`).
 * That is what makes this site correct for all three kinds — and for the fourth
 * — without a branch table to go stale: #14270 exists because three OTHER
 * consumers picked their remedy with a two-way branch written when only two
 * kinds existed, and now hand `declared-no-loadable-entry` the "declare it in
 * your package.json" line for a package that is already declared AND installed.
 * A local re-wording here would join that population; deferring cannot.
 *
 * An error carrying NO kind resolved and then crashed while evaluating, which
 * is a different fact and gets a different sentence — swallowing that one is
 * how a package with a broken dependency reads as a package that was never
 * installed.
 *
 * Returns PLAIN text; the caller owns the channel (`console.warn` ⇒ stderr,
 * which `serve-stdio-stdout-purity.e2e.test.ts` requires of everything that is
 * not an MCP protocol frame).
 */
export function formatI18nLoadDiagnostic(pkg: string, err: unknown): string {
  const kind = hostImportFailureKind(err);
  // The stack is carried ONLY for the crash branch, where the throwing frame is
  // the diagnosis. A classified failure's `message` is already the whole
  // operator-facing text and its stack points at the importer, not at the cause.
  const detail = err instanceof Error
    ? (kind === undefined ? (err.stack ?? err.message) : err.message)
    : String(err);
  const consequence =
    '  Unchanged: this boot serves i18n from the kernel in-memory fallback, so what follows\n'
    + '  is why the file-based service is absent — not a boot failure.\n';
  return kind !== undefined
    ? `[i18n] ${pkg} was requested but could not be loaded (${kind}).\n${consequence}${detail}`
    : `[i18n] ${pkg} resolved but threw while loading — this is the package's own failure, `
      + `not a missing package.\n${consequence}${detail}`;
}


/**
 * The operator-facing prose that names the multi-org runtime, as SEAMS rather
 * than string expressions buried inside `run()` — the same reason
 * {@link resolveTenancyPostureOrRefusal} above is one (#5359).
 *
 * #11614 single-sourced the name `serve` RESOLVES onto
 * {@link Serve.ORGANIZATIONS_RUNTIME_PKG} and stopped there, deliberately: the
 * five sentences below are what an operator reads at the worst possible moment,
 * and churning them for a provable no-op is how a whitespace slip lands in the
 * one text that has to be right. This is the other half, done the way that
 * makes it checkable rather than eyeballed — the name is interpolated from the
 * same declaration the roster pins, and
 * `serve-organizations-message-spelling.test.ts` asserts what these RENDER, not
 * that the constant appears in the source. Rename the roster key and the prose
 * moves with it; re-spell it inline and the rendered text stops matching.
 *
 * Deliberately NOT a source scan for "no bare literal outside the declaration":
 * that shape has to exclude comments (three of them here legitimately name the
 * package) and is easy to get wrong.
 *
 * Each function returns PLAIN text. The `chalk` wrapper and the `process.exit`
 * stay at the call site, where the control flow is readable.
 */

/**
 * The install remedy bullet for a multi-org runtime that would not load — one
 * bullet per ABSENCE, and the absences are what the branch reads (#4719).
 *
 * ## What the branch is ON, and why it is not a kind list
 *
 * The question each arm answers is **"is the declaration the problem?"**:
 *
 *   - `declared-unresolvable` — the app's `package.json` DOES name the package,
 *     so the DECLARATION is not the problem. Telling that operator to re-read a
 *     file that is already correct is the defect this branch exists to avoid.
 *     ⚠️ It used to mint an install remedy here too — "Repair the INSTALL: run
 *     `pnpm install`, check that a production prune did not drop it, and that
 *     its dist is actually built". DRIVEN, on both shapes this kind covers, it
 *     was wrong twice over (#17046):
 *       · a genuinely broken install already gets those three remedies, word
 *         for word, from `unresolvableMessage` in the `cause:` line printed
 *         four lines below — so the bullet was a second copy to drift;
 *       · the sub-case commit 288fe9c34 reworded — a location install this finder cannot tie to
 *         the declaration — prints a `cause:` that says outright "This is NOT
 *         an install problem … re-running `pnpm install`, un-pruning a deploy
 *         and rebuilding a dist all change nothing here", so the two halves of
 *         one screen contradicted each other. #17046 narrowed that sub-case
 *         (a correctly linked package now LOADS) but did NOT remove it: pnpm's
 *         `file:` virtual-store copy and every git / tarball declaration still
 *         land here.
 *     So this arm now says only what it uniquely knows — the declaration — and
 *     defers the remedy, exactly as the next one does.
 *   - `declared-no-loadable-entry` (#14041) — the app declares it, the install
 *     DELIVERED it, and the package's own `exports` names no runtime entry
 *     Node can load. Neither absence applies: there is nothing to declare and
 *     nothing to install, so this arm prescribes NOTHING and defers to the
 *     importer's own message, which `formatOrganizationsAbsentFatal` prints
 *     verbatim as the `cause:` line of the same refusal (#14270).
 *   - anything else — the app never declared it, so the declare-and-install
 *     remedy is the one that works.
 *
 * ⚠️ This was a TWO-WAY branch written when only two kinds existed, so the
 * third fell into the else leg and told an operator whose app already declares
 * AND installs the package to declare and install it — the
 * confidently-wrong-verdict class #14041 removed one layer down, reintroduced
 * by its consumer. ⛔ The third arm deliberately does NOT mint a fourth remedy
 * sentence: the importer already words the package-shape case, and a local
 * re-wording here would be a second copy to drift (the same reason
 * {@link formatI18nLoadDiagnostic} interpolates only the kind TOKEN, and the
 * same shape as {@link formatOrganizationsMountFatal}'s "its message is the
 * authority on the remedy").
 *
 * An error carrying NO kind never came from the host importer at all and keeps
 * the declare-and-install arm it has always had — narrowing that one is a
 * different question, about a different fact, and is not this branch's.
 */
export function formatOrganizationsInstallRemedy(
  kind: HostImportFailureKind | undefined,
  declaration: HostDeclaration,
): string {
  const pkg = Serve.ORGANIZATIONS_RUNTIME_PKG;
  if (kind === 'declared-unresolvable') {
    return `      • this app DECLARES ${pkg} ` +
      `(${declaration.field}: ${JSON.stringify(declaration.specifier)}) — the\n` +
      '        declaration is NOT the problem and re-reading package.json will not help.\n' +
      '        What IS wrong was measured by the importer: the cause below names the\n' +
      '        directory it consulted and what it found there, and is the authority on\n' +
      '        whether any install action can change it — or\n';
  }
  if (kind === 'declared-no-loadable-entry') {
    return `      • this app DECLARES ${pkg} ` +
      `(${declaration.field}: ${JSON.stringify(declaration.specifier)}) and it IS\n` +
      '        INSTALLED — neither the declaration nor the install is the problem, and no change\n' +
      '        you make in this app can fix it. The package publishes no entry Node can load;\n' +
      '        the remedy is in the package, and the cause below is the authority on what it\n' +
      '        has to publish — or\n';
  }
  return `      • add ${pkg} (the multi-org runtime) to THIS APP\n` +
    "        — declare it in the app's package.json and install; the CLI resolves it from the\n" +
    '          app, not from the framework it is linked out of. Being merely reachable\n' +
    '          through NODE_PATH / a hoisted workspace store is deliberately not enough:\n' +
    '          accepting it made this wall depend on how the process was launched.\n' +
    '          NOTE: this runtime is Apache-2.0 and published on the public npm registry\n' +
    '          (ADR-0132), so this bullet is followable on any install — no subscription.\n' +
    '          A commercial deployment resolves the same package name to its own private,\n' +
    '          licence-gated build; the manifest that declares it decides which — or\n';
}

/**
 * Stage 1 refusal: a walled posture was requested and the multi-org runtime is
 * ABSENT, so the organization wall would be inactive (ADR-0093 D5).
 */
export function formatOrganizationsAbsentFatal(
  posture: TenancyPosture,
  remedy: string,
  cause: string,
): string {
  return (
    `\n  ✖ FATAL: tenancy posture '${posture}' was requested but ` +
    `${Serve.ORGANIZATIONS_RUNTIME_PKG} could not be loaded,\n` +
    '    so the organization wall is INACTIVE. Refusing to boot — a deployment that requested\n' +
    '    multi-organization isolation must not serve traffic without it (ADR-0093 D5).\n\n' +
    '    Fix one of:\n' +
    remedy +
    "      • set OS_TENANCY_POSTURE=single (or unset OS_MULTI_ORG_ENABLED) to run single-org, or\n" +
    '      • set OS_ALLOW_DEGRADED_TENANCY=1 to boot in an explicitly degraded single-org state.\n\n' +
    `    cause: ${cause}\n`
  );
}

/**
 * The degraded-boot brand: the operator explicitly accepted an absent multi-org
 * runtime via `OS_ALLOW_DEGRADED_TENANCY=1`, so boot continues — loudly.
 */
export function formatDegradedTenancyWarning(posture: TenancyPosture): string {
  return (
    `  ⚠ DEGRADED TENANCY (OS_ALLOW_DEGRADED_TENANCY=1): posture '${posture}' requested but ` +
    `${Serve.ORGANIZATIONS_RUNTIME_PKG} is unavailable — booting with the organization wall INACTIVE. ` +
    'Organization boundaries are NOT enforced. (ADR-0093 D5)'
  );
}

/**
 * Stage 2 refusal: the runtime IS present and its plugin declined to mount
 * (#4818). A different fact with a different remedy, and one
 * `OS_ALLOW_DEGRADED_TENANCY` deliberately does not cover.
 */
export function formatOrganizationsMountFatal(
  posture: TenancyPosture,
  mountMessage: string,
  mountCode: unknown,
): string {
  return (
    `\n  ✖ FATAL: tenancy posture '${posture}' was requested and ` +
    `${Serve.ORGANIZATIONS_RUNTIME_PKG} WAS found and loaded,\n` +
    '    but its OrganizationsPlugin refused to mount, so the organization wall is INACTIVE.\n' +
    '    Refusing to boot — a deployment that requested multi-organization isolation must not\n' +
    '    serve traffic without it (ADR-0093 D5).\n\n' +
    '    This is NOT a missing-package problem: the runtime is installed and resolvable here,\n' +
    '    so module resolution / NODE_PATH / dependency pruning are not the place to look.\n\n' +
    '    The plugin reported (verbatim — the framework does not interpret it):\n' +
    (mountCode !== undefined ? `      code: ${String(mountCode)}\n` : '') +
    `      ${mountMessage}\n\n` +
    '    Fix one of:\n' +
    '      • resolve what the plugin reported above — its message is the authority on the\n' +
    '        remedy; this CLI has no further detail to add, or\n' +
    "      • set OS_TENANCY_POSTURE=single (or unset OS_MULTI_ORG_ENABLED) to run single-org.\n\n" +
    '    OS_ALLOW_DEGRADED_TENANCY does NOT apply to this failure and will not get past it:\n' +
    '    it covers an ABSENT multi-org runtime the operator accepts doing without, not a\n' +
    '    present one that declined to mount.\n'
  );
}

/**
 * Which env var supplied the auth base URL, in the precedence order `serve`
 * reads them. `null` in {@link AuthBaseUrlResolution.source} means no variable
 * was set and the built-in `http://localhost:<port>` default won.
 */
export const AUTH_BASE_URL_ENV_NAMES = ['OS_AUTH_URL', 'BETTER_AUTH_URL', 'OS_BASE_URL'] as const;
export type AuthBaseUrlEnvName = (typeof AUTH_BASE_URL_ENV_NAMES)[number];

/**
 * What the auth base-URL precedence chain resolved to, and whether that value
 * is usable as a URL.
 */
export interface AuthBaseUrlResolution {
  /** The resolved value, UNCHANGED — including `''` when a variable is set-but-empty. */
  value: string;
  /** The variable that supplied {@link value}, or `null` for the built-in default. */
  source: AuthBaseUrlEnvName | null;
  /** `${protocol}//${host}` of {@link value}, or `null` when it will not parse. */
  baseOrigin: string | null;
}

/**
 * Resolve the auth base URL and report BOTH where it came from and whether it
 * parses (#10202).
 *
 * ## Why this is a seam and not three lines inside `run()`
 *
 * The chain and the `new URL()` that consumes it used to sit inline, with the
 * parse wrapped in `try { … } catch { /* ignore malformed baseUrl *\/ }`. That
 * catch is the defect: it is the ONLY place that learns the configured base URL
 * is unusable, and it threw the knowledge away. Nothing else in the boot notices
 * — `/api/v1/health` and `/api/v1/ready` answer `200` and the server serves
 * every non-auth route normally, so the first symptom reaches the operator as
 * `403 INVALID_ORIGIN` from a browser, with nothing in the log pointing at the
 * variable that caused it.
 *
 * MEASURED on a real `os serve` boot (`NODE_ENV=production`, `OS_AUTH_URL=`
 * set-but-empty, no `OS_TRUSTED_ORIGINS`, no `OS_ROOT_DOMAIN`, no preview mode):
 * health `200`, ready `200`, and `POST /api/v1/auth/sign-in/email` from
 * `https://app.example.com` answered `403 INVALID_ORIGIN`.
 *
 * ## The shape that produces an unusable value
 *
 * `readEnvWithDeprecation` returns the preferred variable whenever it is
 * `!== undefined`, so a **present-but-empty** variable resolves to `''`, not
 * `undefined`. The chain below then coalesces with `??`, which falls through
 * only on `null`/`undefined` — never on `''`. So `OS_AUTH_URL=` on its own line
 * in an env file (or a template rendering an absent key) consults NEITHER
 * `OS_BASE_URL` nor the `http://localhost:<port>` default, and `new URL('')`
 * throws.
 *
 * The resolution itself is deliberately left EXACTLY as it was — this function
 * changes only what is known about the result, never what the result is.
 * Treating empty as unset inside the shared `readEnvWithDeprecation` would
 * change behaviour for every caller and is a separate, deliberate decision.
 *
 * `baseOrigin` is spelled `${protocol}//${host}` rather than `URL.origin`
 * because that is what the inline code computed, and the two disagree for
 * non-special schemes (`URL.origin` answers the string `"null"`).
 *
 * ## The tail follows the LISTENER, and only the tail (#16804)
 *
 * `boundProtocol` names the scheme this process actually bound — `https`
 * exactly when `--cert`/`--key` were both given, derived in `dev-tls-contract`
 * from that material and settable nowhere else. It reaches only the built-in
 * default at the end of the chain, because that default is the one link nobody
 * configured: it is this process describing its own socket, and once TLS
 * terminates in-process `http://localhost:<port>` is an address no client can
 * reach.
 *
 * ⛔ Every CONFIGURED link is untouched. `OS_AUTH_URL`, its legacy name and
 * `OS_BASE_URL` answer a different question — where this deployment is
 * REACHED, which behind a proxy or a tunnel has no relation to what this
 * process bound — so they keep winning, https listener or not, and an
 * `http://` value under a TLS listener is an operator's deliberate statement
 * rather than a default to override.
 *
 * The parameter DEFAULTS to `'http'`, which is what every caller that never
 * passes it resolved to before this existed: on a tree with no TLS flags in
 * play the value, the source and the origin are byte-for-byte what they were.
 */
export function resolveAuthBaseUrl(
  port: number | string,
  boundProtocol: ListenerProtocol = 'http',
): AuthBaseUrlResolution {
  const value = readEnvWithDeprecation('OS_AUTH_URL', 'BETTER_AUTH_URL', { silent: true })
    ?? process.env.OS_BASE_URL
    ?? `${boundProtocol}://localhost:${port}`;

  // Mirrors readEnvWithDeprecation's own precedence (preferred, then legacy),
  // for REPORTING only — the value above is what actually takes effect.
  const env = process.env;
  const source: AuthBaseUrlEnvName | null =
    env.OS_AUTH_URL !== undefined ? 'OS_AUTH_URL'
      : env.BETTER_AUTH_URL !== undefined ? 'BETTER_AUTH_URL'
        : env.OS_BASE_URL !== undefined ? 'OS_BASE_URL'
          : null;

  let baseOrigin: string | null = null;
  try {
    const u = new URL(value);
    baseOrigin = `${u.protocol}//${u.host}`;
  } catch {
    // Unusable. Reported by formatUnusableAuthBaseUrlDiagnostic — NOT swallowed.
  }

  return { value, source, baseOrigin };
}

/**
 * The boot-time complaint for a base URL that will not parse, or `null` when it
 * parses fine.
 *
 * Names the variable and the value it resolved to, because those are the two
 * facts the operator cannot recover from the symptom: a `403 INVALID_ORIGIN` in
 * a browser names neither. The empty case additionally says that empty is not
 * the same as unset, since the whole trap is that an operator who typed
 * `OS_AUTH_URL=` believes they have left it unset.
 *
 * Returns text rather than printing it so the decision to warn stays at the
 * call site (and so a test can read the sentence without capturing a stream).
 */
export function formatUnusableAuthBaseUrlDiagnostic(
  resolution: AuthBaseUrlResolution,
): string | null {
  if (resolution.baseOrigin !== null) return null;

  const { value, source } = resolution;
  const shown = JSON.stringify(value);
  const named = source === null
    ? `    The built-in default resolved to ${shown}, which is not a usable URL.\n`
    : value === ''
      ? `    ${source} is set but EMPTY (${shown}).\n`
      : `    ${source} is set to ${shown}, which is not a usable URL.\n`;

  const emptyNote = (value === '' && source !== null)
    ? '    An empty value is NOT the same as an unset one: the fallback chain skips only\n'
      + `    UNSET variables, so ${source === 'OS_BASE_URL' ? 'the' : 'OS_BASE_URL and the'} built-in`
      + ' http://localhost:<port> default were never consulted.\n'
    : '';

  return '\n'
    + '  ⚠ Auth base URL is unusable — its origin was NOT added to the CSRF allow-list.\n'
    + named
    + emptyNote
    + '    Sign-in and sign-up will answer 403 INVALID_ORIGIN for this deployment\'s own\n'
    + '    origin, while /api/v1/health and /api/v1/ready keep answering 200.\n'
    + '    Fix: set OS_AUTH_URL to this deployment\'s public origin (e.g.\n'
    + '    https://app.example.com), or remove the variable entirely to fall back to\n'
    + '    OS_BASE_URL / http://localhost:<port>.';
}

// [#22301] The constructor arguments a served boot hands the `storage`, `email`
// and `sms` providers are read by ONE rule, `resolveCapabilityArgument`
// (`@objectstack/core`), which `@objectstack/verify`'s `bootStack` reads too —
// so an app's tests construct those providers from the configuration its users'
// server does. The readers it calls moved with it: the storage root lives in
// `@objectstack/core`; the mail and SMS readers live beside the transport
// vocabulary they refuse against, in `@objectstack/plugin-email` and
// `@objectstack/service-sms` (the reasons are in each module's header). These
// names stay importable from here, as handles over those declarations — ⛔ never
// a second copy.
export {
  resolveStorageCapabilityArg,
  resolveStorageLocalRootEnv,
  type StorageCapabilityArg,
} from '@objectstack/core';
export {
  resolveEmailCapabilityArg,
  resolveDeploymentAppName,
  type EmailCapabilityArg,
} from '@objectstack/plugin-email';
export { resolveSmsCapabilityArg, type SmsCapabilityArg } from '@objectstack/service-sms';

/**
 * The multi-node gate verdict, as `os serve` consumes it.
 *
 * ⚠️ A **structural mirror** of `ResolvedMultiNodeVerdict` in
 * `@objectstack/service-cluster` (`src/multi-node-gate.ts`), not an import: the
 * CLI reaches that package through a dynamic, non-literal specifier so it
 * carries no static dependency on it (open-core ships the memory driver;
 * remote drivers arrive with a distribution). The cast at the call site is the
 * only place the two shapes meet, so nothing about a widening on the producer
 * side propagates here on its own — the narrow `{ allowed, reason }` copy that
 * used to live inline is exactly why a licensed node cap stayed unreportable
 * after the gate learned to express one. `serve-multi-node-cap-advisory.pin.test.ts`
 * pins this declaration against the producer's so the next widening is a
 * decision rather than a silent divergence.
 */
export interface MultiNodeGateVerdict {
  /** Whether a multi-node topology is authorized at all. */
  allowed: boolean;
  /** Surfaced in logs. */
  reason?: string;
  /**
   * How many of the requested nodes the gate admits. Absent when the gate
   * imposes no count cap; `0` when it denied outright.
   */
  admitted?: number;
  /**
   * How many requested nodes exceed what the gate admits. `0` when uncapped,
   * when the request fits, or when no count was declared.
   */
  refused: number;
  /**
   * True only for a **partial** refusal — the licensed-overflow case. `false`
   * for an outright denial, so the two cannot be conflated.
   */
  capped: boolean;
}

/**
 * The operator-facing text for a licensed node-cap overflow, or `null` when
 * there is nothing to say.
 *
 * Clause 3 of the maintainer's 2026-08-13 `max_nodes` ruling (recorded on
 * cloud#1275): a licensed overflow must **refuse the excess, run up to the paid
 * limit, and warn loudly** — explicitly not a whole-cluster degrade. The first
 * two clauses need an atomic slot claim across replicas and are tracked as
 * their own mechanism; this is the third, and it is deliverable on its own
 * because it needs nothing beyond the verdict the gate already returns.
 *
 * ⚠️ **The wording is the deliverable, not decoration.** While the enforcement
 * mechanism is open, nothing is actually refused: the gate is consulted once
 * per process at boot, every replica computes the *same* verdict, and none can
 * know whether it is one of the admitted ones — so all of them join. Phrasing
 * this as "2 replicas refused" would therefore be **false**, and would recreate
 * the very declared-vs-delivered gap the warning exists to close. It says
 * instead that the cap is advisory and that the excess replicas still join,
 * which is exactly what happens today.
 *
 * `capped` alone is the trigger: the producer sets it **only** for the partial
 * (licensed-overflow) case, keeping it `false` for an outright `allowed: false`
 * denial — that one is the unlicensed case and the call site already reports it
 * as a downgrade. Reading `refused > 0` instead would double-report it.
 */
export function formatMultiNodeCapAdvisory(verdict: MultiNodeGateVerdict): string | null {
  // `capped: true` is produced only together with a numeric `admitted` and a
  // positive `refused`. The extra narrowing is the type system asking for that
  // invariant in writing — not tolerance of an off-spec producer: a stale build
  // that set `capped` without a count would get silence rather than a warning
  // with an invented number in it, and a wrong number here is worse than the
  // silence it replaces.
  if (!verdict.capped) return null;
  const admitted = verdict.admitted;
  const excess = verdict.refused;
  if (typeof admitted !== 'number' || excess <= 0) return null;

  const declared = admitted + excess;
  const why = verdict.reason ? ` (${verdict.reason})` : '';
  return (
    `[cluster] licensed node cap exceeded${why}: the licence admits ${admitted} node(s), `
    + `but OS_CLUSTER_REPLICAS declares ${declared} — ${excess} beyond the cap.\n`
    + `[cluster] This cap is ADVISORY and is not enforced yet: nothing is refused, and all `
    + `${declared} replicas will still join the cluster.\n`
    + `[cluster] Reduce OS_CLUSTER_REPLICAS to ${admitted}, or raise the licensed node limit.`
  );
}

/**
 * The gate verdict as one word, from the vocabulary the gate itself ships
 * (`admitted` / `refused` / `capped`) — deliberately not a second vocabulary.
 *
 * - `refused` — `allowed: false`, the unlicensed case: the whole topology is
 *   refused and `os serve` downgrades to single-node.
 * - `capped`  — the licensed-overflow case: entitled to cluster, declared more
 *   nodes than the licence admits. **Advisory**: every declared replica still
 *   joins.
 * - `admitted` — everything declared fits, or no cap was expressed at all.
 */
export type MultiNodeCapVerdictWord = 'admitted' | 'capped' | 'refused';

/** One metric observation the operator surface publishes. */
export interface MultiNodeCapMetric {
  /** Canonical name from `SEMCONV` — never a literal written here. */
  name: string;
  kind: 'gauge' | 'counter';
  value: number;
  labels: { verdict: MultiNodeCapVerdictWord };
}

/**
 * A positive, finite, whole node count — or `undefined` for "not declared".
 *
 * ⚠️ A deliberate MIRROR of `normalizeCount` in
 * `@objectstack/service-cluster`'s `multi-node-gate.ts`, kept BYTE-IDENTICAL in
 * its body so `serve-multi-node-cap-advisory.pin.test.ts` can compare the two
 * bodies derived from their own files rather than against a rule re-typed in a
 * test. The mirror exists because the resolved verdict does not carry the
 * declared count back: `admitted` is `min(cap, wanted)`, so `{admitted: 3,
 * refused: 0}` is produced both by "declared 3 under a cap of 5" and by
 * "declared nothing under a cap of 3". The declaration is only knowable from
 * the env var the operator wrote, which is what this reads.
 */
function normalizeDeclaredNodeCount(value: number | undefined): number | undefined {
    if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) return undefined;
    return Math.floor(value);
}

/**
 * The operator-facing TELEMETRY reading of a multi-node gate verdict — the
 * second reach of the same advisory the boot warning above renders as prose
 * (#12667, ruled C on #8501, maintainer 2026-08-27 「其他接受」).
 *
 * ⚠️ **Visibility, not enforcement, and the shape says so.** Nothing here
 * refuses anything: the gate is consulted once per process at boot, every
 * replica computes the same verdict, and none can know whether it is one of the
 * admitted ones — so all of them join. The two facts that make a real count
 * impossible are unchanged: there is no cluster membership view (`nodeId` is
 * random per process, no join/leave registry) and `OS_CLUSTER_REPLICAS` is an
 * operator-DECLARED count identical in every replica. Hence
 * `cluster_declared_nodes` and `cluster_admitted_nodes`: "declared vs what the
 * licence admits" is an honest sentence, "N nodes running" is not, and would
 * be a false statement dressed as telemetry.
 *
 * Why prose alone was not enough reach: the boot warning is one `console.warn`
 * in one process's startup output. An operator who scaled past their cap three
 * weeks ago has no way to ask the question today, and no way to alert on it.
 * These observations put the same reading where the deployment's existing
 * metrics pipeline already looks.
 *
 * Deliberate omissions, each of which would be a false number rather than a
 * missing one:
 *
 *   - no `cluster_declared_nodes` when nothing was declared — `0` would read
 *     as a declaration of zero replicas;
 *   - no `cluster_admitted_nodes` when the gate expressed no count cap
 *     (`admitted` absent) — any number there invents a limit nobody stated;
 *   - no series at all when the gate was never consulted (single-node boot).
 *
 * Pure and exported so the test suite can assert **what an operator sees** for
 * each verdict rather than that some value was computed.
 *
 * @param verdict - the verdict `checkMultiNodeAllowed` returned at boot.
 * @param declaredReplicas - `Number(process.env.OS_CLUSTER_REPLICAS)`, raw:
 *   normalization is this function's job, exactly as it is the gate's at its
 *   own seam. `NaN` (the variable is unset) means "not declared".
 */
export function describeMultiNodeCapTelemetry(
  verdict: MultiNodeGateVerdict,
  declaredReplicas: number,
): MultiNodeCapMetric[] {
  const verdictWord: MultiNodeCapVerdictWord =
    !verdict.allowed ? 'refused' : verdict.capped ? 'capped' : 'admitted';
  const labels = { verdict: verdictWord };

  // The boot EVENT first: it is the one series that survives a push-based
  // exporter's staleness window, so it is what an alert can be written against.
  const metrics: MultiNodeCapMetric[] = [
    { name: SEMCONV.clusterNodeCapVerdictsTotal, kind: 'counter', value: 1, labels },
  ];

  const declared = normalizeDeclaredNodeCount(declaredReplicas);
  if (declared !== undefined) {
    metrics.push({ name: SEMCONV.clusterDeclaredNodes, kind: 'gauge', value: declared, labels });
  }
  if (typeof verdict.admitted === 'number') {
    metrics.push({ name: SEMCONV.clusterAdmittedNodes, kind: 'gauge', value: verdict.admitted, labels });
  }
  return metrics;
}

/**
 * Publish {@link describeMultiNodeCapTelemetry}'s observations into whatever
 * metrics backend the deployment configured.
 *
 * Best-effort by contract: a metric call site must never throw, and an
 * unconfigured deployment must not be worse off than before this existed — with
 * no backend registered the boot warning remains the only reading, which is
 * precisely the state this card set out to improve on rather than replace.
 *
 * ⚠️ `kernel.getService` THROWS on a miss (see `packages/core/src/kernel.ts`),
 * so the lookup is wrapped rather than null-checked. Resolving through the
 * kernel — not through the block `serve` built itself — is what lets a host
 * that mounts its OWN `ObservabilityServicePlugin` receive these too.
 */
function emitMultiNodeCapTelemetry(
  kernel: { getService?: <T>(name: string) => T } | undefined,
  verdict: MultiNodeGateVerdict,
): void {
  // Typed with the slot's contract, never erased to `any` (#4127/#4251,
  // `check:slot-lookup`): the erasure would also have switched off the argument
  // check the two calls below depend on — see their note.
  let metrics: MetricsRegistry | undefined;
  try {
    metrics = kernel?.getService?.<MetricsRegistry>(OBSERVABILITY_METRICS_SERVICE);
  } catch {
    return; // no observability backend configured — boot warning stands alone
  }
  if (!metrics) return;
  try {
    for (const sample of describeMultiNodeCapTelemetry(verdict, Number(process.env.OS_CLUSTER_REPLICAS))) {
      // The two signatures differ in argument ORDER (`MetricsRegistry`):
      // counter(name, labels, value) vs gauge(name, value, labels). Written out
      // separately so the swap is visible — and, because the lookup above is
      // typed, a swap is now a compile error rather than a green build emitting
      // a label map where a number belongs.
      if (sample.kind === 'counter') metrics.counter(sample.name, sample.labels, sample.value);
      else metrics.gauge(sample.name, sample.value, sample.labels);
    }
  } catch {
    // Per the metrics contract: never throw from a call site.
  }
}

/**
 * Best-effort driver introspection.
 *
 * Drivers register themselves under the kernel service name
 * `driver.{driver.name}` (see `DriverPlugin.init`). We probe a list of
 * well-known names and return a single-line label + redacted URL so the
 * startup banner can show *something* even when the driver wasn't
 * registered through this command's own `OS_DATABASE_URL` fallback
 * (e.g. when the example app's preset or `EnvironmentKernelFactory` wired
 * it). Returns `null` when nothing matches; the caller treats that as
 * "no driver info available" and skips the line.
 *
 * Reading the address out of a driver is `describeDriverConnection`'s job
 * (#3793) — it is the one place that knows every shape a driver config
 * arrives in, so a DSN-declared datasource no longer falls through to
 * `(unknown)`, and no shape prints credentials.
 */
export function describeRegisteredDriver(
  kernel: any,
): { label: string; url: string; sqliteFile?: string } | null {
  const candidates = [
    'driver.com.objectstack.driver.sql',
    'driver.com.objectstack.driver.mongodb',
    'driver.com.objectstack.driver.turso',
    'driver.com.objectstack.driver.memory',
    'driver.sql', 'driver.mongodb', 'driver.turso', 'driver.memory',
  ];
  for (const name of candidates) {
    let driver: any;
    try { driver = kernel?.getService?.(name); } catch { /* not registered */ }
    if (!driver) continue;

    const cfg = driver.config;
    // `client` is a plain string for the stock knex dialects, but a Client
    // *class* for SqliteWasmDriver — interpolating that would paste the whole
    // class source into the banner.
    const label = typeof cfg?.client === 'string'
      ? `SqlDriver(${cfg.client})`
      : (driver.constructor?.name ?? driver.name ?? 'Driver');

    // Read the address by shape, not by which branch matches first. Every
    // driver here has a `config` property — SqlDriver's is knex-shaped,
    // MongoDBDriver's holds a top-level `url`, InMemoryDriver's is `{}` — so
    // returning early on "has a config" meant the mongo and in-memory arms
    // below never ran and every non-SqlDriver boot banner read `(unknown)`.
    // `driver.url` still covers a driver that keeps its DSN on the instance.
    const url = describeDriverConnection(cfg)
      ?? (typeof driver.url === 'string' && driver.url ? redactConnectionUrl(driver.url) : undefined);

    // A memory driver has no address to show — say so, rather than
    // `(unknown)`, which reads as "we looked for one and failed".
    //
    // `sqliteFile` is the same config read a second time asking a DIFFERENT
    // question: not "what do I print" but "which file on this filesystem", so
    // a caller can `stat` it. Absent for every driver that serves no on-disk
    // SQLite file, which is the majority of them.
    return {
      label,
      url: url ?? (name.endsWith('.memory') ? '(in-memory)' : '(unknown)'),
      sqliteFile: describeDriverSqliteFile(cfg),
    };
  }
  return null;
}

/**
 * Decide what the ready banner's `Config:`/`Artifact:` row should say
 * (#8978).
 *
 * `relativeConfig` is derived from `args.config` at the top of `run()`,
 * before the artifact-fallback branch is decided, and was being handed to
 * {@link printServerReady} unconditionally. On an `OS_ARTIFACT_URL` boot
 * the `objectstack.config.ts` in cwd is deliberately never executed — the
 * boot diagnostics say so plainly a few lines above the banner — yet the
 * banner still named it. On the plain artifact-fallback path (no config
 * authored, booting from `OS_ARTIFACT_PATH` or the `<cwd>/dist/objectstack.json`
 * convention) the row named a config file that does not exist on disk at
 * all. Both are the same defect: the row is the surface an operator reads
 * to answer "what is this container actually running", and naming what
 * did NOT boot points them at the wrong app (cloud#1292).
 *
 * - `pinnedArtifact` set (OS_ARTIFACT_URL, #8368) → report it. `.display`
 *   is already resolved and already redacted for a pre-signed URL by the
 *   resolver, so it is safe to print as-is.
 * - `useArtifactFallback` set with no `pinnedArtifact` (OS_ARTIFACT_PATH,
 *   the `dist/objectstack.json` convention, or an empty/quick-start boot)
 *   → no config was read and there is no safely-redacted display in hand
 *   here (OS_ARTIFACT_PATH may itself be a credentialed URL) — omit the
 *   row rather than name a nonexistent file or risk leaking a secret.
 * - Neither set → the config-boot path, which names what that boot actually
 *   loaded as the app (#21501): `configBootBundle` set — a non-host config
 *   whose standalone stack served a compiled artifact as its bundle — reports
 *   THAT file as `bundleSource`; otherwise (a host config, whose `plugins` hold
 *   code and which boots its own module, or a config whose artifact was absent)
 *   report `relativeConfig`. No row names a file the boot did not load.
 */
export function resolveBannerConfigRow(opts: {
  relativeConfig: string;
  useArtifactFallback: boolean;
  pinnedArtifact?: { display: string };
  configBootBundle?: string;
}): { configFile?: string; artifactSource?: string; bundleSource?: string } {
  if (opts.pinnedArtifact) return { artifactSource: opts.pinnedArtifact.display };
  if (opts.useArtifactFallback) return {};
  if (opts.configBootBundle) return { bundleSource: opts.configBootBundle };
  return { configFile: opts.relativeConfig };
}

/**
 * Collect the automation wiring facts for the startup banner (2026-07-17
 * third-party eval: a flow that failed to arm emits no log line to find, so the
 * banner reads the binding state off the engine instead).
 *
 * Every probe is feature-detected so an older `@objectstack/service-automation`
 * (without `getTriggerBindingAudit` / `getShadowedFlows` / extended runtime
 * states) degrades to the plain count line instead of crashing the banner.
 * Returns `undefined` when there is nothing automation-related to show at all.
 */
export function collectAutomationSummary(
  kernel: any,
  declaredFlowCount: number,
): AutomationReadySummary | undefined {
  let automation: any;
  try { automation = kernel?.getService?.('automation'); } catch { /* not registered */ }

  if (!automation) {
    return declaredFlowCount > 0
      ? {
          enabled: false,
          declaredFlowCount,
          flowCount: 0,
          boundCount: 0,
          triggerTypes: [],
          unbound: [],
          unknownObject: [],
          shadowed: [],
          draftCount: 0,
        }
      : undefined;
  }

  /**
   * One flow body's provenance, as the engine spells it (`FlowContender` in
   * `@objectstack/service-automation`): a code-shipped artifact, or an
   * ADR-0005 runtime overlay row in `sys_metadata`.
   *
   * Declared structurally, like every other shape this function reads off the
   * engine. The probes below are feature-detected precisely so a host running
   * an OLDER automation package still boots its banner, and a nominal import
   * would type these reads against the CURRENT package while the runtime
   * deliberately tolerates a previous one.
   */
  type Contender = { source: 'package' | 'runtime'; packageId?: string };

  let states: Array<{
    name: string;
    enabled: boolean;
    bound: boolean;
    status?: string;
    triggerType?: string;
    object?: string;
    // [#12028] `getFlowRuntimeStates()` has attached these two per row since
    // #11997 whenever a bare name had more than one contender. Named here so a
    // later read is type-checked against the row's real shape — casting past
    // this annotation is how the field goes back to being declared and unread,
    // which is the whole defect this banner line closes.
    armedFrom?: Contender;
    shadowed?: Contender[];
  }> = [];
  try { states = automation.getFlowRuntimeStates?.() ?? []; } catch { /* older engine */ }
  if (states.length === 0 && declaredFlowCount === 0) return undefined;

  let triggerTypes: string[] = [];
  try { triggerTypes = automation.getRegisteredTriggerTypes?.() ?? []; } catch { /* older engine */ }

  let unbound: Array<{ flowName: string; triggerType: string; reason: string }> = [];
  try { unbound = automation.getTriggerBindingAudit?.() ?? []; } catch { /* older engine */ }

  // [#12028] Same-named definitions: which body armed, and which lost. Read
  // from the engine's dedicated receipt rather than from `states` above, for
  // one measured reason — `getFlowRuntimeStates()` can only attach the receipt
  // to a row it is already emitting, i.e. to a name still in the flow map,
  // whereas `getShadowedFlows()` returns every receipt the boot pull recorded.
  // A contested name is worth saying out loud either way.
  //
  // Feature-detected exactly like the `unbound` probe above and with nothing
  // more: optional call, `?? []`, `catch` for an older engine. No extra
  // tolerance — the neighbouring read is the standard here.
  let shadowing: Array<{ name: string; armed: Contender; shadowed: Contender[] }> = [];
  try { shadowing = automation.getShadowedFlows?.() ?? []; } catch { /* older engine */ }

  // Dead bindings: a bound record-change flow whose target object nobody
  // registered — the hook is filtered to a name that never writes.
  const unknownObject: Array<{ flowName: string; object: string }> = [];
  let ql: any;
  try { ql = kernel?.getService?.('objectql'); } catch { /* absent */ }
  if (ql && typeof ql.getObject === 'function') {
    for (const s of states) {
      if (!s.bound || !s.object || s.triggerType !== 'record_change') continue;
      let known: unknown;
      try { known = ql.getObject(s.object); } catch { known = undefined; }
      if (!known) unknownObject.push({ flowName: s.name, object: s.object });
    }
  }

  return {
    enabled: true,
    declaredFlowCount,
    flowCount: states.length,
    boundCount: states.filter((s) => s.bound).length,
    triggerTypes,
    unbound,
    unknownObject,
    // A receipt that displaced nothing is not a contested name. The engine
    // already refuses to record one, and the banner keeps its own end of that
    // guarantee here rather than inheriting it: a benign boot must print no
    // shadowing line at all, and this is where "benign" is decided.
    shadowed: shadowing
      .filter((r) => r.shadowed.length > 0)
      .map((r) => ({ flowName: r.name, armed: r.armed, shadowedCount: r.shadowed.length })),
    draftCount: states.filter((s) => s.enabled && (s.status ?? 'draft') === 'draft').length,
  };
}