@coffer-org/server 3.4.0 → 4.0.0

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;
+}

package/dist/uploads.js

@@ -3,6 +3,7 @@ import { writeFile } from 'node:fs/promises';
 import { basename, extname, join } from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
+import { instanceDir } from "./data-dir.js";
 const MIME_EXT = {
     'image/jpeg': '.jpg',
     'image/png': '.png',
@@ -14,9 +15,11 @@ const MIME_EXT = {
     'application/json': '.json',
 };
 export function uploadsDir() {
-    const dir = process.env.UPLOADS ?? join(process.cwd(), 'data', 'uploads');
-    mkdirSync(dir, { recursive: true });
-    return dir;
+    const override = process.env.UPLOADS;
+    if (!override)
+        return instanceDir('uploads');
+    mkdirSync(override, { recursive: true });
+    return override;
 }
 export function seedAsset(absPath) {
     const name = `seed-${basename(absPath)}`;

package/dist/value-compare.d.ts

@@ -0,0 +1 @@
+export declare function sameValue(a: unknown, b: unknown): boolean;

package/dist/value-compare.js

@@ -0,0 +1,7 @@
+export function sameValue(a, b) {
+    if (a instanceof Date && b instanceof Date)
+        return a.getTime() === b.getTime();
+    if (a instanceof Date || b instanceof Date)
+        return false;
+    return a === b;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coffer-org/server",
-  "version": "3.4.0",
+  "version": "4.0.0",
   "type": "module",
   "engines": {
     "node": ">=24"
@@ -13,6 +13,18 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./orchestrator": {
+      "types": "./dist/orchestrator/index.d.ts",
+      "default": "./dist/orchestrator/index.js"
+    },
+    "./mcp": {
+      "types": "./dist/mcp-contract/tools.d.ts",
+      "default": "./dist/mcp-contract/tools.js"
+    },
+    "./mcp/*": {
+      "types": "./dist/mcp-contract/*.d.ts",
+      "default": "./dist/mcp-contract/*.js"
+    },
     "./*": {
       "types": "./dist/*.d.ts",
       "default": "./dist/*.js"
@@ -24,8 +36,7 @@
     "postpack": "node ../../scripts/swap-exports.mjs src"
   },
   "dependencies": {
-    "@coffer-org/core": "^3.3.0",
-    "@coffer-org/sdk": "^3.4.0",
+    "@coffer-org/sdk": "^4.0.0",
     "@extractus/oembed-extractor": "^4.1.0",
     "@fastify/cors": "^11.2.0",
     "@fastify/multipart": "^10.0.0",
@@ -41,5 +52,8 @@
   },
   "optionalDependencies": {
     "@mikro-orm/postgresql": "^7.1.6"
+  },
+  "coffer": {
+    "runtime": "node"
   }
 }