bazis 0.134.0 → 0.135.0

package/core/access/contracts/References.ts

@@ -25,6 +25,8 @@ export interface ReferenceItem {
 export interface ReferenceContext {
   readonly scope: Scope;
   readonly language?: string;
+  /** The area the ids are looked for in: the fields of one table. A kind without areas ignores it. */
+  readonly within?: string;
 }
 
 export interface ReferencePage {

package/core/infra/connectors/codex/CodexAppServerClient.ts

@@ -232,7 +232,7 @@ export class CodexAppServerClient implements CodexClient {
         if (method === "account/updated") this.modelCache = undefined;
       }, () => { this.clearLogin(); this.modelCache = undefined; });
       const initialized = await client.request("initialize", {
-        clientInfo: { name: "bazis", title: "Bazis", version: "0.134.0" }, capabilities: { experimentalApi: true },
+        clientInfo: { name: "bazis", title: "Bazis", version: "0.135.0" }, capabilities: { experimentalApi: true },
       }, 15_000, signal);
       if (resolve(text(initialized.codexHome, 4096)) !== this.paths.home) throw new CodexError("PROTOCOL_ERROR");
       client.notify("initialized");

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

@@ -46,7 +46,7 @@ export class OrmEntityReferences extends References {
   }
 }
 
-/** Reference kind `orm.field`: a field open to processes, `Order.status`. */
+/** 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) {
     super();
@@ -56,16 +56,20 @@ export class OrmFieldReferences extends References {
     return opened(this.services).flatMap((item) => item.fields.map((field) => `${item.entity}.${field}`));
   }
 
-  async exists(ids: readonly string[]): Promise<ReadonlySet<string>> {
+  async exists(ids: readonly string[], context: ReferenceContext): Promise<ReadonlySet<string>> {
     const known = new Set(this.ids());
-    return new Set(ids.filter((id) => known.has(id)));
+    const { within } = context;
+    return new Set(ids.filter((id) => known.has(within === undefined ? id : `${within}.${id}`)));
   }
 
-  async describe(ids: readonly string[]): Promise<readonly ReferenceItem[]> {
-    return [...await this.exists(ids)].map((id) => ({ id, title: id }));
+  async describe(ids: readonly string[], context: ReferenceContext): Promise<readonly ReferenceItem[]> {
+    return [...await this.exists(ids, context)].map((id) => ({ id, title: id }));
   }
 
-  async search(text: string, _context: ReferenceContext, range: ReferencePage): Promise<readonly ReferenceItem[]> {
-    return page(this.ids(), text, range);
+  async search(text: string, context: ReferenceContext, range: ReferencePage): Promise<readonly ReferenceItem[]> {
+    const { within } = context;
+    if (within === undefined) return page(this.ids(), text, range);
+    const prefix = `${within}.`;
+    return page(this.ids().filter((id) => id.startsWith(prefix)).map((id) => id.slice(prefix.length)), text, range);
   }
 }

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

@@ -6,6 +6,7 @@ import { DefaultWorkflowExtensions, WorkflowExtensions } from "../contracts/Work
 import { DefaultWorkflowPartitions, WorkflowPartitions } from "../contracts/WorkflowPartitions";
 import { WorkflowEvents } from "../internal/WorkflowEvents";
 import { WorkflowLanguages } from "../internal/WorkflowLanguages";
+import { WorkflowReferences } from "../internal/WorkflowReferences";
 import { WorkflowTools } from "../internal/WorkflowTools";
 import { definitionsPermissions } from "./access/Definitions.permissions";
 import { FolderReferences } from "./access/Folder.references";
@@ -42,6 +43,7 @@ import { WorkflowDefinitions } from "./services/WorkflowDefinitions.service";
     singleton(WorkflowExtensions, DefaultWorkflowExtensions),
     singleton(WorkflowPartitions, DefaultWorkflowPartitions),
     scoped(WorkflowEvents),
+    scoped(WorkflowReferences),
     scoped(CatalogImport),
     scoped(IWorkflowDefinitions, WorkflowDefinitions),
     scoped(ProcessReferences),
@@ -51,6 +53,6 @@ import { WorkflowDefinitions } from "./services/WorkflowDefinitions.service";
     singleton(HOSTED_SERVICE, CodeProcessPublisher),
   ],
   controllers: [ProcessesController],
-  exports: [IWorkflowDefinitions, WorkflowTools, WorkflowClock, WorkflowEvents, WorkflowLanguages, WorkflowExtensions, WorkflowPartitions, ProcessFolderLookup],
+  exports: [IWorkflowDefinitions, WorkflowReferences, WorkflowTools, WorkflowClock, WorkflowEvents, WorkflowLanguages, WorkflowExtensions, WorkflowPartitions, ProcessFolderLookup],
 })
 export class WorkflowDefinitionsModule {}

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

@@ -1,6 +1,7 @@
 import { markConfigurationError, type ServiceProvider } from "../../../di";
 import type { HostedService } from "../../../di/extensions/hosted-service";
 import { LOGGER } from "../../../kernel";
+import { WorkflowReferences } from "../../internal/WorkflowReferences";
 import { WorkflowTools } from "../../internal/WorkflowTools";
 import { IWorkflowDefinitions } from "../services/IWorkflowDefinitions.service";
 import { CatalogImport } from "./CatalogImport";
@@ -12,7 +13,9 @@ import { definitionProblems, WorkflowSetupError } from "./codeProcesses";
  * (WORKFLOW-002 §9), then publishes the processes of `@Module({ processes })`
  * (WORKFLOW-001 §14). A document with an unknown Tool or process, or an `extensions`
  * namespace nobody checks, stops the start with every finding of every process; the same
- * document again gives no new version.
+ * document again gives no new version. So does a reference kind no module owns, in a Tool
+ * or a document. A value that does not exist only warns: it may be data that is yet to come,
+ * and the step then fails with `ref_not_found`.
  */
 export class CodeProcessPublisher implements HostedService {
   readonly diagnosticName = "workflow:processes";
@@ -25,6 +28,11 @@ export class CodeProcessPublisher implements HostedService {
     try {
       const imported = await scope.resolve(CatalogImport).run();
       if (imported > 0) logger?.info("workflow catalog brought over from the old store", { processes: imported });
+      const references = scope.resolve(WorkflowReferences);
+      const unowned = references.unownedToolKinds();
+      if (unowned.length > 0) {
+        throw markConfigurationError(new WorkflowSetupError(`Tools refer to kinds no module owns:\n${unowned.map(({ tool, kind }) => `  - ${tool}: ${kind}${kind.startsWith("orm.") ? " (import StandardToolsModule from bazis/core/tools)" : " (declare it in @Module({ references }))"}`).join("\n")}`));
+      }
       const entries = this.services.resolve(CodeProcessCatalog).list();
       if (entries.length === 0) return;
       const tools = this.services.resolve(WorkflowTools);
@@ -35,6 +43,10 @@ export class CodeProcessPublisher implements HostedService {
         const found = [...definitionProblems(process, (name) => tools.has(name))];
         for (const issue of await definitions.validate(process.document, { processes })) {
           if (issue.severity === "error" && (issue.code === "extension_unknown" || issue.code === "extension_invalid" || issue.code === "unknown_process")) found.push(`${issue.message} (${issue.code})`);
+          else if (issue.code === "broken_ref") {
+            if (issue.message.startsWith("no module owns")) found.push(`${issue.message} (${issue.code})`);
+            else logger?.warn("workflow process refers to what does not exist", { process: process.key, node: issue.node, message: issue.message });
+          }
         }
         if (found.length > 0) problems.push(`${module}: process "${process.key}":\n${found.map((line) => `  - ${line}`).join("\n")}`);
       }

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

@@ -1,6 +1,6 @@
 import { expandModuleMetadata, type BazisModuleRef } from "../../../di";
-import { toolMetadataOf } from "../../../agent";
-import { validateProcess } from "../../../../library/workflow";
+import { describeTool, toolMetadataOf } from "../../../agent";
+import { documentReferences, schemaReferenceKinds, validateProcess } from "../../../../library/workflow";
 import { WORKFLOW_CALLER } from "../../internal/WorkflowTools";
 import { WorkflowDefinitionsModule } from "../WorkflowDefinitions.module";
 import { definitionProblems, type OwnedCodeProcess } from "./codeProcesses";
@@ -28,16 +28,23 @@ export function inspectProcesses(root: BazisModuleRef): ProcessInspection {
   const found: OwnedCodeProcess[] = [];
   const errors: string[] = [];
   const tools = new Set<string>();
+  const schemas = new Map<string, unknown>();
+  const kinds = new Set<string>();
   const visited = new Set<BazisModuleRef>();
   const visit = (moduleRef: BazisModuleRef): void => {
     if (visited.has(moduleRef)) return;
     visited.add(moduleRef);
     const module = typeof moduleRef === "function" ? moduleRef.name || "<anonymous module>" : "<module>";
-    const fields = moduleRef as { readonly processes?: unknown; readonly tools?: unknown };
+    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;
-        if (metadata?.callers.includes(WORKFLOW_CALLER)) tools.add(metadata.name);
+        if (metadata?.callers.includes(WORKFLOW_CALLER)) {
+          tools.add(metadata.name);
+          const input = describeTool({ target: target as new () => object, metadata }).input;
+          if (input?.kind === "json-schema") schemas.set(metadata.name, input.schema);
+        }
       }
     }
     if (fields.processes !== undefined) {
@@ -54,6 +61,10 @@ export function inspectProcesses(root: BazisModuleRef): ProcessInspection {
   if (found.length > 0 && !visited.has(WorkflowDefinitionsModule)) {
     errors.push(`${found[0]!.module} declares processes, but the application does not import WorkflowModule (bazis/core/workflow).`);
   }
+  // The values live in the database: `check` knows only whether someone owns their kind.
+  for (const [tool, schema] of schemas) {
+    for (const kind of schemaReferenceKinds(schema)) if (!kinds.has(kind)) errors.push(`Tool ${tool} refers to the kind ${kind}, and no module owns it.`);
+  }
   const owners = new Map<string, string>();
   for (const { process, module } of found) {
     const other = owners.get(process.key);

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

@@ -92,6 +92,24 @@ export interface SavedDraft {
   readonly draftUpdatedAt: Date;
 }
 
+export interface ProcessReferenceQuery {
+  readonly kind: string;
+  readonly id: string;
+  /** The area of the value: the table of a field. Without it any area goes. */
+  readonly within?: string;
+}
+
+/** A process that refers to a value, and where. */
+export interface ProcessReference {
+  readonly processKey: string;
+  readonly version: number;
+  readonly node?: string;
+  readonly variable?: string;
+  readonly within?: string;
+  /** Where in the input of the step: `/values/status`. */
+  readonly path: string;
+}
+
 /**
  * The process catalog: drafts and immutable published versions
  * (WORKFLOW-001 §3). Errors are {@link WorkflowError}: `not_found`, `conflict`,
@@ -132,6 +150,11 @@ export abstract class IWorkflowDefinitions {
   abstract published(): Promise<readonly VersionDetails[]>;
   /** A version by id, for the engine; `undefined` if there is none. */
   abstract versionById(id: string): Promise<VersionDetails | undefined>;
+  /**
+   * Who refers to a value (WORKFLOW-002 §6.3), by the latest published versions: the
+   * application forbids or warns before it removes a field or a table.
+   */
+  abstract referencing(reference: ProcessReferenceQuery): Promise<readonly ProcessReference[]>;
   /** Processes with a retention period: what the retention service deletes. */
   abstract retentionPolicies(): Promise<readonly { readonly key: string; readonly retentionDays: number }[]>;
   /** The Tools a service task may call, with their input and output schemas. */

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

@@ -2,7 +2,7 @@ import { grantsToWhere } from "../../../access";
 import { createHash } from "node:crypto";
 import { paginate, UniqueViolationError } from "../../../orm";
 import type { AgentToolContract } from "../../../agent";
-import { allTexts, checkLocalizedText, emptyProcess, hasErrors, processPalette, validateProcess, type LocalizedText, type ProcessDocument, type ProcessIssue, type ProcessPalette } from "../../../../library/workflow";
+import { allTexts, checkLocalizedText, emptyProcess, hasErrors, processPalette, validateProcess, type DocumentReference, type LocalizedText, type ProcessDocument, type ProcessIssue, type ProcessPalette } from "../../../../library/workflow";
 import type { ServiceProvider } from "../../../di";
 import { isUuid, pageQueryOf, type WorkflowActor, type WorkflowAuditOptions, type WorkflowPage } from "../../contracts/types";
 import type { WorkflowClock } from "../../contracts/WorkflowClock";
@@ -13,6 +13,7 @@ import { WorkflowProcessUsage } from "../../contracts/WorkflowProcessUsage";
 import { canonicalJson } from "../../internal/canonicalJson";
 import type { WorkflowEvents } from "../../internal/WorkflowEvents";
 import type { WorkflowLanguages } from "../../internal/WorkflowLanguages";
+import type { WorkflowReferences } from "../../internal/WorkflowReferences";
 import type { WorkflowTools } from "../../internal/WorkflowTools";
 import type { CodeProcessCatalog } from "../code/CodeProcessCatalog";
 import type { OwnedCodeProcess } from "../code/codeProcesses";
@@ -25,6 +26,8 @@ import {
   type CreateProcess,
   type ProcessDetails,
   type ProcessListQuery,
+  type ProcessReference,
+  type ProcessReferenceQuery,
   type ProcessSummary,
   type SavedDraft,
   type SaveDraftOptions,
@@ -48,6 +51,7 @@ export class WorkflowDefinitions extends IWorkflowDefinitions {
     private readonly clock: WorkflowClock,
     private readonly events: WorkflowEvents,
     private readonly languages: WorkflowLanguages,
+    private readonly references: WorkflowReferences,
     /** The scope: the port is asked here, so that the application's own registration replaces the default. */
     private readonly services: ServiceProvider,
   ) {
@@ -100,7 +104,7 @@ export class WorkflowDefinitions extends IWorkflowDefinitions {
     const published = await this.db.processes.asNoTracking().where((p) => p.archivedAt.isNull().and(p.latestVersion.isNotNull())).select((p) => ({ key: p.key })).toList();
     const processes = new Set([...published.map((row) => row.key), ...options.processes ?? []]);
     const issues = validateProcess(document, { tools: (name) => this.workflowTools.has(name), processes: (key) => processes.has(key), extensions: (namespace) => namespaces.has(namespace) });
-    if (namespaces.size === 0 || issues.some((issue) => issue.code === "too_large" || issue.code === "schema")) return issues;
+    if (issues.some((issue) => issue.code === "too_large" || issue.code === "schema")) return issues;
     const context: WorkflowPortContext = { partition: null, language: options.language ?? this.languages.default, actor: options.actor ?? null };
     const found: ProcessIssue[] = [...issues];
     const { extensions, variables, nodes } = document as ProcessDocument;
@@ -111,9 +115,52 @@ export class WorkflowDefinitions extends IWorkflowDefinitions {
         for (const message of await port.check(namespace, value, target, context)) found.push({ severity: "error", code: "extension_invalid", message: `${namespace}: ${message}`, ...target });
       }
     };
-    await checkAll(extensions, {});
-    if (Array.isArray(variables)) for (const variable of variables) await checkAll(variable?.extensions, { variable: variable?.name });
-    for (const [node, raw] of Object.entries(nodes)) await checkAll(raw?.extensions, { node });
+    if (namespaces.size > 0) {
+      await checkAll(extensions, {});
+      if (Array.isArray(variables)) for (const variable of variables) await checkAll(variable?.extensions, { variable: variable?.name });
+      for (const [node, raw] of Object.entries(nodes)) await checkAll(raw?.extensions, { node });
+    }
+    found.push(...await this.brokenReferences(document as ProcessDocument, context.language));
+    return found;
+  }
+
+  /** The literal references no owner knows. The processes a document calls are told above as `unknown_process`. */
+  private async brokenReferences(document: ProcessDocument, language: string): Promise<ProcessIssue[]> {
+    let references: DocumentReference[];
+    try {
+      references = this.references.of(document);
+    } catch {
+      // A document that is not whole yet: its shape has been told above.
+      return [];
+    }
+    const missing = await this.references.missing(references.filter((reference) => reference.kind !== "workflow.process"), { scope: null, language });
+    return missing.map((reference) => ({
+      severity: "error" as const,
+      code: "broken_ref" as const,
+      message: this.references.owned(reference.kind)
+        ? `${reference.kind} ${JSON.stringify(reference.id)}${reference.within === undefined ? "" : ` in ${reference.within}`} does not exist`
+        : `no module owns the reference kind ${reference.kind}`,
+      ...(reference.node === undefined ? {} : { node: reference.node }),
+      ...(reference.variable === undefined ? {} : { variable: reference.variable }),
+    }));
+  }
+
+  async referencing(reference: ProcessReferenceQuery): Promise<readonly ProcessReference[]> {
+    const found: ProcessReference[] = [];
+    for (const version of await this.published()) {
+      for (const item of this.references.of(version.document)) {
+        if (item.kind !== reference.kind || item.id !== reference.id) continue;
+        if (reference.within !== undefined && item.within !== reference.within) continue;
+        found.push({
+          processKey: version.key,
+          version: version.version,
+          path: item.path,
+          ...(item.node === undefined ? {} : { node: item.node }),
+          ...(item.variable === undefined ? {} : { variable: item.variable }),
+          ...(item.within === undefined ? {} : { within: item.within }),
+        });
+      }
+    }
     return found;
   }
 
@@ -199,12 +246,15 @@ export class WorkflowDefinitions extends IWorkflowDefinitions {
   }
 
   async publish(key: string, actor: WorkflowActor, options: WorkflowAuditOptions & Pick<ValidateOptions, "language"> = {}): Promise<VersionDetails> {
+    // Before the transaction: the owners of references and the ports read their own contexts.
+    const draft = await this.process(key, false);
+    const issues = await this.validate(draft.draft, { actor, processes: [key], ...(options.language === undefined ? {} : { language: options.language }) });
     return await this.db.transactionScope(async (transaction) => {
       const row = await this.db.processes.where((p) => p.key.eq(key)).forUpdate().firstOrDefault();
       if (!row) throw notFound(key);
       this.assertNotCode(key);
       if (row.archivedAt !== null) throw new WorkflowError("archived", `Process ${key} is archived`);
-      const issues = await this.validate(row.draft, { actor, processes: [key], ...(options.language === undefined ? {} : { language: options.language }) });
+      if (canonicalJson(row.draft) !== canonicalJson(draft.draft)) throw new WorkflowError("conflict", `The draft of ${key} was saved while it was being published`);
       if (hasErrors(issues)) throw new WorkflowError("invalid_document", `Process ${key} has errors and cannot be published`, issues);
       const { version, created } = await this.publishDraft(row, actor);
       if (created) transaction.afterCommit(() => this.changed("published", key, actor, options, version.version));

package/core/workflow/generated/deps.ts

@@ -2,6 +2,7 @@
 // Do not edit manually.
 import { registerFrameworkClassDeps } from "../../di/module/autoDeps";
 import { DbContextOptions } from "../../../library/orm/DbContextOptions";
+import { IAccessCatalog } from "../../access/catalog/IAccessCatalog.service";
 import { ServiceProvider } from "../../di/ServiceProvider";
 import { EventBus } from "../../kernel/events/EventBus";
 import { WorkflowClock } from "../contracts/WorkflowClock";
@@ -18,6 +19,7 @@ import { IWorkflowDefinitions } from "../definitions_module/services/IWorkflowDe
 import { WorkflowDefinitions } from "../definitions_module/services/WorkflowDefinitions.service";
 import { WorkflowEvents } from "../internal/WorkflowEvents";
 import { WorkflowLanguages } from "../internal/WorkflowLanguages";
+import { WorkflowReferences } from "../internal/WorkflowReferences";
 import { WorkflowTools } from "../internal/WorkflowTools";
 import { WorkflowRetention } from "../runtime_module/background/WorkflowRetention";
 import { WorkflowWorker } from "../runtime_module/background/WorkflowWorker";
@@ -63,11 +65,12 @@ registerFrameworkClassDeps([
   [TasksController, [IWorkflowTasks]],
   [TasksDbContext, [DbContextOptions]],
   [TimerStep, [RuntimeDbContext, WorkflowEngine]],
-  [ToolStep, [RuntimeDbContext, WorkflowEngine, WorkflowTools]],
-  [WorkflowDefinitions, [DefinitionsDbContext, WorkflowTools, CodeProcessCatalog, WorkflowClock, WorkflowEvents, WorkflowLanguages, ServiceProvider]],
+  [ToolStep, [RuntimeDbContext, WorkflowEngine, WorkflowTools, WorkflowReferences, WorkflowLanguages]],
+  [WorkflowDefinitions, [DefinitionsDbContext, WorkflowTools, CodeProcessCatalog, WorkflowClock, WorkflowEvents, WorkflowLanguages, WorkflowReferences, ServiceProvider]],
   [WorkflowEngine, [RuntimeDbContext, IWorkflowDefinitions, GraphCache, WorkflowEvents, WorkflowClock]],
   [WorkflowEvents, [EventBus, ServiceProvider, "optional:Logger"]],
   [WorkflowLanguages, ["Config:workflow"]],
+  [WorkflowReferences, [IAccessCatalog, WorkflowTools, ServiceProvider]],
   [WorkflowRetention, [ServiceProvider, "Config:workflow"]],
   [WorkflowRuntime, [RuntimeDbContext, WorkflowEngine, EventDelivery, IWorkflowDefinitions, ServiceProvider, WorkflowLanguages]],
   [WorkflowTasks, [TasksDbContext, IWorkflowRuntime, WorkflowClock, WorkflowEvents]],

package/core/workflow/internal/WorkflowReferences.ts

@@ -0,0 +1,69 @@
+import { IAccessCatalog } from "../../access";
+import type { ServiceProvider } from "../../di";
+import { documentReferences, schemaReferenceKinds, type DocumentReference, type InputReference, type ProcessDocument } from "../../../library/workflow";
+import type { WorkflowTools } from "./WorkflowTools";
+
+/** Whose references: the partition of the instance, when there is one. */
+export interface ReferenceCheckContext {
+  readonly scope: string | null;
+  readonly language: string;
+}
+
+/**
+ * Asks the owners of reference kinds (ACCESS-001 §6) about the references of
+ * processes (WORKFLOW-002 §6.3). The owners are resolved in the scope of the call.
+ */
+export class WorkflowReferences {
+  constructor(
+    private readonly catalog: IAccessCatalog,
+    private readonly tools: WorkflowTools,
+    private readonly services: ServiceProvider,
+  ) {}
+
+  /** The input schema of a Tool, in JSON Schema, if the Tool has one. */
+  inputSchemaOf(tool: string): unknown {
+    const input = this.tools.bound?.describe(tool)?.input;
+    return input?.kind === "json-schema" ? input.schema : undefined;
+  }
+
+  /** The literal references of a document. */
+  of(document: ProcessDocument): DocumentReference[] {
+    return documentReferences(document, (tool) => this.inputSchemaOf(tool));
+  }
+
+  /** Reference kinds the Tools name and no module owns: the application is built wrong. */
+  unownedToolKinds(): readonly { readonly tool: string; readonly kind: string }[] {
+    const found: { tool: string; kind: string }[] = [];
+    for (const contract of this.tools.list()) {
+      const schema = contract.input?.kind === "json-schema" ? contract.input.schema : undefined;
+      for (const kind of schemaReferenceKinds(schema)) if (!this.owned(kind)) found.push({ tool: contract.name, kind });
+    }
+    return found;
+  }
+
+  owned(kind: string): boolean {
+    return this.catalog.referenceKind(kind) !== undefined;
+  }
+
+  /** Those of `references` their owners do not know. A kind nobody owns is reported as not found. */
+  async missing<T extends InputReference>(references: readonly T[], context: ReferenceCheckContext): Promise<readonly T[]> {
+    const groups = new Map<string, T[]>();
+    for (const reference of references) {
+      const key = JSON.stringify([reference.kind, reference.within ?? null]);
+      groups.set(key, [...groups.get(key) ?? [], reference]);
+    }
+    const out: T[] = [];
+    for (const group of groups.values()) {
+      const { kind, within } = group[0]!;
+      const owner = this.catalog.referenceKind(kind);
+      if (owner === undefined) {
+        out.push(...group);
+        continue;
+      }
+      const ids = [...new Set(group.map((reference) => reference.id))];
+      const known = await this.services.resolve(owner.type).exists(ids, { scope: context.scope, language: context.language, ...(within === undefined ? {} : { within }) });
+      out.push(...group.filter((reference) => !known.has(reference.id)));
+    }
+    return out;
+  }
+}

package/core/workflow/runtime_module/access/Runtime.permissions.ts

@@ -14,7 +14,7 @@ export const runtimePermissions = definePermissions({
   "workflow.instances.read": {
     title: { en: "See instances", ru: "Видеть экземпляры" },
     scope: { column: "partition" },
-    on: { process, folder },
+    on: { process, folder, test: { type: "boolean" } },
     owner: "startedById",
   },
   "workflow.instances.manage": {

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

@@ -4,7 +4,9 @@ import { EventBus, type ConfigView } from "../../../kernel";
 import { WorkflowClock } from "../../contracts/WorkflowClock";
 import { IWorkflowDefinitions } from "../../definitions_module/services/IWorkflowDefinitions.service";
 import { WORKFLOW_INSTANCES_DELETED } from "../events/Runtime.events";
+import type { EntityQuery } from "../../../orm";
 import { RuntimeDbContext } from "../model/Runtime.dbContext";
+import type { WfInstance } from "../model/WfInstance.model";
 import type { WorkflowSettings } from "../../contracts/Workflow.config";
 
 const DAY_MS = 86_400_000;
@@ -13,6 +15,7 @@ const DAY_MS = 86_400_000;
  * Deletes `completed`, `cancelled` and `timedOut` instances older than their process's
  * `retentionDays`, with tokens, jobs, subscriptions and history (by cascade),
  * `retention.batchSize` at a time. `failed` instances wait for a person and stay.
+ * Trial runs are gone after a day, whatever their status and process.
  * Each deleted batch is published as `WORKFLOW_INSTANCES_DELETED`, so parts
  * with their own data (tasks) drop theirs.
  */
@@ -47,22 +50,23 @@ export class WorkflowRetention extends BackgroundService {
       const definitions = scope.resolve(IWorkflowDefinitions);
       const db = scope.resolve(RuntimeDbContext);
       const now = scope.resolve(WorkflowClock).now().getTime();
-      for (const policy of await definitions.retentionPolicies()) {
-        const cutoff = new Date(now - policy.retentionDays * DAY_MS);
+      const drop = async (select: () => EntityQuery<WfInstance>): Promise<boolean> => {
         for (;;) {
-          if (signal?.aborted) return deleted;
-          const ids = (await db.instances.asNoTracking()
-            .where((i) => i.processKey.eq(policy.key).and(i.status.in(["completed", "cancelled", "timedOut"])).and(i.endedAt.lt(cutoff)))
-            .orderBy((i) => i.id)
-            .take(batchSize)
-            .select((i) => ({ id: i.id }))
-            .toList()).map((row) => row.id);
-          if (ids.length === 0) break;
+          if (signal?.aborted) return false;
+          const ids = (await select().orderBy((i) => i.id).take(batchSize).select((i) => ({ id: i.id })).toList()).map((row) => row.id);
+          if (ids.length === 0) return true;
           await db.instances.asNoTracking().where((i) => i.id.in(ids)).executeDelete();
           deleted += ids.length;
           await scope.resolve(EventBus).publishScoped(scope, WORKFLOW_INSTANCES_DELETED, { instanceIds: ids });
-          if (ids.length < batchSize) break;
+          if (ids.length < batchSize) return true;
         }
+      };
+      const dayAgo = new Date(now - DAY_MS);
+      if (!await drop(() => db.instances.asNoTracking().where((i) => i.test.eq(true).and(i.createdAt.lt(dayAgo))))) return deleted;
+      for (const policy of await definitions.retentionPolicies()) {
+        const cutoff = new Date(now - policy.retentionDays * DAY_MS);
+        const kept = await drop(() => db.instances.asNoTracking().where((i) => i.processKey.eq(policy.key).and(i.status.in(["completed", "cancelled", "timedOut"])).and(i.endedAt.lt(cutoff))));
+        if (!kept) return deleted;
       }
     } finally {
       await scope.dispose();

package/core/workflow/runtime_module/events/Runtime.events.ts

@@ -68,3 +68,10 @@ export const WORKFLOW_INSTANCES_DELETED = createEventToken<WorkflowInstancesDele
 export const WORKFLOW_INSTANCE_STARTED = createEventToken<WorkflowInstanceStarted>("workflow.instance-started");
 export const WORKFLOW_INSTANCE_CANCELLED = createEventToken<WorkflowInstanceCancelled>("workflow.instance-cancelled");
 export const WORKFLOW_INSTANCE_RETRIED = createEventToken<WorkflowInstanceRetried>("workflow.instance-retried");
+
+/**
+ * Only for the part with the tasks: a trial run publishes nothing to the
+ * application, but its tasks still come and go (WORKFLOW-002 §5.4).
+ */
+export const WORKFLOW_TRIAL_TASK_REQUESTED = createEventToken<WorkflowTaskRequested>("workflow.trial-task-requested");
+export const WORKFLOW_TRIAL_TOKEN_CLOSED = createEventToken<WorkflowTokenClosed>("workflow.trial-token-closed");

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

@@ -2,6 +2,7 @@ import { contextOnlyController } from "../../../http/Routing/contextOnlyControll
 import { can, type AccessObject } from "../../../access";
 import { Authorize, Controller, Created, Get, Post, type HttpContext } from "../../../http";
 import { buildListDocument } from "../../../../library/jsonapi";
+import { WorkflowError } from "../../contracts/WorkflowError";
 import { body, callerOf, filterOf, listQuery, optionalString, pagingOfList, param, requiredString } from "../../internal/http";
 import type { InstanceStatus } from "../model/WfInstance.model";
 import { IWorkflowDefinitions } from "../../definitions_module/services/IWorkflowDefinitions.service";
@@ -29,6 +30,7 @@ export class InstancesController {
       actor,
       request: from,
       language,
+      ...(request.test === true ? { test: true } : {}),
     });
     return Created(`${ctx.path}/${instance.id}`, instance);
   }
@@ -49,9 +51,11 @@ export class InstancesController {
   async list(ctx: HttpContext) {
     const { access } = await callerOf(ctx);
     const list = listQuery(ctx, {
-      filter: { partition: ["eq"], processKey: ["eq"], status: ["eq"], businessKey: ["eq"], startedById: ["eq"], parentInstanceId: ["eq"] },
+      filter: { partition: ["eq"], processKey: ["eq"], status: ["eq"], businessKey: ["eq"], startedById: ["eq"], parentInstanceId: ["eq"], test: ["eq"] },
       sort: ["createdAt", "endedAt", "status", "processKey"],
     });
+    const test = filterOf(list, "test");
+    if (test !== undefined && test !== "true" && test !== "false") throw new WorkflowError("invalid_input", "test must be true or false");
     const page = await this.runtime.instances({
       ...pagingOfList(list),
       access: await access.filter("workflow.instances.read"),
@@ -61,6 +65,7 @@ export class InstancesController {
       businessKey: filterOf(list, "businessKey"),
       startedById: filterOf(list, "startedById"),
       parentInstanceId: filterOf(list, "parentInstanceId"),
+      ...(test === undefined ? {} : { test: test === "true" }),
     });
     return buildListDocument(page.items, list, page.total, { basePath: ctx.path });
   }
@@ -100,7 +105,7 @@ export class InstancesController {
 
   /** The instance as the object of a permission. */
   private async objectOf(instance: InstanceSummary): Promise<AccessObject> {
-    return { scope: instance.partition, process: instance.processKey, folder: await this.definitions.folderOf(instance.processKey), startedById: instance.startedBy.id };
+    return { scope: instance.partition, process: instance.processKey, folder: await this.definitions.folderOf(instance.processKey), startedById: instance.startedBy.id, test: instance.test };
   }
 }
 contextOnlyController(InstancesController);

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

@@ -108,6 +108,7 @@ export class ChildCalls {
       const current = step.tokens.find((t) => t.id === token.id);
       if (current?.status !== "waiting" || step.instance.status !== "running") return;
       const { id } = await this.engine.begin(childGraph, start[0], {
+        test: instance.test,
         input: value,
         partition: step.instance.partition,
         businessKey: null,

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

@@ -39,7 +39,7 @@ export class RunLimits {
   }
 
   private async releaseProcess(processKey: string): Promise<void> {
-    const waiting = await this.db.instances.asNoTracking().where((i) => i.processKey.eq(processKey).and(i.status.eq("pending"))).orderBy((i) => i.id).take(RELEASE_BATCH).toList();
+    const waiting = await this.db.instances.asNoTracking().where((i) => i.processKey.eq(processKey).and(i.test.eq(false)).and(i.status.eq("pending"))).orderBy((i) => i.id).take(RELEASE_BATCH).toList();
     if (waiting.length === 0) return;
     // Graphs live in the Definitions store, out of reach inside the transaction; `inStep` finds them cached.
     const graphs = new Map(await Promise.all(waiting.map(async (row) => [row.id, await this.engine.graphOf(row.versionId)] as const)));
@@ -65,7 +65,7 @@ export class RunLimits {
   /** Whether an instance older than this one still works on the key: it goes first. */
   private async keyTaken(processKey: string, businessKey: string, id: string): Promise<boolean> {
     const same = await this.db.instances.asNoTracking()
-      .where((i) => i.processKey.eq(processKey).and(i.businessKey.eq(businessKey)).and(i.status.in(["pending", "running", "failed"])).and(i.id.lt(id)))
+      .where((i) => i.processKey.eq(processKey).and(i.test.eq(false)).and(i.businessKey.eq(businessKey)).and(i.status.in(["pending", "running", "failed"])).and(i.id.lt(id)))
       .count();
     return same > 0;
   }
@@ -73,7 +73,7 @@ export class RunLimits {
   /** Whether a scheduled run of the partition goes on, or waits since before this one. */
   private async scheduleTaken(processKey: string, partition: string | null, id: string): Promise<boolean> {
     const same = await this.db.instances.asNoTracking()
-      .where((i) => i.processKey.eq(processKey).and(i.startedVia.eq("schedule")).and(partition === null ? i.partition.isNull() : i.partition.eq(partition)).and(i.status.eq("running").or(i.status.eq("pending").and(i.id.lt(id)))))
+      .where((i) => i.processKey.eq(processKey).and(i.test.eq(false)).and(i.startedVia.eq("schedule")).and(partition === null ? i.partition.isNull() : i.partition.eq(partition)).and(i.status.eq("running").or(i.status.eq("pending").and(i.id.lt(id)))))
       .count();
     return same > 0;
   }
@@ -113,6 +113,7 @@ export class RunLimits {
     await this.engine.inStep(failed.id, async (step) => {
       await this.dropJob(job);
       const { id } = await this.engine.begin(graph, start[0], {
+        test: failed.test,
         input: value,
         partition: failed.partition,
         businessKey: null,

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

@@ -1,6 +1,8 @@
 import type { AgentSchemaContract, AgentToolResult } from "../../../agent";
-import { durationMs, maskByMapping, maskBySchema, masksPersonal, personalPaths, resolveInput, type ProcessDocument } from "../../../../library/workflow";
+import { durationMs, inputReferences, maskByMapping, maskBySchema, masksPersonal, personalPaths, resolveInput, type ProcessDocument } from "../../../../library/workflow";
 import type { WorkflowToolMetadata } from "../../contracts/types";
+import type { WorkflowLanguages } from "../../internal/WorkflowLanguages";
+import type { WorkflowReferences } from "../../internal/WorkflowReferences";
 import type { WorkflowTools } from "../../internal/WorkflowTools";
 import type { RuntimeDbContext } from "../model/Runtime.dbContext";
 import type { WfJob } from "../model/WfJob.model";
@@ -23,6 +25,8 @@ export class ToolStep {
     private readonly db: RuntimeDbContext,
     private readonly engine: WorkflowEngine,
     private readonly tools: WorkflowTools,
+    private readonly references: WorkflowReferences,
+    private readonly languages: WorkflowLanguages,
   ) {}
 
   async run(job: WfJob, signal: AbortSignal): Promise<void> {
@@ -42,13 +46,22 @@ export class ToolStep {
       await this.db.jobs.asNoTracking().where((j) => j.id.eq(job.id)).executeUpdate({ lockedUntil: new Date(this.engine.now().getTime() + timeoutMs + LEASE_MS) });
     }
     const runner = this.tools.bound;
+    const trial = instance.test ? runner?.getTool(name)?.metadata.dryRun : undefined;
+    const missing = await this.references.missing(inputReferences(this.references.inputSchemaOf(name), input), { scope: instance.partition, language: this.languages.default });
     const result: AgentToolResult = runner === undefined
       ? { callId: token.id, name, status: "error", error: { code: "TOOL_NOT_FOUND", message: `Tool ${name} is not available to processes` }, metadata: {} } as AgentToolResult
+      : missing.length > 0
+      // A value computed by the process, or one that is gone since the publication (WORKFLOW-002 §6.3).
+      ? { callId: token.id, name, status: "error", error: { code: "ref_not_found", message: `${missing[0]!.kind} ${JSON.stringify(missing[0]!.id)} does not exist`, details: { reason: "ref_not_found", path: missing[0]!.path } }, metadata: {} } as AgentToolResult
+      : trial === "unsupported"
+      // A trial never calls a Tool that cannot run without changing anything.
+      ? { callId: token.id, name, status: "success", output: { dryRun: true }, metadata: {} } as AgentToolResult
       : await runner.run(name, input, {
         idempotencyKey: token.id,
         actor: runActorOf(graph.document, instance),
-        metadata: { instanceId: instance.id, processKey: instance.processKey, nodeId: token.nodeId, partition: instance.partition, test: false } satisfies WorkflowToolMetadata,
+        metadata: { instanceId: instance.id, processKey: instance.processKey, nodeId: token.nodeId, partition: instance.partition, test: instance.test } satisfies WorkflowToolMetadata,
         signal,
+        ...(trial === "supported" ? { dryRun: true } : {}),
         ...(timeoutMs === undefined ? {} : { timeoutMs }),
       });
 
@@ -72,6 +85,7 @@ export class ToolStep {
         status: result.status,
         attempt: job.attempts,
         durationMs: result.durationMs ?? null,
+        ...(trial === undefined ? {} : { dryRun: trial === "supported" ? "called" : "not called" }),
         ...payloads,
         ...(result.error ? { error: { code: result.error.code ?? null, message: result.error.message, ...(reason === undefined ? {} : { reason }) } } : {}),
         ...(retryAt === undefined ? {} : { retryAt: retryAt.toISOString() }),

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

@@ -4,7 +4,7 @@ import type { WorkflowActor, WorkflowRequest } from "../../contracts/types";
 import type { WorkflowClock } from "../../contracts/WorkflowClock";
 import type { IWorkflowDefinitions, VersionDetails } from "../../definitions_module/services/IWorkflowDefinitions.service";
 import type { WorkflowEvents } from "../../internal/WorkflowEvents";
-import { WORKFLOW_INSTANCE_CANCELLED, WORKFLOW_INSTANCE_FINISHED, WORKFLOW_INSTANCE_RETRIED, WORKFLOW_INSTANCE_STARTED, WORKFLOW_TASK_REQUESTED, WORKFLOW_TOKEN_CLOSED } from "../events/Runtime.events";
+import { WORKFLOW_INSTANCE_CANCELLED, WORKFLOW_INSTANCE_FINISHED, WORKFLOW_INSTANCE_RETRIED, WORKFLOW_INSTANCE_STARTED, WORKFLOW_TASK_REQUESTED, WORKFLOW_TOKEN_CLOSED, WORKFLOW_TRIAL_TASK_REQUESTED, WORKFLOW_TRIAL_TOKEN_CLOSED } from "../events/Runtime.events";
 import type { RuntimeDbContext } from "../model/Runtime.dbContext";
 import { WfHistory, type HistoryType } from "../model/WfHistory.model";
 import { WfInstance, type StartedVia } from "../model/WfInstance.model";
@@ -53,6 +53,8 @@ export interface BeginOptions {
   readonly queued?: boolean;
   /** The firing a scheduled start belongs to: `$trigger.scheduledAt`. */
   readonly scheduledAt?: Date;
+  /** A trial run (WORKFLOW-002 §5.4): takes no place among real ones and tells the application nothing. */
+  readonly test?: boolean;
 }
 
 /** Why a step failed. `reason` is the business reason an error boundary may name. */
@@ -162,7 +164,7 @@ export class WorkflowEngine {
    */
   async begin(graph: ProcessGraph, startNodeId: string, options: BeginOptions): Promise<Begun> {
     return await this.db.transactionScope(async (transaction) => {
-      const admission = await this.admit(graph, options.businessKey);
+      const admission = options.test === true ? "start" : await this.admit(graph, options.businessKey);
       if (typeof admission === "object") return { id: admission.skippedBy, skipped: true };
       const waits = admission === "queue" || options.queued === true;
       const instance = this.newInstance(graph, options, waits ? "pending" : "running");
@@ -211,7 +213,7 @@ export class WorkflowEngine {
     await this.lockProcess(graph.processKey);
     if (keyed) {
       const same = await this.db.instances.asNoTracking()
-        .where((i) => i.processKey.eq(graph.processKey).and(i.businessKey.eq(businessKey)).and(i.status.in(["pending", "running", "failed"])))
+        .where((i) => i.processKey.eq(graph.processKey).and(i.businessKey.eq(businessKey)).and(i.test.eq(false)).and(i.status.in(["pending", "running", "failed"])))
         .firstOrDefault();
       if (same) return sameKey === "skip" ? { skippedBy: same.id } : "queue";
     }
@@ -224,13 +226,13 @@ export class WorkflowEngine {
   }
 
   async runningOf(processKey: string): Promise<number> {
-    return await this.db.instances.asNoTracking().where((i) => i.processKey.eq(processKey).and(i.status.eq("running"))).count();
+    return await this.db.instances.asNoTracking().where((i) => i.processKey.eq(processKey).and(i.test.eq(false)).and(i.status.eq("running"))).count();
   }
 
   /** Scheduled runs of a process that still go on in a partition, for `overlap`. A failed one waits for a person and takes no place. */
   async scheduledLive(processKey: string, partition: string | null): Promise<number> {
     return await this.db.instances.asNoTracking()
-      .where((i) => i.processKey.eq(processKey).and(i.startedVia.eq("schedule")).and(i.status.in(["pending", "running"])).and(partition === null ? i.partition.isNull() : i.partition.eq(partition)))
+      .where((i) => i.processKey.eq(processKey).and(i.test.eq(false)).and(i.startedVia.eq("schedule")).and(i.status.in(["pending", "running"])).and(partition === null ? i.partition.isNull() : i.partition.eq(partition)))
       .count();
   }
 
@@ -255,6 +257,7 @@ export class WorkflowEngine {
       processKey: graph.processKey,
       version: graph.version,
       partition: options.partition,
+      test: options.test === true,
       input: options.input,
       vars: initialVarsOf(graph.document),
       event: options.event?.payload ?? null,
@@ -928,14 +931,24 @@ export class WorkflowEngine {
 
   /** Events go out after the commit, so a handler never sees a step that rolled back. */
   private publishAfter(transaction: { afterCommit(callback: () => void | Promise<void>): void }, step: Step): void {
-    if (step.events.length === 0) return;
-    const events = [...step.events];
+    const events = step.instance.test ? trialEvents(step) : [...step.events];
+    if (events.length === 0) return;
     transaction.afterCommit(async () => {
       for (const { event, payload } of events) await this.events.publish(event, payload);
     });
   }
 }
 
+/** What a trial run tells: only what its tasks need, and they go to who started it. */
+function trialEvents(step: Step): PendingEvent[] {
+  const { instance } = step;
+  return step.events.flatMap(({ event, payload }): PendingEvent[] => {
+    if (event === (WORKFLOW_TOKEN_CLOSED as EventToken<unknown>)) return [{ event: WORKFLOW_TRIAL_TOKEN_CLOSED as EventToken<unknown>, payload }];
+    if (event !== (WORKFLOW_TASK_REQUESTED as EventToken<unknown>)) return [];
+    return [{ event: WORKFLOW_TRIAL_TASK_REQUESTED as EventToken<unknown>, payload: { ...(payload as object), assignee: { user: instance.startedById } } }];
+  });
+}
+
 /** When a timer fires: `duration` from now, or the date at the `at` path; `undefined` if neither is valid. */
 export function timerDue(config: Readonly<Record<string, unknown>>, data: InstanceData, now: Date): Date | undefined {
   if (typeof config.duration === "string") {

package/core/workflow/runtime_module/services/IWorkflowRuntime.service.ts

@@ -16,6 +16,11 @@ export interface StartInstance extends WorkflowAuditOptions {
   readonly actor: WorkflowActor;
   /** The language of the request, for the application's validator; `workflow.language` by default. */
   readonly language?: string;
+  /**
+   * A trial run (WORKFLOW-002 §5.4): Tools change nothing, the application hears
+   * nothing, tasks go only to who started it. It lives for a day.
+   */
+  readonly test?: boolean;
 }
 
 /** One element of a mass start. */
@@ -63,8 +68,14 @@ export interface InstanceSummary {
   /** The instance whose `callProcess` started this one. */
   readonly parentInstanceId: string | null;
   readonly error: { readonly node: string; readonly code: string; readonly message: string } | null;
+  /** The step it failed on. */
+  readonly failedNode: string | null;
+  /** A trial run. */
+  readonly test: boolean;
   readonly createdAt: Date;
   readonly endedAt: Date | null;
+  /** How long it took by the engine's clock; `null` until it ends. */
+  readonly durationMs: number | null;
 }
 
 export interface TokenDetails {
@@ -141,6 +152,8 @@ export interface InstanceListQuery extends WorkflowPaging {
   readonly businessKey?: string;
   readonly startedById?: string;
   readonly parentInstanceId?: string;
+  /** Trial runs are hidden unless asked for: `true` gives only them. Children of a named parent are shown as they are. */
+  readonly test?: boolean;
 }
 
 /**

package/core/workflow/runtime_module/services/WorkflowRuntime.service.ts

@@ -55,7 +55,7 @@ export class WorkflowRuntime extends IWorkflowRuntime {
     if (!start) throw new WorkflowError("wrong_status", `Process ${processKey} has no manual start`);
     const { value, issues } = await this.validator().validate(inputSpecOf(version.document), options.input, { purpose: "input", processKey, partition, language: options.language ?? this.languages.default, actor: options.actor });
     if (issues.length > 0) throw new WorkflowError("invalid_input", "The process input is invalid", issues);
-    const { id, skipped } = await this.engine.begin(this.engine.cache(version), start[0], { input: value, partition, businessKey, startedVia: "manual", actor: options.actor, request: options.request ?? null });
+    const { id, skipped } = await this.engine.begin(this.engine.cache(version), start[0], { input: value, partition, businessKey, startedVia: "manual", actor: options.actor, request: options.request ?? null, ...(options.test === true ? { test: true } : {}) });
     if (skipped) throw new WorkflowError("conflict", `Instance ${id} with this businessKey is not finished`);
     return await this.instance(id);
   }
@@ -160,6 +160,7 @@ export class WorkflowRuntime extends IWorkflowRuntime {
     if (query.businessKey !== undefined) source = source.where((i) => i.businessKey.eq(query.businessKey!));
     if (query.startedById !== undefined) source = source.where((i) => i.startedById.eq(query.startedById!));
     if (query.parentInstanceId !== undefined) source = source.where((i) => i.parentInstanceId.eq(query.parentInstanceId!));
+    if (query.test !== undefined || query.parentInstanceId === undefined) source = source.where((i) => i.test.eq(query.test === true));
     const { items, total } = await paginate(source, pageQueryOf(query, { field: "id", dir: "desc" }));
     return { items: items.map(summaryOf), total };
   }
@@ -231,11 +232,20 @@ function summaryOf(row: WfInstance): InstanceSummary {
     startedBy: { kind: row.startedByKind, id: row.startedById },
     parentInstanceId: row.parentInstanceId,
     error: row.error,
+    failedNode: row.error === null || row.error.node === "" ? null : row.error.node,
+    test: row.test,
     createdAt: row.createdAt,
     endedAt: row.endedAt,
+    durationMs: durationOf(row),
   };
 }
 
+/** From the start by the engine's clock: `createdAt` is the clock of the database. */
+function durationOf(row: WfInstance): number | null {
+  const startedAt = typeof row.trigger?.at === "string" ? Date.parse(row.trigger.at) : Number.NaN;
+  return row.endedAt === null || Number.isNaN(startedAt) ? null : row.endedAt.getTime() - startedAt;
+}
+
 function tokenOf(row: WfToken) {
   return { id: row.id, nodeId: row.nodeId, viaFlowId: row.viaFlowId, parentTokenId: row.parentTokenId, iteration: row.iteration, status: row.status, output: row.output, createdAt: row.createdAt, endedAt: row.endedAt };
 }

package/core/workflow/tasks_module/events/TaskEvents.ts

@@ -1,5 +1,5 @@
 import { OnEvent } from "../../../kernel";
-import { WORKFLOW_INSTANCES_DELETED, WORKFLOW_TASK_REQUESTED, WORKFLOW_TOKEN_CLOSED, type WorkflowInstancesDeleted, type WorkflowTaskRequested, type WorkflowTokenClosed } from "../../runtime_module/events/Runtime.events";
+import { WORKFLOW_INSTANCES_DELETED, WORKFLOW_TASK_REQUESTED, WORKFLOW_TOKEN_CLOSED, WORKFLOW_TRIAL_TASK_REQUESTED, WORKFLOW_TRIAL_TOKEN_CLOSED, type WorkflowInstancesDeleted, type WorkflowTaskRequested, type WorkflowTokenClosed } from "../../runtime_module/events/Runtime.events";
 import type { TasksDbContext } from "../model/Tasks.dbContext";
 import { WfTask } from "../model/WfTask.model";
 
@@ -10,6 +10,16 @@ export class TaskEvents {
   /** A step started waiting for a person: its task. Repeated events of one token make one task. */
   @OnEvent(WORKFLOW_TASK_REQUESTED)
   async requested(event: WorkflowTaskRequested): Promise<void> {
+    await this.add(event, false);
+  }
+
+  /** The task of a trial run: it goes to who started it, and is marked. */
+  @OnEvent(WORKFLOW_TRIAL_TASK_REQUESTED)
+  async trialRequested(event: WorkflowTaskRequested): Promise<void> {
+    await this.add(event, true);
+  }
+
+  private async add(event: WorkflowTaskRequested, test: boolean): Promise<void> {
     const assignee = "role" in event.assignee ? `role:${event.assignee.role}` : `user:${event.assignee.user}`;
     // Past the change tracker: the scope may go on to update tasks directly, which a context holding one would refuse.
     await this.db.tasks.insertIfAbsent(Object.assign(new WfTask(), {
@@ -18,6 +28,7 @@ export class TaskEvents {
       processKey: event.processKey,
       nodeId: event.nodeId,
       partition: event.partition,
+      test,
       title: event.title,
       assignee,
       form: event.form,
@@ -32,6 +43,11 @@ export class TaskEvents {
     await this.db.tasks.asNoTracking().where((t) => t.tokenId.eq(event.tokenId).and(t.status.in(["open", "claimed"]))).executeUpdate({ status: "cancelled" });
   }
 
+  @OnEvent(WORKFLOW_TRIAL_TOKEN_CLOSED)
+  async trialClosed(event: WorkflowTokenClosed): Promise<void> {
+    await this.closed(event);
+  }
+
   /** Retention deleted the instances: their tasks go too. */
   @OnEvent(WORKFLOW_INSTANCES_DELETED)
   async deleted(event: WorkflowInstancesDeleted): Promise<void> {

package/core/workflow/tasks_module/services/IWorkflowTasks.service.ts

@@ -11,6 +11,8 @@ export interface TaskDetails {
   readonly nodeId: string;
   readonly partition: string | null;
   readonly title: LocalizedText;
+  /** A task of a trial run. */
+  readonly test: boolean;
   readonly assignee: string;
   readonly form: FormSpec | null;
   readonly dueAt: Date | null;

package/core/workflow/tasks_module/services/WorkflowTasks.service.ts

@@ -100,7 +100,7 @@ export class WorkflowTasks extends IWorkflowTasks {
       completedAt: this.clock.now(),
       output: typeof saved === "object" && saved !== null && !Array.isArray(saved) ? saved as Record<string, unknown> : null,
     });
-    await this.events.publish(WORKFLOW_TASK_COMPLETED, { taskId: task.id, instanceId: task.instanceId, processKey: task.processKey, nodeId: task.nodeId, partition: task.partition, actor, request: options.request ?? null });
+    if (!task.test) await this.events.publish(WORKFLOW_TASK_COMPLETED, { taskId: task.id, instanceId: task.instanceId, processKey: task.processKey, nodeId: task.nodeId, partition: task.partition, actor, request: options.request ?? null });
     return await this.get(task.id);
   }
 
@@ -157,6 +157,7 @@ function detailsOf(row: WfTask): TaskDetails {
     nodeId: row.nodeId,
     partition: row.partition,
     title: row.title,
+    test: row.test,
     assignee: row.assignee,
     form: row.form,
     dueAt: row.dueAt,

package/library/workflow/index.ts

@@ -42,6 +42,7 @@ export {
 } from "./expressions";
 export { ExpressionSyntaxError, parseExpression, printExpression } from "./expressionSyntax";
 export { durationMs } from "./duration";
+export { documentReferences, inputReferences, schemaReferenceKinds, type DocumentReference, type InputReference } from "./references";
 export { isTimeZone, parseCron, type CronSchedule } from "./cron";
 export { processToMermaid } from "./mermaid";
 export { PERSONAL_MASK, maskByMapping, maskBySchema, masksPersonal, personalPaths, personalVariables, readsPersonal } from "./masking";

package/library/workflow/references.ts

@@ -0,0 +1,106 @@
+import { isExpressionNode } from "./expressions";
+import { isPath } from "./paths";
+import type { ProcessDocument } from "./ProcessDocument";
+
+/** One reference in a Tool input or a document: what `x-ref` and `x-ref-keys` of a schema mark. */
+export interface InputReference {
+  readonly kind: string;
+  readonly id: string;
+  /** The area it is looked for in: `x-ref-scope`. */
+  readonly within?: string;
+  /** Where in the input: `/values/status`. */
+  readonly path: string;
+}
+
+/** A reference of a document, and whose it is. */
+export interface DocumentReference extends InputReference {
+  readonly node?: string;
+  readonly variable?: string;
+}
+
+type Json = Record<string, unknown>;
+
+function isObject(value: unknown): value is Json {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Whether a value is known only when the step runs. */
+function isComputed(value: unknown): boolean {
+  return isPath(value) || isExpressionNode(value);
+}
+
+function isId(value: unknown): value is string | number {
+  return (typeof value === "string" && value !== "") || typeof value === "number";
+}
+
+/**
+ * The references in a Tool input by the JSON Schema of the input. A value computed
+ * when the step runs is left out: it is checked then. `x-ref-scope` beginning
+ * with `/` is a JSON Pointer to another field of the input; otherwise it is the area
+ * itself. A reference whose area is computed is left out too.
+ */
+export function inputReferences(schema: unknown, input: unknown): InputReference[] {
+  const out: InputReference[] = [];
+  const within = (source: Json): { readonly known: boolean; readonly value?: string } => {
+    const scope = source["x-ref-scope"];
+    if (typeof scope !== "string") return { known: true };
+    if (!scope.startsWith("/")) return { known: true, value: scope };
+    let current: unknown = input;
+    for (const key of scope.slice(1).split("/")) {
+      current = isObject(current) && Object.hasOwn(current, key) ? current[key] : undefined;
+    }
+    return isId(current) && !isComputed(current) ? { known: true, value: String(current) } : { known: false };
+  };
+  const walk = (source: unknown, value: unknown, path: string): void => {
+    if (!isObject(source) || value === undefined || value === null || isComputed(value)) return;
+    const area = within(source);
+    const add = (kind: string, id: string, at: string) => out.push({ kind, id, ...(area.value === undefined ? {} : { within: area.value }), path: at });
+    if (typeof source["x-ref"] === "string" && isId(value) && area.known) add(source["x-ref"], String(value), path);
+    if (Array.isArray(value)) {
+      value.forEach((item, index) => walk(source.items, item, `${path}/${index}`));
+      return;
+    }
+    if (!isObject(value)) return;
+    if (typeof source["x-ref-keys"] === "string" && area.known) for (const key of Object.keys(value)) add(source["x-ref-keys"], key, `${path}/${key}`);
+    if (isObject(source.properties)) {
+      for (const [key, item] of Object.entries(source.properties)) if (Object.hasOwn(value, key)) walk(item, value[key], `${path}/${key}`);
+    }
+  };
+  walk(schema, input, "");
+  return out;
+}
+
+/** The kinds a schema refers to, whatever the values: each must have an owner. */
+export function schemaReferenceKinds(schema: unknown): string[] {
+  const kinds = new Set<string>();
+  const walk = (source: unknown): void => {
+    if (!isObject(source)) return;
+    for (const key of ["x-ref", "x-ref-keys"]) if (typeof source[key] === "string") kinds.add(source[key]);
+    if (isObject(source.properties)) Object.values(source.properties).forEach(walk);
+    walk(source.items);
+  };
+  walk(schema);
+  return [...kinds];
+}
+
+/**
+ * The references a document holds as literals (WORKFLOW-002 §6.3): in the inputs of
+ * its Tools, by their schemas; the defaults of variables of type `ref`; the processes
+ * it calls. `inputSchemaOf` gives the input schema of a Tool, if it is known.
+ */
+export function documentReferences(document: ProcessDocument, inputSchemaOf: (tool: string) => unknown): DocumentReference[] {
+  const out: DocumentReference[] = [];
+  for (const variable of document.variables ?? []) {
+    if (variable.type === "ref" && typeof variable.ref === "string" && isId(variable.default)) {
+      out.push({ kind: variable.ref, id: String(variable.default), path: "/default", variable: variable.name });
+    }
+  }
+  const handler = document.settings?.errorHandler;
+  if (handler !== undefined) out.push({ kind: "workflow.process", id: handler, path: "/settings/errorHandler" });
+  for (const [node, { kind, config }] of Object.entries(document.nodes)) {
+    if (kind === "callProcess" && typeof config?.process === "string") out.push({ kind: "workflow.process", id: config.process, path: "/process", node });
+    if (kind !== "serviceTask" || typeof config?.tool !== "string") continue;
+    for (const reference of inputReferences(inputSchemaOf(config.tool), config.input)) out.push({ ...reference, node });
+  }
+  return out;
+}

package/library/workflow/validateProcess.ts

@@ -33,6 +33,7 @@ export type ProcessIssueCode =
   | "config_invalid"
   | "unknown_tool"
   | "unknown_process"
+  | "broken_ref"
   | "container_invalid"
   | "flow_across_container"
   | "loop_body"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bazis",
-  "version": "0.134.0",
+  "version": "0.135.0",
   "description": "Modular backend framework for Bun in TypeScript: DI wired by codegen, HTTP, a PostgreSQL ORM, JWT, WebSocket, agents and a CLI.",
   "license": "MIT",
   "author": "Alexander Alenin",