@isomorph.ai/app-sdk 1.16.0 → 1.18.0

package/README.md

@@ -215,6 +215,30 @@ await isomorph.integrations.execute('company-sharepoint', {
 
 (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
 
 Install optional peers `ai` and `playwright-core@1.58.2`. Locally run `npx playwright-core install chromium --only-shell`; V2 packages Chromium in the existing app image. An existing system executable can be supplied as executablePath.

package/dist/index.d.ts

@@ -172,6 +172,38 @@ export interface WarehouseViewReadRequest {
         limit?: number;
     };
 }
+/** One row to append: every key an approved column of the alias; values typed by the catalog, `null` for any column. */
+export type WarehouseAppendRow = Record<string, string | number | boolean | null>;
+/**
+ * Land rows in the warehouse. The resource is an alias IT approved with access `append` (an alias reads or
+ * appends, never both). Up to 500 rows per call; a larger report is several calls, each with its own fresh key.
+ * On a lane without a warehouse binding the rows are validated and answered as a dry run; nothing is written.
+ */
+export interface WarehouseTableAppendRequest {
+    operation: 'warehouse.table.append';
+    resource: string;
+    input: {
+        /** 1 to 500 rows. */
+        rows: WarehouseAppendRow[];
+    };
+    /** A fresh UUID per append, reused only to retry that same append. */
+    idempotencyKey: string;
+}
+/**
+ * The SMS a company-owned number received. The resource is a number alias of a `phone` connection. An app waiting
+ * for a one-time code polls this every few seconds with `since` set to when it asked, and reads the code out of
+ * the message body itself; there is no OTP concept on the platform.
+ */
+export interface PhoneSmsListRequest {
+    operation: 'phone.sms.list';
+    resource: string;
+    input: {
+        /** ISO 8601 instant; only messages received at or after it are returned. */
+        since: string;
+        /** Only messages from this sender id or number, up to 32 characters. */
+        from?: string;
+    };
+}
 /** Gmail runs as the signed-in person after their consent. Resources are approved mailbox aliases (`inbox`). */
 export interface GmailThreadListRequest {
     operation: 'gmail.thread.list';
@@ -497,7 +529,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 | SharePointListListRequest | SharePointItemListRequest | SharePointItemCreateRequest | SharePointItemUpdateRequest | SharePointDriveListRequest | SharePointFileListRequest | SharePointFileSearchRequest | SharePointFileReadRequest | SharePointFileUploadRequest;
+export type IntegrationRequest = ServiceRequest | SlackChannelHistoryRequest | SlackMessagePostRequest | SlackMessageUpdateRequest | SlackMessageDeleteRequest | SlackDmSendRequest | SlackUserLookupRequest | WarehouseViewReadRequest | WarehouseTableAppendRequest | PhoneSmsListRequest | 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;
@@ -534,6 +566,23 @@ export interface WarehouseViewReadResult {
     /** True when more rows matched than `limit`: the rows are incomplete, so never total or average them in code. */
     truncated: boolean;
 }
+export interface WarehouseTableAppendResult {
+    /** How many rows landed (or, on a lane without a warehouse binding, would have). */
+    appended: number;
+    /** The write receipt's id; a retry with the same idempotencyKey answers the same receipt. */
+    jobId: string;
+    /** Present and true when the lane has no warehouse binding: the rows were validated, nothing was written. */
+    dryRun?: boolean;
+}
+export interface PhoneSmsMessage {
+    from: string;
+    body: string;
+    receivedAt: string;
+}
+/** Up to 50 messages received since `since`, newest first. */
+export interface PhoneSmsListResult {
+    messages: PhoneSmsMessage[];
+}
 export interface GmailThreadSummary {
     id: string;
     messageId: string;
@@ -753,7 +802,7 @@ export interface SharePointFileUploadResult {
     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 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 WarehouseTableAppendRequest ? WarehouseTableAppendResult : R extends PhoneSmsListRequest ? PhoneSmsListResult : 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;
@@ -867,6 +916,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;
@@ -917,6 +974,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>>;
@@ -937,6 +995,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

@@ -30,12 +30,31 @@ function warehouseReadProblem({ columns, aggregates }) {
         return { field: 'columns', message: 'columns may use "*" only as the sole entry' };
     return undefined;
 }
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+// The append rules governance states in prose: 1 to 500 rows per call (a
+// larger report is several calls) and a UUID idempotency key per call.
+// Governance checks the columns and the value types against the catalog.
+function warehouseAppendProblem({ input, idempotencyKey }) {
+    const rows = input?.rows;
+    if (!Array.isArray(rows) || rows.length === 0)
+        return { field: 'rows', message: 'a warehouse append needs 1 to 500 rows' };
+    if (rows.length > 500)
+        return { field: 'rows', message: 'a warehouse append takes at most 500 rows per call; send a larger report as several calls, each with its own idempotencyKey' };
+    if (typeof idempotencyKey !== 'string' || !UUID_PATTERN.test(idempotencyKey))
+        return { field: 'idempotencyKey', message: 'a warehouse append needs a fresh UUID idempotencyKey per call' };
+    return undefined;
+}
 /** The AI reason code carried by an error, when it is a governed-AI refusal. */
 export function aiErrorCode(error) {
     const code = error instanceof IsomorphError ? error.details?.code : undefined;
     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 +95,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 +209,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 +221,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 +393,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 +427,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;
@@ -734,8 +765,9 @@ export function createClient(options = {}) {
                 // `isomorph check` (which runs retained journeys through this client)
                 // and the deployed app fail the same way at build time, not at runtime.
                 const checked = validateIntegrationExecuteInput(request.operation, request.input);
-                const problem = !checked.ok ? checked.problem
-                    : request.operation === 'warehouse.view.read' ? warehouseReadProblem(request.input ?? {}) : undefined;
+                const problem = (request.operation === 'warehouse.table.append' ? warehouseAppendProblem(request) : undefined)
+                    ?? (!checked.ok ? checked.problem
+                        : request.operation === 'warehouse.view.read' ? warehouseReadProblem(request.input ?? {}) : undefined);
                 if (problem) {
                     return Promise.reject(new IsomorphError('VALIDATION_FAILED', problem.message, undefined, { code: 'INPUT_INVALID', field: problem.field }));
                 }

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

@@ -63,6 +63,15 @@ export type IntegrationExecuteInputFieldRule = {
     maxProperties: number;
     types: readonly IntegrationExecuteInputRecordValueType[];
     maxLength?: number;
+} | {
+    kind: 'record[]';
+    required: boolean;
+    minItems: number;
+    maxItems: number;
+    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';
@@ -771,6 +780,23 @@ export declare const IntegrationExecuteInputRules: {
             };
         };
     };
+    readonly "phone.sms.list": {
+        readonly idempotencyKey: false;
+        readonly fields: {
+            readonly since: {
+                readonly kind: "string";
+                readonly required: true;
+                readonly minLength: 1;
+                readonly pattern: "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\\.[0-9]{1,9})?(Z|[+-][0-9]{2}:[0-9]{2})$";
+            };
+            readonly from: {
+                readonly kind: "string";
+                readonly required: false;
+                readonly minLength: 0;
+                readonly maxLength: 32;
+            };
+        };
+    };
     readonly "warehouse.view.read": {
         readonly idempotencyKey: false;
         readonly fields: {
@@ -880,6 +906,21 @@ export declare const IntegrationExecuteInputRules: {
             };
         };
     };
+    readonly "warehouse.table.append": {
+        readonly idempotencyKey: true;
+        readonly fields: {
+            readonly rows: {
+                readonly kind: "record[]";
+                readonly required: true;
+                readonly minItems: 1;
+                readonly maxItems: 500;
+                readonly minProperties: 1;
+                readonly maxProperties: 64;
+                readonly types: readonly ["string", "number", "boolean", "null"];
+                readonly maxLength: 4000;
+            };
+        };
+    };
     readonly "service.request": {
         readonly idempotencyKey: false;
         readonly fields: {

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

@@ -241,6 +241,13 @@ export const IntegrationExecuteInputRules = {
             conflict: { kind: "enum", required: false, values: ["rename", "replace", "fail"], default: "rename" },
         },
     },
+    "phone.sms.list": {
+        idempotencyKey: false,
+        fields: {
+            since: { kind: "string", required: true, minLength: 1, pattern: "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\\.[0-9]{1,9})?(Z|[+-][0-9]{2}:[0-9]{2})$" },
+            from: { kind: "string", required: false, minLength: 0, maxLength: 32 },
+        },
+    },
     "warehouse.view.read": {
         idempotencyKey: false,
         fields: {
@@ -263,6 +270,12 @@ export const IntegrationExecuteInputRules = {
             limit: { kind: "integer", required: false, minimum: 1, maximum: 1000, default: 100 },
         },
     },
+    "warehouse.table.append": {
+        idempotencyKey: true,
+        fields: {
+            rows: { kind: "record[]", required: true, minItems: 1, maxItems: 500, minProperties: 1, maxProperties: 64, types: ["string", "number", "boolean", "null"], maxLength: 4000 },
+        },
+    },
     "service.request": {
         idempotencyKey: false,
         fields: {
@@ -337,6 +350,19 @@ function checkFields(operation, prefix, fields, given, nullIsAbsent) {
     }
     return { ok: true, value: out };
 }
+/** One record: a bounded count of free keys, every value one of the record's scalar types. */
+function checkRecord(path, field, value) {
+    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 };
+}
 function checkField(operation, path, name, field, value) {
     switch (field.kind) {
         case 'object':
@@ -347,15 +373,17 @@ 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))}`);
+        case 'record':
+            return checkRecord(path, field, value);
+        case 'record[]': {
+            if (!Array.isArray(value) || value.length < field.minItems || value.length > field.maxItems)
+                return refuse(path, `${path} must list ${field.minItems} to ${field.maxItems} items`);
+            for (const [index, item] of value.entries()) {
+                if (item === null || typeof item !== 'object' || Array.isArray(item))
+                    return refuse(path, `${path}[${index}] is not a valid ${name} entry`);
+                const entry = checkRecord(`${path}[${index}]`, field, item);
+                if (!entry.ok)
+                    return entry;
             }
             return { ok: true, value };
         }

package/dist/integration-operations.d.ts

@@ -217,6 +217,13 @@ export declare const IntegrationOperations: {
         readonly declaredMode: false;
         readonly idempotencyKey: true;
     };
+    readonly "phone.sms.list": {
+        readonly kind: "saas";
+        readonly identities: readonly ["app"];
+        readonly readOnly: true;
+        readonly declaredMode: false;
+        readonly idempotencyKey: false;
+    };
     readonly "warehouse.view.read": {
         readonly kind: "database";
         readonly identities: readonly ["app"];
@@ -224,6 +231,13 @@ export declare const IntegrationOperations: {
         readonly declaredMode: false;
         readonly idempotencyKey: false;
     };
+    readonly "warehouse.table.append": {
+        readonly kind: "database";
+        readonly identities: readonly ["app"];
+        readonly readOnly: false;
+        readonly declaredMode: false;
+        readonly idempotencyKey: true;
+    };
     readonly "service.request": {
         readonly kind: "service";
         readonly identities: readonly ["app"];

package/dist/integration-operations.js

@@ -285,6 +285,15 @@ export const IntegrationOperations = {
         "declaredMode": false,
         "idempotencyKey": true
     },
+    "phone.sms.list": {
+        "kind": "saas",
+        "identities": [
+            "app"
+        ],
+        "readOnly": true,
+        "declaredMode": false,
+        "idempotencyKey": false
+    },
     "warehouse.view.read": {
         "kind": "database",
         "identities": [
@@ -294,6 +303,15 @@ export const IntegrationOperations = {
         "declaredMode": false,
         "idempotencyKey": false
     },
+    "warehouse.table.append": {
+        "kind": "database",
+        "identities": [
+            "app"
+        ],
+        "readOnly": false,
+        "declaredMode": false,
+        "idempotencyKey": true
+    },
     "service.request": {
         "kind": "service",
         "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.16.0",
+  "version": "1.18.0",
   "type": "module",
   "repository": {
     "type": "git",