@friggframework/core 2.0.0--canary.690.08cd07e.0 → 2.0.0--canary.693.d8859c2.0

package/integrations/data-defined/schema/records.md

@@ -0,0 +1,98 @@
+# Data-defined integrations: database records (v0.1)
+
+Three layers, stored separately. Worked examples for Phone ↔ HubSpot are in `examples/records/`.
+
+| Layer | What it holds | Table | Changes when |
+|---|---|---|---|
+| Definition | What the integration can do | `IntegrationDefinitionVersion` (new) | A version is published (then never again) |
+| Installation | What one customer turned on and chose | `Integration.config` (existing column, new shape) | The customer configures, or an upgrade moves the pin |
+| State | What has happened | `IntegrationMapping` (existing), `WorkflowRun` (new) | Every event |
+
+## IntegrationDefinitionVersion (new)
+
+One row per published version. `document` is the definition verbatim; `checksum` is sha256 of its canonical JSON
+(sorted keys), so the same content always has the same checksum and an installation can prove what it runs.
+
+```prisma
+model IntegrationDefinitionVersion {
+  id            String   @id @default(cuid())
+  definitionId  String                       // "phone-hubspot"
+  version       String                       // "1.4.0" (semver)
+  schemaVersion String                       // "0.1"
+  status        DefinitionStatus @default(DRAFT)
+  checksum      String                       // "sha256:..." of canonical(document)
+  document      Json                         // the definition, immutable once PUBLISHED
+  changeLevel   String?                      // patch | minor | major, computed by versioning.diff at publish
+  previousVersion String?
+  notes         String?
+  createdBy     String?
+  createdAt     DateTime @default(now())
+  publishedAt   DateTime?
+
+  @@unique([definitionId, version])
+  @@index([definitionId, status])
+}
+
+enum DefinitionStatus { DRAFT PUBLISHED DEPRECATED RETIRED }
+```
+
+Rules: a `DRAFT` may be edited; publishing runs `validate` (must be valid) and `checkBump` against the latest
+published version (the declared bump must cover the computed change level), then freezes the row. `DEPRECATED`
+versions keep running for installations pinned to them but cannot be newly installed. A version is `RETIRED` only
+when no installation pins it and no queued message references it.
+
+## Integration.config (existing column)
+
+```jsonc
+{
+  "definition": { "id": "phone-hubspot", "version": "1.4.0", "checksum": "sha256:…" },   // the pin
+  "settings":  { "fromNumber": "+15125550100" },                                       // integration-level settings
+  "syncs":     { "contacts": { "enabled": true, "mapping": [ /* optional full override */ ] } },
+  "workflows": { "missed-call-task": { "enabled": true, "settings": { "owner": "81273645" } } },
+  "ui":        { "phone-card": { "enabled": true } },
+  "runtime":   { "installed": { "hook": { "id": "WHk2c9", "url": "…", "events": [ … ] } } }  // runtime-owned: onInstall results by step id
+}
+```
+
+An absent `enabled` means "use the definition's default". The existing `Integration.version` column mirrors
+`config.definition.version` so it can be queried and indexed.
+
+## IntegrationMapping (existing) — three kinds of row
+
+| `sourceId` | `mapping` | Written by |
+|---|---|---|
+| `link:<sync>:<moduleKey>:<id>` | `{ "<moduleKey>": id, …, linkedAt }` | `links.upsert` (both sides get a row) |
+| `idx:<sync>:<identityKey>:<normalised value>` | same as link | `links.upsert` with `keys` (email lowercased, phone E.164) |
+| `evt:<definition>:<workflow>:<providerEventId>` | `{ at }` | `runWorkflow`, insert-only (`createMapping`) so a redelivery is a no-op |
+
+No new table: these are the rows hand-written integrations already keep, under a fixed naming scheme.
+
+## WorkflowRun (new)
+
+One row per workflow execution. Carries the definition version it ran on, so a run is always explainable against the
+exact document, even after an upgrade.
+
+```prisma
+model WorkflowRun {
+  id                String   @id @default(cuid())
+  integrationId     String
+  definitionId      String
+  definitionVersion String
+  workflowId        String
+  triggerType       String                     // webhook | schedule | userAction | syncRecord
+  eventId           String?                    // provider event id (dedupe key)
+  status            String                     // completed | stopped | filtered | duplicate | failed
+  reason            String?                    // why it stopped
+  error             String?
+  attempt           Int      @default(1)
+  trace             Json                       // [{ id, use, status, ms, error? }] — no payload bodies
+  startedAt         DateTime
+  endedAt           DateTime?
+
+  @@index([integrationId, workflowId, startedAt])
+  @@index([integrationId, status])
+}
+```
+
+Retention: keep `failed` runs 30 days and the rest 7 by default. `trace` holds step ids, timings and error messages,
+never request or response bodies (those can hold customer data; the existing logging rules apply).

package/integrations/data-defined/schema-check.js

@@ -0,0 +1,58 @@
+/**
+ * Two layers of validation, run together everywhere (the CLI, the tests, anything that publishes):
+ *   1. JSON Schema (schema/*.schema.json) — the published shape. Needs ajv, which the monorepo installs for
+ *      @friggframework/schemas; core's runtime stays dependency-free, so ajv is loaded only here.
+ *   2. References (validate.js / manifests.js) — what a schema cannot see: steps name declared capabilities,
+ *      $.steps.x is an earlier step, view paths exist, option inputs are declared, and so on.
+ * A document is valid only when both pass.
+ */
+const fs = require('fs');
+const path = require('path');
+const { validate } = require('./validate');
+const { validateManifest } = require('./manifests');
+
+const SCHEMA_DIR = path.join(__dirname, 'schema');
+let compiled;
+
+function loadAjv() {
+    try { return require('ajv/dist/2020'); } catch {
+        const e = new Error('ajv is not installed. Run npm install at the monorepo root (@friggframework/schemas depends on ajv@8).');
+        e.code = 'NO_AJV';
+        throw e;
+    }
+}
+
+function schemas() {
+    if (compiled) return compiled;
+    const Ajv = loadAjv();
+    const ajv = new Ajv({ allErrors: true, strict: false });
+    const read = (f) => JSON.parse(fs.readFileSync(path.join(SCHEMA_DIR, f), 'utf8'));
+    compiled = {
+        definition: ajv.compile(read('integration-definition.v0.1.schema.json')),
+        manifest: ajv.compile(read('capability-manifest.v0.1.schema.json')),
+        installation: ajv.compile(read('installation.v0.1.schema.json')),
+    };
+    return compiled;
+}
+
+const schemaErrors = (check, doc) => (check(doc) ? [] : check.errors.map((e) => ({ layer: 'schema', path: e.instancePath.replace(/^\//, '').replace(/\//g, '.') || '(root)', message: e.message + (e.params?.allowedValues ? ` (${e.params.allowedValues.join(', ')})` : e.params?.additionalProperty ? ` ("${e.params.additionalProperty}")` : '') })));
+
+/** @returns {{ valid: boolean, errors: Array<{layer,path,message}>, warnings: Array<{layer,path,message}> }} */
+function checkManifest(manifest) {
+    const errors = [...schemaErrors(schemas().manifest, manifest), ...validateManifest(manifest).errors.map((e) => ({ layer: 'references', ...e }))];
+    return { valid: errors.length === 0, errors, warnings: [] };
+}
+
+/** A definition against the manifests of the modules it uses. Both layers run even when the first fails. */
+function checkDefinition(def, manifests) {
+    const v = validate(def, manifests);
+    const errors = [...schemaErrors(schemas().definition, def), ...v.errors.map((e) => ({ layer: 'references', ...e }))];
+    return { valid: errors.length === 0, errors, warnings: v.warnings.map((w) => ({ layer: 'references', ...w })) };
+}
+
+function checkInstallation(config) {
+    const errors = schemaErrors(schemas().installation, config);
+    return { valid: errors.length === 0, errors, warnings: [] };
+}
+
+module.exports = { checkDefinition, checkManifest, checkInstallation, loadAjv };

package/integrations/data-defined/scripts/validate.js

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+/**
+ * Validate data-defined integration definitions and capability manifests: JSON Schema, then references.
+ *
+ *   node scripts/validate.js                       every bundled manifest and example
+ *   node scripts/validate.js my.definition.json    one or more definitions (files or directories)
+ *   node scripts/validate.js --manifests dir/ ...  check against manifests in another directory
+ *   node scripts/validate.js --strict ...          warnings fail too
+ *   node scripts/validate.js --json ...            machine-readable result on stdout
+ *
+ * Exit codes: 0 valid · 1 invalid · 2 could not run (bad arguments, unreadable file, ajv missing).
+ * Manifests are always checked first, because a definition is only as trustworthy as the manifests it is checked
+ * against: an invalid manifest fails the run even if every definition passes.
+ */
+const fs = require('fs');
+const path = require('path');
+
+const root = path.join(__dirname, '..');
+const args = process.argv.slice(2);
+const flag = (name) => { const i = args.indexOf(name); if (i < 0) return false; args.splice(i, 1); return true; };
+const option = (name) => { const i = args.indexOf(name); if (i < 0) return null; const v = args[i + 1]; args.splice(i, 2); return v; };
+
+const strict = flag('--strict');
+const asJson = flag('--json');
+const manifestDir = option('--manifests') || path.join(root, 'capabilities');
+const unknown = args.find((a) => a.startsWith('--'));
+if (unknown) { console.error(`Unknown option ${unknown}`); process.exit(2); }
+
+const jsonFiles = (p) => {
+    if (!fs.existsSync(p)) { console.error(`No such file or directory: ${p}`); process.exit(2); }
+    return fs.statSync(p).isDirectory() ? fs.readdirSync(p).filter((f) => f.endsWith('.json')).map((f) => path.join(p, f)) : [p];
+};
+const readJson = (f) => { try { return JSON.parse(fs.readFileSync(f, 'utf8')); } catch (e) { console.error(`${f}: not valid JSON (${e.message})`); process.exit(2); } };
+
+let check;
+try { check = require('../schema-check'); check.loadAjv(); } catch (e) { console.error(e.message); process.exit(2); }
+
+const manifestFiles = jsonFiles(manifestDir).filter((f) => f.endsWith('.capabilities.json'));
+const definitionFiles = (args.length ? args : [path.join(root, 'examples')]).flatMap(jsonFiles).filter((f) => !f.endsWith('.capabilities.json') && !f.includes(`${path.sep}records${path.sep}`));
+
+const manifests = {};
+const results = [];
+for (const f of manifestFiles) {
+    const m = readJson(f);
+    manifests[m.module] = m;
+    results.push({ kind: 'manifest', file: path.relative(process.cwd(), f), name: m.module, ...check.checkManifest(m) });
+}
+for (const f of definitionFiles) {
+    const def = readJson(f);
+    results.push({ kind: 'definition', file: path.relative(process.cwd(), f), name: `${def.id}@${def.version}`, ...check.checkDefinition(def, manifests) });
+}
+
+const failed = results.filter((r) => !r.valid || (strict && r.warnings.length));
+if (asJson) {
+    process.stdout.write(JSON.stringify({ valid: failed.length === 0, strict, results }, null, 2) + '\n');
+} else {
+    for (const r of results) {
+        const bad = !r.valid || (strict && r.warnings.length);
+        console.log(`${bad ? 'FAIL' : 'ok  '} ${r.kind.padEnd(10)} ${r.name}${r.warnings.length ? `  (${r.warnings.length} warning${r.warnings.length > 1 ? 's' : ''})` : ''}`);
+        for (const e of r.errors) console.log(`       error   [${e.layer}] ${e.path}: ${e.message}`);
+        for (const w of r.warnings) console.log(`       warning [${w.layer}] ${w.path}: ${w.message}`);
+    }
+    const n = (k) => results.filter((r) => r.kind === k).length;
+    console.log(`\n${n('manifest')} manifests, ${n('definition')} definitions: ${failed.length ? `${failed.length} failed` : 'all valid'}${strict ? ' (strict)' : ''}`);
+}
+process.exit(failed.length ? 1 : 0);

package/integrations/data-defined/steps.js

@@ -0,0 +1,89 @@
+/**
+ * The v0.1 step catalogue. A step is { id?, use, with?, when?, onError? }.
+ *
+ * `use` is either a built-in below or "<moduleKey>.<object>.<verb>": a capability the module's manifest declares
+ * (e.g. "hubspot.task.create" -> HubSpot Api.createTask). Nothing else can run: there is no http, eval or script step.
+ * The only way to run custom code is `code`, which calls a named, versioned function registered with the runtime.
+ */
+const { applyMapping, deepMerge } = require('./transforms');
+const { resolve } = require('./expressions');
+
+const BUILTINS = {
+    'links.find': {
+        summary: 'Find records already linked, by a sync or a link set (definition.links). By one side\'s id, or by an identity key it indexes (email, phone).',
+        args: { link: 'link set id (or sync: sync id)', from: 'module key, with id', id: 'that module\'s record id', key: '{ <identity field>: value }' },
+        run: (a, { ports }) => ports.links.find(a),
+    },
+    'links.upsert': {
+        summary: 'Record that records on two sides are the same thing, and index their identity keys.',
+        args: { link: 'link set id (or sync: sync id)', ids: '{ <module key>: id }', keys: '{ <identity field>: value }' },
+        run: (a, { ports }) => ports.links.upsert(a),
+    },
+    map: {
+        summary: 'Apply a field mapping: a sync\'s mapping (with the installation\'s overrides) or an inline one.',
+        args: { sync: 'sync id', mapping: 'inline rows', record: 'the source record' },
+        run: (a, { def, installation }) => {
+            let rows = a.mapping;
+            if (!rows && a.sync) {
+                const sync = (def.syncs || []).find((s) => s.id === a.sync);
+                if (!sync) throw new Error(`map: unknown sync "${a.sync}"`);
+                rows = installation?.syncs?.[a.sync]?.mapping || sync.mapping;
+            }
+            return applyMapping(rows, a.record || {});
+        },
+    },
+    template: {
+        summary: 'Render a named template (definition.templates) or inline text.',
+        args: { id: 'template id', text: 'inline template' },
+        run: (a, { def, ctx }) => {
+            const src = a.id ? def.templates?.[a.id] : a.text;
+            if (src == null) throw new Error(`template: unknown template "${a.id}"`);
+            return resolve(src, ctx);
+        },
+    },
+    merge: {
+        summary: 'Deep-merge objects into one; later objects win, lists are replaced.',
+        args: { objects: '[object, ...]' },
+        run: (a) => deepMerge(...(Array.isArray(a.objects) ? a.objects : [])),
+    },
+    set: {
+        summary: 'Store values in $.vars for later steps.',
+        args: { '<name>': 'value' },
+        run: (a, { ctx }) => { Object.assign(ctx.vars, a); return a; },
+    },
+    stop: {
+        summary: 'End the run early (a normal outcome, not an error). Usually guarded by `when`.',
+        args: { reason: 'string' },
+        run: (a) => ({ stop: true, reason: a.reason || 'stopped' }),
+    },
+    foreach: {
+        summary: 'Run nested steps once per item ($.item). Bounded by max (default 100, hard cap 1000). With `collect`, the step\'s result is the list of that value per item; `where` skips items.',
+        args: { over: 'array', max: 'number', where: 'condition on $.item', collect: 'value per item (may use $.item and this iteration\'s $.steps)', do: 'steps (optional when collect is set)' },
+        nested: true,
+    },
+    branch: {
+        summary: 'Run the first case whose `when` holds, else the `else` steps.',
+        args: { cases: '[{ when, do }]', else: 'steps' },
+        nested: true,
+    },
+    code: {
+        summary: 'Call a registered code step: a named, versioned function shipped in reviewed code ("pkg#fn@1.2.0").',
+        args: { ref: 'string', with: 'object' },
+        run: (a, { ports }) => {
+            if (!ports.runCode) throw new Error('code: this runtime has no code steps registered');
+            return ports.runCode(a.ref, a.with || {});
+        },
+    },
+};
+
+const FOREACH_HARD_CAP = 1000;
+
+function isBuiltin(use) { return Object.prototype.hasOwnProperty.call(BUILTINS, use); }
+
+/** "hubspot.task.create" -> { module: 'hubspot', capability: 'task.create' } */
+function splitCapability(use) {
+    const i = use.indexOf('.');
+    return i < 0 ? null : { module: use.slice(0, i), capability: use.slice(i + 1) };
+}
+
+module.exports = { BUILTINS, FOREACH_HARD_CAP, isBuiltin, splitCapability };

package/integrations/data-defined/transforms.js

@@ -0,0 +1,91 @@
+/** Field transforms used by sync mappings and the `map` step (v0.1). Pure functions: (value, options, record) -> value. */
+const TRANSFORMS = {
+    none: (v) => v,
+    trim: (v) => (typeof v === 'string' ? v.trim() : v),
+    lowercase: (v) => (typeof v === 'string' ? v.toLowerCase() : v),
+    uppercase: (v) => (typeof v === 'string' ? v.toUpperCase() : v),
+    number: (v) => (v == null || v === '' ? undefined : Number(v)),
+    boolean: (v) => (v == null ? undefined : v === true || v === 'true' || v === 1 || v === '1'),
+    to_iso_date: (v) => { if (!v) return undefined; const d = new Date(v); return isNaN(d) ? undefined : d.toISOString(); },
+    /** Digits with a leading +. A 10-digit number is assumed to be NANP (options.defaultCountry overrides). */
+    to_e164_phone: (v, o = {}) => {
+        if (v == null || v === '') return undefined;
+        const s = String(v).trim();
+        const digits = s.replace(/\D/g, '');
+        if (!digits) return undefined;
+        if (s.startsWith('+')) return '+' + digits;
+        if (digits.length === 10) return (o.defaultCountry === 'GB' ? '+44' : '+1') + digits;
+        if (digits.length === 11 && digits.startsWith('1')) return '+' + digits;
+        return '+' + digits;
+    },
+    split_full_name: (v, o = {}) => {
+        if (!v) return undefined;
+        const parts = String(v).trim().split(/\s+/);
+        return o.part === 'last' ? parts.slice(1).join(' ') || undefined : parts[0];
+    },
+    join: (v, o = {}, record = {}) => (o.fields || []).map((f) => readField(record, f)).filter((x) => x != null && x !== '').join(o.separator ?? ' ') || undefined,
+    map_values: (v, o = {}) => (v == null ? undefined : (o.values || {})[v] ?? o.fallback),
+    default: (v, o = {}) => (v == null || v === '' ? o.value : v),
+    // money and time, rounded and total (bad input -> undefined, which the mapping leaves out)
+    units_to_cents: (v) => { const n = v == null || v === '' ? NaN : Number(v); return Number.isNaN(n) ? undefined : Math.round(Number(`${n}e2`)); },
+    cents_to_units: (v) => { const n = v == null || v === '' ? NaN : Number(v); return Number.isNaN(n) ? undefined : Math.round(n) / 100; },
+    from_unix_seconds: (v) => { const n = v == null || v === '' ? NaN : Number(v); return Number.isNaN(n) ? undefined : new Date(n * 1000).toISOString(); },
+    to_unix_seconds: (v) => { const t = v ? Date.parse(v) : NaN; return Number.isNaN(t) ? undefined : Math.floor(t / 1000); },
+};
+
+function readField(record, path) {
+    let cur = record;
+    for (const seg of String(path).split(/\.|(?=\[)/)) {
+        if (cur == null) return undefined;
+        const m = /^\[(\d+)\]$/.exec(seg);
+        cur = m ? cur[Number(m[1])] : cur[seg];
+    }
+    return cur;
+}
+
+function writeField(target, path, value) {
+    const segs = String(path).split(/\.|(?=\[)/);
+    let cur = target;
+    segs.forEach((seg, i) => {
+        const m = /^\[(\d+)\]$/.exec(seg);
+        const key = m ? Number(m[1]) : seg;
+        if (i === segs.length - 1) { cur[key] = value; return; }
+        const nextIsIndex = /^\[\d+\]$/.test(segs[i + 1]);
+        if (cur[key] == null) cur[key] = nextIsIndex ? [] : {};
+        cur = cur[key];
+    });
+    return target;
+}
+
+/**
+ * Apply a field mapping to a record. A blank result is left out, never written (a blank must not overwrite a value).
+ * A row either reads `source` from the record or writes a fixed `value` (QuickBooks' Line[0].DetailType, a lifecycle
+ * stage): { target, value }. A fixed value still goes through the row's transform.
+ * @param {Array<{source?:string,value?:any,target:string,transform?:string,options?:object}>} rows
+ */
+function applyMapping(rows, record) {
+    const out = {};
+    for (const r of rows || []) {
+        const fn = TRANSFORMS[r.transform || 'none'];
+        if (!fn) throw new Error(`Unknown transform "${r.transform}"`);
+        const input = 'value' in r ? r.value : readField(record, r.source);
+        const v = fn(input, r.options || {}, record);
+        if (v === undefined || v === null || v === '') continue;
+        writeField(out, r.target, v);
+    }
+    return out;
+}
+
+/** Deep merge, later objects win; arrays and scalars are replaced, not merged. Inputs are not modified. */
+function deepMerge(...objects) {
+    const out = {};
+    for (const o of objects) {
+        if (!o || typeof o !== 'object' || Array.isArray(o)) continue;
+        for (const [k, v] of Object.entries(o)) {
+            out[k] = v && typeof v === 'object' && !Array.isArray(v) && out[k] && typeof out[k] === 'object' && !Array.isArray(out[k]) ? deepMerge(out[k], v) : v;
+        }
+    }
+    return out;
+}
+
+module.exports = { TRANSFORMS, applyMapping, readField, writeField, deepMerge };

package/integrations/data-defined/use-cases/definition-use-cases.js

@@ -0,0 +1,187 @@
+/**
+ * Application layer for data-defined integrations (ADR-063): publishing definition versions, the catalogue the
+ * runtime reads from, and per-installation upgrades. Business rules live here; the repositories only store rows.
+ *
+ *   createDefinitionCatalog()        what defineSharedIntegrationClass({ definitions }) reads: get(id, version), latest(id)
+ *   PublishDefinitionVersion         validate (schema + references) → checkBump against the latest published → store
+ *   DeprecateDefinitionVersion       PUBLISHED → DEPRECATED (still runs for its pins, cannot be newly installed)
+ *   ListPublishedDefinitions         the install catalogue: latest published version of each definition
+ *   GetDefinitionHistory             every version of one definition, newest first
+ *   PlanInstallationUpgrade          planUpgrade(installation, pinned, target), without changing anything
+ */
+const { checksum } = require('../canonical');
+const { checkBump, planUpgrade } = require('../versioning');
+
+class DefinitionError extends Error {
+    constructor(message, { status = 400, code, details } = {}) { super(message); this.name = 'DefinitionError'; this.status = status; this.code = code; this.details = details; }
+}
+
+const SEMVER = /^(\d+)\.(\d+)\.(\d+)(?:-([\w.]+))?$/;
+function compareVersions(a, b) {
+    const x = SEMVER.exec(a), y = SEMVER.exec(b);
+    if (!x || !y) return String(a).localeCompare(String(b));
+    for (let i = 1; i <= 3; i += 1) if (Number(x[i]) !== Number(y[i])) return Number(x[i]) - Number(y[i]);
+    if (x[4] && !y[4]) return -1;                                // 1.0.0-beta < 1.0.0
+    if (!x[4] && y[4]) return 1;
+    return String(x[4] || '').localeCompare(String(y[4] || ''));
+}
+const newestFirst = (rows) => [...rows].sort((a, b) => compareVersions(b.version, a.version));
+const SERVABLE = new Set(['PUBLISHED', 'DEPRECATED', 'RETIRED']);   // a DRAFT never reaches the runtime
+
+/**
+ * The definition store the runtime reads from. Published rows are immutable, so they are cached by id@version for the
+ * life of the process; a pinned checksum is verified, so an installation provably runs the document it was pinned to.
+ */
+function createDefinitionCatalog({ repository } = {}) {
+    const repo = () => repository || (repository = require('../repositories/definition-version-repository').createDefinitionVersionRepository());
+    const cache = new Map();
+    return {
+        async get(definitionId, version, { checksum: expected } = {}) {
+            const key = `${definitionId}@${version}`;
+            let row = cache.get(key);
+            if (!row) {
+                row = await repo().findVersion(definitionId, version);
+                if (!row || !SERVABLE.has(row.status)) return null;
+                cache.set(key, row);
+            }
+            if (expected && expected !== row.checksum) throw new DefinitionError(`${key} does not match the pinned checksum`, { status: 409, code: 'CHECKSUM_MISMATCH' });
+            return row.document;
+        },
+        /** The latest PUBLISHED version (not deprecated, not draft): what a new installation pins. */
+        async latest(definitionId) {
+            const rows = (await repo().listVersions(definitionId)).filter((r) => r.status === 'PUBLISHED');
+            return rows.length ? newestFirst(rows)[0].document : null;
+        },
+        async checksumOf(definitionId, version) {
+            return (await repo().findVersion(definitionId, version))?.checksum || null;
+        },
+        /** The install catalogue: latest published version of each definition. */
+        list: () => new ListPublishedDefinitions({ repository: repo() }).execute(),
+        /** The repository behind this catalogue, for publishing (bundled stores have none). */
+        get repository() { return repo(); },
+    };
+}
+
+class PublishDefinitionVersion {
+    /**
+     * @param {{ repository, manifests: object, check?: (def, manifests) => { valid, errors, warnings } }} deps
+     *        check defaults to schema-check's checkDefinition (JSON Schema + references)
+     */
+    constructor({ repository, manifests, check }) {
+        this.repository = repository;
+        this.manifests = manifests;
+        this.check = check || require('../schema-check').checkDefinition;
+    }
+
+    /** @returns {Promise<{ version: object, created: boolean, changeLevel: string|null, warnings: array }>} */
+    async execute({ document, notes, createdBy, publish = true, strict = false } = {}) {
+        if (!document || typeof document !== 'object') throw new DefinitionError('Send the definition as `document`');
+        const result = this.check(document, this.manifests);
+        if (!result.valid || (strict && result.warnings.length)) throw new DefinitionError(`${document.id}@${document.version} is not valid`, { code: 'INVALID', details: { errors: result.errors, warnings: result.warnings } });
+
+        const sum = checksum(document);
+        const existing = await this.repository.findVersion(document.id, document.version);
+        if (existing && existing.status !== 'DRAFT') {
+            if (existing.checksum === sum) return { version: existing, created: false, changeLevel: existing.changeLevel, warnings: result.warnings };
+            throw new DefinitionError(`${document.id}@${document.version} is already ${existing.status.toLowerCase()} and cannot change. Publish a new version.`, { status: 409, code: 'IMMUTABLE' });
+        }
+
+        const published = newestFirst((await this.repository.listVersions(document.id)).filter((r) => r.status === 'PUBLISHED' || r.status === 'DEPRECATED'));
+        const previous = published.find((r) => r.version !== document.version) || null;
+        let changeLevel = null;
+        if (previous) {
+            if (compareVersions(document.version, previous.version) <= 0) throw new DefinitionError(`${document.version} is not newer than the latest published ${previous.version}`, { status: 409, code: 'NOT_NEWER' });
+            const bump = checkBump(previous.document, document);
+            if (!bump.ok) throw new DefinitionError(bump.message, { status: 409, code: 'BUMP_TOO_SMALL', details: { required: bump.required, declared: bump.declared, changes: bump.changes } });
+            changeLevel = bump.required;
+        }
+
+        const row = {
+            definitionId: document.id, version: document.version, schemaVersion: document.schemaVersion, checksum: sum, document,
+            changeLevel, previousVersion: previous?.version || null, notes: notes ?? null, createdBy: createdBy ?? null,
+            status: publish ? 'PUBLISHED' : 'DRAFT', publishedAt: publish ? new Date() : null,
+        };
+        if (existing) {
+            // A draft may be rewritten, and published, as long as it is still a draft when we write (checked by the
+            // database, so two concurrent publishes cannot both win).
+            const updated = await this.repository.updateIfStatus(document.id, document.version, 'DRAFT', row);
+            if (!updated) throw new DefinitionError(`${document.id}@${document.version} changed while publishing; try again`, { status: 409, code: 'CONFLICT' });
+            return { version: updated, created: false, changeLevel, warnings: result.warnings };
+        }
+        try {
+            return { version: await this.repository.createVersion(row), created: true, changeLevel, warnings: result.warnings };
+        } catch (e) {
+            if (e?.code === 'P2002') {
+                // Lost a race to the same version: the same document is the same publish; anything else is a conflict.
+                const winner = await this.repository.findVersion(document.id, document.version);
+                if (winner?.checksum === sum) return { version: winner, created: false, changeLevel: winner.changeLevel, warnings: result.warnings };
+                throw new DefinitionError(`${document.id}@${document.version} was published with different content just now`, { status: 409, code: 'CONFLICT' });
+            }
+            throw e;
+        }
+    }
+}
+
+class DeprecateDefinitionVersion {
+    constructor({ repository }) { this.repository = repository; }
+    async execute({ definitionId, version }) {
+        const row = await this.repository.updateIfStatus(definitionId, version, 'PUBLISHED', { status: 'DEPRECATED' });
+        if (row) return row;
+        const existing = await this.repository.findVersion(definitionId, version);
+        if (!existing) throw new DefinitionError(`${definitionId}@${version} does not exist`, { status: 404, code: 'NOT_FOUND' });
+        throw new DefinitionError(`${definitionId}@${version} is ${existing.status.toLowerCase()}; only a published version can be deprecated`, { status: 409, code: 'WRONG_STATUS' });
+    }
+}
+
+class ListPublishedDefinitions {
+    constructor({ repository }) { this.repository = repository; }
+    /** Latest published version of each definition, with what an install screen shows. */
+    async execute() {
+        const byId = new Map();
+        for (const r of await this.repository.listByStatus(['PUBLISHED'])) {
+            const cur = byId.get(r.definitionId);
+            if (!cur || compareVersions(r.version, cur.version) > 0) byId.set(r.definitionId, r);
+        }
+        const out = [];
+        for (const r of byId.values()) {
+            const doc = (await this.repository.findVersion(r.definitionId, r.version)).document;
+            out.push({
+                id: r.definitionId, version: r.version, checksum: r.checksum, publishedAt: r.publishedAt,
+                display: doc.display, modules: Object.fromEntries(Object.entries(doc.modules || {}).map(([k, m]) => [k, m.module])),
+                counts: { syncs: (doc.syncs || []).length, links: (doc.links || []).length, workflows: (doc.workflows || []).length, ui: (doc.ui || []).length },
+            });
+        }
+        return out.sort((a, b) => String(a.display?.label || a.id).localeCompare(String(b.display?.label || b.id)));
+    }
+}
+
+class GetDefinitionHistory {
+    constructor({ repository }) { this.repository = repository; }
+    async execute({ definitionId }) {
+        const rows = newestFirst(await this.repository.listVersions(definitionId));
+        if (!rows.length) throw new DefinitionError(`No definition "${definitionId}"`, { status: 404, code: 'NOT_FOUND' });
+        return rows.map(({ document, ...meta }) => meta);
+    }
+}
+
+class PlanInstallationUpgrade {
+    constructor({ catalog }) { this.catalog = catalog; }
+    /** @returns {Promise<{ from, to, allowed, needs, actions, config, changes }>} */
+    async execute({ config, toVersion }) {
+        const pin = config?.definition;
+        if (!pin?.id || !pin?.version) throw new DefinitionError('This installation does not name a definition', { code: 'NO_PIN' });
+        const from = await this.catalog.get(pin.id, pin.version);
+        const target = toVersion || (await this.catalog.latest(pin.id))?.version;
+        if (!target) throw new DefinitionError(`No published version of "${pin.id}"`, { status: 404, code: 'NOT_FOUND' });
+        const to = await this.catalog.get(pin.id, target);
+        if (!from || !to) throw new DefinitionError(`${pin.id}@${!from ? pin.version : target} is not published`, { status: 404, code: 'NOT_FOUND' });
+        const plan = planUpgrade(config, from, to);
+        plan.config.definition = { ...plan.config.definition, checksum: await this.catalog.checksumOf(pin.id, target) };
+        return { from: pin.version, to: target, ...plan, changes: require('../versioning').diff(from, to).changes };
+    }
+}
+
+module.exports = {
+    DefinitionError, compareVersions, createDefinitionCatalog,
+    PublishDefinitionVersion, DeprecateDefinitionVersion, ListPublishedDefinitions, GetDefinitionHistory, PlanInstallationUpgrade,
+};