bazis 0.136.0 → 0.137.0

package/core/tools/generated/deps.ts

@@ -1,7 +1,7 @@
 // This file is auto-generated by `bun run di:generate` (framework.packs of bazis.config.json).
 // Do not edit manually.
 import { registerFrameworkClassDeps } from "../../di/module/autoDeps";
-import { ServiceProvider } from "../../di/ServiceProvider";
+import { ToolRunner } from "../../agent/ToolRunner";
 import { Configuration } from "../../kernel/config/Configuration";
 import { HttpRequestTool } from "../http/HttpRequest.tool";
 import { OrmEntityReferences, OrmFieldReferences } from "../orm/OrmEntity.references";
@@ -10,6 +10,6 @@ import { ConfigSecretStore } from "../secrets/SecretStore";
 registerFrameworkClassDeps([
   [ConfigSecretStore, [Configuration]],
   [HttpRequestTool, ["Config:tools"]],
-  [OrmEntityReferences, [ServiceProvider]],
-  [OrmFieldReferences, [ServiceProvider]],
+  [OrmEntityReferences, [ToolRunner]],
+  [OrmFieldReferences, [ToolRunner]],
 ]);

package/core/tools/http/HttpRequest.tool.ts

@@ -82,8 +82,7 @@ export class HttpRequestTool {
   constructor(private readonly config: ConfigView<ToolsSettings>) {}
 
   async execute(raw: unknown, context: AgentToolExecutionContext): Promise<unknown> {
-    const callers = this.config.get("http.callers").split(",").map((item) => item.trim());
-    if (context.caller !== undefined && !callers.includes(context.caller)) throw new ToolError(`tools.http.callers does not list ${context.caller}`, { reason: "caller_not_allowed" });
+    if (context.caller !== undefined && !this.config.get("http.callers").includes(context.caller)) throw new ToolError(`tools.http.callers does not list ${context.caller}`, { reason: "caller_not_allowed" });
     const request = this.requestOf(raw);
     if (context.dryRun === true && !SAFE_METHODS.has(request.method)) return { dryRun: true };
     const signal = AbortSignal.any([context.signal, AbortSignal.timeout(request.timeoutMs)]);

package/core/tools/http/publicAddress.ts

@@ -82,9 +82,9 @@ export function isPublicAddress(address: string): boolean {
 }
 
 /** Whether `tools.http.allow` lets this host and port through: `api.example.com`, `*.example.com`, `localhost:8080`. */
-export function hostAllowed(allow: string, hostname: string, port: string): boolean {
+export function hostAllowed(allow: readonly string[], hostname: string, port: string): boolean {
   const host = hostname.toLowerCase().replace(/\.$/, "");
-  return allow.split(",").map((item) => item.trim().toLowerCase()).filter((item) => item !== "").some((item) => {
+  return allow.map((item) => item.toLowerCase()).some((item) => {
     // An IPv6 address goes in brackets, as in a URL: [::1]:8080.
     const match = /^\[(.+)\](?::(\d+))?$/.exec(item) ?? /^(.*?)(?::(\d+))?$/.exec(item)!;
     const [name, wanted] = [match[1]!, match[2]];

package/core/tools/orm/OrmEntity.references.ts

@@ -1,13 +1,12 @@
 import type { ReferenceContext, ReferenceItem, ReferencePage } from "../../access";
 import { References } from "../../access";
-import { AgentRegistry } from "../../agent/AgentRegistry";
-import type { ServiceProvider } from "../../di";
+import type { ToolRunner } from "../../agent";
 import { ormEntityToolInfo, type OrmEntityToolInfo } from "./ormEntityTools";
 
 /** What `ormEntityTools` opened in this application: only that is referenced. */
-function opened(services: ServiceProvider): readonly OrmEntityToolInfo[] {
+function opened(tools: ToolRunner): readonly OrmEntityToolInfo[] {
   const entities = new Map<string, Set<string>>();
-  for (const tool of AgentRegistry.fromContainer(services).listTools()) {
+  for (const tool of tools.listTools()) {
     const info = ormEntityToolInfo(tool.target);
     if (info === undefined) continue;
     const fields = entities.get(info.entity) ?? new Set<string>();
@@ -24,12 +23,12 @@ function page(ids: readonly string[], text: string, { limit, offset }: Reference
 
 /** Reference kind `orm.entity`: an entity open to processes, `Order`. */
 export class OrmEntityReferences extends References {
-  constructor(private readonly services: ServiceProvider) {
+  constructor(private readonly tools: ToolRunner) {
     super();
   }
 
   private ids(): readonly string[] {
-    return opened(this.services).map((item) => item.entity);
+    return opened(this.tools).map((item) => item.entity);
   }
 
   async exists(ids: readonly string[]): Promise<ReadonlySet<string>> {
@@ -48,12 +47,12 @@ export class OrmEntityReferences extends References {
 
 /** Reference kind `orm.field`: a field open to processes, `Order.status`, or `status` within `Order`. */
 export class OrmFieldReferences extends References {
-  constructor(private readonly services: ServiceProvider) {
+  constructor(private readonly tools: ToolRunner) {
     super();
   }
 
   private ids(): readonly string[] {
-    return opened(this.services).flatMap((item) => item.fields.map((field) => `${item.entity}.${field}`));
+    return opened(this.tools).flatMap((item) => item.fields.map((field) => `${item.entity}.${field}`));
   }
 
   async exists(ids: readonly string[], context: ReferenceContext): Promise<ReadonlySet<string>> {

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

@@ -17,6 +17,7 @@ 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 +40,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,8 +48,6 @@ import { WorkflowDefinitions } from "./services/WorkflowDefinitions.service";
     scoped(WorkflowReferences),
     scoped(CatalogImport),
     scoped(IWorkflowDefinitions, WorkflowDefinitions),
-    scoped(ProcessReferences),
-    scoped(FolderReferences),
     scoped(ProcessFolderLookup),
     scoped(ProcessPartitionLookup),
     singleton(HOSTED_SERVICE, CodeProcessPublisher),

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>;

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

@@ -19,6 +19,7 @@ import type { CodeProcessCatalog } from "../code/CodeProcessCatalog";
 import type { OwnedCodeProcess } from "../code/codeProcesses";
 import { WORKFLOW_PROCESS_CHANGED, type ProcessChange } from "../events/Definitions.events";
 import type { DefinitionsDbContext } from "../model/Definitions.dbContext";
+import type { PublishedVersions } from "../internal/PublishedVersions";
 import { WfProcess } from "../model/WfProcess.model";
 import { WfVersion } from "../model/WfVersion.model";
 import {
@@ -52,6 +53,7 @@ export class WorkflowDefinitions extends IWorkflowDefinitions {
     private readonly events: WorkflowEvents,
     private readonly languages: WorkflowLanguages,
     private readonly references: WorkflowReferences,
+    private readonly publishedVersions: PublishedVersions,
     /** The scope: the port is asked here, so that the application's own registration replaces the default. */
     private readonly services: ServiceProvider,
   ) {
@@ -351,13 +353,21 @@ export class WorkflowDefinitions extends IWorkflowDefinitions {
   }
 
   async published(): Promise<readonly VersionDetails[]> {
-    const processes = await this.db.processes.asNoTracking().where((p) => p.archivedAt.isNull().and(p.latestVersion.isNotNull())).toList();
-    if (processes.length === 0) return [];
-    const byId = new Map(processes.map((process) => [process.id, process]));
-    const versions = await this.db.versions.asNoTracking().where((v) => v.processId.in([...byId.keys()])).toList();
-    return versions
-      .filter((version) => byId.get(version.processId)?.latestVersion === version.version)
-      .map((version) => versionOf(byId.get(version.processId)!.key, version));
+    // Without the drafts and documents: this runs on every event and every firing of a schedule.
+    const rows = await this.db.processes.asNoTracking()
+      .where((p) => p.archivedAt.isNull().and(p.latestVersion.isNotNull()))
+      .select((p) => ({ id: p.id, key: p.key, latestVersion: p.latestVersion }))
+      .toList();
+    const heads = rows.map((row) => ({ id: row.id, key: row.key, latestVersion: row.latestVersion! }));
+    return await this.publishedVersions.resolve(heads, async (missing) => {
+      const versions = await this.db.versions.asNoTracking()
+        .where((v) => v.processId.in(missing.map((head) => head.id)).and(v.version.in([...new Set(missing.map((head) => head.latestVersion))])))
+        .toList();
+      const byId = new Map(missing.map((head) => [head.id, head]));
+      return versions
+        .filter((version) => byId.get(version.processId)?.latestVersion === version.version)
+        .map((version) => versionOf(byId.get(version.processId)!.key, version));
+    });
   }
 
   async versionById(id: string): Promise<VersionDetails | undefined> {

package/core/workflow/generated/deps.ts

@@ -14,6 +14,7 @@ import { CatalogImport } from "../definitions_module/code/CatalogImport";
 import { CodeProcessCatalog } from "../definitions_module/code/CodeProcessCatalog";
 import { CodeProcessPublisher } from "../definitions_module/code/CodeProcessPublisher";
 import { ProcessesController } from "../definitions_module/http/Processes.controller";
+import { PublishedVersions } from "../definitions_module/internal/PublishedVersions";
 import { DefinitionsDbContext } from "../definitions_module/model/Definitions.dbContext";
 import { IWorkflowDefinitions } from "../definitions_module/services/IWorkflowDefinitions.service";
 import { WorkflowDefinitions } from "../definitions_module/services/WorkflowDefinitions.service";
@@ -66,7 +67,7 @@ registerFrameworkClassDeps([
   [TasksDbContext, [DbContextOptions]],
   [TimerStep, [RuntimeDbContext, WorkflowEngine]],
   [ToolStep, [RuntimeDbContext, WorkflowEngine, WorkflowTools, WorkflowReferences, WorkflowLanguages, ServiceProvider]],
-  [WorkflowDefinitions, [DefinitionsDbContext, WorkflowTools, CodeProcessCatalog, WorkflowClock, WorkflowEvents, WorkflowLanguages, WorkflowReferences, ServiceProvider]],
+  [WorkflowDefinitions, [DefinitionsDbContext, WorkflowTools, CodeProcessCatalog, WorkflowClock, WorkflowEvents, WorkflowLanguages, WorkflowReferences, PublishedVersions, ServiceProvider]],
   [WorkflowEngine, [RuntimeDbContext, IWorkflowDefinitions, GraphCache, WorkflowEvents, WorkflowClock]],
   [WorkflowEvents, [EventBus, ServiceProvider, "optional:Logger"]],
   [WorkflowLanguages, ["Config:workflow"]],

package/core/workflow/index.ts

@@ -3,7 +3,11 @@
  * with the Definitions and Runtime parts, their services, HTTP, events and
  * extension points. The document format is `bazis/library/workflow`.
  */
+import type { PermissionsOf } from "../access";
+import type { definitionsPermissions } from "./definitions_module/access/Definitions.permissions";
 import type { CodeProcess } from "./definitions_module/code/defineProcess";
+import type { runtimePermissions } from "./runtime_module/access/Runtime.permissions";
+import type { tasksPermissions } from "./tasks_module/access/Tasks.permissions";
 import "./generated/deps";
 
 export { WorkflowModule } from "./Workflow.module";
@@ -73,6 +77,11 @@ export { WorkflowPartitions, DefaultWorkflowPartitions, type ProcessPartition }
 export { WorkflowError, type WorkflowErrorCode } from "./contracts/WorkflowError";
 export type { WorkflowActor, WorkflowAuditOptions, WorkflowPage, WorkflowPaging, WorkflowRequest, WorkflowToolMetadata } from "./contracts/types";
 
+// The pack's own permissions: an application that imports the pack may name them in `can` and `defineRoles`.
+declare module "../access/index" {
+  interface BazisPermissions extends PermissionsOf<typeof definitionsPermissions>, PermissionsOf<typeof runtimePermissions>, PermissionsOf<typeof tasksPermissions> {}
+}
+
 // Augment the declaring file, not the "../di" re-export: re-export targets
 // depend on program file order and silently stop merging in some projects.
 declare module "../di/module/types/BazisModule" {

package/core/workflow/internal/WorkflowLanguages.ts

@@ -16,7 +16,7 @@ export class WorkflowLanguages {
   /** The best language of an `Accept-Language` header: by weight, then by order; `ru-RU` also finds `ru`. */
   of(header: string | undefined): string {
     if (header === undefined) return this.default;
-    const known = new Set([this.default, ...this.config.get("languages").split(",").map((item) => item.trim())]);
+    const known = new Set([this.default, ...this.config.get("languages")]);
     const wanted = header.split(",")
       .map((part, index) => {
         const [tag = "", ...parameters] = part.trim().split(";");

package/core/workflow/internal/http.ts

@@ -1,4 +1,4 @@
-import { IAccess, type AccessObject, type SubjectAccess } from "../../access";
+import { IAccess, type AccessObject, type SubjectAccess, type PermissionKey } from "../../access";
 import { ForbiddenError, type HttpContext } from "../../http";
 import { frameworkBadRequest } from "../../http/Errors/HttpError";
 import { ListQueryError, parseListQuery, type ListQuery, type ListQueryOptions, type ListQueryProblem } from "../../../library/jsonapi";
@@ -32,7 +32,7 @@ export function defaultLanguage(ctx: HttpContext): string {
  * right. The actor's id is the first owner id, so that `{ own: true }` means
  * the instances the subject started.
  */
-export async function callerOf(ctx: HttpContext, permission?: string, object?: AccessObject): Promise<WorkflowCaller> {
+export async function callerOf(ctx: HttpContext, permission?: PermissionKey, object?: AccessObject): Promise<WorkflowCaller> {
   const access = await ctx.services.resolve(IAccess).for(ctx);
   if (permission !== undefined && !await access.can(permission, object)) throw new ForbiddenError();
   const sub = access.subject.sub;

package/core/workflow/runtime_module/background/WorkflowWorker.ts

@@ -38,8 +38,12 @@ export class WorkflowWorker extends BackgroundService {
       try {
         const jobs = await this.jobs.claim(batchSize);
         claimed = jobs.length;
-        for (const job of jobs) {
-          if (signal.aborted) return;
+        for (const [index, job] of jobs.entries()) {
+          if (signal.aborted) {
+            // What was claimed and will not run is free for another worker at once, not in a lease.
+            await this.jobs.release(jobs.slice(index));
+            return;
+          }
           await this.jobs.run(job, signal);
         }
       } catch (error) {

package/core/workflow/runtime_module/http/Instances.controller.ts

@@ -32,7 +32,7 @@ export class InstancesController {
       language,
       ...(request.test === true ? { test: true } : {}),
     });
-    return Created(`${ctx.path}/${instance.id}`, instance);
+    return Created(instance, `${ctx.path}/${instance.id}`);
   }
 
   /** A start per element, for an action over many records (WORKFLOW-002 §5.1). */

package/core/workflow/runtime_module/internal/WorkflowJobs.ts

@@ -26,7 +26,10 @@ export class WorkflowJobs {
     private readonly report: JobFailureReport,
   ) {}
 
-  /** Takes up to `batchSize` due jobs with `FOR UPDATE SKIP LOCKED` and a lease, so instances never take one job twice. */
+  /**
+   * Takes up to `batchSize` due jobs with `FOR UPDATE SKIP LOCKED` and a lease, so
+   * instances never take one job twice. {@link run} renews the lease of each as it starts.
+   */
   async claim(batchSize: number): Promise<WfJob[]> {
     const scope = this.services.createScope();
     try {
@@ -51,7 +54,46 @@ export class WorkflowJobs {
     }
   }
 
+  /**
+   * The lease of a claimed job starts when the job does: a batch runs one job after
+   * another, and a job that waited for the ones before it longer than a lease may
+   * have been taken by another worker. `false` then: the job is not this worker's.
+   */
+  private async begin(job: WfJob): Promise<boolean> {
+    const scope = this.services.createScope();
+    try {
+      const db = scope.resolve(RuntimeDbContext);
+      const lockedUntil = new Date(scope.resolve(WorkflowClock).now().getTime() + LEASE_MS);
+      const held = job.lockedUntil;
+      const { affectedRows } = await db.jobs.asNoTracking()
+        .where((j) => j.id.eq(job.id).and(held === null ? j.lockedUntil.isNull() : j.lockedUntil.eq(held)))
+        .executeUpdate({ lockedUntil });
+      if (affectedRows === 0) return false;
+      job.lockedUntil = lockedUntil;
+      return true;
+    } finally {
+      await scope.dispose();
+    }
+  }
+
+  /** Gives back claimed jobs that will not run, a stopping worker's: they are free at once, and the claim does not count as an attempt. */
+  async release(jobs: readonly WfJob[]): Promise<void> {
+    if (jobs.length === 0) return;
+    const scope = this.services.createScope();
+    try {
+      const db = scope.resolve(RuntimeDbContext);
+      for (const job of jobs) {
+        const held = job.lockedUntil;
+        if (held === null) continue;
+        await db.jobs.asNoTracking().where((j) => j.id.eq(job.id).and(j.lockedUntil.eq(held))).executeUpdate({ lockedUntil: null, attempts: Math.max(job.attempts - 1, 0) });
+      }
+    } finally {
+      await scope.dispose();
+    }
+  }
+
   async run(job: WfJob, signal: AbortSignal): Promise<void> {
+    if (!await this.begin(job).catch((error: unknown) => { this.report("job could not begin", error, { job: job.id }); return false; })) return;
     const scope = this.services.createScope();
     try {
       switch (job.kind) {

package/core/workflow/runtime_module/model/WfHistory.model.ts

@@ -1,4 +1,4 @@
-import { Column, Entity, ForeignKey, Index, UUID } from "../../../orm";
+import { Column, Entity, ForeignKey, Index, UUID, Nullable } from "../../../orm";
 import { WfInstance } from "./WfInstance.model";
 
 export type HistoryType = "started" | "queued" | "released" | "entered" | "left" | "tool" | "assigned" | "iteration" | "called" | "returned" | "skipped" | "timer" | "event" | "error" | "retried" | "cancelled" | "timedOut" | "handler" | "completed";
@@ -11,26 +11,33 @@ export class WfHistory {
   @UUID({ version: "v7" })
   id = "";
 
+  @Nullable()
   @Column({ type: "text" })
   instanceId = "";
 
-  @Column({ type: "text", nullable: true })
+  @Nullable()
+  @Column({ type: "text" })
   tokenId: string | null = null;
 
-  @Column({ type: "text", nullable: true })
+  @Nullable()
+  @Column({ type: "text" })
   nodeId: string | null = null;
 
+  @Nullable()
   @Column({ type: "text" })
   type: HistoryType = "entered";
 
-  @Column({ type: "json", nullable: true })
+  @Nullable()
+  @Column({ type: "json" })
   data: Record<string, unknown> | null = null;
 
   /** Who did it: cancel, retry, task completion; `null` for engine steps. */
-  @Column({ type: "text", nullable: true })
+  @Nullable()
+  @Column({ type: "text" })
   actorKind: string | null = null;
 
-  @Column({ type: "text", nullable: true })
+  @Nullable()
+  @Column({ type: "text" })
   actorId: string | null = null;
 
   @Column({ type: "createdAt" })