@sanoma-ai/workflows 0.1.0 → 0.4.0

package/src/approvals.ts

@@ -1,12 +1,13 @@
 import { DBOS } from "@dbos-inc/dbos-sdk";
 import { z } from "zod";
-import { type ApprovalRequest, type ApprovalResult, type ApprovalState, notApprover, Principal } from "./define.ts";
+import { type ApprovalRequest, type ApprovalResult, type ApprovalState, Principal } from "./define.ts";
 import { RejectedError } from "./errors.ts";
 import { entry, write } from "./ledger.ts";
 import { warn } from "./log.ts";
 import type { Placed } from "./call.ts";
 import type { Run } from "./run.ts";
-import { approverLabel, mayDecide } from "./shared.ts";
+import { readPeople } from "./resources.ts";
+import { approverLabel, OWN_CHANGE, refusalOf } from "./shared.ts";
 
 // The wire contract between a run waiting on approvals and whoever decides them. The client
 // imports this file and never the worker's.
@@ -50,23 +51,28 @@ export interface CheckedApproval extends Omit<ApprovalRequest, "covers"> {
   covers: string[];
 }
 
-/** A policy's hold: the call held, and the ledger `seq` its `op.called` record takes. */
+/**
+ * A policy's hold: the call held (an operation, or `workflow:<name>` for a run's start), the
+ * ledger `seq` its `op.called` record takes (a start has none), and the rules that held it.
+ */
 export interface HeldCall {
   op: string;
-  seq: number;
+  seq?: number;
   input: unknown;
+  reasons?: string[] | undefined;
 }
 
 /**
- * Waits, durably, for a decision from someone who may make it. Throws `RejectedError` on a
- * rejection. Without `held`, the workflow asked (`ctx.approval`); with it, the policy did, and
- * `place` is the held call's outline node and name.
+ * Waits, durably, for a decision from someone who may make it (`mayDecide`: the run's own actor
+ * only while nobody else could). Throws `RejectedError` on a rejection. Without `held`, the workflow asked
+ * (`ctx.approval`); with it, the policy did, and `place` is the held call's outline node and name
+ * (none for a run's start, which is no call in the outline).
  */
 export async function awaitApproval(
   run: Run,
   title: string,
   req: CheckedApproval,
-  place: Placed,
+  place: Placed | undefined,
   held?: HeldCall,
 ): Promise<ApprovalResult> {
   const { covers } = req;
@@ -79,7 +85,7 @@ export async function awaitApproval(
     ...(req.details === undefined ? {} : { details: req.details }),
     requestedBy: held ? "policy" : "workflow",
     covers,
-    ...(held ? { op: held.op, opSeq: held.seq, input: held.input } : {}),
+    ...(held && { op: held.op, ...heldOf(held), input: held.input }),
     status: "pending",
     requestedAt: 0,
     refused: [],
@@ -99,7 +105,7 @@ export async function awaitApproval(
         approver: state.approver,
         requestedBy: state.requestedBy,
         covers,
-        ...(held ? { op: held.op, opSeq: held.seq } : {}),
+        ...(held && { op: held.op, ...heldOf(held) }),
       },
       { key: state.id, at: state.requestedAt },
     ),
@@ -113,9 +119,23 @@ export async function awaitApproval(
     const at = await DBOS.now();
     const parsed = ApprovalMessage.safeParse(raw);
     const msg = parsed.success ? parsed.data : undefined;
-    if (!msg || !mayDecide(state, msg.by)) {
+    // The people matter only when the run's own actor decides (`refusalOf`): then they are read as
+    // the data files declare them now, in a step, so a replay decides the same. While those files
+    // have problems, someone else may be missing from them, so the starter is refused.
+    const refusal = !msg
+      ? null
+      : msg.by.id === run.actor.id
+        ? await DBOS.runStep(
+            async () => {
+              const { people, problems } = readPeople(run.state.root);
+              return refusalOf(state, msg.by, run, people) ?? (problems.length ? OWN_CHANGE : null);
+            },
+            { name: `decider:${state.id}` },
+          )
+        : (refusalOf(state, msg.by, run, []) ?? null);
+    if (!msg || refusal !== null) {
       const by = msg?.by.id ?? senderOf(raw);
-      const reason = msg ? notApprover(state, msg.by) : "not a valid decision message";
+      const reason = refusal ?? "not a valid decision message";
       state.refused.push({
         ...(by === undefined ? {} : { by }),
         ...(msg?.id === undefined ? {} : { id: msg.id }),
@@ -133,12 +153,15 @@ export async function awaitApproval(
       );
       continue;
     }
+    // The run's own actor decides only when nobody else could, which the record says.
+    const alone = msg.by.id === run.actor.id ? { alone: true as const } : {};
     Object.assign(state, {
       status: statusOf(msg.decision),
       decidedBy: msg.by.id,
       decidedAt: at,
       note: msg.note,
       decidedWith: msg.id,
+      ...alone,
     });
     // The list first, then the ledger, then the decision event: whoever sees the event sees both.
     await DBOS.setEvent(APPROVALS_EVENT, all);
@@ -146,7 +169,14 @@ export async function awaitApproval(
       run,
       entry(
         run,
-        { type: "approval.decided", approval: state.id, decision: msg.decision, by: msg.by.id, note: msg.note },
+        {
+          type: "approval.decided",
+          approval: state.id,
+          decision: msg.decision,
+          by: msg.by.id,
+          note: msg.note,
+          ...alone,
+        },
         { key: state.id, at },
       ),
     );
@@ -155,3 +185,9 @@ export async function awaitApproval(
     return { approvedBy: msg.by.id, at, note: msg.note };
   }
 }
+
+/** What an approval and its request record keep of a hold besides the operation: its `seq` and rules, when it has them. */
+const heldOf = ({ seq, reasons }: HeldCall) => ({
+  ...(seq !== undefined && { opSeq: seq }),
+  ...(reasons !== undefined && { reasons }),
+});

package/src/call-workflow.ts

@@ -0,0 +1,44 @@
+import { z } from "zod";
+import { defineWorkflow, type WorkflowDefinition } from "./define.ts";
+import { isDirect } from "./direct.ts";
+import type { Op } from "./op.ts";
+import type { CALL_WORKFLOW } from "./shared.ts";
+
+export { CALL_WORKFLOW } from "./shared.ts";
+
+// The built-in `call` workflow: one operation that may be called directly (`isDirect`), as a run.
+// `SanomaClient.call` starts it, as the person, when the policy holds a direct call for an
+// approval, so the approval reaches the Inbox like any run's. It is a workflow like any other,
+// held to the same lint: the call goes through `ctx`, under the policy, in the ledger.
+
+/** The call workflow's input: the operation's id, and its input. */
+export const CallInput = z.object({ op: z.string(), input: z.unknown() });
+
+/**
+ * The call workflow for a config: it `uses` every operation that may be called directly and has
+ * a driver; `resolveConfig` adds it when there is one. A run calls `input.op` with `input.input`,
+ * and returns its output; inside it the call is made as the person who started the run, so a
+ * collection's save records them as `updatedBy`.
+ */
+export function callWorkflow(
+  ops: ReadonlyMap<string, Op>,
+  drivers: ReadonlyMap<string, unknown>,
+  types: ReadonlyMap<string, unknown>,
+): WorkflowDefinition<readonly Op[], typeof CallInput> {
+  const uses = [...ops.values()]
+    .filter((op) => isDirect(op, types) && drivers.has(op.id))
+    .toSorted((a, b) => a.id.localeCompare(b.id));
+  return defineWorkflow({
+    // The literal, held to the one name: the outline finds a workflow by a string, or a const of its own file.
+    name: "call" satisfies typeof CALL_WORKFLOW,
+    title: "Call an operation",
+    trigger: "manual",
+    input: CallInput,
+    uses,
+    // `ctx` refuses an operation that is not in `uses`: one that may not be called directly, or has no driver.
+    run: async (ctx, input) => {
+      const [vendor = "", resource = "", name = ""] = input.op.split(".");
+      return ctx[vendor]![resource]![name]!(input.input);
+    },
+  });
+}

package/src/call.ts

@@ -3,7 +3,9 @@ import { awaitApproval, type CheckedApproval } from "./approvals.ts";
 import { offsetOf } from "./ast.ts";
 import {
   AllMembers,
+  type ApprovalState,
   type ApprovalRequest,
+  type Principal,
   ApprovalRequestSchema,
   SleepFor,
   type SleepRequest,
@@ -22,13 +24,24 @@ import {
   PolicyDeniedError,
   SanomaError,
 } from "./errors.ts";
+import type { Collection } from "./collection.ts";
 import { currentGroup, entry, skipped, write, writeFailure } from "./ledger.ts";
 import { shown } from "./log.ts";
 import { type CallContext, isOp, type Op } from "./op.ts";
 import { callAt, callName, type CallNode } from "./outline.ts";
-import { DecisionSchema, type PolicyCall, policyOpOf, type RecordedDecision } from "./policy.ts";
-import type { Run, WorkerState } from "./run.ts";
-import { approverLabel, errorMessage, fitsOp } from "./shared.ts";
+import { allowAll, type Decision, type Policy, type PolicyCall, policyOpOf, type RecordedDecision } from "./policy.ts";
+import type { Run, StartHold, WorkerState } from "./run.ts";
+import { isChangeOp } from "./resource.ts";
+import {
+  APPLY_WORKFLOW,
+  approverLabel,
+  CALL_WORKFLOW,
+  DATA_VENDOR,
+  errorMessage,
+  fitsOp,
+  type Saved,
+  WORKFLOW_ACTION,
+} from "./shared.ts";
 
 /** DBOS took the run from this execution: it cancelled the run, or another process took it over. */
 const takenByDbos = (err: unknown) =>
@@ -50,7 +63,7 @@ export function isInfrastructureError(err: unknown, state: Pick<WorkerState, "st
 }
 
 /** The value as the ledger records it: each of the operation's `opaque` fields as `"<name>"`. */
-function recorded(op: Op, value: unknown): unknown {
+export function recorded(op: Op, value: unknown): unknown {
   if (!op.opaque?.length || typeof value !== "object" || value === null || Array.isArray(value)) return value;
   const out: Record<string, unknown> = { ...value };
   for (const name of op.opaque) if (out[name] !== undefined) out[name] = `<${name}>`;
@@ -251,16 +264,6 @@ function strict<T extends object>(obj: T, path: string, workflow: string): T {
   });
 }
 
-/** Checks a policy's answer, and copies it so nothing else the policy returned is recorded. */
-function checkDecision(decision: unknown, opId: string): RecordedDecision {
-  const parsed = DecisionSchema.safeParse(decision);
-  if (parsed.success) return parsed.data;
-  const why = parsed.error.issues[0]?.message ?? "not a decision";
-  throw new Error(
-    `The policy returned ${shown(decision)} for ${opId}: ${why}; use allow(), deny(reason) or approve(approver)`,
-  );
-}
-
 /** The resource instance the call acts on, from the operation's `target`, when it declares one. */
 function targetOf(op: Op, input: unknown): { target?: string } {
   if (!op.target) return {};
@@ -271,35 +274,138 @@ function targetOf(op: Op, input: unknown): { target?: string } {
   return { target };
 }
 
-/** Asks the policy. Runs inside a step, so it must have no side effects of its own. */
-async function decide(run: Run, op: Op, input: unknown): Promise<RecordedDecision> {
-  const call: PolicyCall = {
-    op: policyOpOf(op),
-    effect: op.effect,
-    ...targetOf(op, input),
-    input,
-    actor: run.actor,
-    run: { id: run.id, workflow: run.workflow, approvals: structuredClone(run.approvals) },
+/**
+ * Asks the policy about one call, with the record a collection's `save` or
+ * `delete` replaces as `before` (`beforeOf`). Runs inside a step, so it must have no side effects
+ * of its own.
+ */
+export async function decide(run: Run, op: Op, input: unknown): Promise<RecordedDecision> {
+  const seen = { id: run.id, workflow: run.workflow, approvals: structuredClone(run.approvals) };
+  const { policy } = run.state;
+  // Keyed by the call (`seq` was taken for it), so a fake answers each read afresh.
+  const before = await beforeOf(policy, op, input, run.state.collections, (get, key) =>
+    driverOf(run, get)?.(
+      { key },
+      { idempotencyKey: `${run.id}:${run.seq}:before`, runId: run.id, opId: get, attempt: 1, secrets: secretsOf(run) },
+    ),
+  );
+  const call = { ...callOf(op, input, run.actor, seen), ...before };
+  return ask(policy, op.id, () => policy(call), run.state);
+}
+
+/** The run's function for an operation: its own fake's in a sandbox run, never a vendor's; else the driver's. */
+const driverOf = (run: Run, id: string) => (run.sandbox === undefined ? run.state.drivers : run.fakeDrivers)?.get(id);
+
+/** The secrets a run's calls read: its own in a sandbox run, else the stored ones. */
+const secretsOf = (run: Run) => (run.sandbox === undefined ? run.state.secrets : run.fakeSecrets!);
+
+/** One call of `op` as `actor` in `run`, as a policy sees it. */
+const callOf = (op: Op, input: unknown, actor: Principal, run: PolicyCall["run"]): PolicyCall => ({
+  op: policyOpOf(op),
+  effect: op.effect,
+  ...targetOf(op, input),
+  input,
+  actor,
+  run,
+});
+
+/**
+ * For a collection's `save` or `delete`, the record it replaces or removes, read once with the
+ * collection's `get` (`read`): `{ before }` when there is one, else nothing, and nothing read
+ * under `allowAll`, which reads no call. A failed read is named, keeping its error's code.
+ */
+export async function beforeOf(
+  policy: Policy,
+  op: Op,
+  input: unknown,
+  collections: ReadonlyMap<string, Collection>,
+  read: (get: string, key: unknown) => Promise<unknown> | undefined,
+): Promise<{ before?: unknown }> {
+  const collection = op.vendor === DATA_VENDOR ? collections.get(op.resource) : undefined;
+  if (policy === allowAll || !collection || (op.name !== "save" && op.name !== "delete")) return {};
+  const key =
+    op.name === "save"
+      ? (input as { record: Record<string, unknown> }).record[collection.key]
+      : (input as { key: unknown }).key;
+  let saved: Saved | null | undefined;
+  try {
+    saved = (await read(`${DATA_VENDOR}.${op.resource}.get`, key)) as Saved | null | undefined;
+  } catch (err) {
+    if (takenByDbos(err)) throw err;
+    throw keepCode(new Error(`Reading the record ${op.id} replaces failed: ${errorMessage(err)}`, { cause: err }), err);
+  }
+  return saved ? { before: saved.record } : {};
+}
+
+/**
+ * Asks `policy` about one call of `op` as `actor` in `run`: a direct call
+ * (`SanomaClient.call`), with the record a collection's write replaces as `before` (`beforeOf`).
+ */
+export function decideCall(
+  policy: Policy,
+  op: Op,
+  input: unknown,
+  actor: Principal,
+  run: PolicyCall["run"],
+  before: Pick<PolicyCall, "before"> = {},
+): RecordedDecision {
+  const call = { ...callOf(op, input, actor, run), ...before };
+  return ask(policy, op.id, () => policy(call));
+}
+
+/**
+ * Asks the policy whether `actor` may start a run of `workflow` with `input` (`Policy.start`, the
+ * action `workflow:<name>`), as `SanomaClient.start` does before it queues one.
+ */
+export function decideStart(
+  policy: Policy,
+  workflow: string,
+  input: unknown,
+  actor: Principal,
+  approvals: readonly ApprovalState[] = [],
+) {
+  return ask(policy, `${WORKFLOW_ACTION}${workflow}`, () => policy.start(actor, workflow, input, approvals));
+}
+
+/** The approval a start's `approve` answer waits on: whom it asks, its title, and the rules that held it. */
+export function startHoldOf(
+  workflow: string,
+  { approver, title, reasons }: Extract<Decision, { kind: "approve" }>,
+): StartHold {
+  return {
+    approver,
+    title: title ?? `${WORKFLOW_ACTION}${workflow} needs ${approverLabel(approver)}`,
+    ...(reasons && { reasons }),
   };
-  let answer: unknown;
+}
+
+/**
+ * The policy's answer about `id` (`answer`), with its version. A policy that fails is named in
+ * the error, with its error's code, unless the worker is stopping (`state`).
+ */
+function ask(
+  policy: Policy,
+  id: string,
+  answer: () => Decision,
+  state: Pick<WorkerState, "stopped"> = { stopped: false },
+): RecordedDecision {
+  let decision: Decision;
   try {
-    answer = await run.state.policy(call);
+    decision = answer();
   } catch (err) {
     // Named here, so the run's error and the ledger say which call the policy failed on, with
     // the code the policy's error had.
-    if (isInfrastructureError(err, run.state)) throw err;
-    throw keepCode(new Error(`The policy failed deciding ${op.id}: ${errorMessage(err)}`, { cause: err }), err);
+    if (isInfrastructureError(err, state)) throw err;
+    throw keepCode(new Error(`The policy failed deciding ${id}: ${errorMessage(err)}`, { cause: err }), err);
   }
-  const decision = checkDecision(answer, op.id);
-  const policyVersion = run.state.policy.version;
-  return policyVersion === undefined ? decision : { ...decision, policyVersion };
+  return policy.version === undefined ? decision : { ...decision, policyVersion: policy.version };
 }
 
 async function callOp(run: Run, id: string, input: unknown, place: Placed) {
   // The worker's declaration, never the workflow's: its effect, schemas and retry setting.
   const op = run.state.ops.get(id);
   // A sandbox run calls its own fakes, never a vendor.
-  const fn = run.sandbox === undefined ? run.state.drivers.get(id) : run.fakeDrivers?.get(id);
+  const fn = driverOf(run, id);
   if (!op || !fn) {
     throw new Error(
       run.sandbox === undefined
@@ -307,6 +413,13 @@ async function callOp(run: Run, id: string, input: unknown, place: Placed) {
         : `No connector or fake for ${id} in this worker: no fake its connectors attach implements it`,
     );
   }
+  // Only apply changes a declared resource; `resolveConfig` refuses any other workflow that uses such an operation.
+  if (isChangeOp(op, run.state.types) && run.workflow !== APPLY_WORKFLOW) {
+    throw new SanomaError("invalid_input", `${op.id} changes a declared resource, which only ${APPLY_WORKFLOW} does`, {
+      op: op.id,
+      workflow: run.workflow,
+    });
+  }
   const parsed = parseOrThrow(op.input, input, `The input to ${op.id} does not match its schema`, { op: op.id });
   // The call's identity (its ledger seq and id, and the driver's idempotency key) is taken
   // before the first await, so it depends only on the order the workflow made its calls. A
@@ -316,24 +429,27 @@ async function callOp(run: Run, id: string, input: unknown, place: Placed) {
   // The decision is recorded as a step, so a replay reuses it instead of asking a policy
   // that may have changed since. The policy must still be deterministic: a run that fails
   // before the step is recorded asks again.
-  const decision = await DBOS.runStep(() => decide(run, op, parsed), { name: `policy:${op.id}` });
+  const decideStep = () => DBOS.runStep(() => decide(run, op, parsed), { name: `policy:${op.id}` });
+  let decision = await decideStep();
   const logged = recorded(op, parsed);
   const call = { type: "op.called", op: op.id, ...place, effect: op.effect, input: logged, decision } as const;
 
-  if (decision.kind === "deny") {
-    const err = new PolicyDeniedError(op.id, decision.reason);
-    await writeFailure(run, entry(run, { ...call, error: errorInfo(err), durationMs: 0 }, { seq }), err);
-    throw err;
-  }
-  if (decision.kind === "approve") {
+  // Each hold is lifted in turn: once one is approved, the policy is asked again, with it.
+  for (;;) {
+    if (decision.kind === "deny") {
+      const err = new PolicyDeniedError(op.id, decision.reason);
+      await writeFailure(run, entry(run, { ...call, decision, error: errorInfo(err), durationMs: 0 }, { seq }), err);
+      throw err;
+    }
+    if (decision.kind !== "approve") break;
     const title = decision.title ?? `${op.id} needs ${approverLabel(decision.approver)}`;
-    // A hold covers the call it held, and any other operations the policy named.
-    const covers = [...new Set([op.id, ...(decision.covers ?? [])])];
     try {
-      await awaitApproval(run, title, { approver: decision.approver, covers }, place, {
+      // A hold covers the call it held.
+      await awaitApproval(run, title, { approver: decision.approver, covers: [op.id] }, place, {
         op: op.id,
         seq,
         input: logged,
+        reasons: decision.reasons,
       });
     } catch (err) {
       if (errorCode(err) === "approval_rejected") {
@@ -343,6 +459,7 @@ async function callOp(run: Run, id: string, input: unknown, place: Placed) {
       }
       throw err;
     }
+    decision = await decideStep();
   }
 
   const started = Date.now();
@@ -355,7 +472,16 @@ async function callOp(run: Run, id: string, input: unknown, place: Placed) {
       async () => {
         const at = Date.now();
         attempt = DBOS.stepStatus?.currentAttempt ?? 1;
-        const context: CallContext = { idempotencyKey: `${run.id}:${seq}`, runId: run.id, opId: op.id, attempt };
+        const secrets = secretsOf(run);
+        const context: CallContext = {
+          idempotencyKey: `${run.id}:${seq}`,
+          runId: run.id,
+          opId: op.id,
+          attempt,
+          secrets,
+          // A call run is the person's direct call held for an approval: made as them, as it would have been.
+          by: run.workflow === CALL_WORKFLOW ? run.actor.id : `run:${run.id}`,
+        };
         // A live driver's `env` is checked here, inside the step, by the guard `indexDrivers` put
         // on its function: the refusal is the call's failure, recorded and never retried.
         const output = op.output.parse(await fn(parsed, context));
@@ -441,13 +567,14 @@ async function all(run: Run, list: unknown, node: string): Promise<unknown[]> {
 
 /**
  * Waits, durably, until the time or for the duration the request names, and records when it
- * ends. For a duration that is the time the sleep started plus the duration, as the runtime saw
- * it (`Date.now()`, which adds no DBOS call): a replay may compute another, but the store keeps
+ * ends. For a duration that is the record's `at` plus the duration, one read of the runtime's
+ * clock (`Date.now()`, which adds no DBOS call): a replay may compute another, but the store keeps
  * the first record with the id, so the record says what the first execution waited for.
  */
 async function sleep(run: Run, raw: unknown, at: Placed) {
   const req = checkSleep(raw);
   const seq = run.seq++;
+  const started = Date.now();
   let until: number;
   let ms: number;
   if ("until" in req) {
@@ -460,9 +587,9 @@ async function sleep(run: Run, raw: unknown, at: Placed) {
       (req.minutes ?? 0) * 60_000 +
       (req.hours ?? 0) * 3_600_000 +
       (req.days ?? 0) * 86_400_000;
-    until = Date.now() + ms;
+    until = started + ms;
   }
-  await write(run, entry(run, { type: "sleep.started", ...at, until }, { seq }));
+  await write(run, entry(run, { type: "sleep.started", ...at, until }, { seq, at: started }));
   // A time already past waits not at all, and adds no step. A sandbox run never waits.
   if (ms > 0 && run.sandbox === undefined) await DBOS.sleep(ms);
 }