letopis 0.13.0 → 0.16.0

package/dist/write.js

@@ -1,20 +1,21 @@
 /**
- * Запись: операции .set(data) / .delete(opts) / .anonymize(fields) — ЗВЕНЬЯ цепочки;
- * терминал (rows/first/ids/count/run/versions/агрегации) исполняет весь план
- * ОДНОЙ транзакцией (runPlan) — любой отказ (валидация/ACL) откатывает всё.
+ * Запись: операции .create(data) / .update(data) / .delete(opts) / .anonymize(fields) —
+ * ЗВЕНЬЯ цепочки; терминал (rows/first/ids/count/run/versions/агрегации) исполняет весь
+ * план ОДНОЙ транзакцией (runPlan) — любой отказ (валидация/ACL) откатывает всё.
  *
  * Связи задаются dot-цепочкой: шаги до операции (контекст) резолвятся в ровно одну
  * сущность каждый и дают:
- *   - containment-фильтр целей при UPDATE/DELETE (links ⊇ {Класс: id}),
- *   - links создаваемой строки при INSERT.
+ *   - containment-фильтр целей при update/delete (links ⊇ {Класс: id}),
+ *   - links создаваемой строки при create.
  *
- *   await db.Организация(org).Сотрудник().set({ name: 'Вася' }).rows()   // INSERT + links {Org}
- *   await db.Клиент(c).Запись({ status: 'created' }).set({ status: 'confirmed' }).rows()
- *   await db.Клиент({ vip: true }).set({ bonus: 500 })       // сегмент 1: UPDATE всех vip
- *           .Запись().delete({ confirm: true }).rows()       // сегмент 2: снести записи каждого
+ *   await db.Организация(org).Сотрудник().create({ name: 'Вася' }).rows()  // INSERT + links {Org}
+ *   await db.Клиент(c).Запись({ status: 'created' }).update({ status: 'confirmed' }).rows()
+ *   await db.Клиент({ vip: true }).update({ bonus: 500 })     // сегмент 1: версия каждого vip
+ *           .Запись().delete({ confirm: true }).rows()        // сегмент 2: снести записи каждого
  * Продолжение после операции идёт ОТ ЕЁ РЕЗУЛЬТАТА (fan-out по записанным строкам).
  */
 import { randomUUID } from 'node:crypto';
+import { uuidv5, uuidv7 } from './uuid.js';
 import { buildRead, runQuery, insertSql, multiInsertSql, deleteSql, closureSql, isTransient, retryDelay, RETRIES, } from './sql.js';
 import { aclDenied } from './acl.js';
 export class ValidationError extends Error {
@@ -68,18 +69,36 @@ function validate(cls, id, data, links) {
         throw new ValidationError(cls.id, res);
     delete merged.id;
     if (cls.category === 'LINK') {
-        let polymorphic = 0;
         const present = new Set(Object.keys(links));
-        for (const end of cls.links) {
-            if (end === 'Entity')
-                polymorphic++;
-            else if (present.has(end))
-                present.delete(end);
-            else
-                throw new Error(`letopis: link "${cls.id}" requires end "${end}"`);
+        if (cls.strictEnds) {
+            // схема v2: жадный матчинг по порядку объявления концов; союз занимает один ключ;
+            // обязательный конец без ключа и ключ вне концов — ошибки
+            for (const end of cls.links) {
+                const hit = end.classes.find((c) => present.has(c));
+                if (hit)
+                    present.delete(hit);
+                else if (!end.optional)
+                    throw new Error(`letopis: link "${cls.id}" requires end "${end.classes.join('|')}"`);
+            }
+            if (present.size) {
+                throw new Error(`letopis: link "${cls.id}" has stray link(s) ${[...present].map((k) => `"${k}"`).join(', ')} — not an end in Schema.links`);
+            }
         }
-        if (present.size < polymorphic) {
-            throw new Error(`letopis: link "${cls.id}" requires ${polymorphic} polymorphic end(s) (any class), got ${present.size}`);
+        else {
+            // legacy-схема (строковые концы): 'Entity' — полиморф-счётчик, лишние связи молчат
+            let polymorphic = 0;
+            for (const end of cls.links) {
+                const name = end.classes[0];
+                if (name === 'Entity')
+                    polymorphic++;
+                else if (present.has(name))
+                    present.delete(name);
+                else
+                    throw new Error(`letopis: link "${cls.id}" requires end "${name}"`);
+            }
+            if (present.size < polymorphic) {
+                throw new Error(`letopis: link "${cls.id}" requires ${polymorphic} polymorphic end(s) (any class), got ${present.size}`);
+            }
         }
     }
     return merged;
@@ -137,11 +156,6 @@ function aclWrite(ctx, step, op) {
         step[key] = v;
     }
 }
-/**
- * Различие форм фильтра в записи:
- *   Класс()   — БЕЗ аргумента  → INSERT новой сущности;
- *   Класс({}) — пустой объект  → «все найденные» (UPDATE в границах контекста).
- */
 const noFilter = (f) => f === undefined;
 /** Entity.account NOT NULL: модификатор → connect() → System-аккаунт; иначе ошибка. */
 function resolveAccount(ctx, step) {
@@ -165,93 +179,179 @@ function tagsValue(step) {
         return t;
     throw new Error('letopis: .tags() before set() accepts string | string[]');
 }
+/** Конец target, принимающий класс cls (legacy: 'Entity'-конец берёт любой HUB). */
+function endFor(target, cls) {
+    return target.links.find((e) => e.classes.includes(cls.id) || (!target.strictEnds && e.classes.includes('Entity') && cls.category === 'HUB'));
+}
 /**
- * Контекст-шаги (все, кроме последнего) → {КлассId: id}.
- * id-фильтр берётся как есть (без запроса); иной фильтр обязан дать ровно одну сущность.
+ * Связи создаваемой сущности из ПУТИ: каждый реальный шаг-предок, чей класс — конец
+ * target, обязан дать ровно одну сущность (id-фильтр — как есть; иначе чтение путём
+ * от начала до него: контекст честно учитывается).
  */
-async function resolveContext(ctx, steps) {
+async function resolvePathEnds(ctx, steps) {
+    const target = steps[steps.length - 1].cls;
     const links = {};
-    for (const step of steps) {
+    for (let k = 0; k < steps.length - 1; k++) {
+        const step = steps[k];
+        if (step.pivotKey !== undefined || step.op)
+            continue;
+        if (!endFor(target, step.cls))
+            continue;
         let id;
         if (typeof step.filter === 'string') {
             id = step.filter;
         }
-        else if (!noFilter(step.filter) || step.tagsFilter !== undefined || step.accountFilter || step.ownerFilter) {
-            const rows = await readRows(ctx, [step], { limit: 2 });
+        else {
+            const rows = await readRows(ctx, steps.slice(0, k + 1), { limit: 2 });
             if (rows.length !== 1) {
                 throw new Error(`letopis: context step "${step.name}" must resolve to exactly one entity (got ${rows.length})`);
             }
             id = rows[0].id;
         }
-        else {
-            throw new Error(`letopis: context step "${step.name}" needs an id or a unique filter`);
-        }
         links[step.cls.id] = id;
     }
     return links;
 }
-/** Шаг поиска целей: фильтр последнего шага + containment контекст-связей. */
-function targetStep(target, contextLinks, explicitId) {
-    return {
-        ...target,
-        filter: explicitId ?? target.filter,
-        linksFilter: Object.keys(contextLinks).length ? contextLinks : undefined,
-    };
+/** Резолв слот-значений: строки как есть; вложенные планы — в той же транзакции, ровно одна сущность. */
+async function resolveSlots(ctx, target, extra) {
+    const vals = {};
+    const drops = new Set();
+    for (const [clsId, v] of Object.entries(extra ?? {})) {
+        // союз-замещение: слот занимает КОНЕЦ целиком — соседние классы союза снимаются
+        const end = endFor(target, ctx.registry.resolve(clsId));
+        for (const c of end?.classes ?? [clsId])
+            drops.add(c);
+        if (v === null)
+            continue; // .delete() — только снятие
+        let id;
+        if (typeof v === 'string') {
+            id = v;
+        }
+        else {
+            const rows = v.plan.some((s) => s.op)
+                ? (await runPlan(ctx, v.plan, v.mods ?? {}, 'rows'))
+                : await readRows(ctx, v.plan, { ...(v.mods ?? {}), limit: 2 });
+            if (rows.length !== 1) {
+                throw new Error(`letopis: slot "${clsId}" value plan must resolve to exactly one entity (got ${rows.length})`);
+            }
+            if (rows[0].class !== clsId) {
+                throw new Error(`letopis: slot "${clsId}" value plan resolved to class "${rows[0].class}"`);
+            }
+            id = rows[0].id;
+        }
+        vals[clsId] = id;
+    }
+    return { vals, drops };
 }
+/** id новой сущности по IdGen класса (v5 считается отдельно — нужны концы/данные). */
+const genId = (cls) => (cls.idGen.version === 7 ? uuidv7() : randomUUID());
 /**
- * .set(data):
- *  - пустой фильтр последнего шага и нет data.id → INSERT (links = контекст);
- *  - id (фильтр-строка или data.id) → UPSERT: есть → новая версия (deep-merge), нет → создать;
- *  - фильтр-объект → новая версия каждого найденного (в границах контекста); пусто → [].
+ * Детерминированный id (uuid v5): имя = «схема:партиция:класс:значения from».
+ * from-источник — конец Schema.links (класс или полное имя союза 'Service|Complex';
+ * значение — id присутствующего класса конца) или скалярное поле data.
  */
-export async function setOp(ctx, steps, mods, data) {
+function v5Id(ctx, cls, links, data) {
+    const parts = [];
+    for (const f of cls.idGen.from) {
+        const end = cls.links.find((e) => e.classes.includes(f) || e.classes.join('|') === f);
+        if (end) {
+            const hit = end.classes.find((c) => c in links);
+            if (!hit) {
+                throw new Error(`letopis: id (uuid v5) of "${cls.id}" needs end "${end.classes.join('|')}" — set it in the path or with a slot`);
+            }
+            parts.push(links[hit]);
+        }
+        else {
+            const v = data[f];
+            if (v === undefined || v === null || typeof v === 'object') {
+                throw new Error(`letopis: id (uuid v5) of "${cls.id}" needs scalar data field "${f}"`);
+            }
+            parts.push(String(v));
+        }
+    }
+    return uuidv5(`${ctx.pgSchema}:${ctx.partition}:${cls.id}:${parts.join(':')}`);
+}
+/** Новая версия каждой строки: deep-merge данных + слоты концов (союз-конец замещается целиком). */
+async function versionRows(ctx, target, found, data, slots) {
+    const cls = target.cls;
+    const out = [];
+    for (const row of found) {
+        const mergedData = deepMerge(row.data, data); // только указанные листья
+        const mergedLinks = { ...row.links };
+        for (const c of slots.drops)
+            delete mergedLinks[c];
+        Object.assign(mergedLinks, slots.vals);
+        const full = validate(cls, row.id, mergedData, mergedLinks);
+        out.push(await insertOne(ctx, {
+            id: row.id, cls, data: full, links: mergedLinks,
+            tags: tagsValue(target) ?? row.tags, account: row.account, owner: row.owner,
+            prevUpdated: row.updated, deleted: null,
+        }));
+    }
+    return out;
+}
+/**
+ * .create(data) — «чтобы сущность существовала»:
+ *  - id не задан → INSERT (id по IdGen класса; links = концы из пути + слоты);
+ *  - id известен (Класс(id) / data.id / вычислен v5): есть → новая версия (deep-merge),
+ *    нет → INSERT с этим id (идемпотентный create, REST-PUT семантика);
+ *  - фильтр-объект / pivot — ошибка: create не ищет, это update().
+ */
+export async function createOp(ctx, steps, mods, data) {
     const target = steps[steps.length - 1];
     const cls = target.cls;
     aclWrite(ctx, target, 'WRITE');
-    // контекст-шаги: и фильтр целей, и значения; .link() — ТОЛЬКО значения (фильтр не трогает)
-    const contextLinks = await resolveContext(ctx, steps.slice(0, -1));
-    const writeLinks = { ...contextLinks, ...(target.extraLinks ?? {}) };
-    const dataId = typeof data.id === 'string' ? data.id : undefined;
+    if (target.pivotKey !== undefined) {
+        throw new Error(`letopis: create() on a pivot step — pivot returns to an existing node, use update()`);
+    }
     const filterId = typeof target.filter === 'string' ? target.filter : undefined;
-    const explicitId = filterId ?? dataId;
-    const insertMode = noFilter(target.filter); // Класс() без аргумента
-    const found = insertMode && !explicitId
-        ? []
-        : await readRows(ctx, [targetStep(target, contextLinks, explicitId)], mods);
-    if (found.length) {
-        const out = [];
-        for (const row of found) {
-            const mergedData = deepMerge(row.data, data); // только указанные листья
-            const mergedLinks = { ...row.links, ...writeLinks }; // контекст + .link()
-            const full = validate(cls, row.id, mergedData, mergedLinks);
-            out.push(await insertOne(ctx, {
-                id: row.id, cls, data: full, links: mergedLinks,
-                tags: tagsValue(target) ?? row.tags, account: row.account, owner: row.owner,
-                prevUpdated: row.updated, deleted: null,
-            }));
+    if (!noFilter(target.filter) && filterId === undefined) {
+        throw new Error(`letopis: create() takes no filter — ${cls.alias}(id).create(…) fixes the id, searching is update()`);
+    }
+    // слоты (.Класс.set/.unset): значения/снятия концов; союз-конец замещается целиком
+    const slots = await resolveSlots(ctx, cls, target.extraLinks);
+    const dataId = typeof data.id === 'string' ? data.id : undefined;
+    if (filterId && dataId && filterId !== dataId) {
+        throw new Error(`letopis: create() got two ids — step "${filterId}" vs data.id "${dataId}"`);
+    }
+    let explicitId = filterId ?? dataId;
+    // связи создаваемого: концы из пути + слоты (слоты выигрывают, unset снимает)
+    const pathEnds = await resolvePathEnds(ctx, steps);
+    const writeLinks = { ...pathEnds };
+    for (const c of slots.drops)
+        delete writeLinks[c];
+    Object.assign(writeLinks, slots.vals);
+    if (cls.idGen.version === 5) {
+        if (explicitId) {
+            throw new Error(`letopis: class "${cls.id}" computes id (uuid v5 from ${cls.idGen.from.join(', ')}) — remove the explicit id`);
         }
-        return out;
+        explicitId = v5Id(ctx, cls, writeLinks, data);
     }
-    // не найдено: INSERT только при явном id или Класс() без аргумента
-    if (!explicitId && !insertMode)
-        return [];
-    // enforceAcl-предикат + явный id: «не нашёл среди доступных» НЕ значит «можно создать» —
-    // существующая, но недоступная сущность иначе перехватывалась бы новой версией с чужим owner.
-    // Проверка существования — БЕЗ предиката и БЕЗ пришпиленных им колонок.
-    if (explicitId && target.aclFilter) {
-        const bare = { ...ctx, aclDecide: undefined };
-        const probe = {
-            ...targetStep(target, contextLinks, explicitId),
-            aclFilter: undefined,
-            ownerFilter: undefined,
-            accountFilter: undefined,
-            linksFilter: undefined,
-        };
-        const taken = await readRows(bare, [probe], {});
-        if (taken.length)
-            return [];
+    if (explicitId !== undefined) {
+        // id известен и существует (в границах пути) → новая версия
+        const pathSteps = [...steps.slice(0, -1), { ...target, filter: explicitId }];
+        const found = await readRows(ctx, pathSteps, mods);
+        if (found.length)
+            return versionRows(ctx, target, found, data, slots);
+        // enforceAcl-предикат: «не нашёл среди доступных» НЕ значит «можно создать» —
+        // существующая, но недоступная сущность иначе перехватывалась бы новой версией
+        // с чужим owner. Проверка существования — БЕЗ предиката и пришпиленных колонок.
+        if (target.aclFilter) {
+            const bare = { ...ctx, aclDecide: undefined };
+            const probe = {
+                ...target,
+                filter: explicitId,
+                aclFilter: undefined,
+                ownerFilter: undefined,
+                accountFilter: undefined,
+                linksFilter: undefined,
+            };
+            const taken = await readRows(bare, [probe], {});
+            if (taken.length)
+                return [];
+        }
     }
-    const id = explicitId ?? randomUUID();
+    const id = explicitId ?? genId(cls);
     const account = resolveAccount(ctx, target);
     const owner = target.ownerFilter ?? ctx.owner ?? account;
     const full = validate(cls, id, data, writeLinks);
@@ -262,6 +362,23 @@ export async function setOp(ctx, steps, mods, data) {
         }),
     ];
 }
+/**
+ * .update(data?) — новая версия КАЖДОГО найденного путём (deep-merge листьев);
+ * цели: Класс() ≡ Класс({}) — все в границах контекста, id/фильтр/pivot — как в чтении.
+ * Не найдено → [] — update НИКОГДА не создаёт.
+ */
+export async function updateOp(ctx, steps, mods, data) {
+    const target = steps[steps.length - 1];
+    aclWrite(ctx, target, 'WRITE');
+    const slots = await resolveSlots(ctx, target.cls, target.extraLinks);
+    // data.id — цель, только если у шага нет своего фильтра
+    const dataId = typeof data.id === 'string' ? data.id : undefined;
+    const pathSteps = noFilter(target.filter) && dataId !== undefined
+        ? [...steps.slice(0, -1), { ...target, filter: dataId }]
+        : steps;
+    const found = await readRows(ctx, pathSteps, mods); // честный путь: переходы, pivot
+    return versionRows(ctx, target, found, data, slots);
+}
 /**
  * .anonymize(fields): GDPR-затирание — новая версия с '[erased]' в указанных string-полях
  * + тег 'anonymized'. Только string-поля (по Schema); история сохраняется (см. README).
@@ -275,8 +392,7 @@ export async function anonymizeOp(ctx, steps, mods, fields) {
             throw new Error(`letopis: anonymize() erases string fields only; "${f}" is ${cls.fieldTypes.get(f)?.kind ?? 'unknown'}`);
         }
     }
-    const contextLinks = await resolveContext(ctx, steps.slice(0, -1));
-    const found = await readRows(ctx, [targetStep(target, contextLinks)], mods);
+    const found = await readRows(ctx, steps, mods); // цели — честный путь
     const out = [];
     for (const row of found) {
         const patch = Object.fromEntries(fields.filter((f) => f in row.data).map((f) => [f, '[erased]']));
@@ -317,8 +433,7 @@ async function inTransaction(ctx, fn) {
 export async function delOp(ctx, steps, mods, confirm) {
     const target = steps[steps.length - 1];
     aclWrite(ctx, target, 'DELETE');
-    const contextLinks = await resolveContext(ctx, steps.slice(0, -1));
-    const targets = await readRows(ctx, [targetStep(target, contextLinks)], mods);
+    const targets = await readRows(ctx, steps, mods); // цели — честный путь
     if (!targets.length)
         return [];
     const params = [ctx.partition, target.cls.id, ...targets.map((r) => r.id)];
@@ -353,8 +468,10 @@ function splitPlan(steps) {
 }
 function opCall(c, steps, op) {
     switch (op.kind) {
-        case 'set':
-            return setOp(c, steps, op.mods, op.data ?? {});
+        case 'create':
+            return createOp(c, steps, op.mods, op.data ?? {});
+        case 'update':
+            return updateOp(c, steps, op.mods, op.data ?? {});
         case 'anonymize':
             return anonymizeOp(c, steps, op.mods, op.fields ?? []);
         case 'delete':
@@ -473,10 +590,11 @@ async function readByMode(c, steps, mods, mode) {
     }
 }
 const isPureInsertPlan = (p) => p.steps.length === 1 &&
-    p.steps[0].op?.kind === 'set' &&
+    p.steps[0].op?.kind === 'create' &&
     noFilter(p.steps[0].filter) &&
     typeof p.steps[0].op.data?.id !== 'string' &&
-    !Object.keys(p.steps[0].extraLinks ?? {}).length;
+    !Object.keys(p.steps[0].extraLinks ?? {}).length &&
+    p.steps[0].cls.idGen.version !== 5;
 export async function executeBatch(ctx, queue) {
     if (!queue.length)
         return [];
@@ -493,8 +611,8 @@ export async function executeBatch(ctx, queue) {
                 const params = [];
                 for (const g of group) {
                     const s = { ...g.steps[0] };
-                    aclWrite(c, s, 'WRITE'); // склейка multi-VALUES идёт мимо setOp — право+пришпиливание на каждый
-                    const id = randomUUID();
+                    aclWrite(c, s, 'WRITE'); // склейка multi-VALUES идёт мимо createOp — право+пришпиливание на каждый
+                    const id = genId(cls);
                     const full = validate(cls, id, s.op?.data ?? {}, {});
                     const account = resolveAccount(c, s);
                     params.push(c.partition, id, cls.id, full, {}, tagsValue(s) ?? [], account, s.ownerFilter ?? c.owner ?? account);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "letopis",
-  "version": "0.13.0",
+  "version": "0.16.0",
   "description": "Letopis (летопись): append-only versioned entity store on TimescaleDB with dot-notation chains — every change is a new row, history is first-class (asOf, versions, watch, cascade tombstones)",
   "keywords": [
     "timescaledb",

package/sql/ddl.sql

@@ -21,7 +21,7 @@ CREATE TABLE IF NOT EXISTS "<SCHEMA-NAME>"."Schema" (
     category   text   NOT NULL CHECK (category IN ('HUB', 'LINK')),
     ancestor   text,                             -- прямой родитель (наследование)
     attributes jsonb  NOT NULL DEFAULT '{}',     -- fastest-validator DSL (валидирует либа)
-    links      text[] NOT NULL DEFAULT '{}',     -- HUB: встраиваемые цели; LINK: обязательные концы ('Entity' = полиморфный)
+    links      jsonb  NOT NULL DEFAULT '[]',     -- МАССИВ ОБЪЕКТОВ-концов: {"class":…}/{"classes":[…],"optional":…,"cardinality":…} (союзы ролей, матчинг по порядку); legacy-элемент-строка "Org" ("Entity" = полиморфный)
     meta       jsonb  NOT NULL DEFAULT '{}',     -- {abstract?, description?}
     "order"    int    NOT NULL DEFAULT 0,
     ancestors   text[] NOT NULL DEFAULT '{}',    -- [self, parent, …, root] — считает триггер schema_lineage
@@ -132,16 +132,26 @@ CREATE INDEX IF NOT EXISTS entity_owner_idx   ON "<SCHEMA-NAME>"."Entity" (owner
 --   * класс существует в Schema той же partition;
 --   * класс не абстрактный;
 --   * каждый ключ links — существующий класс, значение — строка (id);
---   * LINK содержит все обязательные концы из Schema.links
---     ('Entity' — полиморфный конец, его резолвит либа).
+--   * LINK: концы из Schema.links.
+--     Формат v2 (элемент — JSON-объект '{"class":…}' / '{"classes":[…]}'):
+--     жадный матчинг по порядку объявления, optional-концы могут отсутствовать,
+--     связи вне объявленных концов — ошибка.
+--     Legacy (элемент — имя класса): конец обязателен по имени, 'Entity' —
+--     полиморфный (его резолвит либа), лишние связи не проверяются.
 -- Tombstone-версии (deleted IS NOT NULL) не валидируются.
 -- -----------------------------------------------------------------------------
 CREATE OR REPLACE FUNCTION "<SCHEMA-NAME>".entity_check() RETURNS trigger
 LANGUAGE plpgsql AS $$
 DECLARE
-    s   RECORD;
-    bad text;
-    k   text;
+    s    RECORD;
+    bad  text;
+    k    text;
+    used text[];
+    ej   jsonb;
+    ecs  text[];
+    hit  text;
+    c2   text;
+    is_v2 boolean;
 BEGIN
     IF NEW.deleted IS NOT NULL THEN
         RETURN NEW;
@@ -172,13 +182,45 @@ BEGIN
         RAISE EXCEPTION 'ENTITY_CHECK: links key "%" is not a class or its value is not an id string', bad;
     END IF;
 
-    -- LINK: все объявленные концы обязаны присутствовать
+    -- LINK: концы по Schema.links — jsonb-массив; элемент-объект = v2 (строгий жадный
+    -- матчинг по порядку), элемент-строка = legacy-имя класса
     IF s.category = 'LINK' THEN
-        FOREACH k IN ARRAY COALESCE(s.links, '{}') LOOP
-            IF k <> 'Entity' AND NOT (COALESCE(NEW.links, '{}'::jsonb) ? k) THEN
-                RAISE EXCEPTION 'ENTITY_CHECK: link "%" requires end "%"', NEW.class, k;
+        is_v2 := EXISTS (
+            SELECT 1 FROM jsonb_array_elements(COALESCE(s.links, '[]'::jsonb)) le
+            WHERE jsonb_typeof(le.value) = 'object');
+        IF is_v2 THEN
+            used := ARRAY[]::text[];
+            FOR ej IN SELECT le.value FROM jsonb_array_elements(COALESCE(s.links, '[]'::jsonb)) le LOOP
+                ecs := COALESCE(
+                    (SELECT array_agg(x) FROM jsonb_array_elements_text(ej->'classes') x),
+                    ARRAY[ej->>'class']);
+                hit := NULL;
+                FOREACH c2 IN ARRAY ecs LOOP
+                    IF (COALESCE(NEW.links, '{}'::jsonb) ? c2) AND NOT (c2 = ANY(used)) THEN
+                        hit := c2;
+                        EXIT;
+                    END IF;
+                END LOOP;
+                IF hit IS NOT NULL THEN
+                    used := used || hit;
+                ELSIF NOT COALESCE((ej->>'optional')::boolean, false) THEN
+                    RAISE EXCEPTION 'ENTITY_CHECK: link "%" requires end "%"', NEW.class, array_to_string(ecs, '|');
+                END IF;
+            END LOOP;
+            SELECT e.key INTO bad
+            FROM jsonb_each(COALESCE(NEW.links, '{}'::jsonb)) e
+            WHERE NOT (e.key = ANY(used))
+            LIMIT 1;
+            IF bad IS NOT NULL THEN
+                RAISE EXCEPTION 'ENTITY_CHECK: link "%" has stray link "%" — not an end in Schema.links', NEW.class, bad;
             END IF;
-        END LOOP;
+        ELSE
+            FOR k IN SELECT le.value #>> '{}' FROM jsonb_array_elements(COALESCE(s.links, '[]'::jsonb)) le LOOP
+                IF k <> 'Entity' AND NOT (COALESCE(NEW.links, '{}'::jsonb) ? k) THEN
+                    RAISE EXCEPTION 'ENTITY_CHECK: link "%" requires end "%"', NEW.class, k;
+                END IF;
+            END LOOP;
+        END IF;
     END IF;
 
     RETURN NEW;