@sanoma-ai/workflows 0.2.0 → 0.4.1

package/src/index.ts

@@ -47,6 +47,9 @@ export {
   withoutWriteOnly,
 } from "./resource.ts";
 export { defineConfig, resolveConfig, resolveDatabaseUrl, type ResolvedConfig, type SanomaConfig } from "./config.ts";
+// `sanoma` itself (the people types' constructors) is at `@sanoma-ai/workflows/resources`, for data files.
+// `collection()` itself is at `@sanoma-ai/workflows/data`, for `resources/data.ts`; this tells one apart, as the launcher does.
+export { isCollection } from "./collection.ts";
 export { type CredentialStatus, credentialsOf } from "./env.ts";
 export {
   APPLY_WORKFLOW,
@@ -57,6 +60,8 @@ export {
   type PlanAnswer,
   type PlanStep,
 } from "./apply.ts";
+export { CALL_WORKFLOW, CallInput } from "./call-workflow.ts";
+export { isDirect } from "./direct.ts";
 export {
   DRIFT_WORKFLOW,
   type DriftDeclared,
@@ -73,20 +78,32 @@ export {
   approve,
   approvedFor,
   type Decision,
-  definePolicy,
   deny,
   type Policy,
   type PolicyCall,
   type PolicyOp,
   policyOpOf,
+  type PreviewAnswer,
+  type PreviewRequest,
   type RecordedDecision,
 } from "./policy.ts";
 export {
+  cedarPolicy,
+  type CedarPolicySource,
+  loadPolicies,
+  POLICIES_DIR,
+  type PolicyProblem,
+  readPolicyFiles,
+  validatePolicies,
+} from "./cedar.ts";
+export {
+  ApprovalPendingError,
   errorCode,
   type ErrorCode,
   type ErrorInfo,
   type InputIssue,
   invalidInput,
+  NotAdmittedError,
   PolicyDeniedError,
   RejectedError,
   SanomaError,
@@ -116,12 +133,26 @@ export {
 } from "./secret.ts";
 export { resolveRevision, SOURCE_RESOLVE, type Source } from "./source.ts";
 export type { HostCapabilities, HostLifetime, HostOutputs, HostSpec } from "./host.ts";
-export { SanomaClient, type RunsFilter, type RunSummary, type StartOptions, type StoredSecret } from "./client.ts";
+export {
+  type CallOptions,
+  SanomaClient,
+  type RunsFilter,
+  type RunSummary,
+  type StartOptions,
+  type StoredSecret,
+} from "./client.ts";
 // A raw DBOS client on the runtime's database, for tests and tools that read DBOS directly.
 export { dbosClient } from "./db.ts";
 // Also at `@sanoma-ai/workflows/shared`, which a browser bundle can import.
 export {
+  AGENTS,
   approverLabel,
+  approverOf,
+  declaresPeople,
+  type PeopleResource,
+  personOf,
+  principalOf,
+  RUNTIME_AGENTS,
   credentialReady,
   DEFAULT_SLEEP_NAME,
   ENDED_STATUSES,

package/src/ledger.ts

@@ -3,7 +3,7 @@ import { appendFile, mkdir, readFile, truncate } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { setTimeout as delay } from "node:timers/promises";
 import { isDeepStrictEqual } from "node:util";
-import { LEDGER_TABLE as TABLE, lazyPool, pgCode } from "./db.ts";
+import { type Db, LEDGER_TABLE as TABLE, lazyPool, pgCode } from "./db.ts";
 import type { Approver, Principal } from "./define.ts";
 import { type ErrorInfo, isFinal, keepCode } from "./errors.ts";
 import { shown, warn } from "./log.ts";
@@ -80,13 +80,23 @@ export type LedgerRecord = {
       op?: string;
       /** The held call's `seq`, which its `op.called` record has, for a policy request. */
       opSeq?: number;
+      /** The policies that held the call, by id, for a policy request whose policy names them. */
+      reasons?: string[];
     }
   /** A message the approval ignored: from someone other than the approver, or not a decision. */
   | { type: "approval.refused"; approval: string; by?: string; reason: string }
-  | { type: "approval.decided"; approval: string; decision: "approve" | "reject"; by: string; note?: string }
+  | {
+      type: "approval.decided";
+      approval: string;
+      decision: "approve" | "reject";
+      by: string;
+      note?: string;
+      /** Set when `by` started the run: nobody else could decide (`mayDecide`). */
+      alone?: true;
+    }
   /**
    * A `ctx.sleep` began; `until` is when it ends, in ms since the epoch: the time asked for, or
-   * for a duration the time the sleep started plus the duration, as the runtime saw it. Written
+   * for a duration the record's `at` plus the duration, as the runtime saw it. Written
    * for a time already past too, which waits not at all.
    */
   | {
@@ -292,25 +302,13 @@ export function postgresLedger(databaseUrl: string): LedgerStore & { close(): Pr
 
   return {
     async append(record) {
-      const line = lineOf(record);
       const conn = await pool.db();
-      const inserted = await conn
-        .query(
-          `INSERT INTO ${TABLE} (id, run_id, seq, record) VALUES ($1, $2, $3, $4::jsonb) ON CONFLICT (id) DO NOTHING RETURNING n`,
-          [record.id, record.runId, record.seq, line],
-        )
-        .catch((err: unknown) => {
-          if (DATA_EXCEPTION.test(pgCode(err))) {
-            throw final(`Ledger record ${record.id} can't be stored: ${errorMessage(err)}`, err);
-          }
-          throw err;
-        });
-      if (inserted.rows.length) return;
+      if (await insertRecord(conn, record)) return;
       // Another write of the id was first: the record it stored stands.
       const { rows } = await conn.query<{ record: LedgerRecord }>(`SELECT record FROM ${TABLE} WHERE id = $1`, [
         record.id,
       ]);
-      if (rows[0]) warnIfDifferent(rows[0].record, line);
+      if (rows[0]) warnIfDifferent(rows[0].record, lineOf(record));
     },
     async read(runId) {
       const { rows } = await (
@@ -323,6 +321,26 @@ export function postgresLedger(databaseUrl: string): LedgerStore & { close(): Pr
   };
 }
 
+/**
+ * Stores the record in the Postgres ledger's table through `db`, unless one with its id is
+ * stored: true when this one was. What `postgresLedger` appends with, and a direct write
+ * (`SanomaClient.call`) inside the transaction that saves its record.
+ */
+export async function insertRecord(db: Db, record: LedgerRecord): Promise<boolean> {
+  const inserted = await db
+    .query(
+      `INSERT INTO ${TABLE} (id, run_id, seq, record) VALUES ($1, $2, $3, $4::jsonb) ON CONFLICT (id) DO NOTHING RETURNING n`,
+      [record.id, record.runId, record.seq, lineOf(record)],
+    )
+    .catch((err: unknown) => {
+      if (DATA_EXCEPTION.test(pgCode(err))) {
+        throw final(`Ledger record ${record.id} can't be stored: ${errorMessage(err)}`, err);
+      }
+      throw err;
+    });
+  return inserted.rows.length > 0;
+}
+
 /** Keeps records in memory, for tests. */
 export function memoryLedger(): LedgerStore {
   const runs = new Map<string, Map<string, LedgerRecord>>();

package/src/lint.ts

@@ -1,6 +1,7 @@
+import { realpathSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 import { byPosition, childrenOf, type LintProblem, type Node, parsed, type SourceFile } from "./ast.ts";
-import { readDataFile } from "./datafile.ts";
+import { COLLECTIONS_FILE, readDataFile } from "./datafile.ts";
 import { constsOf, outlineBody, workflowLiterals } from "./outline.ts";
 import { inside, nearestDir, RELATIVE } from "./paths.ts";
 // From src/ and from dist/ alike, the package's own oxlint.json: the one list of allowed names.
@@ -33,7 +34,7 @@ const REFUSED_PACKAGES: [RegExp, string][] = [
 ];
 
 /**
- * What a workflow or policy may import from an author package, besides types: the one list,
+ * What a workflow may import from an author package, besides types: the one list,
  * `allowImportNames` of oxlint.json's `@sanoma-ai/workflows` entry (`sanoma`'s generated
  * `oxlint.json` derives its own entry from it). Everything else is
  * refused: the client, the worker and the app could start runs or approve the run's own
@@ -46,7 +47,7 @@ const WORKFLOW_IMPORTS: readonly string[] =
 const ALLOWED_NAMES = new Set(WORKFLOW_IMPORTS);
 
 const NOT_ALLOWED =
-  `a workflow or policy imports only ${WORKFLOW_IMPORTS.join(", ")} and types from ` +
+  `a workflow imports only ${WORKFLOW_IMPORTS.join(", ")} and types from ` +
   `${AUTHOR_PACKAGES.join(" or ")}: the rest could start runs, approve its own approvals, forge the ledger or read credentials`;
 
 /**
@@ -57,11 +58,12 @@ const NOT_ALLOWED =
 const ERROR_CLASSES = new Set(["DriverError", "SanomaError", "PolicyDeniedError", "RejectedError"]);
 
 /**
- * Checks a workflow or policy file. Imports allowed: the names in `WORKFLOW_IMPORTS` and any
+ * Checks a workflow file. Imports allowed: the names in `WORKFLOW_IMPORTS` and any
  * type from `@sanoma-ai/workflows` or `sanoma`, `@sanoma-ai/connector-<vendor>`, `zod`, and relative files. With
- * `filename`, a relative import must stay inside the file's nearest `workflows/` or `policies/`
- * directory, or its own directory when it has neither. No `instanceof` against the runtime's
- * error classes: read `errorCode(err)`.
+ * `filename`, a relative import must stay inside the file's nearest `workflows/` directory, or its
+ * own directory when it has none; the one file outside it a workflow may import is the company's
+ * `resources/data.ts`, its collections (by real path). No
+ * `instanceof` against the runtime's error classes: read `errorCode(err)`.
  *
  * In each workflow's `run` (the literal `defineWorkflow` is called with), it reports what the
  * outline cannot draw, as the worker refuses to start with (`outlineBody`): `ctx` used other
@@ -82,7 +84,7 @@ export function lintWorkflow(input: string | SourceFile, path?: string): LintPro
   const read = typeof input === "string" ? parsed(input, filename ?? "workflow.ts") : input;
   const { program, at } = read;
   const problems = [...read.problems];
-  const root = filename === undefined ? undefined : nearestDir(filename, ["workflows", "policies"]);
+  const root = filename === undefined ? undefined : nearestDir(filename, ["workflows"]);
 
   const checkSource = (node: Node) => {
     const spec: string = node.source.value;
@@ -197,12 +199,27 @@ type RestrictedPath = { name: string; allowImportNames?: string[] };
 
 function whyRefused(spec: string, filename: string | undefined, root: string | undefined): string | undefined {
   if (RELATIVE.test(spec)) {
-    if (filename === undefined || root === undefined || inside(root, join(dirname(filename), spec))) return undefined;
-    const where =
-      basename(root) === "workflows" || basename(root) === "policies" ? `${basename(root)}/` : "this directory";
-    return `it reaches outside ${where}, toward the config and its drivers; ${THROUGH_CTX}`;
+    if (filename === undefined || root === undefined) return undefined;
+    const target = join(dirname(filename), spec);
+    if (inside(root, target)) return undefined;
+    const tree = basename(root) === "workflows";
+    // The collections, which a workflow names in `uses`: the one data file the runtime imports too.
+    if (tree && realPath(target) === realPath(join(dirname(root), "resources", COLLECTIONS_FILE))) return undefined;
+    return (
+      `it reaches outside ${tree ? `${basename(root)}/` : "this directory"}, toward the config and its drivers; ${THROUGH_CTX}` +
+      (tree ? "; of the files outside it, only resources/data.ts (the collections) may be imported" : "")
+    );
   }
   for (const [pattern, reason] of REFUSED_PACKAGES) if (pattern.test(spec)) return reason;
   if (ALLOWED_PACKAGE.test(spec)) return undefined;
   return "import only from `sanoma` (or `@sanoma-ai/workflows`), a `@sanoma-ai/connector-*` package, zod, or a file beside this one";
 }
+
+/** A path's real path, or the path itself when it does not exist. */
+function realPath(path: string): string {
+  try {
+    return realpathSync(path);
+  } catch {
+    return path;
+  }
+}

package/src/op.ts

@@ -238,6 +238,12 @@ export interface CallContext {
   attempt: number;
   /** The secrets store, for the values `secret()` markers name: `resolveSecrets(input, call.secrets)`. In memory for a fake. */
   secrets: Secrets;
+  /**
+   * Who the call is made as: `run:<runId>` for a call in a run; the person's id for a direct call
+   * (`SanomaClient.call`) and in a run of the built-in `call` workflow. A collection's save
+   * records it as the record's `updatedBy`.
+   */
+  by?: string;
 }
 
 export type DriverFn<I = any, O = unknown> = (input: I, call: CallContext) => Promise<O>;

package/src/outline.ts

@@ -576,7 +576,7 @@ function ctxPath(callee: Node, ctx: string): string[] | undefined {
 }
 
 /** A string literal's value, or a template literal's with nothing interpolated. */
-function stringValue(node: Node): string | undefined {
+export function stringValue(node: Node): string | undefined {
   const n = unwrap(node);
   if (n?.type === "Literal" && typeof n.value === "string") return n.value;
   if (n?.type === "TemplateLiteral" && n.expressions.length === 0) return n.quasis[0]?.value.cooked ?? undefined;

package/src/paths.ts

@@ -1,7 +1,9 @@
-import { basename, dirname, isAbsolute, relative, sep } from "node:path";
+import { readdirSync, statSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, sep } from "node:path";
 
-// Where an import may reach, as the lints and the data-file reader all decide it, and the one
-// walk up the directories. Node's `path` only, no parser: the oxlint plugin loads it.
+// Where an import may reach, as the lints and the data-file reader all decide it, the one walk up
+// the directories and the one walk down (`filesUnder`). Node's `path` and `fs` only, no parser:
+// the oxlint plugin loads it.
 
 /** A relative import specifier: `./x.ts`, `../y.ts`. */
 export const RELATIVE = /^\.\.?\//;
@@ -30,3 +32,16 @@ export function inside(dir: string, path: string): boolean {
   const rel = relative(dir, path);
   return rel === "" || (rel.split(sep)[0] !== ".." && !isAbsolute(rel));
 }
+
+/** True when `path` is a directory. */
+export const isDirectory = (path: string): boolean => statSync(path, { throwIfNoEntry: false })?.isDirectory() ?? false;
+
+/** The files under `dir` whose name `keep` takes, sorted, outside `node_modules`; none when `dir` is not a directory. */
+export function filesUnder(dir: string, keep: (name: string) => boolean): string[] {
+  if (!isDirectory(dir)) return [];
+  return readdirSync(dir, { recursive: true, withFileTypes: true })
+    .filter((d) => d.isFile() && keep(d.name))
+    .map((d) => join(d.parentPath, d.name))
+    .filter((path) => !relative(dir, path).split(sep).includes("node_modules"))
+    .toSorted();
+}

package/src/person.ts

@@ -0,0 +1,75 @@
+import { z } from "zod";
+import { defineConnector } from "./op.ts";
+import { defineResource } from "./resource.ts";
+
+// Who exists in a company: people, agents and groups, declared in data files like any resource,
+// as the runtime's own vendor's types (`sanoma.person`, `sanoma.agent`, `sanoma.group`, imported
+// from "sanoma/resources"). They are `vendorless`: the repo is all there is of them, so they have
+// no driver and no drift. A membership is written on a group only, its members references to the
+// declared people and agents; every agent is in the group `agents` besides. Who a principal is,
+// read from them, is `principalOf` (`shared.ts`).
+
+/** An id or a group's name: one word, as a scenario names an approver. */
+const WORD = z.string().regex(/^\S+$/, 'is one word, such as "ada"');
+const NONE = { immutable: [], vendorOwned: [], writeOnly: [] };
+
+const person = defineResource({
+  vendor: "sanoma",
+  type: "person",
+  title: "Person",
+  identity: "id",
+  schema: z.object({
+    id: WORD,
+    name: z.string().optional(),
+    /** Matched first by a sign-in that vouches for an email (GitHub's, its verified public one). */
+    email: z.email().optional(),
+    /** Their GitHub login, which GitHub sign-in matches, ignoring case, when no email does. */
+    github: z
+      .string()
+      .regex(/^[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?$/, "is a GitHub login, such as ada-ortiz")
+      .optional(),
+  }),
+  fields: NONE,
+  find: ({ id }) => id,
+  vendorless: true,
+});
+
+const agent = defineResource({
+  vendor: "sanoma",
+  type: "agent",
+  title: "Agent",
+  identity: "id",
+  schema: z.object({ id: WORD, name: z.string().optional(), onBehalfOf: WORD.optional() }),
+  fields: { ...NONE, references: { onBehalfOf: { type: "sanoma.person" } } },
+  find: ({ id }) => id,
+  vendorless: true,
+});
+
+const group = defineResource({
+  vendor: "sanoma",
+  type: "group",
+  title: "Group",
+  identity: "name",
+  schema: z.object({ name: WORD, members: z.array(WORD) }),
+  fields: {
+    ...NONE,
+    unordered: ["members"],
+    references: { members: { type: ["sanoma.person", "sanoma.agent"] } },
+  },
+  find: ({ name }) => name,
+  vendorless: true,
+});
+
+/**
+ * What a data file declares the company's people with, imported from "sanoma/resources":
+ * `export const ada = sanoma.person({ id: "ada", name: "Ada Ortiz", github: "ada-ortiz" })`,
+ * `sanoma.agent({ id: "refund-bot", onBehalfOf: bo })` and
+ * `sanoma.group({ name: "finance", members: [ada, refundBot] })`.
+ */
+export const sanoma = { person, agent, group };
+
+/**
+ * The runtime's own connector of the people types: every config's, so its data files may declare
+ * them. Its package is `sanoma`, whose `/resources` entry exports `sanoma`.
+ */
+export const peopleConnector = defineConnector("sanoma", sanoma, { title: "Sanoma", package: "sanoma" });

package/src/plugin.ts

@@ -1,15 +1,67 @@
 import { readDataFile } from "./datafile.ts";
 
-// An oxlint JS plugin with one rule, `sanoma/data-file`: the data-file subset `readResources`
-// reads, the same check as `lintResources`, on the tree oxlint has already parsed. The
-// package's `oxlint.json` turns it on for `resources/**`. Typed here by the little it uses, so
-// the package needs no oxlint types.
+// An oxlint JS plugin with two rules, on the trees oxlint has already parsed, which the package's
+// `oxlint.json` turns on: `sanoma/data-file` for `resources/**`, the data-file subset
+// `readResources` reads, the same check as `lintResources`; and `sanoma/date` for `workflows/**`,
+// `Date` reading the clock. Typed here by the little they use, so the package needs no oxlint types.
 
 interface Context {
   filename: string;
+  sourceCode: { isGlobalReference(node: Node): boolean };
   report(diagnostic: { message: string; node: { range: [number, number] } }): void;
 }
 
+/** A node of oxlint's ESTree, by the little the `date` rule reads. */
+interface Node {
+  type: string;
+  range: [number, number];
+  parent?: Node;
+  name?: string;
+  callee?: Node;
+  object?: Node;
+  property?: Node;
+  computed?: boolean;
+  arguments?: Node[];
+  operator?: string;
+  right?: Node;
+}
+
+const DATE_MESSAGE =
+  "Workflows are replayed, so a workflow reads the clock with `await ctx.now()`, never `Date`: `new Date(await ctx.now())` for a date, `new Date(value)`, `Date.parse` or `Date.UTC` for one it has, and `ctx.sleep({ until })` to wait for a date.";
+
+/** Where `Date` names the type, which the build erases: `d: Date`, `typeof Date`, `implements Date`. */
+const TYPE_PARENTS = new Set([
+  "TSTypeReference",
+  "TSTypeQuery",
+  "TSQualifiedName",
+  "TSClassImplements",
+  "TSInterfaceHeritage",
+]);
+
+/** `Date`'s functions that read no clock. */
+const PURE = new Set(["parse", "UTC"]);
+
+/**
+ * Whether `Date` (`node`) reads no clock where it is: `new Date(value)`, `Date.parse(…)`,
+ * `Date.UTC(…)`, `x instanceof Date`, or a type. A node without its parent is reported.
+ */
+function readsNoClock(node: Node): boolean {
+  const { parent } = node;
+  if (!parent) return false;
+  if (TYPE_PARENTS.has(parent.type)) return true;
+  if (parent.type === "BinaryExpression") return parent.operator === "instanceof" && parent.right === node;
+  if (parent.type === "NewExpression" && parent.callee === node) {
+    const [first] = parent.arguments ?? [];
+    return first !== undefined && first.type !== "SpreadElement";
+  }
+  return (
+    parent.type === "MemberExpression" &&
+    parent.object === node &&
+    !parent.computed &&
+    PURE.has(parent.property?.name ?? "")
+  );
+}
+
 const plugin = {
   meta: { name: "sanoma" },
   rules: {
@@ -18,7 +70,7 @@ const plugin = {
         type: "problem",
         docs: {
           description:
-            "A data file under resources/ holds only imports, `export const <name> = <vendor>.<type>({ … })` with literal fields, and `export default [ … ]`",
+            "A data file under resources/ holds only imports, `export const <name> = <vendor>.<type>({ … })` with literal fields, and `export default [ … ]`; resources/data.ts holds only collections, `collection({ … })` from sanoma/data",
         },
       },
       create(context: Context) {
@@ -31,6 +83,23 @@ const plugin = {
         };
       },
     },
+    // `Date` reads the clock in `Date.now()`, `new Date()` and `Date()`, which a replay would read
+    // again; a workflow reads it with `ctx.now()`, recorded. Every other use of `Date` is pure:
+    // `new Date(value)` (of `await ctx.now()`, or of a date the workflow has), `Date.parse`, `Date.UTC`.
+    date: {
+      meta: {
+        type: "problem",
+        docs: { description: "A workflow reads the clock with `await ctx.now()`, never `Date`" },
+      },
+      create(context: Context) {
+        return {
+          Identifier(node: Node) {
+            if (node.name !== "Date" || readsNoClock(node)) return;
+            if (context.sourceCode.isGlobalReference(node)) context.report({ message: DATE_MESSAGE, node });
+          },
+        };
+      },
+    },
   },
 };