@friggframework/core 2.0.0--canary.693.d8859c2.0 → 2.0.0--canary.694.f66a64a.0

package/database/documentdb-utils.js

@@ -25,6 +25,8 @@ async function findMany(client, collection, filter = {}, options = {}) {
     if (options.projection) command.projection = options.projection;
     if (options.sort) command.sort = options.sort;
     if (options.limit) command.limit = options.limit;
+    // The first batch holds 101 documents unless asked for more; a page wants all of its rows.
+    if (options.batchSize) command.batchSize = options.batchSize;
     const result = await client.$runCommandRaw(command);
     return result?.cursor?.firstBatch || [];
 }

package/handlers/workers/integration-triggers.js

@@ -0,0 +1,25 @@
+/**
+ * The `{integration}Triggers` functions (ADR-055 §2-3): one per integration that declares triggers. Devtools gives
+ * each one schedule per distinct tick (`{ tick: '5m', time }`) and one per `at` trigger (`{ at, time }`); this only
+ * hands the event to the tick use case.
+ */
+const { createHandler } = require('@friggframework/core');
+const { loadAppDefinition } = require('../app-definition-loader');
+const { hasTriggers } = require('../../integrations/triggers');
+const { runTriggerTick } = require('../../integrations/use-cases/run-trigger-tick');
+
+const handlers = {};
+const { integrations: integrationClasses } = loadAppDefinition();
+
+for (const IntegrationClass of integrationClasses) {
+    if (!hasTriggers(IntegrationClass)) continue;
+    handlers[IntegrationClass.Definition.name] = {
+        tick: createHandler({
+            eventName: `Trigger tick for ${IntegrationClass.Definition.name}`,
+            isUserFacingResponse: false,
+            method: async (event, context) => runTriggerTick(IntegrationClass, event || {}, context),
+        }),
+    };
+}
+
+module.exports = { handlers };

package/infrastructure/scheduler/recurrence.js

@@ -0,0 +1,204 @@
+/**
+ * Recurrence: how often something repeats, in a form no host owns.
+ *
+ *   { every: '15m' }                               every 15 minutes ('30s' is refused: ticks are whole minutes)
+ *   { cron: '0 9 * * 1-5', timezone: 'America/New_York' }   standard five-field cron (minute hour dom month dow)
+ *
+ * Recurring triggers (ADR-055, integrations/triggers.js) use it for the timing an installation may choose and for
+ * the floor a developer sets on that choice. Nothing here creates a host schedule: the tick asks `lastFiringIn`
+ * whether a cron fired since the previous tick, so a per-installation calendar needs no schedule of its own.
+ *
+ * Pure; no I/O.
+ */
+
+const EVERY = /^(\d+)\s*(m|h|d)$/;
+const UNIT_MINUTES = { m: 1, h: 60, d: 1440 };
+
+/** '15m' -> 15, '2h' -> 120, '1d' -> 1440. Anything else -> null. */
+function parseEvery(every) {
+    const m = EVERY.exec(String(every ?? '').trim());
+    if (!m) return null;
+    const n = Number(m[1]) * UNIT_MINUTES[m[2]];
+    return n > 0 ? n : null;
+}
+
+const MONTHS = ['JAN', 'FEB', 'MAR', 'APR', 'MAY', 'JUN', 'JUL', 'AUG', 'SEP', 'OCT', 'NOV', 'DEC'];
+const DAYS = ['SUN', 'MON', 'TUE', 'WED', 'THU', 'FRI', 'SAT'];
+const FIELDS = [
+    { name: 'minute', min: 0, max: 59 },
+    { name: 'hour', min: 0, max: 23 },
+    { name: 'day of month', min: 1, max: 31 },
+    { name: 'month', min: 1, max: 12, names: MONTHS, base: 1 },
+    { name: 'day of week', min: 0, max: 7, names: DAYS, base: 0 },   // 0 and 7 are both Sunday
+];
+
+function atom(token, field) {
+    const t = token.toUpperCase();
+    if (field.names) {
+        const i = field.names.indexOf(t);
+        if (i >= 0) return i + field.base;
+    }
+    if (!/^\d+$/.test(t)) return null;
+    const n = Number(t);
+    return n >= field.min && n <= field.max ? n : null;
+}
+
+/** One cron field -> the sorted set of values it matches, or an error string. */
+function parseField(text, field) {
+    const out = new Set();
+    for (const part of text.split(',')) {
+        const [range, stepText] = part.split('/');
+        if (part.split('/').length > 2) return `${field.name}: "${part}" has more than one step`;
+        const step = stepText === undefined ? 1 : Number(stepText);
+        if (!Number.isInteger(step) || step < 1) return `${field.name}: step "${stepText}" is not a positive whole number`;
+        let lo, hi;
+        if (range === '*') { lo = field.min; hi = field.name === 'day of week' ? 6 : field.max; }
+        else if (range.includes('-')) {
+            const [a, b] = range.split('-');
+            lo = atom(a, field); hi = atom(b, field);
+            if (lo === null || hi === null) return `${field.name}: "${range}" is out of range`;
+            if (lo > hi) return `${field.name}: "${range}" runs backwards`;
+        } else {
+            lo = atom(range, field);
+            if (lo === null) return `${field.name}: "${range}" is out of range`;
+            hi = stepText === undefined ? lo : (field.name === 'day of week' ? 6 : field.max);
+        }
+        for (let v = lo; v <= hi; v += step) out.add(field.name === 'day of week' && v === 7 ? 0 : v);
+    }
+    return [...out].sort((a, b) => a - b);
+}
+
+/**
+ * Parse a five-field cron. Returns { fields: [Set x5], restricted: { dom, dow } } or { error }.
+ * `restricted` records whether day-of-month / day-of-week were given (not `*`), which decides how they combine.
+ */
+function parseCron(cron) {
+    const parts = String(cron ?? '').trim().split(/\s+/);
+    if (parts.length !== 5 || parts[0] === '') return { error: 'A cron expression has five fields: minute hour day-of-month month day-of-week' };
+    const fields = [];
+    for (let i = 0; i < 5; i += 1) {
+        const v = parseField(parts[i], FIELDS[i]);
+        if (typeof v === 'string') return { error: v };
+        fields.push(new Set(v));
+    }
+    return { fields, parts, restricted: { dom: parts[2] !== '*', dow: parts[4] !== '*' } };
+}
+
+/** Does a parsed cron fire at this (UTC-free, wall-clock) minute? Standard cron: dom and dow OR when both are set. */
+function matches(parsed, d) {
+    const [mi, h, dom, mon, dow] = parsed.fields;
+    if (!mi.has(d.getUTCMinutes()) || !h.has(d.getUTCHours()) || !mon.has(d.getUTCMonth() + 1)) return false;
+    const domHit = dom.has(d.getUTCDate()), dowHit = dow.has(d.getUTCDay());
+    if (parsed.restricted.dom && parsed.restricted.dow) return domHit || dowHit;
+    return domHit && dowHit;
+}
+
+/**
+ * The shortest gap, in minutes, between two firings. For `every` it is the interval; for cron it is measured over
+ * fifteen months of wall-clock minutes (long enough to see every month and weekday combination), so a floor such as
+ * "no more often than every 15 minutes" is checked against what the expression really does, not its spelling.
+ * Returns Infinity for an expression that fires at most once in that window, null when invalid.
+ */
+function minGapMinutes(recurrence) {
+    if (recurrence?.every !== undefined) return parseEvery(recurrence.every);
+    const parsed = parseCron(recurrence?.cron);
+    return parsed.error ? null : scan(parsed).best;
+}
+
+/** Walk fifteen months of firings: how many there are and the shortest gap between two. */
+function scan(parsed) {
+    const [mi, h] = parsed.fields;
+    const minutes = [...mi], hours = [...h];
+    let prev = null, best = Infinity, count = 0;
+    const start = Date.UTC(2027, 0, 1);
+    for (let day = 0; day < 457 && best > 1; day += 1) {     // fifteen months: every month and weekday pairing
+        const midnight = start + day * 86400000;
+        if (!matches(parsed, new Date(midnight + hours[0] * 3600000 + minutes[0] * 60000))) continue;
+        for (const hr of hours) {
+            for (const mn of minutes) {
+                const t = day * 1440 + hr * 60 + mn;
+                if (prev !== null && t - prev < best) best = t - prev;
+                prev = t;
+                count += 1;
+            }
+        }
+    }
+    return { best, count };
+}
+
+/** Is `tz` an IANA time zone this runtime knows? */
+function isTimeZone(tz) {
+    try { new Intl.DateTimeFormat('en-US', { timeZone: tz }); return true; } catch { return false; }
+}
+
+/**
+ * Validate a recurrence. `min` is an optional floor ('15m'): the expression must never fire more often.
+ * @returns {string[]} problems, empty when valid
+ */
+function validateRecurrence(recurrence, { min } = {}) {
+    const problems = [];
+    if (!recurrence || typeof recurrence !== 'object') return ['Give a schedule as { every } or { cron, timezone? }'];
+    const hasEvery = recurrence.every !== undefined, hasCron = recurrence.cron !== undefined;
+    if (hasEvery === hasCron) return ['Give exactly one of every or cron'];
+    if (hasEvery && parseEvery(recurrence.every) === null) problems.push(`every "${recurrence.every}" is not a whole number of minutes, hours or days (15m, 2h, 1d)`);
+    if (hasCron) {
+        const parsed = parseCron(recurrence.cron);
+        if (parsed.error) problems.push(parsed.error);
+        // EventBridge (and Quartz) cannot express "this day of month OR this weekday"; refuse it everywhere, so a
+        // schedule that validates here runs on every host.
+        else if (parsed.restricted.dom && parsed.restricted.dow) problems.push('Restrict day of month or day of week, not both');
+        else if (scan(parsed).count === 0) problems.push(`"${recurrence.cron}" never fires`);
+    }
+    if (recurrence.timezone !== undefined && (hasEvery || !isTimeZone(recurrence.timezone))) {
+        problems.push(hasEvery ? 'timezone applies to cron schedules only' : `Unknown time zone "${recurrence.timezone}"`);
+    }
+    if (!problems.length && min !== undefined) {
+        const floor = parseEvery(min);
+        const gap = minGapMinutes(recurrence);
+        if (floor === null) problems.push(`minimum interval "${min}" is not a duration (15m, 2h, 1d)`);
+        else if (gap !== null && gap < floor) problems.push(`Runs every ${gap} minute${gap === 1 ? '' : 's'} at its most frequent; the minimum is ${min}`);
+    }
+    return problems;
+}
+
+/** The comparable identity of a recurrence (what decides whether a stored schedule must be updated). */
+function recurrenceKey(r) {
+    if (!r) return '';
+    return r.every !== undefined ? `every:${parseEvery(r.every)}` : `cron:${String(r.cron).trim().split(/\s+/).join(' ')}@${r.timezone || 'UTC'}`;
+}
+
+const wallClockFormats = new Map();
+/**
+ * The wall-clock time of an instant in a time zone, as a Date whose UTC fields hold that wall clock (what `matches`
+ * reads). Seconds are dropped.
+ */
+function wallClock(ms, timezone = 'UTC') {
+    if (timezone === 'UTC') return new Date(Math.floor(ms / 60000) * 60000);
+    let format = wallClockFormats.get(timezone);
+    if (!format) {
+        format = new Intl.DateTimeFormat('en-US', { timeZone: timezone, hourCycle: 'h23', year: 'numeric', month: 'numeric', day: 'numeric', hour: 'numeric', minute: 'numeric' });
+        wallClockFormats.set(timezone, format);
+    }
+    const p = Object.fromEntries(format.formatToParts(new Date(ms)).map((x) => [x.type, x.value]));
+    return new Date(Date.UTC(Number(p.year), Number(p.month) - 1, Number(p.day), Number(p.hour) % 24, Number(p.minute)));
+}
+
+/**
+ * The latest whole minute in (fromMs, toMs] at which a cron recurrence fires in its time zone, as epoch ms, or null.
+ *
+ * This is how one shared tick serves a calendar each installation chose: the tick asks whether the cron fired since
+ * the previous tick. It is stateless, so a tick that runs twice for the same slot gives the same answer (and the same
+ * `scheduledFor`, which is what a run dedupes on). Real instants are walked, so a wall-clock time a DST change skips
+ * does not fire that day, and one it repeats fires twice.
+ */
+function lastFiringIn(recurrence, fromMs, toMs) {
+    const parsed = parseCron(recurrence?.cron);
+    if (parsed.error) return null;
+    const tz = recurrence.timezone || 'UTC';
+    for (let t = Math.floor(toMs / 60000) * 60000; t > fromMs; t -= 60000) {
+        if (matches(parsed, wallClock(t, tz))) return t;
+    }
+    return null;
+}
+
+module.exports = { parseEvery, parseCron, minGapMinutes, validateRecurrence, recurrenceKey, isTimeZone, matches, wallClock, lastFiringIn };

package/integrations/data-defined/README.md

@@ -25,7 +25,7 @@ installation (Integration.config)         ─┘                          │
 | `steps.js`, `interpreter.js`, `transforms.js` | The step catalogue and the interpreter |
 | `validate.js` | Structure + cross-references against the manifests (steps, templates, views, settings, `$.install`) |
 | `manifests.js` | `validateManifest`: the manifests themselves (kinds, option lists, account fields) |
-| `compile.js` | Definition + installation → events, webhook routes, schedules, user actions |
+| `compile.js` | Definition + installation → events, webhook routes, recurring triggers, user actions |
 | `runtime.js` | Ports (Api calls, link store), `runWorkflow`, `runQuery`, `renderSurface`, `runLifecycle`, `resolveOptions`, `installContext` |
 | `versioning.js` | `diff`, `checkBump`, `planUpgrade` |
 | `data-defined-integration.js` | `defineIntegrationClass`: the IntegrationBase subclass that runs it all |
@@ -96,6 +96,24 @@ different document at the same version is refused. So is a version that is not n
 semver bump smaller than the changes. Publishing goes through a conditional write, so two concurrent publishes of one
 version cannot both win. With `memoryDefinitions()` (definitions bundled in the app) the admin routes answer 501.
 
+## Schedules
+
+A schedule-triggered workflow or a polling sync is a recurring trigger (ADR-055), the same mechanism hand-written
+integrations declare as `Definition.triggers` (ADR-063 §15a). Nothing is scheduled per installation: the class
+declares `instanceTriggers: { tick: '5m' }`, so devtools provisions one tick function for it, and each tick compiles
+every ENABLED installation's pinned definition with its config and queues the runs that are due. Mark one
+`configurable` to let installations pick their own timing, optionally with a floor:
+
+```json
+"trigger": { "type": "schedule", "cron": "0 16 * * 1-5", "timezone": "America/New_York", "configurable": { "min": "1h" } }
+"ongoing": { "mode": "poll", "every": "15m", "configurable": true }
+```
+
+The choice goes in `workflows.<id>.schedule` / `syncs.<id>.schedule` (the configure form offers the field). An
+interval runs on whole multiples of the 5-minute tick; a cron runs on the first tick after it fires. Create, update,
+upgrade and delete need no scheduler call: the next tick reads the new state. A run is deduped on
+`tick:<event>:<scheduledFor>`, so a redelivered run happens once.
+
 ## Steps (v0.1)
 
 Built-ins: `links.find`, `links.upsert`, `map`, `merge`, `template`, `set`, `stop`, `foreach` (≤1000), `branch`, `code`.
@@ -164,6 +182,4 @@ CLI as a child process; it fails, rather than skips, if `ajv` is missing. Core's
   the existing `SYNC_PAGE` pattern. `runSync` throws until then.
 - `delay` / wait steps, approvals that pause a run, and per-tenant rate limits.
 - The host renderers (the HubSpot app extension and Phone panel that draw `renderSurface` output).
-- Registering `compiled.schedules` as recurring schedules (Frigg's scheduler commands are one-time jobs). They compile
-  today; nothing creates them yet.
 - Rebuilding `link:` / `idx:` rows after an identity change; `planUpgrade` reports it as `relink` / `reindex`.

package/integrations/data-defined/compile.js

@@ -2,7 +2,7 @@
  * Compile a definition + one installation into what Frigg runs: an events map shaped exactly like a hand-written
  * integration's `this.events`, plus the routing tables the runtime needs. Pure; no I/O.
  *
- * Only what the installation has enabled is compiled, so a disabled workflow has no event, no route and no schedule.
+ * Only what the installation has enabled is compiled, so a disabled workflow has no event, no route and no trigger.
  *
  * Event names:  SYNC_<ID>_BACKFILL (USER_ACTION) · SYNC_<ID>_PAGE (QUEUE) · SYNC_<ID>_ONGOING (WEBHOOK|CRON)
  *               WF_<ID> (WEBHOOK|CRON|USER_ACTION|QUEUE) · Q_<ID> (ROUTE) · UI_<ID> (ROUTE)
@@ -17,7 +17,7 @@ function isOn(item, chosen) {
 function compile(def, installation = {}) {
     const events = {};
     const webhooks = {};      // moduleKey -> topic -> [eventName]
-    const schedules = [];     // { event, cron, timezone }
+    const triggers = [];      // recurring triggers (integrations/triggers.js): { name, every | cron, timezone?, configurable, choice }
     const userActions = [];   // { event, label, from }
     const routes = [];        // { method, path, event }
     const add = (name, e) => { events[name] = e; return name; };
@@ -39,7 +39,7 @@ function compile(def, installation = {}) {
             }
         } else if (mode === 'poll') {
             const n = add(eventName('SYNC', s.id, 'ONGOING'), { type: 'CRON', ref: { kind: 'sync', id: s.id, phase: 'ongoing' } });
-            schedules.push({ event: n, every: s.ongoing.every || '15m' });
+            triggers.push({ name: n, every: s.ongoing.every || '15m', configurable: s.ongoing.configurable || false, choice: installation.syncs?.[s.id]?.schedule });
         }
     }
 
@@ -49,7 +49,10 @@ function compile(def, installation = {}) {
         const type = { webhook: 'WEBHOOK', schedule: 'CRON', userAction: 'USER_ACTION', syncRecord: 'QUEUE' }[t.type];
         const n = add(eventName('WF', w.id), { type, ...(type === 'USER_ACTION' ? { userActionType: 'DATA_ACTION', title: t.label } : {}), ref: { kind: 'workflow', id: w.id } });
         if (t.type === 'webhook') route(t.module, t.topic, n);
-        if (t.type === 'schedule') schedules.push({ event: n, cron: t.cron, timezone: t.timezone || 'UTC' });
+        if (t.type === 'schedule') {
+            const timing = t.every !== undefined ? { every: t.every } : { cron: t.cron, ...(t.timezone ? { timezone: t.timezone } : {}) };
+            triggers.push({ name: n, ...timing, configurable: t.configurable || false, choice: installation.workflows?.[w.id]?.schedule });
+        }
         if (t.type === 'userAction') userActions.push({ event: n, label: t.label, from: t.from || null });
         if (t.type === 'syncRecord') route('$sync', `${t.sync}:${(t.on || []).join('|')}`, n);
     }
@@ -61,7 +64,7 @@ function compile(def, installation = {}) {
         routes.push({ method: 'GET', path: `/ui/${u.id}`, event: n });
     }
 
-    return { events, webhooks, schedules, userActions, routes };
+    return { events, webhooks, triggers, userActions, routes };
 }
 
 /** Which compiled events a delivered webhook goes to. Topic patterns may end in ".*". */

package/integrations/data-defined/config-form.js

@@ -38,6 +38,20 @@ async function settingsSchema(settings, pathPrefix, values, options, integration
     return { schema: { type: 'object', properties, ...(required.length ? { required } : {}) }, ui };
 }
 
+/**
+ * The timing field of a schedule the definition marks configurable: an interval when its default is an interval,
+ * a cron (with time zone) when its default is a cron. The floor is said in the help text and enforced on save.
+ */
+function scheduleField(recurrence, configurable) {
+    if (!configurable || !recurrence) return null;
+    const min = configurable.min ? ` No more often than every ${configurable.min}.` : '';
+    if (recurrence.every !== undefined) {
+        return { schema: { type: 'object', title: 'Schedule', properties: { every: { type: 'string', title: 'Runs every', pattern: '^\\d+\\s*(m|h|d)$', default: recurrence.every } } }, ui: { every: { 'ui:help': `Minutes, hours or days: 15m, 2h, 1d.${min}` } } };
+    }
+    return { schema: { type: 'object', title: 'Schedule', properties: { cron: { type: 'string', title: 'Cron', default: recurrence.cron }, timezone: { type: 'string', title: 'Time zone', default: recurrence.timezone || 'UTC' } } }, ui: { cron: { 'ui:help': `minute hour day-of-month month day-of-week.${min}` } } };
+}
+const configurableOf = (c) => (c ? (c === true ? {} : c) : false);
+
 const toggle = (title, description, enabledByDefault) => ({ type: 'boolean', title, ...(description ? { description } : {}), default: enabledByDefault });
 const isOn = (item, chosen) => (typeof chosen?.enabled === 'boolean' ? chosen.enabled : (item.default || 'on') === 'on');
 
@@ -63,6 +77,12 @@ async function buildConfigForm(def, config = {}, options = async () => []) {
         for (const s of def.syncs) {
             jsonSchema.properties.syncs.properties[s.id] = { type: 'object', title: s.label, properties: { enabled: toggle('On', s.description, (s.default || 'on') === 'on') } };
             data.syncs[s.id] = { enabled: isOn(s, config.syncs?.[s.id]) };
+            const field = s.ongoing?.mode === 'poll' && scheduleField({ every: s.ongoing.every || '15m' }, configurableOf(s.ongoing.configurable));
+            if (field) {
+                jsonSchema.properties.syncs.properties[s.id].properties.schedule = field.schema;
+                ((uiSchema.syncs ||= {})[s.id] ||= {}).schedule = field.ui;
+                if (config.syncs?.[s.id]?.schedule) data.syncs[s.id].schedule = { ...config.syncs[s.id].schedule };
+            }
         }
     }
 
@@ -81,6 +101,13 @@ async function buildConfigForm(def, config = {}, options = async () => []) {
                 // Settings only matter while the workflow is on: required only then.
                 node.dependencies = { enabled: { oneOf: [{ properties: { enabled: { const: false } } }, { properties: { enabled: { const: true } }, required: ['settings'] }] } };
             }
+            const t = w.trigger || {};
+            const field = t.type === 'schedule' && scheduleField(t.every !== undefined ? { every: t.every } : { cron: t.cron, timezone: t.timezone }, configurableOf(t.configurable));
+            if (field) {
+                node.properties.schedule = field.schema;
+                (uiSchema.workflows[w.id] ||= {}).schedule = field.ui;
+                if (chosen.schedule) data.workflows[w.id].schedule = { ...chosen.schedule };
+            }
             jsonSchema.properties.workflows.properties[w.id] = node;
         }
     }

package/integrations/data-defined/data-defined-integration.js

@@ -21,6 +21,22 @@ const { makePorts, runWorkflow, runQuery, renderSurface, runLifecycle, resolveOp
 const { eventsIn, handshakeFor, modulesFor } = require('./webhooks');
 const { buildConfigForm, missingRequired } = require('./config-form');
 
+/** The tick every data-defined trigger runs on: a chosen interval is rounded up to whole multiples of it. */
+const INSTANCE_TICK = '5m';
+
+/** A compiled definition's triggers as IntegrationBase trigger declarations: each runs its compiled event. */
+function triggersOf(def, config) {
+    return compile(def, config).triggers.map((t) => ({
+        ...t,
+        tick: INSTANCE_TICK,
+        handler(payload) {
+            const event = this.events?.[t.name];
+            if (!event) throw new Error(`Trigger "${t.name}" has no compiled event in this installation`);
+            return event.handler({ data: { integrationId: this.id, ...payload } });
+        },
+    }));
+}
+
 /**
  * Shape A — one class per definition id (defineIntegrationClass): the class name and modules come from the
  * definition. Publishing a new VERSION deploys nothing; a new definition ID is a new class (a deploy, and its own
@@ -80,9 +96,35 @@ function makeClass({ name, defaultId, definitions, manifests, runCode, Integrati
     let runStore = runs;
     const runRepository = () => (runStore === undefined ? (runStore = require('./repositories/workflow-run-repository').createWorkflowRunRepository()) : runStore);
     const publicBase = () => `${process.env.FRIGG_PUBLIC_URL || ''}/api/${id}-integration/webhooks`;
+    const pinnedDefinitions = new Map();   // `${id}@${version}` -> definition, for the trigger tick
 
     class DataDefinedIntegration extends Base {
-        static Definition = { name, version, modules, webhooks: { enabled: true }, display }; // version is display only; installations pin their own
+        // version is display only; installations pin their own. instanceTriggers: schedule-triggered workflows and
+        // polling syncs are this class's recurring triggers, resolved per installation (triggersFor) on one 5m tick.
+        static Definition = { name, version, modules, webhooks: { enabled: true }, display, instanceTriggers: { tick: INSTANCE_TICK } };
+
+        /**
+         * The recurring triggers of one installation (ADR-055): its pinned definition compiled with its config, so a
+         * switched-off workflow has none and a configurable one carries the installation's choice. Each runs its
+         * compiled event. Read by the shared tick from the record alone (no modules, no credentials).
+         */
+        static async triggersFor({ config = {} } = {}) {
+            const pin = config.definition || (defaultId ? { id: defaultId } : null);
+            if (!pin?.id) return [];
+            let def;
+            if (pin.version) {
+                // Published versions are immutable, so a tick over many installations reads each one once.
+                const key = `${pin.id}@${pin.version}`;
+                if (!pinnedDefinitions.has(key)) {
+                    if (pinnedDefinitions.size >= 100) pinnedDefinitions.clear();
+                    pinnedDefinitions.set(key, await definitions.get(pin.id, pin.version, { checksum: pin.checksum }));
+                }
+                def = pinnedDefinitions.get(key);
+            } else {
+                def = await definitions.latest(pin.id);
+            }
+            return def ? triggersOf(def, config) : [];
+        }
 
         /** How the routers find data-defined classes and the store and manifests they run on. */
         static DataDefined = { definitions, manifests, shared: !defaultId, runs: () => runRepository() };
@@ -150,7 +192,10 @@ function makeClass({ name, defaultId, definitions, manifests, runCode, Integrati
                 ? await definitions.get(this.def.id, msg.definitionVersion) || this.def
                 : this.def;
             const installation = this.installation();
-            if (ref.kind === 'workflow') return this.recordRun(await runWorkflow({ def, installation, workflowId: ref.id, event: msg.body ?? msg, eventId: msg.eventId, record: msg.record, ports: this.ports, manifests }));
+            // A trigger run may be delivered twice (a redelivery, two ticks in one slot); the trigger and the time it
+            // was scheduled for make its dedupe id.
+            const eventId = msg.eventId || (msg.trigger && msg.scheduledFor ? `tick:${msg.trigger}:${msg.scheduledFor}` : undefined);
+            if (ref.kind === 'workflow') return this.recordRun(await runWorkflow({ def, installation, workflowId: ref.id, event: msg.body ?? msg, eventId, record: msg.record, ports: this.ports, manifests }));
             if (ref.kind === 'query') return runQuery({ def, installation, queryId: ref.id, record: msg.record, ports: this.ports });
             if (ref.kind === 'ui') return renderSurface({ def, installation, surfaceId: ref.id, record: payload.req?.body?.record || msg.record, ports: this.ports });
             if (ref.kind === 'sync') return this.runSync(ref, msg);
@@ -252,6 +297,11 @@ function makeClass({ name, defaultId, definitions, manifests, runCode, Integrati
             return super.onDelete(params);
         }
 
+        /** This installation's triggers, from the definition it already loaded and its current config. */
+        async triggerDeclarations() {
+            return this.def ? triggersOf(this.def, this.config || {}) : this.constructor.triggersFor({ config: this.config || {} });
+        }
+
         /** The configure form (GET /api/integrations/:id/config/options), generated from the definition. */
         async getConfigOptions() {
             return buildConfigForm(this.def, this.config || {}, (path, values, integrationSettings) => this.optionsFor(path, values, integrationSettings));
@@ -316,11 +366,12 @@ function makeClass({ name, defaultId, definitions, manifests, runCode, Integrati
                 await runLifecycle({ def: this.def, installation: this.installation(), hook: 'onUninstall', ports: this.ports });
                 const next = await definitions.get(plan.config.definition.id, plan.config.definition.version);
                 const out = await runLifecycle({ def: next, installation: { ...this.installation(), ...config }, hook: 'onInstall', ports: this.portsFor(next) });
-                config = { ...config, runtime: { installed: Object.fromEntries((next.lifecycle?.onInstall || []).filter((st) => st.id).map((st) => [st.id, out.steps?.[st.id] ?? null])) } };
+                config = { ...config, runtime: { ...(this.config?.runtime || {}), installed: Object.fromEntries((next.lifecycle?.onInstall || []).filter((st) => st.id).map((st) => [st.id, out.steps?.[st.id] ?? null])) } };
             }
             await this.patchConfig(config);
             this.config = { ...this.config, ...config };
             await this.loadDefinition();
+            // Triggers need nothing here: the next tick reads the new pin and config.
             return { ...plan, config, applied: true };
         }
 

package/integrations/data-defined/schema/installation.v0.1.schema.json

@@ -40,6 +40,9 @@
           "mapping": {
             "type": "array",
             "description": "Full replacement mapping when the customer overrides the default."
+          },
+          "schedule": {
+            "$ref": "#/$defs/scheduleChoice"
           }
         }
       }
@@ -54,6 +57,9 @@
           },
           "settings": {
             "type": "object"
+          },
+          "schedule": {
+            "$ref": "#/$defs/scheduleChoice"
           }
         }
       }
@@ -79,5 +85,46 @@
         }
       }
     }
+  },
+  "$defs": {
+    "scheduleChoice": {
+      "description": "The installation's timing for a schedule trigger or polling sync the definition marks configurable: every, or cron with an optional time zone. Honoured only within the definition's minimum; otherwise the definition's timing runs. The integration's shared trigger tick reads it (ADR-055); nothing is scheduled per installation.",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "every": {
+          "type": "string",
+          "pattern": "^\\d+\\s*(m|h|d)$"
+        },
+        "cron": {
+          "type": "string"
+        },
+        "timezone": {
+          "type": "string"
+        }
+      },
+      "oneOf": [
+        {
+          "required": [
+            "every"
+          ],
+          "not": {
+            "required": [
+              "cron"
+            ]
+          }
+        },
+        {
+          "required": [
+            "cron"
+          ],
+          "not": {
+            "required": [
+              "every"
+            ]
+          }
+        }
+      ]
+    }
   }
 }

package/integrations/data-defined/schema/integration-definition.v0.1.schema.json

@@ -217,7 +217,12 @@
                 ]
               },
               "every": {
-                "type": "string"
+                "type": "string",
+                "pattern": "^\\d+\\s*(m|h|d)$",
+                "description": "Poll interval (default 15m)."
+              },
+              "configurable": {
+                "$ref": "#/$defs/scheduleConfigurable"
               }
             }
           },
@@ -662,8 +667,7 @@
         {
           "type": "object",
           "required": [
-            "type",
-            "cron"
+            "type"
           ],
           "additionalProperties": false,
           "properties": {
@@ -671,12 +675,44 @@
               "const": "schedule"
             },
             "cron": {
-              "type": "string"
+              "type": "string",
+              "description": "Five-field cron (minute hour day-of-month month day-of-week). Restrict day of month or day of week, not both."
             },
             "timezone": {
-              "type": "string"
+              "type": "string",
+              "description": "IANA time zone for cron (default UTC)."
+            },
+            "every": {
+              "type": "string",
+              "pattern": "^\\d+\\s*(m|h|d)$",
+              "description": "Fixed interval (15m, 2h, 1d). Give cron or every."
+            },
+            "configurable": {
+              "$ref": "#/$defs/scheduleConfigurable"
             }
-          }
+          },
+          "oneOf": [
+            {
+              "required": [
+                "cron"
+              ],
+              "not": {
+                "required": [
+                  "every"
+                ]
+              }
+            },
+            {
+              "required": [
+                "every"
+              ],
+              "not": {
+                "required": [
+                  "cron"
+                ]
+              }
+            }
+          ]
         },
         {
           "type": "object",
@@ -843,6 +879,24 @@
           }
         }
       ]
+    },
+    "scheduleConfigurable": {
+      "description": "Lets each installation choose its own timing. true: any valid timing. { min }: never more often than this (15m, 2h, 1d).",
+      "oneOf": [
+        {
+          "type": "boolean"
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "min": {
+              "type": "string",
+              "pattern": "^\\d+\\s*(m|h|d)$"
+            }
+          }
+        }
+      ]
     }
   }
 }