@ingenioz-it/caits 0.0.0-stage → 0.5.0

package/src/di/Container.ts

@@ -0,0 +1,123 @@
+import { Token } from "../Token.js";
+
+/** What the build writes next to each class: the parameters of its constructor, in order. */
+export const DEPENDENCIES = Symbol.for("kernel.dependencies");
+
+/**
+ * A parameter of a constructor: its name, and the token of its type when the type has one (a port and its token, or a class). The name
+ * of the type goes with its token: if the module of the type declares no token, the error names the type.
+ */
+export type Dependency = { readonly name: string; readonly type?: string; readonly token?: () => unknown; readonly optional?: true };
+
+export type Concrete<T = unknown> = new (...args: never[]) => T;
+export type Key<T = unknown> = Token<T> | (abstract new (...args: never[]) => T);
+
+/** How the container gets what a key stands for: it builds a class, it gives a value, or it makes the value when something needs it. */
+export type Binding =
+  | { readonly key: Key; readonly to: Concrete; readonly values: Readonly<Record<string, unknown>> }
+  | { readonly key: Key; readonly value: unknown }
+  | { readonly key: Key; readonly make: () => unknown };
+
+type ClassBinding<T> = Binding & {
+  /** The values of some parameters of the class, by their names. */
+  with(values: Readonly<Record<string, unknown>>): ClassBinding<T>;
+};
+
+const toClass = <T>(key: Key<T>, to: Concrete, values: Readonly<Record<string, unknown>>): ClassBinding<T> =>
+  ({ key, to, values, with: more => toClass(key, to, { ...values, ...more }) });
+
+/**
+ * Says what a key stands for: `bind(Port).to(Adapter)`, `bind(Token).toValue(value)`, `bind(Token).toFactory(() => value)`,
+ * `bind(SomeClass).with({ parameter: value })`.
+ */
+export function bind<T>(key: Key<T>) {
+  return {
+    to: <I extends T>(implementation: Concrete<I>): ClassBinding<T> => toClass(key, implementation, {}),
+    toValue: (value: T): Binding => ({ key, value }),
+    toFactory: (make: () => T): Binding => ({ key, make }),
+    with: (values: Readonly<Record<string, unknown>>): ClassBinding<T> => toClass(key, key as Concrete, values)
+  };
+}
+
+const describe = (route: readonly Key[]) => route.map(key => key.name).join(" → ");
+const isKey = (value: unknown): value is Key => value instanceof Token || typeof value === "function";
+
+/**
+ * Builds a class with its dependencies, and the dependencies of its dependencies. A key without a binding is built if it is a class.
+ * Each key gives one instance; `create` gives a new instance of a class each time. A child container (for a request) has bindings of
+ * its own, and asks its parent for the others: what the parent builds never depends on what only the child binds.
+ */
+export class Container {
+  private readonly bindings = new Map<Key, Binding>();
+  private readonly built = new Map<Key, unknown>();
+
+  constructor(bindings: readonly Binding[] = [], private readonly parent?: Container) {
+    for (const binding of bindings) this.bindings.set(binding.key, binding);
+  }
+
+  /** A container whose bindings come first, and which asks this container for the others. */
+  child(bindings: readonly Binding[]): Container {
+    return new Container(bindings, this);
+  }
+
+  /** Tells if a binding of this container, or of its parents, says what this key stands for. */
+  has(key: Key): boolean {
+    return this.bindings.has(key) || this.parent?.has(key) === true;
+  }
+
+  /** The instance of a key: built the first time something needs it, then kept. */
+  get<T>(key: Key<T>): T {
+    return this.resolve(key, [], true) as T;
+  }
+
+  /** A new instance of a class, with its dependencies. */
+  create<T>(type: Concrete<T>): T {
+    return this.build(type, {}, [type], true) as T;
+  }
+
+  /** Makes sure that the container can build a class: each dependency has a binding, a value or a default. It builds nothing. */
+  check(type: Concrete): void {
+    this.build(type, {}, [type], false);
+  }
+
+  /** From now on, this value stands for the key. */
+  use<T, Given extends T>(key: Key<T>, value: Given): Given {
+    this.bindings.set(key, { key, value });
+    return value;
+  }
+
+  private resolve(key: Key, path: readonly Key[], make: boolean): unknown {
+    const binding = this.bindings.get(key);
+    if (!binding && this.parent?.has(key)) return this.parent.resolve(key, path, make);
+    if (binding && "value" in binding) return binding.value;
+    if (this.built.has(key)) return this.built.get(key);
+    const route = [...path, key];
+    if (path.includes(key)) throw new Error(`Circular dependency: ${describe(route)}`);
+    if (!binding && key instanceof Token) throw new Error(`Nothing is bound to ${describe(route)}`);
+    const instance = !binding ? this.build(key as Concrete, {}, route, make)
+      : "make" in binding ? (make ? binding.make() : undefined)
+      : this.build(binding.to, binding.values, route, make);
+    if (make) this.built.set(key, instance);
+    return instance;
+  }
+
+  private build(type: Concrete, values: Readonly<Record<string, unknown>>, path: readonly Key[], make: boolean): unknown {
+    const dependencies = (type as unknown as { [DEPENDENCIES]?: readonly Dependency[] })[DEPENDENCIES];
+    if (!dependencies && type.length > 0) throw new Error(`${type.name} declares no dependencies: the build must run the dependencies plugin`);
+    for (const name of Object.keys(values)) {
+      if (!dependencies?.some(dependency => dependency.name === name)) throw new Error(`${type.name} has no parameter named ${name}`);
+    }
+    const args = (dependencies ?? []).map(({ name, type: typeName, token, optional }) => {
+      if (Object.hasOwn(values, name)) return values[name];
+      const key = token?.();
+      // An optional parameter keeps its default value when its type has no token, or when nothing is bound to its token.
+      if (optional && (!isKey(key) || (key instanceof Token && !this.has(key)))) return undefined;
+      if (isKey(key)) return this.resolve(key, path, make);
+      const bound = path[path.length - 1];
+      const binding = bound === type ? `bind(${type.name})` : `bind(${bound.name}).to(${type.name})`;
+      const noToken = typeName ? `its type ${typeName} has no token (export const ${typeName} = new Token<${typeName}>()), or ` : "";
+      throw new Error(`${describe(path)} needs a value for its parameter ${name}: ${noToken}give it with ${binding}.with({ ${name}: … })`);
+    });
+    return make ? new type(...(args as never[])) : undefined;
+  }
+}

package/src/di/DataDirectory.ts

@@ -0,0 +1,6 @@
+import { Token } from "../Token.js";
+
+/** The folder where the adapters that write files keep their data. */
+export type DataDirectory = string;
+
+export const DataDirectory = new Token<DataDirectory>();

package/src/di/Fetcher.ts

@@ -0,0 +1,6 @@
+import { Token } from "../Token.js";
+
+/** How a frontend reaches the API: on the server, the fetch of the request; in the browser, the fetch of the browser. */
+export type Fetcher = (input: string, init?: RequestInit) => Promise<Response>;
+
+export const Fetcher = new Token<Fetcher>();

package/src/di/RequestContext.ts

@@ -0,0 +1,6 @@
+import { Token } from "../Token.js";
+
+/** What the backend knows of the request that a handler or a controller serves. */
+export type RequestContext = { readonly correlationId: string };
+
+export const RequestContext = new Token<RequestContext>();

package/src/di/backend.ts

@@ -0,0 +1,19 @@
+import { createBackend, type Backend, type BackendOptions } from "./createBackend.js";
+import { discovered } from "./discovered.js";
+
+let current: Backend | undefined;
+
+/** Starts the backend that serves the requests, with the bindings given replacing those of the contexts. */
+export function startBackend(options: BackendOptions = {}): Backend {
+  return current = createBackend(discovered, options);
+}
+
+/** The backend that serves the requests, started with the production bindings on first use. */
+export function backend(): Backend {
+  return current ?? startBackend();
+}
+
+/** The controller of a context, built for a new request with a correlation id of its own. */
+export function controller<C>(type: abstract new (...args: never[]) => C): C {
+  return backend().controller(type, { correlationId: crypto.randomUUID() });
+}

package/src/di/createBackend.ts

@@ -0,0 +1,106 @@
+import type { DomainEvent } from "../DomainEvent.js";
+import type { Token } from "../Token.js";
+import { BackendEventBus, type Published } from "../messaging/BackendEventBus.js";
+import { ContextMap } from "../messaging/ContextMap.js";
+import { EventPublisher } from "../messaging/EventPublisher.js";
+import { InProcessMessageBus } from "../messaging/InProcessMessageBus.js";
+import type { Input } from "../messaging/Input.js";
+import { MessageBus } from "../messaging/MessageBus.js";
+import { ReportError, reportToConsole } from "../messaging/ReportError.js";
+import { bind, Container, type Binding, type Concrete } from "./Container.js";
+import type { BackendModules, Class, UseCase } from "./discover.js";
+import { RequestContext } from "./RequestContext.js";
+
+export type BackendOptions = {
+  /** Bindings that replace those of a context, or, under "shared", those of shared for every context. */
+  replace?: Partial<Record<string, readonly Binding[]>>;
+  reportError?: ReportError;
+  nextEventId?: () => string;
+};
+
+type Context = { readonly container: Container; readonly useCases: readonly UseCase[] };
+
+const SYSTEM: RequestContext = { correlationId: "system" };
+
+/**
+ * Builds every context in a container of its own, child of the container of shared: the dependencies of a context are private to it,
+ * those of shared are built once for all. Each request gets a child of its context, with its correlation id, the publisher of its events
+ * and its message bus: its handlers and its controllers are built there. The backend event bus carries the events between contexts.
+ */
+export function createBackend(modules: BackendModules, options: BackendOptions = {}) {
+  const reportError = options.reportError ?? reportToConsole;
+  const shared = new Container([bind(ReportError).toValue(reportError), ...modules.shared, ...(options.replace?.shared ?? [])]);
+  const contexts = new Map<string, Context>();
+  const owners = new Map<unknown, Context>();
+
+  const ownerOf = (owned: Class): Context => {
+    const context = owners.get(owned);
+    if (!context) throw new Error(`No context owns ${owned.name}`);
+    return context;
+  };
+
+  /** The container of a request, and its message bus: each input DTO gets a new handler. */
+  const requestOf = ({ container, useCases }: Context, request: RequestContext) => {
+    const bus = new InProcessMessageBus();
+    const scope = container.child([
+      bind(RequestContext).toValue(request),
+      bind(EventPublisher).toValue({ publish: (event: DomainEvent) => { eventBus.publish(event, request); } }),
+      ...(container.has(MessageBus) ? [] : [bind(MessageBus).toValue(bus)])
+    ]);
+    for (const { input, handler } of useCases) bus.subscribe(input as never, received => scope.create(handler as Concrete<{ execute(input: unknown): unknown }>).execute(received) as never);
+    return { scope, bus };
+  };
+
+  const send = async <Output>(input: Input<Output>, request: RequestContext = SYSTEM): Promise<Output> =>
+    requestOf(ownerOf(input.constructor as Class), request).bus.send(input);
+
+  const eventBus = new BackendEventBus({
+    map: new ContextMap(modules.map),
+    send: (input, envelope) => send(input, { correlationId: envelope.correlationId }),
+    nextEventId: options.nextEventId ?? (() => crypto.randomUUID()),
+    reportError
+  });
+
+  for (const [name, { bindings, useCases, controllers }] of Object.entries(modules.contexts)) {
+    const context = { container: shared.child([...bindings, ...(options.replace?.[name] ?? [])]), useCases };
+    for (const { input } of useCases) owners.set(input, context);
+    for (const controller of controllers) owners.set(controller, context);
+    contexts.set(name, context);
+    // A dependency that nothing gives is refused now, not when a request arrives.
+    const { scope } = requestOf(context, SYSTEM);
+    for (const type of [...useCases.map(({ handler }) => handler), ...controllers]) scope.check(type as Concrete);
+  }
+
+  /** The contexts that bind a token that shared does not bind. */
+  const binding = (token: Token<unknown>): [string, Container][] => {
+    const found = [...contexts].filter(([, { container }]) => container.has(token)).map(([name, { container }]): [string, Container] => [name, container]);
+    if (found.length === 0) throw new Error(`No context binds ${token.name}`);
+    return found;
+  };
+
+  return {
+    /** Sends an input DTO to the context that handles it, in a request of its own. */
+    send,
+    /** The controller of a context, built for a request. */
+    controller: <C>(controller: abstract new (...args: never[]) => C, request: RequestContext = SYSTEM): C =>
+      requestOf(ownerOf(controller), request).scope.create(controller as unknown as Concrete<C>),
+    publish: (event: DomainEvent, request: RequestContext = SYSTEM) => { eventBus.publish(event, request); },
+    redeliver: (published: Published) => { eventBus.redeliver(published.event, published.envelope); },
+    subscribe: (listener: (published: Published) => void) => eventBus.subscribe(listener),
+    settled: () => eventBus.settled(),
+    /** For the tests: the dependency with this token, built now if nothing needed it before. */
+    get: <T>(token: Token<T>): T => {
+      if (shared.has(token)) return shared.get(token);
+      const found = binding(token);
+      if (found.length > 1) throw new Error(`The contexts ${found.map(([name]) => name).join(", ")} each bind ${token.name}`);
+      return found[0][1].get(token);
+    },
+    /** For the tests: the dependency that the contexts use from now on, in place of the one their bindings build. */
+    use: <T, Given extends T>(token: Token<T>, value: Given): Given => {
+      for (const container of shared.has(token) ? [shared] : binding(token).map(([, container]) => container)) container.use(token, value);
+      return value;
+    }
+  };
+}
+
+export type Backend = ReturnType<typeof createBackend>;

package/src/di/createFrontend.ts

@@ -0,0 +1,53 @@
+import { FrontendEventBus } from "../messaging/FrontendEventBus.js";
+import { EventPublisher } from "../messaging/EventPublisher.js";
+import type { EventSubscriber } from "../messaging/EventSubscriber.js";
+import { InProcessMessageBus } from "../messaging/InProcessMessageBus.js";
+import { createStore, type Store } from "../state/createStore.js";
+import type { Token } from "../Token.js";
+import { bind, Container, type Binding } from "./Container.js";
+import type { FrontendModules } from "./discoverFrontends.js";
+import { Fetcher } from "./Fetcher.js";
+
+type Handler = new () => { execute(input: unknown): unknown };
+
+/**
+ * Builds the frontend of a context: its event bus, its message bus with the handlers of its use cases, its store, and a container with
+ * the bindings of its di.ts. The container gives each class what its constructor needs: a handler gets the event bus as its
+ * EventPublisher. The store gets it as its EventSubscriber.
+ */
+function build(context: FrontendModules, fetch: Fetcher, replace: readonly Binding[]) {
+  const events = new FrontendEventBus<unknown>();
+  const container = new Container([bind(Fetcher).toValue(fetch), bind(EventPublisher).toValue(events), ...context.bindings, ...replace]);
+  const bus = new InProcessMessageBus();
+  // A handler is built for each DTO: it always gets the dependencies that the container holds at that time. A dependency that
+  // nothing gives is refused now, not when a DTO arrives.
+  for (const { input, handler } of context.useCases) {
+    container.check(handler as Handler);
+    bus.subscribe(input as never, received => container.create(handler as Handler).execute(received) as never);
+  }
+  return { events, store: createStore(context.store, { events, bus }), bus, container };
+}
+
+/** The frontend of a context, as the views get it: the publisher of its events, and the store they subscribe to. */
+export function createFrontend(context: FrontendModules, fetch: Fetcher, replace: readonly Binding[] = []): { events: EventPublisher<unknown>; store: Store<unknown> } {
+  const { events, store } = build(context, fetch, replace);
+  return { events, store };
+}
+
+/**
+ * The same frontend, with its message bus and its dependencies: the views never get them. The tests of the application send their DTOs
+ * to the message bus, subscribe to the events to read what the handlers publish, and read or replace a dependency by its token.
+ */
+export function createFrontendWithBus(context: FrontendModules, fetch: Fetcher, replace: readonly Binding[] = []) {
+  const { events, store, bus, container } = build(context, fetch, replace);
+  const subscriber: EventSubscriber<unknown> = events;
+  return {
+    events: subscriber,
+    store,
+    bus,
+    /** The dependency with this token, built now if no handler needed it before. */
+    get: <T>(token: Token<T>): T => container.get(token),
+    /** Gives the dependency that the handlers use from now on, in place of the one the bindings build. */
+    use: <T, Given extends T>(token: Token<T>, value: Given): Given => container.use(token, value)
+  };
+}

package/src/di/declareDependencies.js

@@ -0,0 +1,93 @@
+// JavaScript, not TypeScript: the Vite plugin (vite.js) imports this file, and Node loads the plugin itself. Node strips no types in
+// node_modules, where a project installs the kernel. TypeScript checks the types of the comments.
+
+/** @import { ESTree } from "vite" */
+
+/**
+ * Reads a module of TypeScript as a program: the parser of Vite (oxc) in the build, and in the tests.
+ * @typedef {(filename: string, code: string) => { program: ESTree.Program }} Parse
+ */
+
+/**
+ * The code that a module needs after its own, for the containers:
+ * - after each class that has a constructor, the dependencies of the constructor (DEPENDENCIES in Container.ts): the name of each
+ *   parameter, if it is optional, and the token of its type when the type has a value of the same name, declared in the module or
+ *   imported from a relative path, from a shortcut of the project (#…, which a package.json or a tsconfig.json maps to a folder) or from
+ *   one of the packages given (a port and its token, or a class: the kernel gives EventPublisher, DataDirectory…). The token is read only
+ *   when the container needs it, thus a cycle between modules does no harm. The name of the type goes with its token, for the errors;
+ * - the name of each token declared without one: the name of its constant.
+ * The names are text: the minifier can rename the code.
+ * @param {string} code
+ * @param {string} filename
+ * @param {Parse} parse
+ * @param {readonly string[]} packages
+ * @returns {string | undefined}
+ */
+export function declareDependencies(code, filename, parse, packages) {
+  const { program } = parse(filename, code);
+  /** @type {Map<string, { source: string; name: string }>} */
+  const imported = new Map();
+  /** @type {Set<string>} */
+  const values = new Set();
+  /** @type {{ name: string; parameters: readonly ESTree.ParamPattern[] }[]} */
+  const classes = [];
+  /** @type {string[]} */
+  const tokens = [];
+
+  for (const statement of program.body) {
+    if (statement.type === "ImportDeclaration") {
+      const source = statement.source.value;
+      if (!source.startsWith(".") && !source.startsWith("#") && !packages.some(name => source === name || source.startsWith(`${name}/`))) continue;
+      for (const specifier of statement.specifiers) {
+        if (specifier.type === "ImportSpecifier") imported.set(specifier.local.name, { source, name: nameOf(specifier.imported) });
+        if (specifier.type === "ImportDefaultSpecifier") imported.set(specifier.local.name, { source, name: "default" });
+      }
+      continue;
+    }
+    const declaration = statement.type === "ExportNamedDeclaration" || statement.type === "ExportDefaultDeclaration" ? statement.declaration : statement;
+    if (declaration?.type === "VariableDeclaration") {
+      for (const { id, init } of declaration.declarations) {
+        if (id.type !== "Identifier") continue;
+        values.add(id.name);
+        if (init?.type === "NewExpression" && init.callee.type === "Identifier" && init.callee.name === "Token" && init.arguments.length === 0) tokens.push(id.name);
+      }
+    }
+    if ((declaration?.type === "FunctionDeclaration" || declaration?.type === "TSEnumDeclaration") && declaration.id) values.add(declaration.id.name);
+    if (declaration?.type === "ClassDeclaration" && declaration.id) {
+      values.add(declaration.id.name);
+      const constructor = declaration.body.body.find(member => member.type === "MethodDefinition" && member.kind === "constructor");
+      if (constructor?.type === "MethodDefinition") classes.push({ name: declaration.id.name, parameters: constructor.value.params });
+    }
+  }
+  if (classes.length === 0 && tokens.length === 0) return undefined;
+
+  /** @type {Map<string, string>} */
+  const namespaces = new Map();
+  /** @type {(type: ESTree.TSType | undefined) => { type: string; token: string } | undefined} */
+  const tokenOf = type => {
+    if (type?.type !== "TSTypeReference" || type.typeName.type !== "Identifier") return undefined;
+    const name = type.typeName.name;
+    if (values.has(name)) return { type: name, token: name };
+    const from = imported.get(name);
+    if (!from) return undefined;
+    if (!namespaces.has(from.source)) namespaces.set(from.source, `__dependencies_${namespaces.size}`);
+    return { type: name, token: `${namespaces.get(from.source)}[${JSON.stringify(from.name)}]` };
+  };
+  /** @type {(parameter: ESTree.ParamPattern, index: number) => string} */
+  const dependencyOf = (parameter, index) => {
+    const inner = parameter.type === "TSParameterProperty" ? parameter.parameter : parameter;
+    const pattern = inner.type === "AssignmentPattern" ? inner.left : inner;
+    const name = pattern.type === "Identifier" ? pattern.name : `#${index}`;
+    const typed = tokenOf(pattern.typeAnnotation?.typeAnnotation);
+    const optional = inner.type === "AssignmentPattern" || pattern.optional === true;
+    return `{ name: ${JSON.stringify(name)}${typed ? `, type: ${JSON.stringify(typed.type)}, token: () => ${typed.token}` : ""}${optional ? ", optional: true" : ""} }`;
+  };
+
+  const declarations = classes.map(({ name, parameters }) => `${name}[Symbol.for("kernel.dependencies")] = [${parameters.map(dependencyOf).join(", ")}];`);
+  const imports = [...namespaces].map(([source, alias]) => `import * as ${alias} from ${JSON.stringify(source)};`);
+  const names = tokens.map(name => `${name}.name = ${JSON.stringify(name)};`);
+  return [...imports, ...declarations, ...names].join("\n");
+}
+
+/** @type {(name: ESTree.ModuleExportName) => string} */
+const nameOf = name => name.type === "Literal" ? name.value : name.name;

package/src/di/discover.ts

@@ -0,0 +1,39 @@
+import type { Translation } from "../messaging/ContextMap.js";
+import { Input } from "../messaging/Input.js";
+import type { Binding } from "./Container.js";
+
+export type Class = abstract new (...args: never[]) => unknown;
+export type UseCase = { readonly input: Class; readonly handler: Class };
+export type ContextModules = { bindings: readonly Binding[]; useCases: UseCase[]; controllers: Class[] };
+export type BackendModules = { shared: readonly Binding[]; contexts: Record<string, ContextModules>; map: Translation[] };
+
+type Modules = Record<string, Record<string, unknown>>;
+
+const contextOf = (path: string) => /backend\/([^/]+)\//.exec(path)![1];
+export const classesOf = (module: Record<string, unknown>) => Object.values(module).filter((value): value is Class => typeof value === "function");
+
+export function single<T>(found: T[], what: string): T {
+  if (found.length !== 1) throw new Error(`${what} (found ${found.length})`);
+  return found[0];
+}
+
+/** Turns the modules found in the backend folder (src/backend by default) into the contexts of the backend: a handler serves the input DTO of its use-case folder. */
+export function discover(found: { bindings: Record<string, readonly Binding[]>; dtos: Modules; handlers: Modules; controllers: Modules; map: Record<string, Translation[]> }): BackendModules {
+  const contexts: Record<string, ContextModules> = {};
+  const context = (path: string) => contexts[contextOf(path)] ??= { bindings: [], useCases: [], controllers: [] };
+  let shared: readonly Binding[] = [];
+
+  for (const [path, bindings] of Object.entries(found.bindings)) {
+    if (contextOf(path) === "shared") shared = bindings;
+    else context(path).bindings = bindings;
+  }
+  for (const [path, module] of Object.entries(found.handlers)) {
+    const dto = path.replace(".handler.ts", ".dto.ts");
+    const input = single(classesOf(found.dtos[dto] ?? {}).filter(type => type.prototype instanceof Input), `${dto} declares one input DTO`);
+    const handler = single(classesOf(module), `${path} declares one handler`);
+    context(path).useCases.push({ input, handler });
+  }
+  for (const [path, module] of Object.entries(found.controllers)) context(path).controllers.push(...classesOf(module));
+
+  return { shared, contexts, map: Object.values(found.map)[0] ?? [] };
+}

package/src/di/discoverFrontends.ts

@@ -0,0 +1,36 @@
+import { Input } from "../messaging/Input.js";
+import type { StoreDefinition } from "../state/createStore.js";
+import type { Binding } from "./Container.js";
+import { classesOf, single, type UseCase } from "./discover.js";
+
+export type FrontendModules = { bindings: readonly Binding[]; useCases: UseCase[]; store: StoreDefinition<unknown, unknown> };
+
+type Modules = Record<string, Record<string, unknown>>;
+
+const contextOf = (path: string) => /frontend\/([^/]+)\//.exec(path)![1];
+
+/**
+ * Turns the modules found in the frontend folder (src/frontend by default) into the contexts of the frontend: a context has a di.ts and a store,
+ * and a handler serves the input DTO of its use-case folder.
+ */
+export function discoverFrontends(found: {
+  bindings: Record<string, readonly Binding[]>;
+  dtos: Modules;
+  handlers: Modules;
+  stores: Record<string, StoreDefinition<unknown, unknown>>;
+}): Record<string, FrontendModules> {
+  const contexts: Record<string, FrontendModules> = {};
+  for (const [path, bindings] of Object.entries(found.bindings)) {
+    const name = contextOf(path);
+    const store = single(Object.entries(found.stores).filter(([storePath]) => contextOf(storePath) === name).map(([, definition]) => definition), `the frontend ${name} declares one store in presentation/store/`);
+    contexts[name] = { bindings, useCases: [], store };
+  }
+  for (const [path, module] of Object.entries(found.handlers)) {
+    const context = contexts[contextOf(path)];
+    if (!context) throw new Error(`${path} belongs to a frontend without a di.ts`);
+    const dto = path.replace(".handler.ts", ".dto.ts");
+    const input = single(classesOf(found.dtos[dto] ?? {}).filter(type => type.prototype instanceof Input), `${dto} declares one input DTO`);
+    context.useCases.push({ input, handler: single(classesOf(module), `${path} declares one handler`) });
+  }
+  return contexts;
+}

package/src/di/discovered.ts

@@ -0,0 +1,6 @@
+/// <reference path="../virtual-modules.d.ts" />
+import { bindings, dtos, handlers, controllers, map } from "virtual:kernel/backend";
+import { discover } from "./discover.js";
+
+/** Every context of the backend: its di.ts, its use cases and its controllers, and the context map. The plugin of the kernel finds them. */
+export const discovered = discover({ bindings, dtos, handlers, controllers, map });

package/src/di/discoveredFrontends.ts

@@ -0,0 +1,6 @@
+/// <reference path="../virtual-modules.d.ts" />
+import { bindings, dtos, handlers, stores } from "virtual:kernel/frontend";
+import { discoverFrontends } from "./discoverFrontends.js";
+
+/** Every context of the frontend: its di.ts, its use cases and its store. The plugin of the kernel finds them. */
+export const discoveredFrontends = discoverFrontends({ bindings, dtos, handlers, stores });

package/src/di/frontend.ts

@@ -0,0 +1,33 @@
+import { createFrontend } from "./createFrontend.js";
+import { discoveredFrontends } from "./discoveredFrontends.js";
+import type { Fetcher } from "./Fetcher.js";
+
+/**
+ * The frontends of the contexts, by name. Each context adds its own, next to its type:
+ * `declare module "@ingenioz-it/caits/di/frontend" { interface Frontends { counter: CounterFrontend } }`.
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type -- the contexts fill it
+export interface Frontends {}
+
+const kept = Symbol("frontends");
+type Global = { fetch?: Fetcher; [kept]?: Map<string, unknown> };
+
+/** The frontends kept on a $global, by name. A test can put its own there before a view asks. */
+export function frontendsOn($global: object): Map<string, unknown> {
+  return ($global as Global)[kept] ??= new Map<string, unknown>();
+}
+
+/**
+ * The frontend of a context, for the views of one $global: the server has one $global per request, the browser one per page.
+ * It is built the first time a view asks. On the server, it reaches the API with the fetch of the request (Marko Run, in the
+ * same process); in the browser, with the fetch of the browser.
+ */
+export function frontendOf<Name extends keyof Frontends>($global: object, name: Name): Frontends[Name] {
+  const frontends = frontendsOn($global);
+  if (!frontends.has(name)) {
+    const context = discoveredFrontends[name];
+    if (!context) throw new Error(`No frontend context is named ${name}`);
+    frontends.set(name, createFrontend(context, ($global as Global).fetch ?? ((input, init) => fetch(input, init))));
+  }
+  return frontends.get(name) as Frontends[Name];
+}

package/src/http/failureOf.ts

@@ -0,0 +1,10 @@
+/** The error of a refused HTTP request: the `detail` of its problem when it is text, otherwise its status. */
+export async function failureOf(response: Response): Promise<Error> {
+  const fallback = `HTTP ${response.status}`;
+  try {
+    const body = (await response.json()) as { detail?: unknown } | null;
+    return new Error(typeof body?.detail === "string" ? body.detail : fallback);
+  } catch {
+    return new Error(fallback);
+  }
+}

package/src/messaging/BackendEventBus.ts

@@ -0,0 +1,60 @@
+import type { DomainEvent } from "../DomainEvent.js";
+import type { ContextMap, Envelope } from "./ContextMap.js";
+import type { Input } from "./Input.js";
+import type { ReportError } from "./ReportError.js";
+
+export type Published = { readonly event: DomainEvent; readonly envelope: Envelope };
+
+const nextTurn = () => new Promise(resolve => { setTimeout(resolve, 0); });
+
+/**
+ * Carries the events of the contexts. The context map turns each event into input DTOs, and each input goes to the context that
+ * handles it. The publisher never waits for the reactions; every failure is reported.
+ */
+export class BackendEventBus {
+  private inFlight = new Set<Promise<void>>();
+  private listeners = new Set<(published: Published) => void>();
+
+  constructor(private readonly options: {
+    map: ContextMap;
+    send: (input: Input<unknown>, envelope: Envelope) => Promise<unknown>;
+    nextEventId: () => string;
+    reportError: ReportError;
+  }) {}
+
+  publish(event: DomainEvent, request: { readonly correlationId: string }): void {
+    this.redeliver(event, { eventId: this.options.nextEventId(), correlationId: request.correlationId });
+  }
+
+  /** Carries an event again, in the envelope it was first published in: what a broker does when it delivers twice. */
+  redeliver(event: DomainEvent, envelope: Envelope): void {
+    for (const listener of [...this.listeners]) listener({ event, envelope });
+    const delivery = this.deliver(event, envelope);
+    this.inFlight.add(delivery);
+    void delivery.then(() => { this.inFlight.delete(delivery); });
+  }
+
+  /** Watches every event the contexts publish. */
+  subscribe(listener: (published: Published) => void): () => void {
+    this.listeners.add(listener);
+    return () => { this.listeners.delete(listener); };
+  }
+
+  /** Waits until every event published so far, and every event they led to, has been carried. */
+  async settled(): Promise<void> {
+    while (this.inFlight.size > 0) await Promise.all([...this.inFlight]);
+  }
+
+  private async deliver(event: DomainEvent, envelope: Envelope): Promise<void> {
+    await nextTurn();
+    let inputs: Input<unknown>[];
+    try {
+      inputs = this.options.map.inputsFor(event, envelope);
+    } catch (error) {
+      this.options.reportError(error);
+      return;
+    }
+    const results = await Promise.allSettled(inputs.map(input => this.options.send(input, envelope)));
+    for (const result of results) if (result.status === "rejected") this.options.reportError(result.reason);
+  }
+}

package/src/messaging/ContextMap.ts

@@ -0,0 +1,22 @@
+import type { DomainEvent } from "../DomainEvent.js";
+import type { Input } from "./Input.js";
+
+/** What the shared bus adds to an event it carries: an id of its own, and the correlation id of the request that published it. */
+export type Envelope = { readonly eventId: string; readonly correlationId: string };
+
+type EventClass<E> = abstract new (...args: never[]) => E;
+
+export type Translation = { readonly event: EventClass<DomainEvent>; readonly inputs: (event: never, envelope: Envelope) => Input<unknown>[] };
+
+/** One line of the context map: an event of a context becomes input DTOs, for whichever contexts handle them. */
+export function when<E extends DomainEvent>(event: EventClass<E>, inputs: (event: E, envelope: Envelope) => Input<unknown>[]): Translation {
+  return { event, inputs };
+}
+
+export class ContextMap {
+  constructor(private readonly translations: Translation[]) {}
+
+  inputsFor(event: DomainEvent, envelope: Envelope): Input<unknown>[] {
+    return this.translations.filter(translation => event instanceof translation.event).flatMap(translation => translation.inputs(event as never, envelope));
+  }
+}