@owlmeans/server-app 0.1.18-rc.27 → 0.1.18-rc.28

package/README.md

@@ -1,93 +1,306 @@
 # @owlmeans/server-app
 
-The main entry point for OwlMeans backend services — aggregates server packages and provides the `makeContext` + `main` bootstrap functions.
-
-## Overview
-
-- `makeContext(cfg)` creates a fully initialized server context with Fastify, auth, WebSocket, and static resource support
-- `main(ctx, entrypoints)` registers entrypoints, initializes the context, and starts the HTTP server
-- Re-exports the most commonly used symbols from lower-level packages so backend code has a single import target
-- Used by every service in the viable monorepo
+The bootstrap package for an OwlMeans backend process. An application uses it in every HTTP or
+WebSocket API service: `makeContext` builds the base server context (Fastify API server, API
+client, socket service, static resources and the Ed25519 auth guard), `main` registers the
+entrypoints, initializes the context and starts listening, and the package re-exports the server
+vocabulary (`bind`, `handlers`, `config`, `sservice`, `route`, ...) so backend code has one import
+target. Do not use it in a shared `common` package that only declares protocols (depend on
+`@owlmeans/entrypoint` and `@owlmeans/route` there), in the auth manager process (use
+`@owlmeans/server-auth/manager`, which has its own `makeContext` and `main`), or in a browser app
+(use `@owlmeans/web-panel`).
 
 ## Installation
 
 ```bash
-bun add @owlmeans/server-app@^0.1.18-rc.17
+bun add @owlmeans/server-app@^0.1.18-rc.27
 ```
 
+## Concepts
+
+- **Application context** — one per process, built by the app's own factory that calls
+  `makeContext(cfg)` and then adds its own resources and services with idempotent `append*` mixins.
+  `AppConfig` / `AppContext` are the types that factory extends.
+- **`customize` flag** — `makeContext(cfg, true)` skips the default in-process `AUTH_CACHE` and
+  `appendAuthService`, so the app can register a shared cache (Redis) and the auth guard itself.
+- **Framework entrypoints** — `entrypoints` is the list of bindings every service carries: the
+  `@owlmeans/server-auth` dispatcher bindings and the `@owlmeans/api-config-server` config endpoint.
+- **Bindings** — the app's server-local list of `bind(protocol, handler)` results, materialized from
+  the shared protocol tree and passed to `main`.
+- **Port hold** — `holdApiPort` answers on the service port while the context initializes, so a
+  slow or failing boot answers 503 instead of a connection error.
+
 ## Usage
 
-Bootstrap a backend service:
+### 1. Config
+
+`config(service, base?)` creates a backend config for the named service; `sservice` declares a
+backend service route and `service` any other (frontend) one. A service with `opened: true` listens
+on `0.0.0.0`, otherwise on `127.0.0.1`.
+
+```ts
+import { AppType, config, service, sservice } from '@owlmeans/server-app'
+import type { AppConfig } from '@owlmeans/server-app'
+import { MY_APP_API, MY_APP_WEB, commonConfig } from 'my-app-common'
+
+export interface Config extends AppConfig { }
+
+const cfg = config<Config>(MY_APP_API, commonConfig as Config)
+
+sservice({ service: MY_APP_API, internalHost: 'localhost', internalPort: 3000 }, cfg)
+cfg.services[MY_APP_API].opened = true
+
+service({ type: AppType.Frontend, service: MY_APP_WEB, host: 'localhost', port: 5173 }, cfg)
+
+export default cfg
+```
+
+### 2. Context factory
+
+The app's factory composes the base context and adds its own resources. For development or a
+single replica the defaults are enough:
+
+```ts
+import { makeContext as makeAppContext } from '@owlmeans/server-app'
+import type { AppContext } from '@owlmeans/server-app'
+import { appendStaticResource } from '@owlmeans/static-resource'
+import type { StaticResourceAppend } from '@owlmeans/static-resource'
+import type { Resource } from '@owlmeans/resource'
+import type { Project } from 'my-app-common'
+import type { Config } from './config.js'
+
+export const PROJECTS = 'my-app:projects'
+
+export interface Context<C extends Config = Config> extends AppContext<C>, StaticResourceAppend {
+  project: () => Resource<Project>
+}
+
+export const makeContext = <C extends Config, T extends Context<C>>(cfg: C): T => {
+  const context = makeAppContext<C, T>(cfg)
+
+  appendStaticResource<C, T>(context, PROJECTS)
+  context.project = () => context.getStaticResource<Project>(PROJECTS)
+
+  return context
+}
+```
+
+A scaled deployment passes `customize: true` and registers a shared auth cache before the guard:
+
+```ts
+import { klusterize, makeContext as makeAppContext } from '@owlmeans/server-app'
+import { appendMongo } from '@owlmeans/mongo'
+import { appendRedis } from '@owlmeans/redis'
+import { makeRedisResource } from '@owlmeans/redis-resource'
+import { appendAuthService, AUTH_CACHE } from '@owlmeans/server-auth'
+import { appendAuthIdentityResources } from '@owlmeans/server-auth-identity'
+
+export const makeContext = <C extends Config, T extends Context<C>>(cfg: C): T => {
+  const context = makeAppContext<C, T>(cfg, true)
+  klusterize<C, T>(context)
+  appendMongo<C, T>(context)
+  appendRedis<C, T>(context)
 
-```typescript
-import { makeContext, main, entrypoints, config, service, AppType } from '@owlmeans/server-app'
+  context.registerResource(makeRedisResource(AUTH_CACHE))
+  appendAuthService<C, T>(context)
+  appendAuthIdentityResources(context)
 
-const appConfig = config(
-  AppType.Backend,
-  'manager-api',
-  service({ service: 'manager-api', host: process.env.API_HOST!, port: 3000 }),
-  { port: 3000, dbs: [{ service: 'mongo', alias: 'mongo', host: process.env.MONGO_HOST!, port: 27017 }] }
-)
+  // app-local Mongo resource factory, same `project()` accessor as above
+  context.registerResource(makeProjectResource(PROJECTS))
+  context.project = () => context.resource(PROJECTS)
 
-const context = makeContext(appConfig)
-await main(context, [...entrypoints, ...appEntrypoints])
+  return context
+}
 ```
 
-Bind a shared protocol with a handler:
+### 3. Handlers bound to shared protocols
 
-```typescript
-import { bind } from '@owlmeans/server-entrypoint'
-import { handlers } from '@owlmeans/server-api'
-import { appEntrypoints as protocols } from 'my-app-common'
-import type { Context } from 'my-app-backend'
+Protocols live in the shared package; guards and gates on a parent are inherited by its children.
+
+```ts
+// my-app-common/src/protocols.ts
+import { contract, openProtocol, protocol, typed } from '@owlmeans/entrypoint'
+import { route, RouteMethod, socket } from '@owlmeans/route'
+import { DEFAULT_GUARD } from '@owlmeans/auth-common'
+
+const projectBase = openProtocol(route('my-app:api:project', '/project'), {
+  guards: DEFAULT_GUARD,
+  gate: { alias: MY_APP_GATE, params: ['my-app-project-{entity}'] },
+})
+
+export const projectProtocols = {
+  base: projectBase,
+  list: protocol(
+    route('my-app:api:project:list', '/', { parent: projectBase, method: RouteMethod.GET }),
+    contract(typed<Project[]>()),
+  ),
+  create: protocol(
+    route('my-app:api:project:create', '/', { parent: projectBase, method: RouteMethod.POST }),
+    contract.request({ body: typed<CreateProject>(CreateProjectSchema) }, typed<Project>()),
+  ),
+  get: protocol(
+    route('my-app:api:project:get', '/:id', { parent: projectBase, method: RouteMethod.GET }),
+    contract.request({ params: typed<ProjectParams>(ProjectParamsSchema) }, typed<Project>()),
+  ),
+  watch: protocol(
+    route('my-app:api:project:watch', '/:id/watch', socket({ parent: projectBase })),
+    contract.request({ params: typed<ProjectParams>(ProjectParamsSchema) }, typed<void>()),
+  ),
+}
+```
+
+```ts
+// my-app-api/src/app/project.ts
+import { handlers } from '@owlmeans/server-app'
+import { requireEntityKey } from '@owlmeans/auth-common'
+import { projectProtocols } from 'my-app-common'
+import type { Context } from '../context.js'
 
 const api = handlers<Context>()
-const appEntrypoints = [
-  bind(protocols.api.projectCreate, api.request(protocols.api.projectCreate, async (req, ctx) =>
-    (ctx as Context).project().create(req.body))),
-]
+
+export const list = api.request(projectProtocols.list, async (request, context) => {
+  const { items } = await context.project().list({ entityId: requireEntityKey(request) })
+  return items
+})
+
+export const create = api.body(projectProtocols.create, async (body, context, request) =>
+  context.project().create({ ...body, entityId: requireEntityKey(request) }))
+
+export const get = api.params(projectProtocols.get, async ({ id }, context, request) =>
+  context.project().load({ id, entityId: requireEntityKey(request) }))
 ```
 
-## API
+### 4. Entrypoint list and `main`
 
-### `makeContext<C, T>(cfg, customize?): T`
+```ts
+// my-app-api/src/entrypoints.ts
+import { bind, entrypoints } from '@owlmeans/server-app'
+import { connection } from '@owlmeans/server-socket'
+import { projectProtocols } from 'my-app-common'
+import * as project from './app/project.js'
 
-Creates a server context with Fastify HTTP, WebSocket, static resources, and auth guard set up. Pass `customize: true` to skip the default auth setup.
+export const appEntrypoints = [
+  ...entrypoints,
+  bind(projectProtocols.base),
+  bind(projectProtocols.list, project.list),
+  bind(projectProtocols.create, project.create),
+  bind(projectProtocols.get, project.get),
+  // socket protocols bind the same way; see @owlmeans/server-socket
+  bind(projectProtocols.watch, connection(projectProtocols.watch, async (conn, context, request) => {
+    await conn.notify('project:ready', { id: request.params.id })
+  })),
+]
 
-### `main<R, C, T>(ctx, entrypoints): Promise<void>`
+// my-app-api/src/index.ts
+import { main } from '@owlmeans/server-app'
+import config from './config.js'
+import { makeContext } from './context.js'
+import { appEntrypoints } from './entrypoints.js'
 
-Registers entrypoints, calls `configure().init()`, then starts the Fastify server.
+await main(makeContext(config), appEntrypoints)
+```
 
-### Re-exported symbols (for convenience)
+### 5. A boot that holds the port
 
-| Symbol | Source |
-|---|---|
-| `handlers` | `@owlmeans/server-api` |
-| `bind`, `bindAll`, `guard` | `@owlmeans/server-entrypoint` |
-| `route` | `@owlmeans/route` |
-| `broute` | `@owlmeans/server-route` |
-| `filter`, `body`, `params`, `EntrypointOutcome` | `@owlmeans/entrypoint` |
-| `config`, `service`, `sservice`, `toConfigRecord` | various config packages |
-| `AppType`, `BASE`, `assertContext` | `@owlmeans/context` |
-| `DAUTH_GUARD` | `@owlmeans/server-auth` |
-| `GUARD_ED25519`, `BED255_CASHE_RESOURCE` | `@owlmeans/auth-common` |
-| `klusterize` | `@owlmeans/kluster` |
-| `createListSchema`, `filterObject` | `@owlmeans/resource` |
-| `Request`, `Response`, `RefedEntrypointHandler` | type re-exports |
-| `Criteria`, `ListOptions`, `ListQuery`, `ListResult`, `Sort` | type re-exports from `@owlmeans/resource` |
+`main` is `registerEntrypoints` + `configure().init()` + `getApiServer().listen()`. Write it out when
+something must run between init and listen, or when the port must answer during a long boot:
 
-### `entrypoints`
+```ts
+import { holdApiPort } from '@owlmeans/server-app'
+import type { ApiPortHold } from '@owlmeans/server-app'
 
-Default entrypoint array providing auth and API config routes. Spread into `main()`:
-```typescript
-await main(context, [...entrypoints, ...myEntrypoints])
+const boot = async () => {
+  let hold: ApiPortHold
+  try {
+    hold = await holdApiPort(config, { okPath: '/healthz', payload: () => ({ status: 'booting' }) })
+  } catch (error) {
+    console.error('port is taken', error)
+    process.exit(1) // a failed bind must be fatal
+  }
+
+  const context = makeContext(config)
+  context.registerEntrypoints(appEntrypoints)
+  try {
+    await context.configure().init()
+    await seed(context)
+  } catch (error) {
+    console.error('boot failed', error) // the hold keeps answering 503
+    return
+  }
+
+  await hold.release()
+  await context.getApiServer().listen()
+}
+
+await boot()
 ```
 
-## Related Packages
+## API
+
+### Bootstrap
+
+| Symbol | Kind | Purpose |
+|---|---|---|
+| `makeContext<C, T>(cfg, customize = false)` | function | Server context with API server, API client, socket service and middleware, default static resource; unless `customize`, also a static `AUTH_CACHE` and `appendAuthService` |
+| `main<R, C, T>(ctx, entrypoints)` | function | Register entrypoints, `configure().init()`, then `getApiServer().listen()` |
+| `entrypoints` | const | Framework bindings: `@owlmeans/server-auth` dispatcher + `@owlmeans/api-config-server` |
+| `AppConfig` | type | `ServerConfig & KlusterConfig` with `services: Record<string, ServiceRoute>` |
+| `AppContext<C>` | type | `ServerContext<C> & AuthServiceAppend & ApiServerAppend` |
+
+### Re-exports
+
+| Symbol | Kind | Source |
+|---|---|---|
+| `config` | function | `@owlmeans/server-context` — `config(service, cfg?)` |
+| `sservice` | function | `@owlmeans/server-config` — declare a backend service route |
+| `service`, `toConfigRecord`, `PLUGINS` | function / const | `@owlmeans/config` |
+| `PluginConfig` | type | `@owlmeans/config` |
+| `addWebService` | function | `@owlmeans/client-config` |
+| `contract`, `protocol`, `typed`, `EntrypointOutcome` | function / enum | `@owlmeans/entrypoint` |
+| `Request`, `Response` | type | `AbstractRequest`, `AbstractResponse` from `@owlmeans/entrypoint` |
+| `bind`, `bindAll` | function | `@owlmeans/server-entrypoint` |
+| `handlers`, `holdApiPort` | function | `@owlmeans/server-api` |
+| `handleBody`, `handleParams`, `handleRequest`, `handleIntermediate` | function | `@owlmeans/server-api` — unbound compatibility wrappers |
+| `ApiPortHold`, `ApiPortHoldOptions` | type | `@owlmeans/server-api` |
+| `route` | function | `@owlmeans/route` |
+| `broute` | function | `route` from `@owlmeans/server-route` |
+| `ClientEntrypoint` | type | `@owlmeans/client-entrypoint` |
+| `AppType`, `BASE`, `assertContext` | enum / const / function | `@owlmeans/context` |
+| `DAUTH_GUARD` | const | `DEFAULT_ALIAS` (`'auth'`) from `@owlmeans/server-auth` |
+| `GUARD_ED25519`, `BED255_CASHE_RESOURCE` | const | `@owlmeans/auth-common` |
+| `klusterize` | function | `@owlmeans/kluster` |
+| `createListSchema`, `filterObject` | function | `@owlmeans/resource` |
+| `Criteria`, `ListOptions`, `ListQuery`, `ListResult`, `Sort` | type | `@owlmeans/resource` |
+
+## Common pitfalls
+
+- Keep `protocol()` declarations in the shared package; a server supplies implementations with
+  `bind()` and `handlers()` and never changes a declaration or finds it by alias.
+- Bind parent and group declarations (`bind(projectProtocols.base)`) as well as leaves — parents
+  establish inherited paths, guards and gates.
+- `entrypoints` holds framework registrations. Spread it into a new local array; do not mutate it.
+- The default `makeContext(cfg)` backs `AUTH_CACHE` with an in-process static resource, correct for
+  one replica only. A scaled service passes `customize: true` and registers a Redis resource under
+  `AUTH_CACHE` before `appendAuthService`.
+- Validation belongs in `contract()` with `typed()` or `schema()`, not in a wrapper around a handler.
+  Prefer `handlers<Context>()` over the unbound `handleBody` / `handleParams` / `handleRequest`.
+- Key organization-scoped records on `requireEntityKey(request)` / `requireEntity(request)`; never
+  read an organization id from the token — `entitySlug` is the only organization value on the wire.
+- Reference other services' entrypoints with `context.entrypoint(protocol)` and the protocol object,
+  without a caller-side response generic.
+- A `holdApiPort` bind failure (`EADDRINUSE`) must end the process with a non-zero exit.
+
+## Related packages
 
-- [`@owlmeans/server-context`](../server-context) — `makeServerContext` called internally by `makeContext`
-- [`@owlmeans/server-api`](../server-api) — typed handler factories re-exported here
-- [`@owlmeans/server-entrypoint`](../server-entrypoint) — protocol binding helpers
+- [`@owlmeans/server-context`](../server-context) — `makeServerContext`, called by `makeContext`
+- [`@owlmeans/server-api`](../server-api) — the Fastify API server and `handlers`
+- [`@owlmeans/server-entrypoint`](../server-entrypoint) — `bind` / `bindAll`
+- [`@owlmeans/server-socket`](../server-socket) — WebSocket bindings
+- [`@owlmeans/server-auth`](../server-auth) — the Ed25519 guard and `AUTH_CACHE`
+- [`@owlmeans/server-auth-identity`](../server-auth-identity) — local identity and entity resolver
+- [`@owlmeans/entrypoint`](../entrypoint) and [`@owlmeans/route`](../route) — shared protocol declarations
+- [`@owlmeans/static-resource`](../static-resource) — in-memory resources
+- [`@owlmeans/kluster`](../kluster) — `klusterize`
 
 <!-- owlmeans:agent-guidance:start -->
 ## Agent guidance
@@ -97,7 +310,7 @@ This package ships embedded agent skills under `agent-meta/`. After installing y
 your project's skill store (`.agents/skills/`):
 
 ```sh
-npx @owlmeans/agent-skills@^0.1.18-rc.20
+npx @owlmeans/agent-skills@^0.1.18-rc.21
 ```
 
 The embedded files are version-matched to this package release. Do not edit them

package/agent-meta/manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 2,
   "package": "@owlmeans/server-app",
-  "version": "0.1.18-rc.27",
-  "generatedAt": "2026-09-12T14:18:54.790Z",
+  "version": "0.1.18-rc.28",
+  "generatedAt": "2026-09-15T12:21:31.923Z",
   "canonicalRepo": "https://github.com/owlmeans/common",
   "entries": [
     {

package/agent-meta/skills/server-app/SKILL.md

@@ -6,7 +6,7 @@ description: Build OwlMeans server applications from immutable entrypoint protoc
 
 # Server application entrypoints
 
-**Install:** `bun add @owlmeans/server-app@^0.1.18-rc.25`
+**Install:** `bun add @owlmeans/server-app@^0.1.18-rc.27`
 
 Declare routes and request/response contracts in a shared package with `protocol()` or
 `openProtocol()`. A server package supplies local implementations with `bind()` and `handlers()`;
@@ -14,15 +14,15 @@ it never changes a shared declaration by alias.
 
 ```ts
 import { bind, entrypoints, handlers } from '@owlmeans/server-app'
-import { projectEntrypoints } from 'project-common'
+import { projectProtocols } from 'project-common'
 import { createProject } from './app/project.js'
 
 const api = handlers<Context>()
 
-export const appEntrypoints = [
+export const serverBindings = [
   ...entrypoints,
-  bind(projectEntrypoints.base),
-  bind(projectEntrypoints.create, api.body(projectEntrypoints.create, createProject)),
+  bind(projectProtocols.base),
+  bind(projectProtocols.create, api.body(projectProtocols.create, createProject)),
 ]
 ```
 

package/build/boot-state.d.ts

@@ -0,0 +1,55 @@
+import type { ApiPortHoldOptions } from '@owlmeans/server-api';
+/**
+ * Boot phase of the process.
+ *
+ * An app binds its port before it initializes, so that a failure has somewhere to be reported
+ * from. Without a listener the only thing anyone sees is a connection refused at the edge — an
+ * opaque 503 that names neither the app nor the cause. This phase is what the health path answers
+ * with, and what the platform reads to tell "still starting" from "gave up, and here is why".
+ */
+export type BootPhase = 'initializing' | 'ready' | 'failed';
+export interface BootHealth extends Record<string, unknown> {
+    status: 'OK' | 'FAILED';
+    phase: BootPhase;
+    ok: boolean;
+    /** Whatever `setBootPhase` was given — the failure message, or the step being waited on. */
+    reason?: string;
+    /**
+     * Identity, not health: a supervisor passes the id to the child it spawns and compares it
+     * here, so an answer carrying another id means the port is held by a leftover process and the
+     * health it reports describes code nobody asked for. Empty when nothing supplied one.
+     */
+    bootId: string;
+    pid: number;
+}
+/** Env var a supervisor stamps the spawned process with; surfaced as `bootId`. */
+export declare const BOOT_ID_ENV = "OWLMEANS_BOOT_ID";
+export declare const getBootPhase: () => BootPhase;
+export declare const getBootDetail: () => string | undefined;
+/**
+ * `detail` is free text, and is kept for every phase — a boot that is merely slow is as worth
+ * explaining as one that failed.
+ */
+export declare const setBootPhase: (phase: BootPhase, detail?: string) => void;
+/**
+ * The body the health path answers with, from either server.
+ *
+ * The port hold and the app's own handler both build it here, so a consumer polling through the
+ * handover never sees the shape change under it — which is why the keys are unconditional and
+ * only `reason` comes and goes with the state it describes.
+ */
+export declare const bootHealthPayload: () => BootHealth;
+/**
+ * Hold options wired to this module — the bind-first boot in one line:
+ *
+ *     const hold = await holdApiPort(ctx.cfg, bootHold(HEALTH_PATH))
+ *     try { await init() } catch (e) { setBootPhase('failed', message); return }
+ *     await hold.release()
+ *     setBootPhase('ready')
+ *     await ctx.getApiServer().listen()
+ *
+ * The hold evaluates `payload` per request, so the phase set after a failure is reported live by
+ * the listener that is already bound rather than needing a server that will never start.
+ */
+export declare const bootHold: (okPath?: string) => ApiPortHoldOptions;
+//# sourceMappingURL=boot-state.d.ts.map

package/build/boot-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"boot-state.d.ts","sourceRoot":"","sources":["../src/boot-state.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAA;AAE9D;;;;;;;GAOG;AACH,MAAM,MAAM,SAAS,GAAG,cAAc,GAAG,OAAO,GAAG,QAAQ,CAAA;AAE3D,MAAM,WAAW,UAAW,SAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACzD,MAAM,EAAE,IAAI,GAAG,QAAQ,CAAA;IACvB,KAAK,EAAE,SAAS,CAAA;IAChB,EAAE,EAAE,OAAO,CAAA;IACX,4FAA4F;IAC5F,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAA;IACd,GAAG,EAAE,MAAM,CAAA;CACZ;AAED,kFAAkF;AAClF,eAAO,MAAM,WAAW,qBAAqB,CAAA;AAK7C,eAAO,MAAM,YAAY,QAAO,SAAmB,CAAA;AAEnD,eAAO,MAAM,aAAa,QAAO,MAAM,GAAG,SAAoB,CAAA;AAE9D;;;GAGG;AACH,eAAO,MAAM,YAAY,UAAW,SAAS,WAAW,MAAM,KAAG,IAGhE,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,QAAO,UAOnC,CAAA;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,QAAQ,YAAa,MAAM,KAAG,kBAGzC,CAAA"}

package/build/boot-state.js

@@ -0,0 +1,46 @@
+/** Env var a supervisor stamps the spawned process with; surfaced as `bootId`. */
+export const BOOT_ID_ENV = 'OWLMEANS_BOOT_ID';
+let _phase = 'initializing';
+let _detail;
+export const getBootPhase = () => _phase;
+export const getBootDetail = () => _detail;
+/**
+ * `detail` is free text, and is kept for every phase — a boot that is merely slow is as worth
+ * explaining as one that failed.
+ */
+export const setBootPhase = (phase, detail) => {
+    _phase = phase;
+    _detail = detail;
+};
+/**
+ * The body the health path answers with, from either server.
+ *
+ * The port hold and the app's own handler both build it here, so a consumer polling through the
+ * handover never sees the shape change under it — which is why the keys are unconditional and
+ * only `reason` comes and goes with the state it describes.
+ */
+export const bootHealthPayload = () => ({
+    status: _phase === 'failed' ? 'FAILED' : 'OK',
+    phase: _phase,
+    ok: _phase === 'ready',
+    ...(_detail != null ? { reason: _detail } : {}),
+    bootId: process.env[BOOT_ID_ENV] ?? '',
+    pid: process.pid
+});
+/**
+ * Hold options wired to this module — the bind-first boot in one line:
+ *
+ *     const hold = await holdApiPort(ctx.cfg, bootHold(HEALTH_PATH))
+ *     try { await init() } catch (e) { setBootPhase('failed', message); return }
+ *     await hold.release()
+ *     setBootPhase('ready')
+ *     await ctx.getApiServer().listen()
+ *
+ * The hold evaluates `payload` per request, so the phase set after a failure is reported live by
+ * the listener that is already bound rather than needing a server that will never start.
+ */
+export const bootHold = (okPath) => ({
+    ...(okPath != null ? { okPath } : {}),
+    payload: bootHealthPayload
+});
+//# sourceMappingURL=boot-state.js.map

package/build/boot-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"boot-state.js","sourceRoot":"","sources":["../src/boot-state.ts"],"names":[],"mappings":"AA2BA,kFAAkF;AAClF,MAAM,CAAC,MAAM,WAAW,GAAG,kBAAkB,CAAA;AAE7C,IAAI,MAAM,GAAc,cAAc,CAAA;AACtC,IAAI,OAA2B,CAAA;AAE/B,MAAM,CAAC,MAAM,YAAY,GAAG,GAAc,EAAE,CAAC,MAAM,CAAA;AAEnD,MAAM,CAAC,MAAM,aAAa,GAAG,GAAuB,EAAE,CAAC,OAAO,CAAA;AAE9D;;;GAGG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,KAAgB,EAAE,MAAe,EAAQ,EAAE;IACtE,MAAM,GAAG,KAAK,CAAA;IACd,OAAO,GAAG,MAAM,CAAA;AAClB,CAAC,CAAA;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,GAAe,EAAE,CAAC,CAAC;IAClD,MAAM,EAAE,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI;IAC7C,KAAK,EAAE,MAAM;IACb,EAAE,EAAE,MAAM,KAAK,OAAO;IACtB,GAAG,CAAC,OAAO,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAC/C,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,IAAI,EAAE;IACtC,GAAG,EAAE,OAAO,CAAC,GAAG;CACjB,CAAC,CAAA;AAEF;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,MAAe,EAAsB,EAAE,CAAC,CAAC;IAChE,GAAG,CAAC,MAAM,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IACrC,OAAO,EAAE,iBAAiB;CAC3B,CAAC,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@owlmeans/server-app",
-  "version": "0.1.18-rc.27",
+  "version": "0.1.18-rc.28",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -21,21 +21,21 @@
     }
   },
   "dependencies": {
-    "@owlmeans/api": "^0.1.18-rc.21",
-    "@owlmeans/client-config": "^0.1.18-rc.20",
-    "@owlmeans/client-entrypoint": "^0.1.18-rc.21",
-    "@owlmeans/config": "^0.1.18-rc.20",
-    "@owlmeans/context": "^0.1.18-rc.16",
-    "@owlmeans/kluster": "^0.1.18-rc.20",
-    "@owlmeans/entrypoint": "^0.1.18-rc.19",
-    "@owlmeans/route": "^0.1.18-rc.17",
-    "@owlmeans/server-api": "^0.1.18-rc.25",
-    "@owlmeans/server-auth": "^0.1.18-rc.27",
-    "@owlmeans/server-context": "^0.1.18-rc.20",
-    "@owlmeans/server-entrypoint": "^0.1.18-rc.19",
-    "@owlmeans/server-route": "^0.1.18-rc.17",
-    "@owlmeans/server-socket": "^0.1.18-rc.27",
-    "@owlmeans/static-resource": "^0.1.18-rc.17"
+    "@owlmeans/api": "^0.1.18-rc.22",
+    "@owlmeans/client-config": "^0.1.18-rc.21",
+    "@owlmeans/client-entrypoint": "^0.1.18-rc.22",
+    "@owlmeans/config": "^0.1.18-rc.21",
+    "@owlmeans/context": "^0.1.18-rc.17",
+    "@owlmeans/kluster": "^0.1.18-rc.21",
+    "@owlmeans/entrypoint": "^0.1.18-rc.20",
+    "@owlmeans/route": "^0.1.18-rc.18",
+    "@owlmeans/server-api": "^0.1.18-rc.26",
+    "@owlmeans/server-auth": "^0.1.18-rc.28",
+    "@owlmeans/server-context": "^0.1.18-rc.21",
+    "@owlmeans/server-entrypoint": "^0.1.18-rc.20",
+    "@owlmeans/server-route": "^0.1.18-rc.18",
+    "@owlmeans/server-socket": "^0.1.18-rc.28",
+    "@owlmeans/static-resource": "^0.1.18-rc.18"
   },
   "devDependencies": {
     "@owlmeans/dep-config": "workspace:*",