primitive-functions 0.2.0-alpha.7 → 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,10 +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;
+      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. `runKey` is the key
+   * the admin's start named, or null (#3562).
    */
-  | { kind: "function"; functionKey: string; runId: string | null };
+  | { kind: "manual"; userId: string; runKey: string | null };
 
 /** The result shape of an operation that answers in response headers. */
 export interface HeaderResult {
@@ -708,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;
@@ -785,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;
@@ -846,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;
@@ -862,6 +904,11 @@ export interface FunctionApi {
     "getSchema"(args: {
       "documentId": string | number;
     }): Promise<any>;
+    /** `documents.getSnapshot` — GET /documents/{documentId}/snapshots/{buildId}. One snapshot build with its verification result */
+    "getSnapshot"(args: {
+      "documentId": string | number;
+      "buildId": string | number;
+    }): Promise<any>;
     /** `documents.getStats` — GET /documents/{documentId}/stats. Document statistics (record/model/blob counts, approximate size) */
     "getStats"(args: {
       "documentId": string | number;
@@ -899,10 +946,22 @@ 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;
     }): Promise<any>;
+    /** `documents.listSnapshots` — GET /documents/{documentId}/snapshots. List a large document's snapshot builds, newest first */
+    "listSnapshots"(args: {
+      "documentId": string | number;
+      "limit"?: string | number | boolean;
+      "cursor"?: string | number | boolean;
+    }): Promise<any>;
     /** `documents.open` — POST /documents/open. Open a document for collaboration (resolves access + alias) */
     "open"(args: {
       body: unknown;
@@ -999,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;
@@ -1016,13 +1081,19 @@ export interface FunctionApi {
       "functionKey": string | number;
       body?: unknown;
     }): Promise<any>;
+    /** `functions.invokeAsSystem` — POST /functions/{functionKey}/invoke-as-system. Invoke a server function as the system, with no caller */
+    "invokeAsSystem"(args: {
+      "functionKey": string | number;
+      body?: unknown;
+    }): Promise<any>;
     /** `functions.logs` — GET /functions/{functionKey}/logs. List a server function's invocation logs, newest first */
     "logs"(args: {
       "functionKey": string | number;
       "limit"?: string | number | boolean;
       "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;
@@ -1313,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 {}
 
@@ -1342,13 +1413,6 @@ export type FunctionOutput<K extends string> = K extends keyof FunctionSchemas
     : any
   : any;
 
-/** A declared function's mode, fixed at generation time. */
-export type FunctionMode<K extends string> = K extends keyof FunctionSchemas
-  ? FunctionSchemas[K] extends { mode: infer M }
-    ? M
-    : "request" | "task"
-  : "request" | "task";
-
 /**
  * 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
@@ -1358,9 +1422,38 @@ export type DatabaseModelNames<TModels> = [keyof TModels] extends [never]
   ? string
   : keyof TModels & string;
 
+/**
+ * A row as the platform HANDS IT BACK: whatever the schema declared, plus the
+ * record identity the platform owns (#3450).
+ *
+ * Every stored record has an `id`. A save that arrives without one is given a
+ * ULID, a projection always keeps it, and `delete` and `patch` take nothing
+ * else — so a function that queries a model and then moves one of its rows
+ * needs the id of the row it just read. A schema is free to say nothing about
+ * that field, and most do; the identity is the platform's, not the schema's,
+ * so it is added here rather than rendered into each declaration.
+ *
+ * A declared `id` is REPLACED, never intersected: one declared optional would
+ * stay optional on a read row it is always present on, and one declared with
+ * some other type would intersect to `never` and be unusable. The platform
+ * stamps a string whatever the schema says.
+ *
+ * An `any` row stays `any` — `DatabaseHandle<any>` is `defineQuery`'s default
+ * handle, and turning its rows into an object with one known member would
+ * narrow code that was deliberately left open.
+ *
+ * Writes are untouched: every one of them takes `Partial<TRow>`, so a row a
+ * function BUILDS still needs no id.
+ */
+export type PlatformRow<TRow> = 0 extends 1 & TRow
+  ? TRow
+  : Omit<TRow, "id"> & { id: string };
+
 /** One model's row shape, open when the type declares no schema. */
 export type DatabaseModelRow<TModels, M extends string> =
-  M extends keyof TModels ? TModels[M] : Record<string, unknown>;
+  M extends keyof TModels
+    ? PlatformRow<TModels[M]>
+    : Record<string, unknown> & { id: string };
 
 /**
  * One model of one database, scoped: the `modelName` every records call needs
@@ -1404,6 +1497,29 @@ export interface DatabaseModelHandle<TRow> {
   count(body?: ModelScopedBody): Promise<any>;
   aggregate(body: ModelScopedBody): Promise<any>;
   save(body: ModelScopedBody<{ id?: string; data: Partial<TRow>; [key: string]: unknown }>): Promise<any>;
+  /**
+   * Change some fields of ONE row — `databases.records.patch`, with this
+   * handle's model bound (#3450).
+   *
+   * The record id is positional and the body may not carry another, for the
+   * same reason it may not name another model: the runtime assigns both LAST,
+   * so a body that appeared to choose either would be a lie about which row
+   * moved. `condition`, `stringSets` and the rest of the operation's own keys
+   * pass through untouched.
+   */
+  patch(
+    recordId: string,
+    body: ModelScopedBody<{ data: Partial<TRow>; id?: never; [key: string]: unknown }>
+  ): Promise<any>;
+  /**
+   * Remove ONE row by the id a read handed back — `databases.records.delete`,
+   * with this handle's model bound (#3450). An optional `condition` makes it
+   * conditional, and travels untouched.
+   */
+  delete(
+    recordId: string,
+    body?: ModelScopedBody<{ condition?: Record<string, unknown>; id?: never }>
+  ): Promise<any>;
   /** Several writes to THIS model in one request; the binding is per item. */
   batch(body: {
     operations: Array<ModelBatchOperation<TRow>>;
@@ -1445,10 +1561,15 @@ export type DocumentModelNames = [keyof DocumentSchemas] extends [never]
   ? string
   : keyof DocumentSchemas & string;
 
-/** A document model's row shape, or an open record for an undeclared schema. */
+/**
+ * A document model's row shape, or an open record for an undeclared schema —
+ * carrying the platform's record identity either way (#3450), by the same rule
+ * and for the same reason as a database row: the records DO is one
+ * implementation, and `patch` and `delete` here take an id too.
+ */
 export type DocumentModelRow<M extends string> = M extends keyof DocumentSchemas
-  ? DocumentSchemas[M]
-  : Record<string, unknown>;
+  ? PlatformRow<DocumentSchemas[M]>
+  : Record<string, unknown> & { id: string };
 
 /** The options a document model read takes: a filter object (or its JSON), a page size, a cursor. */
 export interface DocumentQueryOptions {
@@ -1461,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 }>;
@@ -1468,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`. */
@@ -1517,15 +1667,94 @@ export interface PromptRunArgs {
   configId?: string;
 }
 
-/** The member execute envelope, unchanged on the function path. */
-export interface PromptRunResult {
+/**
+ * The app's PROMPTS — EMPTY here and filled by the declaration
+ * `primitive config push` writes into the config tree's `functions/` directory
+ * (`primitive-prompt-types.d.ts`, from the tree's `prompts/*.toml`). A prompt
+ * that declares an `outputSchema` carries `{ output: <Key>PromptOutput }`; one
+ * that declares none carries `{}`, so reading `parsed.field` on it is a
+ * compile error rather than a runtime `undefined`.
+ */
+export interface PromptSchemas {}
+
+/** The keys `ctx.prompts.run` accepts — every declared one, or `string` before a push. */
+export type PromptKeys = [keyof PromptSchemas] extends [never]
+  ? string
+  : keyof PromptSchemas & string;
+
+/** One prompt's declared output type, or `unknown` where none is declared. */
+export type PromptOutput<K extends string> = K extends keyof PromptSchemas
+  ? PromptSchemas[K] extends { output: infer O }
+    ? O
+    : unknown
+  : unknown;
+
+/**
+ * Why a prompt's own answer was refused — #3330. Never set on a PROVIDER
+ * failure, which is what makes "the model returned the wrong shape"
+ * distinguishable from "the model failed".
+ */
+export type PromptOutputErrorCode =
+  | "PROMPT_OUTPUT_NOT_JSON"
+  | "PROMPT_OUTPUT_SCHEMA_VIOLATION";
+
+/** A prompt that declares an output shape, when the answer matched it. */
+export interface PromptRunSuccess<TParsed> {
+  success: true;
+  output: string;
+  /** The parsed, validated answer — no caller-side `JSON.parse` (#3330). */
+  parsed: TParsed;
+  error?: null;
+  errorCode?: null;
+  metrics?: Record<string, unknown>;
+  configId: string;
+}
+
+/**
+ * The failure arm, whichever failed. `errorCode` is set for a SHAPE failure
+ * and absent for a provider one; `output` carries the text either way, which
+ * is where the model's own value lives — a validation `error` names paths and
+ * schema constraints only.
+ */
+export interface PromptRunFailure {
+  success: false;
+  output: string;
+  error: string | null;
+  errorCode?: PromptOutputErrorCode | null;
+  parsed?: undefined;
+  metrics?: Record<string, unknown>;
+  configId: string;
+}
+
+/** The envelope for a key whose declaration says nothing about its output. */
+export interface PromptRunOpenResult {
   success: boolean;
   output: string;
+  /**
+   * Present when the config that ran declares `outputFormat = "json"` and the
+   * text parsed. Untyped: nothing declared its shape.
+   */
+  parsed?: unknown;
   error?: string | null;
+  errorCode?: PromptOutputErrorCode | null;
   metrics?: Record<string, unknown>;
   configId: string;
 }
 
+/**
+ * The member execute envelope, plus what the prompt's own declaration adds.
+ *
+ * For a key whose `prompts/<key>.toml` declares an `outputSchema`, this is a
+ * discriminated union: narrow on `success` and `parsed` is the declared type,
+ * required. For every other key — and in a tree that has not pushed — it is
+ * the open shape, with `parsed` optional and `unknown`.
+ */
+export type PromptRunResult<K extends string = string> = K extends keyof PromptSchemas
+  ? PromptSchemas[K] extends { output: infer O }
+    ? PromptRunSuccess<O> | PromptRunFailure
+    : PromptRunOpenResult
+  : PromptRunOpenResult;
+
 /** What a send delivered to. */
 export interface SendResult {
   /** Unique live connections the frame was sent to. Zero is a success. */
@@ -1616,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
@@ -1673,14 +1938,33 @@ export interface FunctionContext {
     ): Promise<FunctionStartResult>;
   };
   /**
-   * Run one of the app's prompts, under a `prompt:<key>` grant (#3183).
+   * Run one of the app's prompts, with nothing to declare (#3183, #3279).
    *
    * The prompt's `accessRule` is not consulted — it states which MEMBERS may
-   * execute the prompt from a client, and the grant is what authorizes this
-   * call. The provider request is bounded by the invocation's own deadline.
+   * execute the prompt from a client, and the invocation gate is what
+   * authorized this call. The provider request is bounded by the invocation's
+   * own deadline.
+   *
+   * TYPED BY KEY (#3330). Where `prompts/<key>.toml` declares an
+   * `outputSchema`, the platform parses the answer, validates it against that
+   * schema and hands it back as `parsed`, typed — so the shape is written once
+   * in TOML instead of restated as a `JSON.parse` at every call site. Where
+   * only the config that ran declares `outputFormat = "json"`, `parsed` is
+   * present but `unknown`. Where neither is declared the envelope is exactly
+   * what it has always been.
+   *
+   * A shape the declaration refuses is `success: false` with an `errorCode`
+   * (`PROMPT_OUTPUT_NOT_JSON` or `PROMPT_OUTPUT_SCHEMA_VIOLATION`) and the
+   * text still in `output`; a PROVIDER failure has `error` and no
+   * `errorCode`, so the two are told apart without guessing.
+   *
+   * Once a tree has pushed, a key it does not declare is a compile error.
    */
   prompts: {
-    run(promptKey: string, args?: PromptRunArgs): Promise<PromptRunResult>;
+    run<K extends PromptKeys>(
+      promptKey: K,
+      args?: PromptRunArgs
+    ): Promise<PromptRunResult<K>>;
   };
   /**
    * The value of one app secret, under a `secret:<NAME>` grant (#3183).
@@ -1750,13 +2034,22 @@ export interface FunctionContext {
 }
 
 /**
- * The durable step handle — Cloudflare Workflows' `WorkflowStep`, forwarded
- * untouched, so `step.do` results are memoized and `step.sleep` hibernates.
+ * The step handle. `step` is the third argument under BOTH runners, so the
+ * same body runs either way — which is what `mode = "any"` is for (#3454).
  *
- * A SYNCHRONOUS invocation gets a passthrough shim of the same shape, so a body
- * written for durable mode runs either way: `do` executes the body (nothing to
- * memoize into without an engine), `sleep` resolves immediately (the sync
- * ceiling is seconds), and `waitForEvent` throws `STEP_NOT_AVAILABLE`.
+ * Under the TASK runner it is Cloudflare Workflows' `WorkflowStep`, forwarded
+ * untouched: `step.do` results are memoized and replayed, and `step.sleep`
+ * hibernates.
+ *
+ * Under the REQUEST runner it is the platform's own, bounded by the request's
+ * 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_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
+ * keeps catching it.
  */
 export interface FunctionStep {
   do<T>(name: string, body: () => T | Promise<T>): Promise<T>;
@@ -1775,13 +2068,57 @@ 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.
  *
- * `step` is the third argument in BOTH modes (#3186). A task run gets the
- * engine's live `WorkflowStep`; a request invocation gets a passthrough shim
- * (`do` runs the body, `sleep` resolves at once, `waitForEvent` throws a
- * named error), so a task-authored body can be exercised as a request.
+ * `step` is the third argument under BOTH runners (#3186, #3454). A task run
+ * gets the engine's live `WorkflowStep`; a request invocation gets the
+ * platform's own, where `do` runs the body inline and a wait the request
+ * budget cannot cover fails the invocation naming the task runner — so a
+ * task-authored body can be exercised as a request, and the one place the two
+ * genuinely differ says so rather than pretending.
  */
 export type FunctionHandler<TInput, TOutput> = (
   input: TInput,
@@ -2005,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;
@@ -2012,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.7",
+  "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",