Method create

packages/storage/src/task-ledger-store.ts:188–259

(
    sessionId: string,
    drafts: unknown,
    context: TaskLedgerMutationContext = {},
  )

  }

  async create(
    sessionId: string,
    drafts: unknown,
    context: TaskLedgerMutationContext = {},
  ): Promise<{ created: Task[]; total: number }> {
    assertSafeSessionId(sessionId);
    if (!Array.isArray(drafts) || drafts.length === 0) {
      throw new Error('Task creation requires at least one task draft');
    }
    // Front-door the per-batch cap before generating ids or normalizing drafts:
    // a single call can never add more than the absolute ledger cap, and rejecting
    // here avoids generating N uuids for a batch the write-queue total check
    // would refuse anyway. The total (existing + new) cap is still enforced
    // inside the serialized mutate callback below.
    if (drafts.length > TASK_LEDGER_MAX_TASKS) {
      throw new Error(
        `Task creation batch of ${drafts.length} tasks exceeds the ${TASK_LEDGER_MAX_TASKS}-task per-batch cap; split the work into smaller calls.`,
      );
    }
    const normalizedDrafts = drafts.map((draft) => {
      const normalized = normalizeCreateTaskInput(draft);
      if (!normalized.ok) throw new Error(normalized.message);
      return normalized.value;
    });
    const created: Task[] = [];
    // Cap check runs inside the serialized mutate callback (after reading the
    // current ledger) so concurrent creates cannot race past the limit, and a
    // rejected create never touches the file.
    const all = await this.mutate(
      sessionId,
      (tasks) => {
        if (tasks.length + normalizedDrafts.length > TASK_LEDGER_MAX_TASKS) {
          throw new Error(
            `Task ledger is limited to ${TASK_LEDGER_MAX_TASKS} tasks total per session ` +
              `(currently ${tasks.length}, adding ${normalizedDrafts.length}). This is a hard runaway guard on the ` +
              'total count — completed or cancelled tasks still count, so batch related work into fewer, ' +
              'coarser tasks instead.',
          );
        }
        const now = Date.now();
        for (const draft of normalizedDrafts) {
          const parent = draft.parentId ? findTaskByRef(tasks, draft.parentId) : undefined;
          if (draft.parentId && !parent) throw new Error(`No such parent task: ${draft.parentId}`);
          if (parent && isTerminalTaskStatus(parent.status)) {
            throw new Error(`Cannot create a child under terminal task ${parent.key}`);
          }
          const task: Task = {
            id: randomUUID(),
            key: nextTaskKey([...tasks, ...created], parent),
            subject: draft.subject,
            status: 'pending',
            createdAt: now,
            updatedAt: now,
            ...(parent ? { parentId: parent.id } : {}),
            ...(ownerFromContext(context) ? { owner: ownerFromContext(context) } : {}),
          };
          created.push(task);
        }