@friggframework/core 2.0.0--canary.703.12b980b.0 → 2.0.0--canary.707.df80bfd.0

package/integrations/define/DESIGN.md

@@ -1,122 +0,0 @@
-# defineIntegration: design note
-
-ADR-054's stable, event-driven path (target file (a)) built on Stack B's integration runtime (ADR-063, #693–#700).
-The same decisions are recorded as an amendment in ADR-054 (#669).
-
-## 1. One runtime, two front doors
-
-Both front doors compile to one target: an `IntegrationBase` subclass with a static `Definition` and an instance
-`events` map. Everything downstream reads only that target: the devtools builders, the defined-routes and webhook
-routers, the queue worker, the ADR-055 tick (`RunTriggerTick`, one tick, per-installation due decisions), the run
-(`IntegrationBase#onTriggerRun` with `RunTrigger`), `integration-types` and the management API.
-
-| | Code (`defineIntegration`, this folder) | Document (ADR-063, `definitions/`) |
-|---|---|---|
-| Entry | `defineIntegration({...})` | `fromDefinitionDocument(...)`, `definitionDocumentHost(...)`, `embedDefinitionDocument(Cls, ...)` |
-| `Definition.modules` | from `modules: { key: use(module) }` | from the document's `modules` |
-| Webhooks | contract-2 extension, compiled to a contract-1 `Definition.extensions` binding | capability manifest `webhook` block, `Definition.webhooks` |
-| Recurring work | `Definition.triggers` (ADR-055) | `triggersFor()` / `Definition.instanceTriggers` (ADR-055) |
-| Handlers | functions `(payload, ctx)` | workflow steps (interpreter), `code` steps |
-
-Neither is a serialisation of the other. They compose: `embedDefinitionDocument(DealAlerts, { definition })` gives a
-`defineIntegration` class a document's workflows, and both kinds of trigger come out of one `triggersFor` list
-(`tests/front-doors.test.js`).
-
-Base branch: Stack B's tip (`claude/shared-conversation-8hgmbr-stack-9-module-methods`). Its compile target was
-suitable as is; the only changes to Stack B code are additive (`webhookRequestFacts` exported, `static visible`
-honoured by `integration-types`, the document-door names below as aliases).
-
-## 2. Names
-
-| Collision | Resolution |
-|---|---|
-| `defineIntegrationClass` beside `defineIntegration` | `defineIntegration` is the code front door. The document door is named for documents: `fromDefinitionDocument` (was `defineIntegrationClass`), `definitionDocumentHost` (was `defineSharedIntegrationClass`), `embedDefinitionDocument` (was `extendIntegrationClass`). The old names are aliases until Stack B merges. |
-| "Definition" means three things | `Definition` is only the static on the class (the compile target). The ADR-063 JSON is an *integration document* (its schema becomes `integration-document.v0.1.schema.json`). `config.definition` is the installation's *document pin*. |
-| workflow `trigger` vs ADR-055 `triggers` | One registry: `Definition.triggers`. `defineIntegration`'s `triggers` is that key (functions wrapped to get `ctx`); a contract-2 extension's `triggers` merge as `<moduleKey>.<name>` (dotted names are reserved for them). A document's `workflows[].trigger` is a workflow's start condition, not a registry; its `schedule` kind compiles into the same list through `triggersFor`. |
-| Webhook facts in contract 2 and in capability manifests | Declared once, by the module. Verification is an Api method (`verifyWebhookSignature(input)`, with #699's input `{ headers, body, query, rawBody, method, url }`); contract 2 may name it (`verify: 'verifyWebhookSignature'`) as a manifest's `webhook.verify` does. Emitted names, account resolution and the subscription set live in the contract-2 extension; a manifest's `webhook`/`events` blocks should be generated from it (follow-up), not written beside it. `use()` options (`subscribe`, `hydrate`) reference those facts and never restate them. |
-
-## 3. API (as built)
-
-```text
-defineIntegration({ name, version, display, usage, modules: { <key>: use(module, { <ext>: opts }) },
-                    config, on, triggers, actions, visible, webhooks?, routes? })   // -> IntegrationBase subclass
-defineApp({ name, integrations, ...appDefinition })                                 // -> { Definition }
-use(module, extensionOptions?)                                                      // core's, not the module's
-defineExtension(bundle)                                                             // optional; a plain object works
-reconcileAppSubscriptions({ integrations, listInstallations?, prune?, dryRun? })   // app-scope subscriptions, add-only unless prune
-createReconcileSubscriptionsScript({ name, extension })                           // the admin script (prune, dryRun inputs)
-```
-
-- Handlers are `(payload, ctx)`, called without `this`. `ctx = { modules, config, log, telemetry, commands,
-  integration }`, frozen. `ctx.modules.<key>` is the installation's Api for that binding. `ctx.config` is the stored
-  config with the form defaults. `ctx.integration` is a read-only record (`id, name, status, userId, entities,
-  version`) — ADR-054 open question 6, lean taken. `commands` is created on first use.
-- Unknown keys, an `on` key no bound extension emits, method-name handlers, bad `use()` options, trigger problems,
-  name collisions and a contract or core-range mismatch all throw when the class is defined.
-- **Module keys cannot name an `IntegrationBase` member** (`config`, `events`, `send`, `id`, …). `_appendModules`
-  attaches each module to the instance as `this[key]`, so such a key would overwrite the member. Inside
-  `ctx.modules` any name is fine; the instance is the constraint. (ADR-054 said any identifier works.)
-- `config` entries are JSON Schema fragments (`required: true` and `ui` are lifted) or **module fields**:
-  `module.fields.<name>(opts)` returns `{ module, schema, required, ui, options(api, { config }) }`. Fields are a
-  module export, not an extension key, because a module bound without an extension (Slack in (a)) offers them too.
-- `actions` become `USER_ACTION` events (`DATA_ACTION`), run as `run(input, ctx)`.
-- `visible(context)` becomes `static visible`; `integration-types` honours it when a caller passes a context.
-
-## 4. Extension contract 2 (the stable minimum)
-
-A contract-2 extension enabled with `use()` compiles to a contract-1 binding under `<moduleKey>-<extKey>`, so devtools
-gives it its function (`deal-alerts__crmwebhooks`, no Prisma layer unless `useDatabase`), the router mounts its
-routes under `/api/<integration>-integration/crm-webhooks`, and the queue worker runs its events:
-
-1. **Receipt** (`CRM__WEBHOOKS__RECEIVED`, no database): `handshake` (answered synchronously), `verify` (401 with a
-   logged reason), `receive` splits the delivery into `{ externalId, body }` items, one `RESOLVE` message each.
-2. **Resolve** (`CRM__WEBHOOKS__RESOLVE`, worker, dry): `resolve: { module }` looks up the installations of this
-   integration type connected to the account (the entity reverse lookup, filtered by type) and queues one
-   `DISPATCH` per installation. It fans out instead of throwing on two matches, as Stack B's app-level webhooks do.
-3. **Dispatch** (`CRM__WEBHOOKS__DISPATCH`, worker, hydrated): `normalize(batch, { api, options, config, env, log })`
-   turns the body into `{ name, payload }` events (the HubSpot module hydrates here, with the installation's
-   credential); each runs `on['crm.<name>']`, else the extension's default handler, else it is acked and counted
-   (`frigg.extension.event_unhandled`). `CRM__WEBHOOKS__DEAL_CHANGED` etc. exist for replays.
-4. **Subscriptions, app scope**: `reconcileAppSubscriptions` takes the union of `desired(options)` over every class
-   that binds the extension (per ENABLED installation when an option is a function of config), lists what the
-   provider has and creates what is missing. **Add-only by default**: it removes what no binding needs only with
-   `prune: true`, and only when it could read every installation's config (otherwise it reports `pruneSkipped`). A
-   dry run reports `create` and `remove` and writes nothing. **Supported setup: one provider developer app per
-   stage**, because subscriptions are app-wide; stages sharing one developer app would see, and with `prune` remove,
-   each other's. It runs at three points, with no recurring trigger:
-   - (a) **after deploy**: `frigg deploy` runs it add-only with no database (`--prune-subscriptions` prunes groups
-     whose options are all static; `--skip-subscriptions` skips it). A failure is reported, never a failed deploy.
-   - (b) **installation lifecycle**: on create and config update, an ENABLED installation whose binding options are
-     functions of its config gets the subscriptions it needs (`ensureInstallationSubscriptions`, add-only). On delete
-     nothing is called: removal needs the whole app's union, so it is a pruning reconcile's job. A failure is a
-     warning on the installation. The call sites are `onCreate`/`onUpdate`/`onDelete` overrides until the §5
-     dispatcher exists.
-   - (c) **admin script**: `createReconcileSubscriptionsScript(...)` with `prune` and `dryRun` inputs, run in the
-     stack where installations can be read. `defineApp` appends scripts that bound modules export (`module.scripts`);
-     the HubSpot module exports `hubspot.reconcile-subscriptions`.
-5. **One bundle, both contracts**: a contract-2 bundle may keep its contract-1 face (`events` and `routes[].event`),
-   which a class binding it by hand through `Definition.extensions` (or an older core) runs. `defineIntegration`
-   ignores both. That is how the HubSpot module moves `extensions.webhooks` to contract 2 without a major version.
-6. **Options**: `use()` options are checked against the extension's `options` schema when the class is defined;
-   function values are resolved with the installation's config and checked again.
-
-Not in this PR (checklist on the PR): extension `lifecycle` hooks and the §5 dispatcher (the subscription call sites
-move there), ADR-027 `env` scoping
-in devtools and `frigg validate`, `instance`-scope subscriptions (experimental), the Slack module promotion, and
-generating capability-manifest webhook blocks from contract 2.
-
-## 5. Open questions
-
-1. *(Decided: no recurring reconcile. It runs after deploy, on installation lifecycle, and from the admin script.)*
-2. *(Decided: add-only by default, `prune` on request; one developer app per stage is the supported setup.)*
-   Alternative under evaluation: HubSpot's Webhooks Journal API makes subscriptions per portal (installation scope),
-   at the cost of a polling consumer. See the ADR-054 amendment.
-3. **Where verification runs.** Contract 2 verifies at receipt (no database, app-scope secret from env). Stack B
-   verifies manifest webhooks in the worker (raw body carried in the message, #699). One place for both doors? Lean:
-   receipt when the secret is app-scope, the worker when it is per installation.
-4. **Event names.** The HubSpot manifest names provider topics (`deal.propertyChange`); contract 2 emits normalized
-   names (`deal.changed`, payload `{ deal, changes }`). Lean: manifest event keys become the contract-2 names, with
-   the provider topic in `match`.
-5. **Base trigger ctx.** `IntegrationBase#onTriggerRun` passes `{ modules: <module instances>, config, log,
-   integration: this }` to function handlers on classic classes; `defineIntegration` gives its handlers the ADR-054
-   ctx. Align the base to ADR-054 (`modules` -> Api) before Stack B merges?

package/integrations/define/config.js

@@ -1,98 +0,0 @@
-/**
- * `config` (ADR-054 §4): the end user's per-install form, compiled to what `getConfigOptions()` returns today
- * (`{ jsonSchema, uiSchema }`), so `validateConfig()`, NEEDS_CONFIG and the config/options routes work unchanged.
- *
- * An entry is either a JSON Schema fragment, with two conveniences:
- *
- *     minAmount: { type: 'number', title: 'Only deals worth at least', default: 0, required: true, ui: { 'ui:help': '…' } }
- *
- * or a module field: what a module's `fields.<name>(opts)` returns. A field is a schema fragment plus a loader for
- * its choices, run with the installation's own credential for that module:
- *
- *     { module: 'slack', schema: { type: 'string', title }, required, ui, options: async (api, { config }) => [{ const, title }] }
- *
- * The loader runs against the binding of that module. When a module is bound twice, the author picks one with
- * `{ ...slack.fields.channel(), from: 'chatA' }`. No field reaches a form unless the integration author put it in
- * `config`, which keeps ADR-054 §4's rule: an extension never adds to the end user's form by itself.
- */
-const { withDefaults } = require('./json-schema-lite');
-
-const isField = (v) => Boolean(v && typeof v === 'object' && v.schema && typeof v.schema === 'object' && typeof v.options === 'function');
-
-/**
- * @param {object} config the `config` given to defineIntegration
- * @param {Array<{ key, moduleName }>} bindings
- * @param {string} where for messages
- */
-function compileConfig(config = {}, bindings = [], where = 'defineIntegration') {
-    if (!config || typeof config !== 'object' || Array.isArray(config)) throw new Error(`${where}: "config" must be an object keyed by field name`);
-    const properties = {}, uiSchema = {}, required = [], fields = {};
-    for (const [name, entry] of Object.entries(config)) {
-        if (!entry || typeof entry !== 'object') throw new Error(`${where}: config.${name} must be a JSON Schema fragment or a module field`);
-        if (isField(entry)) {
-            const candidates = bindings.filter((b) => (entry.from ? b.key === entry.from : b.moduleName === entry.module));
-            if (candidates.length === 0) {
-                throw new Error(`${where}: config.${name} is a ${entry.module} field${entry.from ? ` from "${entry.from}"` : ''}, but no such module is bound in "modules"`);
-            }
-            if (candidates.length > 1) {
-                throw new Error(`${where}: config.${name} is a ${entry.module} field and ${entry.module} is bound as ${candidates.map((b) => b.key).join(' and ')}; say which with { ...field, from: '<key>' }`);
-            }
-            fields[name] = { field: entry, moduleKey: candidates[0].key };
-            properties[name] = { ...entry.schema };
-            if (entry.ui) uiSchema[name] = { ...entry.ui };
-            if (entry.required) required.push(name);
-            continue;
-        }
-        const { required: isRequired, ui, ...schema } = entry;
-        if (isRequired !== undefined && typeof isRequired !== 'boolean') throw new Error(`${where}: config.${name}.required must be true or false`);
-        properties[name] = schema;
-        if (ui) uiSchema[name] = { ...ui };
-        if (isRequired) required.push(name);
-    }
-    const jsonSchema = { type: 'object', properties, ...(required.length ? { required } : {}) };
-    return { jsonSchema, uiSchema, fields };
-}
-
-/** The config a handler sees: the stored config with the form's defaults filled in. */
-function resolveConfig(plan, stored = {}) {
-    return withDefaults(plan.jsonSchema, stored || {});
-}
-
-const asChoice = (c) => (c && typeof c === 'object'
-    ? { const: c.const ?? c.value ?? c.id, title: String(c.title ?? c.label ?? c.name ?? c.const ?? c.value ?? c.id) }
-    : { const: c, title: String(c) });
-
-/**
- * The form with each module field's choices loaded from the connected account.
- * @param {object} plan compileConfig's result
- * @param {(moduleKey: string) => object|undefined} apiFor the installation's Api for a binding key
- * @param {object} values the stored config, or the form's current values on refresh
- * @param {{ warn: Function }} [log]
- */
-async function configOptions(plan, apiFor, values = {}, log) {
-    const jsonSchema = JSON.parse(JSON.stringify(plan.jsonSchema));
-    const uiSchema = JSON.parse(JSON.stringify(plan.uiSchema));
-    const config = resolveConfig(plan, values);
-    for (const [name, { field, moduleKey }] of Object.entries(plan.fields)) {
-        const api = apiFor(moduleKey);
-        let choices = [];
-        if (api) {
-            try {
-                choices = (await field.options(api, { config })) || [];
-            } catch (error) {
-                log?.warn?.('Config field options did not load', { eventName: 'frigg.define.config_options_failed', field: name, error });
-                uiSchema[name] = { ...(uiSchema[name] || {}), 'ui:help': 'The options could not be loaded from the connected account. Try again.' };
-            }
-        } else {
-            uiSchema[name] = { ...(uiSchema[name] || {}), 'ui:help': `Connect ${field.module} to choose.` };
-        }
-        const oneOf = choices.map(asChoice);
-        if (!oneOf.length) continue;
-        const prop = { ...field.schema, ...(field.schema.title ? { title: field.schema.title } : {}) };
-        if (prop.type === 'array') jsonSchema.properties[name] = { ...prop, uniqueItems: true, items: { ...(prop.items || { type: 'string' }), oneOf } };
-        else jsonSchema.properties[name] = { ...prop, oneOf };
-    }
-    return { jsonSchema, uiSchema };
-}
-
-module.exports = { compileConfig, resolveConfig, configOptions, isField };

package/integrations/define/define-app.js

@@ -1,66 +0,0 @@
-/**
- * `defineApp` (ADR-054 §1): the app definition, as `backend/index.js` exports it today (`{ Definition }`).
- *
- *     module.exports = defineApp({ name, integrations: [DealAlerts], database: { postgres: { enable: true } } });
- *
- * It checks what can be checked when the file loads: every integration is an IntegrationBase subclass with a
- * `Definition.name`, names are unique, and the app definition passes ADR-051's `app-definition.schema.json`
- * (through `@friggframework/schemas`, when the app has it installed; the schema treats each integration as an
- * object, so the classes are checked here and summarised for it).
- *
- * It also appends the admin scripts the bound modules export (`module.scripts`, e.g. HubSpot's
- * `hubspot.reconcile-subscriptions`) to `adminScripts`, once each by name; a script the app lists itself wins.
- */
-const { IntegrationBase } = require('../integration-base');
-const { planOf } = require('./define-integration');
-
-function loadSchemas() {
-    try {
-        // eslint-disable-next-line global-require
-        return require('@friggframework/schemas');
-    } catch (error) {
-        if (error?.code === 'MODULE_NOT_FOUND') return null;
-        throw error;
-    }
-}
-
-function defineApp(appDefinition = {}, { schemas = loadSchemas() } = {}) {
-    const where = `defineApp(${appDefinition?.name ? `"${appDefinition.name}"` : ''})`;
-    if (!appDefinition || typeof appDefinition !== 'object') throw new Error(`${where}: expects the app definition object`);
-    const integrations = appDefinition.integrations;
-    if (!Array.isArray(integrations) || !integrations.length) throw new Error(`${where}: "integrations" must list at least one integration`);
-    const names = new Set();
-    for (const [i, Cls] of integrations.entries()) {
-        if (typeof Cls !== 'function' || !(Cls.prototype instanceof IntegrationBase)) {
-            throw new Error(`${where}: integrations[${i}] is not an integration class (defineIntegration or an IntegrationBase subclass)`);
-        }
-        const name = Cls.Definition?.name;
-        if (!name) throw new Error(`${where}: integrations[${i}] has no Definition.name`);
-        if (names.has(name)) throw new Error(`${where}: two integrations are named "${name}"`);
-        names.add(name);
-    }
-    if (schemas?.validateAppDefinition) {
-        const summary = { ...appDefinition, integrations: integrations.map((Cls) => ({ name: Cls.Definition.name })) };
-        const result = schemas.validateAppDefinition(summary);
-        if (result && result.valid === false) {
-            const errors = (result.errors || []).map((e) => (typeof e === 'string' ? e : `${e.instancePath || e.path || ''} ${e.message || ''}`.trim()));
-            throw new Error(`${where}: the app definition does not match app-definition.schema.json: ${errors.join('; ')}`);
-        }
-    }
-    const adminScripts = [...(appDefinition.adminScripts || [])];
-    const named = new Set(adminScripts.map((S) => S?.Definition?.name));
-    for (const Cls of integrations) {
-        for (const binding of planOf(Cls)?.bindings || []) {
-            const scripts = binding.module.scripts;
-            for (const Script of Array.isArray(scripts) ? scripts : Object.values(scripts || {})) {
-                const scriptName = Script?.Definition?.name;
-                if (!scriptName || named.has(scriptName)) continue;
-                named.add(scriptName);
-                adminScripts.push(Script);
-            }
-        }
-    }
-    return { Definition: { ...appDefinition, integrations: [...integrations], ...(adminScripts.length ? { adminScripts } : {}) } };
-}
-
-module.exports = { defineApp };

package/integrations/define/define-extension.js

@@ -1,154 +0,0 @@
-/**
- * Extension contract 2 (ADR-054 §2): what an API module's extension may declare beyond contract 1's routes and
- * events. Everything is optional, and a contract-1 bundle (no `contract`, or `contract: 1`) stays valid as it is.
- *
- *     module.exports = defineExtension({            // or a plain object with `contract: 2`: modules need no core import
- *         name: 'hubspot-webhooks',
- *         contract: 2,
- *         requires: { core: '>=2.0.0-next.0 <3' },
- *         useDatabase: false,
- *         env: ['HUBSPOT_CLIENT_SECRET'],
- *         options: { type: 'object', properties: { subscribe: {...}, hydrate: {...} } },   // schema of use(m, { <key>: opts })
- *         routes: [{ path: '/webhooks', method: 'POST' }],
- *         handshake: (input, ctx) => ({ status, headers, body }) | null,     // answered at receipt, nothing queued
- *         verify: (input, ctx) => ({ valid, reason }) | boolean,             // or the name of an Api method (see below)
- *         receive: (input, ctx) => [{ externalId, body }],                   // split one delivery, at receipt (no DB)
- *         resolve: { module: 'hubspot' },                                    // externalId -> installations, in the worker
- *         emits: { 'deal.changed': {}, ... },                               // integration-facing names, prefixed by the module key
- *         normalize: async (batch, ctx) => [{ name: 'deal.changed', payload }],   // in the worker, with the installation's api
- *         subscriptions: { scope: 'app', desired, list, create, remove, key },
- *         triggers: {},                                                      // ADR-055 shape, merged as `<moduleKey>.<name>`
- *         events: {},                                                        // the contract-1 face (see below)
- *     });
- *
- * One bundle can serve both contracts: `events` and `routes[].event` are what a class that binds the bundle by hand
- * through `Definition.extensions` runs (and what an older core runs), and `defineIntegration` ignores both, because
- * core receives a contract-2 route itself and never adds bare event names. A module can therefore move its
- * extension to contract 2 without breaking the integrations that bind it the contract-1 way.
- *
- * `input` is the delivery as signature checks need it, the same object Stack B's runtime passes to a capability
- * manifest's `webhook.verify` (IntegrationBase#webhookVerificationInput): `{ headers, body, query, rawBody, method, url }`.
- * `verify` may name an Api method instead of being a function: that is how a capability manifest names it too, so a
- * module declares how deliveries are verified once, on its Api (`verifyWebhookSignature`), for both front doors.
- *
- * Not in the stable 2.0.1 path (ADR-054 decisions 2026-10-03): `subscriptions.scope: 'instance'` (experimental),
- * extension `queues`/`workers` (ADR-047), `scripts` and `lifecycle` (follow-up in this PR's checklist).
- */
-const CORE_VERSION = require('../../package.json').version;
-
-const STABLE_KEYS = new Set([
-    'name', 'contract', 'requires', 'useDatabase', 'env', 'options', 'routes', 'handshake', 'verify', 'receive',
-    'resolve', 'emits', 'normalize', 'subscriptions', 'triggers', 'events', 'description',
-]);
-const LATER_KEYS = new Set(['scripts', 'lifecycle', 'queues', 'workers', 'fields']);
-const METHODS = new Set(['get', 'post', 'put', 'patch', 'delete', 'options', 'head']);
-
-// ---- a tiny semver range check: space-separated comparators (>=, >, <=, <, =), prereleases ordered as semver does.
-function parseVersion(v) {
-    const m = /^v?(\d+)(?:\.(\d+))?(?:\.(\d+))?(?:-([0-9A-Za-z.-]+))?/.exec(String(v).trim());
-    if (!m) return null;
-    return { nums: [Number(m[1]), Number(m[2] || 0), Number(m[3] || 0)], pre: m[4] ? m[4].split('.') : [] };
-}
-function compareVersions(a, b) {
-    for (let i = 0; i < 3; i++) if (a.nums[i] !== b.nums[i]) return a.nums[i] < b.nums[i] ? -1 : 1;
-    if (!a.pre.length || !b.pre.length) return a.pre.length === b.pre.length ? 0 : a.pre.length ? -1 : 1;
-    for (let i = 0; i < Math.max(a.pre.length, b.pre.length); i++) {
-        const x = a.pre[i], y = b.pre[i];
-        if (x === undefined) return -1;
-        if (y === undefined) return 1;
-        const nx = /^\d+$/.test(x), ny = /^\d+$/.test(y);
-        if (nx && ny && Number(x) !== Number(y)) return Number(x) < Number(y) ? -1 : 1;
-        if (nx !== ny) return nx ? -1 : 1;
-        if (x !== y) return x < y ? -1 : 1;
-    }
-    return 0;
-}
-function satisfies(version, range) {
-    const v = parseVersion(version);
-    if (!v) return false;
-    return String(range).trim().split(/\s+/).every((part) => {
-        const m = /^(>=|<=|>|<|=)?(.+)$/.exec(part);
-        const target = parseVersion(m[2]);
-        if (!target) return false;
-        const c = compareVersions(v, target);
-        switch (m[1] || '=') {
-            case '>=': return c >= 0;
-            case '>': return c > 0;
-            case '<=': return c <= 0;
-            case '<': return c < 0;
-            default: return c === 0;
-        }
-    });
-}
-
-const contractOf = (ext) => (ext && ext.contract !== undefined ? ext.contract : 1);
-const isContract2 = (ext) => contractOf(ext) === 2;
-
-/**
- * Validate a contract-2 bundle. Throws with the extension name and what is wrong. Returns the bundle.
- * @param {object} ext
- * @param {{ coreVersion?: string, where?: string }} [opts]
- */
-function validateExtension(ext, { coreVersion = CORE_VERSION, where } = {}) {
-    const name = ext?.name || '(unnamed)';
-    const fail = (msg) => { throw new Error(`${where ? `${where}: ` : ''}extension "${name}" ${msg}`); };
-    if (!ext || typeof ext !== 'object') fail('must be an object');
-    if (typeof ext.name !== 'string' || !ext.name) fail('needs a "name"');
-    const contract = contractOf(ext);
-    if (contract !== 1 && contract !== 2) fail(`declares contract ${contract}; this core supports contracts 1 and 2`);
-    if (contract === 1) return ext;
-    if (ext.requires?.core && !satisfies(coreVersion, ext.requires.core)) {
-        fail(`requires @friggframework/core ${ext.requires.core}, but this is ${coreVersion}`);
-    }
-    for (const key of Object.keys(ext)) {
-        if (key === 'fields') fail('declares "fields": config fields are a module export (module.fields), so a module bound without an extension can offer them');
-        if (LATER_KEYS.has(key)) fail(`declares "${key}", which the stable defineIntegration does not run yet (ADR-054 phasing)`);
-        if (!STABLE_KEYS.has(key)) fail(`has an unknown key "${key}"`);
-    }
-    if (ext.useDatabase !== undefined && typeof ext.useDatabase !== 'boolean') fail('"useDatabase" must be a boolean');
-    if (ext.env !== undefined && (!Array.isArray(ext.env) || ext.env.some((e) => typeof e !== 'string'))) fail('"env" must be a list of variable names');
-    if (ext.options !== undefined && (typeof ext.options !== 'object' || ext.options === null)) fail('"options" must be a JSON Schema object');
-    for (const fn of ['handshake', 'receive', 'normalize']) {
-        if (ext[fn] !== undefined && ext[fn] !== null && typeof ext[fn] !== 'function') fail(`"${fn}" must be a function`);
-    }
-    if (ext.verify !== undefined && ext.verify !== null && typeof ext.verify !== 'function' && typeof ext.verify !== 'string') {
-        fail('"verify" must be a function or the name of an Api method');
-    }
-    const routes = ext.routes || [];
-    if (!Array.isArray(routes)) fail('"routes" must be an array');
-    for (const r of routes) {
-        if (!r || typeof r.path !== 'string' || !r.path.startsWith('/')) fail('has a route without a "/path"');
-        if (typeof r.method !== 'string' || !METHODS.has(r.method.toLowerCase())) fail(`route ${r.path} has an unsupported method`);
-        // A route's `event` is the bundle's contract-1 face: a class that binds the bundle by hand through
-        // Definition.extensions (or an older core) dispatches it. defineIntegration ignores it: core receives.
-        if (r.event !== undefined && !Object.prototype.hasOwnProperty.call(ext.events || {}, r.event)) {
-            fail(`route ${r.path} names event "${r.event}", which is not in "events" (a contract-2 route needs no event: core receives it)`);
-        }
-    }
-    if (routes.length && typeof ext.receive !== 'function') fail('has routes but no "receive"');
-    if (routes.length && !ext.resolve) fail('has routes but no "resolve"');
-    if (ext.resolve && typeof ext.resolve !== 'function' && typeof ext.resolve?.module !== 'string') fail('"resolve" must be { module } or a function');
-    if (ext.emits !== undefined && (typeof ext.emits !== 'object' || Array.isArray(ext.emits))) fail('"emits" must be an object keyed by event name');
-    for (const [k, v] of Object.entries(ext.emits || {})) {
-        if (!/^[a-z][A-Za-z0-9_-]*(\.[a-z][A-Za-z0-9_-]*)*$/.test(k)) fail(`emits "${k}": names are dotted lower-camel words (deal.changed)`);
-        if (v?.handler !== undefined && typeof v.handler !== 'function') fail(`emits "${k}": "handler" must be a function`);
-    }
-    const subs = ext.subscriptions;
-    if (subs) {
-        if (subs.scope === 'instance') fail('declares instance-scope subscriptions, which are experimental (@friggframework/core/experimental)');
-        if (subs.scope !== 'app') fail('subscriptions.scope must be "app"');
-        for (const fn of ['desired', 'list', 'create']) if (typeof subs[fn] !== 'function') fail(`subscriptions.${fn} must be a function`);
-        for (const fn of ['remove', 'key']) if (subs[fn] !== undefined && typeof subs[fn] !== 'function') fail(`subscriptions.${fn} must be a function`);
-    }
-    if (ext.triggers !== undefined && (typeof ext.triggers !== 'object' || Array.isArray(ext.triggers))) fail('"triggers" must be an object');
-    return ext;
-}
-
-/** Core's helper for module authors: validates and freezes a contract-2 bundle. A plain object works the same. */
-function defineExtension(ext) {
-    const bundle = { contract: 2, ...ext };
-    validateExtension(bundle);
-    return Object.freeze(bundle);
-}
-
-module.exports = { defineExtension, validateExtension, isContract2, contractOf, satisfies, CORE_VERSION };