bazis 0.136.0 → 0.138.0

package/core/websocket/DESIGN.md

@@ -30,7 +30,8 @@ import { Module, singleton } from "@/core/di";
 @Module({ gateways: [ChatGateway], providers: [singleton(ChatHistory)] })
 export class ChatModule {}
 
-await runApp(AppModule, { http: { port: 3000 }, websocket: { requireAuth: true, authenticator } });
+@App({ modules: [AppModule], http: {}, websocket: { requireAuth: true, authenticator } })
+export class Application {}
 ```
 
 Without `runApp`, `websocketModule({ imports: [ChatModule], ... })` next to
@@ -101,7 +102,7 @@ default, `replayDelivery: "transport"`.
 ### Client-confirmed replay
 
 Opt in with `?replay=client-ack` on each connection, or require it for all clients
-with `runApp({ websocket: { replayDelivery: "client-ack" } })`. The adapter
+with `@App({ websocket: { replayDelivery: "client-ack" } })`. The adapter
 must support CAS. A saved client-ack session cannot reconnect in transport mode;
 such an upgrade returns 409. Invalid/duplicate replay query values return 400.
 
@@ -150,7 +151,8 @@ Pass an existing native Bun RedisClient from the host infrastructure:
 const adapter = new RedisWebSocketAdapter(hostRedisClient, {
   keyPrefix: "my-app:ws", // same on participating nodes; distinct per application
 });
-await runApp(AppModule, { http: {}, websocket: { adapter, replayDelivery: "client-ack" } });
+@App({ modules: [AppModule], http: {}, websocket: { adapter, replayDelivery: "client-ack" } })
+export class Application {}
 ```
 
 The adapter owns only a duplicate connection for pub/sub. Closing the adapter

package/core/websocket/middleware.ts

@@ -26,7 +26,7 @@ export interface WsAuthenticationContext {
   readonly request?: Request;
   /**
    * The application's services, for a token check that needs them
-   * (`services.resolve(AuthTokens)`). Set by `runApp({ websocket })`.
+   * (`services.resolve(AuthTokens)`). Set by `@App({ websocket })`.
    */
   readonly services?: ServiceResolver;
 }

package/core/websocket/websocketModule.ts

@@ -1,5 +1,4 @@
 import {
-  DI,
   collectModuleGateways,
   markGlobal,
   Module,
@@ -8,6 +7,7 @@ import {
   type ProviderDefinition,
   type ServiceResolver,
 } from "../di";
+import { DI } from "../di/lowLevel";
 import { WEBSOCKET_UPGRADE } from "../http";
 import { LOGGER } from "../kernel";
 import { WebSocketService } from "./WebSocketService";
@@ -54,13 +54,13 @@ export interface WebSocketModuleConfig {
   readonly exposeHandlerErrors?: boolean;
 }
 
-/** Server-wide WebSocket settings of `runApp({ websocket })`; gateways come from the modules. */
+/** Server-wide WebSocket settings of `@App({ websocket })`; gateways come from the modules. */
 export type WebSocketOptions = Omit<WebSocketModuleConfig, "imports">;
 
 /**
  * Serves the gateways declared by the modules of `imports` on the shared HTTP
  * listener. `runApp` installs it next to the HTTP module whenever a module
- * declares `gateways`; `runApp({ websocket })` passes the settings.
+ * declares `gateways`; `@App({ websocket })` passes the settings.
  *
  * ```ts
  * @Module({ gateways: [ChatGateway], providers: [singleton(ChatHistory)] })

package/core/workflow/contracts/Workflow.config.ts

@@ -1,15 +1,15 @@
-import { defineConfig } from "../../kernel";
+import { configList, defineConfig } from "../../kernel";
 
 /**
  * Settings of the workflow pack, from the application configuration:
  * `BAZIS_WORKFLOW__WORKER__ENABLED=false` keeps an instance from running jobs,
  * for example a web-only one (WORKFLOW-001 §4). `language` is the default
- * language of texts, `languages` the comma-separated list a request may ask for
+ * language of texts, `languages` the list a request may ask for (comma-separated in the environment)
  * with `Accept-Language` (WORKFLOW-002 §6).
  */
 export interface WorkflowSettings {
   readonly language: string;
-  readonly languages: string;
+  readonly languages: readonly string[];
   readonly "worker.enabled": boolean;
   readonly "worker.intervalMs": number;
   readonly "worker.batchSize": number;
@@ -23,7 +23,7 @@ const LANGUAGE = /^[a-z]{2,3}(-[A-Za-z0-9]{2,8})*$/;
 export const workflowConfig = defineConfig<WorkflowSettings>("workflow", {
   default: {
     language: "en",
-    languages: "en",
+    languages: configList(["en"]),
     "worker.enabled": true,
     "worker.intervalMs": 1000,
     "worker.batchSize": 10,
@@ -33,7 +33,7 @@ export const workflowConfig = defineConfig<WorkflowSettings>("workflow", {
   },
   validate: {
     language: (value) => (LANGUAGE.test(value) ? undefined : "must be a language: en, ru, pt-BR"),
-    languages: (value) => (value.split(",").every((item) => LANGUAGE.test(item.trim())) ? undefined : "must be a comma-separated list of languages"),
+    languages: (value) => (value.every((item) => LANGUAGE.test(item)) ? undefined : "must be a list of languages: en, ru, pt-BR"),
     "worker.intervalMs": (value) => positive(value, 3_600_000),
     "worker.batchSize": (value) => positive(value, 1000),
     "retention.intervalMs": (value) => positive(value, 86_400_000),

package/core/workflow/definitions_module/WorkflowDefinitions.module.ts

@@ -12,11 +12,11 @@ import { definitionsPermissions } from "./access/Definitions.permissions";
 import { FolderReferences } from "./access/Folder.references";
 import { ProcessReferences } from "./access/Process.references";
 import { ProcessFolderLookup } from "./access/ProcessFolder.lookup";
-import { ProcessPartitionLookup } from "./access/ProcessPartition.lookup";
 import { CatalogImport } from "./code/CatalogImport";
 import { CodeProcessCatalog } from "./code/CodeProcessCatalog";
 import { CodeProcessPublisher } from "./code/CodeProcessPublisher";
 import { ProcessesController } from "./http/Processes.controller";
+import { PublishedVersions } from "./internal/PublishedVersions";
 import { DefinitionsDbContext, definitionsStore } from "./model/Definitions.dbContext";
 import { WfProcess } from "./model/WfProcess.model";
 import { WfVersion } from "./model/WfVersion.model";
@@ -39,6 +39,7 @@ import { WorkflowDefinitions } from "./services/WorkflowDefinitions.service";
     singleton(WorkflowClock, SystemWorkflowClock),
     singleton(WorkflowTools),
     singleton(CodeProcessCatalog),
+    singleton(PublishedVersions),
     singleton(WorkflowLanguages),
     singleton(WorkflowExtensions, DefaultWorkflowExtensions),
     singleton(WorkflowPartitions, DefaultWorkflowPartitions),
@@ -46,10 +47,8 @@ import { WorkflowDefinitions } from "./services/WorkflowDefinitions.service";
     scoped(WorkflowReferences),
     scoped(CatalogImport),
     scoped(IWorkflowDefinitions, WorkflowDefinitions),
-    scoped(ProcessReferences),
-    scoped(FolderReferences),
+    // Shared with the Runtime and Tasks parts: owned and exported here.
     scoped(ProcessFolderLookup),
-    scoped(ProcessPartitionLookup),
     singleton(HOSTED_SERVICE, CodeProcessPublisher),
   ],
   controllers: [ProcessesController],

package/core/workflow/definitions_module/code/defineProcess.ts

@@ -1,9 +1,134 @@
-import type { LocalizedText, ProcessDocument } from "../../../../library/workflow";
+import { toolNameOf, type DefinedTool } from "../../../agent";
+import type {
+  Expr,
+  LocalizedText,
+  NodeConfigs,
+  NodeKind,
+  ProcessDiagram,
+  ProcessDocument,
+  ProcessFlow,
+  ProcessNode,
+  ProcessNodeOf,
+  ProcessSettings,
+  TypedProcessFlow,
+  TypedProcessNode,
+  VariableSpec,
+} from "../../../../library/workflow";
 
 const CODE_PROCESS = Symbol.for("bazis/core/workflow/code-process");
+declare const PROCESS_TYPES: unique symbol;
+
+/** A class with `@Tool`: a process names it instead of writing its name. */
+export type ToolClass = abstract new (...args: never[]) => { execute(...args: never[]): unknown };
+/** A Tool of a step: by reference (a class with `@Tool`, a Tool made by `defineTool`), or by name. */
+export type ToolRef = string | ToolClass | DefinedTool;
+/** A process another one calls or hands its failures to: by reference, or by key. */
+export type ProcessRef = string | CodeProcess;
+
+/** The node configs a process in code may write: a Tool and a process by reference. */
+export interface CodeNodeConfigs extends Omit<NodeConfigs, "serviceTask" | "callProcess"> {
+  readonly serviceTask: Omit<NodeConfigs["serviceTask"], "tool"> & { readonly tool: ToolRef };
+  readonly callProcess: Omit<NodeConfigs["callProcess"], "process"> & { readonly process: ProcessRef };
+}
+
+/** A node as code writes it: the `config` of its kind, the ids of the document's own nodes. */
+export type CodeProcessNode<Id extends string = string> = TypedProcessNode<Id, CodeNodeConfigs>;
+
+/** The settings of a process in code: the error handler by reference. */
+export interface CodeProcessSettings extends Omit<ProcessSettings, "errorHandler"> {
+  /** The process to start when an instance fails or times out. */
+  readonly errorHandler?: ProcessRef;
+}
+
+type FieldValue<F> =
+  F extends { readonly type: "enum"; readonly values: readonly (infer Value)[] } ? Value
+  : F extends { readonly type: "string" | "text" | "date" | "datetime" | "ref" | "enum" } ? string
+  : F extends { readonly type: "number" | "integer" } ? number
+  : F extends { readonly type: "boolean" } ? boolean
+  : F extends { readonly type: "list" } ? readonly unknown[]
+  : F extends { readonly type: "object" } ? Readonly<Record<string, unknown>>
+  : unknown;
+
+type Flat<T> = { readonly [K in keyof T]: T[K] };
+
+/** What a start of the process takes: its `in` variables; the `required` ones must be there. */
+export type ProcessInput<V extends readonly VariableSpec[]> = string extends V[number]["name"]
+  ? Readonly<Record<string, unknown>>
+  : Flat<
+    & { [F in V[number] as F extends { readonly direction: "in"; readonly required: true } ? F["name"] : never]: FieldValue<F> }
+    & { [F in V[number] as F extends { readonly direction: "in" } ? (F extends { readonly required: true } ? never : F["name"]) : never]?: FieldValue<F> }
+  >;
+
+/** What a finished process gives back: its `out` variables. */
+export type ProcessOutput<V extends readonly VariableSpec[]> = string extends V[number]["name"]
+  ? Readonly<Record<string, unknown>>
+  : Flat<{ [F in V[number] as F extends { readonly direction: "out" } ? F["name"] : never]: FieldValue<F> | null }>;
+
+/** What a Tool takes: the parameter of its `execute`. `unknown` when it does not say. */
+type ToolInputOf<T> =
+  T extends DefinedTool<infer Input, unknown> ? Input
+  : T extends abstract new (...args: never[]) => { execute(input: infer Input, ...rest: never[]): unknown } ? Input
+  : unknown;
+
+/** `config.input` of a step against what its Tool or process takes: every required parameter, no unknown one. */
+type InputOf<Target, Given> = unknown extends Target ? unknown
+  : Target extends object
+    ? string extends keyof Target ? unknown
+      : { readonly config: ({} extends Target ? { readonly input?: MappingOf<Target, Given> } : { readonly input: MappingOf<Target, Given> }) }
+    : unknown;
+
+type MappingOf<Target, Given> = { readonly [P in keyof Target]: Expr } & { readonly [P in Exclude<keyof Given, keyof Target>]?: never };
+
+type CheckedInput<Node> =
+  Node extends { readonly kind: "serviceTask"; readonly config: { readonly tool: infer Tool; readonly input?: infer Given } } ? InputOf<ToolInputOf<Tool>, Given>
+  : Node extends { readonly kind: "callProcess"; readonly config: { readonly process: infer Called; readonly input?: infer Given } }
+    ? (Called extends CodeProcess<infer Input, unknown> ? InputOf<Input, Given> : unknown)
+    : unknown;
+
+/** The nodes of a document, as `defineProcess` reads their type. */
+export type CodeProcessNodes = Readonly<Record<string, ProcessNode | CodeProcessNode>>;
+
+type KeysOf<T> = T extends unknown ? keyof T : never;
+type ValueOf<T, K extends PropertyKey> = T extends unknown ? (K extends keyof T ? T[K] : never) : never;
+/** Whether a value of this type is not a closed object: a primitive, a list of anything, a map by any key. */
+type IsOpen<T> = T extends unknown ? (T extends readonly unknown[] ? false : T extends object ? (string extends keyof T ? true : false) : true) : never;
+
+/**
+ * `Given` with every key the allowed type does not know turned into `never`:
+ * a misspelled optional field is an error, not a field nobody reads.
+ */
+type Exact<Given, Allowed> =
+  true extends IsOpen<NonNullable<Allowed>> ? unknown
+  : Given extends readonly (infer Item)[] ? (NonNullable<Allowed> extends readonly (infer AllowedItem)[] ? readonly Exact<Item, AllowedItem>[] : unknown)
+  : Given extends object ? { readonly [P in keyof Given]: P extends KeysOf<NonNullable<Allowed>> ? Exact<Given[P], ValueOf<NonNullable<Allowed>, P>> : never }
+  : unknown;
+
+type ExactNode<Node, Id extends string> = Node extends { readonly kind: infer Kind extends NodeKind } ? Exact<Node, ProcessNodeOf<Kind, Id, CodeNodeConfigs>> : unknown;
+
+/** What the nodes written as a literal must also be: of their kind, with known fields, with the input their Tool takes. */
+type CheckedNodes<N> = string extends keyof N ? unknown : { readonly [Id in keyof N]: CodeProcessNode<keyof N & string> & CheckedInput<N[Id]> & ExactNode<N[Id], keyof N & string> };
+
+/**
+ * The document of a process in code. Written as a literal, it is checked while
+ * you type: the `config` of each node kind, the nodes that flows, `attachedTo`
+ * and `parent` name, the input of a Tool or a called process given by
+ * reference. A document that already exists as data (exported from a designer,
+ * built by a function, upgraded from version 1) is taken as it is.
+ */
+export interface CodeProcessDocument<V extends readonly VariableSpec[], N extends CodeProcessNodes> {
+  readonly schemaVersion: ProcessDocument["schemaVersion"];
+  /** `in` — the input of a start, `local` — inside the process, `out` — what it gives back. */
+  readonly variables?: V;
+  readonly settings?: CodeProcessSettings;
+  readonly nodes: N & CheckedNodes<N>;
+  readonly flows: Readonly<Record<string, string extends keyof N ? ProcessFlow : TypedProcessFlow<keyof N & string>>>;
+  readonly diagram?: ProcessDiagram;
+  /** The application's data by namespace; the engine does not read it. */
+  readonly extensions?: Readonly<Record<string, unknown>>;
+}
 
 /** What `defineProcess` takes: the catalog fields of the process and its document. */
-export interface ProcessDefinition {
+export interface ProcessDefinition<V extends readonly VariableSpec[] = readonly VariableSpec[], N extends CodeProcessNodes = CodeProcessNodes> {
   /** The key it is started by: `^[a-z][a-z0-9_.-]{0,63}$`. */
   readonly key: string;
   readonly title: LocalizedText;
@@ -14,12 +139,27 @@ export interface ProcessDefinition {
   readonly owner?: string | null;
   /** Days to keep completed and cancelled instances; omitted keeps them. */
   readonly retentionDays?: number | null;
-  readonly document: ProcessDocument;
+  readonly document: CodeProcessDocument<V, N>;
 }
 
-/** A process described in code: listed in `@Module({ processes })` and published at start (WORKFLOW-001 §14). */
-export interface CodeProcess extends ProcessDefinition {
+/**
+ * A process described in code: listed in `@Module({ processes })` and published
+ * at start (WORKFLOW-001 §14). `Input` and `Output` come from its variables:
+ * `runtime.start(process, { input })` and a `callProcess` step are checked by them.
+ * Plain `CodeProcess` is any process.
+ */
+export interface CodeProcess<Input = never, Output = unknown> {
+  readonly key: string;
+  readonly title: LocalizedText;
+  readonly description?: LocalizedText | null;
+  readonly folder?: string | null;
+  readonly owner?: string | null;
+  readonly retentionDays?: number | null;
+  /** The document as it is stored: Tools by name, processes by key. */
+  readonly document: ProcessDocument;
   readonly [CODE_PROCESS]: true;
+  /** Only for the types. */
+  readonly [PROCESS_TYPES]?: { readonly input: (input: Input) => void; readonly output: Output };
 }
 
 /**
@@ -27,20 +167,82 @@ export interface CodeProcess extends ProcessDefinition {
  * description: checks happen when the container is built and at start.
  *
  * ```ts
- * // orders_module/processes/OrderApproval.process.ts
- * export const OrderApprovalProcess = defineProcess({
+ * // order/process/OrderApproval.process.ts
+ * export const orderApproval = defineProcess({
  *   key: "order-approval",
  *   title: "Order approval",
- *   document: { schemaVersion: "bazis.workflow/v2", nodes: { … }, flows: { … } },
+ *   document: {
+ *     schemaVersion: "bazis.workflow/v2",
+ *     variables: [{ name: "orderId", type: "string", direction: "in", required: true }],
+ *     nodes: {
+ *       Start: { kind: "manualStart", title: "Start" },
+ *       Approve: { kind: "serviceTask", title: "Approve", config: { tool: SetOrderStatusTool, input: { orderId: "$input.orderId", status: "approved" } } },
+ *       End: { kind: "end", title: "End" },
+ *     },
+ *     flows: { a: { source: "Start", target: "Approve" }, b: { source: "Approve", target: "End" } },
+ *   },
  * });
+ *
+ * await runtime.start(orderApproval, { actor, input: { orderId: "o-1" } });
  * ```
  *
- * A document of version 1 goes through `upgradeDocument`.
+ * A Tool is named by its class (or by a Tool made by `defineTool`:
+ * `orderTools.find`), a called process and the error handler by their
+ * `defineProcess` result; a name or a key in a string is still taken, for what
+ * the module does not see. A document of version 1 goes through `upgradeDocument`.
  */
-export function defineProcess(definition: ProcessDefinition): CodeProcess {
-  return Object.freeze({ ...definition, [CODE_PROCESS]: true as const });
+export function defineProcess<const V extends readonly VariableSpec[] = readonly VariableSpec[], const N extends CodeProcessNodes = Readonly<Record<string, ProcessNode>>>(
+  definition: ProcessDefinition<V, N>,
+): CodeProcess<ProcessInput<V>, ProcessOutput<V>> {
+  const { document, ...catalog } = definition;
+  return Object.freeze({ ...catalog, document: storedDocument(String(definition.key), document as unknown as LooseDocument), [CODE_PROCESS]: true as const });
 }
 
 export function isCodeProcess(value: unknown): value is CodeProcess {
   return typeof value === "object" && value !== null && (value as Record<symbol, unknown>)[CODE_PROCESS] === true;
 }
+
+interface LooseDocument {
+  readonly settings?: { readonly errorHandler?: unknown };
+  readonly nodes?: unknown;
+}
+
+/** The document with its references written as the engine stores them: a Tool by name, a process by key. */
+function storedDocument(key: string, document: LooseDocument): ProcessDocument {
+  // A wrong shape is the business of the checks at start: they name every problem at once.
+  if (typeof document !== "object" || document === null) return document as unknown as ProcessDocument;
+  const out: Record<string, unknown> = { ...document };
+  if (typeof document.settings === "object" && document.settings !== null && document.settings.errorHandler !== undefined) {
+    out.settings = { ...document.settings, errorHandler: processKeyOf(key, "settings.errorHandler", document.settings.errorHandler) };
+  }
+  if (typeof document.nodes === "object" && document.nodes !== null && !Array.isArray(document.nodes)) {
+    const nodes: Record<string, unknown> = {};
+    for (const [id, node] of Object.entries(document.nodes as Record<string, unknown>)) nodes[id] = storedNode(key, id, node);
+    out.nodes = nodes;
+  }
+  return out as unknown as ProcessDocument;
+}
+
+function storedNode(key: string, id: string, node: unknown): unknown {
+  if (typeof node !== "object" || node === null) return node;
+  const { kind, config } = node as { readonly kind?: unknown; readonly config?: unknown };
+  if (typeof config !== "object" || config === null) return node;
+  const fields = config as Record<string, unknown>;
+  if (kind === "serviceTask" && typeof fields.tool === "function") {
+    const name = toolNameOf(fields.tool);
+    if (name === undefined) {
+      throw new TypeError(`defineProcess("${key}"): node "${id}" names ${fields.tool.name || "a class"} as its Tool, but it is neither a class with @Tool nor a Tool made by defineTool.`);
+    }
+    return { ...node, config: { ...fields, tool: name } };
+  }
+  if (kind === "callProcess" && typeof fields.process !== "string" && fields.process !== undefined) {
+    return { ...node, config: { ...fields, process: processKeyOf(key, `node "${id}"`, fields.process) } };
+  }
+  return node;
+}
+
+function processKeyOf(key: string, where: string, value: unknown): unknown {
+  if (typeof value === "string") return value;
+  if (isCodeProcess(value)) return value.key;
+  throw new TypeError(`defineProcess("${key}"): ${where} must name a process by its key or by its defineProcess(...) result.`);
+}

package/core/workflow/definitions_module/code/inspectProcesses.ts

@@ -1,5 +1,6 @@
 import { expandModuleMetadata, type BazisModuleRef } from "../../../di";
 import { describeTool, toolMetadataOf } from "../../../agent";
+import { moduleToolsOf } from "../../../agent/defineTool";
 import { documentReferences, schemaReferenceKinds, validateProcess } from "../../../../library/workflow";
 import { WORKFLOW_CALLER } from "../../internal/WorkflowTools";
 import { WorkflowDefinitionsModule } from "../WorkflowDefinitions.module";
@@ -38,8 +39,8 @@ export function inspectProcesses(root: BazisModuleRef): ProcessInspection {
     const fields = moduleRef as { readonly processes?: unknown; readonly tools?: unknown; readonly references?: unknown };
     if (typeof fields.references === "object" && fields.references !== null) for (const kind of Object.keys(fields.references)) kinds.add(kind);
     if (Array.isArray(fields.tools)) {
-      for (const target of fields.tools) {
-        const metadata = typeof target === "function" ? toolMetadataOf(target as new () => object) : undefined;
+      for (const target of toolsOrNone(fields.tools)) {
+        const metadata = toolMetadataOf(target as new () => object);
         if (metadata?.callers.includes(WORKFLOW_CALLER)) {
           tools.add(metadata.name);
           const input = describeTool({ target: target as new () => object, metadata }).input;
@@ -83,3 +84,12 @@ export function inspectProcesses(root: BazisModuleRef): ProcessInspection {
     tools: [...tools].sort(),
   };
 }
+
+/** The Tools of a module; a wrong list is reported by the start, not by the check. */
+function toolsOrNone(tools: unknown): readonly unknown[] {
+  try {
+    return moduleToolsOf(tools);
+  } catch {
+    return [];
+  }
+}

package/core/workflow/definitions_module/http/Processes.controller.ts

@@ -45,7 +45,7 @@ export class ProcessesController {
       owner: optionalString(request.owner, "owner") ?? null,
       retentionDays: optionalInteger(request.retentionDays, "retentionDays") ?? null,
     }, actor, { request: from });
-    return Created(`${ctx.path}/${process.key}`, withTitleText(process, language, defaultLanguage(ctx)));
+    return Created(withTitleText(process, language, defaultLanguage(ctx)), `${ctx.path}/${process.key}`);
   }
 
   @Get("processes/:key")
@@ -105,7 +105,7 @@ export class ProcessesController {
     const key = param(ctx, "key");
     const { actor, request, language } = await callerOf(ctx, "workflow.processes.publish", await this.objectOf(key));
     const version = await this.definitions.publish(key, actor, { request, language });
-    return Created(`${ctx.path.replace(/\/publish$/, "")}/versions/${version.version}`, version);
+    return Created(version, `${ctx.path.replace(/\/publish$/, "")}/versions/${version.version}`);
   }
 
   @Get("processes/:key/versions")

package/core/workflow/definitions_module/internal/PublishedVersions.ts

@@ -0,0 +1,39 @@
+import type { VersionDetails } from "../services/IWorkflowDefinitions.service";
+
+/** A process with a published version, as a list query reads it: no documents. */
+export interface PublishedHead {
+  readonly id: string;
+  readonly key: string;
+  readonly latestVersion: number;
+}
+
+/**
+ * The latest published versions, kept between calls. Versions are immutable, so
+ * what was read once is read no more: an event or a firing of a schedule costs
+ * one query of the heads, and documents are loaded only for versions published
+ * since. One per application instance; another instance sees a publication with
+ * its next query of the heads.
+ */
+export class PublishedVersions {
+  private readonly byProcess = new Map<string, VersionDetails>();
+
+  /** The latest version of each head; `load` reads the documents this cache does not hold yet. */
+  async resolve(heads: readonly PublishedHead[], load: (missing: readonly PublishedHead[]) => Promise<readonly VersionDetails[]>): Promise<readonly VersionDetails[]> {
+    const current = new Set(heads.map((head) => head.id));
+    for (const id of this.byProcess.keys()) if (!current.has(id)) this.byProcess.delete(id);
+    const missing = heads.filter((head) => this.byProcess.get(head.id)?.version !== head.latestVersion);
+    if (missing.length > 0) {
+      const loaded = new Map((await load(missing)).map((version) => [version.key, version]));
+      for (const head of missing) {
+        const version = loaded.get(head.key);
+        // A version another instance has just replaced is read on the next call.
+        if (version?.version === head.latestVersion) this.byProcess.set(head.id, version);
+        else this.byProcess.delete(head.id);
+      }
+    }
+    return heads.flatMap((head) => {
+      const version = this.byProcess.get(head.id);
+      return version === undefined ? [] : [version];
+    });
+  }
+}

package/core/workflow/definitions_module/model/WfProcess.model.ts

@@ -1,4 +1,4 @@
-import { Column, Entity, Index, UUID } from "../../../orm";
+import { Column, Entity, Index, UUID, Nullable } from "../../../orm";
 import type { LocalizedText } from "../../../../library/workflow";
 
 /**
@@ -12,50 +12,63 @@ export class WfProcess {
   id = "";
 
   @Index({ unique: true })
+  @Nullable()
   @Column({ type: "text" })
   key = "";
 
+  @Nullable()
   @Column({ type: "json" })
   title: LocalizedText = "";
 
   /** Every text of `title`, the default language first: what a list searches and sorts by. */
+  @Nullable()
   @Column({ type: "text" })
   titleText = "";
 
-  @Column({ type: "json", nullable: true })
+  @Nullable()
+  @Column({ type: "json" })
   description: LocalizedText | null = null;
 
   /** A path, `Sales/Orders`: there is no folder entity. */
   @Index()
-  @Column({ type: "text", nullable: true })
+  @Nullable()
+  @Column({ type: "text" })
   folder: string | null = null;
 
   /** Whose process it is: an opaque id of the application. */
-  @Column({ type: "text", nullable: true })
+  @Nullable()
+  @Column({ type: "text" })
   owner: string | null = null;
 
   /** The draft document; kept with validation errors too. */
-  @Column({ type: "json", nullable: true })
+  @Nullable()
+  @Column({ type: "json" })
   draft: unknown = null;
 
-  @Column({ type: "datetime", nullable: true })
+  @Nullable()
+  @Column({ type: "datetime" })
   draftUpdatedAt: Date | null = null;
 
-  @Column({ type: "text", nullable: true })
+  @Nullable()
+  @Column({ type: "text" })
   draftUpdatedByKind: string | null = null;
 
-  @Column({ type: "text", nullable: true })
+  @Nullable()
+  @Column({ type: "text" })
   draftUpdatedById: string | null = null;
 
-  @Column({ type: "integer", nullable: true })
+  @Nullable()
+  @Column({ type: "integer" })
   latestVersion: number | null = null;
 
   /** Days to keep completed and cancelled instances; `null` keeps them. */
-  @Column({ type: "integer", nullable: true })
+  @Nullable()
+  @Column({ type: "integer" })
   retentionDays: number | null = null;
 
   /** An archived process is not started. */
-  @Column({ type: "datetime", nullable: true })
+  @Nullable()
+  @Column({ type: "datetime" })
   archivedAt: Date | null = null;
 
   @Column({ type: "createdAt" })

package/core/workflow/definitions_module/model/WfVersion.model.ts

@@ -1,4 +1,4 @@
-import { Column, Entity, ForeignKey, Index, UUID } from "../../../orm";
+import { Column, Entity, ForeignKey, Index, UUID, Nullable } from "../../../orm";
 import { WfProcess } from "./WfProcess.model";
 
 /** A published version of a process: an immutable snapshot of its document. */
@@ -10,25 +10,31 @@ export class WfVersion {
   id = "";
 
   /** A reference: the foreign key makes the column a native uuid. A non-key `type: "uuid"` would generate a value. */
+  @Nullable()
   @Column({ type: "text" })
   processId = "";
 
+  @Nullable()
   @Column({ type: "integer" })
   version = 0;
 
+  @Nullable()
   @Column({ type: "json" })
   document: unknown = null;
 
   /** sha-256 of the document: publishing the same document again adds no version. */
+  @Nullable()
   @Column({ type: "text" })
   documentHash = "";
 
   @Column({ type: "createdAt" })
   publishedAt = new Date(0);
 
+  @Nullable()
   @Column({ type: "text" })
   publishedByKind = "";
 
+  @Nullable()
   @Column({ type: "text" })
   publishedById = "";
 }

package/core/workflow/definitions_module/services/IWorkflowDefinitions.service.ts

@@ -146,7 +146,10 @@ export abstract class IWorkflowDefinitions {
   abstract version(key: string, version: number): Promise<VersionDetails>;
   /** The latest published version of a process that is not archived. */
   abstract latest(key: string): Promise<VersionDetails>;
-  /** The latest version of every process that is not archived: where event and scheduled starts come from. */
+  /**
+   * The latest version of every process that is not archived: where event and scheduled
+   * starts come from. Documents are kept between calls and must not be changed.
+   */
   abstract published(): Promise<readonly VersionDetails[]>;
   /** A version by id, for the engine; `undefined` if there is none. */
   abstract versionById(id: string): Promise<VersionDetails | undefined>;