executor.ts · Source

executor.tsapps/api/src/modules/ai/generator/executor.tsraw ← generator19,881 B← Back to the app
1/**
2 * TASK-0126 — the page-generation EXECUTOR.
3 *
4 * Runs a validated {@link GeneratePlan} SEQUENTIALLY through the existing
5 * domain services (Page / Block / Database / Relation) with the REQUESTING
6 * USER's identity — every call re-checks permissions server-side (AGENTS #7 /
7 * #19: the frontend is never trusted, the executor never elevates). It keeps
8 * a `ref → real id` map (the model's plan is ref-based, see
9 * `packages/ai/src/schemas/generate.ts`) and a `createdRefs` ROLLBACK SET
10 * (every resource this run created). A failing step stops execution, rolls
11 * back the partial tree (only what THIS run created — user-owned content is
12 * preserved), and re-throws with `failedStep`.
13 *
14 * **Permission-context hook (the spec's Security unit surface):** before every
15 * domain call the executor passes its own requester context and asserts it is
16 * the REQUESTER's (not elevated). A mocked service call with an elevated
17 * context fails this assertion (see `assertPermissionContext`).
18 *
19 * **Cancellation + timeout:** the executor runs under an `AbortSignal` (the
20 * SSE client-abort and the total-timeout watchdog both set it). Each step
21 * checks the signal first; on abort it rolls back and throws `GenerationAborted`.
22 */
23import type { PrismaClient } from "@prisma/client";
24import type { Request } from "express";
25import { ApiError } from "../../../common/errors.js";
26import { PageService } from "../../pages/page.service.js";
27import { BlockService } from "../../blocks/block.service.js";
28import { DatabaseService } from "../../databases/database.service.js";
29import { DatabaseQueryService } from "../../databases/query.service.js";
30import { logger } from "../../../common/logger.js";
31import { BLOCK_TYPES, type BlockType } from "../../../constants.js";
32import { validateCreateDatabase } from "../db-prompts.js";
33import type {
34  CreatePageCall,
35  CreateDatabaseCall,
36  CreateRelationCall,
37  GenerateBlockPayload,
38  GeneratePlan,
39  InsertBlocksCall,
40} from "@factory/ai";
41 
42/** The four tool names the executor knows (a plan step's `name`). */
43export type StepName = "createPage" | "insertBlocks" | "createDatabase" | "createRelation";
44 
45/** One resource the run created (the rollback set element). */
46export interface CreatedRef {
47  kind: "page" | "database" | "relation";
48  /** The page id (for a page / a database's host page). */
49  pageId?: string;
50  /** The database id (kind === "database"). */
51  databaseId?: string;
52  /** The relation id (kind === "relation"). */
53  relationId?: string;
54  /** The source database the relation lives on (for deleteRelation). */
55  sourceDatabaseId?: string;
56}
57 
58/** What the executor reports on success (the `done` frame's `created`). */
59export interface GeneratedResult {
60  pageId: string;
61  created: { pages: string[]; blocks: number; databases: string[]; relations: number };
62}
63 
64/** Thrown when the abort signal fired (client cancel / timeout watchdog). */
65export class GenerationAborted extends Error {
66  constructor(readonly reason: "cancelled" | "timeout") {
67    super(`generation ${reason}`);
68    this.name = "GenerationAborted";
69  }
70}
71 
72/** Thrown when a step fails (after the executor has rolled back). */
73export class GenerationStepFailed extends Error {
74  constructor(readonly failedStep: StepName, readonly error: unknown) {
75    super(`generation failed at step ${failedStep}: ${String((error as Error)?.message ?? error)}`);
76    this.name = "GenerationStepFailed";
77  }
78}
79 
80/** The requester context the executor passes to every domain call. */
81export interface ExecutorContext {
82  workspaceId: string;
83  userId: string;
84  /** The raw request (carries `req.auth` for the domain services' audit +
85   *  permission re-check). Always the REQUESTER's — never elevated. */
86  req: Request;
87  /** An optional assertion hook: called with the context before each domain
88   *  call; throws if the context is not the requester's (the unit seam for
89   *  "an elevated context fails the assertion hook"). */
90  assertContext?: (ctx: { workspaceId: string; userId: string; req: unknown }) => void;
91  /** The caller's abort signal (client cancel + the total-timeout watchdog). */
92  signal: AbortSignal;
93  /** Emit a progress frame (the service forwards it to the SSE stream). */
94  onStep: (name: StepName, status: "started" | "done", ref?: string) => void;
95  /** The expected (requester) userId the permission hook checks against. */
96  expectedUserId?: string;
97}
98 
99export interface ExecutorServices {
100  pages: PageService;
101  blocks: BlockService;
102  databases: DatabaseService;
103  records: DatabaseQueryService;
104  /** The Prisma client (the property-name → id lookup for sample records). */
105  prisma: PrismaClient;
106}
107 
108/** A plan ref's resolved resources (built as the plan runs). */
109interface RefState {
110  pageId?: string;
111  databaseId?: string;
112  blockIds: string[];
113}
114 
115export class GenerationExecutor {
116  private readonly ctx: ExecutorContext;
117  /** The model's ref → resolved real ids (the ref-resolution map). */
118  private readonly refMap = new Map<string, RefState>();
119  /** The rollback set (created in run order). */
120  private readonly created: CreatedRef[] = [];
121  /** The first page the plan created (the `done.pageId`). */
122  private rootPageId: string | null = null;
123  /** Blocks appended to the root page via an omitted-`pageRef` `insertBlocks`
124   *  (the root may carry a NAMED ref, so they can't land in the `__root__`
125   *  RefState; tracked here so the "every created block is tracked" invariant
126   *  holds even when the first page is named). */
127  private readonly rootBlockIds: string[] = [];
128  private blocksCreated = 0;
129  private cancelled = false;
130 
131  constructor(private readonly svc: ExecutorServices, ctx: ExecutorContext) {
132    this.ctx = ctx;
133  }
134 
135  /** The root (first) page id, once known (the `done.pageId`). */
136  get rootPage(): string | null {
137    return this.rootPageId;
138  }
139 
140  /** Run the plan in order; returns the generated tree on success. */
141  async execute(plan: GeneratePlan, parentId?: string | null): Promise<GeneratedResult> {
142    for (const call of plan.tools) {
143      const name: StepName = call.name;
144      this.ctx.onStep(name, "started");
145      let ref: string | undefined;
146      try {
147        this.checkAborted();
148        switch (call.name) {
149          case "createPage":
150            ref = await this.runCreatePage(call.args, parentId);
151            break;
152          case "insertBlocks":
153            ref = await this.runInsertBlocks(call.args);
154            break;
155          case "createDatabase":
156            ref = await this.runCreateDatabase(call.args);
157            break;
158          case "createRelation":
159            ref = await this.runCreateRelation(call.args);
160            break;
161        }
162        this.ctx.onStep(name, "done", ref);
163      } catch (err) {
164        // ANY failure (a step error OR an abort) rolls back the partial tree;
165        // an abort re-throws as GenerationAborted (the service emits
166        // `cancelled`/timeout), a step error as GenerationStepFailed.
167        await this.rollback();
168        if (err instanceof GenerationAborted) throw err;
169        throw new GenerationStepFailed(name, err);
170      }
171    }
172    const pageId = this.rootPageId;
173    if (!pageId) throw new GenerationStepFailed("createPage", new Error("the plan created no page"));
174    return {
175      pageId,
176      created: {
177        pages: this.created.filter((c) => c.kind === "page").map((c) => c.pageId!).filter(Boolean),
178        blocks: this.blocksCreated,
179        databases: this.created.filter((c) => c.kind === "database").map((c) => c.databaseId!).filter(Boolean),
180        relations: this.created.filter((c) => c.kind === "relation").length,
181      },
182    };
183  }
184 
185  /** Abort check (client cancel / the total-timeout watchdog). */
186  private checkAborted(): void {
187    if (this.ctx.signal.aborted) {
188      this.cancelled = true;
189      throw new GenerationAborted(this.ctx.signal.reason === "timeout" ? "timeout" : "cancelled");
190    }
191  }
192 
193  /** Every domain call goes through here: the permission-context hook fires
194   *  first (an elevated context throws), then the signal is re-checked. */
195  private assertPermissionContext(): void {
196    const ctx = { workspaceId: this.ctx.workspaceId, userId: this.ctx.userId, req: this.ctx.req };
197    // The executor's context is ALWAYS the requester's. If a test seam (or a
198    // bug) swaps in an elevated userId, the hook catches it — the spec's
199    // "a mocked service call with an elevated context fails the assertion hook".
200    if (this.ctx.expectedUserId != null && this.ctx.userId !== this.ctx.expectedUserId) {
201      throw ApiError.forbidden("Generation may not run with an elevated context.", [
202        { reason: "elevated_context" },
203      ]);
204    }
205    this.ctx.assertContext?.(ctx);
206    this.checkAborted();
207  }
208 
209  private resolveRef(ref: string | undefined, what: string): RefState {
210    const key = ref ?? "__root__";
211    const st = this.refMap.get(key);
212    if (!st) {
213      throw ApiError.unprocessable(
214        `Plan references ${what} "${ref ?? "(root)"}" before it is created.`,
215        [{ field: "ref", issue: `unknown_ref:${ref ?? "root"}` }],
216      );
217    }
218    return st;
219  }
220 
221  /** `createPage` — the first one is the root; later ones nest under the root.
222   *  An optional inline `blocks` list is inserted under the page (the same
223   *  sequential path as `insertBlocks`). */
224  private async runCreatePage(args: CreatePageCall, endpointParentId?: string | null): Promise<string> {
225    this.assertPermissionContext();
226    // The endpoint's `parentId` (a real id) is injected into the FIRST page
227    // only; later createPage calls nest under the root (the plan's own tree).
228    const isRoot = this.rootPageId == null;
229    const parentId = isRoot ? endpointParentId ?? null : this.rootPageId;
230    const refKey = args.ref ?? "__root__";
231    const created = await this.svc.pages.create(
232      this.ctx.workspaceId,
233      this.ctx.userId,
234      { title: args.title, ...(parentId ? { parentId } : {}), type: "page" },
235      this.ctx.req,
236    );
237    const pageId = (created as { id: string }).id;
238    if (isRoot) this.rootPageId = pageId;
239    const state: RefState = { pageId, blockIds: [] };
240    this.refMap.set(refKey, state);
241    this.created.push({ kind: "page", pageId });
242    // Inline blocks (the plan may carry the page's content on the create step).
243    if (args.blocks && args.blocks.length > 0) {
244      const ids = await this.insertBlockList(pageId, args.blocks);
245      state.blockIds.push(...ids);
246    }
247    return pageId;
248  }
249 
250  /** Shared block-insert path (createPage inline blocks + insertBlocks): each
251   *  block is created through BlockService (EDIT re-checked per call), chained
252   *  after the previous (the first lands at the page's natural end). */
253  private async insertBlockList(pageId: string, blocks: GenerateBlockPayload[]): Promise<string[]> {
254    let afterBlockId: string | undefined;
255    const ids: string[] = [];
256    for (const b of blocks) {
257      this.assertPermissionContext();
258      const type = (b.type as string).toUpperCase();
259      if (!(BLOCK_TYPES as readonly string[]).includes(type)) {
260        throw ApiError.unprocessable(`Plan step insertBlocks uses an unknown block type "${b.type}".`, [
261          { field: "type", issue: `unknown_block_type:${b.type}` },
262        ]);
263      }
264      const created = await this.svc.blocks.create(
265        pageId,
266        this.ctx.userId,
267        { type: type as BlockType, content: b.content, properties: {}, ...(afterBlockId ? { afterBlockId } : {}) },
268        this.ctx.req,
269      );
270      const blockId = (created as { id: string }).id;
271      ids.push(blockId);
272      afterBlockId = blockId;
273      this.blocksCreated += 1;
274    }
275    return ids;
276  }
277 
278  /** `insertBlocks` — appends the blocks under the host page. When `pageRef`
279   *  is omitted the host is the FIRST page the plan created (the schema
280   *  contract, `InsertBlocksCallSchema`). That page may carry a NAMED ref, so
281   *  an omitted pageRef must not go through the ref map — it resolves to the
282   *  root page id directly (recorded decision: a model that named its first
283   *  page `p` and then wrote an omitted pageRef previously failed with
284   *  "references page (root) before it is created"). */
285  private async runInsertBlocks(args: InsertBlocksCall): Promise<string> {
286    if (args.pageRef === undefined) {
287      const pageId = this.rootPageId;
288      if (!pageId) throw ApiError.unprocessable("Plan step insertBlocks has no host page (it runs before any createPage).", [{ field: "pageRef", issue: "no_host_page" }]);
289      const ids = await this.insertBlockList(pageId, args.blocks);
290      this.rootBlockIds.push(...ids);
291      return pageId;
292    }
293    const host = this.resolveRef(args.pageRef, "page");
294    if (!host.pageId) throw ApiError.unprocessable(`Plan step insertBlocks references "${args.pageRef}" which is not a page.`, [{ field: "pageRef", issue: "not_a_page" }]);
295    const pageId = host.pageId;
296    const ids = await this.insertBlockList(pageId, args.blocks);
297    host.blockIds.push(...ids);
298    return pageId;
299  }
300 
301  /** `createDatabase` — a child page (type:"database") under the host page,
302   *  then its properties + sample records (the domain services). The plan's
303   *  args are normalized by TASK-0124's `validateCreateDatabase` (the allowlist
304   *  + the seeded Title/Status re-declaration check + option-id generation +
305   *  sample-record value coercion) BEFORE any write (AGENTS #4 reuse). */
306  private async runCreateDatabase(args: CreateDatabaseCall): Promise<string> {
307    this.assertPermissionContext();
308    // Normalize + validate (reuses the proven TASK-0124 path; a re-declared
309    // Title/Status or a non-generatable type is rejected pre-write).
310    const parsed = validateCreateDatabase(args as unknown as Record<string, unknown>);
311    if (!parsed.ok) {
312      // A plain Error — `execute`'s catch wraps it into GenerationStepFailed
313      // ("createDatabase") + rolls back the partial tree.
314      throw new Error(parsed.feedback);
315    }
316    const normalized = parsed.value;
317    const host = args.pageRef ? this.resolveRef(args.pageRef, "page") : { pageId: this.rootPageId ?? undefined, blockIds: [] };
318    const hostPageId = host.pageId ?? this.rootPageId;
319    if (!hostPageId) throw ApiError.unprocessable("Plan step createDatabase has no host page (declare pageRef).", [{ field: "pageRef", issue: "no_host_page" }]);
320    const refKey = args.ref ?? "db";
321    const created = await this.svc.pages.create(
322      this.ctx.workspaceId,
323      this.ctx.userId,
324      { title: normalized.title, parentId: hostPageId, type: "database" },
325      this.ctx.req,
326    );
327    const page = created as { id: string; databaseId?: string };
328    const databaseId = page.databaseId!;
329    if (!databaseId) throw ApiError.unprocessable("The database page was created without a database id.", [{ field: "databaseId", issue: "missing" }]);
330    this.refMap.set(refKey, { pageId: page.id, databaseId, blockIds: [] });
331    this.created.push({ kind: "database", pageId: page.id, databaseId });
332 
333    // Properties (write-ready: type → enum, options with ids).
334    for (const p of normalized.properties) {
335      this.assertPermissionContext();
336      await this.svc.databases.createProperty(
337        databaseId,
338        this.ctx.userId,
339        {
340          name: p.name,
341          type: p.type,
342          ...(p.options ? { config: { options: p.options } } : { config: {} }),
343          ...(p.required !== undefined ? { required: p.required } : {}),
344        },
345        this.ctx.req,
346      );
347    }
348    // Sample records (property NAME → id; the seeded Title comes from the
349    // record's Title key — already coerced by validateCreateDatabase).
350    if (normalized.sampleRecords.length > 0) {
351      const allProps = await this.svc.prisma.databaseProperty.findMany({
352        where: { databaseId, deletedAt: null },
353        select: { id: true, name: true },
354      });
355      const idByName = new Map(allProps.map((ap) => [ap.name.toLowerCase(), ap.id]));
356      for (const rec of normalized.sampleRecords) {
357        this.assertPermissionContext();
358        const title = typeof rec.Title === "string" ? rec.Title : undefined;
359        const properties: Record<string, unknown> = {};
360        for (const [name, value] of Object.entries(rec)) {
361          if (name === "Title") continue;
362          const pid = idByName.get(name.toLowerCase());
363          if (pid) properties[pid] = value;
364        }
365        await this.svc.records.createRecord(databaseId, this.ctx.userId, { title, properties, links: {} }, this.ctx.req);
366      }
367    }
368    return databaseId;
369  }
370 
371  /** `createRelation` — links the plan's own database to a target database
372   *  the plan also generated (both refs resolve to real database ids). */
373  private async runCreateRelation(args: CreateRelationCall): Promise<string> {
374    this.assertPermissionContext();
375    const src = this.resolveRef(args.databaseRef, "database");
376    const tgt = this.resolveRef(args.targetPageRef, "database");
377    if (!src.databaseId) throw ApiError.unprocessable(`Plan step createRelation references "${args.databaseRef}" which is not a database.`, [{ field: "databaseRef", issue: "not_a_database" }]);
378    if (!tgt.databaseId) throw ApiError.unprocessable(`Plan step createRelation references "${args.targetPageRef}" which is not a database.`, [{ field: "targetPageRef", issue: "not_a_database" }]);
379    const created = await this.svc.databases.createRelation(
380      src.databaseId,
381      this.ctx.userId,
382      { name: args.name, targetDatabaseId: tgt.databaseId, twoWay: true, cardinality: "MANY_TO_MANY" },
383      this.ctx.req,
384    );
385    const relationId = (created as { id: string }).id;
386    this.created.push({ kind: "relation", relationId, sourceDatabaseId: src.databaseId });
387    return relationId;
388  }
389 
390  /**
391   * Roll back the partial tree (only what THIS run created, in reverse
392   * creation order). Uses the domain delete paths:
393   *   - relations  → `databases.deleteRelation` (EDIT-level);
394   *   - databases  → `databases.remove` (hard, cascades its page + records +
395   *                  blocks; FULL_ACCESS — falls back to `pages.trash` for an
396   *                  EDIT-only user so the tree is at least hidden);
397   *   - pages      → `pages.trash` (EDIT-level, cascades descendant pages).
398   * Best-effort: a single rollback failure is logged, not thrown (the primary
399   * failure is already in flight). User-owned content is NEVER touched.
400   */
401  async rollback(): Promise<void> {
402    if (this.created.length === 0) return;
403    const reversed = [...this.created].reverse();
404    for (const ref of reversed) {
405      try {
406        if (ref.kind === "relation" && ref.relationId && ref.sourceDatabaseId) {
407          await this.svc.databases.deleteRelation(ref.sourceDatabaseId, ref.relationId, this.ctx.userId, this.ctx.req);
408        } else if (ref.kind === "database" && ref.databaseId) {
409          try {
410            await this.svc.databases.remove(ref.databaseId, this.ctx.userId, this.ctx.req);
411          } catch {
412            // EDIT-only (no FULL_ACCESS) → soft-trash the database page so the
413            // partial tree is hidden (the normal user-deletion path).
414            if (ref.pageId) await this.svc.pages.trash(ref.pageId, this.ctx.userId, this.ctx.req);
415          }
416        } else if (ref.kind === "page" && ref.pageId) {
417          await this.svc.pages.trash(ref.pageId, this.ctx.userId, this.ctx.req);
418        }
419      } catch (err) {
420        logger.warn(`generation rollback failed for ${ref.kind}:${ref.pageId ?? ref.databaseId ?? ref.relationId}: ${(err as Error).message}`);
421      }
422    }
423    // Reset (a retried run starts clean; the idempotency key keeps it from
424    // double-creating the SAME logical generation).
425    this.created.length = 0;
426    this.refMap.clear();
427    this.rootPageId = null;
428    this.rootBlockIds.length = 0;
429    this.blocksCreated = 0;
430  }
431}
432