bazis 0.134.0 → 0.136.0

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, ServiceProvider]],
+  [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,11 @@
 import type { AgentSchemaContract, AgentToolResult } from "../../../agent";
-import { durationMs, maskByMapping, maskBySchema, masksPersonal, personalPaths, resolveInput, type ProcessDocument } from "../../../../library/workflow";
+import { redactValues, rememberSecretValue } from "../../../../library/redaction";
+import { durationMs, inputReferences, maskByMapping, maskBySchema, masksPersonal, personalPaths, resolveInput, secretNames, type ProcessDocument } from "../../../../library/workflow";
+import type { ServiceProvider } from "../../../di";
+import { SecretStore } from "../../../tools/secrets/SecretStore";
 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 +28,10 @@ export class ToolStep {
     private readonly db: RuntimeDbContext,
     private readonly engine: WorkflowEngine,
     private readonly tools: WorkflowTools,
+    private readonly references: WorkflowReferences,
+    private readonly languages: WorkflowLanguages,
+    /** The scope: the application's own `SecretStore` replaces the default. */
+    private readonly services: ServiceProvider,
   ) {}
 
   async run(job: WfJob, signal: AbortSignal): Promise<void> {
@@ -35,26 +44,41 @@ export class ToolStep {
     const graph = await this.engine.graphOf(instance.versionId);
     const node = graph.document.nodes[token.nodeId];
     const name = String(node?.config?.tool ?? "");
-    const input = resolveInput(node?.config?.input ?? {}, dataOf(instance, this.engine.now(), token));
+    const { values: secrets, missing: noSecret } = await this.secretsOf(node?.config?.input, instance.partition);
+    const revealed = Object.values(secrets);
+    const input = resolveInput(node?.config?.input ?? {}, { ...dataOf(instance, this.engine.now(), token), secrets });
     const timeoutMs = stepTimeoutMs(node?.config?.timeout, graph.document);
     // A step may run longer than the lease: another worker must not take the job and call the Tool again meanwhile.
     if (timeoutMs !== undefined && timeoutMs >= LEASE_MS) {
       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 result: AgentToolResult = runner === undefined
+    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 raw: 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
+      : noSecret !== undefined
+      ? { callId: token.id, name, status: "error", error: { code: "secret_not_found", message: `There is no secret ${noSecret}`, details: { reason: "secret_not_found" } }, 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 }),
       });
 
+    // What the Tool got back from the outside may echo a secret: it goes no further than the Tool.
+    const result = redactValues(raw, revealed);
     const timedOut = TIMEOUT_CODES.has(result.error?.code ?? "");
     const reason = timedOut ? "timeout" : reasonOf(result);
-    const payloads = graph.document.settings?.log?.toolPayloads === true ? this.payloads(graph.document, name, node?.config?.input, input, result) : {};
+    const payloads = graph.document.settings?.log?.toolPayloads === true ? redactValues(this.payloads(graph.document, name, node?.config?.input, input, result), revealed) : {};
     await this.engine.inStep(instance.id, async (step) => {
       const current = step.tokens.find((t) => t.id === token.id);
       const retryAt = current?.status === "waiting" && step.instance.status === "running" && result.status === "error" && (reason === undefined || timedOut)
@@ -72,6 +96,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() }),
@@ -89,6 +114,21 @@ export class ToolStep {
     });
   }
 
+  /** The values of `$secrets` this input names, and the first one there is not. Remembered, so that a log masks them too. */
+  private async secretsOf(input: unknown, partition: string | null): Promise<{ readonly values: Record<string, string>; readonly missing?: string }> {
+    const values: Record<string, string> = {};
+    const names = secretNames(input);
+    if (names.length === 0) return { values };
+    const store = this.services.tryResolve(SecretStore);
+    for (const name of names) {
+      const value = await store?.get(name, { partition });
+      if (value === undefined) return { values, missing: name };
+      rememberSecretValue(value);
+      values[name] = value;
+    }
+    return { values };
+  }
+
   /** The input and output for the history under `log.toolPayloads`; personal data is masked unless `log.maskPersonal` is `false`. */
   private payloads(document: ProcessDocument, name: string, mapping: unknown, input: unknown, result: AgentToolResult): Record<string, unknown> {
     if (!masksPersonal(document)) return { input, output: result.output ?? null };

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") {