@anteros/core 0.0.40 → 0.0.41

package/tests/vars.test.ts

@@ -0,0 +1,216 @@
+import { describe, it, expect, beforeAll, afterAll } from "bun:test";
+import { MongoClient, ObjectId } from "mongodb";
+import { useRest } from "../database/rest";
+import { formatConfig, cfg } from "../server/config";
+import { syncVars } from "../database/vars";
+import { define } from "../lib/define";
+
+const TEST_TENANT = "vars";
+const DB = "mongodb://localhost:27017/_VARS_TEST";
+
+let rest: InstanceType<typeof useRest>;
+let client: MongoClient;
+const raw = () => client.db().collection("_vars_");
+
+beforeAll(async () => {
+    formatConfig({
+        server: { port: 4000 },
+        tenants: [{
+            id: TEST_TENANT,
+            dir: "packages/core/tests/fixtures/vars-tenant",
+            database: { uri: DB },
+        }],
+    });
+
+    client = new MongoClient(DB, { serverSelectionTimeoutMS: 3000 });
+    await client.connect();
+    const tenant: any = cfg.tenants?.[0];
+    tenant.database.client = client;
+    tenant.database.db = client.db();
+
+    await syncVars();
+
+    rest = new useRest({ tenant_id: TEST_TENANT });
+});
+
+afterAll(async () => {
+    try { await client.db().dropDatabase(); } catch (_) {}
+    try { await client.close(); } catch (_) {}
+});
+
+describe("define.Vars", () => {
+    it("marks the definition", () => {
+        const v = define.Vars({ namespace: "x", vars: { a: 1 } });
+        expect(v._isVars_).toBe(true);
+    });
+});
+
+describe("vars loading & seeding", () => {
+    it("loads the definitions from vars/*.var.ts", () => {
+        const namespaces = (cfg.vars ?? []).map((v) => v.namespace).sort();
+        expect(namespaces).toEqual(["config", "private"]);
+        expect((cfg.vars ?? []).every((v) => v._tenant_ === TEST_TENANT)).toBe(true);
+    });
+
+    it("seeds default values at the global scope", async () => {
+        expect(await rest.vars.get<string>("config", "licence")).toBe("RDX00");
+        expect(await rest.vars.get<number>("config", "maxUsers")).toBe(100);
+    });
+
+    it("never overwrites an existing value when re-seeding", async () => {
+        await rest.vars.set("config", "licence", "CHANGED");
+        await syncVars();
+        expect(await rest.vars.get<string>("config", "licence")).toBe("CHANGED");
+    });
+
+    it("always creates the scope + TTL indexes", async () => {
+        const names = (await raw().listIndexes().toArray()).map((i) => i.name);
+        expect(names).toContain("scope_1_ns_1");
+        expect(names).toContain("expiresAt_1");
+    });
+});
+
+describe("rest.vars — CRUD", () => {
+    it("set / get / has / del", async () => {
+        await rest.vars.set("app", "theme", "dark");
+        expect(await rest.vars.get<string>("app", "theme")).toBe("dark");
+        expect(await rest.vars.has("app", "theme")).toBe(true);
+
+        expect(await rest.vars.del("app", "theme")).toBe(true);
+        expect(await rest.vars.get<string>("app", "theme")).toBeUndefined();
+        expect(await rest.vars.has("app", "theme")).toBe(false);
+        expect(await rest.vars.del("app", "theme")).toBe(false);
+    });
+
+    it("stores rich values (objects, arrays, booleans)", async () => {
+        const value = { max: 10, tags: ["a", "b"], on: true };
+        await rest.vars.set("app", "limits", value);
+        expect(await rest.vars.get<any>("app", "limits")).toEqual(value);
+    });
+
+    it("setMany / all / clear", async () => {
+        await rest.vars.setMany("bulk", { a: 1, b: 2, c: 3 });
+        expect(await rest.vars.all("bulk")).toEqual({ a: 1, b: 2, c: 3 });
+        expect(await rest.vars.clear("bulk")).toBe(3);
+        expect(await rest.vars.all("bulk")).toEqual({});
+    });
+
+    it("incr is atomic (and creates a missing key)", async () => {
+        await rest.vars.set("counters", "hits", 5);
+        expect(await rest.vars.incr("counters", "hits")).toBe(6);
+        expect(await rest.vars.incr("counters", "hits", 10)).toBe(16);
+        expect(await rest.vars.incr("counters", "fresh", 3)).toBe(3);
+    });
+
+    it("isolates namespaces", async () => {
+        await rest.vars.set("ns1", "k", "a");
+        await rest.vars.set("ns2", "k", "b");
+        expect(await rest.vars.get<string>("ns1", "k")).toBe("a");
+        expect(await rest.vars.get<string>("ns2", "k")).toBe("b");
+    });
+});
+
+describe("rest.vars — scope (per company)", () => {
+    it("keeps a distinct value per scope", async () => {
+        const acme = new ObjectId().toHexString();
+        const globex = new ObjectId().toHexString();
+
+        await rest.vars.scope(acme).set("config", "licence", "ACME-001");
+        await rest.vars.scope(globex).set("config", "licence", "GLBX-002");
+
+        expect(await rest.vars.scope(acme).get<string>("config", "licence")).toBe("ACME-001");
+        expect(await rest.vars.scope(globex).get<string>("config", "licence")).toBe("GLBX-002");
+        // global value untouched
+        expect(await rest.vars.get<string>("config", "licence")).not.toBe("ACME-001");
+    });
+
+    it("accepts an explicit scope option", async () => {
+        const id = new ObjectId().toHexString();
+        await rest.vars.set("config", "licence", "SCOPED", { scope: id });
+        expect(await rest.vars.get<string>("config", "licence", { scope: id })).toBe("SCOPED");
+    });
+});
+
+describe("rest.vars — meta", () => {
+    it("stores and returns validated meta", async () => {
+        const id = new ObjectId().toHexString();
+        const acme = rest.vars.scope(id);
+
+        await acme.set("config", "licence", "ACME-003", { meta: { note: "Contrat 2026" } });
+        const entry = await acme.entry("config", "licence");
+
+        expect(entry?.value).toBe("ACME-003");
+        expect(entry?.meta).toEqual({ note: "Contrat 2026" });
+        expect(String(entry?.scope)).toBe(id);
+    });
+
+    it("rejects unknown meta keys", async () => {
+        await expect(
+            rest.vars.set("config", "licence", "X", { meta: { nope: 1 } }),
+        ).rejects.toThrow(/nope/);
+    });
+
+    it("filters entries on meta with `where`", async () => {
+        const id = new ObjectId().toHexString();
+        const acme = rest.vars.scope(id);
+
+        await acme.setMany("flags", { a: true, b: false }, { meta: { note: "grp" } });
+        const found = await acme.entries("flags", { where: { note: "grp" } });
+
+        expect(found.length).toBe(2);
+        expect(await acme.entries("flags", { where: { note: "other" } })).toEqual([]);
+    });
+});
+
+describe("rest.vars — validation", () => {
+    it("rejects a value that does not match its spec", async () => {
+        await expect(rest.vars.set("config", "maxUsers", "not-a-number")).rejects.toThrow(/maxUsers/);
+    });
+});
+
+describe("rest.vars — TTL", () => {
+    it("stores an expiry set per call", async () => {
+        await rest.vars.set("ttl", "k", "v", { ttl: "1h" });
+        const entry = await rest.vars.entry("ttl", "k");
+        expect(entry?.expiresAt).toBeInstanceOf(Date);
+        expect(entry!.expiresAt!.getTime()).toBeGreaterThan(Date.now());
+    });
+
+    it("applies the variable's default TTL", async () => {
+        await rest.vars.set("config", "session", "s1"); // `session` declares ttl: '1h'
+        const entry = await rest.vars.entry("config", "session");
+        expect(entry?.expiresAt).toBeInstanceOf(Date);
+    });
+
+    it("`set` without ttl clears an existing one", async () => {
+        await rest.vars.set("ttl", "clear", "v", { ttl: "1h" });
+        await rest.vars.set("ttl", "clear", "v2"); // no ttl → authoritative reset
+        const entry = await rest.vars.entry("ttl", "clear");
+        expect(entry?.expiresAt).toBeNull();
+    });
+
+    it("`expire` sets / renews the TTL", async () => {
+        await rest.vars.set("ttl", "renew", "v");
+        expect(await rest.vars.expire("ttl", "renew", "30m")).toBe(true);
+        const entry = await rest.vars.entry("ttl", "renew");
+        expect(entry?.expiresAt).toBeInstanceOf(Date);
+    });
+
+    it("hides an expired entry from reads", async () => {
+        await raw().insertOne({
+            _id: "config:gone",
+            ns: "config", key: "gone", scope: null,
+            value: "x", meta: {},
+            expiresAt: new Date(Date.now() - 1000),
+            createdAt: new Date(), updatedAt: new Date(),
+        } as any);
+
+        expect(await rest.vars.get<string>("config", "gone")).toBeUndefined();
+        expect(await rest.vars.has("config", "gone")).toBe(false);
+        expect(await rest.vars.entry("config", "gone")).toBeUndefined();
+    });
+
+    it("rejects an invalid ttl", async () => {
+        await expect(rest.vars.set("ttl", "bad", "v", { ttl: "abc" })).rejects.toThrow(/ttl/);
+    });
+});

package/types/collection.d.ts

@@ -8,6 +8,7 @@ import type { useRest } from "../database/rest";
 import type { jwt } from "../utils/func";
 import type { ActionsApiList, ApiAccess, ApiActions } from "./api";
 import type { Server as SocketIO } from "socket.io";
+import type { CollectionReplicationConfig } from "./replication";
 
 /** Context passed to a collection custom action (`define.Action`). */
 export type CollectionActionContext = {
@@ -85,6 +86,8 @@ export type Collection = {
         /** Default TTL for cached queries — human string ('5m', '2h') or ms */
         ttl?: string | number;
     };
+    /** Opt-in one-way replication to destination databases — see `ReplicationConfig`. */
+    replication?: CollectionReplicationConfig;
     /**
      * The tenant id of the collection
      * @type {string}

package/types/config.d.ts

@@ -7,6 +7,8 @@ import type { Service } from "./service";
 import type { Script } from "./scripts";
 import type { FileCollection } from "./file";
 import type { McpTool, McpResource } from "./mcp";
+import type { VarDefinition } from "./vars";
+import type { AuditFileConfig } from "../lib/audit";
 export type ServerConfig = {
     debug?: boolean;
     version?: string;
@@ -21,9 +23,70 @@ export type ServerConfig = {
         metricsPort?: number;
         /** When true, trusts proxy headers (CF-Connecting-IP / X-Forwarded-For) as the client IP. Default: false. */
         trustProxy?: boolean;
+        /**
+         * Audit trail defaults for every tenant. A tenant declaring its own
+         * `tenant.audit` always wins (even `false`).
+         */
+        audit?: {
+            /**
+             * How long `_audit_` entries are kept (MongoDB TTL on `ts`).
+             * Duration string: `'90d'`, `'24h'`.
+             * `false` → explicitly disabled (drops the TTL index if one exists).
+             * Omitted → untouched: entries are kept forever.
+             */
+            retention?: string | false;
+            /**
+             * Local append-only JSONL copy of the audit trail (one file per day,
+             * rotated on size, pruned by age).
+             * `true` → defaults, `string` → directory, object → full options.
+             * `false` / omitted → disabled.
+             */
+            file?: AuditFileConfig;
+            /**
+             * Object keys whose value is replaced by `"[redacted]"` in every audit
+             * entry (`operation.input`, `operation.result` and `meta`), at any depth,
+             * case-insensitively. `false` → disabled.
+             *
+             * Default: password, passwd, pwd, token, authorization, apikey, api_key,
+             * key, secret, cookie, otp, pin.
+             */
+            redact?: string[] | false;
+            /**
+             * What an audit entry keeps of the operation's **result**
+             * (default: `'summary'`).
+             *
+             * - `'summary'` (default) → the **generated identifiers** (`_id`,
+             *   `insertedIds`) plus the operational counters (`matchedCount`,
+             *   `modifiedCount`, `deletedCount`, `nIndexesWas`…). Never a document:
+             *   the data lives in the collection (and in its replications).
+             * - `'none'`    → the generated identifiers only.
+             * - `'full'`    → the raw result, documents included.
+             *
+             * Reads (`find`, `findOne`, `aggregate`, streams, `watch`) and custom
+             * actions/services never store a result, whatever this setting.
+             */
+            results?: 'none' | 'summary' | 'full';
+        };
         body?: {
             maxSize?: number;
         };
+        /**
+         * Boot mode (default: `'full'`).
+         *
+         * - `'full'` — HTTP API **and** the replication engine.
+         * - `'replication-only'` — a process dedicated to the replication engine: no
+         *   HTTP API, no websocket handlers, no scripts, no services, no MCP tools,
+         *   no middlewares. Loaded: tenant databases, collections, file collections,
+         *   variables and lifecycle hooks (`beforeBoot` / `onDestroy`).
+         * - `'no-replication'` — a full server that never starts the replication
+         *   engine (no scheduling, no tombstones, no `_replication_` state).
+         * - `'api-only'` — the HTTP API and nothing around it: no replication, no
+         *   scripts, no sockets.
+         *
+         * Flags always win over this setting: `--replication-only`, `--no-replication`,
+         * `--api-only`, `--no-scripts`, `--no-sockets`.
+         */
+        mode?: 'full' | 'replication-only' | 'no-replication' | 'api-only';
         cors?: {
             origin: string | string[] | ((ctx: { origin: string, c: Context }) => string | string[]);
             credentials?: boolean;
@@ -123,4 +186,5 @@ export type Config = ServerConfig & {
     fileCollections?: FileCollection[]
     mcpTools?: McpTool[]
     mcpResources?: McpResource[]
+    vars?: VarDefinition[]
 }

package/types/file.d.ts

@@ -4,6 +4,7 @@ import type { HooksCollection } from "./hook";
 import type Joi from "joi";
 import type { useRest } from "../database/rest";
 import type { jwt } from "../utils/func";
+import type { CollectionReplicationConfig } from "./replication";
 
 type FileAccessHandler = (ctx: {
     rest: InstanceType<typeof useRest>;
@@ -42,6 +43,8 @@ export type FileCollection = {
     };
     /** Metadata fields stored alongside the file document */
     fields?: Field[];
+    /** Opt this file collection into the data replication engine (its documents). */
+    replication?: CollectionReplicationConfig;
     /** Upload validation rules */
     upload?: {
         /** Allowed MIME types for upload.
@@ -103,7 +106,7 @@ export type FileCollection = {
             /** Private key path for SSH auth */
             privateKey?: string;
         }[];
-        /** Enregistrer les métadonnées du fichier en base. Défaut: true */
+        /** Save the file metadata in the database. Default: true */
         trackMetaData?: boolean;
     api?: {
         access?: FileApiAccess;

package/types/lifecycle.d.ts

@@ -0,0 +1,71 @@
+import type { useRest } from "../database/rest";
+import type { Tenant } from "./tenant";
+import type { Config } from "./config";
+import type { logger } from "../utils/logger";
+import type { Server as SocketIO } from "socket.io";
+import type { TenantReplicationApi } from "./replication";
+
+/** Signal that triggered the shutdown. */
+export type LifecycleReason = "SIGINT" | "SIGTERM";
+
+/** Base context shared by every lifecycle hook. `rest` is tenant-scoped. */
+export type LifecycleContext = {
+    tenant: Tenant;
+    rest: InstanceType<typeof useRest>;
+    logger: typeof logger;
+    cfg: Config;
+    /** Tenant-scoped replication API — `reset()`, `seed()`, `now()`, `state()` (no tenant id needed). */
+    replication: TenantReplicationApi;
+};
+
+/** Context of `beforeBoot` — runs before replication and before the HTTP server listens. */
+export type LifecycleBootContext = LifecycleContext;
+
+/** Context of `afterBoot` — runs once the server is listening. */
+export type LifecycleReadyContext = LifecycleContext & {
+    io: SocketIO;
+    server: ReturnType<typeof Bun.serve>;
+};
+
+/** Context of `onDestroy` — runs on SIGINT/SIGTERM, before replication stops and DB clients close. */
+export type LifecycleDestroyContext = LifecycleContext & {
+    reason: LifecycleReason;
+};
+
+/**
+ * Per-tenant lifecycle — one `lifecycle.ts` at the tenant root.
+ *
+ * @example
+ * ```ts
+ * export default define.Lifecycle({
+ *   beforeBoot: async ({ rest, tenant }) => { await rest.insertOne('settings', { tenant: tenant.id }) },
+ *   afterBoot: async ({ server, logger }) => { logger.info(`ready on :${server.port}`) },
+ *   onDestroy: async ({ reason }) => { await flushSomething(reason) },
+ * })
+ * ```
+ */
+export type Lifecycle = {
+    _isLifecycle_?: boolean;
+    /** Injected by the loader — the tenant this lifecycle belongs to. */
+    _tenant_?: string;
+    /** Turn this lifecycle off without removing the file (default: true). */
+    enabled?: boolean;
+    /**
+     * Blocking — runs after databases are connected and collections are loaded,
+     * before replication starts and before the HTTP server listens. Ideal for
+     * migrations, seeding, warmup. Throwing aborts the boot.
+     */
+    beforeBoot?: (ctx: LifecycleBootContext) => Promise<void> | void;
+    /**
+     * Runs once the server is listening (after `Bun.serve`). Ideal for
+     * notifications and cache warming. Errors are logged, never fatal.
+     */
+    afterBoot?: (ctx: LifecycleReadyContext) => Promise<void> | void;
+    /**
+     * Runs on SIGINT/SIGTERM, before replication stops and tenant DB clients
+     * close — so `rest` is still usable. Errors are logged; shutdown proceeds.
+     */
+    onDestroy?: (ctx: LifecycleDestroyContext) => Promise<void> | void;
+    /** Max time (ms) allowed for `onDestroy` before shutdown proceeds anyway (default: 10000). */
+    destroyTimeout?: number;
+};

package/types/replication.d.ts

@@ -0,0 +1,199 @@
+import type { MongoClientOptions } from "mongodb";
+
+/** When to run replication — either a cron expression or a fixed interval. */
+export type ReplicationSchedule =
+    | { cron: string }
+    | { interval: string | number };
+
+/**
+ * Initial synchronization mode — how replication starts when no `_replication_`
+ * state exists yet.
+ * - `"full"` — backfill everything (default)
+ * - `"skip"` — ignore existing documents, start from now
+ * - `"latest"` — start from the latest `key` in the source
+ * - ISO string / `Date` — start from this date
+ */
+export type ReplicationInitialSync = "full" | "skip" | "latest" | (string & {}) | Date;
+
+/** A destination database that receives replicated documents. */
+export type ReplicationDestination = {
+    /** Unique identifier — used as the `_replication_` state key (required). */
+    id: string;
+    /** MongoDB connection string (required). */
+    uri: string;
+    /** Database name override — defaults to the name in the URI. */
+    name?: string;
+    /** Extra MongoDB client options (pool size, timeouts…). */
+    options?: MongoClientOptions;
+    /** Restrict replication to these collection slugs (default: all enabled). */
+    collections?: string[];
+    /** Turn this destination off without removing it. */
+    enabled?: boolean;
+};
+
+/** Per-tenant replication configuration (source → destination, one-way). */
+export type ReplicationConfig = {
+    /** Enable/disable replication for this scope (default: true when `destinations` is non-empty). */
+    enabled?: boolean;
+    /** Scheduling — `{ cron }` or `{ interval }` (default: every 5 minutes). */
+    schedule?: ReplicationSchedule;
+    /** Date key used for incremental replication (default: `'updatedAt'`). */
+    key?: string;
+    /**
+     * Rewind the cursor by this many milliseconds on each run, so documents
+     * written slightly out of order (clock skew) are not missed (default: 0).
+     */
+    lookback?: number;
+    /** Documents transferred per batch (default: 1000). */
+    batchSize?: number;
+    /** Run a first replication right after boot (default: true). */
+    runOnBoot?: boolean;
+    /**
+     * How the initial synchronization starts when no `_replication_` state exists
+     * yet (default: `'full'`). Use `'skip'` or `'latest'` to avoid the full
+     * backfill when the destination is already pre-loaded (e.g. via `mongorestore`).
+     */
+    initialSync?: ReplicationInitialSync;
+    /** Destination databases (required). */
+    destinations: ReplicationDestination[];
+};
+
+/** Per-collection opt-in replication. */
+export type CollectionReplicationConfig = {
+    /** Opt this collection into replication (required). */
+    enabled: boolean;
+    /** Date key override — defaults to `replication.key`. */
+    key?: string;
+    /** Initial sync override — defaults to `replication.initialSync`. */
+    initialSync?: ReplicationInitialSync;
+};
+
+export type ReplicationStatus = "idle" | "running" | "success" | "error";
+
+/** Cursor of the last replicated document — `value` is the date key, `id` the tie-breaker. */
+export type ReplicationCursor = {
+    value: Date | null;
+    id: any;
+};
+
+export type ReplicationStats = {
+    inserted: number;
+    updated: number;
+    deleted: number;
+    failed: number;
+    batches: number;
+    durationMs: number;
+};
+
+/** State document persisted in `_replication_`, one per (tenant, destination, collection). */
+export type ReplicationState = {
+    _id: string;
+    type: "state";
+    tenant: string;
+    destination: string;
+    collection: string;
+    key: string;
+    cursor: ReplicationCursor;
+    status: ReplicationStatus;
+    lastRunAt: Date | null;
+    lastError: string | null;
+    stats: ReplicationStats;
+    createdAt?: Date;
+    updatedAt: Date;
+};
+
+/** Tombstone document persisted in `_replication_` when a replicated document is deleted. */
+export type ReplicationDeleteMarker = {
+    _id: string;
+    type: "delete";
+    tenant: string;
+    collection: string;
+    docId: string;
+    deletedAt: Date;
+    /** Destination ids that already applied the delete. */
+    synced: string[];
+    updatedAt: Date;
+};
+
+/** Scope of a `replication.reset()` call. */
+export type ReplicationResetOptions = {
+    /** Only reset this destination id (default: every destination). */
+    destination?: string;
+    /** Only reset this collection slug (default: every replicated collection). */
+    collection?: string;
+    /**
+     * Also delete pending delete tombstones (default: true). Ignored when
+     * `destination` is set — tombstones are shared across destinations.
+     */
+    tombstones?: boolean;
+};
+
+/** Result of a `replication.reset()` call. */
+export type ReplicationResetResult = {
+    tenant: string;
+    /** State documents deleted (one per destination + collection). */
+    state: number;
+    /** Delete tombstones deleted. */
+    tombstones: number;
+};
+
+/**
+ * Where to (re)start replication from — accepted by `replication.seed()`.
+ * - `"now"` — start from now (same as `initialSync: 'skip'`)
+ * - `"latest"` — start from the latest `key` in the source
+ * - ISO string / `Date` — start from this date
+ */
+export type ReplicationSeedValue = "now" | "latest" | (string & {}) | Date;
+
+/** Scope of a `replication.seed()` call. */
+export type ReplicationSeedOptions = {
+    /** Only seed this destination id (default: every destination). */
+    destination?: string;
+    /** Only seed this collection slug (default: every replicated collection). */
+    collection?: string;
+    /** Optional `_id` tie-breaker for the cursor. */
+    id?: any;
+};
+
+/** Result of a `replication.seed()` call. */
+export type ReplicationSeedResult = {
+    tenant: string;
+    /** State documents written (one per destination + collection). */
+    seeded: number;
+};
+
+/** Shape of the `replication` namespace exported by the package (multi-tenant). */
+export type ReplicationApi = {
+    start: () => Promise<void>;
+    stop: () => Promise<void>;
+    now: (tenantId?: string) => Promise<ReplicationRunResult[]>;
+    state: (tenantId: string, destinationId?: string, collection?: string) => Promise<ReplicationState[]>;
+    reset: (tenantId: string, opts?: ReplicationResetOptions) => Promise<ReplicationResetResult>;
+    seed: (tenantId: string, value: ReplicationSeedValue, opts?: ReplicationSeedOptions) => Promise<ReplicationSeedResult>;
+};
+
+/**
+ * Tenant-scoped replication API — like `rest`, the tenant is implicit. This is
+ * the `replication` passed to lifecycle hooks. Engine control (`start`/`stop`)
+ * stays on the global `ReplicationApi`.
+ */
+export type TenantReplicationApi = {
+    now: () => Promise<ReplicationRunResult[]>;
+    state: (destinationId?: string, collection?: string) => Promise<ReplicationState[]>;
+    reset: (opts?: ReplicationResetOptions) => Promise<ReplicationResetResult>;
+    seed: (value: ReplicationSeedValue, opts?: ReplicationSeedOptions) => Promise<ReplicationSeedResult>;
+};
+
+/** Outcome of a single (tenant, destination, collection) replication. */
+export type ReplicationRunResult = {
+    tenant: string;
+    destination: string;
+    collection: string;
+    inserted: number;
+    updated: number;
+    deleted: number;
+    failed: number;
+    batches: number;
+    durationMs: number;
+    error?: string;
+};

package/types/tenant.d.ts

@@ -1,9 +1,32 @@
 import type { Db, MongoClient, MongoClientOptions } from "mongodb";
+import type { ReplicationConfig } from "./replication";
+import type { AuditFileConfig } from "../lib/audit";
 export type Tenant = {
     id: string;
     name?: string;
     description?: string;
     dir: string;
+    /** Per-tenant replication — each tenant has its own destinations and schedule. */
+    replication?: ReplicationConfig;
+    /**
+     * Audit trail (`_audit_`) — query indexes are always ensured in the background,
+     * retention is opt-in.
+     */
+    audit?: {
+        /**
+         * How long audit entries are kept, as a MongoDB TTL index on `ts`.
+         * Duration string: `'90d'`, `'24h'`, `'30m'`.
+         * `false` → explicitly disabled (drops the TTL index if one exists).
+         * Omitted → untouched: entries are kept forever.
+         */
+        retention?: string | false;
+        /**
+         * Local append-only JSONL copy of this tenant's audit trail.
+         * `true` → defaults, `string` → directory, object → full options.
+         * `false` → explicitly disabled (overrides `server.audit.file`).
+         */
+        file?: AuditFileConfig;
+    };
     routes?: {
         prefix?: string;
     },