// ── Seeding what a module ships (ENGAGEMENT.md Phase 11b, decision 7) ────── // // Core's own bodies and rules are seeded from `seedDefaults()`, and a module's // cannot be: `server.js` calls `seedDefaults()` BEFORE it requires `app.js`, and // requiring `app.js` is what scans the volume and runs the loader. At the moment // core seeds, no module has registered anything at all. // // So this runs from `modules/lifecycle.js` `boot()` instead — after the // `installed_modules` reconcile, so a module the operator disabled or one that // failed to load is skipped rather than seeded, and BEFORE the `onBoot` // dispatch, so a module that warms a cache in `onBoot` may assume its rules // exist. // // **It reuses core's two seeders rather than reimplementing them**, which is the // whole argument for the registry existing (decision 7): `seedOne` owns the // `customized` skip and the `seed_version` comparison, `validateEmailBlocks` // owns what a renderable body is, and a module supplies data. A copy of either // living outside this directory would drift the first time core improved the // original — and the drift would surface as a mail somebody already received. // // ── The asymmetry, once more, because it is the thing to get right ───────── // // **Templates are re-ensured every boot.** A row carries `seed_key`, // `seed_version` and `customized`, so re-ensuring is how a better default // reaches a deployment without stealing an operator's edit (§4.6.1 property 3), // and a template added in a later module version reaches every deployment rather // than only fresh ones. // // **Rule groups are one-shot, each under its own settings guard.** Re-ensuring a // rule would resurrect one an operator deleted and reset one they enabled. This // is 11a's seed-key finding as a mechanism: a rule appended to an existing group // reaches fresh installs only, and a rule that must reach already-stamped // deployments takes a new group key. The module chooses; this file honours it. // // **Never throws.** It is on the boot path beside every other `safe()`-wrapped // step in `lifecycle.boot()`, and a body that would not seed costs the shipped // default — `renderByKey`'s fallback stays in charge — not the deployment. const templatesDb = require('../model/engagement/engagementTemplates.db') const rulesDb = require('../model/engagement/engagementRules.db') const settingsDb = require('../model/settings/settings.db') const emailBlocks = require('../emailBlocks') const log = require('../utils/logger')('engagement') /** * The one-shot guard for one module's rule group. * * Namespaced by owner AND by group so two modules may use the same group name, * and so a module can add a second group later without touching the first. Its * VALUE is the timestamp — purely so an operator reading the settings table can * tell when it ran; only its presence is read. */ const guardKey = (owner, group) => `engagement_module_rules_seeded:${owner}:${group}` /** * Ensure one module's templates, and bring un-customized rows up to the current * seed. Idempotent. */ async function seedModuleTemplates(owner, templates, deps = {}) { const templates_ = deps.templatesDb || templatesDb const counts = { inserted: 0, updated: 0, skipped: 0, invalid: 0 } for (const seed of templates) { // Validated against the block registry before it is stored, exactly as core's // own seeds are and for the same reason: a shipped block array no renderer // understands sitting in the table reads to an operator as their deployment // being broken. Refusing to write it leaves the fallback in charge and puts // the reason in the boot log, with the module named. const { valid, errors } = emailBlocks.validateEmailBlocks(seed.blocks) if (!valid) { log.error('a module template is invalid and was not seeded', { owner, key: seed.key, errors }) counts.invalid += 1 continue } try { counts[await templates_.seedOne(seed)] += 1 } catch (err) { log.error('module template seed failed', { owner, key: seed.key, message: err.message }) } } // The third arm of §4.6.1 property 3: a customized row is never touched, and // the fact that a better default now exists is surfaced instead of applied. let stale = [] try { stale = await templates_.staleCustomized( templates.map((t) => ({ key: t.key, seedVersion: t.seedVersion })), ) } catch { stale = [] } if (stale.length) { log.info('customized module templates have a newer shipped default', { owner, keys: stale.map((t) => t.key), }) } return { ...counts, stale: stale.map((t) => t.key) } } /** * Seed one named rule group, once, under its own guard. * * Mirrors `coreRules.seedGroup` deliberately, including the claim-before-insert * ordering and what it costs: re-running would duplicate the rules that DID * insert, and a duplicate rule is two mails per event — worse than the one * missing rule an operator can add from the Rules screen. The guard is taken * atomically for the same reason; see the comment at the claim. */ async function seedRuleGroup(owner, group, deps = {}) { const rules_ = deps.rulesDb || rulesDb const settings_ = deps.settingsDb || settingsDb const summary = { inserted: 0, skipped: 0 } const key = guardKey(owner, group.key) try { // **Claim BEFORE inserting, not after.** The guard used to be a `get()` here // and a `set()` after the loop, which is not a guard under concurrency: two // processes starting in the same moment both read "absent" and both insert // the whole group. That is not hypothetical — `docker compose up // --scale app=2` and a rolling restart both boot two instances deliberately, // and Phase 13's acceptance walk hit it with two, ending up with 52 module // rules where the module ships 26. `claim()` is an `INSERT IGNORE` reporting // its own `affectedRows`, so exactly one caller wins. // // The cost is the one this function already accepted below: a process that // dies mid-loop leaves the group stamped and partly seeded, and the missing // rules are an operator's visit to the "new rule" form. Duplicates are the // worse failure — two mails per event, for every rule in the group — which // is why the order is this way round rather than the other. if (!(await settings_.claim(key, new Date().toISOString()))) { return { ...summary, skipped: group.rules.length } } for (const rule of group.rules) { try { await rules_.insert(rule) summary.inserted += 1 } catch (err) { log.error('module rule seed failed', { owner, group: group.key, trigger: rule.trigger_id, message: err.message, }) } } if (summary.inserted) { log.info('seeded module engagement rules, all disabled', { owner, group: group.key, rules: summary.inserted, note: group.note || undefined, }) } } catch (err) { log.error('module rule group seeding failed', { owner, group: group.key, message: err.message }) } return summary } /** * Seed every registered module's engagement content. * * @param {object} [deps] * @param {Function} [deps.seeds] () => [{ owner, templates, ruleGroups }] * @param {Set} [deps.skip] owners not to seed (disabled or failed) * @param {object} [deps.templatesDb] / [deps.rulesDb] / [deps.settingsDb] — test seams */ async function seedModuleEngagement({ seeds, skip = new Set(), ...dbs } = {}) { // eslint-disable-next-line global-require const read = seeds || require('../modules/registries').allEngagementSeeds const totals = { templates: 0, rules: 0 } for (const entry of read()) { if (skip.has(entry.owner)) { log.info('skipping engagement seeds for a module that is not booting', { owner: entry.owner }) continue } const t = await seedModuleTemplates(entry.owner, entry.templates || [], dbs) totals.templates += t.inserted + t.updated for (const group of entry.ruleGroups || []) { const r = await seedRuleGroup(entry.owner, group, dbs) totals.rules += r.inserted } log.info('module engagement seeds ensured', { owner: entry.owner, ...t }) } return totals } module.exports = { seedModuleEngagement, seedModuleTemplates, seedRuleGroup, guardKey, }