@anteros/core 0.0.40 → 0.0.42

package/tests/audit-retention-config.test.ts

@@ -0,0 +1,76 @@
+import { describe, it, expect, beforeAll, afterAll } from "bun:test";
+import { formatConfig, cfg } from "../server/config";
+import { syncTenants, getTenant } from "../database/tenant";
+import { AUDIT_COLLECTION, AUDIT_TTL_INDEX, resolveAuditRetention } from "../database/audit";
+
+const SERVER_RETENTION = "30d";
+
+const INHERIT = "ret-inherit";
+const OVERRIDE = "ret-override";
+const OFF = "ret-off";
+
+const DBS = {
+    [INHERIT]: "mongodb://localhost:27017/_AUDIT_RET_INHERIT",
+    [OVERRIDE]: "mongodb://localhost:27017/_AUDIT_RET_OVERRIDE",
+    [OFF]: "mongodb://localhost:27017/_AUDIT_RET_OFF",
+} as const;
+
+/** TTL index of a tenant's `_audit_` collection, or undefined. */
+async function ttlIndex(tenantId: string): Promise<any> {
+    const db = getTenant(tenantId)!.database!.db!;
+    return (await db.collection(AUDIT_COLLECTION).listIndexes().toArray())
+        .find((i: any) => i.name === AUDIT_TTL_INDEX);
+}
+
+beforeAll(async () => {
+    formatConfig({
+        server: {
+            port: 4000,
+            // Server-wide default — every tenant inherits it unless it declares its own
+            audit: { retention: SERVER_RETENTION },
+        },
+        tenants: [
+            { id: INHERIT, dir: "src", database: { uri: DBS[INHERIT] } },
+            { id: OVERRIDE, dir: "src", database: { uri: DBS[OVERRIDE] }, audit: { retention: "1h" } },
+            { id: OFF, dir: "src", database: { uri: DBS[OFF] }, audit: { retention: false } },
+        ],
+    });
+
+    await syncTenants();
+});
+
+afterAll(async () => {
+    for (const id of Object.keys(DBS)) {
+        try { await getTenant(id)?.database?.db?.collection(AUDIT_COLLECTION).drop(); } catch (_) {}
+    }
+    // `cfg.server` is shared by every test file in the same process: the server-wide
+    // retention would otherwise leak into the other suites
+    delete (cfg.server as any).audit;
+});
+
+describe("audit retention precedence", () => {
+    it("resolves: the tenant wins, the server default is the fallback", () => {
+        const base = { dir: "src", database: { uri: "" } };
+
+        expect(resolveAuditRetention({ id: INHERIT, ...base } as any)).toBe(SERVER_RETENTION);
+        expect(resolveAuditRetention({ id: OVERRIDE, ...base, audit: { retention: "1h" } } as any)).toBe("1h");
+        // `false` is a value, not an absence — it must override the server default
+        expect(resolveAuditRetention({ id: OFF, ...base, audit: { retention: false } } as any)).toBe(false);
+    });
+
+    it("applies the server default to a tenant without its own config", async () => {
+        const ttl = await ttlIndex(INHERIT);
+        expect(ttl).toBeDefined();
+        expect(ttl.expireAfterSeconds).toBe(30 * 86400);
+    });
+
+    it("lets the tenant override the server default", async () => {
+        const ttl = await ttlIndex(OVERRIDE);
+        expect(ttl).toBeDefined();
+        expect(ttl.expireAfterSeconds).toBe(3600);
+    });
+
+    it("lets the tenant opt out of the server default with `false`", async () => {
+        expect(await ttlIndex(OFF)).toBeUndefined();
+    });
+});

package/tests/audit-run-action.test.ts

@@ -0,0 +1,120 @@
+import { describe, it, expect, beforeAll, afterAll } from "bun:test";
+import { createApp } from "../server/hono";
+import { formatConfig, cfg } from "../server/config";
+import { syncTenants } from "../database/tenant";
+import { useRest } from "../database/rest";
+import { AUDIT_COLLECTION } from "../database/audit";
+
+const TENANT = "act-test";
+const DB = "mongodb://localhost:27017/_AUDIT_ACTION_TEST";
+const SLUG = "invoices";
+
+let internalRest: InstanceType<typeof useRest>;
+let server: any;
+let url = "";
+
+/**
+ * Latest audited `runAction` entry.
+ * `#logActivity` is fire-and-forget, and `since` (captured *before* the call)
+ * makes sure we wait for the new entry instead of reading the previous one.
+ */
+async function lastRunAction(since?: Date) {
+    for (let i = 0; i < 40; i++) {
+        const found: any = await internalRest.db.collection(AUDIT_COLLECTION).findOne(
+            { "operation.action": "runAction", ...(since ? { ts: { $gte: since } } : {}) },
+            { sort: { ts: -1 } },
+        );
+        if (found) return found;
+        await Bun.sleep(25);
+    }
+    return null;
+}
+
+beforeAll(async () => {
+    formatConfig({
+        server: { port: 4000 },
+        tenants: [{ id: TENANT, dir: "src", database: { uri: DB } }],
+    });
+    await syncTenants();
+
+    (cfg as any).collections = [{
+        _tenant_: TENANT,
+        slug: SLUG,
+        fields: [{ name: "ref", type: "string" }],
+        actions: {
+            greet: async ({ data }: any) => ({ hello: data?.name }),
+            boom: async () => { throw new Error("kaboom") },
+        },
+        api: { access: { "*": true } },
+    }];
+
+    internalRest = new useRest({ internal: true, tenant_id: TENANT });
+
+    const app = createApp();
+    server = Bun.serve({ port: 0, fetch: app.fetch });
+    url = server.url.href.replace(/\/$/, "");
+});
+
+afterAll(async () => {
+    try { await internalRest.db.collection(SLUG).drop(); } catch (_) {}
+    try { await internalRest.db.collection(AUDIT_COLLECTION).drop(); } catch (_) {}
+    try { server.stop(true); } catch {}
+});
+
+describe("audit — custom actions (runAction)", () => {
+    it("audits an internal call with the action name and its data, never the payload", async () => {
+        const since = new Date();
+        const result: any = await internalRest.runAction(SLUG, "greet", { name: "Ada" });
+
+        // the caller still receives the action's payload…
+        expect(result).toEqual({ hello: "Ada" });
+
+        // …but the audit only holds the parameters
+        const logged = await lastRunAction(since);
+        expect(logged).not.toBeNull();
+        expect(logged.operation.input.action).toBe("greet");
+        expect(logged.operation.input.data).toEqual({ name: "Ada" });
+        expect(logged.operation.result).toBeNull();
+        expect(logged.operation.status).toBe("success");
+        expect(logged.internal).toBe(true);
+    });
+
+    it("audits the HTTP route as well, and marks it as not internal", async () => {
+        const since = new Date();
+        const res = await fetch(`${url}/api/${TENANT}/collections/${SLUG}/greet`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ data: { name: "Grace" } }),
+        });
+
+        expect(res.status).toBe(200);
+        expect(await res.json()).toEqual({ hello: "Grace" });
+
+        const logged = await lastRunAction(since);
+        expect(logged.operation.input.action).toBe("greet");
+        expect(logged.operation.input.data).toEqual({ name: "Grace" });
+        expect(logged.operation.result).toBeNull();
+        expect(logged.internal).toBe(false);
+    });
+
+    it("records a failing action with its error, and rethrows it unchanged", async () => {
+        const since = new Date();
+
+        // `wrapErrors: false` — a custom action's own error reaches the caller as-is
+        await expect(internalRest.runAction(SLUG, "boom")).rejects.toThrow("kaboom");
+
+        const logged = await lastRunAction(since);
+        expect(logged.operation.status).toBe("error");
+        expect(logged.operation.error.message).toBe("kaboom");
+        expect(logged.operation.result).toBeNull();
+    });
+
+    it("records an unknown action", async () => {
+        const since = new Date();
+        await expect(internalRest.runAction(SLUG, "nope")).rejects.toThrow();
+
+        const logged = await lastRunAction(since);
+        expect(logged.operation.status).toBe("error");
+        expect(logged.operation.error.code).toBe("ACTION_NOT_FOUND");
+    });
+});

package/tests/audit.test.ts

@@ -0,0 +1,320 @@
+import { describe, it, expect, beforeAll, afterAll } from "bun:test";
+import { useRest } from "../database/rest";
+import { formatConfig, cfg } from "../server/config";
+import { syncTenants, getTenant } from "../database/tenant";
+import {
+    AUDIT_COLLECTION,
+    LEGACY_AUDIT_COLLECTION,
+    AUDIT_TTL_INDEX,
+    migrateAuditCollection,
+    syncAuditRetention,
+} from "../database/audit";
+
+const TEST_TENANT = "audit";
+const TEST_DB = "mongodb://localhost:27017/_AUDIT_TEST";
+
+// Second tenant: proves `tenant.audit.retention` is wired end-to-end
+const TTL_TENANT = "audit-ttl";
+const TTL_DB = "mongodb://localhost:27017/_AUDIT_TTL_TEST";
+
+let rest: InstanceType<typeof useRest>;
+
+/**
+ * Latest audit entry for a (collection, action) pair.
+ *
+ * `#logActivity` is fire-and-forget, so we poll — and when the same pair was
+ * already logged by an earlier test, `since` (captured *before* the operation)
+ * makes sure we wait for the new entry instead of reading the stale one.
+ */
+async function lastActivity(collection: string, action: string, since?: Date) {
+    for (let i = 0; i < 40; i++) {
+        const found: any = await rest.db.collection(AUDIT_COLLECTION).findOne(
+            {
+                "operation.collection": collection,
+                "operation.action": action,
+                ...(since ? { ts: { $gte: since } } : {}),
+            },
+            { sort: { ts: -1 } },
+        );
+        if (found) return found;
+        await Bun.sleep(25);
+    }
+    return null;
+}
+
+/** Minimal activity document (same shape as `ActivityInput`). */
+function activity(action: string) {
+    return {
+        internal: true,
+        trace: { id: crypto.randomUUID() },
+        meta: {},
+        operation: {
+            tenant: TEST_TENANT,
+            action,
+            collection: "items",
+            status: "success",
+            input: null,
+            result: null,
+            error: null,
+            duration: 0,
+            transaction: false,
+        },
+        ts: new Date(),
+    } as any;
+}
+
+/** Index document, or undefined when absent. */
+async function index(name: string): Promise<any> {
+    return (await rest.db.collection(AUDIT_COLLECTION).listIndexes().toArray())
+        .find((i: any) => i.name === name);
+}
+
+beforeAll(async () => {
+    formatConfig({
+        server: { port: 4000 },
+        tenants: [
+            { id: TEST_TENANT, dir: "src", database: { uri: TEST_DB } },
+            { id: TTL_TENANT, dir: "src", database: { uri: TTL_DB }, audit: { retention: "7d" } },
+        ],
+    });
+    await syncTenants();
+
+    // Declared collections — needed to exercise the `$lookup` allow-list and `collectionType`
+    (cfg as any).collections = [
+        {
+            _tenant_: TEST_TENANT,
+            slug: "items",
+            fields: [{ name: "title", type: "string" }],
+            api: { access: { "*": true } },
+        },
+    ];
+    (cfg as any).fileCollections = [
+        {
+            _tenant_: TEST_TENANT,
+            _isFileCollection_: true,
+            slug: "photos",
+            fields: [{ name: "label", type: "string" }],
+            api: { access: { "*": true } },
+        },
+    ];
+
+    rest = new useRest({ internal: true, tenant_id: TEST_TENANT });
+});
+
+afterAll(async () => {
+    try { await rest.db.collection("items").drop(); } catch (_) {}
+    try { await rest.db.collection("photos").drop(); } catch (_) {}
+    try { await rest.db.collection(AUDIT_COLLECTION).drop(); } catch (_) {}
+    try { await rest.db.collection(LEGACY_AUDIT_COLLECTION).drop(); } catch (_) {}
+    try { await getTenant(TTL_TENANT)?.database?.db?.collection(AUDIT_COLLECTION).drop(); } catch (_) {}
+});
+
+describe("audit collection", () => {
+    it("writes to `_audit_`", async () => {
+        await rest.audit.addActivities([activity("unit")]);
+
+        const stored: any = await rest.db.collection(AUDIT_COLLECTION)
+            .findOne({ "operation.action": "unit" });
+        expect(stored).toBeDefined();
+        expect(stored.operation.collection).toBe("items");
+    });
+
+    it("reads back through getActivities", async () => {
+        const logs = await rest.audit.getActivities({
+            $match: { "operation.action": "unit" },
+            $limit: 10,
+        } as any);
+        expect(logs.length).toBeGreaterThanOrEqual(1);
+    });
+
+    it("does not use the legacy `_activities_` name anymore", async () => {
+        const legacy = await rest.db.listCollections({ name: LEGACY_AUDIT_COLLECTION }).toArray();
+        expect(legacy.length).toBe(0);
+    });
+
+    it("is on disk as soon as a mutation resolves (no polling needed)", async () => {
+        const doc: any = await rest.insertOne("items", { title: "awaited" });
+
+        // Deliberately **no** polling: mutations await their audit entry, so it is
+        // already there — a successful write can never lose its trace.
+        const logged: any = await rest.db.collection(AUDIT_COLLECTION).findOne({
+            "operation.action": "insertOne",
+            "operation.result._id": doc._id,
+        });
+        expect(logged).not.toBeNull();
+        expect(logged.operation.status).toBe("success");
+    });
+
+    it("accepts `_audit_` as a $lookup target from a declared collection", async () => {
+        const rows = await rest.aggregate("items", [
+            { $lookup: { from: AUDIT_COLLECTION, localField: "_id", foreignField: "_id", as: "audit" } },
+            { $limit: 1 },
+        ]);
+        expect(Array.isArray(rows)).toBe(true);
+    });
+});
+
+describe("audit collectionType", () => {
+    it("labels a document collection as `document`", async () => {
+        await rest.insertOne("items", { title: "collectionType" });
+
+        const logged = await lastActivity("items", "insertOne");
+        expect(logged).not.toBeNull();
+        expect(logged.operation.collectionType).toBe("document");
+    });
+
+    it("labels a file collection as `file`", async () => {
+        await rest.insertOne("photos", { label: "ct", _file: { filename: "ct.png" } });
+
+        const logged = await lastActivity("photos", "insertOne");
+        expect(logged).not.toBeNull();
+        expect(logged.operation.collectionType).toBe("file");
+    });
+
+    it("leaves `collectionType` undefined for an internal collection", async () => {
+        // `_audit_` is not declared anywhere — no type to report
+        const logged: any = await rest.db.collection(AUDIT_COLLECTION)
+            .findOne({ "operation.collection": "_locks_" });
+        expect(logged?.operation?.collectionType).toBeUndefined();
+    });
+});
+
+describe("audit read operations", () => {
+    it("logs `find` with its parameters, never the result", async () => {
+        const since = new Date();
+        const docs = await rest.find("items", { $match: { title: "collectionType" }, $limit: 5 });
+        expect(docs.length).toBeGreaterThanOrEqual(1); // the read really returned data
+
+        const logged = await lastActivity("items", "find", since);
+        expect(logged).not.toBeNull();
+        expect(logged.operation.input.params).toEqual({ $match: { title: "collectionType" }, $limit: 5 });
+        expect(logged.operation.result).toBeNull();          // ← nothing returned is stored
+        expect(logged.operation.status).toBe("success");
+    });
+
+    it("logs `findOne` with the id", async () => {
+        const since = new Date();
+        const [first] = await rest.find("items", { $limit: 1 });
+        const doc: any = await rest.findOne("items", first!._id);
+        expect(doc).not.toBeNull();
+
+        const logged = await lastActivity("items", "findOne", since);
+        expect(logged.operation.input.id).toBeString();
+        expect(logged.operation.result).toBeNull();
+    });
+
+    it("logs `aggregate` with its pipeline", async () => {
+        const since = new Date();
+        const pipeline = [{ $match: { title: "collectionType" } }, { $limit: 1 }];
+        const rows = await rest.aggregate("items", pipeline);
+        expect(rows.length).toBeGreaterThanOrEqual(1);
+
+        const logged = await lastActivity("items", "aggregate", since);
+        expect(logged.operation.input.pipeline).toEqual(pipeline);
+        expect(logged.operation.result).toBeNull();
+    });
+
+    it("logs a failed read with its error and still no result", async () => {
+        const since = new Date();
+        await expect(rest.aggregate("items", [
+            { $lookup: { from: "not_declared", localField: "_id", foreignField: "_id", as: "x" } },
+        ])).rejects.toThrow();
+
+        const logged = await lastActivity("items", "aggregate", since);
+        expect(logged.operation.status).toBe("error");
+        expect(logged.operation.error.message).toBeString();
+        expect(logged.operation.result).toBeNull();
+    });
+});
+
+describe("audit query indexes", () => {
+    it("are ensured at boot", async () => {
+        const names = (await rest.db.collection(AUDIT_COLLECTION).listIndexes().toArray())
+            .map((i: any) => i.name);
+        expect(names).toContain("_audit_ts_");
+        expect(names).toContain("_audit_collection_ts_");
+        expect(names).toContain("_audit_status_ts_");
+        expect(names).toContain("_audit_trace_");
+    });
+
+    it("serve the documented sorts and filters", async () => {
+        expect((await index("_audit_ts_")).key).toEqual({ ts: -1 });
+        expect((await index("_audit_collection_ts_")).key).toEqual({ "operation.collection": 1, ts: -1 });
+        expect((await index("_audit_status_ts_")).key).toEqual({ "operation.status": 1, ts: -1 });
+        expect((await index("_audit_trace_")).key).toEqual({ "trace.id": 1 });
+    });
+});
+
+describe("audit retention (TTL)", () => {
+    it("stays untouched — no TTL index — when retention is not configured", async () => {
+        expect(await syncAuditRetention(rest.db, undefined)).toBe("skipped");
+        expect(await index(AUDIT_TTL_INDEX)).toBeUndefined();
+    });
+
+    it("creates a TTL index when a duration is configured", async () => {
+        expect(await syncAuditRetention(rest.db, "90d")).toBe("applied");
+
+        const ttl = await index(AUDIT_TTL_INDEX);
+        expect(ttl.key).toEqual({ ts: 1 });
+        expect(ttl.expireAfterSeconds).toBe(90 * 86400);
+    });
+
+    it("is idempotent — the same duration is a no-op", async () => {
+        expect(await syncAuditRetention(rest.db, "90d")).toBe("unchanged");
+    });
+
+    it("updates expireAfterSeconds when the duration changes", async () => {
+        expect(await syncAuditRetention(rest.db, "24h")).toBe("applied");
+        expect((await index(AUDIT_TTL_INDEX)).expireAfterSeconds).toBe(24 * 3600);
+    });
+
+    it("drops the TTL index when retention is explicitly disabled", async () => {
+        expect(await syncAuditRetention(rest.db, false)).toBe("dropped");
+        expect(await index(AUDIT_TTL_INDEX)).toBeUndefined();
+    });
+
+    it("ignores an invalid duration", async () => {
+        expect(await syncAuditRetention(rest.db, "banana")).toBe("skipped");
+        expect(await index(AUDIT_TTL_INDEX)).toBeUndefined();
+    });
+
+    it("is wired through `tenant.audit.retention`", async () => {
+        const db = getTenant(TTL_TENANT)!.database!.db!;
+        const ttl: any = (await db.collection(AUDIT_COLLECTION).listIndexes().toArray())
+            .find((i: any) => i.name === AUDIT_TTL_INDEX);
+
+        expect(ttl).toBeDefined();
+        expect(ttl.expireAfterSeconds).toBe(7 * 86400);
+    });
+});
+
+describe("audit collection migration (`_activities_` → `_audit_`)", () => {
+    it("renames an existing legacy collection, without losing documents", async () => {
+        await rest.db.collection(AUDIT_COLLECTION).drop().catch(() => {});
+        await rest.db.collection(LEGACY_AUDIT_COLLECTION).insertOne(activity("legacy") as any);
+
+        expect(await migrateAuditCollection(rest.db)).toBe(true);
+
+        const legacy = await rest.db.listCollections({ name: LEGACY_AUDIT_COLLECTION }).toArray();
+        expect(legacy.length).toBe(0);
+
+        const moved: any = await rest.db.collection(AUDIT_COLLECTION)
+            .findOne({ "operation.action": "legacy" });
+        expect(moved).toBeDefined();
+    });
+
+    it("is idempotent — a second run is a no-op", async () => {
+        expect(await migrateAuditCollection(rest.db)).toBe(false);
+    });
+
+    it("never touches the legacy collection when `_audit_` already exists", async () => {
+        await rest.db.collection(AUDIT_COLLECTION).insertOne(activity("keep") as any);
+        await rest.db.collection(LEGACY_AUDIT_COLLECTION).insertOne(activity("orphan") as any);
+
+        expect(await migrateAuditCollection(rest.db)).toBe(false);
+
+        // neither merged nor dropped — both collections survive untouched
+        expect(await rest.db.collection(AUDIT_COLLECTION).countDocuments({ "operation.action": "orphan" })).toBe(0);
+        expect(await rest.db.collection(LEGACY_AUDIT_COLLECTION).countDocuments({})).toBe(1);
+    });
+});

package/tests/db-cache.test.ts

@@ -152,10 +152,10 @@ describe("DB query cache (useCache)", () => {
         const r1: any = await rest.find("items", params, { useCache: true });
         expect(r1[0]!.count).toBe(1);
 
-        // update avec un ObjectId NATIF (pas un string) — la normalisation String(id) doit matcher l'index
+        // update with a NATIVE ObjectId (not a string) — String(id) normalization must match the index
         await rest.updateOne("items", new ObjectId(a._id), { $set: { count: 77 } });
         const r2: any = await rest.find("items", params, { useCache: true });
-        expect(r2[0]!.count).toBe(77); // invalidé + refetch
+        expect(r2[0]!.count).toBe(77); // invalidated + refetch
 
         await rest.db.collection("items").deleteMany({ title: marker });
     });
@@ -168,15 +168,15 @@ describe("DB query cache (useCache)", () => {
         const b = await rest.insertOne("items", { title: marker, count: 2 });
         const c = await rest.insertOne("items", { title: marker, count: 3 });
 
-        const params = { $match: { title: marker }, $sort: { count: 1 } }; // ordre garanti: a(1), b(2), c(3)
-        await rest.find("items", params, { useCache: true }); // cache peuplé (3 docs)
+        const params = { $match: { title: marker }, $sort: { count: 1 } }; // guaranteed order: a(1), b(2), c(3)
+        await rest.find("items", params, { useCache: true }); // cache populated (3 docs)
 
-        // le 3e id (c) n'est PAS taggé (maxTags: 2) → pas d'invalidation ciblée
+        // the 3rd id (c) is NOT tagged (maxTags: 2) → no targeted invalidation
         await rest.updateOne("items", c._id, { $set: { count: 33 } });
         const r1: any = await rest.find("items", params, { useCache: true });
-        expect(r1.find((d: any) => d._id === c._id)!.count).toBe(3); // cache conservé
+        expect(r1.find((d: any) => d._id === c._id)!.count).toBe(3); // cache kept
 
-        // le 1er id (a) est taggé → invalidation ciblée
+        // the 1st id (a) is tagged → targeted invalidation
         await rest.updateOne("items", a._id, { $set: { count: 11 } });
         const r2: any = await rest.find("items", params, { useCache: true });
         expect(r2.find((d: any) => d._id === a._id)!.count).toBe(11); // refetch

package/tests/endpoints.test.ts

@@ -0,0 +1,80 @@
+import { describe, it, expect } from "bun:test";
+import { endpoints, FAMILIES, isReservedFamily, patterns, segment } from "../lib/endpoints";
+
+/**
+ * The URL of everything — pinned here so a change of shape is a **deliberate**
+ * change (the whole surface moved to `/api/:tenant_id/<family>/…` once already,
+ * and every client, doc and skill had to follow).
+ */
+
+describe("endpoints — the server patterns", () => {
+    it("keeps every surface under `/api/:tenant_id/<family>`", () => {
+        for (const pattern of Object.values(patterns)) {
+            expect(pattern.startsWith("/api/:tenant_id/")).toBe(true);
+        }
+    });
+
+    it("names a family the builders also use", () => {
+        const families = new Set<string>(FAMILIES);
+        for (const pattern of Object.values(patterns)) {
+            const [, , , family] = pattern.split("/");
+            expect(families.has(family!)).toBe(true);
+        }
+    });
+
+    it("registers no pattern that could shadow a collection action", () => {
+        // A collection lives under `/collections/`, so `services`, `vars` or `login`
+        // are usable as collection names — that is the point of the layout.
+        expect(patterns.collection.split("/")[3]).toBe("collections");
+        expect(patterns.login).toBe("/api/:tenant_id/collections/:collection/login");
+    });
+});
+
+describe("endpoints — the builders", () => {
+    it("builds the documented paths", () => {
+        expect(endpoints.collection("v1", "orders", "find")).toBe("/api/v1/collections/orders/find");
+        expect(endpoints.collection("v1", "users", "login")).toBe("/api/v1/collections/users/login");
+        expect(endpoints.service("v1", "billing", "charge")).toBe("/api/v1/services/billing/charge");
+        expect(endpoints.vars("v1", "get")).toBe("/api/v1/vars/get");
+        expect(endpoints.upload("v1", "photos")).toBe("/api/v1/upload/photos");
+        expect(endpoints.file("v1", "photos", "507f1f77.jpg")).toBe("/api/v1/files/photos/507f1f77.jpg");
+        expect(endpoints.agent("v1", "support", "generate")).toBe("/api/v1/agents/support/generate");
+        expect(endpoints.mcp("v1")).toBe("/api/v1/mcp");
+    });
+
+    it("matches the pattern it maps to", () => {
+        const mapped: Array<[string, string]> = [
+            [patterns.collection, endpoints.collection("t", "c", "a")],
+            [patterns.login, endpoints.collection("t", "c", "login")],
+            [patterns.service, endpoints.service("t", "s", "a")],
+            [patterns.vars, endpoints.vars("t", "a")],
+            [patterns.upload, endpoints.upload("t", "c")],
+            [patterns.file, endpoints.file("t", "c", "f")],
+            [patterns.agent, endpoints.agent("t", "ag", "a")],
+            [patterns.mcp, endpoints.mcp("t")],
+        ];
+
+        for (const [pattern, path] of mapped) {
+            const expected = pattern.split("/").slice(1);
+            expect(path.split("/").slice(1)).toHaveLength(expected.length);
+            // Same shape: each `:param` is one segment, the literals are identical
+            for (const [index, part] of expected.entries()) {
+                if (part.startsWith(":")) continue;
+                expect(path.split("/").slice(1)[index]).toBe(part);
+            }
+        }
+    });
+
+    it("encodes a segment, so an id with a slash cannot forge a path", () => {
+        expect(segment("a/b c")).toBe("a%2Fb%20c");
+        expect(endpoints.file("v1", "photos", "../etc/passwd")).toBe("/api/v1/files/photos/..%2Fetc%2Fpasswd");
+    });
+});
+
+describe("endpoints — reserved families", () => {
+    it("recognises what a tenant route must not shadow", () => {
+        for (const family of FAMILIES) expect(isReservedFamily(family)).toBe(true);
+        expect(isReservedFamily("orders")).toBe(false);
+        expect(isReservedFamily("Collections")).toBe(false);
+    });
+});