@anteros/core 0.0.41 → 0.0.44

package/database/audit.ts

@@ -1,7 +1,7 @@
 import type { Db } from "mongodb";
 import { cfg } from "../server/config";
 import type { Tenant } from "../types/tenant";
-import { parseDuration } from "../utils/func";
+import { syncTtlRetention, type RetentionResult } from "./ttl";
 
 /**
  * Collection holding the audit trail — one document per database operation
@@ -35,8 +35,6 @@ const AUDIT_INDEXES: { name: string; key: Record<string, 1 | -1> }[] = [
     { name: '_audit_trace_', key: { 'trace.id': 1 } },
 ]
 
-type RetentionResult = 'applied' | 'dropped' | 'unchanged' | 'skipped'
-
 /**
  * One-off migration: `_activities_` → `_audit_`.
  *
@@ -90,67 +88,19 @@ async function ensureAuditIndexes(db: Db): Promise<string[]> {
 }
 
 /**
- * Declarative retention (MongoDB TTL on `ts`):
+ * Declarative retention (MongoDB TTL on `ts`) — shared TTL helper:
  * - duration string (`'90d'`, `'24h'`) → ensure the TTL index with that expiry
  * - `false`                            → explicitly disabled: drop the TTL index
  * - omitted                            → untouched (entries are kept forever)
  */
 async function syncAuditRetention(db: Db, retention?: string | false): Promise<RetentionResult> {
-    if (retention === undefined) return 'skipped'
-
-    const col: any = db.collection(AUDIT_COLLECTION)
-
-    try {
-        const existing = (await col.listIndexes().toArray())
-            .find((index: any) => index.name === AUDIT_TTL_INDEX)
-
-        if (retention === false) {
-            if (!existing) return 'unchanged'
-            await col.dropIndex(AUDIT_TTL_INDEX)
-            console.log(`🧹 Audit retention disabled — ${AUDIT_TTL_INDEX} dropped`)
-            return 'dropped'
-        }
-
-        const parsed = parseDuration(retention)
-        if (parsed === null) {
-            console.error(`Invalid audit retention '${retention}' — expected a duration like '90d' or '24h'`)
-            return 'skipped'
-        }
-        const expireAfterSeconds = Math.round(parsed / 1000)
-
-        if (!existing) {
-            await col.createIndex({ ts: 1 }, {
-                name: AUDIT_TTL_INDEX,
-                expireAfterSeconds,
-                background: true,
-            })
-            console.log(`🧹 Audit retention enabled — entries expire after ${retention}`)
-            return 'applied'
-        }
-
-        if (existing.expireAfterSeconds === expireAfterSeconds) return 'unchanged'
-
-        // `expireAfterSeconds` cannot be updated through createIndex: collMod does it
-        // instantly, dropping/recreating the index is only a fallback for older servers
-        try {
-            await db.command({
-                collMod: AUDIT_COLLECTION,
-                index: { name: AUDIT_TTL_INDEX, expireAfterSeconds },
-            })
-        } catch {
-            await col.dropIndex(AUDIT_TTL_INDEX)
-            await col.createIndex({ ts: 1 }, {
-                name: AUDIT_TTL_INDEX,
-                expireAfterSeconds,
-                background: true,
-            })
-        }
-        console.log(`🧹 Audit retention updated — entries expire after ${retention}`)
-        return 'applied'
-    } catch (err: any) {
-        console.error(`Audit retention failed (${retention})`, err?.message)
-        return 'skipped'
-    }
+    return syncTtlRetention(db, {
+        collection: AUDIT_COLLECTION,
+        index: AUDIT_TTL_INDEX,
+        field: 'ts',
+        retention,
+        label: 'Audit',
+    })
 }
 
 /**

package/database/collection.ts

@@ -5,6 +5,7 @@ import fs from "fs/promises"
 import type { Collection } from "../types/collection"
 import type { IndexDescription } from "mongodb"
 import type { Field } from "../types/field"
+import { importDefinition } from "../lib/load"
 import { getTenant } from "./tenant"
 import { buildSchema } from "./schema"
 import type { FileCollection } from "../types/file"
@@ -38,7 +39,8 @@ async function syncCollections() {
             if (isDirectory) {
                 const glob = new Glob(path.join(COLLECTIONS_PATH, '**/*.model.ts'))
                 for await (let file of glob.scan('.')) {
-                    let collectionModule = await import(file)
+                    // A broken model file is skipped, never fatal for the others
+                    let collectionModule = await importDefinition(file, 'collection')
                     if (collectionModule?.default?._isCollection_) {
                         collections.push({
                             ...collectionModule?.default,

package/database/deleteLog.ts

@@ -1,14 +1,78 @@
 import type { Db } from "mongodb";
+import { cfg } from "../server/config";
+import type { ReplicationMetaName } from "../types/replication";
 
 /** Collection holding the replication state (`_replication_`). */
 const MARKERS = "_replication_";
 
+/** Meta collection slug → the name `replication.exclude` knows it by. */
+const META_BY_SLUG: Record<string, ReplicationMetaName> = {
+    [MARKERS]: "replication",
+    _audit_: "audit",
+    _workflows_: "workflows",
+    _locks_: "locks",
+    _vars_: "vars",
+};
+
+/** Replication is armed: enabled, with at least one usable destination. */
+function replicationReady(tenantId: string): boolean {
+    const tenant: any = (cfg.tenants ?? []).find((candidate) => candidate.id === tenantId);
+    const replication = tenant?.replication;
+
+    if (!replication || replication.enabled === false) return false;
+    return (replication.destinations ?? []).some((destination: any) =>
+        destination?.enabled !== false && destination?.id && destination?.uri);
+}
+
+/** `replication.exclude` names this collection. */
+function isExcluded(tenantId: string, name: string): boolean {
+    const tenant: any = (cfg.tenants ?? []).find((candidate) => candidate.id === tenantId);
+    return (tenant?.replication?.exclude ?? []).includes(name);
+}
+
+/**
+ * Whether the framework replicates a **meta** collection (`_audit_`, `_vars_`…)
+ * for this tenant.
+ */
+function replicatesMetaCollection(tenantId: string, name: ReplicationMetaName): boolean {
+    return replicationReady(tenantId) && !isExcluded(tenantId, name);
+}
+
+/**
+ * The same question, by **collection slug** — used by the stores that delete on
+ * their own instead of going through the collection hooks (agent memory, and the
+ * variables / file paths mirror this).
+ *
+ * It answers exactly what `replicatedCollectionsFor()` would: a meta collection,
+ * an agent memory collection (`exclude: ['memory']` covers them all — the tenant
+ * names them), or a declared collection that opted in. A collection nobody
+ * replicates gets no tombstone: it would never be flushed and would only pile up
+ * in `_replication_`.
+ */
+function replicatesCollection(tenantId: string, slug: string): boolean {
+    const asMeta = META_BY_SLUG[slug];
+    if (asMeta) return replicatesMetaCollection(tenantId, asMeta);
+    if (!replicationReady(tenantId)) return false;
+
+    const isAgentMemory = (cfg.agentMemories ?? [])
+        .some((memory) => memory._tenant_ === tenantId && memory.collection === slug);
+    if (isAgentMemory) return !isExcluded(tenantId, "memory");
+
+    const declared = [...(cfg.collections ?? []), ...(cfg.fileCollections ?? [])]
+        .some((collection: any) =>
+            collection._tenant_ === tenantId
+            && collection.slug === slug
+            && collection.replication?.enabled);
+
+    return declared && !isExcluded(tenantId, slug);
+}
+
 /**
  * Upsert delete tombstones consumed by the replication engine.
  *
  * Some collections bypass the collection hooks when deleting (variables,
- * file-collection documents) — those paths call this directly so their
- * deletions still propagate to the destinations.
+ * agent memory, file-collection documents) — those paths call this directly so
+ * their deletions still propagate to the destinations.
  */
 async function writeDeleteMarkers(
     db: Db,
@@ -31,4 +95,4 @@ async function writeDeleteMarkers(
     await db.collection(MARKERS).bulkWrite(ops as any, { ordered: false }).catch(() => { /* ignore */ });
 }
 
-export { writeDeleteMarkers };
+export { writeDeleteMarkers, replicatesMetaCollection, replicatesCollection };

package/database/file.ts

@@ -4,6 +4,7 @@ import path from "path"
 import fs from "fs/promises"
 import type { FileCollection } from "../types/file"
 import { getTenant } from "./tenant"
+import { importDefinition } from "../lib/load"
 import type { IndexDescription } from "mongodb"
 
 async function syncFileCollections() {
@@ -18,7 +19,7 @@ async function syncFileCollections() {
             if (filesExist && (await fs.stat(FILES_PATH)).isDirectory()) {
                 const globFiles = new Glob(path.join(FILES_PATH, '**/*.file.ts'))
                 for await (let file of globFiles.scan('.')) {
-                    let fileModule = await import(file)
+                    let fileModule = await importDefinition(file, 'file collection')
                     if (fileModule?.default?._isFileCollection_) {
                         fileCollections.push({
                             ...fileModule?.default,
@@ -30,7 +31,7 @@ async function syncFileCollections() {
                 // Also scan *.model.ts in files/ with _isFileCollection_
                 const globModels = new Glob(path.join(FILES_PATH, '**/*.model.ts'))
                 for await (let file of globModels.scan('.')) {
-                    let fileModule = await import(file)
+                    let fileModule = await importDefinition(file, 'file collection')
                     if (fileModule?.default?._isFileCollection_) {
                         fileCollections.push({
                             ...fileModule?.default,
@@ -46,7 +47,7 @@ async function syncFileCollections() {
             if (collectionsExist && (await fs.stat(COLLECTIONS_PATH)).isDirectory()) {
                 const globFiles = new Glob(path.join(COLLECTIONS_PATH, '**/*.file.ts'))
                 for await (let file of globFiles.scan('.')) {
-                    let fileModule = await import(file)
+                    let fileModule = await importDefinition(file, 'file collection')
                     if (fileModule?.default?._isFileCollection_) {
                         fileCollections.push({
                             ...fileModule?.default,

package/database/mongodbadapter.ts

@@ -1,6 +1,20 @@
 
 import type { Tenant } from "../types/tenant";
 import type { MongoClientOptions, Db, ClientSession, UpdateOptions, UpdateFilter, Document, DeleteResult, ChangeStreamOptions, ChangeStream, ChangeStreamDocument, AnyBulkWriteOperation, BulkWriteOptions, BulkWriteResult, UpdateResult } from "mongodb";
+
+/**
+ * Is a process still running **on this host**? `EPERM` means it exists but belongs
+ * to another user — which still counts as alive.
+ */
+function isProcessAlive(pid: number): boolean {
+    if (!Number.isInteger(pid) || pid <= 0) return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    } catch (err: any) {
+        return err?.code === 'EPERM';
+    }
+}
 import { MongoClient, ObjectId, AggregationCursor } from "mongodb";
 import type { FindOptions, findOneOptions } from "../types/mongo";
 import type { FindCallOptions } from "../types/mongo";
@@ -28,6 +42,8 @@ import { io } from '../server/io';
 import type { Service } from '../types/service';
 import { createVars } from "./vars";
 import type { TenantVars } from "../types/vars";
+import { createAgents } from "../lib/agents";
+import { createApi } from "../lib/api";
 
 class MongoRest {
     client!: MongoClient;
@@ -163,6 +179,15 @@ class MongoRest {
         return options.data;
     }
 
+    /**
+     * Context handed to a collection hook. `agents` is the tenant-scoped registry,
+     * bound to `this` — so a hook runs an agent exactly like it reads a collection:
+     * `await agents.get('support')?.generate(...)`.
+     */
+    #hookCtx(action: any, meta: any) {
+        return { rest: this, io, action, meta, agents: createAgents(this.tenant_id, this), api: createApi(this) };
+    }
+
     async #logActivity(data: {
         action: string,
         collection: string,
@@ -377,7 +402,7 @@ class MongoRest {
                 pipeline = func.toBson(pipeline, { col })
                 const meta: any = { action, collection, pipeline }
                 if (col.hooks?.beforeOperation) {
-                    await col.hooks.beforeOperation({ rest: this, io, action, meta })
+                    await col.hooks.beforeOperation(this.#hookCtx(action, meta))
                 }
 
                 let result = await this.db.collection(collection).aggregate(pipeline, {
@@ -387,7 +412,7 @@ class MongoRest {
                 result = func.toJson(result)
                 meta.result = result
 
-                await col.hooks?.afterOperation?.({ rest: this, io, action, meta })
+                await col.hooks?.afterOperation?.(this.#hookCtx(action, meta))
 
                 return result as any[]
             } catch (err: any) {
@@ -585,7 +610,7 @@ class MongoRest {
 
                     const meta: any = { action, collection, params, options }
                     if (col.hooks?.beforeOperation) {
-                        await col.hooks.beforeOperation({ rest: this, io, action, meta })
+                        await col.hooks.beforeOperation(this.#hookCtx(action, meta))
                     }
 
                     let result = await this.db.collection(collection).aggregate(pipeline, {
@@ -596,7 +621,7 @@ class MongoRest {
                     meta.result = result
 
                     if (col.hooks?.afterOperation) {
-                        await col.hooks.afterOperation({ rest: this, io, action, meta })
+                        await col.hooks.afterOperation(this.#hookCtx(action, meta))
                     }
 
                     return result as any[]
@@ -630,7 +655,7 @@ class MongoRest {
 
                 const meta: any = { action, collection, params, id: _id }
                 if (col.hooks?.beforeOperation) {
-                    await col.hooks.beforeOperation({ rest: this, io, action, meta })
+                    await col.hooks.beforeOperation(this.#hookCtx(action, meta))
                 }
 
                 let result = (await this.db.collection(collection).aggregate(pipeline, {
@@ -641,7 +666,7 @@ class MongoRest {
                 meta.result = result
 
                 if (col.hooks?.afterOperation) {
-                    await col.hooks.afterOperation({ rest: this, io, action, meta })
+                    await col.hooks.afterOperation(this.#hookCtx(action, meta))
                 }
 
                 return result
@@ -665,7 +690,7 @@ class MongoRest {
 
             const meta: any = { action, collection, data }
             if (col.hooks?.beforeOperation) {
-                await col.hooks.beforeOperation({ rest: this, io, action, meta })
+                await col.hooks.beforeOperation(this.#hookCtx(action, meta))
             }
             // Validate AFTER hooks (they may fill required fields or apply Joi defaults)
             meta.data = this._validate({ collection, action: action, data: meta.data })
@@ -681,7 +706,7 @@ class MongoRest {
             const result: T & { _id: string } = { ...func.toJson(meta.data as any), _id: (inserted.insertedId as ObjectId).toHexString() }
             meta.result = result
             if (col?.hooks?.afterOperation) {
-                await col.hooks.afterOperation({ rest: this, io, action, meta })
+                await col.hooks.afterOperation(this.#hookCtx(action, meta))
             }
 
             return result
@@ -708,7 +733,7 @@ class MongoRest {
 
             const meta: any = { action, collection, data: dataInput }
             if (col.hooks?.beforeOperation) {
-                await col.hooks.beforeOperation({ rest: this, io, action, meta })
+                await col.hooks.beforeOperation(this.#hookCtx(action, meta))
             }
             // Validate AFTER hooks (they may fill required fields or apply Joi defaults)
             meta.data = this._validate({ collection, action: action, data: meta.data })
@@ -727,7 +752,7 @@ class MongoRest {
             meta.result = result
 
             if (col.hooks?.afterOperation) {
-                await col.hooks.afterOperation({ rest: this, io, action, meta })
+                await col.hooks.afterOperation(this.#hookCtx(action, meta))
             }
 
             return result as (T & { _id: string })[]
@@ -754,7 +779,7 @@ class MongoRest {
 
             const meta: any = { action, collection, update, id: _id }
             if (col.hooks?.beforeOperation) {
-                await col.hooks.beforeOperation({ rest: this, io, action, meta })
+                await col.hooks.beforeOperation(this.#hookCtx(action, meta))
             }
 
             const data = await this.db.collection(collection).findOneAndUpdate(
@@ -767,7 +792,7 @@ class MongoRest {
             meta.result = result
 
             if (col.hooks?.afterOperation) {
-                await col.hooks.afterOperation({ rest: this, io, action, meta })
+                await col.hooks.afterOperation(this.#hookCtx(action, meta))
             }
 
             return result
@@ -821,7 +846,7 @@ class MongoRest {
 
             const meta: any = { action, collection, filter, update }
             if (col.hooks?.beforeOperation) {
-                await col.hooks.beforeOperation({ rest: this, io, action, meta })
+                await col.hooks.beforeOperation(this.#hookCtx(action, meta))
             }
 
             const data = await this.db.collection(collection).findOneAndUpdate(
@@ -837,7 +862,7 @@ class MongoRest {
             meta.result = result
 
             if (col.hooks?.afterOperation) {
-                await col.hooks.afterOperation({ rest: this, io, action, meta })
+                await col.hooks.afterOperation(this.#hookCtx(action, meta))
             }
 
             return result as Document | null
@@ -863,7 +888,7 @@ class MongoRest {
 
             const meta: any = { action, collection, update, ids: _ids }
             if (col.hooks?.beforeOperation) {
-                await col.hooks.beforeOperation({ rest: this, io, action, meta })
+                await col.hooks.beforeOperation(this.#hookCtx(action, meta))
             }
 
             const result = await this.db.collection(collection).updateMany(
@@ -874,7 +899,7 @@ class MongoRest {
             meta.result = result
 
             if (col.hooks?.afterOperation) {
-                await col.hooks.afterOperation({ rest: this, io, action, meta })
+                await col.hooks.afterOperation(this.#hookCtx(action, meta))
             }
 
             return result as UpdateResult
@@ -891,7 +916,7 @@ class MongoRest {
 
             const meta: any = { action, collection, id: _id }
             if (col.hooks?.beforeOperation) {
-                await col.hooks.beforeOperation({ rest: this, io, action, meta })
+                await col.hooks.beforeOperation(this.#hookCtx(action, meta))
             }
 
             let result = await this.db.collection(collection).findOneAndDelete(
@@ -902,7 +927,7 @@ class MongoRest {
             meta.result = result
 
             if (col.hooks?.afterOperation) {
-                await col.hooks.afterOperation({ rest: this, io, action, meta })
+                await col.hooks.afterOperation(this.#hookCtx(action, meta))
             }
 
             return result
@@ -920,7 +945,7 @@ class MongoRest {
 
             const meta: any = { action, collection, ids: _ids }
             if (col.hooks?.beforeOperation) {
-                await col.hooks.beforeOperation({ rest: this, io, action, meta })
+                await col.hooks.beforeOperation(this.#hookCtx(action, meta))
             }
 
             let result: DeleteResult = await this.db.collection(collection).deleteMany(
@@ -931,7 +956,7 @@ class MongoRest {
             meta.result = result
 
             if (col.hooks?.afterOperation) {
-                await col.hooks.afterOperation({ rest: this, io, action, meta })
+                await col.hooks.afterOperation(this.#hookCtx(action, meta))
             }
 
             return result
@@ -1094,6 +1119,8 @@ class MongoRest {
             return await col.actions?.[action]?.({
                 rest: this,
                 io,
+                agents: createAgents(this.tenant_id, this),
+                api: createApi(this),
                 data,
                 error: fn.error,
                 jwt: func.jwt,
@@ -1125,6 +1152,8 @@ class MongoRest {
                 data,
                 error: fn.error,
                 io,
+                agents: createAgents(this.tenant_id, this),
+                api: createApi(this),
                 jwt: func.jwt,
                 token: token ?? { value: null, decoded: null, provided: false, expired: false },
                 rest: this,
@@ -1335,39 +1364,71 @@ class MongoRest {
         const now = Date.now();
         const expiresAt = now + ttlMs;
         const id = `${this.tenant_id}:${name}`;
-
-        try {
-            const result = await this.db.collection('_locks_').findOneAndUpdate(
-                { _id: id as any, expiresAt: { $lt: now } },
-                { $set: { tid: this.tenant_id, name, acquiredAt: now, expiresAt } },
-                { upsert: true, returnDocument: 'after' }
-            );
-            if (!result) {
-                throw new AppError(`Lock '${name}' is already held by another node`, {
-                    code: 'LOCK_ACQUISITION_FAILED',
-                    status: 409
-                });
+        const hostname = os.hostname();
+        const col = this.db.collection('_locks_');
+
+        // A lock is free when it expired, or when it is held by a process that is
+        // gone **on this host** (Bun `reusePort` / forked processes: a crashed
+        // worker must not block a run for the whole TTL). A remote owner cannot be
+        // probed — its TTL is the only guarantee.
+        const stale = (lock: any): boolean => {
+            if ((lock.expiresAt ?? 0) < now) return true;
+            if (lock.hostname === hostname && typeof lock.pid === 'number') {
+                if (lock.pid === process.pid) return false; // ours: not stale
+                return !isProcessAlive(lock.pid);
             }
-        } catch (err: any) {
-            if (err instanceof AppError) throw err;
-            // E11000 duplicate key = another node holds a valid lock
-            if (err?.code === 11000) {
-                throw new AppError(`Lock '${name}' is already held by another node`, {
-                    code: 'LOCK_ACQUISITION_FAILED',
-                    status: 409
-                });
+            return false;
+        };
+
+        const claim = async (): Promise<boolean> => {
+            const existing: any = await col.findOne({ _id: id as any });
+
+            if (!existing) {
+                try {
+                    await col.insertOne({
+                        _id: id as any,
+                        tid: this.tenant_id,
+                        name,
+                        acquiredAt: now,
+                        expiresAt,
+                        pid: process.pid,
+                        hostname,
+                    } as any);
+                    return true;
+                } catch (err: any) {
+                    if (err?.code === 11000) return false; // another node won the race
+                    throw err;
+                }
             }
-            throw err;
+
+            if (!stale(existing)) return false;
+
+            // Compare-and-set on `expiresAt` (+ owner pid): another node may take it
+            // over in the same instant, only one of us matches
+            const res = await col.updateOne(
+                { _id: id as any, expiresAt: existing.expiresAt ?? null, pid: existing.pid ?? null },
+                { $set: { tid: this.tenant_id, name, acquiredAt: now, expiresAt, pid: process.pid, hostname } },
+            );
+            return (res.matchedCount ?? 0) > 0;
+        };
+
+        if (!(await claim())) {
+            throw new AppError(`Lock '${name}' is already held by another node`, {
+                code: 'LOCK_ACQUISITION_FAILED',
+                status: 409,
+            });
         }
     }
 
     /**
-     * Release a distributed lock.
+     * Release a distributed lock — only when **we** own it: another node may have
+     * taken it over after our process was considered gone.
      */
     async unlock(name: string): Promise<void> {
         await this.db.collection('_locks_').deleteOne({
             tid: this.tenant_id,
             name,
+            $or: [{ pid: process.pid }, { pid: { $exists: false } }],
         });
     }