@zmdb/app 1.0.0-beta.1

package/src/di/index.ts

@@ -0,0 +1,179 @@
+// @zmdb/app — compile-time dependency injection (epic #262, spec ./SPEC.md).
+// Container + @Inject field decorator. No emitDecoratorMetadata, no reflection,
+// no `as` on the consumer surface. Resolution happens at build (class-init) time.
+
+// Install Symbol.metadata (used by field decorators) before any decorated class
+// in a consumer module is evaluated.
+import '../polyfill.js';
+
+// A typed injection token. The phantom `__type` carries the instance type at
+// compile time without existing at runtime (it is `never`-valued and optional).
+export interface Token<T> {
+  readonly description: string;
+  readonly __type?: T;
+}
+
+/** Create a unique injection token carrying its instance type. */
+export function createToken<T>(description: string): Token<T> {
+  return { description };
+}
+
+/** Thrown by `Container.resolve` when a token was never registered. */
+export class UnresolvedTokenError extends Error {
+  constructor(description: string) {
+    super(`@zmdb/app: no provider registered for token "${description}"`);
+    this.name = 'UnresolvedTokenError';
+  }
+}
+
+// A field-injection request recorded by @Inject. Nothing reads the slot yet — the
+// HTTP-aware devtools inspector is its first reader
+// (../../../web/src/devtools/SPEC.md §4).
+interface InjectionRequest {
+  readonly field: string | symbol;
+  readonly token: Token<unknown>;
+}
+
+const INJECTIONS = Symbol('zmdb.web.di.injections');
+
+interface DiMetadata {
+  [INJECTIONS]?: InjectionRequest[];
+}
+
+// boundary: our @Inject decorator is the only writer of the INJECTIONS slot, so
+// viewing the metadata record through DiMetadata is sound (no call-site `as`).
+function diView(metadata: DecoratorMetadata): DiMetadata {
+  return metadata;
+}
+
+/** Read the field-injection declarations recorded on a class. */
+export function injectionsOf(
+  ctor: abstract new (...args: never[]) => unknown,
+): readonly { readonly field: string | symbol; readonly token: Token<unknown> }[] {
+  const metadata = ctor[Symbol.metadata];
+  if (metadata === undefined || metadata === null) {
+    return [];
+  }
+  return diView(metadata)[INJECTIONS] ?? [];
+}
+
+// The container whose `build` is currently running. Field initializers read it
+// to resolve their token. Set for the duration of `build` and cleared in a
+// `finally`, so there is no persistent global request-time state.
+let currentContainer: Container | undefined;
+
+// Run `fn` with `container` set as the active (building) container, restoring the
+// previous one afterward. Keeps the swap out of `Container.build` so the method
+// body never aliases `this` to a variable.
+function withActiveContainer<T>(container: Container, fn: () => T): T {
+  const previous = currentContainer;
+  currentContainer = container;
+  try {
+    return fn();
+  } finally {
+    currentContainer = previous;
+  }
+}
+
+/**
+ * Field decorator: resolve `token` from the container that is building this
+ * instance. The field's declared type must be assignable from the token type,
+ * so a mismatch is a compile error and no `as` is needed.
+ */
+export function Inject<T>(token: Token<T>) {
+  return function (_value: undefined, context: ClassFieldDecoratorContext<unknown, T>): (initial: T) => T {
+    const view = diView(context.metadata);
+    const request: InjectionRequest = { field: context.name, token };
+    // A subclass's metadata record is created with the base's as its prototype, so
+    // `view[INJECTIONS]` on a subclass reads the base's array and pushing into it
+    // files the subclass's field under the base class. Copy what is inherited on
+    // the first own write, then push, so a reader sees base fields then own.
+    const own = Object.hasOwn(context.metadata, INJECTIONS) ? view[INJECTIONS] : undefined;
+    if (own === undefined) {
+      view[INJECTIONS] = [...(view[INJECTIONS] ?? []), request];
+    } else {
+      own.push(request);
+    }
+    // The initializer runs during construction; resolve from the active build.
+    return function (): T {
+      if (currentContainer === undefined) {
+        throw new Error(
+          `@zmdb/app: @Inject field "${String(context.name)}" was initialized outside container.build(...)`,
+        );
+      }
+      return currentContainer.resolve(token);
+    };
+  };
+}
+
+/** A class constructor the container can build. */
+export type Constructor<T> = new () => T;
+
+/** Provider scope: a singleton is resolved once and cached; transient re-runs. */
+export type Scope = 'singleton' | 'transient';
+
+/** The explicit, opt-in DI registry. Resolution is O(1) by token identity. */
+export class Container {
+  // Keyed by token identity. Values are the registered instances; each key's
+  // value type is guaranteed by `register`'s typed signature.
+  readonly #bindings = new Map<Token<unknown>, unknown>();
+  // Factory providers: token → { factory, scope }. Singleton factories cache
+  // their first result back into #bindings.
+  readonly #factories = new Map<Token<unknown>, { factory: (c: Container) => unknown; scope: Scope }>();
+
+  /** Bind a token to an instance. The instance type is constrained to T. */
+  register<T>(token: Token<T>, instance: T): void {
+    this.#bindings.set(token, instance);
+  }
+
+  /** Bind a token to a factory with a scope (default singleton). */
+  registerFactory<T>(token: Token<T>, factory: (c: Container) => T, scope: Scope = 'singleton'): void {
+    this.#factories.set(token, { factory, scope });
+  }
+
+  /** True if the token is registered (as a value or a factory). */
+  has<T>(token: Token<T>): boolean {
+    return this.#bindings.has(token) || this.#factories.has(token);
+  }
+
+  /** Resolve a token to its instance, or throw UnresolvedTokenError. */
+  resolve<T>(token: Token<T>): T {
+    if (this.#bindings.has(token)) {
+      return readBinding(this.#bindings, token);
+    }
+    const provider = this.#factories.get(token);
+    if (provider !== undefined) {
+      const value = provider.factory(this);
+      if (provider.scope === 'singleton') {
+        this.#bindings.set(token, value);
+      }
+      return narrowFactoryValue<T>(value);
+    }
+    throw new UnresolvedTokenError(token.description);
+  }
+
+  /**
+   * Construct `Ctor` with its `@Inject`ed fields satisfied from this container.
+   * Resolution happens here (once), then is cached on the instance.
+   */
+  build<T>(Ctor: Constructor<T>): T {
+    return withActiveContainer(this, () => new Ctor());
+  }
+}
+
+// boundary: `register<T>` is the only writer and stores exactly the token's T
+// under that token key, so reading it back as T is sound. This is the single
+// enumerated boundary cast in the DI module (ARCHITECTURE.md §2.1) — a
+// heterogeneous token→instance Map cannot prove its value type structurally, so
+// the assertion is isolated here with the soundness argument, and never appears
+// at a call site or on the consumer surface.
+function readBinding<T>(bindings: ReadonlyMap<Token<unknown>, unknown>, token: Token<T>): T {
+  return bindings.get(token) as T;
+}
+
+// boundary: a factory registered under Token<T> via registerFactory returns T by
+// construction; widening its `unknown` result to T is sound. Same enumerated DI
+// boundary as readBinding (ARCHITECTURE.md §2.1); never on the consumer surface.
+function narrowFactoryValue<T>(value: unknown): T {
+  return value as T;
+}

package/src/events/index.ts

@@ -0,0 +1,248 @@
+// @zmdb/app — typed, app-owned application events (epic #591, spec ./SPEC.md).
+// Handlers are registered explicitly, run concurrently, and report failures
+// without letting one handler stop another. Durable emission crosses through
+// the caller's transaction and the repository outbox.
+
+import '../polyfill.js';
+import { type OutboxWriter } from '@zmdb/orm/outbox';
+import { type TransactionContext } from '@zmdb/orm/transactions';
+
+/** An application-owned map from event names to payload types. */
+export interface EventMap {
+  readonly [event: string]: unknown;
+}
+
+/** One validator or handler failure observed while dispatching an event. */
+export interface EventFailure {
+  readonly event: string;
+  readonly handler: string;
+  readonly error: unknown;
+}
+
+/** The settled result of an awaited in-process emission. */
+export interface EmitReport {
+  readonly delivered: number;
+  readonly failures: readonly EventFailure[];
+}
+
+/** Construction options for one app-owned event registry. */
+export interface EventsOptions<M extends EventMap> {
+  readonly onError: (failure: EventFailure) => void;
+  readonly validate?: { readonly [K in keyof M]?: (raw: unknown) => M[K] };
+  readonly outbox?: (tx: TransactionContext) => OutboxWriter;
+}
+
+/** Typed in-process dispatch plus an explicit transactional outbox crossing. */
+export interface Events<M extends EventMap> {
+  emit<K extends keyof M & string>(event: K, payload: M[K]): void;
+  emitAndWait<K extends keyof M & string>(event: K, payload: M[K]): Promise<EmitReport>;
+  on<K extends keyof M & string>(event: K, handler: (payload: M[K]) => void | Promise<void>): () => void;
+  bind(instance: object): () => void;
+  emitInTransaction<K extends keyof M & string>(tx: TransactionContext, event: K, payload: M[K]): Promise<string>;
+}
+
+/** A handler declaration recorded by `@OnEvent`. */
+export interface ResolvedEventHandler {
+  readonly event: string;
+  readonly handlerName: string;
+}
+
+const EVENT_HANDLERS = Symbol('zmdb.web.events.handlers');
+
+interface EventMetadata {
+  [EVENT_HANDLERS]?: ResolvedEventHandler[];
+}
+
+interface StoredHandler {
+  readonly name: string;
+  invoke(payload: unknown): void | Promise<void>;
+}
+
+// boundary: @OnEvent is the only writer of the EVENT_HANDLERS slot, so this
+// typed view of decorator metadata is sound (ARCHITECTURE.md §2.1).
+function eventMetadata(metadata: DecoratorMetadata): EventMetadata {
+  return metadata;
+}
+
+/** Stage-3 method decorator recording an application-event binding. */
+export function OnEvent(event: string) {
+  return function (_target: Function, context: ClassMethodDecoratorContext): void {
+    const handlerName = typeof context.name === 'string' ? context.name : context.name.toString();
+    const view = eventMetadata(context.metadata);
+    const own = Object.hasOwn(context.metadata, EVENT_HANDLERS) ? view[EVENT_HANDLERS] : undefined;
+    const binding = { event, handlerName };
+    if (own === undefined) {
+      view[EVENT_HANDLERS] = [...(view[EVENT_HANDLERS] ?? []), binding];
+    } else {
+      own.push(binding);
+    }
+  };
+}
+
+function handlersDeclaredBy(cls: Function): readonly ResolvedEventHandler[] {
+  const metadata = cls[Symbol.metadata];
+  if (metadata === undefined || metadata === null) {
+    return [];
+  }
+  return eventMetadata(metadata)[EVENT_HANDLERS] ?? [];
+}
+
+/** Read the bindings declared by a class. Nothing scans or constructs it. */
+export function getEventHandlers(cls: abstract new (...args: never[]) => unknown): readonly ResolvedEventHandler[] {
+  return handlersDeclaredBy(cls);
+}
+
+function storedHandler<P>(
+  handler: (payload: P) => void | Promise<void>,
+  name = handler.name || '<anonymous>',
+): StoredHandler {
+  return {
+    name,
+    async invoke(payload: unknown): Promise<void> {
+      // The public `on(event, handler)` signature ties P to the same event key
+      // used by the registry; Reflect.apply is the erased runtime crossing.
+      await Reflect.apply(handler, undefined, [payload]);
+    },
+  };
+}
+
+function boundHandler(instance: object, declaration: ResolvedEventHandler): StoredHandler {
+  const value: unknown = Reflect.get(instance, declaration.handlerName);
+  if (typeof value !== 'function') {
+    throw new Error(`@zmdb/app: @OnEvent handler "${declaration.handlerName}" is not a callable instance method`);
+  }
+  return {
+    name: declaration.handlerName,
+    async invoke(payload: unknown): Promise<void> {
+      await Reflect.apply(value, instance, [payload]);
+    },
+  };
+}
+
+function invoke(handler: StoredHandler, payload: unknown): Promise<void> {
+  try {
+    return Promise.resolve(handler.invoke(payload));
+  } catch (error) {
+    return Promise.reject(error);
+  }
+}
+
+/** Build one isolated event registry for an application. */
+export function createEvents<M extends EventMap>(options: EventsOptions<M>): Events<M> {
+  const handlers = new Map<string, StoredHandler[]>();
+
+  const report = (failure: EventFailure): void => {
+    try {
+      options.onError(failure);
+    } catch {
+      // The error sink is the terminal reporting boundary. Its own exception
+      // must not turn a fire-and-forget emission into an unhandled rejection.
+    }
+  };
+
+  const register = (event: string, handler: StoredHandler): (() => void) => {
+    const registrations = handlers.get(event);
+    if (registrations === undefined) {
+      handlers.set(event, [handler]);
+    } else {
+      registrations.push(handler);
+    }
+
+    let active = true;
+    return (): void => {
+      if (!active) {
+        return;
+      }
+      active = false;
+      const current = handlers.get(event);
+      if (current === undefined) {
+        return;
+      }
+      const index = current.indexOf(handler);
+      if (index >= 0) {
+        current.splice(index, 1);
+      }
+      if (current.length === 0) {
+        handlers.delete(event);
+      }
+    };
+  };
+
+  const dispatch = async <K extends keyof M & string>(event: K, payload: M[K]): Promise<EmitReport> => {
+    let checked = payload;
+    try {
+      const validator = options.validate?.[event];
+      if (validator !== undefined) {
+        checked = validator(payload);
+      }
+    } catch (error) {
+      const failure: EventFailure = { event, handler: 'validate', error };
+      report(failure);
+      return { delivered: 0, failures: [failure] };
+    }
+
+    const registrations = [...(handlers.get(event) ?? [])];
+    const settled = await Promise.allSettled(registrations.map(handler => invoke(handler, checked)));
+    const failures: EventFailure[] = [];
+    let delivered = 0;
+    for (let index = 0; index < settled.length; index += 1) {
+      const outcome = settled[index];
+      const registration = registrations[index];
+      if (outcome?.status === 'fulfilled') {
+        delivered += 1;
+      } else if (outcome !== undefined && registration !== undefined) {
+        const failure: EventFailure = {
+          event,
+          handler: registration.name,
+          error: outcome.reason,
+        };
+        failures.push(failure);
+        report(failure);
+      }
+    }
+    return { delivered, failures };
+  };
+
+  return {
+    emit(event, payload): void {
+      void dispatch(event, payload).catch(error => {
+        report({ event, handler: '<dispatch>', error });
+      });
+    },
+
+    emitAndWait: dispatch,
+
+    on(event, handler): () => void {
+      return register(event, storedHandler(handler));
+    },
+
+    bind(instance): () => void {
+      const ctor = instance.constructor;
+      const declarations = typeof ctor === 'function' ? handlersDeclaredBy(ctor) : [];
+      const disposers = declarations.map(declaration =>
+        register(declaration.event, boundHandler(instance, declaration)),
+      );
+      let active = true;
+      return (): void => {
+        if (!active) {
+          return;
+        }
+        active = false;
+        for (const dispose of disposers) {
+          dispose();
+        }
+      };
+    },
+
+    async emitInTransaction(tx, event, payload): Promise<string> {
+      if (options.outbox === undefined) {
+        throw new Error('@zmdb/app: emitInTransaction requires an outbox writer');
+      }
+      const encoded = JSON.stringify(payload);
+      if (encoded === undefined) {
+        throw new Error('@zmdb/app: event payload is not JSON-serializable');
+      }
+      return options.outbox(tx).write(event, encoded);
+    },
+  };
+}

package/src/health/index.ts

@@ -0,0 +1,54 @@
+import { type Driver } from '@zmdb/orm';
+
+/** The process is not wedged. Synchronous by construction. */
+export interface LivenessCheck {
+  readonly name: string;
+  run(): boolean;
+}
+
+export interface CheckResult {
+  readonly ok: boolean;
+  readonly detail?: string;
+}
+
+/** The process can serve traffic. Dependencies receive an explicit deadline. */
+export interface ReadinessCheck {
+  readonly name: string;
+  readonly timeoutMs: number;
+  readonly cacheMs?: number;
+  run(signal: AbortSignal): Promise<CheckResult>;
+}
+
+export interface HealthChecks {
+  readonly liveness?: readonly LivenessCheck[];
+  readonly readiness?: readonly ReadinessCheck[];
+}
+
+export interface DetailedCheck {
+  readonly name: string;
+  readonly ok: boolean;
+  readonly detail?: string;
+  readonly durationMs?: number;
+}
+
+export interface DatabaseReadinessOptions {
+  readonly name?: string;
+  readonly timeoutMs: number;
+  readonly cacheMs?: number;
+}
+
+/** Build the protocol-neutral readiness check for one required database. */
+export function databaseReadinessCheck(
+  driver: Pick<Driver, 'execute'>,
+  options: DatabaseReadinessOptions,
+): ReadinessCheck {
+  return {
+    name: options.name ?? 'database',
+    timeoutMs: options.timeoutMs,
+    ...(options.cacheMs === undefined ? {} : { cacheMs: options.cacheMs }),
+    async run(signal) {
+      await driver.execute({ text: 'SELECT 1', parameters: [] }, { signal });
+      return { ok: true };
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,68 @@
+// @zmdb/app — the protocol-neutral application kernel.
+//
+// This entry owns the one Stage-3 metadata installation and reader, the
+// application graph, dependency injection and lifecycle. Concern-heavy
+// capabilities such as command parsing, events and observability remain behind
+// their explicit subpaths.
+
+import './polyfill.js';
+
+export type ApplicationMetadata = DecoratorMetadataObject;
+
+interface HasMetadata {
+  readonly [Symbol.metadata]?: DecoratorMetadata | null;
+}
+
+const EMPTY: ApplicationMetadata = Object.freeze(Object.create(null));
+
+function hasMetadata(value: object): value is { readonly [Symbol.metadata]: DecoratorMetadata } {
+  const carrier: HasMetadata = value;
+  const record = carrier[Symbol.metadata];
+  return record !== undefined && record !== null;
+}
+
+/** Read one Stage-3 metadata record, or the shared frozen empty record. */
+export function metadataOf(target: object): ApplicationMetadata {
+  return hasMetadata(target) ? target[Symbol.metadata] : EMPTY;
+}
+
+export {
+  Container,
+  createToken,
+  Inject,
+  injectionsOf,
+  UnresolvedTokenError,
+  type Constructor,
+  type Scope,
+  type Token,
+} from './di/index.js';
+export {
+  compileModule,
+  lazy,
+  Module,
+  moduleDefOf,
+  type CompiledModule,
+  type LazyImport,
+  type LazyModuleHandle,
+  type LazyStatus,
+  type ModuleClass,
+  type ModuleDef,
+  type ProviderDef,
+} from './modules/index.js';
+export {
+  createApplication,
+  type Application,
+  type ApplicationExtension,
+  type ApplicationExtensionContext,
+  type ApplicationOptions,
+} from './application.js';
+export type { OnApplicationBootstrap, OnModuleInit, OnShutdown } from './lifecycle.js';
+
+export { defineStateTransitions, createStateUpdatePayload, defineEntityStateMachine } from './state-transitions.js';
+export type {
+  StateTransitions,
+  AllowedTargetStates,
+  StateUpdateDTO,
+  EntityStateMachineOptions,
+  EntityStateMachine,
+} from './state-transitions.js';

package/src/lifecycle.ts

@@ -0,0 +1,62 @@
+// @zmdb/app — lifecycle hooks, shared by the app bootstrap and the test harness.
+//
+// Every protocol adapter and test harness delegates to this one ledger. Hook
+// detection and ordering therefore cannot drift between HTTP, commands, jobs
+// or a standalone application.
+//
+// Detection is structural `in`-narrowing on the instance: no reflection, no cast.
+
+/** Called after the eager application instances are constructed. */
+export interface OnModuleInit {
+  onModuleInit(): void | Promise<void>;
+}
+/** Called after all modules are initialized. */
+export interface OnApplicationBootstrap {
+  onApplicationBootstrap(): void | Promise<void>;
+}
+/** Called on graceful shutdown (via `await using` / dispose). */
+export interface OnShutdown {
+  onShutdown(): void | Promise<void>;
+}
+
+function hasModuleInit(x: object): x is OnModuleInit {
+  return 'onModuleInit' in x && typeof x.onModuleInit === 'function';
+}
+function hasBootstrap(x: object): x is OnApplicationBootstrap {
+  return 'onApplicationBootstrap' in x && typeof x.onApplicationBootstrap === 'function';
+}
+function hasShutdown(x: object): x is OnShutdown {
+  return 'onShutdown' in x && typeof x.onShutdown === 'function';
+}
+
+/**
+ * `onModuleInit` on every implementer, then `onApplicationBootstrap` on every
+ * implementer — two full passes, so a bootstrap hook can rely on every module
+ * having been initialized.
+ */
+export async function runInit(instances: readonly object[]): Promise<void> {
+  for (const instance of instances) {
+    if (hasModuleInit(instance)) await instance.onModuleInit();
+  }
+  for (const instance of instances) {
+    if (hasBootstrap(instance)) await instance.onApplicationBootstrap();
+  }
+}
+
+/** `onShutdown` in reverse construction order, so a dependent tears down before what it depends on. */
+export async function runShutdown(instances: readonly (object | undefined)[]): Promise<void> {
+  const errors: unknown[] = [];
+  for (let i = instances.length - 1; i >= 0; i -= 1) {
+    const instance = instances[i];
+    if (instance === undefined || !hasShutdown(instance)) continue;
+    try {
+      await instance.onShutdown();
+    } catch (error) {
+      errors.push(error);
+    }
+  }
+  if (errors.length === 1) throw errors[0];
+  if (errors.length > 1) {
+    throw new AggregateError(errors, '@zmdb/app: application shutdown hooks failed');
+  }
+}