bazis 0.128.0 → 0.130.0

package/core/scripts/di-generate.ts

@@ -31,6 +31,13 @@ const FRAMEWORK_SOURCE = ((): string | null => {
 })();
 const FRAMEWORK_ROOT = FRAMEWORK_SOURCE ?? "src/bazis";
 const isFrameworkSourcePath = (file: string): boolean => FRAMEWORK_SOURCE !== null && file.startsWith(`${FRAMEWORK_SOURCE}/`);
+/**
+ * Packs of the framework's own checkout whose DI wiring ships inside the
+ * package (`framework.packs` of bazis.config.json): an application's codegen
+ * skips node_modules, so the pack carries `<pack>/generated/deps.ts` itself.
+ */
+let frameworkPacks: readonly string[] = [];
+const isFrameworkPackPath = (file: string): boolean => frameworkPacks.some((pack) => file.startsWith(`${pack}/`));
 const APP_GENERATED_DIR = "src/generated/bazis";
 let activeGeneratedDir = APP_GENERATED_DIR;
 const plannedWrites = new Map<string, string>();
@@ -163,8 +170,9 @@ function readRequestedTarget(): string | undefined {
   throw new Error(`BAZIS_CODEGEN_TARGET_UNKNOWN: ${target ?? ""}`);
 }
 
-// Framework internals: their classes are excluded from the auto-deps map (they
-// wire their own services explicitly). Auto-deps magic targets user code only.
+// Framework internals: their classes are excluded from the auto-deps map of a
+// target. Packs listed in `framework.packs` get their own generated wiring
+// (generateFrameworkPack); the rest still wire their services explicitly.
 const FRAMEWORK_INTERNAL_PREFIXES = FRAMEWORK_SOURCE === null ? [] : [
   "core/di/", "core/kernel/", "core/http/", "core/grpc/", "core/http-client/", "core/background/",
   "core/agent/", "core/websocket/", "core/cache/", "library/validation/", "library/boundary/",
@@ -251,7 +259,8 @@ let program: ts.Program;
 let programFiles = new Map<string, ts.SourceFile>();
 // Framework sources outside the scanned project (node_modules/bazis, vendor/bazis).
 // Only their class and token names are read, so app constructor dependencies on
-// framework classes are not discarded as unknown; their own wiring ships with them.
+// framework classes are not discarded as unknown; their own wiring ships with them
+// (`<pack>/generated/deps.ts` of the framework packs).
 let installedFrameworkSources: ts.SourceFile[] = [];
 let sourceFilePathSet = new Set<string>();
 let checker: ts.TypeChecker;
@@ -348,6 +357,7 @@ async function runConfiguredTargets(): Promise<void> {
   const totalStartedAt = performance.now();
   const configStartedAt = performance.now();
   const config = await readCodegenConfig();
+  frameworkPacks = FRAMEWORK_SOURCE === null ? [] : (config.framework?.packs ?? []);
   await planStaleGeneratedTargetRemoval(Object.keys(config.targets));
   // Test sources remain excluded from the broad candidate scan. A test-only
   // target can still opt a single fixture in explicitly through its declared
@@ -434,6 +444,7 @@ async function runConfiguredTargets(): Promise<void> {
     eligible += metrics.eligible;
     candidates += metrics.candidates;
   }
+  for (const pack of frameworkPacks) generateFrameworkPack(pack);
   const targetMs = performance.now() - targetStartedAt;
   const writeStartedAt = performance.now();
   await commitPlannedWrites();
@@ -444,7 +455,7 @@ async function runConfiguredTargets(): Promise<void> {
 
 function createSourceCandidateIndex(files: ReadonlyMap<string, ts.SourceFile>): ReadonlyMap<string, boolean> {
   for (const [file, source] of files) {
-    if (!FRAMEWORK_INTERNAL_PREFIXES.some((prefix) => file.startsWith(prefix))) collectDiClassRegistrations(source);
+    if (!FRAMEWORK_INTERNAL_PREFIXES.some((prefix) => file.startsWith(prefix)) && !isFrameworkPackPath(file)) collectDiClassRegistrations(source);
   }
   return new Map([...files].map(([file, source]) => [file, sourceHasCodegenCandidate(source)]));
 }
@@ -511,15 +522,16 @@ async function generateTarget(name: string, reachable: Set<string>, production:
   resetTargetAnalysis(reachable, generatedDir);
   for (const { source } of sourceEntries) collectListRequestClasses(source);
   for (const { filePath, source } of sourceEntries) {
-    if (!FRAMEWORK_INTERNAL_PREFIXES.some((prefix) => filePath.startsWith(prefix))) collectDiClassRegistrations(source);
+    if (!FRAMEWORK_INTERNAL_PREFIXES.some((prefix) => filePath.startsWith(prefix)) && !isFrameworkPackPath(filePath)) collectDiClassRegistrations(source);
   }
   const prepassMs = performance.now() - startedAt;
   for (const source of installedFrameworkSources) collectTokenDescriptions(source);
   for (const { filePath, source } of sourceEntries) {
     fatalErrors.push(...analyzeOrmPredicates(checker, source));
     collectTokenDescriptions(source);
-    if (!FRAMEWORK_INTERNAL_PREFIXES.some((prefix) => filePath.startsWith(prefix))) {
+    if (!FRAMEWORK_INTERNAL_PREFIXES.some((prefix) => filePath.startsWith(prefix)) && !isFrameworkPackPath(filePath)) {
       collectClassDeps(source);
+      collectProviderFormErrors(source);
       collectGrpcBindings(source);
       toolCodegenSources.push({ filePath, sourceFile: source });
     }
@@ -575,6 +587,72 @@ function classifyToolWarnings(toolWarnings: readonly string[]): void {
   }
 }
 
+/**
+ * The wiring of one framework pack: constructor dependencies of the classes
+ * its modules register, written to `<pack>/generated/deps.ts`. The pack's
+ * `index.ts` imports that file, so the package carries its own wiring and
+ * framework modules register `singleton(IContract, Implementation)` like an
+ * application does.
+ */
+function generateFrameworkPack(pack: string): void {
+  const files = new Set([...programFiles.keys()].filter((file) => file.startsWith(`${pack}/`)));
+  if (!files.has(`${pack}/index.ts`)) throw new Error(`BAZIS_CODEGEN_CONFIG_INVALID: framework pack ${pack} has no index.ts`);
+  resetTargetAnalysis(files, `${pack}/generated`);
+  // Tokens, configs and classes the pack depends on may live anywhere in the framework.
+  for (const source of programFiles.values()) collectTokenDescriptions(source);
+  for (const { source } of sourceEntries) collectDiClassRegistrations(source);
+  for (const { source } of sourceEntries) collectClassDeps(source);
+  for (const { source } of sourceEntries) collectProviderFormErrors(source);
+  resolveConfigViewDeps();
+  validateDepsAgainstKnownTokens();
+  failOnFatalErrors();
+  stageWrite(`${pack}/generated/deps.ts`, renderFrameworkPackDeps(pack));
+  for (const warning of warnings) reportWarning(warning);
+  reportInfo(`[di:generate] framework pack=${pack} deps=${classDeps.size}`);
+}
+
+function renderFrameworkPackDeps(pack: string): string {
+  const generatedDir = `${pack}/generated`;
+  const entries = [...classDeps.entries()].sort(([left], [right]) =>
+    left.name!.text.localeCompare(right.name!.text)
+    || left.getSourceFile().fileName.localeCompare(right.getSourceFile().fileName)
+    || left.pos - right.pos);
+  const references = new Map<ts.ClassDeclaration, string>();
+  for (const [declaration] of entries) references.set(declaration, declaration.name!.text);
+  for (const [, dependencies] of entries) {
+    for (const dependency of dependencies) {
+      if (dependency.target && !references.has(dependency.target)) references.set(dependency.target, dependency.target.name!.text);
+    }
+  }
+  const di = (file: string) => JSON.stringify(toModuleSpecifierFrom(generatedDir, `${FRAMEWORK_SOURCE}/core/di/${file}`));
+  const lines = ["// This file is auto-generated by `bun run di:generate` (framework.packs of bazis.config.json).", "// Do not edit manually."];
+  const helpers = ["lazyDependency", "optionalDependency"].filter((helper) => entries.some(([, deps]) =>
+    deps.some((dep) => dep.target && (helper === "lazyDependency" ? dep.lazy : dep.optional))));
+  if (helpers.length > 0) lines.push(`import { ${helpers.join(", ")} } from ${di("provider/index.ts")};`);
+  lines.push(`import { registerFrameworkClassDeps } from ${di("module/autoDeps.ts")};`);
+  const byFile = new Map<string, string[]>();
+  for (const [declaration, reference] of references) {
+    const name = dependencyClassExportName(declaration);
+    if (!name) throw new Error(`BAZIS_DI_CLASS_UNIMPORTABLE: ${sourceLocation(declaration)}`);
+    const specifier = toModuleSpecifierFrom(generatedDir, normalizeProjectPath(declaration.getSourceFile().fileName));
+    byFile.set(specifier, [...(byFile.get(specifier) ?? []), name === reference ? name : `${name} as ${reference}`]);
+  }
+  for (const [specifier, names] of [...byFile].sort(([left], [right]) => left.localeCompare(right))) {
+    lines.push(`import { ${names.sort().join(", ")} } from ${JSON.stringify(specifier)};`);
+  }
+  lines.push("", "registerFrameworkClassDeps([");
+  for (const [declaration, dependencies] of entries) {
+    const values = dependencies.map((dependency) => {
+      if (!dependency.target) return JSON.stringify(dependency.optional ? `optional:${dependency.name}` : dependency.name);
+      const reference = references.get(dependency.target)!;
+      return dependency.lazy ? `lazyDependency(${reference})` : dependency.optional ? `optionalDependency(${reference})` : reference;
+    });
+    lines.push(`  [${references.get(declaration)}, [${values.join(", ")}]],`);
+  }
+  lines.push("]);");
+  return `${lines.join("\n")}\n`;
+}
+
 function failOnFatalErrors(): void {
   if (fatalErrors.length === 0) {
     return;
@@ -797,7 +875,7 @@ function resolveConfigViewDeps(): void {
         if (needsInferredDiDeps(declaration)) {
           fatalErrors.push(prefixes.length === 0
             ? `BAZIS_DI_CONFIG_UNKNOWN: ${sourceLocation(declaration)}: constructor parameter ${index + 1} of "${declaration.name?.text}" has type "ConfigView<${typeName}>", but no defineConfig<${typeName}>(...) declaration was found. Declare the configuration with an explicit type argument, for example defineConfig<${typeName}>("name", { default: {...} }).`
-            : `BAZIS_DI_CONFIG_AMBIGUOUS: ${sourceLocation(declaration)}: constructor parameter ${index + 1} of "${declaration.name?.text}" has type "ConfigView<${typeName}>", which matches several declarations: ${prefixes.map((prefix) => `"${prefix}"`).join(", ")}. Give each declaration its own type, or pass the token explicitly: scoped(Service, Service, [config.token]).`);
+            : `BAZIS_DI_CONFIG_AMBIGUOUS: ${sourceLocation(declaration)}: constructor parameter ${index + 1} of "${declaration.name?.text}" has type "ConfigView<${typeName}>", which matches several declarations: ${prefixes.map((prefix) => `"${prefix}"`).join(", ")}. Give each declaration its own type.`);
         }
         changed = false;
         break;
@@ -833,7 +911,7 @@ function validateDepsAgainstKnownTokens(): void {
       // would fail later, far from the cause. Other classes need no entry.
       if (needsInferredDiDeps(declaration)) {
         fatalErrors.push(declaration.members.some(ts.isConstructorDeclaration)
-          ? `BAZIS_DI_DEPENDENCY_UNKNOWN: ${sourceLocation(declaration)}: constructor parameter ${index + 1} of "${declaration.name?.text}" has type "${depName}", which is neither a DI token (createToken) nor a class known to codegen. Register it, import it from the framework package, or bind the class with an explicit factory.`
+          ? `BAZIS_DI_DEPENDENCY_UNKNOWN: ${sourceLocation(declaration)}: constructor parameter ${index + 1} of "${declaration.name?.text}" has type "${depName}", which is neither a DI token (createToken) nor a class known to codegen. Register it in a module or import it from the framework package.`
           : `BAZIS_DI_CONSTRUCTOR_UNRESOLVED: ${sourceLocation(declaration)}: inherited constructor dependency "${depName}" has no known DI token.`);
       }
       break;
@@ -847,7 +925,7 @@ function collectClassDeps(source: ts.SourceFile): void {
       const result = readConstructorTypeNames(node);
       if (result.unsupportedParameter !== undefined && needsInferredDiDeps(node)) {
         const { index, name, type } = result.unsupportedParameter;
-        fatalErrors.push(`BAZIS_DI_DEPENDENCY_UNKNOWN: ${sourceLocation(node)}: constructor parameter ${index + 1} "${name}" of "${node.name.text}" has type "${type}", which cannot be injected: DI resolves dependencies by class, contract or token, and a plain type does not say which value to inject. Declare a token with the same name as a type alias (export type Prefix = string; export const Prefix = createToken<Prefix>("Prefix")) and register a value, or pass the deps explicitly: scoped(${node.name.text}, ${node.name.text}, [TOKEN] as const).`);
+        fatalErrors.push(`BAZIS_DI_DEPENDENCY_UNKNOWN: ${sourceLocation(node)}: constructor parameter ${index + 1} "${name}" of "${node.name.text}" has type "${type}", which cannot be injected: DI resolves dependencies by class, contract or token, and a plain type does not say which value to inject. Declare a token with the same name as a type alias (export type Prefix = string; export const Prefix = createToken<Prefix>("Prefix")), register a value with singletonValue(Prefix, "…") and type the parameter with it: prefix: Prefix.`);
       }
       if (result.unsupportedInheritedParameter !== undefined && needsInferredDiDeps(node)) {
         fatalErrors.push(`BAZIS_DI_CONSTRUCTOR_UNRESOLVED: ${sourceLocation(node)}: cannot infer inherited constructor parameter "${result.unsupportedInheritedParameter}" for "${node.name.text}". The parameter needs a runtime DI token or an explicit value/factory binding.`);
@@ -951,6 +1029,96 @@ function collectDiClassRegistrations(source: ts.SourceFile): void {
   visit(source);
 }
 
+/**
+ * A module registers its services only in the agreed forms (docs/guide
+ * fundamentals/dependency-injection.md): a class under its contract, a ready
+ * value, an asynchronously created resource, event subscribers. Constructor dependencies come from codegen, so a
+ * dependency list, a factory or a low-level `DI.*` provider is a fatal error
+ * with the agreed form in the message.
+ */
+function collectProviderFormErrors(source: ts.SourceFile): void {
+  // Inside the function: the script runs before later top-level constants are initialized.
+  const AGREED_PROVIDERS = "scoped(IService, Service), singleton(IService, Service), transient(IService, Service) (or the class alone), singletonValue(TOKEN, value), singletonAsyncFactory(TOKEN, [deps], async factory) or ...withEventSubscribers(Class)";
+  const CLASS_LISTS = ["controllers", "grpcControllers", "gateways", "background", "tools", "grpcClients", "httpClients"];
+  const callee = (call: ts.CallExpression): { file?: string; name?: string } => {
+    let symbol = checker.getSymbolAtLocation(call.expression);
+    if (symbol && (symbol.flags & ts.SymbolFlags.Alias)) symbol = checker.getAliasedSymbol(symbol);
+    const declaration = symbol?.declarations?.find((entry) => ts.isFunctionDeclaration(entry) || ts.isMethodDeclaration(entry));
+    const name = declaration && "name" in declaration && declaration.name && ts.isIdentifier(declaration.name) ? declaration.name.text : undefined;
+    return { file: declaration?.getSourceFile().fileName.replace(/\\/g, "/"), name };
+  };
+  const resolved = <T extends ts.Node>(expression: ts.Expression, is: (node: ts.Node) => node is T): T | undefined => {
+    let current: ts.Expression = expression;
+    for (let depth = 0; depth < 5; depth++) {
+      if (is(current)) return current;
+      if (ts.isParenthesizedExpression(current) || ts.isAsExpression(current) || ts.isSatisfiesExpression(current)) { current = current.expression; continue; }
+      let symbol = checker.getSymbolAtLocation(current);
+      if (symbol && (symbol.flags & ts.SymbolFlags.Alias)) symbol = checker.getAliasedSymbol(symbol);
+      const declaration = symbol?.valueDeclaration;
+      if (!declaration || !ts.isVariableDeclaration(declaration) || !declaration.initializer) return undefined;
+      current = declaration.initializer;
+    }
+    return undefined;
+  };
+  const text = (node: ts.Node): string => {
+    const value = node.getText().replace(/\s+/g, " ");
+    return value.length > 90 ? `${value.slice(0, 87)}...` : value;
+  };
+  const checkProvider = (module: string, element: ts.Expression): void => {
+    if (ts.isSpreadElement(element)) {
+      const call = resolved(element.expression, ts.isCallExpression);
+      const target = call && callee(call);
+      if (target?.name === "withEventSubscribers" && target.file?.endsWith("/core/kernel/events/eventSubscribers.ts")) return;
+      fatalErrors.push(`BAZIS_DI_PROVIDER_FORM: ${sourceLocation(element)}: providers of ${module}: "${text(element)}" is not an agreed registration. Agreed forms: ${AGREED_PROVIDERS}.`);
+      return;
+    }
+    const call = ts.isCallExpression(element) ? element : undefined;
+    const target = call && callee(call);
+    if (call && target?.file?.endsWith("/core/di/module/shortcuts.ts")) {
+      if (["scoped", "singleton", "transient"].includes(target.name ?? "")) {
+        if (call.arguments.length <= 2) return;
+        fatalErrors.push(`BAZIS_DI_PROVIDER_FORM: ${sourceLocation(element)}: providers of ${module}: "${text(element)}" passes a dependency list. Remove it: codegen reads the constructor. Agreed forms: ${AGREED_PROVIDERS}.`);
+        return;
+      }
+      if (target.name === "singletonValue" && call.arguments.length === 2) return;
+      // A resource that is created asynchronously (a connection): created at startup.
+      if (target.name === "singletonAsyncFactory" && call.arguments.length === 3) return;
+    }
+    fatalErrors.push(`BAZIS_DI_PROVIDER_FORM: ${sourceLocation(element)}: providers of ${module}: "${text(element)}" is not an agreed registration. A computed service is a class with a constructor: scoped(IService, Service). Agreed forms: ${AGREED_PROVIDERS}.`);
+  };
+  const checkModule = (module: string, argument: ts.Expression | undefined): void => {
+    const object = argument && resolved(argument, ts.isObjectLiteralExpression);
+    if (!object) return;
+    for (const property of object.properties) {
+      if (!ts.isPropertyAssignment(property)) continue;
+      const field = property.name.getText().replace(/["']/g, "");
+      if (field !== "providers" && !CLASS_LISTS.includes(field)) continue;
+      const list = resolved(property.initializer, ts.isArrayLiteralExpression);
+      if (!list) {
+        fatalErrors.push(`BAZIS_DI_PROVIDER_FORM: ${sourceLocation(property)}: ${field} of ${module} must be an array written in the module.`);
+        continue;
+      }
+      for (const element of list.elements) {
+        if (field === "providers") checkProvider(module, element);
+        else if (!ts.isIdentifier(element) && !ts.isPropertyAccessExpression(element)) {
+          fatalErrors.push(`BAZIS_DI_PROVIDER_FORM: ${sourceLocation(element)}: ${field} of ${module}: "${text(element)}" — list the class itself; its constructor dependencies come from codegen.`);
+        }
+      }
+    }
+  };
+  const visit = (node: ts.Node): void => {
+    if (ts.isClassDeclaration(node)) {
+      for (const decorator of ts.getDecorators(node) ?? []) {
+        if (!ts.isCallExpression(decorator.expression)) continue;
+        const target = callee(decorator.expression);
+        if (target.name === "Module" && target.file?.endsWith("/core/di/module/Module.ts")) checkModule(node.name?.text ?? "<anonymous module>", decorator.expression.arguments[0]);
+      }
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(source);
+}
+
 function hasStaticClassDeps(node: ts.ClassDeclaration): boolean {
   if (!node.name) return false;
   const symbol = checker.getSymbolAtLocation(node.name);

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

@@ -1,9 +1,11 @@
-import { DI, HOSTED_SERVICE, Module, SERVICE_PROVIDER, scoped } from "../../di";
+import { AccessModule } from "../../access";
+import { HOSTED_SERVICE, Module, scoped, singleton } from "../../di";
 import { SystemWorkflowClock, WorkflowClock } from "../contracts/WorkflowClock";
 import { WorkflowTools } from "../internal/WorkflowTools";
+import { definitionsPermissions } from "./access/Definitions.permissions";
+import { ProcessReferences } from "./access/Process.references";
 import { CodeProcessCatalog } from "./code/CodeProcessCatalog";
 import { CodeProcessPublisher } from "./code/CodeProcessPublisher";
-import { codeProcessesOf } from "./code/codeProcesses";
 import { ProcessesController } from "./http/Processes.controller";
 import { DefinitionsDbContext, definitionsStore } from "./model/Definitions.dbContext";
 import { WfProcess } from "./model/WfProcess.model";
@@ -13,20 +15,22 @@ import { WorkflowDefinitions } from "./services/WorkflowDefinitions.service";
 
 /**
  * The process catalog: drafts and published versions, and the processes
- * declared in code ([passport](MODULE.md)). Dependencies are explicit: the
- * framework's classes are not covered by the application's codegen.
+ * declared in code ([passport](MODULE.md)).
  */
 @Module({
+  imports: [AccessModule],
+  permissions: definitionsPermissions,
+  references: { "workflow.process": ProcessReferences },
   ormBazis: { context: DefinitionsDbContext, entities: [WfProcess, WfVersion], ownedStore: definitionsStore, registerRepositories: false },
   providers: [
-    DI.singleton(DI.factoryProvider(WorkflowClock, [], () => new SystemWorkflowClock())),
-    DI.singleton(DI.factoryProviderWithResolver(WorkflowTools, [], (resolver) => new WorkflowTools(resolver.resolve(SERVICE_PROVIDER)))),
-    DI.singleton(DI.factoryProviderWithResolver(CodeProcessCatalog, [], (resolver) => new CodeProcessCatalog(codeProcessesOf(resolver.resolve(SERVICE_PROVIDER))))),
-    scoped(WorkflowDefinitions, WorkflowDefinitions, [DefinitionsDbContext, WorkflowTools, CodeProcessCatalog, WorkflowClock] as const),
-    DI.scoped(DI.factoryProviderWithResolver(IWorkflowDefinitions, [], (resolver) => resolver.resolve(WorkflowDefinitions))),
-    DI.singleton(DI.factoryProviderWithResolver(HOSTED_SERVICE, [], (resolver) => new CodeProcessPublisher(resolver.resolve(SERVICE_PROVIDER)))),
+    singleton(WorkflowClock, SystemWorkflowClock),
+    singleton(WorkflowTools),
+    singleton(CodeProcessCatalog),
+    scoped(IWorkflowDefinitions, WorkflowDefinitions),
+    scoped(ProcessReferences),
+    singleton(HOSTED_SERVICE, CodeProcessPublisher),
   ],
-  controllers: [DI.bindDeps(ProcessesController, IWorkflowDefinitions)],
+  controllers: [ProcessesController],
   exports: [IWorkflowDefinitions, WorkflowTools, WorkflowClock],
 })
 export class WorkflowDefinitionsModule {}

package/core/workflow/definitions_module/access/Definitions.permissions.ts

@@ -0,0 +1,23 @@
+import { definePermissions } from "../../../access";
+
+const process = { ref: "workflow.process", column: "key" };
+
+/**
+ * The rights of the process catalog (WORKFLOW-002 §6.2). A process is one per
+ * application, so these have no partition until `WorkflowPartitions` connects
+ * processes to partitions (stage 4).
+ */
+export const definitionsPermissions = definePermissions({
+  "workflow.processes.read": {
+    title: { en: "See processes", ru: "Видеть процессы" },
+    on: { process },
+  },
+  "workflow.processes.manage": {
+    title: { en: "Edit processes", ru: "Редактировать процессы" },
+    on: { process },
+  },
+  "workflow.processes.publish": {
+    title: { en: "Publish processes", ru: "Публиковать процессы" },
+    on: { process },
+  },
+});

package/core/workflow/definitions_module/access/Process.references.ts

@@ -0,0 +1,27 @@
+import { References, type ReferenceItem, type ReferencePage } from "../../../access";
+import type { DefinitionsDbContext } from "../model/Definitions.dbContext";
+
+/** Reference kind `workflow.process`: what an administrator picks in a condition. */
+export class ProcessReferences extends References {
+  constructor(private readonly db: DefinitionsDbContext) {
+    super();
+  }
+
+  async exists(ids: readonly string[]): Promise<ReadonlySet<string>> {
+    return new Set((await this.describe(ids)).map((item) => item.id));
+  }
+
+  async describe(ids: readonly string[]): Promise<readonly ReferenceItem[]> {
+    if (ids.length === 0) return [];
+    const rows = await this.db.processes.asNoTracking().where((p) => p.key.in([...ids])).toList();
+    return rows.map((row) => ({ id: row.key, title: row.title }));
+  }
+
+  async search(text: string, _context: unknown, page: ReferencePage): Promise<readonly ReferenceItem[]> {
+    const found = text.trim();
+    let source = this.db.processes.asNoTracking();
+    if (found !== "") source = source.where((p) => p.key.contains(found, { ignoreCase: true }).or(p.title.contains(found, { ignoreCase: true })));
+    const rows = await source.orderBy((p) => p.key).skip(page.offset).take(page.limit).toList();
+    return rows.map((row) => ({ id: row.key, title: row.title }));
+  }
+}

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

@@ -1,11 +1,12 @@
-import type { OwnedCodeProcess } from "./codeProcesses";
+import type { ServiceProvider } from "../../../di";
+import { codeProcessesOf, type OwnedCodeProcess } from "./codeProcesses";
 
 /** The processes declared in the application's modules, by key: which module owns a key. */
 export class CodeProcessCatalog {
   private readonly byKey: ReadonlyMap<string, OwnedCodeProcess>;
 
-  constructor(entries: readonly OwnedCodeProcess[]) {
-    this.byKey = new Map([...entries].sort((a, b) => a.process.key.localeCompare(b.process.key)).map((entry) => [entry.process.key, entry]));
+  constructor(services: ServiceProvider) {
+    this.byKey = new Map([...codeProcessesOf(services)].sort((a, b) => a.process.key.localeCompare(b.process.key)).map((entry) => [entry.process.key, entry]));
   }
 
   /** The module whose `processes` declare `key`; `undefined` for a process of the catalog. */

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

@@ -2,7 +2,7 @@ import { markConfigurationError, type ServiceProvider } from "../../../di";
 import type { HostedService } from "../../../di/extensions/hosted-service";
 import { LOGGER } from "../../../kernel";
 import { WorkflowTools } from "../../internal/WorkflowTools";
-import { WorkflowDefinitions } from "../services/WorkflowDefinitions.service";
+import { IWorkflowDefinitions } from "../services/IWorkflowDefinitions.service";
 import { CodeProcessCatalog } from "./CodeProcessCatalog";
 import { definitionProblems, WorkflowSetupError } from "./codeProcesses";
 
@@ -30,7 +30,7 @@ export class CodeProcessPublisher implements HostedService {
     }
     const scope = this.services.createScope();
     try {
-      const results = await scope.resolve(WorkflowDefinitions).publishCode(entries);
+      const results = await scope.resolve(IWorkflowDefinitions).publishCode(entries);
       this.services.tryResolve(LOGGER)?.info("workflow processes from code", {
         published: results.filter((result) => result.published).map((result) => `${result.key} v${result.version}`),
         unchanged: results.filter((result) => !result.published).map((result) => result.key),

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

@@ -1,28 +1,31 @@
 import { contextOnlyController } from "../../../http/Routing/contextOnlyControllers";
-import { Controller, Created, Get, Patch, Post, Put, type HttpContext } from "../../../http";
-import { authorize, body, optionalInteger, optionalString, pagingQuery, param, requiredString } from "../../internal/http";
+import { can } from "../../../access";
+import { Authorize, Controller, Created, Get, Patch, Post, Put, type HttpContext } from "../../../http";
+import { body, callerOf, optionalInteger, optionalString, pagingQuery, param, requiredString } from "../../internal/http";
 import { WorkflowError } from "../../contracts/WorkflowError";
 import { IWorkflowDefinitions } from "../services/IWorkflowDefinitions.service";
 
-/** The process catalog over HTTP (WORKFLOW-001 §3); rights come from `WorkflowAccess`. */
+/** The process catalog over HTTP (WORKFLOW-001 §3); rights are `workflow.processes.*` (WORKFLOW-002 §6.2). */
 @Controller("workflow")
 export class ProcessesController {
   constructor(private readonly definitions: IWorkflowDefinitions) {}
 
   @Get("processes")
+  @Authorize(can("workflow.processes.read"))
   async list(ctx: HttpContext) {
-    await authorize(ctx, "processes.read");
+    const { access } = await callerOf(ctx);
     const archived = ctx.query("archived");
     if (archived !== undefined && archived !== "true" && archived !== "false") throw new WorkflowError("invalid_input", "archived must be true or false");
-    const page = await this.definitions.list({ ...pagingQuery(ctx), archived: archived === undefined ? undefined : archived === "true", search: optionalString(ctx.query("search"), "search") });
+    const page = await this.definitions.list({ ...pagingQuery(ctx), access: await access.filter("workflow.processes.read"), archived: archived === undefined ? undefined : archived === "true", search: optionalString(ctx.query("search"), "search") });
     return { data: page.items, meta: { total: page.total } };
   }
 
   @Post("processes")
+  @Authorize(can("workflow.processes.manage"))
   async create(ctx: HttpContext) {
     const request = await body(ctx);
     const key = requiredString(request.key, "key", 64);
-    const actor = await authorize(ctx, "processes.manage", { processKey: key });
+    const { actor } = await callerOf(ctx, "workflow.processes.manage", { process: key });
     const process = await this.definitions.create({
       key,
       title: requiredString(request.title, "title"),
@@ -33,17 +36,19 @@ export class ProcessesController {
   }
 
   @Get("processes/:key")
+  @Authorize(can("workflow.processes.read"))
   async get(ctx: HttpContext) {
     const key = param(ctx, "key");
-    await authorize(ctx, "processes.read", { processKey: key });
+    await callerOf(ctx, "workflow.processes.read", { process: key });
     return await this.definitions.get(key);
   }
 
   @Patch("processes/:key")
+  @Authorize(can("workflow.processes.manage"))
   async update(ctx: HttpContext) {
     const key = param(ctx, "key");
     const request = await body(ctx);
-    const actor = await authorize(ctx, "processes.manage", { processKey: key });
+    const { actor } = await callerOf(ctx, "workflow.processes.manage", { process: key });
     if (request.archived !== undefined && typeof request.archived !== "boolean") throw new WorkflowError("invalid_input", "archived must be a boolean");
     return await this.definitions.update(key, {
       ...(request.title === undefined ? {} : { title: requiredString(request.title, "title") }),
@@ -54,40 +59,44 @@ export class ProcessesController {
   }
 
   @Put("processes/:key/draft")
+  @Authorize(can("workflow.processes.manage"))
   async saveDraft(ctx: HttpContext) {
     const key = param(ctx, "key");
     const request = await body(ctx);
-    const actor = await authorize(ctx, "processes.manage", { processKey: key });
+    const { actor } = await callerOf(ctx, "workflow.processes.manage", { process: key });
     return await this.definitions.saveDraft(key, request.document, actor);
   }
 
   @Post("processes/:key/publish")
+  @Authorize(can("workflow.processes.publish"))
   async publish(ctx: HttpContext) {
     const key = param(ctx, "key");
-    const actor = await authorize(ctx, "processes.publish", { processKey: key });
+    const { actor } = await callerOf(ctx, "workflow.processes.publish", { process: key });
     const version = await this.definitions.publish(key, actor);
     return Created(`${ctx.path.replace(/\/publish$/, "")}/versions/${version.version}`, version);
   }
 
   @Get("processes/:key/versions")
+  @Authorize(can("workflow.processes.read"))
   async versions(ctx: HttpContext) {
     const key = param(ctx, "key");
-    await authorize(ctx, "processes.read", { processKey: key });
+    await callerOf(ctx, "workflow.processes.read", { process: key });
     return { data: await this.definitions.versions(key) };
   }
 
   @Get("processes/:key/versions/:version")
+  @Authorize(can("workflow.processes.read"))
   async version(ctx: HttpContext) {
     const key = param(ctx, "key");
-    await authorize(ctx, "processes.read", { processKey: key });
+    await callerOf(ctx, "workflow.processes.read", { process: key });
     const version = optionalInteger(param(ctx, "version"), "version");
     if (version === undefined) throw new WorkflowError("invalid_input", "version must be an integer");
     return await this.definitions.version(key, version);
   }
 
   @Get("tools")
-  async tools(ctx: HttpContext) {
-    await authorize(ctx, "processes.read");
+  @Authorize(can("workflow.processes.read"))
+  async tools() {
     return { data: this.definitions.tools() };
   }
 }

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

@@ -1,6 +1,8 @@
+import type { AccessFilter } from "../../../access";
 import type { AgentToolContract } from "../../../agent";
 import type { ProcessDocument, ProcessIssue } from "../../../../library/workflow";
 import type { WorkflowActor, WorkflowPage, WorkflowPaging } from "../../contracts/types";
+import type { OwnedCodeProcess } from "../code/codeProcesses";
 
 export interface ProcessSummary {
   readonly key: string;
@@ -52,6 +54,8 @@ export interface UpdateProcess {
 }
 
 export interface ProcessListQuery extends WorkflowPaging {
+  /** Which processes the caller may see, from `IAccess`; without it the calling code has decided. */
+  readonly access?: AccessFilter;
   readonly archived?: boolean;
   /** Part of the key or title, case-insensitive. */
   readonly search?: string;
@@ -87,4 +91,9 @@ export abstract class IWorkflowDefinitions {
   abstract retentionPolicies(): Promise<readonly { readonly key: string; readonly retentionDays: number }[]>;
   /** The Tools a service task may call, with their input and output schemas. */
   abstract tools(): readonly AgentToolContract[];
+  /**
+   * Publishes the processes of `@Module({ processes })` as `{ kind: "system", id: "code" }`
+   * (WORKFLOW-001 §14): called once at start by the framework, not by the application.
+   */
+  abstract publishCode(entries: readonly OwnedCodeProcess[]): Promise<readonly { readonly key: string; readonly version: number | null; readonly published: boolean }[]>;
 }

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

@@ -1,3 +1,4 @@
+import { grantsToWhere } from "../../../access";
 import { createHash } from "node:crypto";
 import { UniqueViolationError } from "../../../orm";
 import type { AgentToolContract } from "../../../agent";
@@ -38,7 +39,10 @@ export class WorkflowDefinitions extends IWorkflowDefinitions {
 
   async list(query: ProcessListQuery = {}): Promise<WorkflowPage<ProcessSummary>> {
     const { limit, offset } = pagingOf(query);
+    const where = query.access === undefined ? "all" : grantsToWhere(query.access);
+    if (where === "none") return { items: [], total: 0 };
     let source = this.db.processes.asNoTracking();
+    if (where !== "all") source = source.where(() => where);
     if (query.archived === true) source = source.where((p) => p.archivedAt.isNotNull());
     if (query.archived === false) source = source.where((p) => p.archivedAt.isNull());
     if (query.search !== undefined && query.search.trim() !== "") {

package/core/workflow/generated/deps.ts

@@ -0,0 +1,56 @@
+// This file is auto-generated by `bun run di:generate` (framework.packs of bazis.config.json).
+// Do not edit manually.
+import { registerFrameworkClassDeps } from "../../di/module/autoDeps";
+import { DbContextOptions } from "../../../library/orm/DbContextOptions";
+import { ServiceProvider } from "../../di/ServiceProvider";
+import { EventBus } from "../../kernel/events/EventBus";
+import { WorkflowClock } from "../contracts/WorkflowClock";
+import { ProcessReferences } from "../definitions_module/access/Process.references";
+import { CodeProcessCatalog } from "../definitions_module/code/CodeProcessCatalog";
+import { CodeProcessPublisher } from "../definitions_module/code/CodeProcessPublisher";
+import { ProcessesController } from "../definitions_module/http/Processes.controller";
+import { DefinitionsDbContext } from "../definitions_module/model/Definitions.dbContext";
+import { IWorkflowDefinitions } from "../definitions_module/services/IWorkflowDefinitions.service";
+import { WorkflowDefinitions } from "../definitions_module/services/WorkflowDefinitions.service";
+import { WorkflowTools } from "../internal/WorkflowTools";
+import { WorkflowRetention } from "../runtime_module/background/WorkflowRetention";
+import { WorkflowWorker } from "../runtime_module/background/WorkflowWorker";
+import { EventsController } from "../runtime_module/http/Events.controller";
+import { InstancesController } from "../runtime_module/http/Instances.controller";
+import { GraphCache } from "../runtime_module/internal/GraphCache";
+import { Schedules } from "../runtime_module/internal/Schedules";
+import { TimerStep } from "../runtime_module/internal/TimerStep";
+import { ToolStep } from "../runtime_module/internal/ToolStep";
+import { WorkflowEngine } from "../runtime_module/internal/WorkflowEngine";
+import { RuntimeDbContext } from "../runtime_module/model/Runtime.dbContext";
+import { IWorkflowRuntime } from "../runtime_module/services/IWorkflowRuntime.service";
+import { WorkflowRuntime } from "../runtime_module/services/WorkflowRuntime.service";
+import { TaskEvents } from "../tasks_module/events/TaskEvents";
+import { TasksController } from "../tasks_module/http/Tasks.controller";
+import { TasksDbContext } from "../tasks_module/model/Tasks.dbContext";
+import { IWorkflowTasks } from "../tasks_module/services/IWorkflowTasks.service";
+import { WorkflowTasks } from "../tasks_module/services/WorkflowTasks.service";
+
+registerFrameworkClassDeps([
+  [CodeProcessCatalog, [ServiceProvider]],
+  [CodeProcessPublisher, [ServiceProvider]],
+  [DefinitionsDbContext, [DbContextOptions]],
+  [EventsController, [IWorkflowRuntime]],
+  [InstancesController, [IWorkflowRuntime]],
+  [ProcessesController, [IWorkflowDefinitions]],
+  [ProcessReferences, [DefinitionsDbContext]],
+  [RuntimeDbContext, [DbContextOptions]],
+  [Schedules, [RuntimeDbContext, WorkflowEngine, IWorkflowDefinitions]],
+  [TaskEvents, [TasksDbContext]],
+  [TasksController, [IWorkflowTasks]],
+  [TasksDbContext, [DbContextOptions]],
+  [TimerStep, [RuntimeDbContext, WorkflowEngine]],
+  [ToolStep, [RuntimeDbContext, WorkflowEngine, WorkflowTools]],
+  [WorkflowDefinitions, [DefinitionsDbContext, WorkflowTools, CodeProcessCatalog, WorkflowClock]],
+  [WorkflowEngine, [RuntimeDbContext, IWorkflowDefinitions, GraphCache, EventBus, ServiceProvider, WorkflowClock, "optional:Logger"]],
+  [WorkflowRetention, [ServiceProvider, "Config:workflow"]],
+  [WorkflowRuntime, [RuntimeDbContext, WorkflowEngine, IWorkflowDefinitions, ServiceProvider]],
+  [WorkflowTasks, [TasksDbContext, IWorkflowRuntime, WorkflowClock]],
+  [WorkflowTools, [ServiceProvider]],
+  [WorkflowWorker, [ServiceProvider, "Config:workflow"]],
+]);