@isomorph.ai/app-sdk 1.31.0 → 1.33.0

package/README.md

@@ -473,6 +473,32 @@ Without `onProgress` the call is unchanged and `ctx.progress` does nothing. At
 most 256 steps of up to 1 KiB each reach the page; further steps are dropped.
 The action still has the 300 s action budget. (Unreleased)
 
+## Watching a query: `data.watch`
+
+Progress, status and export screens re-read one query on a timer:
+
+```ts
+const stop = isomorph.data.watch(
+  () => isomorph.data.from('imports').select('*').eq('id', importId).single(),
+  ({ data }) => setImport(data),
+  { every: 3000, maxEvery: 15000 },   // the defaults
+);
+// on unmount
+stop();
+```
+
+`build()` runs at once and then every `every` ms (3 s). While the tab is
+hidden no read is made (where there is no `document`, as in Node, nothing is
+skipped). While the answer is unchanged the interval doubles up to `maxEvery`
+(15 s) and goes back to `every` on the first change; every result, changed or
+not, reaches `onResult`. A read that fails (a 401, the network) reaches it
+too, as `{ data: null, error }` with the error `await`ing the query would
+have thrown, and the timer keeps running. There is no new transport or route: each tick is an ordinary
+`QueryBuilder.execute()`, so it counts as app activity and is billed and
+authorized like any read. Watch the job row, not the data table. Use
+`realtime.channel` only when several people edit the same rows and sub-second
+updates matter. (1.32.0)
+
 ## Running on Lambda
 
 On a serverless cell Harbour runs an app's server code as Lambda functions, from a `runtime.zip` Kit Build makes; nothing in the app changes. The Web Function starts `dist/lambda-entry.js` (the zip's `index.js` is `import "@isomorph.ai/app-sdk/dist/lambda-entry.js"`), which serves actions on the port in `AWS_LAMBDA_HTTP_ENDPOINT` and stops on SIGTERM. The Event Function's handler is `node_modules/@isomorph.ai/app-sdk/dist/lambda-events-entry.handler`: `{"job": "<name>"}` runs that job once, as `--run-job <name>` does, and SQS records work queued runs until none are left.
@@ -485,7 +511,7 @@ On a serverless cell Harbour runs an app's server code as Lambda functions, from
 
 ### Email-arrival jobs
 
-On managed serverless hosting, an ordinary job can declare an inbox trigger instead of a schedule:
+On managed same-account serverless or Kubernetes hosting, an ordinary job can declare an inbox trigger instead of a schedule:
 
 ```ts
 export const trigger = {
@@ -506,8 +532,29 @@ may additionally require an exact sender. Deployment registers the job; activati
 the app owner's approved read access and background consent for that environment.
 Multiple apps share one provider watch per mailbox. Notifications enqueue the existing durable
 job runtime; duplicate deliveries retain the same run instead of rerunning a completed job.
-This does not add a per-app polling timer. Cluster hosting and cross-account delivery are not
-supported by this first release. Local manual job execution tests the handler, not the provider
+This does not add a per-app polling timer. Cross-account delivery is not supported. Local manual job execution tests the handler, not the provider
 subscription; verify a real incoming email after deployment before calling the trigger live.
 
 For PO-linked Zoho bills, first read the PO and send each returned `lineItemId` as the bill line’s `purchaseOrderItemId`. `itemId` identifies the catalog item; it does not identify the PO line. Purchase-order list results are summaries; read the document before comparing lines.
+
+
+### Folder-arrival jobs
+
+```ts
+export const trigger = {
+  type: 'file.created', connection: 'company-drive', resource: 'my-drive',
+  folderId: 'provider-folder-id', mimeTypes: ['application/pdf'],
+};
+export default async (ctx) => {
+  // ctx.input is FileArrivalInput: provider/sourceId/fileId/folderId/driveId?,
+  // name/mimeType/size/createdAt/observedAt. Read bytes through the existing integration.
+};
+```
+
+SharePoint uses its configured site alias as `resource` and also requires `driveId`.
+The trigger covers newly created direct-child PDF/XLSX files observed after activation;
+omit `mimeTypes` for both formats. Existing files moved into the folder, edits, renames,
+subfolders, shortcuts and native Google documents are excluded. No historical backfill.
+Background read consent is required. Existing file-read size limits still apply. Provider
+subscriptions and real upload acceptance must be verified after deployment. Retries retain
+one durable job run; accounting/email side effects still need their own idempotency keys.

package/dist/index.d.ts

@@ -39,6 +39,15 @@ export interface IsomorphResult<T> {
     data: T;
     count?: number;
 }
+/** `data.watch` timing: `every` ms between reads (default 3000), backing off to `maxEvery` (default 15000) while the answer does not change. */
+export interface WatchOptions {
+    every?: number;
+    maxEvery?: number;
+}
+/** What `data.watch` delivers: the read's result, or `{ data: null, error }` when the read failed (the error `await`ing the query would have thrown). */
+export type WatchResult = IsomorphResult<any> & {
+    error?: Error;
+};
 /** How Slack renders a message's `text`: plain text, or Slack mrkdwn (`*bold*`, `<url|label>`, `<@U123>`); plain when absent. */
 export type SlackTextFormat = 'plain' | 'mrkdwn';
 /**
@@ -1895,6 +1904,7 @@ export declare function createClient(options?: ClientOptions): {
     data: {
         from: <T = Record<string, unknown>>(table: string) => QueryBuilder<T, T[]>;
         rpc: <T = unknown>(name: string, args?: Record<string, unknown>) => Promise<T>;
+        watch: <T = Record<string, unknown>>(build: () => QueryBuilder<T, any>, onResult: (result: WatchResult) => void, options?: WatchOptions) => (() => void);
     };
     files: {
         createUpload: (input: {
@@ -1962,3 +1972,17 @@ export type HarbourResult<T> = IsomorphResult<T>;
 export type HarbourClient = IsomorphClient;
 /** @deprecated Internal transformation lane only; a kit app uses IsomorphCompatSource. */
 export type HarbourCompatSource = import('./supabase-compat.js').IsomorphCompatSource;
+/** Provider file metadata delivered to a file.created job; bytes are read through its connection. */
+export interface FileArrivalInput {
+    type: 'file.created';
+    provider: 'drive' | 'sharepoint';
+    sourceId: string;
+    fileId: string;
+    folderId: string;
+    driveId?: string;
+    name: string;
+    mimeType: string;
+    size: number;
+    createdAt: string;
+    observedAt: string;
+}

package/dist/index.js

@@ -707,6 +707,45 @@ export function createClient(options = {}) {
         data: {
             from: (table) => new QueryBuilder(transport, table),
             rpc: (name, args = {}) => transport.json(`/_harbour/data/rpc/${encodeURIComponent(name)}`, { method: 'POST', body: JSON.stringify(args) }),
+            // A query on a timer: QueryBuilder.execute() now and every `every` ms,
+            // no read while the tab is hidden, the interval doubling up to
+            // `maxEvery` while the answer is unchanged. No new transport or route;
+            // each read is an ordinary read (it counts as app activity), so watch
+            // the job row, not the data table. A failed read is delivered as
+            // { data: null, error } and the timer keeps going.
+            watch: (build, onResult, options = {}) => {
+                const every = options.every ?? 3_000;
+                const maxEvery = options.maxEvery ?? 15_000;
+                let delay = every;
+                let previous;
+                let stopped = false;
+                let timer;
+                const schedule = () => { if (!stopped)
+                    timer = setTimer(tick, delay); };
+                const tick = async () => {
+                    if (typeof document !== 'undefined' && document.hidden) {
+                        schedule();
+                        return;
+                    }
+                    let result;
+                    try {
+                        result = await build().execute();
+                    }
+                    catch (error) {
+                        result = { data: null, error: error instanceof Error ? error : new Error(String(error)) };
+                    }
+                    if (stopped)
+                        return;
+                    const json = JSON.stringify({ ...result, error: result.error?.message });
+                    delay = json === previous ? Math.min(delay * 2, maxEvery) : every;
+                    previous = json;
+                    onResult(result);
+                    schedule();
+                };
+                void tick();
+                return () => { stopped = true; if (timer !== undefined)
+                    clearTimer(timer); };
+            },
         },
         files: {
             createUpload: (input) => transport.json('/_harbour/files/uploads', { method: 'POST', body: JSON.stringify(input) }),

package/dist/jobs.d.ts

@@ -8,12 +8,23 @@ export interface EmailArrivalTrigger {
         subjectContains?: string;
     };
 }
+export declare const FILE_MIME_TYPES: readonly ["application/pdf", "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"];
+export declare const providerFileId: (value: unknown) => value is string;
+export interface FileCreatedTrigger {
+    type: 'file.created';
+    connection: string;
+    resource: string;
+    folderId: string;
+    driveId?: string;
+    mimeTypes?: string[];
+}
+export type EventTrigger = EmailArrivalTrigger | FileCreatedTrigger;
 export interface JobDefinition {
     name: string;
     schedule?: string;
-    trigger?: EmailArrivalTrigger;
+    trigger?: EventTrigger;
 }
-export declare function emailArrivalTrigger(value: unknown): EmailArrivalTrigger;
+export declare function eventTrigger(value: unknown): EventTrigger;
 export interface JobContext {
     scheduledAt: string;
     runId?: string;

package/dist/jobs.js

@@ -6,10 +6,14 @@ import { stripTypeScriptTypes } from 'node:module';
 import { parse } from 'acorn';
 export const JOBS_DIR = 'jobs';
 const LOGICAL_NAME = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+export const FILE_MIME_TYPES = ['application/pdf', 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'];
+export const providerFileId = (value) => typeof value === 'string' && /^[A-Za-z0-9!._,=-]{1,256}$/.test(value);
 function literalObject(node) {
     const value = node;
     if (value?.type === 'Literal')
         return value.value;
+    if (value?.type === 'ArrayExpression')
+        return value.elements.map(literalObject);
     if (value?.type !== 'ObjectExpression')
         throw new Error('trigger must be a literal object');
     const result = {};
@@ -23,7 +27,17 @@ function literalObject(node) {
     }
     return result;
 }
-export function emailArrivalTrigger(value) {
+export function eventTrigger(value) {
+    if (value?.type === 'file.created') {
+        const t = value;
+        if (Object.keys(t).some(k => !['type', 'connection', 'resource', 'folderId', 'driveId', 'mimeTypes'].includes(k))
+            || typeof t.connection !== 'string' || !LOGICAL_NAME.test(t.connection)
+            || typeof t.resource !== 'string' || !t.resource.trim() || t.resource.length > 320
+            || !providerFileId(t.folderId) || (t.driveId !== undefined && !providerFileId(t.driveId))
+            || (t.mimeTypes !== undefined && (!Array.isArray(t.mimeTypes) || !t.mimeTypes.length || t.mimeTypes.length > 2 || new Set(t.mimeTypes).size !== t.mimeTypes.length || t.mimeTypes.some(m => !FILE_MIME_TYPES.includes(m)))))
+            throw new Error('file.created requires a connection, resource, folder ID and optional PDF/XLSX MIME types');
+        return t;
+    }
     const trigger = value;
     if (!trigger || typeof trigger !== 'object' || Object.keys(trigger).some(key => !['type', 'connection', 'resource', 'filter'].includes(key))
         || trigger.type !== 'email.arrived' || trigger.resource !== 'inbox' || typeof trigger.connection !== 'string' || !LOGICAL_NAME.test(trigger.connection))
@@ -102,7 +116,7 @@ export async function discoverJobs(root) {
                     if (statement.declaration.kind !== 'const')
                         fail('export one literal trigger with export const trigger.');
                     try {
-                        trigger = emailArrivalTrigger(literalObject(declaration.init));
+                        trigger = eventTrigger(literalObject(declaration.init));
                     }
                     catch (error) {
                         fail(String(error));

package/dist/lambda-events-entry.js

@@ -18,9 +18,11 @@ function eventRuntime() {
     return runtime;
 }
 export async function handler(event) {
-    const { job, Records: records, mailArrival } = (event && typeof event === 'object' ? event : {});
-    if (mailArrival !== undefined)
-        return eventRuntime().acceptMailArrival(mailArrival);
+    const { job, Records: records, mailArrival, eventArrival } = (event && typeof event === 'object' ? event : {});
+    if (eventArrival !== undefined && mailArrival !== undefined)
+        throw new Error('ambiguous arrival envelope');
+    if (eventArrival !== undefined || mailArrival !== undefined)
+        return eventRuntime().acceptEventArrival(eventArrival ?? mailArrival);
     if (typeof job === 'string' && job) {
         if (!(await eventRuntime().runJobOnce(job)))
             throw new Error(`jobs/${job}.ts did not run to completion; the log above names why`);

package/dist/runtime.d.ts

@@ -50,7 +50,7 @@ export declare class Runs {
     enqueue(job: string, input: unknown, owner: string): Promise<{
         id: string;
     }>;
-    enqueueMail(delivery: {
+    enqueueEvent(delivery: {
         deliveryId: string;
         job: string;
         input: unknown;
@@ -61,7 +61,7 @@ export declare class Runs {
     get(id: string, owner: string): Promise<JobRun | null>;
     cancel(id: string, owner: string): Promise<JobRun | null>;
     /** Rows whose lease ran out go back to the queue while attempts remain, else fail; how many there were. */
-    reclaim(now: Date): Promise<number>;
+    reclaim(now: Date, active?: ReadonlySet<string>): Promise<number>;
     /** Claims the oldest queued run by a conditional update; null when the queue is empty or another worker won. */
     claim(now: Date): Promise<JobRun | null>;
     progress(id: string, percent: number, note?: string): Promise<void>;
@@ -106,8 +106,10 @@ export declare class Runtime {
     private readonly timers;
     private stopped;
     private aiBinding;
-    private queueLive;
+    private queueWorkers;
     private queueWake;
+    private claimTail;
+    private readonly activeRuns;
     private readonly runs;
     private session;
     private readonly log;
@@ -127,8 +129,8 @@ export declare class Runtime {
      */
     drainQueue(): Promise<void>;
     /**
-     * Starts the queue loop unless it is already live. The first pass runs at
-     * once; each further pass follows QUEUE_POLL_MS after one that found work
+     * Starts one free execution slot, up to the fixed local bound. Its first
+     * pass runs at once; each further pass follows QUEUE_POLL_MS after one that found work
      * (or threw: a gateway that is waking answers 5xx, and the row that woke
      * the loop is still there). A pass that finds nothing ends the loop with no
      * timer armed, so an idle runtime makes no data calls at all.
@@ -141,7 +143,7 @@ export declare class Runtime {
      * would have been. False when the app has no such job, the gateway's data
      * path never answered, or the handler threw; the log names which.
      */
-    acceptMailArrival(value: unknown): Promise<void>;
+    acceptEventArrival(value: unknown): Promise<void>;
     runJobOnce(name: string, now?: Date): Promise<boolean>;
     private awaitDataPath;
     stop(): Promise<void>;
@@ -152,10 +154,11 @@ export declare class Runtime {
     /** One scheduled run; true when the handler returned, false when it threw or the last tick's run is still going. */
     private runScheduled;
     /**
-     * One pass of the queue loop: reclaim expired leases, claim one run, run it.
+     * One worker pass: reclaim interrupted leases, claim one run, then execute
+     * outside the claim lock so another slot can handle unrelated work.
      * True when the pass found work — a lease reclaimed, a run claimed, or the
      * run it finished left a retry queued — so the loop should look again; false
-     * when the queue is empty (or another pass is already going).
+     * when the queue is empty or both execution slots are occupied.
      */
     work(): Promise<boolean>;
     private serve;

package/dist/runtime.js

@@ -20,7 +20,8 @@
 // database calls: the runtime is the process that serves the enqueue action
 // and the one that finishes every run, so it knows when work exists. It runs
 // one pass at start (reclaiming whatever a crashed predecessor left running
-// and draining any backlog), then loops every QUEUE_POLL_MS only while a pass
+// and draining any backlog), filling at most two local execution slots. Each
+// slot loops every QUEUE_POLL_MS only while a pass
 // found something — a claimed run, a reclaimed lease, a run that finished with
 // retries queued — and stops with no timer armed once the queue is empty. An
 // enqueue starts the loop again. This holds because kit-runtime is pinned to
@@ -67,7 +68,7 @@ import { pathToFileURL } from 'node:url';
 import { createClient, gatewayRequest, IsomorphError } from './index.js';
 import { userGroupsFromHeader } from './user-groups.js';
 import { userRole } from './user-role.js';
-import { discoverJobs, exportsTrue, invokeJob, loadHandler, JOBS_DIR } from './jobs.js';
+import { FILE_MIME_TYPES, providerFileId, 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();
@@ -83,6 +84,7 @@ export const CANCEL_RUN_ACTION = 'isomorph-jobs-cancel';
 const LOGICAL_NAME = /^[a-z0-9][a-z0-9_-]{0,63}$/;
 const MAX_BODY_BYTES = 1 << 20;
 const LEASE_MS = 5 * 60_000;
+const QUEUE_WORKERS = 2;
 const QUEUE_POLL_MS = 2_000;
 const TOKEN_REFRESH_MS = 60_000;
 // A gateway session lasts an hour. An action runs at most 300 s, so a request
@@ -204,7 +206,7 @@ export class Runs {
         const { data } = await this.table().insert({ job, input: input ?? null, status: 'queued', attempt: 0, max_attempts: DEFAULT_MAX_ATTEMPTS, progress: 0, owner_subject: owner, cancel_requested: false }).select('id').single();
         return { id: data.id };
     }
-    async enqueueMail(delivery) {
+    async enqueueEvent(delivery) {
         const hex = createHash('sha256').update(`mail:${delivery.deliveryId}`).digest('hex');
         const id = `${hex.slice(0, 8)}-${hex.slice(8, 12)}-5${hex.slice(13, 16)}-a${hex.slice(17, 20)}-${hex.slice(20, 32)}`;
         try {
@@ -230,13 +232,14 @@ export class Runs {
         return data;
     }
     /** Rows whose lease ran out go back to the queue while attempts remain, else fail; how many there were. */
-    async reclaim(now) {
+    async reclaim(now, active = new Set()) {
         const { data: expired } = await this.table().select('*').eq('status', 'running').lt('lease_until', now.toISOString()).limit(20);
-        for (const run of expired) {
+        const interrupted = expired.filter(run => !active.has(run.id));
+        for (const run of interrupted) {
             const exhausted = run.attempt >= run.max_attempts;
             await this.table().update({ status: exhausted ? 'failed' : 'queued', error: exhausted ? 'the worker was interrupted and no attempts remain' : run.error, lease_until: null, updated_at: now.toISOString() }).eq('id', run.id).eq('status', 'running');
         }
-        return expired.length;
+        return interrupted.length;
     }
     /** Claims the oldest queued run by a conditional update; null when the queue is empty or another worker won. */
     async claim(now) {
@@ -270,10 +273,10 @@ export class Runtime {
     timers = [];
     stopped = false;
     aiBinding;
-    // The queue loop is live while a pass runs or its next pass is timed; a
-    // wake that arrives mid-pass is remembered so the pass after it looks again.
-    queueLive = false;
-    queueWake = false;
+    queueWorkers = 0;
+    queueWake = 0;
+    claimTail = Promise.resolve();
+    activeRuns = new Set();
     runs;
     // Built on first use: the AWS signing modules load only on a serverless
     // cell, so a cluster runtime never imports them.
@@ -339,8 +342,8 @@ export class Runtime {
             await new Promise((wake) => setTimeout(wake, this.options.queuePollMs ?? QUEUE_POLL_MS));
     }
     /**
-     * Starts the queue loop unless it is already live. The first pass runs at
-     * once; each further pass follows QUEUE_POLL_MS after one that found work
+     * Starts one free execution slot, up to the fixed local bound. Its first
+     * pass runs at once; each further pass follows QUEUE_POLL_MS after one that found work
      * (or threw: a gateway that is waking answers 5xx, and the row that woke
      * the loop is still there). A pass that finds nothing ends the loop with no
      * timer armed, so an idle runtime makes no data calls at all.
@@ -348,17 +351,16 @@ export class Runtime {
     wakeQueue() {
         if (this.stopped || !this.worksQueue())
             return;
-        if (this.queueLive) {
-            this.queueWake = true;
+        this.queueWake += 1;
+        if (this.queueWorkers >= QUEUE_WORKERS)
             return;
-        }
-        this.queueLive = true;
+        this.queueWorkers += 1;
         const pass = async () => {
             if (this.stopped) {
-                this.queueLive = false;
+                this.queueWorkers -= 1;
                 return;
             }
-            this.queueWake = false;
+            const wake = this.queueWake;
             let again = true;
             try {
                 again = await this.work();
@@ -366,14 +368,10 @@ export class Runtime {
             catch (error) {
                 this.log(`queue pass failed: ${error instanceof Error ? error.message : String(error)}`);
             }
-            if (this.stopped) {
-                this.queueLive = false;
-                return;
-            }
-            if (again || this.queueWake)
+            if (!this.stopped && (again || wake !== this.queueWake))
                 this.timers.push(setTimeout(() => void pass(), this.options.queuePollMs ?? QUEUE_POLL_MS));
             else
-                this.queueLive = false;
+                this.queueWorkers -= 1;
         };
         void pass();
     }
@@ -384,23 +382,36 @@ export class Runtime {
      * would have been. False when the app has no such job, the gateway's data
      * path never answered, or the handler threw; the log names which.
      */
-    async acceptMailArrival(value) {
+    async acceptEventArrival(value) {
         const delivery = value;
         if (!delivery || typeof delivery.deliveryId !== 'string' || !/^[a-f0-9]{64}$/.test(delivery.deliveryId)
-            || typeof delivery.owner !== 'string' || !delivery.owner || delivery.owner.length > 320
-            || !delivery.input || !['gmail', 'outlook'].includes(delivery.input.provider)
-            || typeof delivery.input.messageId !== 'string' || !delivery.input.messageId || delivery.input.messageId.length > 2048
-            || typeof delivery.input.threadId !== 'string' || delivery.input.threadId.length > 2048
-            || typeof delivery.input.receivedAt !== 'string' || !Number.isFinite(Date.parse(delivery.input.receivedAt)))
-            throw new Error('invalid mail arrival');
+            || typeof delivery.owner !== 'string' || !delivery.owner || delivery.owner.length > 320 || !delivery.input || typeof delivery.input !== 'object')
+            throw new Error('invalid event arrival');
         this.inventory = await discover(this.options.root);
         const job = this.inventory.jobs.find(job => job.name === delivery.job);
-        if (!job?.trigger || job.trigger.connection !== delivery.input.sourceId)
-            throw new Error('mail trigger is not declared by this deployed app');
+        const input = delivery.input;
+        if (!job?.trigger || job.trigger.connection !== input.sourceId)
+            throw new Error('event trigger is not declared by this deployed app');
+        if (job.trigger.type === 'file.created') {
+            const instant = (v) => typeof v === 'string' && /^\d{4}-\d{2}-\d{2}T/.test(v) && Number.isFinite(Date.parse(v));
+            if (Object.keys(input).some(k => !['type', 'provider', 'sourceId', 'fileId', 'folderId', 'driveId', 'name', 'mimeType', 'size', 'createdAt', 'observedAt'].includes(k))
+                || input.type !== 'file.created' || !['drive', 'sharepoint'].includes(String(input.provider)) || !providerFileId(input.fileId) || input.folderId !== job.trigger.folderId
+                || (input.driveId !== undefined && !providerFileId(input.driveId)) || (input.provider === 'sharepoint' && !input.driveId)
+                || (job.trigger.driveId !== undefined && input.driveId !== job.trigger.driveId)
+                || typeof input.name !== 'string' || !input.name || input.name.length > 1024 || !Number.isSafeInteger(input.size) || Number(input.size) < 0
+                || !(job.trigger.mimeTypes ?? [...FILE_MIME_TYPES]).includes(String(input.mimeType))
+                || !instant(input.createdAt) || !instant(input.observedAt))
+                throw new Error('invalid file arrival');
+        }
+        else if (input.type !== undefined || !['gmail', 'outlook'].includes(String(input.provider))
+            || typeof input.messageId !== 'string' || !input.messageId || input.messageId.length > 2048
+            || typeof input.threadId !== 'string' || input.threadId.length > 2048
+            || typeof input.receivedAt !== 'string' || !Number.isFinite(Date.parse(input.receivedAt)))
+            throw new Error('invalid mail arrival');
         await this.refreshToken(JOB_SESSION_MIN_VALIDITY_MS);
         if (!this.options.gatewayUrl || this.options.mode === 'gate' || this.options.jobRuns === false || !(await this.awaitDataPath()))
-            throw new Error('mail arrival requires durable job runs');
-        const queued = await this.runs.enqueueMail(delivery);
+            throw new Error('event arrival requires durable job runs');
+        const queued = await this.runs.enqueueEvent(delivery);
         await this.signalQueuedRun(queued.id);
     }
     async runJobOnce(name, now = new Date()) {
@@ -539,21 +550,38 @@ export class Runtime {
         }
     }
     /**
-     * One pass of the queue loop: reclaim expired leases, claim one run, run it.
+     * One worker pass: reclaim interrupted leases, claim one run, then execute
+     * outside the claim lock so another slot can handle unrelated work.
      * True when the pass found work — a lease reclaimed, a run claimed, or the
      * run it finished left a retry queued — so the loop should look again; false
-     * when the queue is empty (or another pass is already going).
+     * when the queue is empty or both execution slots are occupied.
      */
     async work() {
-        if (this.running.has('queue'))
-            return false;
-        this.running.add('queue');
+        // Serialize only the claim, not the handler. A second slot must not race
+        // the same oldest row or reclaim a long handler still running here.
+        const previous = this.claimTail;
+        let release;
+        this.claimTail = new Promise(resolve => { release = resolve; });
+        await previous;
+        let run;
+        let reclaimed = 0;
+        try {
+            if (this.activeRuns.size >= QUEUE_WORKERS)
+                return false;
+            const now = new Date();
+            reclaimed = await this.runs.reclaim(now, this.activeRuns);
+            run = await this.runs.claim(now);
+            if (run)
+                this.activeRuns.add(run.id);
+        }
+        finally {
+            release();
+        }
+        if (!run)
+            return reclaimed > 0;
+        this.wakeQueue(); // Fill the spare slot when startup discovers a backlog.
         try {
             const now = new Date();
-            const reclaimed = await this.runs.reclaim(now);
-            const run = await this.runs.claim(now);
-            if (!run)
-                return reclaimed > 0;
             if (!this.inventory.jobs.some((job) => job.name === run.job)) {
                 await this.runs.finish({ ...run, attempt: run.max_attempts }, { error: `no jobs/${run.job}.ts in this app` });
                 return true;
@@ -574,7 +602,7 @@ export class Runtime {
             return true;
         }
         finally {
-            this.running.delete('queue');
+            this.activeRuns.delete(run.id);
         }
     }
     async serve(request, response) {
@@ -645,7 +673,7 @@ export class Runtime {
             if (name === 'isomorph-mail-arrival') {
                 if (header(request, 'X-Harbour-Verified-Mail-Arrival') !== 'true')
                     return refuse(response, 403, 'FORBIDDEN', 'governed mail delivery is required', requestId);
-                await this.acceptMailArrival(input);
+                await this.acceptEventArrival(input);
                 return answer(response, 200, { data: { accepted: true } }, requestId);
             }
             if (name.startsWith(RESERVED_PREFIX))

package/package.json

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