@coffer-org/server 3.3.0 → 4.0.0

package/dist/settings-groups.js

@@ -0,0 +1,25 @@
+import { getPlugins } from "./plugin-runtime.js";
+import { SYSTEM_SETTINGS_ID, SYSTEM_SETTINGS } from "./system-settings.js";
+export { SYSTEM_SETTINGS_ID };
+export function groupsFromPlugins(plugins) {
+    return plugins
+        .filter((p) => p.settings && p.settings.fields.length > 0)
+        .map((p) => ({ id: p.id, label: p.settings.label, fields: p.settings.fields }));
+}
+export function systemSettingsGroup() {
+    return { id: SYSTEM_SETTINGS_ID, label: SYSTEM_SETTINGS.label, fields: SYSTEM_SETTINGS.fields };
+}
+export function groupsWithSystem(plugins) {
+    const fromPlugins = groupsFromPlugins(plugins);
+    const clash = fromPlugins.find((g) => g.id === SYSTEM_SETTINGS_ID);
+    if (clash) {
+        throw new Error(`[settings] a plugin declares settings under the reserved group id '${SYSTEM_SETTINGS_ID}'`);
+    }
+    return [systemSettingsGroup(), ...fromPlugins];
+}
+export async function settingsGroups() {
+    return groupsWithSystem(await getPlugins());
+}
+export async function findSettingsGroup(id) {
+    return (await settingsGroups()).find((g) => g.id === id);
+}

package/dist/settings-write.d.ts

@@ -9,10 +9,10 @@ export interface SettingsFieldInfo {
     options?: string[];
 }
 export declare function describeSettingsFields(fields: LayoutEl[]): SettingsFieldInfo[];
-export declare function buildSettingsBody(pluginId: string, fields: LayoutEl[], incoming: Record<string, unknown>, existing: Record<string, unknown>): Record<string, unknown>;
-export declare function writePluginSettings(em: EntityManager, pluginId: string, incoming: Record<string, unknown>, actor: string, plugins?: PluginManifest[]): Promise<Record<string, unknown>>;
-export declare function listSettings(plugins?: PluginManifest[]): Promise<{
-    plugin: string;
+export declare function buildSettingsBody(groupId: string, fields: LayoutEl[], incoming: Record<string, unknown>, existing: Record<string, unknown>, label?: string): Record<string, unknown>;
+export declare function writePluginSettings(em: EntityManager, groupId: string, incoming: Record<string, unknown>, actor: string, pluginsOverride?: PluginManifest[]): Promise<Record<string, unknown>>;
+export declare function listSettings(pluginsOverride?: PluginManifest[]): Promise<{
+    group: string;
     label: string;
     fields: SettingsFieldInfo[];
     values: Record<string, unknown>;

package/dist/settings-write.js

@@ -1,8 +1,9 @@
 import { fieldEntries, buildZodObject } from '@coffer-org/sdk/shelf';
 import { preserveTree, maskTree } from "./field-masking.js";
 import { ValidationError, NotFoundError, toIssue } from "./mutate.js";
-import { getPlugins, getPluginSettings } from "./plugin-runtime.js";
+import { getPluginSettings } from "./plugin-runtime.js";
 import { invalidatePublicUrlCache } from "./public-url.js";
+import { groupsFromPlugins, settingsGroups, findSettingsGroup, SYSTEM_SETTINGS_ID } from "./settings-groups.js";
 export function describeSettingsFields(fields) {
     return fieldEntries(fields).map(([key, f]) => ({
         key,
@@ -12,38 +13,35 @@ export function describeSettingsFields(fields) {
         ...(f.options ? { options: f.options.map((o) => o.value) } : {}),
     }));
 }
-function settingsShelf(pluginId, fields) {
-    return { library: '_settings', shelf: pluginId, label: `${pluginId}.plugin.label`, fields };
+function settingsShelf(groupId, fields, label = `${groupId}.plugin.label`) {
+    return { library: '_settings', shelf: groupId, label, fields };
 }
-export function buildSettingsBody(pluginId, fields, incoming, existing) {
+export function buildSettingsBody(groupId, fields, incoming, existing, label) {
     const body = preserveTree(fields, incoming, existing);
-    const parsed = buildZodObject(settingsShelf(pluginId, fields)).safeParse(body);
+    const parsed = buildZodObject(settingsShelf(groupId, fields, label)).safeParse(body);
     if (!parsed.success)
         throw new ValidationError(parsed.error.issues.map(toIssue));
     return parsed.data;
 }
-function withSettings(plugins) {
-    return plugins.filter((p) => p.settings && p.settings.fields.length > 0);
-}
-export async function writePluginSettings(em, pluginId, incoming, actor, plugins) {
-    const all = plugins ?? (await getPlugins());
-    const p = all.find((x) => x.id === pluginId);
-    if (!p || !p.settings || p.settings.fields.length === 0) {
+export async function writePluginSettings(em, groupId, incoming, actor, pluginsOverride) {
+    const group = pluginsOverride
+        ? groupsFromPlugins(pluginsOverride).find((g) => g.id === groupId)
+        : await findSettingsGroup(groupId);
+    if (!group)
         throw new NotFoundError();
-    }
-    const fields = p.settings.fields;
-    const existing = await getPluginSettings(pluginId);
-    const data = buildSettingsBody(pluginId, fields, incoming, existing);
-    const row = { plugin_id: pluginId, ...data };
-    await em.upsert(`_settings__${pluginId}`, row);
-    if (pluginId === 'core')
+    const fields = group.fields;
+    const existing = await getPluginSettings(groupId);
+    const data = buildSettingsBody(groupId, fields, incoming, existing, group.label);
+    const row = { plugin_id: groupId, ...data };
+    await em.upsert(`_settings__${groupId}`, row);
+    if (groupId === SYSTEM_SETTINGS_ID)
         invalidatePublicUrlCache();
     const masked = maskTree(fields, row);
     em.create('_Event', {
         ts: new Date().toISOString(),
         actor,
         op: 'settings',
-        type: pluginId,
+        type: groupId,
         record_id: null,
         before: JSON.stringify(maskTree(fields, existing)),
         after: JSON.stringify(masked),
@@ -51,13 +49,12 @@ export async function writePluginSettings(em, pluginId, incoming, actor, plugins
     await em.flush();
     return masked;
 }
-export async function listSettings(plugins) {
-    const all = withSettings(plugins ?? (await getPlugins()));
+export async function listSettings(pluginsOverride) {
+    const groups = pluginsOverride ? groupsFromPlugins(pluginsOverride) : await settingsGroups();
     const out = [];
-    for (const p of all) {
-        const fields = p.settings.fields;
-        const values = maskTree(fields, await getPluginSettings(p.id));
-        out.push({ plugin: p.id, label: p.settings.label, fields: describeSettingsFields(fields), values });
+    for (const g of groups) {
+        const values = maskTree(g.fields, await getPluginSettings(g.id));
+        out.push({ group: g.id, label: g.label, fields: describeSettingsFields(g.fields), values });
     }
     return out;
 }

package/dist/system-settings.d.ts

@@ -0,0 +1,3 @@
+import { type SettingsDef } from '@coffer-org/sdk/settings';
+export declare const SYSTEM_SETTINGS_ID = "system";
+export declare const SYSTEM_SETTINGS: SettingsDef;

package/dist/system-settings.js

@@ -0,0 +1,27 @@
+import { field } from '@coffer-org/sdk/fields';
+import { defineSettings } from '@coffer-org/sdk/settings';
+export const SYSTEM_SETTINGS_ID = 'system';
+export const SYSTEM_SETTINGS = defineSettings({
+    label: 'core.settings.label',
+    fields: {
+        publicUrl: field.string({
+            label: 'core.settings.publicUrl',
+            rules: { pattern: '^https?://[^/\\s]+/?$', messageKey: 'core.settings.publicUrlHint' },
+        }),
+        language: field.string({
+            label: 'core.settings.language',
+            default: 'uk',
+            strict: true,
+            view: { noSearch: true },
+            options: [
+                { value: 'uk', title: 'Українська' },
+                { value: 'ru', title: 'Русский' },
+                { value: 'en', title: 'English' },
+            ],
+        }),
+        agent_id: field.string({ label: 'core.settings.agent_id', strict: true, view: { noSearch: true } }),
+        access_password: field.password({ label: 'core.settings.access_password' }),
+        trigger_prefix: field.string({ label: 'core.settings.trigger_prefix' }),
+        reply_window: field.int({ label: 'core.settings.reply_window', default: 1800 }),
+    },
+});

package/dist/thread-store.d.ts

@@ -1,6 +1,7 @@
+export declare const SIDECAR_ROLES: readonly ["reasoning", "suggestions"];
 export interface StoredMsg {
     msgId: string;
-    role: 'user' | 'assistant' | 'reasoning';
+    role: 'user' | 'assistant' | 'reasoning' | 'suggestions';
     sender: string | null;
     text: string;
     attachments?: StoredAttachment[];
@@ -24,7 +25,7 @@ export declare function putThreadMessage(m: {
     connector: string;
     chatId: string;
     msgId: string;
-    role: 'user' | 'assistant' | 'reasoning';
+    role: 'user' | 'assistant' | 'reasoning' | 'suggestions';
     sender?: string | null;
     attachments?: StoredAttachment[];
     text: string;

package/dist/thread-store.js

@@ -1,4 +1,5 @@
 import { getEm } from "./db.js";
+export const SIDECAR_ROLES = ['reasoning', 'suggestions'];
 function toStored(r) {
     let attachments;
     if (r.attachments) {
@@ -49,12 +50,12 @@ export async function pruneThreadMessages(connector, cutoffTs) {
 }
 export async function listThreadMessages(connector, chatId, limit = 200) {
     const em = getEm().fork();
-    const visible = (await em.find('_ThreadMessage', { connector, chat_id: chatId, role: { $ne: 'reasoning' } }, { orderBy: { ts: 'desc', msg_id: 'desc' }, limit }));
+    const visible = (await em.find('_ThreadMessage', { connector, chat_id: chatId, role: { $nin: SIDECAR_ROLES } }, { orderBy: { ts: 'desc', msg_id: 'desc' }, limit }));
     const oldest = visible.at(-1)?.ts;
-    const reasoning = oldest === undefined
+    const sidecars = oldest === undefined
         ? []
-        : (await em.find('_ThreadMessage', { connector, chat_id: chatId, role: 'reasoning', ts: { $gte: oldest - 1 } }, { orderBy: { ts: 'desc', msg_id: 'desc' } }));
-    return [...visible, ...reasoning]
+        : (await em.find('_ThreadMessage', { connector, chat_id: chatId, role: { $in: SIDECAR_ROLES }, ts: { $gte: oldest - 1 } }, { orderBy: { ts: 'desc', msg_id: 'desc' } }));
+    return [...visible, ...sidecars]
         .sort((a, b) => b.ts - a.ts || (a.msg_id < b.msg_id ? 1 : a.msg_id > b.msg_id ? -1 : 0))
         .reverse()
         .map(toStored);
@@ -69,7 +70,7 @@ export async function listThreadChats(connector, chatIdPrefix) {
     const rows = (await em.find('_ThreadMessage', { connector, chat_id: { $gte: chatIdPrefix, $lt: upper } }, { orderBy: { ts: 'asc' } }));
     const byChat = new Map();
     for (const r of rows) {
-        if (r.role === 'reasoning')
+        if (SIDECAR_ROLES.includes(r.role))
             continue;
         const cur = byChat.get(r.chat_id);
         if (!cur) {

package/dist/trigger-queue.d.ts

@@ -0,0 +1,33 @@
+import { type LayoutEl } from '@coffer-org/sdk/fields';
+import type { MutateTarget } from '@coffer-org/sdk/mutate-path';
+import { type MutateGraph } from '@coffer-org/sdk/mutate-graph';
+import { type Row } from './compute-unit.ts';
+import { type PartCtx } from './part-injection.ts';
+export declare class TriggerQueueOverflowError extends Error {
+}
+export declare class TriggerRecordCapError extends Error {
+}
+export interface TouchedRecord {
+    library: string;
+    shelf: string;
+    id: number;
+    changed: string[];
+}
+interface CrossRecordState {
+    visited: Set<string>;
+    cap: number;
+    touched?: TouchedRecord[];
+}
+export interface ChangedField {
+    path: string[];
+}
+export declare function changedFields(before: Row, after: Row, fields: LayoutEl[]): ChangedField[];
+export declare function allUnitPaths(fields: LayoutEl[], scope?: string[]): string[][];
+export declare function runTriggers(fields: LayoutEl[], row: Row, changed: ChangedField[], graph: MutateGraph, shelfKey: string, ctx: PartCtx, opts?: {
+    seedAll?: boolean;
+    seedTargets?: MutateTarget[];
+    crossRecordState?: CrossRecordState;
+    recordCap?: number;
+    touched?: TouchedRecord[];
+}): Promise<Row>;
+export {};

package/dist/trigger-queue.js

@@ -0,0 +1,432 @@
+import { hasChildren, isNamedField, isCollectionGroup, isJsonStored, } from '@coffer-org/sdk/fields';
+import { fieldEntries } from '@coffer-org/sdk/shelf';
+import { newScope, childScope, runFieldUnit, isPlainObject, isComputeUnit, isGroupUnit, } from "./compute-unit.js";
+import { newPartMemo } from "./part-injection.js";
+import { sameValue } from "./value-compare.js";
+import { getShelf } from "./registry-context.js";
+import { shelfTableName } from "./entity-schema.js";
+import { selectRows } from "./read-rows.js";
+import { decodeTemporal, encodeTemporal } from "./temporal.js";
+import { nestEmbedded, flattenEmbedded, readCollections, writeCollections, splitCollections } from "./collection-io.js";
+const MAX_UNIT_COMPUTATIONS = 10_000;
+export class TriggerQueueOverflowError extends Error {
+}
+const MAX_TOUCHED_RECORDS = 1000;
+export class TriggerRecordCapError extends Error {
+}
+function readHop(row, fields, hop, i) {
+    const seg = hop[i];
+    for (const el of fields) {
+        if (isNamedField(el)) {
+            if (el.key !== seg)
+                continue;
+            return el.type.relation ? [{ value: row[seg], relation: el.type.relation }] : [];
+        }
+        if (hasChildren(el)) {
+            const sub = el.fields;
+            if (!el.key) {
+                const found = readHop(row, sub, hop, i);
+                if (found.length)
+                    return found;
+                continue;
+            }
+            if (el.key !== seg)
+                continue;
+            if (isCollectionGroup(el)) {
+                const rows = Array.isArray(row[seg]) ? row[seg] : [];
+                return rows.flatMap((r) => (isPlainObject(r) ? readHop(r, sub, hop, i + 1) : []));
+            }
+            const child = row[seg];
+            return isPlainObject(child) ? readHop(child, sub, hop, i + 1) : [];
+        }
+    }
+    return [];
+}
+function idsOf(value) {
+    if (Array.isArray(value))
+        return value.filter((v) => Number.isInteger(v) && v > 0);
+    return Number.isInteger(value) && value > 0 ? [value] : [];
+}
+async function loadRecords(em, m, ids) {
+    const table = shelfTableName(m.library, m.shelf);
+    const flats = (await selectRows(em, table, { id: { $in: ids }, deleted_at: null }));
+    const out = new Map();
+    for (const flat of flats) {
+        const id = Number(flat['id']);
+        const nested = nestEmbedded(m, decodeTemporal(m, flat));
+        const collections = await readCollections(em, m, id);
+        out.set(id, { ...nested, ...collections });
+    }
+    return out;
+}
+async function resolveHopChain(em, startRow, startFields, hops) {
+    let current = [{ row: startRow, fields: startFields }];
+    let loaded = [];
+    for (const hop of hops) {
+        const byShelf = new Map();
+        for (const cur of current) {
+            for (const match of readHop(cur.row, cur.fields, hop, 0)) {
+                const m = getShelf(match.relation.library, match.relation.shelf);
+                if (!m)
+                    continue;
+                const key = `${match.relation.library}/${match.relation.shelf}`;
+                let entry = byShelf.get(key);
+                if (!entry) {
+                    entry = { m, ids: new Set() };
+                    byShelf.set(key, entry);
+                }
+                for (const id of idsOf(match.value))
+                    entry.ids.add(id);
+            }
+        }
+        loaded = [];
+        for (const { m, ids } of byShelf.values()) {
+            if (!ids.size)
+                continue;
+            const rows = await loadRecords(em, m, [...ids]);
+            for (const [id, row] of rows)
+                loaded.push({ m, row, id });
+        }
+        current = loaded.map((l) => ({ row: l.row, fields: l.m.fields }));
+    }
+    return loaded;
+}
+function encodeJsonForWrite(fields, data) {
+    const out = { ...data };
+    for (const [k, fm] of fieldEntries(fields)) {
+        if (isJsonStored(fm) && out[k] !== null && out[k] !== undefined && typeof out[k] === 'object') {
+            out[k] = JSON.stringify(out[k]);
+        }
+    }
+    return out;
+}
+async function runCrossRecordTarget(target, rootRow, rootFields, graph, ctx, cross) {
+    const em = ctx.em;
+    if (!em)
+        return;
+    const endpoints = await resolveHopChain(em, rootRow, rootFields, target.hops);
+    for (const { m, row, id } of endpoints) {
+        const key = `${m.library}/${m.shelf}#${id}`;
+        if (cross.visited.has(key))
+            continue;
+        cross.visited.add(key);
+        if (cross.visited.size > cross.cap) {
+            throw new TriggerRecordCapError(`[trigger-queue] a cross-record write touched more than ${cross.cap} distinct records in one ` +
+                `transaction (reaching ${m.library}/${m.shelf}#${id}) — a chain of relation hops is not ` +
+                `converging (this guards the runtime cascade; a cycle in the DECLARED graph is rejected at ` +
+                `compose time by buildMutateGraph, so this is not that).`);
+        }
+        const before = row;
+        const after = { ...row };
+        const shelfKeyB = `${m.library}/${m.shelf}`;
+        const triggered = await runTriggers(m.fields, after, [], graph, shelfKeyB, { ...ctx, meta: { library: m.library, shelf: m.shelf }, memo: undefined }, { seedTargets: [{ hops: [], path: target.path, relative: false }], crossRecordState: cross });
+        const changedB = changedFields(before, triggered, m.fields);
+        if (!changedB.length)
+            continue;
+        cross.touched?.push({
+            library: m.library,
+            shelf: m.shelf,
+            id,
+            changed: changedB.map((c) => c.path.join('.')),
+        });
+        const { base, collections } = splitCollections(m, triggered);
+        const dbRow = encodeJsonForWrite(m.fields, encodeTemporal(m, flattenEmbedded(m, base)));
+        await em.upsert(shelfTableName(m.library, m.shelf), { ...dbRow, id });
+        const changedTop = new Set(changedB.map((c) => c.path[0]));
+        const toWrite = {};
+        for (const [k, rows] of Object.entries(collections))
+            if (changedTop.has(k))
+                toWrite[k] = rows;
+        if (Object.keys(toWrite).length)
+            await writeCollections(em, m, id, toWrite);
+    }
+}
+function valuesDiffer(a, b) {
+    if (a instanceof Date || b instanceof Date)
+        return !sameValue(a, b);
+    if (Array.isArray(a) || Array.isArray(b)) {
+        if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length)
+            return true;
+        return a.some((v, i) => valuesDiffer(v, b[i]));
+    }
+    if (isPlainObject(a) && isPlainObject(b)) {
+        const av = a;
+        const bv = b;
+        const keys = new Set([...Object.keys(av), ...Object.keys(bv)]);
+        for (const k of keys)
+            if (valuesDiffer(av[k], bv[k]))
+                return true;
+        return false;
+    }
+    return !sameValue(a, b);
+}
+export function changedFields(before, after, fields) {
+    const out = [];
+    collectChanges(before, after, fields, out);
+    return out;
+}
+function asRow(v) {
+    return isPlainObject(v) ? v : {};
+}
+function collectChanges(before, after, fields, out) {
+    for (const el of fields) {
+        if (isNamedField(el)) {
+            const key = el.key;
+            if (el.type.parts?.length) {
+                const bObj = asRow(before[key]);
+                const aObj = asRow(after[key]);
+                for (const p of el.type.parts) {
+                    if (valuesDiffer(bObj[p.key], aObj[p.key]))
+                        out.push({ path: [key, p.key] });
+                }
+            }
+            else if (valuesDiffer(before[key], after[key])) {
+                out.push({ path: [key] });
+            }
+        }
+        else if (hasChildren(el)) {
+            const sub = el.fields;
+            if (!el.key) {
+                collectChanges(before, after, sub, out);
+            }
+            else if (isCollectionGroup(el)) {
+                const bRows = Array.isArray(before[el.key]) ? before[el.key] : [];
+                const aRows = Array.isArray(after[el.key]) ? after[el.key] : [];
+                if (bRows.length !== aRows.length)
+                    out.push({ path: [el.key] });
+                const rowKeys = new Set();
+                const n = Math.min(bRows.length, aRows.length);
+                for (let i = 0; i < n; i++) {
+                    const rowOut = [];
+                    collectChanges(asRow(bRows[i]), asRow(aRows[i]), sub, rowOut);
+                    for (const c of rowOut)
+                        rowKeys.add(c.path.join(''));
+                }
+                for (const s of rowKeys)
+                    out.push({ path: [el.key, ...s.split('')] });
+            }
+            else {
+                const subOut = [];
+                collectChanges(asRow(before[el.key]), asRow(after[el.key]), sub, subOut);
+                for (const c of subOut)
+                    out.push({ path: [el.key, ...c.path] });
+            }
+        }
+    }
+}
+function markDone(scope) {
+    for (const key of scope.units.keys())
+        scope.status.set(key, 'done');
+    return scope;
+}
+const rowScopesCache = new WeakMap();
+function rowScopesOf(scope, key, sub) {
+    let byKey = rowScopesCache.get(scope);
+    if (!byKey) {
+        byKey = new Map();
+        rowScopesCache.set(scope, byKey);
+    }
+    const cached = byKey.get(key);
+    if (cached)
+        return cached;
+    const rows = scope.obj[key];
+    const arr = Array.isArray(rows) ? rows : [];
+    const copies = arr.map((r) => (isPlainObject(r) ? { ...r } : r));
+    scope.obj[key] = copies;
+    const scopes = [];
+    copies.forEach((r, i) => {
+        if (!isPlainObject(r))
+            return;
+        scopes.push(markDone(newScope(scope.st, r, sub, [...scope.path, key, i], null, `collection row '${key}'`)));
+    });
+    byKey.set(key, scopes);
+    return scopes;
+}
+function locateUnits(scope, fields, path, i, materialized) {
+    const seg = path[i];
+    const last = i === path.length - 1;
+    for (const el of fields) {
+        if (isNamedField(el)) {
+            if (el.key !== seg)
+                continue;
+            return [{ scope, key: el.key, fm: el.type }];
+        }
+        if (hasChildren(el)) {
+            const sub = el.fields;
+            if (!el.key) {
+                const found = locateUnits(scope, sub, path, i, materialized);
+                if (found.length)
+                    return found;
+                continue;
+            }
+            if (el.key !== seg)
+                continue;
+            if (last)
+                return el.compute !== undefined ? [{ scope, key: el.key, fm: el }] : [];
+            if (isCollectionGroup(el)) {
+                const rows = rowScopesOf(scope, el.key, sub);
+                return rows.flatMap((row) => locateUnits(row, sub, path, i + 1, materialized));
+            }
+            let child = childScope(scope, el.key);
+            if (!child) {
+                child = newScope(scope.st, {}, sub, [...scope.path, el.key], scope.level, scope.level.label);
+                scope.obj[el.key] = child.obj;
+                scope.groups.set(el.key, child);
+                materialized.push({ parent: scope, key: el.key });
+            }
+            markDone(child);
+            return locateUnits(child, sub, path, i + 1, materialized);
+        }
+    }
+    return [];
+}
+function isPathPrefix(prefix, path) {
+    return prefix.length <= path.length && prefix.every((seg, i) => path[i] === seg);
+}
+function edgesFrom(graph, shelfKey, path) {
+    return (graph.get(shelfKey) ?? []).filter((e) => isPathPrefix(path, e.from));
+}
+function movedNodes(item, before, after) {
+    if (isGroupUnit(item.fm)) {
+        const base = item.path;
+        const out = [];
+        if (valuesDiffer(before, after))
+            out.push(base);
+        if (!isCollectionGroup(item.fm)) {
+            const b = isPlainObject(before) ? before : {};
+            const a = isPlainObject(after) ? after : {};
+            for (const child of item.fm.fields) {
+                if (isNamedField(child) && valuesDiffer(b[child.key], a[child.key]))
+                    out.push([...base, child.key]);
+            }
+        }
+        return out;
+    }
+    const parts = item.fm.parts;
+    const lastSeg = item.path[item.path.length - 1];
+    const base = parts?.some((p) => p.key === lastSeg) ? item.path.slice(0, -1) : item.path;
+    const out = [];
+    if (valuesDiffer(before, after))
+        out.push(base);
+    if (parts?.length) {
+        const b = isPlainObject(before) ? before : {};
+        const a = isPlainObject(after) ? after : {};
+        for (const p of parts)
+            if (valuesDiffer(b[p.key], a[p.key]))
+                out.push([...base, p.key]);
+    }
+    return out;
+}
+export function allUnitPaths(fields, scope = []) {
+    const out = [];
+    for (const el of fields) {
+        if (isNamedField(el)) {
+            if (isComputeUnit(el.type))
+                out.push([...scope, el.key]);
+        }
+        else if (hasChildren(el)) {
+            const p = el.key ? [...scope, el.key] : scope;
+            if (el.key && el.compute !== undefined)
+                out.push(p);
+            out.push(...allUnitPaths(el.fields, p));
+        }
+    }
+    return out;
+}
+function declaresCache(fm) {
+    return fm.cache !== undefined || (fm.parts?.some((p) => p.meta.cache !== undefined) ?? false);
+}
+function cacheUnitPaths(fields, scope = []) {
+    const out = [];
+    for (const el of fields) {
+        if (isNamedField(el)) {
+            if (isComputeUnit(el.type) && declaresCache(el.type))
+                out.push([...scope, el.key]);
+        }
+        else if (hasChildren(el)) {
+            out.push(...cacheUnitPaths(el.fields, el.key ? [...scope, el.key] : scope));
+        }
+    }
+    return out;
+}
+export async function runTriggers(fields, row, changed, graph, shelfKey, ctx, opts = {}) {
+    const id = row['id'] ?? row['base_id'];
+    const st = {
+        ctx,
+        mode: 'write',
+        memo: ctx.memo ?? newPartMemo(),
+        refs: ctx.refs ?? null,
+        selfKey: typeof id === 'number' ? `${ctx.meta.library}/${ctx.meta.shelf}#${id}` : null,
+        recordLevel: null,
+        now: ctx.now ?? new Date().toISOString(),
+    };
+    const root = markDone(newScope(st, { ...row }, fields, [], null, shelfKey));
+    st.recordLevel = root.level;
+    const queue = [];
+    const pending = new Set();
+    const materialized = [];
+    const cross = opts.crossRecordState ?? {
+        visited: new Set(),
+        cap: opts.recordCap ?? MAX_TOUCHED_RECORDS,
+        ...(opts.touched ? { touched: opts.touched } : {}),
+    };
+    const enqueue = async (target) => {
+        if (target.hops.length > 0) {
+            await runCrossRecordTarget(target, root.obj, fields, graph, ctx, cross);
+            return;
+        }
+        for (const unit of locateUnits(root, fields, target.path, 0, materialized)) {
+            const dedupeKey = `${unit.scope.uid}:${unit.key}`;
+            if (pending.has(dedupeKey))
+                continue;
+            pending.add(dedupeKey);
+            queue.push({ scope: unit.scope, key: unit.key, fm: unit.fm, path: target.path, dedupeKey });
+        }
+    };
+    if (opts.seedAll) {
+        for (const path of allUnitPaths(fields))
+            await enqueue({ hops: [], path, relative: false });
+    }
+    else if (opts.seedTargets) {
+        for (const target of opts.seedTargets)
+            await enqueue(target);
+    }
+    else {
+        for (const path of cacheUnitPaths(fields))
+            await enqueue({ hops: [], path, relative: false });
+    }
+    for (const c of changed) {
+        await enqueue({ hops: [], path: c.path, relative: false });
+        for (const edge of edgesFrom(graph, shelfKey, c.path))
+            await enqueue(edge.to);
+    }
+    let computations = 0;
+    while (queue.length > 0) {
+        const wave = queue.splice(0, queue.length);
+        for (const item of wave)
+            pending.delete(item.dedupeKey);
+        computations += wave.length;
+        if (computations > MAX_UNIT_COMPUTATIONS) {
+            throw new TriggerQueueOverflowError(`[trigger-queue] ${shelfKey}: more than ${MAX_UNIT_COMPUTATIONS} unit computations in one drain — ` +
+                `a compute function is not converging (this guards the runtime queue; a cycle in the DECLARED ` +
+                `graph is rejected at compose time by buildMutateGraph, so this is not that).`);
+        }
+        const movedPerItem = await Promise.all(wave.map(async (item) => {
+            const before = item.scope.obj[item.key];
+            await runFieldUnit(item.scope, item.key, item.fm);
+            return movedNodes(item, before, item.scope.obj[item.key]);
+        }));
+        for (const nodes of movedPerItem) {
+            for (const node of nodes) {
+                for (const edge of edgesFrom(graph, shelfKey, node))
+                    await enqueue(edge.to);
+            }
+        }
+    }
+    for (const g of materialized) {
+        const obj = g.parent.obj[g.key];
+        if (isPlainObject(obj) && Object.keys(obj).length === 0)
+            delete g.parent.obj[g.key];
+    }
+    return root.obj;
+}