bazis 0.123.0 → 0.124.0

package/core/agent/index.ts

@@ -87,6 +87,7 @@ export {
   toolMetadataOf,
   type ToolApproval,
   type ToolMetadata,
+  type ToolActor,
   type ToolOptions,
   type ToolSideEffect,
 } from "./metadata";

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.123.0" }, capabilities: { experimentalApi: true },
+        clientInfo: { name: "bazis", title: "Bazis", version: "0.124.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/workflow/Workflow.module.ts

@@ -0,0 +1,15 @@
+import { Module } from "../di";
+import { WorkflowDefinitionsModule } from "./definitions_module/WorkflowDefinitions.module";
+import { IWorkflowDefinitions } from "./definitions_module/services/IWorkflowDefinitions.service";
+import { WorkflowRuntimeModule } from "./runtime_module/WorkflowRuntime.module";
+import { IWorkflowRuntime } from "./runtime_module/services/IWorkflowRuntime.service";
+
+/**
+ * Business processes (WORKFLOW-001): the pack only assembles its parts
+ * ([passport](MODULE.md)). An application imports it, or only the parts it needs.
+ */
+@Module({
+  imports: [WorkflowDefinitionsModule, WorkflowRuntimeModule],
+  exports: [IWorkflowDefinitions, IWorkflowRuntime],
+})
+export class WorkflowModule {}

package/core/workflow/access/WorkflowAccess.ts

@@ -0,0 +1,52 @@
+import type { HttpContext } from "../../http";
+import type { WorkflowActor } from "../contracts/types";
+
+export type WorkflowAction =
+  | "processes.read"
+  | "processes.manage"
+  | "processes.publish"
+  | "instances.start"
+  | "instances.read"
+  | "instances.manage"
+  | "events.emit"
+  | "tasks.work";
+
+/** What an action is about; the fields known for the route. */
+export interface WorkflowAccessTarget {
+  readonly processKey?: string;
+  readonly partition?: string | null;
+  readonly instanceId?: string;
+  readonly taskId?: string;
+}
+
+/**
+ * Rights and identity of the workflow HTTP (WORKFLOW-001 §6). The framework's
+ * controllers do not know how the application signs people in, so they ask this
+ * port. It is the DI token too: register the application's implementation in any
+ * module, `DI.singleton(DI.classProvider(WorkflowAccess, AppWorkflowAccess))`.
+ * Without one every workflow route answers 403. The services never ask it: the
+ * application's code that calls them decides itself.
+ */
+export abstract class WorkflowAccess {
+  /** Who makes the request; `undefined` answers 401. */
+  abstract actor(ctx: HttpContext): WorkflowActor | undefined | Promise<WorkflowActor | undefined>;
+
+  /** Whether the actor may do `action` on `target`; `false` answers 403. */
+  abstract can(ctx: HttpContext, action: WorkflowAction, target: WorkflowAccessTarget): boolean | Promise<boolean>;
+
+  /** Whom the user's tasks are addressed to: `user:<id>`, `role:<code>`. */
+  assignees(_ctx: HttpContext, actor: WorkflowActor): readonly string[] | Promise<readonly string[]> {
+    return [`user:${actor.id}`];
+  }
+}
+
+/** The default: nothing is allowed until the application says otherwise. */
+export class DenyWorkflowAccess extends WorkflowAccess {
+  actor(): undefined {
+    return undefined;
+  }
+
+  can(): boolean {
+    return false;
+  }
+}

package/core/workflow/contracts/WorkflowError.ts

@@ -0,0 +1,28 @@
+import { HttpError } from "../../http";
+import type { FormIssue, ProcessIssue } from "../../../library/workflow";
+
+export type WorkflowErrorCode = "not_found" | "conflict" | "wrong_status" | "invalid_document" | "invalid_input" | "archived";
+
+const STATUS: Readonly<Record<WorkflowErrorCode, number>> = {
+  not_found: 404,
+  conflict: 409,
+  wrong_status: 409,
+  archived: 409,
+  invalid_document: 422,
+  invalid_input: 422,
+};
+
+/**
+ * An error of the workflow services. Code and HTTP status in one: the
+ * framework's controllers throw it as is, the response is
+ * `{ error, details: { code, issues? } }`.
+ */
+export class WorkflowError extends HttpError {
+  constructor(
+    readonly code: WorkflowErrorCode,
+    message: string,
+    readonly issues?: readonly (ProcessIssue | FormIssue)[],
+  ) {
+    super(STATUS[code], message, issues === undefined ? { code } : { code, issues });
+  }
+}

package/core/workflow/contracts/WorkflowInputValidator.ts

@@ -0,0 +1,24 @@
+import { validateForm, type FormIssue, type FormSpec } from "../../../library/workflow";
+
+/** What a value is checked for: a process input or a task form. */
+export interface WorkflowInputContext {
+  readonly purpose: "input" | "task";
+  readonly processKey: string;
+  readonly partition: string | null;
+}
+
+/**
+ * Checks a process input and task forms against their fields (WORKFLOW-001 §9).
+ * The default checks the types of `bazis.workflow/v1`; an application with its
+ * own field rules registers its implementation of this class in any module.
+ */
+export abstract class WorkflowInputValidator {
+  abstract validate(spec: FormSpec | undefined, value: unknown, context: WorkflowInputContext): { readonly value: Record<string, unknown>; readonly issues: readonly FormIssue[] } | Promise<{ readonly value: Record<string, unknown>; readonly issues: readonly FormIssue[] }>;
+}
+
+/** The built-in field check. */
+export class DefaultWorkflowInputValidator extends WorkflowInputValidator {
+  validate(spec: FormSpec | undefined, value: unknown): { readonly value: Record<string, unknown>; readonly issues: readonly FormIssue[] } {
+    return validateForm(spec, value);
+  }
+}

package/core/workflow/contracts/types.ts

@@ -0,0 +1,30 @@
+/** Who acts: a user or the system (schedules, events). Steps of an instance run on behalf of who started it. */
+export interface WorkflowActor {
+  readonly kind: "user" | "system";
+  readonly id: string;
+}
+
+/** A page of a list. */
+export interface WorkflowPage<T> {
+  readonly items: readonly T[];
+  readonly total: number;
+}
+
+/** Paging of the list operations: `limit` 1–200 (50 by default), `offset` from 0. */
+export interface WorkflowPaging {
+  readonly limit?: number;
+  readonly offset?: number;
+}
+
+export function pagingOf(paging: WorkflowPaging): { readonly limit: number; readonly offset: number } {
+  const limit = paging.limit === undefined ? 50 : Math.trunc(paging.limit);
+  const offset = paging.offset === undefined ? 0 : Math.trunc(paging.offset);
+  return { limit: Number.isFinite(limit) ? Math.min(Math.max(limit, 1), 200) : 50, offset: Number.isFinite(offset) ? Math.max(offset, 0) : 0 };
+}
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/** Whether an id can be a row key; anything else would reach PostgreSQL as an invalid uuid. */
+export function isUuid(value: unknown): value is string {
+  return typeof value === "string" && UUID.test(value);
+}

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

@@ -0,0 +1,24 @@
+import { DI, Module, SERVICE_PROVIDER, scoped } from "../../di";
+import { WorkflowTools } from "../internal/WorkflowTools";
+import { ProcessesController } from "./http/Processes.controller";
+import { DefinitionsDbContext, definitionsStore } from "./model/Definitions.dbContext";
+import { WfProcess } from "./model/WfProcess.model";
+import { WfVersion } from "./model/WfVersion.model";
+import { IWorkflowDefinitions } from "./services/IWorkflowDefinitions.service";
+import { WorkflowDefinitions } from "./services/WorkflowDefinitions.service";
+
+/**
+ * The process catalog: drafts and published versions ([passport](MODULE.md)).
+ * Dependencies are explicit: the framework's classes are not covered by the
+ * application's codegen.
+ */
+@Module({
+  ormBazis: { context: DefinitionsDbContext, entities: [WfProcess, WfVersion], ownedStore: definitionsStore, registerRepositories: false },
+  providers: [
+    DI.singleton(DI.factoryProviderWithResolver(WorkflowTools, [], (resolver) => new WorkflowTools(resolver.resolve(SERVICE_PROVIDER)))),
+    scoped(IWorkflowDefinitions, WorkflowDefinitions, [DefinitionsDbContext, WorkflowTools] as const),
+  ],
+  controllers: [DI.bindDeps(ProcessesController, IWorkflowDefinitions)],
+  exports: [IWorkflowDefinitions, WorkflowTools],
+})
+export class WorkflowDefinitionsModule {}

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

@@ -0,0 +1,92 @@
+import { Controller, Created, Get, Patch, Post, Put, type HttpContext } from "../../../http";
+import { authorize, body, 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`. */
+@Controller("workflow")
+export class ProcessesController {
+  constructor(private readonly definitions: IWorkflowDefinitions) {}
+
+  @Get("processes")
+  async list(ctx: HttpContext) {
+    await authorize(ctx, "processes.read");
+    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") });
+    return { data: page.items, meta: { total: page.total } };
+  }
+
+  @Post("processes")
+  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 process = await this.definitions.create({
+      key,
+      title: requiredString(request.title, "title"),
+      description: optionalString(request.description, "description", 2000) ?? null,
+      retentionDays: optionalInteger(request.retentionDays, "retentionDays") ?? null,
+    }, actor);
+    return Created(`${ctx.path}/${process.key}`, process);
+  }
+
+  @Get("processes/:key")
+  async get(ctx: HttpContext) {
+    const key = param(ctx, "key");
+    await authorize(ctx, "processes.read", { processKey: key });
+    return await this.definitions.get(key);
+  }
+
+  @Patch("processes/:key")
+  async update(ctx: HttpContext) {
+    const key = param(ctx, "key");
+    const request = await body(ctx);
+    const actor = await authorize(ctx, "processes.manage", { processKey: 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") }),
+      ...(request.description === undefined ? {} : { description: optionalString(request.description, "description", 2000) ?? null }),
+      ...(request.retentionDays === undefined ? {} : { retentionDays: optionalInteger(request.retentionDays, "retentionDays") ?? null }),
+      ...(request.archived === undefined ? {} : { archived: request.archived as boolean }),
+    }, actor);
+  }
+
+  @Put("processes/:key/draft")
+  async saveDraft(ctx: HttpContext) {
+    const key = param(ctx, "key");
+    const request = await body(ctx);
+    const actor = await authorize(ctx, "processes.manage", { processKey: key });
+    return await this.definitions.saveDraft(key, request.document, actor);
+  }
+
+  @Post("processes/:key/publish")
+  async publish(ctx: HttpContext) {
+    const key = param(ctx, "key");
+    const actor = await authorize(ctx, "processes.publish", { processKey: key });
+    const version = await this.definitions.publish(key, actor);
+    return Created(`${ctx.path.replace(/\/publish$/, "")}/versions/${version.version}`, version);
+  }
+
+  @Get("processes/:key/versions")
+  async versions(ctx: HttpContext) {
+    const key = param(ctx, "key");
+    await authorize(ctx, "processes.read", { processKey: key });
+    return { data: await this.definitions.versions(key) };
+  }
+
+  @Get("processes/:key/versions/:version")
+  async version(ctx: HttpContext) {
+    const key = param(ctx, "key");
+    await authorize(ctx, "processes.read", { processKey: 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");
+    return { data: this.definitions.tools() };
+  }
+}

package/core/workflow/definitions_module/model/Definitions.dbContext.ts

@@ -0,0 +1,16 @@
+import { DbContext, defineOrmOwnedStoreV1 } from "../../../orm";
+import { WfProcess } from "./WfProcess.model";
+import { WfVersion } from "./WfVersion.model";
+
+export class DefinitionsDbContext extends DbContext {
+  readonly processes = this.set(WfProcess);
+  readonly versions = this.set(WfVersion);
+}
+
+/** The tables of the Definitions part: bazis creates and checks them in the application database. */
+export const definitionsStore = defineOrmOwnedStoreV1({
+  contract: "bazis.orm-owned-store/v1",
+  storeKey: "bazis.workflow.definitions",
+  formatVersion: 1,
+  ownedScope: { schema: "public", tablePrefix: "bazis_wf_def_" },
+});

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

@@ -0,0 +1,52 @@
+import { Column, Entity, Index, UUID } from "../../../orm";
+
+/**
+ * A process in the catalog: the key it is started by, its names, the draft a
+ * designer edits and the retention of finished instances. Changes; the
+ * published versions ({@link WfVersion}) do not.
+ */
+@Entity({ table: "bazis_wf_def_processes" })
+export class WfProcess {
+  @UUID({ version: "v7" })
+  id = "";
+
+  @Index({ unique: true })
+  @Column({ type: "text" })
+  key = "";
+
+  @Column({ type: "text" })
+  title = "";
+
+  @Column({ type: "text", nullable: true })
+  description: string | null = null;
+
+  /** The draft document; kept with validation errors too. */
+  @Column({ type: "json", nullable: true })
+  draft: unknown = null;
+
+  @Column({ type: "datetime", nullable: true })
+  draftUpdatedAt: Date | null = null;
+
+  @Column({ type: "text", nullable: true })
+  draftUpdatedByKind: string | null = null;
+
+  @Column({ type: "text", nullable: true })
+  draftUpdatedById: string | null = null;
+
+  @Column({ type: "integer", nullable: true })
+  latestVersion: number | null = null;
+
+  /** Days to keep completed and cancelled instances; `null` keeps them. */
+  @Column({ type: "integer", nullable: true })
+  retentionDays: number | null = null;
+
+  /** An archived process is not started. */
+  @Column({ type: "datetime", nullable: true })
+  archivedAt: Date | null = null;
+
+  @Column({ type: "createdAt" })
+  createdAt = new Date(0);
+
+  @Column({ type: "updatedAt" })
+  updatedAt = new Date(0);
+}

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

@@ -0,0 +1,33 @@
+import { Column, Entity, ForeignKey, Index, UUID } from "../../../orm";
+import { WfProcess } from "./WfProcess.model";
+
+/** A published version of a process: an immutable snapshot of its document. */
+@ForeignKey(() => WfProcess, { properties: ["processId"], onDelete: "cascade" })
+@Index(["processId", "version"], { unique: true })
+@Entity({ table: "bazis_wf_def_versions" })
+export class WfVersion {
+  @UUID({ version: "v7" })
+  id = "";
+
+  @Column({ type: "uuid" })
+  processId = "";
+
+  @Column({ type: "integer" })
+  version = 0;
+
+  @Column({ type: "json" })
+  document: unknown = null;
+
+  /** sha-256 of the document: publishing the same document again adds no version. */
+  @Column({ type: "text" })
+  documentHash = "";
+
+  @Column({ type: "createdAt" })
+  publishedAt = new Date(0);
+
+  @Column({ type: "text" })
+  publishedByKind = "";
+
+  @Column({ type: "text" })
+  publishedById = "";
+}

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

@@ -0,0 +1,79 @@
+import type { AgentToolContract } from "../../../agent";
+import type { ProcessDocument, ProcessIssue } from "../../../../library/workflow";
+import type { WorkflowActor, WorkflowPage, WorkflowPaging } from "../../contracts/types";
+
+export interface ProcessSummary {
+  readonly key: string;
+  readonly title: string;
+  readonly description: string | null;
+  readonly latestVersion: number | null;
+  readonly retentionDays: number | null;
+  readonly archived: boolean;
+  readonly createdAt: Date;
+  readonly updatedAt: Date;
+}
+
+export interface ProcessDetails extends ProcessSummary {
+  /** The draft a designer edits; may hold validation errors. */
+  readonly draft: unknown;
+  readonly draftUpdatedAt: Date | null;
+  readonly draftUpdatedBy: WorkflowActor | null;
+}
+
+export interface VersionSummary {
+  readonly id: string;
+  readonly key: string;
+  readonly version: number;
+  readonly publishedAt: Date;
+  readonly publishedBy: WorkflowActor;
+}
+
+export interface VersionDetails extends VersionSummary {
+  readonly document: ProcessDocument;
+}
+
+export interface CreateProcess {
+  readonly key: string;
+  readonly title: string;
+  readonly description?: string | null;
+  readonly retentionDays?: number | null;
+}
+
+export interface UpdateProcess {
+  readonly title?: string;
+  readonly description?: string | null;
+  readonly retentionDays?: number | null;
+  readonly archived?: boolean;
+}
+
+export interface ProcessListQuery extends WorkflowPaging {
+  readonly archived?: boolean;
+  /** Part of the key or title, case-insensitive. */
+  readonly search?: string;
+}
+
+/**
+ * The process catalog: drafts and immutable published versions
+ * (WORKFLOW-001 §3). Errors are {@link WorkflowError}: `not_found`, `conflict`,
+ * `invalid_document` with the issues, `invalid_input`.
+ */
+export abstract class IWorkflowDefinitions {
+  abstract list(query?: ProcessListQuery): Promise<WorkflowPage<ProcessSummary>>;
+  abstract get(key: string): Promise<ProcessDetails>;
+  abstract create(process: CreateProcess, actor: WorkflowActor): Promise<ProcessDetails>;
+  abstract update(key: string, changes: UpdateProcess, actor: WorkflowActor): Promise<ProcessDetails>;
+  /** Stores the draft even with errors and returns every validation finding. */
+  abstract saveDraft(key: string, document: unknown, actor: WorkflowActor): Promise<{ readonly issues: readonly ProcessIssue[] }>;
+  /** Validates the draft and stores it as the next version; the same document again returns the latest version. */
+  abstract publish(key: string, actor: WorkflowActor): Promise<VersionDetails>;
+  abstract versions(key: string): Promise<readonly VersionSummary[]>;
+  abstract version(key: string, version: number): Promise<VersionDetails>;
+  /** The latest published version of a process that is not archived. */
+  abstract latest(key: string): Promise<VersionDetails>;
+  /** A version by id, for the engine; `undefined` if there is none. */
+  abstract versionById(id: string): Promise<VersionDetails | undefined>;
+  /** 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. */
+  abstract tools(): readonly AgentToolContract[];
+}