@sanoma-ai/workflows 0.7.1 → 0.8.0

package/src/db.ts

@@ -101,6 +101,29 @@ export function openPool(databaseUrl: string, what: string): Pool {
  */
 export const DBOS_DATABASE_OPTIONS = { systemDatabaseIdleTransactionTimeoutMs: 0 } as const;
 
+/**
+ * Stamps the change runs `ids` still unfinished on another version with the application version
+ * `version`, so DBOS gives them to a worker of that version: those it stamped, each with its status
+ * (a PENDING one is the caller's to queue again). DBOS has no call for it (a run's version is set at
+ * its start, `forkWorkflow` makes a new id, `rewindWorkflow` takes only an ended run), so this is the
+ * runtime's one write to DBOS's own tables, in its schema `dbos` (dbos-sdk 5.2.11). One statement:
+ * of two workers stamping a run, one does.
+ */
+export async function stampVersion(
+  db: Db,
+  ids: readonly string[],
+  version: string,
+): Promise<{ id: string; pending: boolean }[]> {
+  const { rows } = await db.query<{ workflow_uuid: string; status: string }>(
+    `UPDATE dbos.workflow_status SET application_version = $1
+     WHERE workflow_uuid = ANY($2) AND name = 'change' AND status IN ('PENDING', 'ENQUEUED')
+       AND application_version <> $1
+     RETURNING workflow_uuid, status`,
+    [version, ids],
+  );
+  return rows.map((r) => ({ id: r.workflow_uuid, pending: r.status === "PENDING" }));
+}
+
 /**
  * A DBOS client of the app `applicationName` on the database at `databaseUrl`, as every client of
  * the runtime, its tests and `@sanoma-ai/testing` make one (`DBOS_DATABASE_OPTIONS`).

package/src/deadlines.ts

@@ -14,8 +14,11 @@ import type { WakeupRegistration } from "./wakeup.ts";
 // blocked in a `ctx` wait, and until when. DBOS sees both as PENDING. A worker that registers a
 // wakeup stops itself once nothing can run before the next deadline (`stopWhenIdle`).
 
-/** What a run blocked in a `ctx` wait waits for: a sleep, until its deadline, or an approval's decision, which has none. */
-export type Wait = { kind: "sleep"; until: number } | { kind: "approval" };
+/**
+ * What a run blocked in a wait waits for: a sleep, until its deadline; or, with no deadline, an
+ * approval's decision, a message (a change run's `ChangeEvent`), or another run it started.
+ */
+export type Wait = { kind: "sleep"; until: number } | { kind: "approval" | "message" | "run" };
 
 /** A deadline besides the sleeping runs', such as a schedule's next fire; undefined for none. */
 export type DeadlineSource = () => Date | undefined;

package/src/define.ts

@@ -2,6 +2,8 @@ import { fileURLToPath } from "node:url";
 import { getCallSites } from "node:util";
 import { z } from "zod";
 import { isOp, type Op } from "./op.ts";
+import { appOfFile } from "./paths.ts";
+import { type DATA_VENDOR, qualified } from "./shared.ts";
 
 /**
  * Who is acting: the person or agent that starts a run, calls an operation or decides an
@@ -171,19 +173,27 @@ export interface StepOptions {
 
 type OpsOf<U extends readonly Use[]> = Extract<U[number], Op>;
 
-type CtxOps<O extends Op> = {
-  readonly [V in O["vendor"]]: {
-    readonly [R in Extract<O, { vendor: V }>["resource"]]: {
-      readonly [N in Extract<O, { vendor: V; resource: R }>["name"]]: Extract<
-        O,
-        { vendor: V; resource: R; name: N }
-      > extends Op<any, any, any, infer I, infer Out>
-        ? (input: I, options?: StepOptions) => Promise<Out>
-        : never;
-    };
+type VendorCtx<O extends Op, V> = {
+  readonly [R in Extract<O, { vendor: V }>["resource"]]: {
+    readonly [N in Extract<O, { vendor: V; resource: R }>["name"]]: Extract<
+      O,
+      { vendor: V; resource: R; name: N }
+    > extends Op<any, any, any, infer I, infer Out>
+      ? (input: I, options?: StepOptions) => Promise<Out>
+      : never;
   };
 };
 
+/**
+ * `ctx.<vendor>.<resource>.<op>`. An app's collections are `ctx.data.<app>.<name>` at run time,
+ * a folder's name no type knows: that level is untyped (`any`), the root's collections typed.
+ */
+type CtxOps<O extends Op> = {
+  readonly [V in O["vendor"]]: V extends typeof DATA_VENDOR
+    ? VendorCtx<O, V> & { readonly [app: string]: any }
+    : VendorCtx<O, V>;
+};
+
 interface ApprovalCtx {
   /** Waits, durably, until the approver (or someone in the approver group) approves. Throws `RejectedError` on a rejection, `WithdrawnError` on a withdrawal. */
   approval(title: string, request: ApprovalRequest): Promise<ApprovalResult>;
@@ -256,7 +266,10 @@ export type Trigger = "manual" | { readonly schedule: string; readonly timezone?
 
 export interface WorkflowDefinition<U extends readonly Use[] = readonly Use[], S extends z.ZodType = z.ZodType> {
   readonly kind: "workflow";
+  /** Its name, as written at the root; in an app's folder, `<app>.<name>` (`app`). */
   readonly name: string;
+  /** The app whose folder defined it (`apps/<app>/`), from its `file`; absent for one at the root. */
+  readonly app?: string;
   readonly title?: string;
   readonly trigger: Trigger;
   readonly input: S;
@@ -273,8 +286,13 @@ export interface WorkflowDefinition<U extends readonly Use[] = readonly Use[], S
 /** The ids of the operations a workflow `uses`, in the order declared. */
 export const opIdsOf = (wf: Pick<WorkflowDefinition, "uses">): string[] => wf.uses.filter(isOp).map((op) => op.id);
 
+/**
+ * Defines a workflow in its own file. Its `name` is a lowercase letter, then lowercase letters,
+ * digits and dashes; in an app's folder (`apps/<app>/`, `appOfFile`) the runtime names it
+ * `<app>.<name>`, so two apps may each have a `sync`.
+ */
 export function defineWorkflow<const U extends readonly Use[], S extends z.ZodType>(
-  def: Omit<WorkflowDefinition<U, S>, "kind" | "file">,
+  def: Omit<WorkflowDefinition<U, S>, "kind" | "file" | "app">,
 ): WorkflowDefinition<U, S> {
   if (!/^[a-z][a-z0-9-]*$/.test(def.name)) {
     throw new Error(`Workflow name "${def.name}" must be lowercase letters, digits and dashes`);
@@ -293,7 +311,8 @@ export function defineWorkflow<const U extends readonly Use[], S extends z.ZodTy
         "its outline is read from the file, and a run is held to the outline",
     );
   }
-  return Object.freeze({ kind: "workflow", ...def, file });
+  const app = appOfFile(file);
+  return Object.freeze({ kind: "workflow", ...def, name: qualified(app, def.name), ...(app && { app }), file });
 }
 
 /** True when `{}` parses: a schema zod can check only asynchronously is taken as accepting it, and the run parses it. */

package/src/demo.ts

@@ -2,9 +2,9 @@ import type { SanomaClient } from "./client.ts";
 import type { ResolvedConfig } from "./config.ts";
 import { DATA_TABLE } from "./db.ts";
 import { applyGivens } from "./sandbox.ts";
-import { loadScenarios, type Moment } from "./scenario.ts";
+import { type Given, loadScenarios, type Moment } from "./scenario.ts";
 import { memorySecrets } from "./secret.ts";
-import { errorMessage } from "./shared.ts";
+import { DATA_VENDOR, errorMessage } from "./shared.ts";
 
 /*
  * A demo: a company repo run on its connectors' fakes, with the world its scenarios describe.
@@ -27,20 +27,43 @@ export interface DemoState {
 const states = new WeakMap<ResolvedConfig, DemoState>();
 
 /**
- * Seeds the demo instance afresh: empties the collections' table, resets the instance's fakes,
+ * A half of a demo's seed (`reseed`'s `only`): what goes into its `database` (the runs cancelled,
+ * `sanoma_data` emptied, the worlds' collection records, the moments' runs), or into its `memory`
+ * (the instance's fakes reset, the worlds' vendor objects and calls). A copy of a seeded database
+ * holds the first half but not the second, which a process over it applies to its own fakes.
+ */
+export type SeedHalf = "database" | "memory";
+
+/** Which half a world's `Given` goes to: a collection's operation the database, anything else memory; a fault both, each refusing it. */
+const halfOf = (g: Given, resolved: ResolvedConfig): SeedHalf | undefined =>
+  "fault" in g ? undefined : "op" in g && resolved.ops.get(g.op)?.vendor === DATA_VENDOR ? "database" : "memory";
+
+/**
+ * Seeds the demo instance afresh: cancels the app's unfinished runs (`cancelUnfinished`: the last
+ * seed's moments among them), empties the collections' table, resets the instance's fakes,
  * applies every world (a scenario with no `When`) to the instance (`applyGivens`: its records
  * saved through the collections' driver, its vendor objects put in the fakes), then starts each
  * moment as a sandbox run by its person, left undriven, so its first approval waits for them.
- * `resolved` is the resolution the worker and `client` run on, made with `fakes: "instance"`.
- * A world or a moment that fails is a problem in the state it returns, and the rest go on.
+ * `only` seeds one half (`SeedHalf`). `resolved` is the resolution the worker and `client` run
+ * on, made with `fakes: "instance"`. A world or a moment that fails is a problem in the state it
+ * returns, and the rest go on.
  */
-export async function reseed(client: SanomaClient, resolved: ResolvedConfig): Promise<DemoState> {
+export async function reseed(
+  client: SanomaClient,
+  resolved: ResolvedConfig,
+  { only }: { only?: SeedHalf } = {},
+): Promise<DemoState> {
   const fakes = resolved.instanceFakes;
   if (!fakes) throw new Error('reseed seeds an instance on fakes: resolve its config with `fakes: "instance"`');
+  const into = (half: SeedHalf) => only === undefined || only === half;
   // Read first, so scenarios that cannot be read at all leave the instance as it was.
   const { scenarios, errors } = await loadScenarios(resolved);
-  if (resolved.dataStore) await (await resolved.dataStore.db()).query(`TRUNCATE ${DATA_TABLE}`);
-  for (const fake of fakes.values()) fake.reset();
+  if (into("database")) {
+    // The last seed's moments, and whatever a visitor started since, end here: nothing is kept.
+    await client.cancelUnfinished();
+    if (resolved.dataStore) await (await resolved.dataStore.db()).query(`TRUNCATE ${DATA_TABLE}`);
+  }
+  if (into("memory")) for (const fake of fakes.values()) fake.reset();
   const state: DemoState = {
     seededAt: new Date().toISOString(),
     worlds: [],
@@ -49,28 +72,36 @@ export async function reseed(client: SanomaClient, resolved: ResolvedConfig): Pr
   };
   const secrets = memorySecrets();
   for (const world of scenarios.filter((s) => s.workflow === undefined)) {
+    // Each Given keeps its place in the world, so its call's idempotency key is the same in either half.
+    const kept = [...world.given.entries()].filter(([, g]) => {
+      const half = halfOf(g, resolved);
+      return half === undefined || into(half);
+    });
     try {
-      await applyGivens(world, {
-        kind: "instance",
-        drivers: resolved.drivers,
-        fakes,
-        ops: resolved.ops,
-        call: (i, opId) => ({
-          idempotencyKey: `world:${world.name}:${i}`,
-          runId: `world:${world.name}`,
-          opId,
-          attempt: 1,
-          secrets,
-          // Who its records are by: whoever it says is acting, else the runtime's own agent.
-          by: world.startedBy ?? "scenarios",
-        }),
-      });
+      await applyGivens(
+        { name: world.name, given: kept.map(([, g]) => g) },
+        {
+          kind: "instance",
+          drivers: resolved.drivers,
+          fakes,
+          ops: resolved.ops,
+          call: (i, opId) => ({
+            idempotencyKey: `world:${world.name}:${kept[i]![0]}`,
+            runId: `world:${world.name}`,
+            opId,
+            attempt: 1,
+            secrets,
+            // Who its records are by: whoever it says is acting, else the runtime's own agent.
+            by: world.startedBy ?? "scenarios",
+          }),
+        },
+      );
       state.worlds.push(world.name);
     } catch (err) {
       state.problems.push(`world "${world.name}": ${errorMessage(err)}`);
     }
   }
-  for (const s of scenarios) {
+  for (const s of into("database") ? scenarios : []) {
     if (!s.moment || s.workflow === undefined) continue;
     try {
       const runId = await client.start(s.workflow, s.input, { sandbox: s.name, startedBy: s.moment.person });

package/src/describe.ts

@@ -1,5 +1,6 @@
 import { join } from "node:path";
 import type { z } from "zod";
+import { type AppEntry, appsAt } from "./apps.ts";
 import { type LintProblem, readSource, type SourceFile } from "./ast.ts";
 import { type Field, recordSchemaOf } from "./collection.ts";
 import { connectorsOf, resolveConfig, rootOf, type SanomaConfig } from "./config.ts";
@@ -14,6 +15,7 @@ import {
   type DataFiles,
   type DeclaredCollection,
   type DeclaredResource,
+  inAppPeople,
   readDataFiles,
   type ResourceProblem,
 } from "./resources.ts";
@@ -62,8 +64,19 @@ export {
   type Bindings,
   type Rebind,
 } from "./lockfile.ts";
+// The apps under `apps/`, read without running their `app.ts`.
+export { crossAppImports, readApps, type AppEntry } from "./apps.ts";
 // What the sites call, read from their source: a workflow's Used by.
-export { readSites, type SiteCall, type SiteEntry, type SitePage, siteContentPages, siteLocales } from "./sites.ts";
+export {
+  readSites,
+  type SiteCall,
+  type SiteEntry,
+  type SitePage,
+  siteContentPages,
+  siteIcons,
+  siteLocales,
+  sitesUnder,
+} from "./sites.ts";
 // The generated SDK, `.sanoma/api.ts`: a site's `api` typed from this description.
 export { API_FILE, generateApi, writeApi, writeGenerated } from "./sdk.ts";
 // The Cedar schema, `.sanoma/schema.cedarschema`: what a company's policies are validated and decided against.
@@ -76,7 +89,10 @@ export type { ApplyInput, ApplyPlan, ApplyReport, ApplyResult, PlanAnswer, PlanS
 
 /** What a workflow is, read from its definition: enough to draw a start form and show what it may call. */
 export interface WorkflowEntry {
+  /** Its name: `<app>.<name>` for one an app's folder defines. */
   name: string;
+  /** The app whose folder defines it (`apps/<app>/workflows/`); absent for one at the root. */
+  app?: string;
   title?: string;
   /** `manual`, or the schedule it starts on (`defineWorkflow`'s `trigger`). */
   trigger: Trigger;
@@ -166,7 +182,10 @@ export interface ResourceTypeEntry {
 
 /** A collection the config declares (`collection()`). */
 export interface CollectionEntry {
+  /** Its name: `<app>.<name>` for one an app's `resources/data.ts` declares. */
   name: string;
+  /** The app whose folder declares it (`apps/<app>/resources/data.ts`); absent for one at the root. */
+  app?: string;
   title?: string;
   /** The field each record is found by. */
   key: string;
@@ -204,8 +223,14 @@ export interface ConfigDescription {
   resources: DeclaredResource[];
   /** Each binding in the lockfile (`LOCKFILE`) whose key no data file declares, as `readDataFiles` reports it. */
   orphans: DataFiles["orphans"];
-  /** What is wrong in the data files (`readDataFiles`), each at its file, relative to the root, line and column. A workflow's are on its entry. */
+  /**
+   * What is wrong in the data files (`readDataFiles`) and the apps (a folder of `apps/` that is no
+   * app, an `app.ts` that cannot be read, a collection or site at the root named as an app is),
+   * each at its file, relative to the root, line and column. A workflow's are on its entry.
+   */
   problems: ResourceProblem[];
+  /** The apps under `apps/` (`readApps`), by name. Each workflow, collection and site an app declares names it (`app`). */
+  apps: AppEntry[];
   /**
    * `defined` when the root has `policies/**\/*.cedar` (else the policy is `allowAll`), with their
    * `version`, or while they have `problems` (`policyProblems`), none: then every call and start is refused.
@@ -258,6 +283,7 @@ export function describeConfig(config: SanomaConfig): ConfigDescription {
   const collections: CollectionEntry[] = [...resolved.collections.values()]
     .map((c) => ({
       name: c.name,
+      ...(c.app !== undefined && { app: c.app }),
       ...(c.title !== undefined && { title: c.title }),
       key: c.key,
       fields: c.fields,
@@ -294,6 +320,7 @@ export function describeConfig(config: SanomaConfig): ConfigDescription {
         ];
     return {
       name: wf.name,
+      ...(wf.app !== undefined && { app: wf.app }),
       title: wf.title,
       trigger: wf.trigger,
       ...(builtin && { builtin: true as const }),
@@ -308,6 +335,7 @@ export function describeConfig(config: SanomaConfig): ConfigDescription {
   });
   workflows.sort((a, b) => a.name.localeCompare(b.name));
   addApiNameProblems(workflows, new Set(ops.map((op) => op.vendor)));
+  const { apps, problems: appProblems } = appsAt(resolved.root);
   const sites = readSites(
     resolved.root,
     { workflows, collections, ops },
@@ -323,9 +351,16 @@ export function describeConfig(config: SanomaConfig): ConfigDescription {
     vendors,
     resourceTypes,
     collections,
-    resources: dataFiles.resources,
+    // An app's people are refused (`readPeople`), so the grid and the People page never show them.
+    resources: dataFiles.resources.filter((r) => !inAppPeople(r)),
     orphans: dataFiles.orphans,
-    problems: [...dataFiles.problems, ...domainProblems(resolved.root, dataFiles.resources, resources, sites, read)],
+    problems: [
+      ...dataFiles.problems,
+      ...appProblems,
+      ...appClashes(apps, collections, sites),
+      ...domainProblems(resolved.root, dataFiles.resources, resources, sites, read),
+    ],
+    apps,
     policy: {
       defined: resolved.policy !== allowAll,
       ...(resolved.policy.version === undefined ? {} : { version: resolved.policy.version }),
@@ -335,6 +370,34 @@ export function describeConfig(config: SanomaConfig): ConfigDescription {
   };
 }
 
+/** That the root's `kind` `name`, in `file`, is named as an app is. */
+const appClash = (kind: string, name: string, file: string): ResourceProblem => ({
+  file,
+  line: 1,
+  column: 1,
+  message: `the ${kind} ${name} is named as the app apps/${name} is: name it otherwise`,
+});
+
+/**
+ * A collection or site at the root named as an app is: `api.data.<app>` and `/sites/<app>/` are
+ * the app's, so the root's would take its place.
+ */
+function appClashes(
+  apps: readonly AppEntry[],
+  collections: readonly CollectionEntry[],
+  sites: readonly SiteEntry[],
+): ResourceProblem[] {
+  const names = new Set(apps.map((app) => app.name));
+  return [
+    ...collections
+      .filter((c) => c.app === undefined && names.has(c.name))
+      .map((c) => appClash("collection", c.name, c.declared?.file ?? "resources/data.ts")),
+    ...sites
+      .filter((site) => site.app === undefined && names.has(site.name))
+      .map((site) => appClash("site", site.name, `sites/${site.name}`)),
+  ];
+}
+
 /**
  * Each site a host's `domains` (its type's `host.inputs.domains`) names that is not a public
  * site, and each domain it gives more than one site, at the host's declaration: the app serves

package/src/direct.ts

@@ -1,15 +1,19 @@
 import type { Op } from "./op.ts";
 import { isResourceOp } from "./resource.ts";
-import { DATA_VENDOR } from "./shared.ts";
+import { APPS_LIST, DATA_VENDOR } from "./shared.ts";
 
 /**
  * Whether an operation may be called directly, outside a run (`SanomaClient.call`), as the
- * person: a collection's (`data.<name>.<op>`), or a `read` that is neither the runtime's own
- * (the vendor `sanoma`) nor a resource type's (`isResourceOp`), which only drift and apply call.
+ * person: a collection's (`data.<name>.<op>`), the runtime's listing of apps (`sanoma.apps.list`,
+ * which a page calls), or a `read` that is neither the runtime's own (the vendor `sanoma`) nor a
+ * resource type's (`isResourceOp`), which only drift and apply call.
  * Anything else (an effect at a vendor) is a workflow's. The one rule: the built-in `call`
  * workflow, the SDK and the app read it, from here or from `OpEntry.direct`, and never derive it.
  */
 export const isDirect = (
-  op: Pick<Op, "vendor" | "resource" | "effect">,
+  op: Pick<Op, "id" | "vendor" | "resource" | "effect">,
   types: ReadonlyMap<string, unknown>,
-): boolean => op.vendor === DATA_VENDOR || (op.effect === "read" && op.vendor !== "sanoma" && !isResourceOp(op, types));
+): boolean =>
+  op.vendor === DATA_VENDOR ||
+  op.id === APPS_LIST ||
+  (op.effect === "read" && op.vendor !== "sanoma" && !isResourceOp(op, types));

package/src/errors.ts

@@ -51,6 +51,9 @@ export function errorCode(e: unknown): ErrorCode | undefined {
   return code !== undefined && KNOWN.has(code) ? (code as ErrorCode) : undefined;
 }
 
+/** A `DriverError`'s `vendorCode` (`no_token`, `bad_signature`), read as a property: undefined for anything else. */
+export const vendorCodeOf = (e: unknown): string | undefined => own<string>(e, "vendorCode", "string");
+
 /**
  * True when the error says trying again would only repeat it (`retryable: false`), as a
  * `DriverError` for a vendor's final answer or a ledger store for a corrupt file does. Read as

package/src/index.ts

@@ -61,6 +61,9 @@ export {
   type ResolvedConfig,
   type SanomaConfig,
 } from "./config.ts";
+// An app's `app.ts` (`defineApp`), and where the launcher finds an app's workflows and data file.
+export { type AppDefinition, type AppEntry, defineApp, readApps } from "./apps.ts";
+export { appFolders, APPS_DIR, filesUnder, kindDirs } from "./paths.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";
@@ -76,12 +79,15 @@ export {
 } from "./apply.ts";
 export { CALL_WORKFLOW, CallInput } from "./call-workflow.ts";
 export {
+  type ChangeDecision,
+  type ChangeDeploy,
   type ChangeEvent,
   ChangeFacts,
   ChangeInput,
   changeOps,
   type ChangeReport,
   type ChangeState,
+  type ChangeVerified,
   runtimeHold,
   touchesOf,
 } from "./change.ts";
@@ -125,6 +131,7 @@ export {
   ApprovalPendingError,
   errorCode,
   type ErrorCode,
+  vendorCodeOf,
   type ErrorInfo,
   type InputIssue,
   invalidInput,
@@ -161,9 +168,12 @@ export {
   type Secrets,
 } from "./secret.ts";
 export {
+  type AppMerge,
   type CheckResult,
   type Draft,
+  draftBranch,
   type DraftDiff,
+  draftOf,
   type HostEnforcement,
   type PullRequest,
   type RemoteContext,
@@ -196,6 +206,8 @@ export {
 } from "./wakeup.ts";
 export {
   type CallOptions,
+  type ChangesFilter,
+  type ChangeView,
   type ClientOptions,
   SanomaClient,
   type RunsFilter,
@@ -217,12 +229,14 @@ export {
   CHANGE_MERGE,
   CHANGE_OPEN,
   CHANGE_REVIEW,
+  CHANGE_TOPIC,
   CHANGE_WORKFLOW,
   declaresPeople,
   type PeopleResource,
   personOf,
   principalOf,
   RUNTIME_AGENTS,
+  HOST_CHECK_AGENT,
   SCHEDULE_AGENT,
   credentialReady,
   DEFAULT_SLEEP_NAME,

package/src/lint.ts

@@ -1,9 +1,9 @@
 import { realpathSync } from "node:fs";
-import { basename, dirname, join } from "node:path";
+import { basename, dirname, join, relative, sep } from "node:path";
 import { byPosition, childrenOf, type LintProblem, type Node, parsed, type SourceFile } from "./ast.ts";
 import { COLLECTIONS_FILE, readDataFile } from "./datafile.ts";
 import { constsOf, outlineBody, workflowLiterals } from "./outline.ts";
-import { inside, nearestDir, RELATIVE } from "./paths.ts";
+import { APPS_DIR, inside, nearestDir, RELATIVE } from "./paths.ts";
 // From src/ and from dist/ alike, the package's own oxlint.json: the one list of allowed names.
 import oxlint from "../oxlint.json" with { type: "json" };
 
@@ -203,11 +203,14 @@ function whyRefused(spec: string, filename: string | undefined, root: string | u
     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;
+    // The collections, which a workflow names in `uses`: the one data file the runtime imports too,
+    // the root's or an app's (`apps/<app>/resources/data.ts`), wherever the workflow is.
+    if (tree && isCollectionsFile(realPath(target), realPath(dirname(root)))) 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" : "")
+      (tree
+        ? "; of the files outside it, only resources/data.ts (the collections, the root's or an app's apps/<app>/resources/data.ts) may be imported"
+        : "")
     );
   }
   for (const [pattern, reason] of REFUSED_PACKAGES) if (pattern.test(spec)) return reason;
@@ -215,6 +218,18 @@ function whyRefused(spec: string, filename: string | undefined, root: string | u
   return "import only from `sanoma` (or `@sanoma-ai/workflows`), a `@sanoma-ai/connector-*` package, zod, or a file beside this one";
 }
 
+/**
+ * Whether `target` is a collections file of the company whose workflows' tree is in `base` (the
+ * root, or an app's `apps/<app>/`): `<root>/resources/data.ts` or `<root>/apps/<app>/resources/data.ts`.
+ */
+function isCollectionsFile(target: string, base: string): boolean {
+  const root = basename(dirname(base)) === APPS_DIR ? dirname(dirname(base)) : base;
+  const parts = relative(root, target).split(sep);
+  const [first, app] = parts;
+  const rest = first === APPS_DIR && app !== undefined ? parts.slice(2) : parts;
+  return rest.length === 2 && rest[0] === "resources" && rest[1] === COLLECTIONS_FILE;
+}
+
 /** A path's real path, or the path itself when it does not exist. */
 function realPath(path: string): string {
   try {

package/src/outline.ts

@@ -1,6 +1,6 @@
 import { childrenOf, type Node, readSource, type SourceFile } from "./ast.ts";
 import { opIdsOf, type WorkflowDefinition } from "./define.ts";
-import { childLists, DEFAULT_SLEEP_NAME, fitsOp, flatten } from "./shared.ts";
+import { childLists, DATA_VENDOR, DEFAULT_SLEEP_NAME, fitsOp, flatten, writtenName } from "./shared.ts";
 
 /**
  * What a workflow's `run` calls through `ctx`, in the order it makes the calls, with the loops,
@@ -118,8 +118,10 @@ export function outlineWithSource(
     return { outline: { error: `${file.file} could not be parsed: ${why}` }, found: false };
   }
   const consts = constsOf(file.program);
-  const fn = runIn(file.program, wf.name, consts);
-  if (!fn) return { outline: { error: `${file.file} holds no workflow named "${wf.name}"` }, found: false };
+  // An app's workflow is found by the name its file writes, without the app.
+  const name = writtenName(wf);
+  const fn = runIn(file.program, name, consts);
+  if (!fn) return { outline: { error: `${file.file} holds no workflow named "${name}"` }, found: false };
   const { nodes, problems } = outlineBody(fn, { consts, source: file.source });
   if (problems.length) {
     const lines = problems.map((p) => {
@@ -219,8 +221,8 @@ const DEFAULT_LIKE = (name: string) =>
 /** Two steps given one name, and how to tell them apart. */
 const TWICE = (name: string, fix: string) =>
   `two steps of this workflow are named "${name}": a name given is one step's, so a test or the graph can tell them apart; ${fix}`;
-/** A name given that reads as an operation's id: what an unnamed call is called. */
-const OP_ID = /^[\w-]+(\.[\w-]+){2}$/;
+/** A name given that reads as an operation's id, four segments only for an app's collection: what an unnamed call is called. */
+const OP_ID = new RegExp(String.raw`^([\w-]+(\.[\w-]+){2}|${DATA_VENDOR}(\.[\w-]+){3})$`);
 
 /** Where a function's body starts: its own statement rules, nothing of the caller's. */
 const bodyOf = (fn: Node): Where => ({ fn, inCatch: false });
@@ -424,7 +426,7 @@ export function outlineBody(
             { kind: "sleep", path, span: span(node), name: nameIn(args[1]) ?? DEFAULT_SLEEP_NAME },
           ];
         default:
-          if (members.length === 3) {
+          if (isOpPath(members)) {
             // A computed id's own name is the operation it calls, known only in a run.
             const name = nameIn(args[1]) ?? (id.includes("*") ? undefined : id);
             return [
@@ -564,6 +566,13 @@ function switchArms(node: Node): Node[] {
   return node.cases.some((c: Node) => c.test === null) ? arms : [...arms, null];
 }
 
+/**
+ * Whether a path on `ctx` is an operation's: `<vendor>.<resource>.<op>`, or an app's collection's,
+ * `data.<app>.<collection>.<op>` (a computed vendor may be either).
+ */
+const isOpPath = (members: readonly string[]): boolean =>
+  members.length === 3 || (members.length === 4 && (members[0] === DATA_VENDOR || members[0] === "*"));
+
 /** The member names from `ctx` to the callee, `*` for a computed one, when the callee is on `ctx`. */
 function ctxPath(callee: Node, ctx: string): string[] | undefined {
   const path: string[] = [];