primitive-functions 0.2.0-alpha.8 → 0.2.0-alpha.9

package/index.d.ts

@@ -32,8 +32,15 @@ export interface FunctionUser {
  * that the fire path does not set.
  */
 export type FunctionTrigger =
-  /** An HTTP invocation: the caller is `ctx.user`. */
-  | { kind: "http" }
+  /**
+   * An HTTP invocation: the caller is `ctx.user`.
+   *
+   * `runKey` is the key a `start` was coalesced by (#3562) — what you
+   * passed as `runKey` to make the run a singleton — and null when the
+   * start named none, or when the call was an `invoke`, which coalesces
+   * nothing.
+   */
+  | { kind: "http"; runKey: string | null }
   /** A verified webhook delivery to the function's own key. */
   | {
       kind: "webhook";
@@ -56,8 +63,6 @@ export type FunctionTrigger =
       /** Present, and true, only on the diagnostic fire: nothing was scheduled. */
       manual?: true;
     }
-  /** A write to a watched database type. */
-  | { kind: "database"; databaseId: string; databaseType: string }
   /**
    * A DSL workflow's `workflow.call` step reached this function (#3288).
    *
@@ -71,19 +76,25 @@ export type FunctionTrigger =
    * Another function started this one with `ctx.functions.start` (#3280).
    *
    * `functionKey` names the PARENT, and `runId` its run — null when the
-   * parent was a request invocation over HTTP, which writes no run row, or a
-   * database-change fire, which writes none either.
+   * parent was a request invocation over HTTP, which writes no run row.
+   * `runKey` is the key the parent's start named, or null (#3562).
    */
-  | { kind: "function"; functionKey: string; runId: string | null }
+  | {
+      kind: "function";
+      functionKey: string;
+      runId: string | null;
+      runKey: string | null;
+    }
   /**
    * An admin ran this function as the SYSTEM, from outside any trigger
    * (#3448) — `primitive functions invoke --as system`.
    *
    * `ctx.user` is null and the code runs with the app's system authority, as
    * it does for a cron or webhook fire. `userId` names the admin who asked:
-   * attribution, never the principal the code runs as.
+   * attribution, never the principal the code runs as. `runKey` is the key
+   * the admin's start named, or null (#3562).
    */
-  | { kind: "manual"; userId: string };
+  | { kind: "manual"; userId: string; runKey: string | null };
 
 /** The result shape of an operation that answers in response headers. */
 export interface HeaderResult {
@@ -717,6 +728,12 @@ export interface FunctionApi {
     }): Promise<any>;
   };
   "documents": {
+    /** `documents.abortIngest` — POST /documents/{documentId}/ingest/{sessionId}/abort. Abort a bulk-load session before its swap */
+    "abortIngest"(args: {
+      "documentId": string | number;
+      "sessionId": string | number;
+      body: unknown;
+    }): Promise<any>;
     /** `documents.addTag` — POST /documents/{documentId}/tags. Add a tag to a document */
     "addTag"(args: {
       "documentId": string | number;
@@ -794,10 +811,21 @@ export interface FunctionApi {
     "clearLinkAccess"(args: {
       "documentId": string | number;
     }): Promise<any>;
+    /** `documents.commitIngest` — POST /documents/{documentId}/ingest/{sessionId}/commit. Commit a bulk-load session: freeze its manifest and apply it */
+    "commitIngest"(args: {
+      "documentId": string | number;
+      "sessionId": string | number;
+      body: unknown;
+    }): Promise<any>;
     /** `documents.create` — POST /documents. Create a new document */
     "create"(args: {
       body: unknown;
     }): Promise<any>;
+    /** `documents.createIngest` — POST /documents/{documentId}/ingest. Open a bulk-load session on a large document */
+    "createIngest"(args: {
+      "documentId": string | number;
+      body: unknown;
+    }): Promise<any>;
     /** `documents.createWithAlias` — POST /documents/create-with-alias. Create a document and bind it to an alias */
     "createWithAlias"(args: {
       body: unknown;
@@ -855,6 +883,11 @@ export interface FunctionApi {
     "getImportChainStatus"(args: {
       "documentId": string | number;
     }): Promise<any>;
+    /** `documents.getIngest` — GET /documents/{documentId}/ingest/{sessionId}. One bulk-load session's status */
+    "getIngest"(args: {
+      "documentId": string | number;
+      "sessionId": string | number;
+    }): Promise<any>;
     /** `documents.getLinkAccess` — GET /documents/{documentId}/link-access. Get the document's "anyone with the link" access level */
     "getLinkAccess"(args: {
       "documentId": string | number;
@@ -913,6 +946,12 @@ export interface FunctionApi {
     "listGroupPermissions"(args: {
       "documentId": string | number;
     }): Promise<any>;
+    /** `documents.listIngests` — GET /documents/{documentId}/ingest. List a large document's bulk-load sessions, newest first */
+    "listIngests"(args: {
+      "documentId": string | number;
+      "limit"?: string | number | boolean;
+      "cursor"?: string | number | boolean;
+    }): Promise<any>;
     /** `documents.listPendingInvitations` — GET /documents/{documentId}/pending-invitations. List a document's pending (deferred) invitations */
     "listPendingInvitations"(args: {
       "documentId": string | number;
@@ -1019,6 +1058,12 @@ export interface FunctionApi {
       "documentId": string | number;
       body: unknown;
     }): Promise<any>;
+    /** `documents.uploadIngestChunk` — POST /documents/{documentId}/ingest/{sessionId}/chunks. Upload one chunk of a bulk-load session's artifact */
+    "uploadIngestChunk"(args: {
+      "documentId": string | number;
+      "sessionId": string | number;
+      body: FormData | ArrayBuffer | Uint8Array | string;
+    }): Promise<any>;
     /** `documents.validateAccess` — POST /documents/{documentId}/validate-access. Resolve the caller's effective access level for a document */
     "validateAccess"(args: {
       "documentId": string | number;
@@ -1048,7 +1093,7 @@ export interface FunctionApi {
       "cursor"?: string | number | boolean;
       "runId"?: string | number | boolean;
     }): Promise<any>;
-    /** `functions.start` — POST /functions/{functionKey}/start. Start a task function from inside another server function */
+    /** `functions.start` — POST /functions/{functionKey}/start. Start a server function as a task run */
     "start"(args: {
       "functionKey": string | number;
       body?: unknown;
@@ -1339,8 +1384,8 @@ export type DatabaseModels<K extends string> = K extends keyof DatabaseSchemas
  * The app's functions, key by key — EMPTY here and filled by the declaration
  * `primitive config push` writes into the config tree's `functions/`
  * directory (`primitive-function-types.d.ts`): each key's declared input and
- * output types (from its `inputSchema` and `outputSchema`) and its mode. It
- * is what types `defineFunction("<key>", handler)`.
+ * output types, from its `inputSchema` and `outputSchema`. It is what types
+ * `defineFunction("<key>", handler)`.
  */
 export interface FunctionSchemas {}
 
@@ -1368,20 +1413,6 @@ export type FunctionOutput<K extends string> = K extends keyof FunctionSchemas
     : any
   : any;
 
-/**
- * A declared function's mode, fixed at generation time.
- *
- * `"any"` — the default when the authored file names no mode (#3454) — takes
- * EITHER runner and the caller picks at call time; `"request"` and `"task"`
- * lock it to one. An UNDECLARED key is the whole union, because nothing has
- * said which of the three it is.
- */
-export type FunctionMode<K extends string> = K extends keyof FunctionSchemas
-  ? FunctionSchemas[K] extends { mode: infer M }
-    ? M
-    : "request" | "task" | "any"
-  : "request" | "task" | "any";
-
 /**
  * The model names one database type addresses — its own, or any name at all
  * for a type that declares no schema (the DO is schemaless, so a grant on such
@@ -1551,6 +1582,26 @@ export interface DocumentQueryOptions {
  * One document model, bound to its document and its model name — a thin
  * binding over `ctx.api.documents.records.*` with the route's own shapes.
  */
+/**
+ * One op of a document `batch` — the `documents.records.bulk` blob's shape,
+ * typed to this handle's model (#3455).
+ *
+ * `model` is NOT a member: the handle already names it and assigns it last, so
+ * a multi-model blob stays on the raw `ctx.api.documents.records.bulk`
+ * operation rather than becoming a second way to say the same thing.
+ */
+export type DocumentBatchOp<TRow> =
+  | { action: "create" | "patch"; id: string; data: Partial<TRow>; precondition?: Record<string, unknown> }
+  | { action: "delete"; id: string; precondition?: Record<string, unknown> };
+
+/** What `documents.records.bulk` answers: the blob's aggregate effect. */
+export interface DocumentBulkResult {
+  applied: number;
+  added: Array<{ model: string; id: string }>;
+  updated: Array<{ model: string; id: string }>;
+  deleted: number;
+}
+
 export interface DocumentModelHandle<TRow> {
   query(options?: DocumentQueryOptions): Promise<{ items: TRow[]; hasMore: boolean; nextCursor?: string }>;
   count(options?: { filter?: Record<string, unknown> | string }): Promise<{ count: number }>;
@@ -1558,6 +1609,15 @@ export interface DocumentModelHandle<TRow> {
   save(body: { id: string; data: Partial<TRow>; options?: Record<string, unknown> }): Promise<{ record: TRow }>;
   patch(recordId: string, body: { data: Partial<TRow>; options?: Record<string, unknown> }): Promise<{ record: TRow }>;
   delete(recordId: string): Promise<{ deleted: boolean }>;
+  /**
+   * Apply an ordered blob of this model's ops in ONE transaction — all of it
+   * commits or none of it does, and connected clients see one update.
+   *
+   * One model's ops, by construction: every op's `model` is this handle's.
+   * A blob that spans models is the raw `ctx.api.documents.records.bulk`
+   * operation's job.
+   */
+  batch(ops: Array<DocumentBatchOp<TRow>>): Promise<DocumentBulkResult>;
 }
 
 /** A document, addressed once; its models are typed from `DocumentSchemas`. */
@@ -1785,9 +1845,45 @@ export interface FunctionStartResult {
 }
 
 export interface FunctionContext {
-  /** The HTTP caller, or null for a webhook, cron or database-change fire. */
+  /** The HTTP caller, or null for a webhook or cron fire. */
   user: FunctionUser | null;
   trigger: FunctionTrigger;
+  /**
+   * Which RUNTIME is hosting this code — #3482.
+   *
+   * Beside `trigger`, which says which DOOR fired, and they are different
+   * questions: an HTTP call is whichever runtime the caller chose
+   * (`invoke` or `start`), a cron fire is always a task and a webhook
+   * delivery is always a request.
+   *
+   * To REFUSE a runtime rather than branch on it, call
+   * `assertRuntime("task")` — at module scope to refuse it outright, or in
+   * the handler to refuse one call.
+   */
+  runtime: "request" | "task";
+  /**
+   * The RUN this invocation belongs to, or null — #3562.
+   *
+   * Set under the task runtime (every slice of the run, the first and every
+   * resume) and for a webhook-fired request run, which writes a row. Null for
+   * an HTTP `invoke`, which writes no run row at all.
+   *
+   * It is the deterministic OWNER a task run presents to re-take its own
+   * lease: `ctx.api.locks.tryAcquire({ body: { key, ttlMs, owner: ctx.runId } })`
+   * succeeds for the run that already holds the key, with a fresh handle.
+   */
+  runId: string | null;
+  /**
+   * The SLICE of the run this code is running in, or null — #3562.
+   *
+   * The same identifier `primitive functions runs` and the run-status
+   * route's `slice.sliceId` report. A task run is a sequence of slices: it
+   * changes when the run hibernates and wakes, which is how a handler can tell
+   * a resume from a first pass.
+   *
+   * Null under the request runtime: a request invocation is not a slice.
+   */
+  sliceId: string | null;
   api: FunctionApi;
   /**
    * A typed handle over one database. The second argument is the database TYPE
@@ -1949,7 +2045,7 @@ export interface FunctionContext {
  * clock: `do` executes the body inline (there is no engine to memoize into,
  * and nothing is replayed); `sleep` and `sleepUntil` REALLY wait when the
  * remaining request budget covers the duration, and otherwise fail the
- * invocation with `errorCode: "FUNCTION_STEP_NEEDS_TASK"` saying to start the
+ * invocation with `errorCode: "FUNCTION_RUNTIME_REFUSED"` saying to start the
  * function as a task; `waitForEvent` fails the same way, because nothing can
  * deliver an event to an invocation that has to return now. The thrown error's
  * `name` is `STEP_NOT_AVAILABLE` in every case, so a body that catches it
@@ -1972,6 +2068,48 @@ export interface FunctionStep {
 
 export declare const SDK_STUB_VERSION: string;
 
+/**
+ * Thrown by `assertRuntime` when this function is running under the other
+ * runtime — #3482.
+ *
+ * The platform settles it as `status: "failed"` with
+ * `errorCode: "FUNCTION_RUNTIME_REFUSED"`, on a request invocation's
+ * envelope and on a task run's row and record alike.
+ */
+export declare class FunctionRuntimeError extends Error {
+  name: "FUNCTION_RUNTIME_REFUSED";
+  /** The runtime this invocation is actually running under. */
+  runtime: "request" | "task";
+  /** The runtime the function asked for. */
+  required: "request" | "task";
+}
+
+/**
+ * Refuse the runtime this function was not written for — #3482.
+ *
+ * A function is a function and the caller picks the runtime at each call, so
+ * nothing in config says which one a function may run under. This is the lock,
+ * and it lives in the one place that can always be right about the code:
+ *
+ * ```ts
+ * import { assertRuntime } from "primitive-functions";
+ *
+ * // At module scope: this function is never runnable inside a request.
+ * assertRuntime("task");
+ *
+ * export default async function (input, ctx, step) {
+ *   await step.sleep("cool-off", "1 hour");
+ *   return { ok: true };
+ * }
+ * ```
+ *
+ * Returns when the runtimes match; otherwise throws
+ * {@link FunctionRuntimeError}, which the platform settles as
+ * `status: "failed"` with `errorCode: "FUNCTION_RUNTIME_REFUSED"` and a
+ * message naming both runtimes and the verb that takes the one required.
+ */
+export declare function assertRuntime(required: "request" | "task"): void;
+
 /**
  * The handler a function exports, typed for one declared key.
  *
@@ -2204,6 +2342,12 @@ export declare const stepPolicy: {
   database: StepPolicy;
 };
 
+// Every member the three runtime copies put on their own default export — the
+// platform's `sdk-core.ts`, the published stub and the CLI's collect stub —
+// and nothing else. A helper the module hands a default import but does not
+// declare here is one an author cannot call without the compiler refusing it
+// (#3482 CR3482-002); `tests/api/spec/function-profile.test.ts` holds the four
+// lists equal and compiles a default import against them.
 declare const _default: {
   SDK_STUB_VERSION: string;
   defineFunction: typeof defineFunction;
@@ -2211,5 +2355,7 @@ declare const _default: {
   defineMutation: typeof defineMutation;
   pMap: typeof pMap;
   ulid: typeof ulid;
+  assertRuntime: typeof assertRuntime;
+  FunctionRuntimeError: typeof FunctionRuntimeError;
 };
 export default _default;

package/index.js

@@ -82,6 +82,34 @@ export const stepPolicy = {
   database: null,
 };
 
+/**
+ * The runtime refusal's error class — #3482.
+ *
+ * Carried rather than thrown from: a function narrows a `catch` with
+ * `instanceof FunctionRuntimeError`, and a class that threw on construction
+ * would break a build that only type-checks. The platform copy is the one that
+ * is ever really thrown.
+ */
+export class FunctionRuntimeError extends Error {
+  constructor(message, runtime, required) {
+    super(message);
+    this.name = "FUNCTION_RUNTIME_REFUSED";
+    this.runtime = runtime;
+    this.required = required;
+  }
+}
+
+/**
+ * Refuse the runtime this function was not written for — #3482.
+ *
+ * The platform copy compares the required runtime against the one the isolate
+ * declared. This one refuses, loudly, like every other function here: an
+ * assertion answered outside a sandbox would be answering about nothing.
+ */
+export function assertRuntime() {
+  throw new Error(NOT_PROVIDED);
+}
+
 export default {
   SDK_STUB_VERSION,
   defineFunction,
@@ -89,4 +117,6 @@ export default {
   defineMutation,
   pMap,
   ulid,
+  assertRuntime,
+  FunctionRuntimeError,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "primitive-functions",
-  "version": "0.2.0-alpha.8",
+  "version": "0.2.0-alpha.9",
   "description": "The module a Primitive server function imports. Supplied by the platform at invoke time; reserved here so the name is ours before the runtime lands.",
   "license": "UNLICENSED",
   "author": "Primitive LLC",