@friggframework/core 2.0.0--canary.690.08cd07e.0 → 2.0.0--canary.694.f66a64a.0

package/integrations/data-defined/expressions.js

@@ -0,0 +1,225 @@
+/**
+ * Expressions for data-defined integrations (v0.1).
+ *
+ * Three forms, and no others (nothing is ever passed to eval):
+ *   1. Reference   "$.event.contact.id"     A string that is exactly a path. Resolves to the value, keeping its type.
+ *   2. Template    "Call with {{event.from}}" A string with {{path | filter}} parts. Resolves to a string, except
+ *                  that a string which is exactly one tag ("{{record.amount | to_cents}}") keeps the value's type, so
+ *                  a filter can produce a number or a list for an API argument.
+ *   3. Condition   "$.steps.contact == null && $.event.duration > 30"  Used by `when` and trigger filters.
+ *
+ * Paths are read from a context object: { event, steps, settings, install, vars, item, record, now }.
+ * A missing segment resolves to undefined; it never throws.
+ */
+
+const PATH_RE = /^\$\.[A-Za-z_][\w-]*(\.[\w-]+|\[\d+\])*$/;
+
+function getPath(ctx, path) {
+    const clean = path.replace(/^\$\./, '');
+    let cur = ctx;
+    for (const seg of clean.split(/\.|(?=\[)/)) {
+        if (cur == null) return undefined;
+        const m = /^\[(\d+)\]$/.exec(seg);
+        cur = m ? cur[Number(m[1])] : cur[seg];
+    }
+    return cur;
+}
+
+const num = (v) => (v == null || v === '' ? null : Number(v));
+const arith = (f) => (v, arg) => { const a = num(v), b = num(arg); return a == null || b == null || Number.isNaN(a) || Number.isNaN(b) ? null : f(a, b); };
+
+/**
+ * Template filters. Each is a named, total function of (value, argument): no filter loops, calls out or throws on
+ * bad input (a non-number gives null, which renders as ''). Arithmetic is here, as named filters, instead of an
+ * expression language: {{item.amount | to_cents}}, {{record.created | from_unix}}.
+ */
+// ISO 4217 minor-unit exponents that are not 2 (Stripe's zero-decimal and three-decimal lists).
+const MINOR_EXPONENT = { BIF: 0, CLP: 0, DJF: 0, GNF: 0, JPY: 0, KMF: 0, KRW: 0, MGA: 0, PYG: 0, RWF: 0, UGX: 0, VND: 0, VUV: 0, XAF: 0, XOF: 0, XPF: 0, BHD: 3, JOD: 3, KWD: 3, OMR: 3, TND: 3 };
+const exponentOf = (currency) => MINOR_EXPONENT[String(currency || '').toUpperCase()] ?? 2;
+/** a * 10^e, rounded half-up in decimal (19.995 -> 1999.5 -> 2000; 19.995 * 100 is 1999.4999... in binary). */
+const shiftRound = (a, e) => Math.round(Number(`${a}e${e}`));
+
+const FILTERS = {
+    upper: (v) => String(v ?? '').toUpperCase(),
+    lower: (v) => String(v ?? '').toLowerCase(),
+    minutes: (v) => (v == null ? '' : String(Math.round(Number(v) / 60000))),
+    seconds: (v) => (v == null ? '' : String(Math.round(Number(v) / 1000))),
+    date: (v) => (v ? new Date(v).toISOString().slice(0, 10) : ''),
+    json: (v) => JSON.stringify(v),
+    default: (v, arg) => (v == null || v === '' ? arg : v),
+    truncate: (v, arg) => { const s = String(v ?? ''); const n = Number(arg) || 80; return s.length > n ? s.slice(0, n - 1) + '…' : s; },
+    // lists
+    join: (v, arg) => (Array.isArray(v) ? v.filter((x) => x != null && x !== '').join(arg ?? ', ') : v),
+    size: (v) => (Array.isArray(v) || typeof v === 'string' ? v.length : v && typeof v === 'object' ? Object.keys(v).length : 0),
+    first: (v) => (Array.isArray(v) ? v[0] : v),
+    // arithmetic
+    plus: arith((a, b) => a + b),
+    minus: arith((a, b) => a - b),
+    times: arith((a, b) => a * b),
+    divided_by: arith((a, b) => (b === 0 ? null : a / b)),
+    // Rounded in decimal-exponent form, so 1.005 | round: 2 is 1.01 (1.005 * 100 is 100.49999... in binary floating point).
+    round: (v, arg) => { const a = num(v); if (a == null || Number.isNaN(a)) return null; const d = Math.max(0, Math.min(10, Number(arg) || 0)); return Number(`${shiftRound(a, d)}e-${d}`); },
+    abs: (v) => { const a = num(v); return a == null || Number.isNaN(a) ? null : Math.abs(a); },
+    number: (v) => { const a = num(v); return a == null || Number.isNaN(a) ? null : a; },
+    // money in minor units, rounded so 19.99 -> 1999 (19.99 * 100 is 1998.9999999999998)
+    to_cents: (v) => { const a = num(v); return a == null || Number.isNaN(a) ? null : shiftRound(a, 2); },
+    from_cents: (v) => { const a = num(v); return a == null || Number.isNaN(a) ? null : Math.round(a) / 100; },
+    // the same for any currency: {{record.amount | from_minor_units: record.currency}} (JPY has no minor unit, KWD three)
+    to_minor_units: (v, cur) => { const a = num(v); if (a == null || Number.isNaN(a)) return null; return shiftRound(a, exponentOf(cur)); },
+    from_minor_units: (v, cur) => { const a = num(v); if (a == null || Number.isNaN(a)) return null; const e = exponentOf(cur); return Math.round(a) / 10 ** e; },
+    // unix seconds <-> ISO 8601
+    from_unix: (v) => { const a = num(v); return a == null || Number.isNaN(a) ? null : new Date(a * 1000).toISOString(); },
+    to_unix: (v) => { const t = v ? Date.parse(v) : NaN; return Number.isNaN(t) ? null : Math.floor(t / 1000); },
+};
+
+/** A filter argument is a quoted literal ('x'), a number, or a path read from the context (steps.full.owner). */
+function filterArg(raw, ctx) {
+    if (raw == null) return undefined;
+    const a = raw.trim();
+    if (/^'.*'$/.test(a)) return a.slice(1, -1).replace(/\\n/g, '\n').replace(/\\t/g, '\t');
+    if (/^-?\d+(\.\d+)?$/.test(a)) return a;
+    return getPath(ctx, '$.' + a.replace(/^\$\./, ''));
+}
+
+const TAG_RE = /\{\{\s*([^}]+?)\s*\}\}/g;
+const SINGLE_TAG_RE = /^\{\{\s*([^}]+?)\s*\}\}$/;
+
+/** Split one tag's expression into its path and filters: "item.amount | times: 100" -> { path, filters: [{ name, arg }] }. */
+function parseTag(expr) {
+    const [p, ...filters] = expr.split('|').map((x) => x.trim());
+    return { path: p.replace(/^\$\./, ''), filters: filters.map((f) => { const m = /^(\w+)(?::\s*(.*))?$/.exec(f); return m ? { name: m[1], arg: m[2] } : { name: f, arg: undefined, bad: true }; }) };
+}
+
+function evalTag(expr, ctx) {
+    const { path, filters } = parseTag(expr);
+    let v = getPath(ctx, '$.' + path);
+    for (const f of filters) {
+        const fn = !f.bad && FILTERS[f.name];
+        if (!fn) throw new Error(`Unknown template filter "${f.name}"`);
+        v = fn(v, filterArg(f.arg, ctx));
+    }
+    return v;
+}
+
+function renderTemplate(str, ctx) {
+    const single = SINGLE_TAG_RE.exec(str);
+    if (single) return evalTag(single[1], ctx) ?? '';
+    return str.replace(TAG_RE, (_, expr) => {
+        const v = evalTag(expr, ctx);
+        return v == null ? '' : typeof v === 'object' ? JSON.stringify(v) : String(v);
+    });
+}
+
+/** Every tag in a value (deep), for validation: [{ path, filters }]. */
+function templateTags(value, acc = []) {
+    if (typeof value === 'string') for (const m of value.matchAll(TAG_RE)) acc.push(parseTag(m[1]));
+    else if (Array.isArray(value)) value.forEach((v) => templateTags(v, acc));
+    else if (value && typeof value === 'object') Object.values(value).forEach((v) => templateTags(v, acc));
+    return acc;
+}
+
+/** Resolve every reference and template inside a value (deep). Non-string scalars pass through. */
+function resolve(value, ctx) {
+    if (typeof value === 'string') {
+        if (PATH_RE.test(value)) return getPath(ctx, value);
+        if (value.includes('{{')) return renderTemplate(value, ctx);
+        return value;
+    }
+    if (Array.isArray(value)) return value.map((v) => resolve(v, ctx));
+    if (value && typeof value === 'object') {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) out[k] = resolve(v, ctx);
+        return out;
+    }
+    return value;
+}
+
+// ---------- conditions ----------
+const TOKEN_RE = /\s*(\$\.[A-Za-z_][\w.\-[\]]*|'(?:[^'\\]|\\.)*'|-?\d+(?:\.\d+)?|==|!=|>=|<=|&&|\|\||[()!<>]|\bin\b|\bcontains\b|\bexists\b|\btrue\b|\bfalse\b|\bnull\b)/y;
+
+function tokenize(src) {
+    const out = [];
+    TOKEN_RE.lastIndex = 0;
+    let pos = 0;
+    while (pos < src.length) {
+        if (/^\s*$/.test(src.slice(pos))) break;
+        TOKEN_RE.lastIndex = pos;
+        const m = TOKEN_RE.exec(src);
+        if (!m) throw new Error(`Cannot parse condition near "${src.slice(pos, pos + 20)}"`);
+        out.push(m[1]);
+        pos = TOKEN_RE.lastIndex;
+    }
+    return out;
+}
+
+/** Parse a condition into a small AST. Grammar: or := and ('||' and)* ; and := not ('&&' not)* ; not := '!' not | cmp ; cmp := atom (op atom | 'exists')? */
+function parseCondition(src) {
+    const t = tokenize(src);
+    let i = 0;
+    const peek = () => t[i];
+    const next = () => t[i++];
+    function atom() {
+        const tok = next();
+        if (i > t.length) throw new Error(`Condition ends early: "${src}"`);
+        if (tok === '(') { const e = or(); if (next() !== ')') throw new Error(`Missing ) in "${src}"`); return e; }
+        if (tok.startsWith('$.')) return { ref: tok };
+        if (tok.startsWith("'")) return { lit: tok.slice(1, -1).replace(/\\'/g, "'") };
+        if (tok === 'true' || tok === 'false') return { lit: tok === 'true' };
+        if (tok === 'null') return { lit: null };
+        if (/^-?\d/.test(tok)) return { lit: Number(tok) };
+        throw new Error(`Unexpected "${tok}" in "${src}"`);
+    }
+    function cmp() {
+        const left = atom();
+        const op = peek();
+        if (op === 'exists') { next(); return { op: 'exists', left }; }
+        if (['==', '!=', '>', '>=', '<', '<=', 'in', 'contains'].includes(op)) { next(); return { op, left, right: atom() }; }
+        return { op: 'truthy', left };
+    }
+    function not() { if (peek() === '!') { next(); return { op: '!', left: not() }; } return cmp(); }
+    function and() { let l = not(); while (peek() === '&&') { next(); l = { op: '&&', left: l, right: not() }; } return l; }
+    function or() { let l = and(); while (peek() === '||') { next(); l = { op: '||', left: l, right: and() }; } return l; }
+    const ast = or();
+    if (i < t.length) throw new Error(`Unexpected "${t[i]}" in "${src}"`);
+    return ast;
+}
+
+function evalAst(n, ctx) {
+    if ('ref' in n) return getPath(ctx, n.ref);
+    if ('lit' in n) return n.lit;
+    const L = () => evalAst(n.left, ctx), R = () => evalAst(n.right, ctx);
+    switch (n.op) {
+        case 'truthy': return Boolean(L());
+        case 'exists': return L() != null;
+        case '!': return !evalAst(n.left, ctx);
+        case '&&': return Boolean(L()) && Boolean(R());
+        case '||': return Boolean(L()) || Boolean(R());
+        case '==': return L() == R(); // eslint-disable-line eqeqeq -- null == undefined is intended
+        case '!=': return L() != R(); // eslint-disable-line eqeqeq
+        case '>': return L() > R();
+        case '>=': return L() >= R();
+        case '<': return L() < R();
+        case '<=': return L() <= R();
+        case 'in': { const r = R(); return Array.isArray(r) ? r.includes(L()) : typeof r === 'string' && r.includes(String(L())); }
+        case 'contains': { const l = L(); return Array.isArray(l) ? l.includes(R()) : String(l ?? '').includes(String(R())); }
+        default: throw new Error(`Unknown operator ${n.op}`);
+    }
+}
+
+function evaluate(condition, ctx) {
+    if (condition == null) return true;
+    return Boolean(evalAst(parseCondition(condition), ctx));
+}
+
+/** Every $.root referenced by an expression-bearing value (for validation). */
+function referencedPaths(value, acc = []) {
+    if (typeof value === 'string') {
+        if (PATH_RE.test(value)) acc.push(value);
+        for (const m of value.matchAll(/\{\{\s*([^}|]+?)\s*(\|[^}]*)?\}\}/g)) acc.push('$.' + m[1].replace(/^\$\./, ''));
+        for (const m of value.matchAll(/\$\.[A-Za-z_][\w.\-[\]]*/g)) if (!acc.includes(m[0])) acc.push(m[0]);
+    } else if (Array.isArray(value)) value.forEach((v) => referencedPaths(v, acc));
+    else if (value && typeof value === 'object') Object.values(value).forEach((v) => referencedPaths(v, acc));
+    return acc;
+}
+
+module.exports = { getPath, resolve, renderTemplate, evaluate, parseCondition, referencedPaths, templateTags, FILTERS };

package/integrations/data-defined/index.js

@@ -0,0 +1,39 @@
+/**
+ * Data-defined integrations, v0.1 (ADR-063). An integration as a document: modules, syncs, workflows, queries,
+ * UI surfaces and templates, run by one runtime class on the existing Frigg infrastructure.
+ */
+const fs = require('fs');
+const path = require('path');
+const { validate } = require('./validate');
+const { compile, routeWebhook, eventName } = require('./compile');
+const { execute } = require('./interpreter');
+const { makePorts, runWorkflow, runQuery, renderSurface, resolveView, runLifecycle, resolveOptions } = require('./runtime');
+const { diff, checkBump, planUpgrade } = require('./versioning');
+const { defineIntegrationClass, defineSharedIntegrationClass, memoryDefinitions } = require('./data-defined-integration');
+const { BUILTINS } = require('./steps');
+const { TRANSFORMS, applyMapping } = require('./transforms');
+const { FILTERS } = require('./expressions');
+const { validateManifest } = require('./manifests');
+const { checkDefinition, checkManifest, checkInstallation } = require('./schema-check');
+const useCases = require('./use-cases/definition-use-cases');
+
+/** Load every capabilities/*.capabilities.json (bundled mocks; real modules ship their own). */
+function loadManifests(dir = path.join(__dirname, 'capabilities')) {
+    const out = {};
+    for (const f of fs.readdirSync(dir)) if (f.endsWith('.capabilities.json')) { const m = JSON.parse(fs.readFileSync(path.join(dir, f), 'utf8')); out[m.module] = m; }
+    return out;
+}
+function loadExamples(dir = path.join(__dirname, 'examples')) {
+    return fs.readdirSync(dir).filter((f) => f.endsWith('.definition.json')).map((f) => JSON.parse(fs.readFileSync(path.join(dir, f), 'utf8')));
+}
+
+module.exports = {
+    SCHEMA_VERSION: '0.1',
+    validate, validateManifest, checkDefinition, checkManifest, checkInstallation, compile, routeWebhook, eventName, execute,
+    makePorts, runWorkflow, runQuery, renderSurface, resolveView, runLifecycle,
+    diff, checkBump, planUpgrade,
+    defineIntegrationClass, defineSharedIntegrationClass, memoryDefinitions,
+    BUILTINS, TRANSFORMS, FILTERS, applyMapping, resolveOptions,
+    loadManifests, loadExamples,
+    ...useCases,
+};

package/integrations/data-defined/interpreter.js

@@ -0,0 +1,89 @@
+/**
+ * Runs a list of steps against a context. Pure apart from the ports it is given:
+ *   ports.call(moduleKey, capability, args)   a module capability (the runtime maps it to Api.<method>)
+ *   ports.links.find / ports.links.upsert       the link + identity store (IntegrationMapping rows)
+ *   ports.runCode(ref, args)                    registered code steps (optional)
+ *
+ * Every step leaves a trace entry: { id, use, status, ms, error? }. A step's result is stored at $.steps.<id>.
+ * onError per step: 'fail' (default: throw, so the queue retries the whole run), 'continue' (result null), 'stop'.
+ */
+const { resolve, evaluate } = require('./expressions');
+const { BUILTINS, FOREACH_HARD_CAP, isBuiltin, splitCapability } = require('./steps');
+
+class StopRun extends Error { constructor(reason) { super(reason); this.name = 'StopRun'; this.reason = reason; } }
+
+async function runSteps(steps, env, path = 'steps') {
+    const { ctx, trace } = env;
+    for (let i = 0; i < (steps || []).length; i++) {
+        const step = steps[i];
+        const id = step.id || `${step.use}#${i}`;
+        const at = `${path}[${i}]`;
+        if (step.when && !evaluate(step.when, ctx)) { trace.push({ id, use: step.use, at, status: 'skipped' }); continue; }
+        const t0 = Date.now();
+        try {
+            let out;
+            if (step.use === 'foreach') {
+                const all = resolve(step.with?.over, ctx) ?? [];
+                if (!Array.isArray(all)) throw new Error('foreach: `over` is not an array');
+                const max = Math.min(step.with?.max || 100, FOREACH_HARD_CAP);
+                const saved = { item: ctx.item, index: ctx.index };
+                // `where` is checked per item, before the cap, so max bounds the work actually done.
+                const items = [];
+                for (const [n, item] of all.entries()) {
+                    ctx.item = item; ctx.index = n;
+                    if (!step.with?.where || evaluate(step.with.where, ctx)) items.push(item);
+                }
+                Object.assign(ctx, saved);
+                const collect = step.with && 'collect' in step.with;
+                out = [];
+                for (const [n, item] of items.slice(0, max).entries()) {
+                    ctx.item = item; ctx.index = n;
+                    await runSteps(step.do || [], env, `${at}.do#${n}`);
+                    out.push(collect
+                        ? resolve(step.with.collect, ctx)
+                        : Object.fromEntries((step.do || []).filter((s) => s.id).map((s) => [s.id, ctx.steps[s.id]])));
+                    Object.assign(ctx, saved);
+                }
+                if (items.length > max) trace.push({ id, use: 'foreach', at, status: 'truncated', note: `${items.length - max} items over max ${max}` });
+            } else if (step.use === 'branch') {
+                const hit = (step.cases || []).find((c) => evaluate(c.when, ctx));
+                await runSteps(hit ? hit.do : step.else || [], env, `${at}.${hit ? 'case' : 'else'}`);
+                out = { matched: hit ? hit.when : null };
+            } else if (isBuiltin(step.use)) {
+                out = await BUILTINS[step.use].run(resolve(step.with || {}, ctx), env);
+                if (out && out.stop) { ctx.steps[id] = out; trace.push({ id, use: step.use, at, status: 'stopped', ms: Date.now() - t0, reason: out.reason }); throw new StopRun(out.reason); }
+            } else {
+                const cap = splitCapability(step.use);
+                if (!cap) throw new Error(`Unknown step "${step.use}"`);
+                out = await env.ports.call(cap.module, cap.capability, resolve(step.with || {}, ctx));
+            }
+            ctx.steps[id] = out === undefined ? null : out;
+            trace.push({ id, use: step.use, at, status: 'ok', ms: Date.now() - t0 });
+        } catch (e) {
+            if (e instanceof StopRun) throw e;
+            const policy = step.onError || 'fail';
+            trace.push({ id, use: step.use, at, status: 'error', ms: Date.now() - t0, error: String(e && e.message || e), policy });
+            if (policy === 'continue') { ctx.steps[id] = null; continue; }
+            if (policy === 'stop') throw new StopRun(`step ${id} failed`);
+            throw e;
+        }
+    }
+}
+
+/**
+ * Run steps and report the outcome instead of throwing for a normal stop.
+ * @returns {Promise<{status:'completed'|'stopped', reason?:string, steps:object, trace:Array}>}
+ */
+async function execute(steps, { def, installation, ctx, ports }) {
+    const env = { def, installation, ports, trace: [], ctx: { steps: {}, vars: {}, ...ctx } };
+    try {
+        await runSteps(steps, env);
+        return { status: 'completed', steps: env.ctx.steps, trace: env.trace };
+    } catch (e) {
+        if (e instanceof StopRun) return { status: 'stopped', reason: e.reason, steps: env.ctx.steps, trace: env.trace };
+        e.trace = env.trace;
+        throw e;
+    }
+}
+
+module.exports = { execute, runSteps, StopRun };

package/integrations/data-defined/manifests.js

@@ -0,0 +1,125 @@
+/**
+ * Validate a capability manifest (v0.1): the module author's promise of what a definition may call. Definitions are
+ * validated against manifests, so a broken manifest would let a broken definition through; this checks the manifest
+ * itself.
+ *
+ * @param {object} m  capabilities/<module>.capabilities.json
+ * @returns {{ valid: boolean, errors: Array<{path:string,message:string}> }}
+ */
+const { templateTags, parseCondition, FILTERS } = require('./expressions');
+const { eventsIn } = require('./webhooks');
+
+const PATH_RE = /^\$\.[A-Za-z_][\w-]*(\.[\w-]+|\[\d+\])*$/;
+const KINDS = new Set(['read', 'search', 'write', 'delete', 'subscribe']); // schema/capability-manifest.v0.1.schema.json
+const READS = new Set(['read', 'search']);
+
+function validateManifest(m) {
+    const errors = [];
+    const err = (path, message) => errors.push({ path, message });
+    if (!m || typeof m !== 'object') return { valid: false, errors: [{ path: '', message: 'Manifest must be an object' }] };
+    if (!/^[a-z][a-z0-9-]*$/.test(m.module || '')) err('module', 'Lowercase module name');
+    if (!m.label) err('label', 'Required');
+
+    const objects = m.objects || {};
+    for (const [o, def] of Object.entries(objects)) {
+        const names = new Set();
+        (def.fields || []).forEach((f, i) => {
+            if (!f?.name) err(`objects.${o}.fields[${i}]`, 'Field needs a name');
+            else if (names.has(f.name)) err(`objects.${o}.fields[${i}]`, `Duplicate field "${f.name}"`);
+            else names.add(f.name);
+            // An enum lists its values, or names one of this module's option lists when they differ per account
+            // (HubSpot deal stages are per portal).
+            if (f?.type === 'enum' && !Array.isArray(f.values) && !(typeof f.values === 'string' && m.options?.[f.values])) err(`objects.${o}.fields[${i}]`, 'An enum lists its values, or names an option list of this module');
+        });
+    }
+
+    const caps = m.capabilities || {};
+    for (const [name, c] of Object.entries(caps)) {
+        const p = `capabilities.${name}`;
+        if (!/^[A-Za-z][\w]*\.[A-Za-z][\w]*$/.test(name)) err(p, 'Capability names are "<object>.<verb>"');
+        if (!KINDS.has(c?.kind)) err(`${p}.kind`, [...KINDS].join(', '));
+        if (!/^[A-Za-z_$][\w$]*$/.test(c?.method || '')) err(`${p}.method`, 'Name of a method on the module\'s Api class');
+        for (const [arg, spec] of Object.entries(c?.input || {})) if (!spec?.type) err(`${p}.input.${arg}`, 'Input needs a type');
+    }
+
+    for (const [topic, e] of Object.entries(m.events || {})) {
+        const p = `events.${topic}`;
+        if (e.object && !objects[e.object]) err(`${p}.object`, `"${e.object}" is not an object of this module`);
+        if (e.payload && (e.delivery || 'webhook') === 'webhook' && m.webhook) {
+            // The example is a real delivery (body, plus headers when the topic is in one): it must route to this event
+            // through the same code a live webhook goes through, and its record path must find something.
+            const found = eventsIn(m, { body: e.payload, headers: e.headers }).find((x) => x.topic === topic);
+            if (!found) err(`${p}.payload`, `The example delivery does not route to "${topic}" (check webhook.topic and this event's match)`);
+            else if (e.record && found.record === undefined) err(`${p}.record`, `"${e.record}" finds nothing in the example event`);
+        } else if (e.record && e.payload) {
+            let cur = e.payload;
+            for (const seg of e.record.split(/\.|(?=\[)/)) { const i = /^\[(\d+)\]$/.exec(seg); cur = cur == null ? undefined : i ? cur[Number(i[1])] : cur[seg]; }
+            if (cur === undefined) err(`${p}.record`, `"${e.record}" is not a path in the example payload`);
+        }
+    }
+
+    // An option list: a read capability, its inputs, and how each item becomes { label, value } (one reference, or
+    // a template). A string that mixes "$.x" into text renders the path literally, so it is refused.
+    const checkItemExpr = (v, p) => {
+        if (typeof v !== 'string') { err(p, 'A reference ($.item.id) or a template ({{item.name}})'); return; }
+        if (!PATH_RE.test(v) && v.includes('$.')) err(p, `"${v}" mixes a $. reference into text, which renders literally; use {{item.x}} for every part`);
+        for (const t of templateTags(v)) {
+            if (t.path.split(/\.|\[/)[0] !== 'item') err(p, `{{${t.path}}} — an option label can only read item`);
+            for (const f of t.filters) if (!FILTERS[f.name]) err(p, `Unknown template filter "${f.name}"`);
+        }
+        if (PATH_RE.test(v) && !v.startsWith('$.item')) err(p, 'An option value can only read $.item');
+    };
+    for (const [name, o] of Object.entries(m.options || {})) {
+        const p = `options.${name}`;
+        const c = caps[o?.capability];
+        if (!c) err(`${p}.capability`, `"${o?.capability}" is not a capability of this module`);
+        else if (!READS.has(c.kind)) err(`${p}.capability`, `An option list reads; ${o.capability} is a ${c.kind} capability`);
+        checkItemExpr(o?.label, `${p}.label`);
+        checkItemExpr(o?.value, `${p}.value`);
+        for (const [input, spec] of Object.entries(o?.inputs || {})) {
+            if (c && !(input in (c.input || {}))) err(`${p}.inputs.${input}`, `${o.capability} takes no argument "${input}"`);
+            if (!spec?.type) err(`${p}.inputs.${input}`, 'Input needs a type');
+        }
+        if (c) for (const [arg, spec] of Object.entries(c.input || {})) if (spec.required && !(arg in (o.inputs || {}))) err(`${p}.inputs`, `${o.capability} requires "${arg}", so the option list must declare it as an input`);
+    }
+
+    // Webhook delivery: how a POST from this provider becomes module events (webhooks.js). Templates may read body,
+    // headers (lower-case), query, item (one event of a batch) and parent (the outer item of a two-level batch).
+    const w = m.webhook;
+    const webhookEvents = Object.entries(m.events || {}).filter(([, e]) => (e.delivery || 'webhook') === 'webhook');
+    if (webhookEvents.length && !w) err('webhook', 'This module has webhook events, so it needs a webhook block saying where the topic is');
+    if (w) {
+        if (!['installation', 'app'].includes(w.scope)) err('webhook.scope', 'installation (a URL per installation) or app (one URL for every account)');
+        const tpl = (v, p, roots = ['body', 'headers', 'query', 'item', 'parent']) => {
+            for (const t of (Array.isArray(v) ? v : [v])) {
+                if (typeof t !== 'string') { err(p, 'A template string, or a list of them'); continue; }
+                for (const tag of templateTags(t)) {
+                    if (!roots.includes(tag.path.split(/\.|\[/)[0])) err(p, `{{${tag.path}}}: a webhook template can read ${roots.join(', ')}`);
+                    for (const f of tag.filters) if (!FILTERS[f.name]) err(p, `Unknown template filter "${f.name}"`);
+                }
+            }
+        };
+        if (!w.topic) err('webhook.topic', 'Required: where the provider puts the event type');
+        else tpl(w.topic, 'webhook.topic');
+        if (w.eventId) tpl(w.eventId, 'webhook.eventId'); else err('webhook.eventId', 'Required: the id that makes a redelivery a no-op');
+        if (w.scope === 'app' && !w.account) err('webhook.account', 'An app-level webhook needs account: which connected account an event is about');
+        if (w.account) tpl(w.account, 'webhook.account');
+        const batch = w.batch == null ? [] : Array.isArray(w.batch) ? w.batch : [w.batch];
+        if (batch.length > 2 || batch.some((b) => typeof b !== 'string')) err('webhook.batch', 'A path to the array of events, or [outer, inner] for two levels');
+        if (w.verify != null && !/^[A-Za-z_$][\w$]*$/.test(w.verify)) err('webhook.verify', 'Name of an Api method that checks the signature');
+        if (w.handshake) {
+            try { parseCondition(w.handshake.when); } catch (e) { err('webhook.handshake.when', e.message); }
+            if (w.handshake.status != null && !Number.isInteger(w.handshake.status)) err('webhook.handshake.status', 'An HTTP status code');
+        }
+        if (w.unwrap != null && typeof w.unwrap !== 'string') err('webhook.unwrap', 'The name of a form field holding the JSON body');
+    }
+    for (const [topic, e] of webhookEvents) {
+        if (e.match != null && typeof e.match !== 'string') err(`events.${topic}.match`, 'The provider\'s topic string for this event');
+        if (e.when) { try { parseCondition(e.when); } catch (x) { err(`events.${topic}.when`, x.message); } }
+    }
+
+    for (const pl of m.ui?.placements || []) if (typeof pl !== 'string') err('ui.placements', 'Placements are strings');
+    return { valid: errors.length === 0, errors };
+}
+
+module.exports = { validateManifest };

package/integrations/data-defined/repositories/definition-version-repository.js

@@ -0,0 +1,67 @@
+/**
+ * IntegrationDefinitionVersion persistence (ADR-063). Pure data access: one Prisma call per method, no business rules.
+ * Which version is "latest", whether a publish is allowed and what a status change means are decided by the use cases
+ * (../use-cases/definition-use-cases.js); this layer only stores and reads rows.
+ *
+ * Rows come back as plain objects with string ids on every database. `document` is the definition verbatim.
+ */
+const { prisma } = require('../../../database/prisma');
+
+const FIELDS = ['definitionId', 'version', 'schemaVersion', 'status', 'checksum', 'document', 'changeLevel', 'previousVersion', 'notes', 'createdBy', 'publishedAt'];
+const pick = (o) => Object.fromEntries(FIELDS.filter((k) => o[k] !== undefined).map((k) => [k, o[k]]));
+
+class DefinitionVersionRepositoryMongo {
+    constructor({ client } = {}) { this.prisma = client || prisma; }
+    toRow(r) { return r ? { ...r, id: String(r.id) } : null; }
+
+    async findVersion(definitionId, version) {
+        return this.toRow(await this.prisma.integrationDefinitionVersion.findUnique({ where: { definitionId_version: { definitionId, version } } }));
+    }
+
+    /** Every version of one definition, any status, unordered (semver order is the caller's business). */
+    async listVersions(definitionId) {
+        return (await this.prisma.integrationDefinitionVersion.findMany({ where: { definitionId } })).map((r) => this.toRow(r));
+    }
+
+    /** Rows in the given statuses across all definitions, without documents (a catalogue listing). */
+    async listByStatus(statuses) {
+        const rows = await this.prisma.integrationDefinitionVersion.findMany({
+            where: { status: { in: statuses } },
+            select: { id: true, definitionId: true, version: true, schemaVersion: true, status: true, checksum: true, changeLevel: true, publishedAt: true, createdAt: true },
+        });
+        return rows.map((r) => this.toRow(r));
+    }
+
+    async createVersion(data) {
+        return this.toRow(await this.prisma.integrationDefinitionVersion.create({ data: pick(data) }));
+    }
+
+    /**
+     * Change a row only if it is still in `fromStatus` (the use case's precondition, checked by the database, so two
+     * concurrent publishes cannot both win). Returns the updated row, or null if it was not in that status.
+     */
+    async updateIfStatus(definitionId, version, fromStatus, data) {
+        const { count } = await this.prisma.integrationDefinitionVersion.updateMany({ where: { definitionId, version, status: fromStatus }, data: pick(data) });
+        return count ? this.findVersion(definitionId, version) : null;
+    }
+
+    async deleteIfStatus(definitionId, version, status) {
+        const { count } = await this.prisma.integrationDefinitionVersion.deleteMany({ where: { definitionId, version, status } });
+        return count > 0;
+    }
+}
+
+class DefinitionVersionRepositoryPostgres extends DefinitionVersionRepositoryMongo {}
+class DefinitionVersionRepositoryDocumentDB extends DefinitionVersionRepositoryMongo {}
+
+function createDefinitionVersionRepository() {
+    const { DB_TYPE } = require('../../../database/config');
+    switch (DB_TYPE) {
+        case 'mongodb': return new DefinitionVersionRepositoryMongo();
+        case 'postgresql': return new DefinitionVersionRepositoryPostgres();
+        case 'documentdb': return new DefinitionVersionRepositoryDocumentDB();
+        default: throw new Error(`Unsupported database type: ${DB_TYPE}. Supported values: 'mongodb', 'documentdb', 'postgresql'`);
+    }
+}
+
+module.exports = { createDefinitionVersionRepository, DefinitionVersionRepositoryMongo, DefinitionVersionRepositoryPostgres, DefinitionVersionRepositoryDocumentDB };

package/integrations/data-defined/repositories/workflow-run-repository.js

@@ -0,0 +1,59 @@
+/**
+ * WorkflowRun persistence (ADR-063). Pure data access. A run row never holds request or response bodies: `trace` is
+ * step ids, statuses, timings and error messages (see runtime.js).
+ */
+const { prisma } = require('../../../database/prisma');
+
+class WorkflowRunRepositoryMongo {
+    constructor({ client } = {}) { this.prisma = client || prisma; }
+    toId(id) { return String(id); }
+    toRow(r) { return r ? { ...r, id: String(r.id), integrationId: String(r.integrationId) } : null; }
+
+    async createRun(run) {
+        return this.toRow(await this.prisma.workflowRun.create({
+            data: {
+                integrationId: this.toId(run.integrationId), definitionId: run.definitionId, definitionVersion: run.definitionVersion,
+                workflowId: run.workflowId, triggerType: run.triggerType, eventId: run.eventId ?? null, status: run.status,
+                reason: run.reason ?? null, error: run.error ?? null, retryable: Boolean(run.retryable), trace: run.trace || [],
+                startedAt: new Date(run.startedAt), endedAt: run.endedAt ? new Date(run.endedAt) : null,
+            },
+        }));
+    }
+
+    /** Newest first. `before` pages by startedAt. */
+    async listRuns(integrationId, { workflowId, status, before, limit = 50 } = {}) {
+        const rows = await this.prisma.workflowRun.findMany({
+            where: { integrationId: this.toId(integrationId), ...(workflowId ? { workflowId } : {}), ...(status ? { status } : {}), ...(before ? { startedAt: { lt: new Date(before) } } : {}) },
+            orderBy: { startedAt: 'desc' },
+            take: Math.min(Math.max(1, limit), 500),
+        });
+        return rows.map((r) => this.toRow(r));
+    }
+
+    /** Delete runs that started before `olderThan`, optionally only in some statuses. Returns the count. */
+    async deleteRunsBefore(olderThan, { statuses } = {}) {
+        const { count } = await this.prisma.workflowRun.deleteMany({ where: { startedAt: { lt: new Date(olderThan) }, ...(statuses ? { status: { in: statuses } } : {}) } });
+        return count;
+    }
+}
+
+class WorkflowRunRepositoryPostgres extends WorkflowRunRepositoryMongo {
+    toId(id) {
+        const n = Number.parseInt(id, 10);
+        if (Number.isNaN(n)) throw new Error(`Invalid integration id: ${id}`);
+        return n;
+    }
+}
+class WorkflowRunRepositoryDocumentDB extends WorkflowRunRepositoryMongo {}
+
+function createWorkflowRunRepository() {
+    const { DB_TYPE } = require('../../../database/config');
+    switch (DB_TYPE) {
+        case 'mongodb': return new WorkflowRunRepositoryMongo();
+        case 'postgresql': return new WorkflowRunRepositoryPostgres();
+        case 'documentdb': return new WorkflowRunRepositoryDocumentDB();
+        default: throw new Error(`Unsupported database type: ${DB_TYPE}. Supported values: 'mongodb', 'documentdb', 'postgresql'`);
+    }
+}
+
+module.exports = { createWorkflowRunRepository, WorkflowRunRepositoryMongo, WorkflowRunRepositoryPostgres, WorkflowRunRepositoryDocumentDB };