@isomorph.ai/app-sdk 1.15.0 → 1.17.0

package/README.md

@@ -168,7 +168,76 @@ await isomorph.integrations.execute('company-basecamp', {
 });
 ```
 
-(1.14.0; contracts 0.76.0)
+SharePoint runs as the signed-in person after their consent. Every operation
+names a site alias IT mapped to one site of the company's Microsoft 365 tenant.
+Ids are opaque Microsoft Graph ids; a list item's `fields` are its columns by
+internal name; adding an item or uploading a file is an explicit action with a
+fresh UUID, while an update is a PATCH and needs none.
+
+```ts
+// The site's lists, then one list's open items
+const { lists } = await isomorph.integrations.execute('company-sharepoint', {
+  operation: 'sharepoint.list.list', resource: 'intranet', input: {},
+});
+const open = await isomorph.integrations.execute('company-sharepoint', {
+  operation: 'sharepoint.item.list', resource: 'intranet',
+  input: { listId: lists[0].id, filter: "fields/Status eq 'Open'" },
+});
+// open.nextPageToken, when hasMore, is the next read's pageToken
+
+// A new item, then one of its columns changed
+const item = await isomorph.integrations.execute('company-sharepoint', {
+  operation: 'sharepoint.item.create', resource: 'intranet',
+  input: { listId: lists[0].id, fields: { Title: 'Confirm the venue', Status: 'Open', DueDate: '2026-10-20' } },
+  idempotencyKey: crypto.randomUUID(),
+});
+await isomorph.integrations.execute('company-sharepoint', {
+  operation: 'sharepoint.item.update', resource: 'intranet',
+  input: { listId: lists[0].id, itemId: item.id, fields: { Status: 'Done' } },
+});
+
+// The default library's root, a search, one file's bytes, and an upload into a folder
+const { files } = await isomorph.integrations.execute('company-sharepoint', {
+  operation: 'sharepoint.file.list', resource: 'intranet', input: {},
+});
+const found = await isomorph.integrations.execute('company-sharepoint', {
+  operation: 'sharepoint.file.search', resource: 'intranet', input: { q: 'venue contract' },
+});
+const file = await isomorph.integrations.execute('company-sharepoint', {
+  operation: 'sharepoint.file.read', resource: 'intranet', input: { fileId: found.files[0].id },
+});
+await isomorph.integrations.execute('company-sharepoint', {
+  operation: 'sharepoint.file.upload', resource: 'intranet',
+  input: { filename: 'venue-contract-signed.pdf', contentType: 'application/pdf', dataBase64: file.dataBase64, folderId: files.find((entry) => entry.isFolder)?.id, conflict: 'rename' },
+  idempotencyKey: crypto.randomUUID(),
+});
+```
+
+(1.16.0; contracts 0.78.0)
+
+## Trusted actions
+
+A normal action runs with the signed-in person's rights, so a rule in it is advice: whatever it may write, the browser may write directly. A business rule that must hold goes in a trusted action: `export const trusted = true;` beside the default export. Its data calls run as the app on behalf of the caller (the database sees `harbour.user_id = 'workload:…'` and `harbour.on_behalf_of` = the person, with the person's email, groups and role), so the tables it writes give people no write rule (`WITH CHECK (current_setting('harbour.user_id', true) LIKE 'workload:%')`). `ctx.transaction(fn)` runs every call inside `fn` as one database transaction, committed when `fn` returns and rolled back when it throws; `.forUpdate()` on a select locks the row until then. A thrown `Error` with `code` (an error category such as `FORBIDDEN` or `CONFLICT`) and `message` reaches the page with that status and text.
+
+```ts
+// actions/lead-convert.ts
+export const trusted = true;
+
+export default async function leadConvert(input: { leadId: string }, ctx) {
+  if (!(await mayConvert(ctx.user))) throw Object.assign(new Error('Only Sales converts a Lead.'), { code: 'FORBIDDEN' });
+  return ctx.transaction(async () => {
+    const { data: lead } = await isomorph.data.from('crm_lead').select('*').eq('lead_public_id', input.leadId).forUpdate().single();
+    if (lead.lead_status_code !== 'QUALIFIED') throw Object.assign(new Error('Only a qualified Lead can be converted.'), { code: 'CONFLICT' });
+    const { data: [account] } = await isomorph.data.from('business_party').insert({ account_name: lead.company_name }).select();
+    await isomorph.data.from('crm_lead').update({ lead_status_code: 'CONVERTED' }).eq('id', lead.id);
+    return { accountId: account.business_party_public_id };
+  });
+}
+```
+
+The calls go to the local App Gateway beside the runtime (`ISOMORPH_TRUSTED_GATEWAY_URL`; a sidecar on Kubernetes, a child process the runtime starts when `ISOMORPH_LOCAL_GATEWAY_BINARY`, `ISOMORPH_LOCAL_GATEWAY_CONFIG_FILE` and `ISOMORPH_LOCAL_GATEWAY_URL` are set). The kit check refuses a trusted action unless a retained journey invokes it as the second person and is refused. `isomorph-ping` lists trusted actions under `trusted`.
+
+(1.17.0; data plane ADR 0057)
 
 ## Browser read tools
 

package/dist/index.d.ts

@@ -373,6 +373,113 @@ export interface BasecampPeopleListRequest {
         pageToken?: string;
     };
 }
+/** What `sharepoint.file.upload` does when the folder already has a file of that name: `rename` (the default), `replace` or `fail`. */
+export type SharePointConflictBehavior = 'rename' | 'replace' | 'fail';
+/** One column value as a SharePoint write takes it: a string of at most 4000 characters, a number, a boolean, or null (which clears the column on an update). */
+export type SharePointFieldValue = string | number | boolean | null;
+/** Lists the site's lists the signed-in person can see (hidden lists dropped); resource is a site alias. */
+export interface SharePointListListRequest {
+    operation: 'sharepoint.list.list';
+    resource: string;
+    input?: {
+        /** The `nextPageToken` of the previous page; leave it out to read the first page. */
+        pageToken?: string;
+    };
+}
+/** Lists one list's items, 50 a page, filtered when `filter` says so. */
+export interface SharePointItemListRequest {
+    operation: 'sharepoint.item.list';
+    resource: string;
+    input: {
+        /** The `id` a `sharepoint.list.list` result named. */
+        listId: string;
+        /** An OData `$filter` over the columns as `fields/<column> <op> <value>`, e.g. `fields/Status eq 'Open'`; 1 to 512 characters. */
+        filter?: string;
+        pageToken?: string;
+    };
+}
+/** Adds one item to a list as the signed-in person; an explicit action with its own idempotency key. */
+export interface SharePointItemCreateRequest {
+    operation: 'sharepoint.item.create';
+    resource: string;
+    input: {
+        listId: string;
+        /** 1 to 32 column values keyed by the column's internal name (`Title`, `Status`, `DueDate`...); which columns the list has is Graph's check. */
+        fields: Record<string, SharePointFieldValue>;
+    };
+    /** A fresh UUID per authorized action, reused only to retry that action. */
+    idempotencyKey: string;
+}
+/** Changes the named columns of one item; a PATCH, the same outcome however often it runs, so no idempotency key. */
+export interface SharePointItemUpdateRequest {
+    operation: 'sharepoint.item.update';
+    resource: string;
+    input: {
+        listId: string;
+        /** The `id` a `sharepoint.item.list` or `sharepoint.item.create` result named. */
+        itemId: string;
+        /** 1 to 32 column values; null clears a column. */
+        fields: Record<string, SharePointFieldValue>;
+    };
+}
+/** Lists the site's document libraries; their `id` is what the file operations take as `driveId`. */
+export interface SharePointDriveListRequest {
+    operation: 'sharepoint.drive.list';
+    resource: string;
+    input?: {
+        pageToken?: string;
+    };
+}
+/** Lists one folder's entries, files and folders alike: the site's default library and its root when `driveId` and `folderId` are absent. */
+export interface SharePointFileListRequest {
+    operation: 'sharepoint.file.list';
+    resource: string;
+    input?: {
+        driveId?: string;
+        /** The `id` of an entry with `isFolder` from an earlier listing. */
+        folderId?: string;
+        pageToken?: string;
+    };
+}
+/** Searches one library's file names and contents. */
+export interface SharePointFileSearchRequest {
+    operation: 'sharepoint.file.search';
+    resource: string;
+    input: {
+        /** The words to search for, 1 to 256 characters. */
+        q: string;
+        driveId?: string;
+        pageToken?: string;
+    };
+}
+/** Reads one file's bytes (at most 2 MiB) as the signed-in person; `fileId` comes from a listing, a search or an upload. */
+export interface SharePointFileReadRequest {
+    operation: 'sharepoint.file.read';
+    resource: string;
+    input: {
+        fileId: string;
+        driveId?: string;
+    };
+}
+/** Uploads one file (at most 2 MiB) as the signed-in person; an explicit action with its own idempotency key. */
+export interface SharePointFileUploadRequest {
+    operation: 'sharepoint.file.upload';
+    resource: string;
+    input: {
+        /** The name to store it under, 1 to 255 characters; the result's `filename` is the stored name, which `conflict: 'rename'` may have changed. */
+        filename: string;
+        /** The file's MIME type, e.g. `application/pdf`. */
+        contentType: string;
+        /** The bytes as standard base64: at most 2 MiB of bytes (2,796,203 base64 characters). */
+        dataBase64: string;
+        driveId?: string;
+        folderId?: string;
+        /** `rename` when absent. */
+        conflict?: SharePointConflictBehavior;
+    };
+    /** A fresh UUID per authorized action, reused only to retry that action. */
+    idempotencyKey: string;
+}
 export interface ServiceRequest {
     operation: 'service.request';
     resource?: never;
@@ -390,7 +497,7 @@ export interface ServiceRequestResult {
     headers: Record<string, string>;
     body: unknown;
 }
-export type IntegrationRequest = ServiceRequest | SlackChannelHistoryRequest | SlackMessagePostRequest | SlackMessageUpdateRequest | SlackMessageDeleteRequest | SlackDmSendRequest | SlackUserLookupRequest | WarehouseViewReadRequest | GmailThreadListRequest | GmailThreadReadRequest | GmailMessageReadRequest | GmailAttachmentReadRequest | GmailMessageSendRequest | BasecampProjectListRequest | BasecampTodolistListRequest | BasecampTodoListRequest | BasecampTodoCreateRequest | BasecampTodoCompleteRequest | BasecampMessageListRequest | BasecampMessagePostRequest | BasecampCommentListRequest | BasecampCommentPostRequest | BasecampCampfirePostRequest | BasecampPeopleListRequest;
+export type IntegrationRequest = ServiceRequest | SlackChannelHistoryRequest | SlackMessagePostRequest | SlackMessageUpdateRequest | SlackMessageDeleteRequest | SlackDmSendRequest | SlackUserLookupRequest | WarehouseViewReadRequest | GmailThreadListRequest | GmailThreadReadRequest | GmailMessageReadRequest | GmailAttachmentReadRequest | GmailMessageSendRequest | BasecampProjectListRequest | BasecampTodolistListRequest | BasecampTodoListRequest | BasecampTodoCreateRequest | BasecampTodoCompleteRequest | BasecampMessageListRequest | BasecampMessagePostRequest | BasecampCommentListRequest | BasecampCommentPostRequest | BasecampCampfirePostRequest | BasecampPeopleListRequest | SharePointListListRequest | SharePointItemListRequest | SharePointItemCreateRequest | SharePointItemUpdateRequest | SharePointDriveListRequest | SharePointFileListRequest | SharePointFileSearchRequest | SharePointFileReadRequest | SharePointFileUploadRequest;
 export type IntegrationOperation = IntegrationRequest['operation'];
 export interface SlackMessage {
     id: string;
@@ -578,7 +685,75 @@ export interface BasecampTodoCompleteResult {
     id: string;
     completed: true;
 }
-export type IntegrationResult<R extends IntegrationRequest> = R extends ServiceRequest ? ServiceRequestResult : R extends SlackChannelHistoryRequest ? SlackChannelHistoryResult : R extends SlackMessagePostRequest | SlackMessageUpdateRequest | SlackMessageDeleteRequest ? SlackMessagePostResult : R extends SlackDmSendRequest ? SlackDmSendResult : R extends SlackUserLookupRequest ? SlackUserLookupResult : R extends WarehouseViewReadRequest ? WarehouseViewReadResult : R extends GmailThreadListRequest ? GmailThreadListResult : R extends GmailThreadReadRequest ? GmailThreadReadResult : R extends GmailMessageReadRequest ? GmailMessageReadResult : R extends GmailAttachmentReadRequest ? GmailAttachmentReadResult : R extends GmailMessageSendRequest ? GmailMessageSendResult : R extends BasecampProjectListRequest ? BasecampProjectListResult : R extends BasecampTodolistListRequest ? BasecampTodolistListResult : R extends BasecampTodoListRequest ? BasecampTodoListResult : R extends BasecampMessageListRequest ? BasecampMessageListResult : R extends BasecampCommentListRequest ? BasecampCommentListResult : R extends BasecampPeopleListRequest ? BasecampPeopleListResult : R extends BasecampTodoCreateRequest | BasecampMessagePostRequest | BasecampCommentPostRequest | BasecampCampfirePostRequest ? BasecampRecordingResult : R extends BasecampTodoCompleteRequest ? BasecampTodoCompleteResult : never;
+/** One list of the site; `id` is the `listId` the item operations take. `template` is what Graph reports (genericList, documentLibrary, tasks, events...) when it does. */
+export interface SharePointList {
+    id: string;
+    name: string;
+    description?: string;
+    webUrl: string;
+    template?: string;
+}
+/** One list item: `fields` are its column values keyed by internal column name as Graph returns them, system columns dropped and the whole object cut at 16 KiB; `id` is the `itemId` an update takes. */
+export interface SharePointListItem {
+    id: string;
+    fields: Record<string, unknown>;
+    webUrl: string;
+    createdAt: string;
+    modifiedAt: string;
+}
+/** One document library; `id` is the `driveId` the file operations take. */
+export interface SharePointDrive {
+    id: string;
+    name: string;
+    webUrl: string;
+}
+/** One entry of a folder or a search: a file (`mimeType` set; `id` is a `fileId`) or a folder (`isFolder`; `id` is a `folderId`). `size` is in bytes, a folder's the total of its contents. */
+export interface SharePointFile {
+    id: string;
+    name: string;
+    isFolder: boolean;
+    size: number;
+    mimeType?: string;
+    webUrl: string;
+    modifiedAt: string;
+}
+/** One page of a SharePoint list; `nextPageToken` is present only when `hasMore` and is the next read's `pageToken`. */
+export interface SharePointPage {
+    hasMore: boolean;
+    nextPageToken?: string;
+}
+export interface SharePointListListResult extends SharePointPage {
+    lists: SharePointList[];
+}
+export interface SharePointItemListResult extends SharePointPage {
+    items: SharePointListItem[];
+}
+export interface SharePointDriveListResult extends SharePointPage {
+    drives: SharePointDrive[];
+}
+/** `sharepoint.file.list` and `sharepoint.file.search` answer the same page of entries. */
+export interface SharePointFileListResult extends SharePointPage {
+    files: SharePointFile[];
+}
+/** The new item and its SharePoint page, for a person to open. */
+export interface SharePointItemCreateResult {
+    id: string;
+    webUrl: string;
+}
+export interface SharePointItemUpdateResult {
+    id: string;
+}
+/** The Gmail attachment shape plus the file's id. */
+export interface SharePointFileReadResult extends GmailAttachmentReadResult {
+    id: string;
+}
+/** The stored file, under the name `conflict: 'rename'` may have given it, and its SharePoint page. */
+export interface SharePointFileUploadResult {
+    id: string;
+    filename: string;
+    webUrl: string;
+}
+export type IntegrationResult<R extends IntegrationRequest> = R extends ServiceRequest ? ServiceRequestResult : R extends SlackChannelHistoryRequest ? SlackChannelHistoryResult : R extends SlackMessagePostRequest | SlackMessageUpdateRequest | SlackMessageDeleteRequest ? SlackMessagePostResult : R extends SlackDmSendRequest ? SlackDmSendResult : R extends SlackUserLookupRequest ? SlackUserLookupResult : R extends WarehouseViewReadRequest ? WarehouseViewReadResult : R extends GmailThreadListRequest ? GmailThreadListResult : R extends GmailThreadReadRequest ? GmailThreadReadResult : R extends GmailMessageReadRequest ? GmailMessageReadResult : R extends GmailAttachmentReadRequest ? GmailAttachmentReadResult : R extends GmailMessageSendRequest ? GmailMessageSendResult : R extends BasecampProjectListRequest ? BasecampProjectListResult : R extends BasecampTodolistListRequest ? BasecampTodolistListResult : R extends BasecampTodoListRequest ? BasecampTodoListResult : R extends BasecampMessageListRequest ? BasecampMessageListResult : R extends BasecampCommentListRequest ? BasecampCommentListResult : R extends BasecampPeopleListRequest ? BasecampPeopleListResult : R extends BasecampTodoCreateRequest | BasecampMessagePostRequest | BasecampCommentPostRequest | BasecampCampfirePostRequest ? BasecampRecordingResult : R extends BasecampTodoCompleteRequest ? BasecampTodoCompleteResult : R extends SharePointListListRequest ? SharePointListListResult : R extends SharePointItemListRequest ? SharePointItemListResult : R extends SharePointItemCreateRequest ? SharePointItemCreateResult : R extends SharePointItemUpdateRequest ? SharePointItemUpdateResult : R extends SharePointDriveListRequest ? SharePointDriveListResult : R extends SharePointFileListRequest | SharePointFileSearchRequest ? SharePointFileListResult : R extends SharePointFileReadRequest ? SharePointFileReadResult : R extends SharePointFileUploadRequest ? SharePointFileUploadResult : never;
 export type IntegrationConnectResult = {
     status: 'connected';
     accountLabel: string;
@@ -692,6 +867,14 @@ interface Query {
     count?: 'exact';
     head?: boolean;
     onConflict?: string[];
+    lock?: 'update';
+}
+/** What the kit runtime puts around a running action: the caller's signed context, and for a trusted action the open transaction and the gateway it talks to. */
+export interface ActionIdentity {
+    context: string;
+    trusted: boolean;
+    transactionId?: string;
+    baseUrl?: string;
 }
 interface IdentityRenewal {
     renewals(): number;
@@ -742,6 +925,7 @@ export declare class QueryBuilder<T = Record<string, unknown>, Result = T[]> imp
     }): QueryBuilder<T, Result>;
     limit(value: number): QueryBuilder<T, Result>;
     range(from: number, to: number): QueryBuilder<T, Result>;
+    forUpdate(): QueryBuilder<T, Result>;
     single(): QueryBuilder<T, T>;
     maybeSingle(): QueryBuilder<T, T | null>;
     execute(): Promise<IsomorphResult<Result>>;
@@ -762,6 +946,8 @@ declare class RealtimeChannelBuilder {
     on(event: 'postgres_changes' | 'presence' | 'broadcast', filter: unknown, handler: RealtimeHandler): this;
     subscribe(callback?: (status: RealtimeStatus) => void): RealtimeSubscription;
 }
+/** One request on the gateway with the client's headers and refusals; for the kit runtime's own calls. */
+export declare function gatewayRequest<T>(options: ClientOptions, path: string, init?: RequestInit): Promise<T>;
 export declare function createClient(options?: ClientOptions): {
     identity: {
         current: () => Promise<IsomorphUser | null>;

package/dist/index.js

@@ -36,6 +36,11 @@ export function aiErrorCode(error) {
     return typeof code === 'string' && AI_ERROR_CODES.has(code) ? code : undefined;
 }
 const AI_ERROR_CODES = new Set(['AI_NOT_ENABLED', 'AI_POLICY_DENIED', 'AI_QUOTA_EXCEEDED', 'AI_PROVIDER_ERROR', 'AI_UNAVAILABLE', 'REQUEST_TOO_LARGE', 'VALIDATION_FAILED']);
+function currentAction() {
+    if (typeof location !== 'undefined')
+        return undefined;
+    return globalThis[Symbol.for('isomorph.actionIdentity')]?.();
+}
 // Header names are case-insensitive, but a plain object is not: `Headers`
 // JOINS `X-Harbour-Identity-Context` and `x-harbour-identity-context` into one
 // value "a, b". The kit starter's retained checks attach the identity context
@@ -76,17 +81,23 @@ function mergeHeaders(...layers) {
 // client with createClient({ fetch }). The ownership and cross-user coverage
 // rules require that identity, so either the brief should sanction that option
 // or this transport should take a per-request identity.
-function runnerIdentityHeaders(identity) {
+function runnerIdentityHeaders(identity, action = currentAction()) {
     if (typeof location !== 'undefined')
         return {};
-    const resolver = globalThis[Symbol.for('isomorph.actionIdentity')];
-    const actionToken = resolver?.();
-    if (actionToken !== undefined) {
-        if (!actionToken)
+    const environment = globalThis.process?.env;
+    if (action !== undefined) {
+        if (!action.context)
             throw new IsomorphError('AUTH_REQUIRED', 'The action has no invoking-user identity.');
-        return { 'x-harbour-identity-context': actionToken };
+        const headers = { 'x-harbour-identity-context': action.context };
+        if (action.trusted) {
+            if (!environment?.ISOMORPH_WORKLOAD_TOKEN)
+                throw new IsomorphError('AUTH_REQUIRED', 'The trusted action has no workload token to act with.');
+            headers.authorization = `Bearer ${environment.ISOMORPH_WORKLOAD_TOKEN}`;
+        }
+        if (action.transactionId)
+            headers['x-harbour-tx'] = action.transactionId;
+        return headers;
     }
-    const environment = globalThis.process?.env;
     const name = environment?.ISOMORPH_IDENTITY_CONTEXT_HEADER;
     const token = identity === 'second-user' ? environment?.ISOMORPH_IDENTITY_CONTEXT_SECOND_USER : environment?.ISOMORPH_IDENTITY_CONTEXT;
     const workloadToken = environment?.ISOMORPH_WORKLOAD_TOKEN;
@@ -184,9 +195,10 @@ class Transport {
     }
     async request(path, init, renewOnUnauthorized, onProgress) {
         const sentAt = this.renewal?.renewals() ?? 0;
+        const action = currentAction();
         // (headers with an undefined value are removed so a multipart body can
         // clear the JSON default and let the browser set its own boundary)
-        const response = await this.fetch(`${this.baseUrl}${path}`, {
+        const response = await this.fetch(`${action?.baseUrl ?? this.baseUrl}${path}`, {
             credentials: 'same-origin',
             ...init,
             headers: mergeHeaders(
@@ -195,7 +207,7 @@ class Transport {
             // (OPTIONS, one more round trip, on a separate uncredentialed
             // connection a preconnect cannot warm) before the GET itself. Without
             // it the identity GET and every other read is one round trip.
-            init.body === undefined && ['GET', 'HEAD'].includes((init.method ?? 'GET').toUpperCase()) ? {} : { 'content-type': 'application/json' }, runnerIdentityHeaders(this.identity), init.headers, onProgress ? { accept: PROGRESS_MEDIA_TYPE } : undefined),
+            init.body === undefined && ['GET', 'HEAD'].includes((init.method ?? 'GET').toUpperCase()) ? {} : { 'content-type': 'application/json' }, runnerIdentityHeaders(this.identity, action), init.headers, onProgress ? { accept: PROGRESS_MEDIA_TYPE } : undefined),
         });
         if (onProgress && response.ok && response.body && response.headers.get('content-type')?.startsWith(PROGRESS_MEDIA_TYPE)) {
             return readProgress(response, onProgress);
@@ -367,6 +379,7 @@ export class QueryBuilder {
     }
     limit(value) { return this.next({ limit: value }); }
     range(from, to) { return this.next({ range: { from, to } }); }
+    forUpdate() { return this.next({ lock: 'update' }); }
     single() { return this.next({ cardinality: 'single' }); }
     maybeSingle() { return this.next({ cardinality: 'maybeSingle' }); }
     async execute() {
@@ -400,6 +413,10 @@ class RealtimeChannelBuilder {
         }
     }
 }
+/** One request on the gateway with the client's headers and refusals; for the kit runtime's own calls. */
+export function gatewayRequest(options, path, init) {
+    return new Transport(options).json(path, init);
+}
 export function createClient(options = {}) {
     const authListeners = new Set();
     let currentUser;

package/dist/integration-execute-input-rules.d.ts

@@ -56,9 +56,18 @@ export type IntegrationExecuteInputFieldRule = {
 } | {
     kind: 'boolean';
     required: boolean;
+} | {
+    kind: 'record';
+    required: boolean;
+    minProperties: number;
+    maxProperties: number;
+    types: readonly IntegrationExecuteInputRecordValueType[];
+    maxLength?: number;
 };
 /** The scalar types a `value` input accepts, alone or in its list form. */
 export type IntegrationExecuteInputValueType = 'string' | 'number' | 'boolean';
+/** The value types a `record` input accepts under each of its keys (0.78.0): a value type or null. */
+export type IntegrationExecuteInputRecordValueType = IntegrationExecuteInputValueType | 'null';
 export type IntegrationExecuteOperationRule = {
     idempotencyKey: boolean;
     fields: Record<string, IntegrationExecuteInputFieldRule>;
@@ -569,6 +578,199 @@ export declare const IntegrationExecuteInputRules: {
             };
         };
     };
+    readonly "sharepoint.list.list": {
+        readonly idempotencyKey: false;
+        readonly fields: {
+            readonly pageToken: {
+                readonly kind: "string";
+                readonly required: false;
+                readonly minLength: 1;
+                readonly maxLength: 2048;
+            };
+        };
+    };
+    readonly "sharepoint.item.list": {
+        readonly idempotencyKey: false;
+        readonly fields: {
+            readonly listId: {
+                readonly kind: "string";
+                readonly required: true;
+                readonly minLength: 0;
+                readonly pattern: "^[A-Za-z0-9!._,=-]{1,256}$";
+            };
+            readonly filter: {
+                readonly kind: "string";
+                readonly required: false;
+                readonly minLength: 1;
+                readonly maxLength: 512;
+            };
+            readonly pageToken: {
+                readonly kind: "string";
+                readonly required: false;
+                readonly minLength: 1;
+                readonly maxLength: 2048;
+            };
+        };
+    };
+    readonly "sharepoint.item.create": {
+        readonly idempotencyKey: true;
+        readonly fields: {
+            readonly listId: {
+                readonly kind: "string";
+                readonly required: true;
+                readonly minLength: 0;
+                readonly pattern: "^[A-Za-z0-9!._,=-]{1,256}$";
+            };
+            readonly fields: {
+                readonly kind: "record";
+                readonly required: true;
+                readonly minProperties: 1;
+                readonly maxProperties: 32;
+                readonly types: readonly ["string", "number", "boolean", "null"];
+                readonly maxLength: 4000;
+            };
+        };
+    };
+    readonly "sharepoint.item.update": {
+        readonly idempotencyKey: false;
+        readonly fields: {
+            readonly listId: {
+                readonly kind: "string";
+                readonly required: true;
+                readonly minLength: 0;
+                readonly pattern: "^[A-Za-z0-9!._,=-]{1,256}$";
+            };
+            readonly itemId: {
+                readonly kind: "string";
+                readonly required: true;
+                readonly minLength: 0;
+                readonly pattern: "^[A-Za-z0-9!._,=-]{1,256}$";
+            };
+            readonly fields: {
+                readonly kind: "record";
+                readonly required: true;
+                readonly minProperties: 1;
+                readonly maxProperties: 32;
+                readonly types: readonly ["string", "number", "boolean", "null"];
+                readonly maxLength: 4000;
+            };
+        };
+    };
+    readonly "sharepoint.drive.list": {
+        readonly idempotencyKey: false;
+        readonly fields: {
+            readonly pageToken: {
+                readonly kind: "string";
+                readonly required: false;
+                readonly minLength: 1;
+                readonly maxLength: 2048;
+            };
+        };
+    };
+    readonly "sharepoint.file.list": {
+        readonly idempotencyKey: false;
+        readonly fields: {
+            readonly driveId: {
+                readonly kind: "string";
+                readonly required: false;
+                readonly minLength: 0;
+                readonly pattern: "^[A-Za-z0-9!._,=-]{1,256}$";
+            };
+            readonly folderId: {
+                readonly kind: "string";
+                readonly required: false;
+                readonly minLength: 0;
+                readonly pattern: "^[A-Za-z0-9!._,=-]{1,256}$";
+            };
+            readonly pageToken: {
+                readonly kind: "string";
+                readonly required: false;
+                readonly minLength: 1;
+                readonly maxLength: 2048;
+            };
+        };
+    };
+    readonly "sharepoint.file.search": {
+        readonly idempotencyKey: false;
+        readonly fields: {
+            readonly q: {
+                readonly kind: "string";
+                readonly required: true;
+                readonly minLength: 1;
+                readonly maxLength: 256;
+            };
+            readonly driveId: {
+                readonly kind: "string";
+                readonly required: false;
+                readonly minLength: 0;
+                readonly pattern: "^[A-Za-z0-9!._,=-]{1,256}$";
+            };
+            readonly pageToken: {
+                readonly kind: "string";
+                readonly required: false;
+                readonly minLength: 1;
+                readonly maxLength: 2048;
+            };
+        };
+    };
+    readonly "sharepoint.file.read": {
+        readonly idempotencyKey: false;
+        readonly fields: {
+            readonly fileId: {
+                readonly kind: "string";
+                readonly required: true;
+                readonly minLength: 0;
+                readonly pattern: "^[A-Za-z0-9!._,=-]{1,256}$";
+            };
+            readonly driveId: {
+                readonly kind: "string";
+                readonly required: false;
+                readonly minLength: 0;
+                readonly pattern: "^[A-Za-z0-9!._,=-]{1,256}$";
+            };
+        };
+    };
+    readonly "sharepoint.file.upload": {
+        readonly idempotencyKey: true;
+        readonly fields: {
+            readonly filename: {
+                readonly kind: "string";
+                readonly required: true;
+                readonly minLength: 1;
+                readonly maxLength: 255;
+            };
+            readonly contentType: {
+                readonly kind: "string";
+                readonly required: true;
+                readonly minLength: 1;
+                readonly maxLength: 128;
+            };
+            readonly dataBase64: {
+                readonly kind: "string";
+                readonly required: true;
+                readonly minLength: 1;
+                readonly maxLength: 2796203;
+            };
+            readonly driveId: {
+                readonly kind: "string";
+                readonly required: false;
+                readonly minLength: 0;
+                readonly pattern: "^[A-Za-z0-9!._,=-]{1,256}$";
+            };
+            readonly folderId: {
+                readonly kind: "string";
+                readonly required: false;
+                readonly minLength: 0;
+                readonly pattern: "^[A-Za-z0-9!._,=-]{1,256}$";
+            };
+            readonly conflict: {
+                readonly kind: "enum";
+                readonly required: false;
+                readonly values: readonly ["rename", "replace", "fail"];
+                readonly default: "rename";
+            };
+        };
+    };
     readonly "warehouse.view.read": {
         readonly idempotencyKey: false;
         readonly fields: {

package/dist/integration-execute-input-rules.js

@@ -172,6 +172,75 @@ export const IntegrationExecuteInputRules = {
             pageToken: { kind: "string", required: false, minLength: 1, maxLength: 256 },
         },
     },
+    "sharepoint.list.list": {
+        idempotencyKey: false,
+        fields: {
+            pageToken: { kind: "string", required: false, minLength: 1, maxLength: 2048 },
+        },
+    },
+    "sharepoint.item.list": {
+        idempotencyKey: false,
+        fields: {
+            listId: { kind: "string", required: true, minLength: 0, pattern: "^[A-Za-z0-9!._,=-]{1,256}$" },
+            filter: { kind: "string", required: false, minLength: 1, maxLength: 512 },
+            pageToken: { kind: "string", required: false, minLength: 1, maxLength: 2048 },
+        },
+    },
+    "sharepoint.item.create": {
+        idempotencyKey: true,
+        fields: {
+            listId: { kind: "string", required: true, minLength: 0, pattern: "^[A-Za-z0-9!._,=-]{1,256}$" },
+            fields: { kind: "record", required: true, minProperties: 1, maxProperties: 32, types: ["string", "number", "boolean", "null"], maxLength: 4000 },
+        },
+    },
+    "sharepoint.item.update": {
+        idempotencyKey: false,
+        fields: {
+            listId: { kind: "string", required: true, minLength: 0, pattern: "^[A-Za-z0-9!._,=-]{1,256}$" },
+            itemId: { kind: "string", required: true, minLength: 0, pattern: "^[A-Za-z0-9!._,=-]{1,256}$" },
+            fields: { kind: "record", required: true, minProperties: 1, maxProperties: 32, types: ["string", "number", "boolean", "null"], maxLength: 4000 },
+        },
+    },
+    "sharepoint.drive.list": {
+        idempotencyKey: false,
+        fields: {
+            pageToken: { kind: "string", required: false, minLength: 1, maxLength: 2048 },
+        },
+    },
+    "sharepoint.file.list": {
+        idempotencyKey: false,
+        fields: {
+            driveId: { kind: "string", required: false, minLength: 0, pattern: "^[A-Za-z0-9!._,=-]{1,256}$" },
+            folderId: { kind: "string", required: false, minLength: 0, pattern: "^[A-Za-z0-9!._,=-]{1,256}$" },
+            pageToken: { kind: "string", required: false, minLength: 1, maxLength: 2048 },
+        },
+    },
+    "sharepoint.file.search": {
+        idempotencyKey: false,
+        fields: {
+            q: { kind: "string", required: true, minLength: 1, maxLength: 256 },
+            driveId: { kind: "string", required: false, minLength: 0, pattern: "^[A-Za-z0-9!._,=-]{1,256}$" },
+            pageToken: { kind: "string", required: false, minLength: 1, maxLength: 2048 },
+        },
+    },
+    "sharepoint.file.read": {
+        idempotencyKey: false,
+        fields: {
+            fileId: { kind: "string", required: true, minLength: 0, pattern: "^[A-Za-z0-9!._,=-]{1,256}$" },
+            driveId: { kind: "string", required: false, minLength: 0, pattern: "^[A-Za-z0-9!._,=-]{1,256}$" },
+        },
+    },
+    "sharepoint.file.upload": {
+        idempotencyKey: true,
+        fields: {
+            filename: { kind: "string", required: true, minLength: 1, maxLength: 255 },
+            contentType: { kind: "string", required: true, minLength: 1, maxLength: 128 },
+            dataBase64: { kind: "string", required: true, minLength: 1, maxLength: 2796203 },
+            driveId: { kind: "string", required: false, minLength: 0, pattern: "^[A-Za-z0-9!._,=-]{1,256}$" },
+            folderId: { kind: "string", required: false, minLength: 0, pattern: "^[A-Za-z0-9!._,=-]{1,256}$" },
+            conflict: { kind: "enum", required: false, values: ["rename", "replace", "fail"], default: "rename" },
+        },
+    },
     "warehouse.view.read": {
         idempotencyKey: false,
         fields: {
@@ -223,17 +292,22 @@ function matches(pattern, value) {
     return compiled.test(value);
 }
 function refuse(field, message) { return { ok: false, problem: { field, message } }; }
-const valueNouns = { string: ['a string', 'strings'], number: ['a number', 'numbers'], boolean: ['a boolean', 'booleans'] };
+const valueNouns = { string: ['a string', 'strings'], number: ['a number', 'numbers'], boolean: ['a boolean', 'booleans'], null: ['null', 'nulls'] };
 function either(parts) {
     return parts.length > 1 ? `${parts.slice(0, -1).join(', ')} or ${parts[parts.length - 1]}` : parts.join('');
 }
 function isScalar(types, maxLength, value) {
+    if (value === null)
+        return types.includes('null');
     if (typeof value === 'string')
         return types.includes('string') && (maxLength === undefined || value.length <= maxLength);
     if (typeof value === 'number')
         return types.includes('number') && Number.isFinite(value);
     return typeof value === 'boolean' && types.includes('boolean');
 }
+function scalarShapes(types, maxLength) {
+    return types.map(type => (type === 'string' && maxLength !== undefined ? `a string of at most ${maxLength} characters` : valueNouns[type][0]));
+}
 /**
  * Checks one object's fields in rule order and applies defaults: the input
  * itself (where null counts as absent), or one entry of an object[] input
@@ -273,6 +347,18 @@ function checkField(operation, path, name, field, value) {
             if (typeof value !== 'boolean')
                 return refuse(path, `${path} must be a boolean`);
             return { ok: true, value };
+        case 'record': {
+            if (value === null || typeof value !== 'object' || Array.isArray(value))
+                return refuse(path, `${path} must be a JSON object`);
+            const keys = Object.keys(value);
+            if (keys.length < field.minProperties || keys.length > field.maxProperties)
+                return refuse(path, `${path} must have ${field.minProperties} to ${field.maxProperties} properties`);
+            for (const key of keys) {
+                if (!isScalar(field.types, field.maxLength, value[key]))
+                    return refuse(`${path}.${key}`, `${path}.${key} must be ${either(scalarShapes(field.types, field.maxLength))}`);
+            }
+            return { ok: true, value };
+        }
         case 'integer':
             if (typeof value !== 'number' || !Number.isInteger(value) || value < field.minimum || value > field.maximum)
                 return refuse(path, `${path} must be an integer between ${field.minimum} and ${field.maximum}`);
@@ -318,7 +404,7 @@ function checkField(operation, path, name, field, value) {
             const { types, maxLength, list } = field;
             if (isScalar(types, maxLength, value) || (list !== undefined && Array.isArray(value) && value.length >= list.minItems && value.length <= list.maxItems && value.every(item => isScalar(list.types, maxLength, item))))
                 return { ok: true, value };
-            const shapes = types.map(type => (type === 'string' && maxLength !== undefined ? `a string of at most ${maxLength} characters` : valueNouns[type][0]));
+            const shapes = scalarShapes(types, maxLength);
             if (list !== undefined)
                 shapes.push(`a list of ${list.minItems} to ${list.maxItems} ${either(list.types.map(type => valueNouns[type][1]))}`);
             return refuse(path, `${path} must be ${either(shapes)}`);

package/dist/integration-operations.d.ts

@@ -154,6 +154,69 @@ export declare const IntegrationOperations: {
         readonly declaredMode: false;
         readonly idempotencyKey: false;
     };
+    readonly "sharepoint.list.list": {
+        readonly kind: "saas";
+        readonly identities: readonly ["user"];
+        readonly readOnly: true;
+        readonly declaredMode: false;
+        readonly idempotencyKey: false;
+    };
+    readonly "sharepoint.item.list": {
+        readonly kind: "saas";
+        readonly identities: readonly ["user"];
+        readonly readOnly: true;
+        readonly declaredMode: false;
+        readonly idempotencyKey: false;
+    };
+    readonly "sharepoint.item.create": {
+        readonly kind: "saas";
+        readonly identities: readonly ["user"];
+        readonly readOnly: false;
+        readonly declaredMode: false;
+        readonly idempotencyKey: true;
+    };
+    readonly "sharepoint.item.update": {
+        readonly kind: "saas";
+        readonly identities: readonly ["user"];
+        readonly readOnly: false;
+        readonly declaredMode: false;
+        readonly idempotencyKey: false;
+    };
+    readonly "sharepoint.drive.list": {
+        readonly kind: "saas";
+        readonly identities: readonly ["user"];
+        readonly readOnly: true;
+        readonly declaredMode: false;
+        readonly idempotencyKey: false;
+    };
+    readonly "sharepoint.file.list": {
+        readonly kind: "saas";
+        readonly identities: readonly ["user"];
+        readonly readOnly: true;
+        readonly declaredMode: false;
+        readonly idempotencyKey: false;
+    };
+    readonly "sharepoint.file.search": {
+        readonly kind: "saas";
+        readonly identities: readonly ["user"];
+        readonly readOnly: true;
+        readonly declaredMode: false;
+        readonly idempotencyKey: false;
+    };
+    readonly "sharepoint.file.read": {
+        readonly kind: "saas";
+        readonly identities: readonly ["user"];
+        readonly readOnly: true;
+        readonly declaredMode: false;
+        readonly idempotencyKey: false;
+    };
+    readonly "sharepoint.file.upload": {
+        readonly kind: "saas";
+        readonly identities: readonly ["user"];
+        readonly readOnly: false;
+        readonly declaredMode: false;
+        readonly idempotencyKey: true;
+    };
     readonly "warehouse.view.read": {
         readonly kind: "database";
         readonly identities: readonly ["app"];

package/dist/integration-operations.js

@@ -204,6 +204,87 @@ export const IntegrationOperations = {
         "declaredMode": false,
         "idempotencyKey": false
     },
+    "sharepoint.list.list": {
+        "kind": "saas",
+        "identities": [
+            "user"
+        ],
+        "readOnly": true,
+        "declaredMode": false,
+        "idempotencyKey": false
+    },
+    "sharepoint.item.list": {
+        "kind": "saas",
+        "identities": [
+            "user"
+        ],
+        "readOnly": true,
+        "declaredMode": false,
+        "idempotencyKey": false
+    },
+    "sharepoint.item.create": {
+        "kind": "saas",
+        "identities": [
+            "user"
+        ],
+        "readOnly": false,
+        "declaredMode": false,
+        "idempotencyKey": true
+    },
+    "sharepoint.item.update": {
+        "kind": "saas",
+        "identities": [
+            "user"
+        ],
+        "readOnly": false,
+        "declaredMode": false,
+        "idempotencyKey": false
+    },
+    "sharepoint.drive.list": {
+        "kind": "saas",
+        "identities": [
+            "user"
+        ],
+        "readOnly": true,
+        "declaredMode": false,
+        "idempotencyKey": false
+    },
+    "sharepoint.file.list": {
+        "kind": "saas",
+        "identities": [
+            "user"
+        ],
+        "readOnly": true,
+        "declaredMode": false,
+        "idempotencyKey": false
+    },
+    "sharepoint.file.search": {
+        "kind": "saas",
+        "identities": [
+            "user"
+        ],
+        "readOnly": true,
+        "declaredMode": false,
+        "idempotencyKey": false
+    },
+    "sharepoint.file.read": {
+        "kind": "saas",
+        "identities": [
+            "user"
+        ],
+        "readOnly": true,
+        "declaredMode": false,
+        "idempotencyKey": false
+    },
+    "sharepoint.file.upload": {
+        "kind": "saas",
+        "identities": [
+            "user"
+        ],
+        "readOnly": false,
+        "declaredMode": false,
+        "idempotencyKey": true
+    },
     "warehouse.view.read": {
         "kind": "database",
         "identities": [

package/dist/jobs.d.ts

@@ -10,6 +10,8 @@ export interface JobContext {
     progress(percent: number, note?: string): Promise<void>;
     cancelled(): Promise<boolean>;
 }
+/** Whether the module says `export const <name> = true`, read without importing it; a module that does not parse does not. */
+export declare function exportsTrue(file: string, name: string): Promise<boolean>;
 export declare function discoverJobs(root: string): Promise<JobDefinition[]>;
 type Handler = (...args: unknown[]) => unknown;
 export declare function loadHandler(root: string, dir: string, name: string): Promise<Handler>;

package/dist/jobs.js

@@ -16,6 +16,23 @@ function bindsSchedule(binding) {
         default: return false;
     }
 }
+function parseModule(source) {
+    return parse(stripTypeScriptTypes(source), { ecmaVersion: 'latest', sourceType: 'module' }).body;
+}
+/** Whether the module says `export const <name> = true`, read without importing it; a module that does not parse does not. */
+export async function exportsTrue(file, name) {
+    let statements;
+    try {
+        statements = parseModule(await readFile(file, 'utf8'));
+    }
+    catch {
+        return false;
+    }
+    return statements.some(statement => statement.type === 'ExportNamedDeclaration'
+        && statement.declaration?.type === 'VariableDeclaration' && statement.declaration.kind === 'const'
+        && statement.declaration.declarations.some(declaration => declaration.id.type === 'Identifier' && declaration.id.name === name
+            && declaration.init?.type === 'Literal' && declaration.init.value === true));
+}
 export async function discoverJobs(root) {
     const directory = join(root, JOBS_DIR);
     const entries = await readdir(directory, { withFileTypes: true }).catch((error) => {
@@ -34,7 +51,7 @@ export async function discoverJobs(root) {
         const source = await readFile(join(directory, entry.name), 'utf8');
         let statements;
         try {
-            statements = parse(stripTypeScriptTypes(source), { ecmaVersion: 'latest', sourceType: 'module' }).body;
+            statements = parseModule(source);
         }
         catch (error) {
             fail(`cannot parse the job module: ${error instanceof Error ? error.message : String(error)}`);

package/dist/local-gateway.d.ts

@@ -0,0 +1,17 @@
+export interface LocalGatewayOptions {
+    binary: string;
+    configFile: string;
+    url: string;
+    log: (line: string) => void;
+}
+/** The App Gateway as a child of the runtime (the Lambda option; Kubernetes runs it as a sidecar): started once, restarted when it exits, killed on stop. */
+export declare class LocalGateway {
+    private readonly options;
+    private child;
+    private stopped;
+    constructor(options: LocalGatewayOptions);
+    start(): Promise<void>;
+    stop(): void;
+    private spawn;
+    private listening;
+}

package/dist/local-gateway.js

@@ -0,0 +1,50 @@
+import { spawn } from 'node:child_process';
+import { setTimeout as sleep } from 'node:timers/promises';
+const LISTEN_WAIT_MS = 20_000;
+const LISTEN_POLL_MS = 250;
+const RESTART_DELAY_MS = 1_000;
+/** The App Gateway as a child of the runtime (the Lambda option; Kubernetes runs it as a sidecar): started once, restarted when it exits, killed on stop. */
+export class LocalGateway {
+    options;
+    child;
+    stopped = false;
+    constructor(options) {
+        this.options = options;
+    }
+    async start() {
+        if (!this.options.url)
+            throw new Error('ISOMORPH_LOCAL_GATEWAY_URL names where the local gateway listens');
+        this.spawn();
+        const deadline = Date.now() + LISTEN_WAIT_MS;
+        while (!(await this.listening())) {
+            if (Date.now() > deadline)
+                throw new Error(`the local gateway did not listen on ${this.options.url} within ${LISTEN_WAIT_MS / 1000} s`);
+            await sleep(LISTEN_POLL_MS);
+        }
+        process.env.ISOMORPH_TRUSTED_GATEWAY_URL = this.options.url;
+    }
+    stop() {
+        this.stopped = true;
+        this.child?.kill('SIGTERM');
+    }
+    spawn() {
+        this.child = spawn(this.options.binary, [], { env: { ...process.env, HARBOUR_APP_GATEWAY_CONFIG_FILE: this.options.configFile }, stdio: ['ignore', 'ignore', 'pipe'] });
+        this.child.stderr?.on('data', (chunk) => process.stderr.write(chunk));
+        this.child.once('exit', (code, signal) => {
+            if (this.stopped)
+                return;
+            this.options.log(`the local gateway exited (${signal ?? code}); restarting`);
+            void sleep(RESTART_DELAY_MS).then(() => { if (!this.stopped)
+                this.spawn(); });
+        });
+    }
+    async listening() {
+        try {
+            await fetch(`${this.options.url}/_harbour/identity/current`, { signal: AbortSignal.timeout(LISTEN_POLL_MS * 4) });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+}

package/dist/runtime.d.ts

@@ -1,6 +1,7 @@
 import { type IncomingMessage, type ServerResponse } from 'node:http';
 import { type IsomorphClient, type IsomorphUser, type JobRun } from './index.js';
 import { type JobDefinition } from './jobs.js';
+import { type LocalGatewayOptions } from './local-gateway.js';
 export { JOBS_DIR, type JobContext } from './jobs.js';
 export declare const ACTIONS_DIR = "actions";
 export declare const RUNS_TABLE = "isomorph_job_runs";
@@ -21,9 +22,19 @@ export interface ActionContext {
      * step over 1 KiB, further calls are dropped.
      */
     progress(step: string | Record<string, unknown>): void;
+    /**
+     * Runs `fn` in one database transaction: every data call inside it, from
+     * any client, is part of it; it commits when `fn` returns and rolls back
+     * when `fn` throws (the error is rethrown). Only in a trusted action
+     * (`export const trusted = true`). A transaction inside a transaction joins
+     * the outer one.
+     */
+    transaction<T>(fn: () => Promise<T>): Promise<T>;
 }
 export interface RuntimeInventory {
     actions: string[];
+    /** The actions whose module says `export const trusted = true`: they act as the app on behalf of the caller. */
+    trusted: string[];
     jobs: JobDefinition[];
 }
 /** Every `actions/<name>.ts` and `jobs/<name>.ts` the app carries, by logical name. */
@@ -72,10 +83,13 @@ export interface RuntimeOptions {
     log?: (line: string) => void;
     /** The pause between queue passes while work is found; the tests shorten it. */
     queuePollMs?: number;
+    /** Set when the runtime itself runs the App Gateway for its trusted actions (the Lambda option). */
+    localGateway?: Omit<LocalGatewayOptions, 'log'>;
 }
 export declare class Runtime {
     private readonly options;
     private inventory;
+    private localGateway;
     private readonly running;
     private readonly timers;
     private stopped;
@@ -121,6 +135,7 @@ export declare class Runtime {
      */
     work(): Promise<boolean>;
     private serve;
+    private transaction;
     private loadFailures;
     private reserved;
 }

package/dist/runtime.js

@@ -56,10 +56,11 @@ import { register } from 'node:module';
 import { join, resolve } from 'node:path';
 import { realpathSync } from 'node:fs';
 import { pathToFileURL } from 'node:url';
-import { createClient, IsomorphError } from './index.js';
+import { createClient, gatewayRequest, IsomorphError } from './index.js';
 import { userGroupsFromHeader } from './user-groups.js';
 import { userRole } from './user-role.js';
-import { discoverJobs, invokeJob, loadHandler, JOBS_DIR } from './jobs.js';
+import { discoverJobs, exportsTrue, invokeJob, loadHandler, JOBS_DIR } from './jobs.js';
+import { LocalGateway } from './local-gateway.js';
 export { JOBS_DIR } from './jobs.js';
 const actionIdentity = new AsyncLocalStorage();
 const identityKey = Symbol.for('isomorph.actionIdentity');
@@ -94,8 +95,9 @@ export async function discover(root) {
         return entries.filter((entry) => entry.isFile() && entry.name.endsWith('.ts')).map((entry) => entry.name.slice(0, -3)).filter((name) => LOGICAL_NAME.test(name)).sort();
     };
     const actions = (await list(ACTIONS_DIR)).filter((name) => !name.startsWith(RESERVED_PREFIX));
+    const trusted = await Promise.all(actions.map((name) => exportsTrue(join(root, ACTIONS_DIR, `${name}.ts`), 'trusted')));
     const jobs = await discoverJobs(root);
-    return { actions, jobs };
+    return { actions, trusted: actions.filter((_, index) => trusted[index]), jobs };
 }
 // ---- Cron ------------------------------------------------------------------
 /** One field of a five-field cron expression: numbers, `*`, lists, ranges and steps, no names. */
@@ -148,6 +150,16 @@ function answer(response, status, body, requestId) {
 function refuse(response, status, category, message, requestId) {
     answer(response, status, { error: { category, message } }, requestId);
 }
+const REFUSAL_STATUS = { AUTH_REQUIRED: 401, FORBIDDEN: 403, NOT_FOUND: 404, CONFLICT: 409, VALIDATION_FAILED: 400, RATE_LIMITED: 429, UNAVAILABLE: 503, INTERNAL: 500 };
+/** An action's refusal for the browser: an IsomorphError, or any error carrying one of the SDK's categories as `code`. */
+function refusal(error) {
+    if (error instanceof IsomorphError)
+        return { status: error.status ?? REFUSAL_STATUS[error.category], category: error.category, message: error.message };
+    const code = error?.code;
+    if (error instanceof Error && typeof code === 'string' && code in REFUSAL_STATUS)
+        return { status: REFUSAL_STATUS[code], category: code, message: error.message };
+    return undefined;
+}
 async function readBody(request) {
     const chunks = [];
     let size = 0;
@@ -225,7 +237,8 @@ export class Runs {
 }
 export class Runtime {
     options;
-    inventory = { actions: [], jobs: [] };
+    inventory = { actions: [], trusted: [], jobs: [] };
+    localGateway;
     running = new Set();
     timers = [];
     stopped = false;
@@ -245,6 +258,10 @@ export class Runtime {
     async start() {
         this.inventory = await discover(this.options.root);
         await this.refreshToken();
+        if (this.options.localGateway && this.inventory.trusted.length > 0) {
+            this.localGateway = new LocalGateway({ ...this.options.localGateway, log: this.log });
+            await this.localGateway.start();
+        }
         await new Promise((done, fail) => {
             this.server.once('error', fail);
             this.server.listen(this.options.port, '0.0.0.0', () => done());
@@ -346,6 +363,7 @@ export class Runtime {
         this.stopped = true;
         for (const timer of this.timers)
             clearTimeout(timer);
+        this.localGateway?.stop();
         await new Promise((done) => this.server.close(() => done()));
     }
     every(ms, task) {
@@ -522,7 +540,7 @@ export class Runtime {
                 response.writeHead(200, { 'content-type': PROGRESS_MEDIA_TYPE, ...(requestId ? { 'x-request-id': requestId } : {}) });
             response.write(line);
         };
-        const context = { signal: controller.signal, user, tenant, app, requestId: requestId ?? '', progress };
+        const context = { signal: controller.signal, user, tenant, app, requestId: requestId ?? '', progress, transaction: (fn) => this.transaction(name, fn) };
         const raw = await readBody(request);
         if (raw === undefined)
             return refuse(response, 413, 'VALIDATION_FAILED', 'the request body is larger than 1 MiB', requestId);
@@ -542,12 +560,15 @@ export class Runtime {
                 return refuse(response, 404, 'NOT_FOUND', `this app has no ${ACTIONS_DIR}/${name}.ts`, requestId);
             await this.prepareAI();
             const handler = await loadHandler(this.options.root, ACTIONS_DIR, name);
-            const result = await actionIdentity.run(header(request, 'X-Harbour-Identity-Context'), () => handler(input, context));
+            const trusted = this.inventory.trusted.includes(name);
+            const identity = { context: header(request, 'X-Harbour-Identity-Context'), trusted, baseUrl: trusted ? process.env.ISOMORPH_TRUSTED_GATEWAY_URL || undefined : undefined };
+            const result = await actionIdentity.run(identity, () => handler(input, context));
             return answer(response, 200, { data: result === undefined ? null : result }, requestId);
         }
         catch (error) {
-            if (error instanceof IsomorphError)
-                return refuse(response, error.status ?? 400, error.category, error.message, requestId);
+            const refused = refusal(error);
+            if (refused)
+                return refuse(response, refused.status, refused.category, refused.message, requestId);
             this.log(`${name}: ${error instanceof Error ? error.stack ?? error.message : String(error)}`);
             return refuse(response, 500, 'INTERNAL', `the action ${name} failed; its log names the cause`, requestId);
         }
@@ -563,6 +584,26 @@ export class Runtime {
     // first click, hosted and in isomorph dev alike (fourier app-06b08cba,
     // 2026-09-29). Ping still answers 200: the gate's readiness probe is ping.
     // Messages are capped: the gate's coverage ledger parses the first 64 KiB.
+    async transaction(name, fn) {
+        const identity = actionIdentity.getStore();
+        if (!identity?.trusted)
+            throw new IsomorphError('INTERNAL', `ctx.transaction needs a trusted action: add export const trusted = true to ${ACTIONS_DIR}/${name}.ts`, undefined, undefined, 500);
+        if (identity.transactionId)
+            return fn();
+        const gateway = { baseUrl: this.options.gatewayUrl };
+        const { id } = await gatewayRequest(gateway, '/_harbour/data/tx', { method: 'POST', body: '{}' });
+        const end = (outcome) => gatewayRequest(gateway, `/_harbour/data/tx/${encodeURIComponent(id)}/${outcome}`, { method: 'POST', body: '{}' });
+        let result;
+        try {
+            result = await actionIdentity.run({ ...identity, transactionId: id }, fn);
+        }
+        catch (error) {
+            await end('rollback').catch(() => undefined);
+            throw error;
+        }
+        await end('commit');
+        return result;
+    }
     async loadFailures() {
         const failures = [];
         const modules = [[ACTIONS_DIR, this.inventory.actions], [JOBS_DIR, this.inventory.jobs.map((job) => job.name)]];
@@ -583,7 +624,7 @@ export class Runtime {
         const owner = context.user.id;
         switch (name) {
             case PING_ACTION: {
-                const answer = { ok: true, mode: this.options.mode, actions: this.inventory.actions, jobs: this.inventory.jobs.map((job) => job.name) };
+                const answer = { ok: true, mode: this.options.mode, actions: this.inventory.actions, trusted: this.inventory.trusted, jobs: this.inventory.jobs.map((job) => job.name) };
                 return this.options.mode === 'gate' ? { ...answer, loadFailures: await this.loadFailures() } : answer;
             }
             case ENQUEUE_ACTION: {
@@ -622,6 +663,9 @@ export function optionsFromEnvironment(env = process.env) {
         mode: env.ISOMORPH_RUNTIME_MODE === 'gate' ? 'gate' : env.ISOMORPH_JOBS_SCHEDULER === 'platform' ? 'actions' : 'full',
         tokenFile: env.HARBOUR_WORKLOAD_TOKEN_FILE || undefined,
         jobRuns: env.ISOMORPH_JOB_RUNS !== 'none',
+        ...(env.ISOMORPH_LOCAL_GATEWAY_BINARY && env.ISOMORPH_LOCAL_GATEWAY_CONFIG_FILE
+            ? { localGateway: { binary: env.ISOMORPH_LOCAL_GATEWAY_BINARY, configFile: env.ISOMORPH_LOCAL_GATEWAY_CONFIG_FILE, url: (env.ISOMORPH_LOCAL_GATEWAY_URL || '').replace(/\/$/, '') } }
+            : {}),
     };
 }
 /** The job named by `--run-job <name>` or `--run-job=<name>`; undefined when the runtime is a server. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@isomorph.ai/app-sdk",
-  "version": "1.15.0",
+  "version": "1.17.0",
   "type": "module",
   "repository": {
     "type": "git",