primitive-functions 0.2.0-alpha.1 → 0.2.0-alpha.11

package/index.d.ts

@@ -10,16 +10,91 @@
  * time, and reaching the stub means it did not.
  */
 
-/** The signed-in user on whose behalf the invocation runs. */
+/**
+ * The signed-in user who invoked the function over HTTP.
+ *
+ * Attribution, never authority (#3279): function code acts as the system
+ * whoever called it, so this says WHO asked, and the rows the function writes
+ * are attributed to them. A trigger fire has no caller and `ctx.user` is
+ * null.
+ */
 export interface FunctionUser {
   userId: string;
   email: string | null;
 }
 
-/** What started this invocation. Only `http` exists today. */
-export interface FunctionTrigger {
-  kind: "http";
-}
+/**
+ * What started this invocation. Narrow on `kind`.
+ *
+ * The same union the runtime builds (`src/server-functions/trigger-descriptor.ts`),
+ * held identical by `tests/api/spec/function-trigger-declarations-3281.test.ts`:
+ * a field the fire path sets is declared here, and nothing is declared here
+ * that the fire path does not set.
+ */
+export type FunctionTrigger =
+  /**
+   * 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";
+      /** The webhook key, which is the function key. */
+      webhookKey: string;
+      /** The platform's webhook row the delivery log lives under. */
+      webhookId: string;
+      /** The provider's event id (`X-Webhook-Event-Id`), when it sent one. */
+      externalEventId: string | null;
+    }
+  /** A cron entry firing, scheduled or from the `cron-triggers test` diagnostic. */
+  | {
+      kind: "cron";
+      /** The `[[function.triggers.cron]]` entry's `name`. */
+      name: string;
+      /** The platform's cron row. */
+      triggerId: string;
+      /** ISO 8601. The instant the fire was scheduled for; a diagnostic fire's is "now". */
+      scheduledFor: string;
+      /** Present, and true, only on the diagnostic fire: nothing was scheduled. */
+      manual?: true;
+    }
+  /**
+   * A DSL workflow's `workflow.call` step reached this function (#3288).
+   *
+   * TRANSITIONAL: the bridge exists so a workflow tree can migrate leaf-first
+   * during the transition, and it retires with the workflow engine in phase 7,
+   * taking this variant with it. `workflowKey` names the PARENT workflow, and
+   * `runId`/`stepId` locate the step inside its run.
+   */
+  | { kind: "workflow"; workflowKey: string; runId: string; stepId: string }
+  /**
+   * 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.
+   * `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: "manual"; userId: string; runKey: string | null };
 
 /** The result shape of an operation that answers in response headers. */
 export interface HeaderResult {
@@ -39,16 +114,21 @@ export interface PrimitivePlatformError extends Error {
 
 /**
  * The typed HTTP profile, generated from the platform's OpenAPI document. Its
- * namespaces mirror the operation ids: analytics, blobBuckets, collections, configVars, connections, databaseTypeConfigs, databases, documents, email, functions, gemini, groups, integrations, iterations, llm, locks, notifications, prompts, resourceMetadata, secrets, users.
+ * namespaces mirror the operation ids: analytics, blobBuckets, channels, collections, configVars, connections, databaseTypeConfigs, databases, documents, email, functions, gemini, groups, integrations, llm, locks, notifications, prompts, resourceMetadata, secrets, users.
  * Methods take one options object carrying the operation's path parameters,
  * query parameters, request headers (under their wire names) and `body`.
  *
  * Generated from the same operations as the runtime profile, so a method that
  * type-checks is a method the platform publishes — and a missing path
  * parameter or a missing required header is a compile error rather than a
- * `TypeError` at invoke time. Namespaces the GATEWAY does not yet allow are
- * still declared: they exist, they answer the gateway's structured denial, and
- * hiding them would make a route's availability look like a typo.
+ * `TypeError` at invoke time. Every call runs with the app's own SYSTEM
+ * authority (#3279): the invocation gate was the authorization. The two
+ * namespaces the gateway does not admit are still declared: they exist, they
+ * answer the gateway's structured denial, and hiding them would make a route's
+ * availability look like a typo. Those are `databaseTypeConfigs` whole, and
+ * `functions` except for `functions.start` — the nested-start door #3280
+ * admits by name, which `ctx.functions.start` calls. `functions.invoke`
+ * stays refused: same-run composition is an import.
  */
 export interface FunctionApi {
   "analytics": {
@@ -124,6 +204,10 @@ export interface FunctionApi {
     "searchUsers"(args?: {
       "q"?: string | number | boolean;
       "limit"?: string | number | boolean;
+      "signupDay"?: string | number | boolean;
+      "signupStartDay"?: string | number | boolean;
+      "signupEndDay"?: string | number | boolean;
+      "offset"?: string | number | boolean;
       "current_timestamp"?: string | number | boolean;
       "_bust"?: string | number | boolean;
     }): Promise<any>;
@@ -233,6 +317,18 @@ export interface FunctionApi {
       body: ArrayBuffer | Uint8Array | string;
     }): Promise<any>;
   };
+  "channels": {
+    /** `channels.authorize` — POST /channels/{channel}/grants. Issue a channel grant under a server function's grant */
+    "authorize"(args: {
+      "channel": string | number;
+      body: unknown;
+    }): Promise<any>;
+    /** `channels.publish` — POST /channels/{channel}/publish. Publish a message to a channel under a server function's grant */
+    "publish"(args: {
+      "channel": string | number;
+      body: unknown;
+    }): Promise<any>;
+  };
   "collections": {
     /** `collections.addDocument` — POST /collections/{collectionId}/documents. Add a document to a collection */
     "addDocument"(args: {
@@ -273,6 +369,8 @@ export interface FunctionApi {
     /** `collections.listCollectionsForDocument` — GET /documents/{documentId}/collections. List collections a document belongs to (reverse lookup) */
     "listCollectionsForDocument"(args: {
       "documentId": string | number;
+      "limit"?: string | number | boolean;
+      "cursor"?: string | number | boolean;
     }): Promise<any>;
     /** `collections.listDocuments` — GET /collections/{collectionId}/documents. List documents in a collection */
     "listDocuments"(args: {
@@ -567,7 +665,7 @@ export interface FunctionApi {
       "query"(args: {
         "databaseId": string | number;
         body: unknown;
-      }): Promise<any>;
+      }): Promise<{ items: any[]; hasMore: boolean; nextCursor?: string; prevCursor?: string }>;
       /** `databases.records.registerIndex` — POST /databases/{databaseId}/records/index/register. Database records: index/register (requires manager-or-higher on the database, or an app-admin/owner role) */
       "registerIndex"(args: {
         "databaseId": string | number;
@@ -632,6 +730,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;
@@ -709,10 +813,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;
@@ -770,6 +885,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;
@@ -786,6 +906,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;
@@ -823,10 +948,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;
@@ -847,6 +984,7 @@ export interface FunctionApi {
       "count"(args: {
         "documentId": string | number;
         "model": string | number;
+        "filter"?: Record<string, unknown> | string;
       }): Promise<any>;
       /** `documents.records.delete` — DELETE /documents/{documentId}/records/{model}/{recordId}. Delete a record from a document model */
       "delete"(args: {
@@ -865,6 +1003,9 @@ export interface FunctionApi {
       "query"(args: {
         "documentId": string | number;
         "model": string | number;
+        "limit"?: string | number | boolean;
+        "cursor"?: string | number | boolean;
+        "filter"?: Record<string, unknown> | string;
       }): Promise<any>;
       /** `documents.records.save` — POST /documents/{documentId}/records/{model}. Create or replace a record in a document model */
       "save"(args: {
@@ -893,6 +1034,11 @@ export interface FunctionApi {
       "documentId": string | number;
       body: unknown;
     }): Promise<any>;
+    /** `documents.requestSnapshot` — POST /documents/{documentId}/snapshots. Snapshot a large document now: seal the open epoch and build a base */
+    "requestSnapshot"(args: {
+      "documentId": string | number;
+      body: unknown;
+    }): Promise<any>;
     /** `documents.revokeGroupPermission` — DELETE /documents/{documentId}/group-permissions/{groupType}/{groupId}. Revoke a group permission on a document */
     "revokeGroupPermission"(args: {
       "documentId": string | number;
@@ -919,6 +1065,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;
@@ -931,11 +1083,28 @@ export interface FunctionApi {
     }): Promise<any>;
   };
   "functions": {
-    /** `functions.invoke` — POST /functions/{functionKey}. Invoke a server function: a synchronous one returns its result, a durable one starts a run */
+    /** `functions.invoke` — POST /functions/{functionKey}. Invoke a server function: a request function returns its result, a task function starts a run */
     "invoke"(args: {
       "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 server function as a task run */
+    "start"(args: {
+      "functionKey": string | number;
+      body?: unknown;
+    }): Promise<any>;
   };
   "gemini": {
     /** `gemini.countTokens` — POST /gemini/count-tokens. Count tokens for a Gemini request */
@@ -1043,18 +1212,6 @@ export interface FunctionApi {
       "integrationKey": string | number;
     }): Promise<any>;
   };
-  "iterations": {
-    /** `iterations.get` — GET /iterations/{iterationName}. Get details for a single iteration */
-    "get"(args: {
-      "iterationName": string | number;
-    }): Promise<any>;
-    /** `iterations.list` — GET /iterations. List iteration runs */
-    "list"(args?: Record<string, never>): Promise<any>;
-    /** `iterations.reset` — POST /iterations/{iterationName}/reset. Reset a terminal iteration so the next trigger runs fresh */
-    "reset"(args: {
-      "iterationName": string | number;
-    }): Promise<any>;
-  };
   "llm": {
     /** `llm.chat` — POST /llm/chat. Run an LLM chat completion */
     "chat"(args: {
@@ -1230,6 +1387,39 @@ export type DatabaseModels<K extends string> = K extends keyof DatabaseSchemas
   ? DatabaseSchemas[K]
   : Record<string, Record<string, unknown>>;
 
+/**
+ * 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`. It is what types
+ * `defineFunction("<key>", handler)`.
+ */
+export interface FunctionSchemas {}
+
+/**
+ * The keys `defineFunction(key, handler)` accepts: every key the augmentation
+ * declares once a tree has pushed, so a key the tree does not declare is a
+ * compile error — and `string` before that, the `DatabaseTypeKeys` rule, so an
+ * unaugmented tree keeps compiling.
+ */
+export type FunctionKeys = [keyof FunctionSchemas] extends [never]
+  ? string
+  : keyof FunctionSchemas & string;
+
+/** A declared function's input type, or `any` when nothing is declared. */
+export type FunctionInput<K extends string> = K extends keyof FunctionSchemas
+  ? FunctionSchemas[K] extends { input: infer I }
+    ? I
+    : any
+  : any;
+
+/** A declared function's output type, or `any` when nothing is declared. */
+export type FunctionOutput<K extends string> = K extends keyof FunctionSchemas
+  ? FunctionSchemas[K] extends { output: infer O }
+    ? O
+    : any
+  : 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
@@ -1239,9 +1429,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
@@ -1274,10 +1493,40 @@ export type ModelBatchOperation<TRow> = {
 };
 
 export interface DatabaseModelHandle<TRow> {
-  query(body?: ModelScopedBody): Promise<{ data: TRow[]; hasMore?: boolean; nextCursor?: string }>;
+  /**
+   * One page of this model's rows, in the decided envelope — `{ items,
+   * hasMore, nextCursor? }` (#3287), the same shape `ctx.doc(...)`,
+   * `ctx.users.list` and the client library answer. The route's own wire
+   * shape is unchanged; the SDK is where the one name lives, so shared paging
+   * code can be written once.
+   */
+  query(body?: ModelScopedBody): Promise<{ items: TRow[]; hasMore: boolean; nextCursor?: string }>;
   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>>;
@@ -1306,6 +1555,84 @@ export interface DatabaseHandle<TModels> {
   runOperation(name: string, params?: Record<string, unknown>): Promise<any>;
 }
 
+/**
+ * The app's DOCUMENT models — EMPTY here and filled by the declaration
+ * `primitive config push` writes into the config tree's `functions/` directory
+ * (`primitive-document-types.d.ts`, from the project's `models/models.toml`).
+ * A project with no document schema gets the open form and still compiles.
+ */
+export interface DocumentSchemas {}
+
+/** The model names `ctx.doc(id).model()` accepts — every declared one, or `string` before a push. */
+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 —
+ * 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
+  ? 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 {
+  filter?: Record<string, unknown> | string;
+  limit?: number;
+  cursor?: string;
+}
+
+/**
+ * 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 }>;
+  aggregate(body: Record<string, unknown>): Promise<any>;
+  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`. */
+export interface DocumentHandle {
+  documentId: string;
+  model<M extends DocumentModelNames>(modelName: M): DocumentModelHandle<DocumentModelRow<M>>;
+}
+
 /**
  * One call through a granted integration — #3183.
  *
@@ -1347,15 +1674,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. */
@@ -1364,9 +1770,127 @@ export interface SendResult {
   truncated: boolean;
 }
 
+/** Who a channel grant is for, and for how long — #3184. */
+export interface ChannelAuthorizeOptions {
+  /**
+   * The member the grant names. Caller mode defaults to the invoking caller;
+   * system mode has no caller and must say.
+   */
+  userId?: string;
+  /** Default 300 s, clamped to the platform ceiling of 900 s. */
+  ttlSeconds?: number;
+}
+
+/** The credential a client presents on the WebSocket it already has. */
+export interface ChannelGrantResult {
+  channel: string;
+  /** The signed grant. Hand it to the client; it is not readable here. */
+  grant: string;
+  /** Epoch milliseconds. Expiry is the only revocation a channel has. */
+  expiresAt: number;
+}
+
+/** Where to start and how big a page to take — #3280. */
+export interface UserPageOptions {
+  /** Page size. Capped by the route at 100. */
+  limit?: number;
+  /** The `nextCursor` of the page before this one. */
+  cursor?: string;
+}
+
+/** One user on the roster, as the platform's own users route reports them. */
+export interface UserPageItem {
+  userId: string;
+  email: string | null;
+  name: string | null;
+  avatarUrl: string | null;
+  role: string;
+  addedAt: string | null;
+  status: string;
+  disabledAt: string | null;
+  [key: string]: unknown;
+}
+
+/** The decided paged envelope, the same shape every paged read answers. */
+export interface UserPage {
+  items: UserPageItem[];
+  hasMore: boolean;
+  /** Absent on the last page. */
+  nextCursor?: string;
+}
+
+/** How a nested start is keyed and labelled — #3280. */
+export interface FunctionStartOptions {
+  /**
+   * Idempotency key, scoped to the tree's root initiator and the resolved
+   * context document: a repeat replays the run that already exists rather than
+   * starting a second. At most 100 characters.
+   */
+  runKey?: string;
+  /**
+   * The document the child's run is keyed under. Defaults through the
+   * inheritance rule: the parent run's context, else the root caller's root
+   * document, else `fn:<the root function's id>`. At most 100 characters.
+   */
+  contextDocId?: string;
+  /** Caller metadata, at most 1 KB encoded. */
+  meta?: Record<string, unknown>;
+}
+
+/** The start envelope, the same one a workflow start answers with — #3280. */
+export interface FunctionStartResult {
+  /** Poll this on the platform's run-status route. */
+  runId: string;
+  runKey: string;
+  instanceId: string;
+  status: string;
+  /**
+   * True when `runKey` already named a run in this tree, which this envelope
+   * describes. That is what makes a run key a singleton.
+   */
+  existing?: boolean;
+}
+
 export interface FunctionContext {
-  user: FunctionUser;
+  /** 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
@@ -1377,6 +1901,13 @@ export interface FunctionContext {
     databaseId: string,
     databaseType: K
   ): DatabaseHandle<DatabaseModels<K>>;
+  /**
+   * A typed handle over one document's record models, typed from the
+   * project's `models/models.toml` — `ctx.db`'s shape for documents. It
+   * confers nothing: every call is a `documents.records.*` operation on the
+   * same authority.
+   */
+  doc(documentId: string): DocumentHandle;
   /**
    * Outbound HTTP, through a granted integration and nowhere else (#3183).
    *
@@ -1394,14 +1925,53 @@ export interface FunctionContext {
     ): Promise<IntegrationCallResult>;
   };
   /**
-   * Run one of the app's prompts, under a `prompt:<key>` grant (#3183).
+   * Start a TASK function from inside this one — #3280.
+   *
+   * The one nested door, and it is a START. A request function is code and
+   * code composes by being IMPORTED, so there is no synchronous nested
+   * invocation to reach for; a request-mode callee answers
+   * `FUNCTION_MODE_MISMATCH`.
+   *
+   * The callee's `access` gate is not consulted — this function's own gate was
+   * the authorization — and every run in the tree is keyed by whoever started
+   * it, so the member who invoked the root polls and terminates them all.
+   * Nesting is bounded at four levels.
+   */
+  functions: {
+    start(
+      functionKey: string,
+      input?: unknown,
+      options?: FunctionStartOptions
+    ): Promise<FunctionStartResult>;
+  };
+  /**
+   * 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).
@@ -1427,22 +1997,66 @@ export interface FunctionContext {
    * error.
    */
   users: {
+    /**
+     * One page of the app's users — #3280.
+     *
+     * On the APP's system authority, whoever invoked the function: a member
+     * who passes this function's gate reads whatever roster it chooses to
+     * expose, so say who may in the function's own `access` expression.
+     * `limit` is capped by the route at 100.
+     */
+    list(options?: UserPageOptions): Promise<UserPage>;
+    /**
+     * Every page of the app's users, in order — #3280.
+     *
+     * FOR A REQUEST FUNCTION AND A SINGLE-SLICE LOOP. A durable loop must take
+     * its pages inside `step.do` with an EXPLICIT cursor: a memoized step does
+     * not advance an iterator on resume, so an iteration across a sleep would
+     * replay pages it had already taken.
+     */
+    iterate(options?: UserPageOptions): AsyncIterable<UserPage>;
     send(userId: string, payload: unknown): Promise<SendResult>;
   };
   /** The same frame to ONE connection, under a `connections:send` grant. */
   connections: {
     send(connectionId: string, payload: unknown): Promise<SendResult>;
   };
+  /**
+   * Realtime channels, under a `channel:<namespace>` grant that COVERS the
+   * channel — #3184.
+   *
+   * `authorize` hands back a short-lived grant for ONE member to present on
+   * the socket it already has; `publish` delivers a `channel.message` frame to
+   * every connection that has joined and whose grant has not expired. Expiry is
+   * the only revocation, so `expiresAt` comes back for the client to renew
+   * ahead of — a renewal is another authorize and another subscribe.
+   */
+  channels: {
+    authorize(
+      channel: string,
+      options?: ChannelAuthorizeOptions
+    ): Promise<ChannelGrantResult>;
+    publish(channel: string, payload: unknown): Promise<SendResult>;
+  };
 }
 
 /**
- * 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).
+ *
+ * Under the TASK runner it is Cloudflare Workflows' `WorkflowStep`, forwarded
+ * untouched: `step.do` results are memoized and replayed, and `step.sleep`
+ * hibernates.
  *
- * 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 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>;
@@ -1462,29 +2076,93 @@ export interface FunctionStep {
 export declare const SDK_STUB_VERSION: string;
 
 /**
- * Declare a server function's handler.
+ * 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 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,
+  ctx: FunctionContext,
+  step: FunctionStep
+) => Promise<TOutput>;
+
+/**
+ * Declare a server function's handler, typed from its declaration.
  *
- * Both authoring styles reach the platform bootstrap identically — a plain
- * default export taking `(input, ctx, step)` runs exactly as a wrapped one
- * does — so this is a typing and intent marker, not a different calling
- * convention.
+ * The KEYED form, `defineFunction("<key>", handler)`, is typed from the
+ * `FunctionSchemas` augmentation `primitive config push` writes beside the
+ * sources: `input` is the key's declared input, the return is checked against
+ * its declared output, and a key the tree does not declare is a compile error.
+ * `config push` also refuses an entry whose key names another file's. In a
+ * tree that has not pushed yet the key is any string and both types are `any`.
  *
- * `step` is the third argument in BOTH modes (#3186). A durable run gets the
- * engine's live `WorkflowStep`; a synchronous one gets a passthrough shim
- * (`do` runs the body, `sleep` resolves at once, `waitForEvent` throws a
- * named error), so a durable-authored body can be exercised synchronously.
+ * The UNKEYED form is what it always was: author-declared generics. Both
+ * styles reach the platform bootstrap identically — a plain default export
+ * taking `(input, ctx, step)` runs exactly as a wrapped one does — so this is
+ * a typing and intent marker, not a different calling convention.
  */
+export declare function defineFunction<K extends FunctionKeys>(
+  key: K,
+  handler: (
+    input: FunctionInput<K>,
+    ctx: FunctionContext,
+    step: FunctionStep
+  ) => FunctionOutput<K> | Promise<FunctionOutput<K>>
+): FunctionHandler<FunctionInput<K>, FunctionOutput<K>> & { functionKey: K };
 export declare function defineFunction<TInput = unknown, TOutput = unknown>(
   handler: (
     input: TInput,
     ctx: FunctionContext,
     step: FunctionStep
   ) => TOutput | Promise<TOutput>
-): (
-  input: TInput,
-  ctx: FunctionContext,
-  step: FunctionStep
-) => Promise<TOutput>;
+): FunctionHandler<TInput, TOutput>;
 
 /**
  * One declared parameter of a registered query.
@@ -1493,13 +2171,64 @@ export declare function defineFunction<TInput = unknown, TOutput = unknown>(
  * the platform injects the invocation's user and refuses a call that supplies
  * the parameter itself.
  */
+/** The scalar parameter types, and an array parameter's element types. */
+export type QueryScalarParamType = "string" | "number" | "boolean" | "any";
+
 export interface QueryParamSpec {
-  type?: "string" | "number" | "boolean" | "any" | "$caller";
+  type?: QueryScalarParamType | "$caller" | "array";
+  /** For `type: "array"` — the element type; absent means any element. */
+  items?: { type: QueryScalarParamType };
   caller?: boolean;
   optional?: boolean;
   default?: unknown;
 }
 
+/** A scalar parameter type's TypeScript type. */
+export type QueryScalarValue<T> = T extends "string"
+  ? string
+  : T extends "number"
+    ? number
+    : T extends "boolean"
+      ? boolean
+      : T extends "$caller"
+        ? string
+        : any;
+
+/** The value `run` receives for one declared parameter. */
+export type QueryParamValue<S> = S extends { caller: true }
+  ? string
+  : S extends { type: "array"; items: { type: infer I } }
+    ? QueryScalarValue<I>[]
+    : S extends { type: "array" }
+      ? unknown[]
+      : S extends { type: infer T }
+        ? QueryScalarValue<T>
+        : any;
+
+type QueryOptionalKeys<P> = {
+  [K in keyof P]: P[K] extends { optional: true } ? K : never;
+}[keyof P];
+
+/**
+ * `run`'s `params`, typed from the declaration: scalars as their scalar,
+ * `$caller` as a string, an array as `T[]`, an `optional: true` parameter
+ * as an optional key (a parameter with a default is always present). An
+ * undeclared name is a compile error.
+ */
+export type QueryParams<P> = {
+  [K in Exclude<keyof P, QueryOptionalKeys<P>>]: QueryParamValue<P[K]>;
+} & {
+  [K in QueryOptionalKeys<P>]?: QueryParamValue<P[K]>;
+};
+
+/** A registration's definition with its parameters DECLARED, so `run` is typed from them. */
+export interface TypedQueryDefinition<TDb, TSpec extends Record<string, QueryParamSpec>, TResult> {
+  models: string[];
+  params?: TSpec;
+  cache?: { ttlMs: number };
+  run: (db: TDb, params: QueryParams<TSpec>) => TResult | Promise<TResult>;
+}
+
 export interface QueryDefinition<TDb, TParams, TResult> {
   /** The models this query touches. Caching is off unless the run matches. */
   models: string[];
@@ -1524,7 +2253,23 @@ export interface QueryDefinition<TDb, TParams, TResult> {
  *
  * Register at MODULE scope: a registration made inside the handler still works
  * for direct calls but is invisible to `config push`'s manifest.
+ *
+ * `run`'s `params` are TYPED from the declaration (the first overload,
+ * inferred with a `const` type parameter): a scalar as its scalar, `$caller`
+ * as a string, `{ type: "array", items: { type: "string" } }` as `string[]`,
+ * an `optional: true` parameter as an optional key; an undeclared name inside
+ * `run` is a compile error. A declared default is coerced to the declared
+ * type at registration, so `run` receives what the declaration promises. The
+ * second overload keeps an explicit `TParams`.
  */
+export declare function defineQuery<
+  const TSpec extends Record<string, QueryParamSpec>,
+  TDb = DatabaseHandle<any>,
+  TResult = any
+>(
+  name: string,
+  definition: TypedQueryDefinition<TDb, TSpec, TResult>
+): (db: TDb, params?: Record<string, unknown>) => Promise<TResult>;
 export declare function defineQuery<
   TDb = DatabaseHandle<any>,
   TParams = Record<string, any>,
@@ -1535,6 +2280,14 @@ export declare function defineQuery<
 ): (db: TDb, params?: Record<string, unknown>) => Promise<TResult>;
 
 /** The same, for a registration that writes. A mutation is never cached. */
+export declare function defineMutation<
+  const TSpec extends Record<string, QueryParamSpec>,
+  TDb = DatabaseHandle<any>,
+  TResult = any
+>(
+  name: string,
+  definition: TypedQueryDefinition<TDb, TSpec, TResult>
+): (db: TDb, params?: Record<string, unknown>) => Promise<TResult>;
 export declare function defineMutation<
   TDb = DatabaseHandle<any>,
   TParams = Record<string, any>,
@@ -1596,6 +2349,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;
@@ -1603,5 +2362,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

@@ -24,10 +24,12 @@ const NOT_PROVIDED =
 export const SDK_STUB_VERSION = "0.0.1";
 
 /**
- * Declare a function's handler. The platform copy returns the handler wrapped
- * with its invocation context; this one refuses, loudly.
+ * Declare a function's handler — `defineFunction(handler)` or the keyed
+ * `defineFunction("<key>", handler)`. The platform copy returns the handler
+ * wrapped with its invocation context; this one refuses, loudly, whichever
+ * shape it is called with.
  */
-export function defineFunction() {
+export function defineFunction(_keyOrHandler, _maybeHandler) {
   throw new Error(NOT_PROVIDED);
 }
 
@@ -80,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,
@@ -87,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.1",
+  "version": "0.2.0-alpha.11",
   "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",