@orthacms/content-server 0.0.0-reserve.0

package/dist/lib/entries/infrastructure/persistence/relation-link.service.js

@@ -0,0 +1,1008 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RelationLinkService = exports.RELATION_PAGE_SIZE = void 0;
+exports.assertSameLocale = assertSameLocale;
+const tslib_1 = require("tslib");
+const common_1 = require("@nestjs/common");
+const drizzle_orm_1 = require("drizzle-orm");
+const database_1 = require("@orthacms/database");
+const content_type_1 = require("../../../types/content-type");
+const fields_1 = require("../../../types/fields");
+const entry_row_1 = require("./entry-row");
+/**
+ * Reject any target row that lives in a different locale from the source.
+ *
+ * Two **i18n** types must link inside one locale. A cross-locale link is a
+ * broken model rather than a preference: the English article would render the
+ * German tag, and since links are per-row rather than synced across a
+ * translation group, nothing later repairs it. The admin has always enforced
+ * this by only offering same-locale candidates in its relation picker; this is
+ * the same rule at the layer a direct API call cannot skip.
+ *
+ * A no-op unless BOTH sides are localized — `sourceLocale` is `undefined` for a
+ * non-i18n owner, and a non-i18n target has no locale to disagree about.
+ *
+ * Exported so `EntryWriterService` applies the identical rule to the owning
+ * **single** relations it validates itself (a `<field>_id` FK never reaches the
+ * join-table paths), instead of the two growing their own versions of it.
+ */
+function assertSameLocale(rows, target, field, sourceLocale) {
+    if (!sourceLocale || !target.i18n)
+        return;
+    const foreign = rows.filter((row) => row['locale'] !== sourceLocale);
+    if (!foreign.length)
+        return;
+    throw new common_1.UnprocessableEntityException({
+        message: 'Entry validation failed',
+        issues: foreign.map((row) => ({
+            field,
+            message: `must reference a "${sourceLocale}" entry — ` +
+                `"${row['id']}" is "${row['locale']}". ` +
+                'Link the translation of that record in this entry’s locale.'
+        }))
+    });
+}
+/** Default links per page when the caller doesn't specify one. */
+exports.RELATION_PAGE_SIZE = 20;
+/**
+ * How many relation fields are resolved at once — by the page preview and by
+ * the per-entry {@link RelationLinkService.readAll}. `relationFields` is
+ * bounded in bytes but not in count, so a type with many relation columns could
+ * otherwise fan out one concurrent query per field — and each field takes a
+ * connection twice (its window query, then `refsFor`). The pool is small and
+ * app-wide, so cap the fan-out and let the remainder queue in-process rather
+ * than in the pool, where it would block unrelated requests.
+ */
+const RELATION_FIELD_CONCURRENCY = 3;
+/**
+ * A private advisory-lock class (the first `pg_advisory_xact_lock` key)
+ * namespacing the per-source append locks, so their hashed `<table>:<sourceId>`
+ * keys can't collide with any other advisory lock the app takes (e.g. identity's
+ * per-workspace lock). Arbitrary but fixed.
+ */
+const RELATION_APPEND_LOCK_CLASS = 0x524c; // 'RL'
+/**
+ * Reads and writes the relation **links** an entry owns beyond its own columns:
+ * many-to-many join rows and the inverse (back-reference) side of a two-way
+ * relation. Owning **single** relations are plain `<field>_id` FK columns —
+ * written by `toColumns`, read off the row — so they need no join plumbing.
+ *
+ * Everything is **paginated**: a relation can hold thousands of links, so reads
+ * return one ordered page + a `total` (never every id), and writes apply an
+ * incremental {@link RelationDelta} (link / unlink / reorder) inside a
+ * transaction — so a huge relation never has to be sent or held in full.
+ * Order is persisted in the join table's `position` column, owned by the
+ * **source** side; the inverse reads by it (stable) but can't reorder it.
+ */
+let RelationLinkService = class RelationLinkService {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    // ---- reads -------------------------------------------------------------
+    /**
+     * First page (+ total) of **every** relation field of `type` for one entry,
+     * keyed by field name — what the editor loads on open. Each field is read
+     * independently (paginated), so a relation with many links contributes only
+     * its first page, not every id.
+     *
+     * Admin-only, hence no {@link RelationTargetVisibility}: an editor must see
+     * the draft targets it may be about to publish. The public API reads links
+     * one field at a time through {@link readField}, which takes the flag.
+     */
+    async readAll(type, row, workspaceId, pageSize = exports.RELATION_PAGE_SIZE) {
+        // Each relation field is an independent read, so fan them out
+        // concurrently rather than awaiting one before starting the next — a
+        // type with several relations pays one field's latency, not their sum.
+        //
+        // Bounded by the same cap as `previewForEntries`, and for the same
+        // reason: the pool is small (10 by default) and app-wide, while each
+        // field takes a connection for its page + count and then again for
+        // `refsFor`. Unbounded, a type with several relation fields could let a
+        // couple of concurrent editor opens occupy every connection and queue
+        // unrelated traffic behind them — the exact hazard the preview path
+        // already guards, which this read simply hadn't caught up with.
+        const fields = Object.entries(type.fields).filter(([, spec]) => spec.type === fields_1.CONTENT_FIELD_TYPE.Relation && spec.relation);
+        const views = [];
+        for (let i = 0; i < fields.length; i += RELATION_FIELD_CONCURRENCY) {
+            views.push(...(await Promise.all(fields
+                .slice(i, i + RELATION_FIELD_CONCURRENCY)
+                .map(([name, spec]) => this.readField(type, row, name, spec, 1, pageSize, workspaceId)))));
+        }
+        const out = {};
+        fields.forEach(([name], i) => {
+            out[name] = views[i];
+        });
+        return out;
+    }
+    /**
+     * A capped relation preview for a whole **page** of entries — what the
+     * records table's relation columns render. Returns, per entry id, a
+     * `{ items, total }` view for each requested field.
+     *
+     * The batching is the point: this issues a constant number of queries **per
+     * relation field**, spanning every row on the page (`inArray(ownCol, ids)`),
+     * never one query per row. Contrast {@link readAll}, which is scoped to a
+     * single entry (`eq(ownCol, row.id)`) because the editor opens one record —
+     * calling it in a loop over a page would be a textbook N+1 (a 50-row page
+     * with two relation columns would cost 300 queries; this costs a handful).
+     *
+     * Each field contributes at most `pageSize` refs plus its true `total`, so a
+     * record holding thousands of links reads exactly one page here — the
+     * dropdown pages through the rest via {@link readField}. Only `fields` are
+     * resolved (the table's visible columns), so a hidden relation column costs
+     * nothing.
+     */
+    async previewForEntries(type, fields, rows, workspaceId, pageSize = exports.RELATION_PAGE_SIZE, visibility) {
+        const out = new Map();
+        const sourceIds = rows
+            .map((row) => row['id'])
+            .filter((id) => typeof id === 'string' && !!id);
+        const specs = fields
+            .map((name) => [name, type.fields[name]])
+            .filter((entry) => entry[1]?.type === fields_1.CONTENT_FIELD_TYPE.Relation &&
+            !!entry[1].relation);
+        if (!sourceIds.length || !specs.length)
+            return out;
+        for (const id of sourceIds)
+            out.set(id, {});
+        // Each relation field is an independent read, so fan them out
+        // concurrently rather than awaiting one before starting the next — a
+        // table with several relation columns pays one field's latency, not
+        // their sum (the same reasoning as `readAll`).
+        //
+        // Bounded, though: the pool is small and shared app-wide, and each
+        // field holds a connection for its window query and then another for
+        // `refsFor`. A type with many relation columns would otherwise let a
+        // couple of list requests occupy every connection, queueing unrelated
+        // traffic behind a records table's previews.
+        const views = [];
+        for (let i = 0; i < specs.length; i += RELATION_FIELD_CONCURRENCY) {
+            const batch = specs.slice(i, i + RELATION_FIELD_CONCURRENCY);
+            views.push(...(await Promise.all(batch.map(([name, spec]) => this.previewField(type, name, spec, rows, sourceIds, workspaceId, pageSize, visibility)))));
+        }
+        specs.forEach(([name], index) => {
+            for (const [sourceId, view] of views[index]) {
+                const bucket = out.get(sourceId);
+                if (bucket)
+                    bucket[name] = view;
+            }
+        });
+        return out;
+    }
+    /**
+     * Preview one relation field across the page, dispatched by storage form —
+     * the same three shapes {@link readField} handles: an owning single relation
+     * (FK on the row), a join-backed relation (owning many-to-many or the
+     * inverse of one), and an inverse-of-single (the owner's FK points back).
+     */
+    previewField(type, field, spec, rows, sourceIds, workspaceId, pageSize, visibility) {
+        const relation = spec.relation;
+        if (!relation)
+            return Promise.resolve(new Map());
+        if (!relation.many && !relation.inverse)
+            return this.previewSingle(relation.to(), field, rows, workspaceId, visibility);
+        const join = this.joinPlanFor(type, field, spec);
+        if (join)
+            return this.previewJoin(join, sourceIds, workspaceId, pageSize, visibility);
+        const inverse = this.inversePlanFor(spec);
+        if (inverse)
+            return this.previewInverse(inverse, sourceIds, workspaceId, pageSize, visibility);
+        return Promise.resolve(new Map());
+    }
+    /**
+     * Owning **single** relations: the FK already rides each page row, so this
+     * is one batched {@link refsFor} for every row's target at once — which also
+     * de-duplicates, so 50 posts sharing one author resolve that title once
+     * instead of 50 times.
+     */
+    async previewSingle(target, field, rows, workspaceId, visibility) {
+        const fkBySource = new Map();
+        for (const row of rows) {
+            const fk = row[field];
+            const id = row['id'];
+            if (typeof fk === 'string' && fk && typeof id === 'string')
+                fkBySource.set(id, fk);
+        }
+        const out = new Map();
+        if (!fkBySource.size)
+            return out;
+        const refs = await this.refsFor(target, [...fkBySource.values()], workspaceId, visibility);
+        const refById = new Map(refs.map((ref) => [ref.id, ref]));
+        for (const [sourceId, fk] of fkBySource) {
+            // Under a visibility restriction an unresolvable target is one the
+            // caller may not see, so the link is reported as absent rather than
+            // as a `missing` ref — a public consumer must not learn that a
+            // hidden record is linked here, and `total` must not count it.
+            if (visibility?.publishedOnly && !refById.has(fk)) {
+                out.set(sourceId, { items: [], total: 0 });
+                continue;
+            }
+            // `refsFor` is total — it yields a ref for every id, id-only and
+            // flagged `missing` when the target is gone. So the link is always
+            // represented (`total` counts the link, not whether its target
+            // resolved, exactly as `readField` reports it), and it is the flag,
+            // not an absent item, that tells the UI the target is unavailable.
+            const ref = refById.get(fk) ?? {
+                id: fk,
+                title: fk,
+                missing: true
+            };
+            out.set(sourceId, { items: [ref], total: 1 });
+        }
+        return out;
+    }
+    /**
+     * Join-backed relations (owning many-to-many, or the inverse of one), ranked
+     * in a single windowed pass: `row_number()` applies the per-source page cap
+     * and `count(*)` the true total, both partitioned by the owning id. That is
+     * what keeps a 600-link record to `pageSize` rows read instead of 600.
+     */
+    async previewJoin(join, sourceIds, workspaceId, pageSize, visibility) {
+        const cols = join.table;
+        const own = cols[join.ownCol];
+        const ref = cols[join.refCol];
+        const position = cols['position'];
+        const ranked = this.db
+            .select({
+            own,
+            ref,
+            rn: (0, drizzle_orm_1.sql) `row_number() over (partition by ${own} order by ${position} asc, ${ref} asc)`.as('rn'),
+            total: (0, drizzle_orm_1.sql) `count(*) over (partition by ${own})`.as('total')
+        })
+            .from(join.table)
+            .where((0, drizzle_orm_1.and)((0, drizzle_orm_1.inArray)(own, sourceIds), 
+        // Applied INSIDE the window, not after it: `count(*) over`
+        // is computed here, so filtering later would page over
+        // hidden links and report a total the caller can't reach.
+        this.visibleTargetIdsPredicate(ref, join.target, workspaceId, visibility)))
+            .as('ranked');
+        // The window aliases (`rn`/`own`) carry no column type through the
+        // subquery, so compare and order them as raw fragments rather than via
+        // `lte`/`asc`, whose overloads can't resolve an untyped alias.
+        const rows = (await this.db
+            .select()
+            .from(ranked)
+            .where((0, drizzle_orm_1.sql) `${ranked.rn} <= ${pageSize}`)
+            .orderBy((0, drizzle_orm_1.sql) `${ranked.own} asc, ${ranked.rn} asc`));
+        return this.groupPreview(rows, 'ref', await this.refsFor(join.target, rows.map((row) => row['ref']), workspaceId, visibility));
+    }
+    /**
+     * Inverse-of-single (one-to-many): the links are the owner rows whose FK
+     * points back at each page row. Windowed the same way, and scoped to the
+     * workspace with the soft-delete guard the inverse read side already applies.
+     */
+    async previewInverse(inverse, sourceIds, workspaceId, pageSize, visibility) {
+        const cols = inverse.table;
+        const fk = cols[inverse.fkCol];
+        const ranked = this.db
+            .select({
+            own: fk,
+            ref: cols['id'],
+            rn: (0, drizzle_orm_1.sql) `row_number() over (partition by ${fk} order by ${cols['createdAt']} asc, ${cols['id']} asc)`.as('rn'),
+            total: (0, drizzle_orm_1.sql) `count(*) over (partition by ${fk})`.as('total')
+        })
+            .from(inverse.table)
+            .where((0, drizzle_orm_1.and)((0, drizzle_orm_1.inArray)(fk, sourceIds), 
+        // The window reads the TARGET table here (the owners whose
+        // FK points back), so the restriction is a plain column
+        // predicate rather than a sub-select.
+        this.targetVisibleWhere(inverse.target, workspaceId, visibility)))
+            .as('ranked');
+        const rows = (await this.db
+            .select()
+            .from(ranked)
+            .where((0, drizzle_orm_1.sql) `${ranked.rn} <= ${pageSize}`)
+            .orderBy((0, drizzle_orm_1.sql) `${ranked.own} asc, ${ranked.rn} asc`));
+        return this.groupPreview(rows, 'ref', await this.refsFor(inverse.target, rows.map((row) => row['ref']), workspaceId, visibility));
+    }
+    /**
+     * Fold ranked window rows (already ordered by owner, then rank) into one
+     * `{ items, total }` view per owning id, resolving each link through the
+     * batched `refs`. Shared by the join-backed and inverse previews.
+     */
+    groupPreview(rows, refKey, refs) {
+        const refById = new Map(refs.map((ref) => [ref.id, ref]));
+        const out = new Map();
+        for (const row of rows) {
+            const sourceId = row['own'];
+            let view = out.get(sourceId);
+            if (!view) {
+                view = { items: [], total: Number(row['total']) };
+                out.set(sourceId, view);
+            }
+            // `refsFor` resolved every ranked id, so there is always a ref —
+            // id-only and flagged `missing` where the target is soft-deleted or
+            // out of workspace. Skipping it here would make `items` shorter
+            // than `total` and leave the cell showing a phantom `+N`.
+            const id = row[refKey];
+            view.items.push(refById.get(id) ?? { id, title: id, missing: true });
+        }
+        return out;
+    }
+    /**
+     * One page of a single relation field's links, ordered by `position`
+     * (owning) and resolved to display-ready refs (id + title). `row` is the
+     * editing entry (its FK columns back a single relation); pass it to avoid a
+     * re-read. Returns `{ items, total }`.
+     */
+    async readField(type, row, field, spec, page, pageSize, workspaceId, visibility) {
+        if (spec.type !== fields_1.CONTENT_FIELD_TYPE.Relation || !spec.relation)
+            return { items: [], total: 0 };
+        const offset = (page - 1) * pageSize;
+        // Owning single relation: the id is the row's FK value (0 or 1 link).
+        if (!spec.relation.many && !spec.relation.inverse) {
+            const fk = row[field];
+            const ids = typeof fk === 'string' && fk ? [fk] : [];
+            const items = page === 1
+                ? await this.refsFor(spec.relation.to(), ids, workspaceId, visibility)
+                : [];
+            // Under a visibility restriction an unresolved target is hidden,
+            // not `missing` — the link is reported as absent (see
+            // `previewSingle` for why `total` must not count it).
+            if (visibility?.publishedOnly && !items.some((ref) => !ref.missing))
+                return { items: [], total: 0 };
+            return { items, total: ids.length };
+        }
+        const join = this.joinPlanFor(type, field, spec);
+        if (join) {
+            const cols = join.table;
+            const selectable = join.table;
+            // One predicate for the page and the count, so a restricted read
+            // can't report a total its pages never reach.
+            const linkWhere = (0, drizzle_orm_1.and)((0, drizzle_orm_1.eq)(cols[join.ownCol], row['id']), this.visibleTargetIdsPredicate(selectable[join.refCol], join.target, workspaceId, visibility));
+            const [rows, [{ total }]] = await Promise.all([
+                this.db
+                    .select()
+                    .from(join.table)
+                    .where(linkWhere)
+                    .orderBy((0, drizzle_orm_1.asc)(cols['position']), (0, drizzle_orm_1.asc)(cols[join.refCol]))
+                    .limit(pageSize)
+                    .offset(offset),
+                this.db
+                    .select({ total: (0, drizzle_orm_1.count)() })
+                    .from(join.table)
+                    .where(linkWhere)
+            ]);
+            const ids = rows.map((r) => r[join.refCol]);
+            return {
+                items: await this.refsFor(join.target, ids, workspaceId, visibility),
+                total: Number(total)
+            };
+        }
+        const inverse = this.inversePlanFor(spec);
+        if (inverse) {
+            const cols = inverse.table;
+            const where = (0, drizzle_orm_1.and)((0, drizzle_orm_1.eq)(cols[inverse.fkCol], row['id']), this.targetVisibleWhere(inverse.target, workspaceId, visibility));
+            const [rows, [{ total }]] = await Promise.all([
+                this.db
+                    .select()
+                    .from(inverse.table)
+                    .where(where)
+                    .orderBy((0, drizzle_orm_1.asc)(cols['createdAt']), (0, drizzle_orm_1.asc)(cols['id']))
+                    .limit(pageSize)
+                    .offset(offset),
+                this.db
+                    .select({ total: (0, drizzle_orm_1.count)() })
+                    .from(inverse.table)
+                    .where(where)
+            ]);
+            return {
+                items: rows.map((r) => this.rowToRef(inverse.target, r)),
+                total: Number(total)
+            };
+        }
+        return { items: [], total: 0 };
+    }
+    /**
+     * The **full** ordered target-id list of every join-backed relation field
+     * (owning many-to-many and the inverse of one) for one entry, keyed by field
+     * name — the relation half of a revision snapshot. Unlike {@link readAll}
+     * (one page + a `total`, for the editor), this reads every link, since a
+     * snapshot must reconstruct the whole set. Runs on the passed executor (the
+     * save transaction), so it captures exactly what committed. Owning single
+     * relations aren't included — their FK already rides the entry's `values`.
+     * The join rows belong to the owning entry (scoped by `row.id`), so no
+     * workspace filter is needed here — the same as the join read in
+     * {@link readField}.
+     */
+    async snapshotLinks(exec, type, row) {
+        const out = {};
+        for (const [field, spec] of Object.entries(type.fields)) {
+            const join = this.joinPlanFor(type, field, spec);
+            if (!join)
+                continue; // single FK / inverse-of-single: not join-backed
+            const cols = join.table;
+            const rows = (await exec
+                .select()
+                .from(join.table)
+                .where((0, drizzle_orm_1.eq)(cols[join.ownCol], row['id']))
+                .orderBy((0, drizzle_orm_1.asc)(cols['position']), (0, drizzle_orm_1.asc)(cols[join.refCol])));
+            out[field] = rows.map((r) => r[join.refCol]);
+        }
+        return out;
+    }
+    // ---- writes ------------------------------------------------------------
+    /**
+     * Apply an incremental {@link RelationDelta} to one many/inverse relation
+     * field inside `tx`: validate the linked targets are in the workspace, unlink
+     * the removed pairs, append the new ones (`position = max+1` for the source,
+     * `ON CONFLICT DO NOTHING`), then renumber to `order` (owning side only).
+     * A single relation or an inverse-of-single owns no delta-writable link, so
+     * it's a no-op. Returns nothing — read the field back for the new state.
+     */
+    async applyDelta(tx, type, sourceId, field, delta, workspaceId, sourceLocale) {
+        const spec = type.fields[field];
+        const join = spec ? this.joinPlanFor(type, field, spec) : null;
+        if (!join)
+            return; // single / inverse-of-single: nothing to write here
+        // `by: 'localeGroup'` names translation groups rather than rows; resolve
+        // them to this source's own locale before anything touches the join.
+        const resolved = delta.by === 'localeGroup'
+            ? await this.resolveByLocaleGroup(tx, join.target, delta, workspaceId, field, sourceLocale)
+            : delta;
+        await this.assertTargets(tx, join.target, resolved.link ?? [], workspaceId, field, sourceLocale);
+        const cols = join.table;
+        const own = cols[join.ownCol];
+        const ref = cols[join.refCol];
+        if (resolved.unlink?.length) {
+            await tx
+                .delete(join.table)
+                .where((0, drizzle_orm_1.and)((0, drizzle_orm_1.eq)(own, sourceId), (0, drizzle_orm_1.inArray)(ref, resolved.unlink)));
+        }
+        // Append each new link at the end of its **source's** ordered list.
+        const links = dedupe(resolved.link);
+        if (links.length && join.ownCol === 'sourceId') {
+            // Owning relation: every new link shares this entry as its source, so
+            // read the append base once and insert them all in a single
+            // statement (position = base + index) instead of a SELECT+INSERT per
+            // link inside the locked transaction. Take the source's append lock
+            // first so a concurrent writer to the same list can't read the same
+            // `max(position)` and produce a duplicate position (the inverse side
+            // and a whole-set write both target this same physical list).
+            await this.lockSource(tx, join.table, sourceId);
+            const base = await this.nextPosition(tx, join.table, sourceId);
+            await tx
+                .insert(join.table)
+                .values(links.map((targetId, i) => ({
+                [join.ownCol]: sourceId,
+                [join.refCol]: targetId,
+                position: base + i
+            })))
+                .onConflictDoNothing();
+        }
+        else if (links.length) {
+            // Inverse relation: each link appends to a **different** owner row's
+            // list (its physical source is the linked owner, not this entry), so
+            // each needs its own append base — and its own append lock. Lock (and
+            // append) in a stable sorted order so two transactions touching an
+            // overlapping owner set can't deadlock by taking the locks in
+            // opposite orders.
+            for (const targetId of [...links].sort()) {
+                await this.lockSource(tx, join.table, targetId);
+                const position = await this.nextPosition(tx, join.table, targetId);
+                await tx
+                    .insert(join.table)
+                    .values({
+                    [join.ownCol]: sourceId,
+                    [join.refCol]: targetId,
+                    position
+                })
+                    .onConflictDoNothing();
+            }
+        }
+        // Reorder is the owning side's prerogative (its `source_id` axis); the
+        // inverse reuses the same rows and can't renumber them without corrupting
+        // the owner's order, so `order` is ignored there. One `CASE` update
+        // renumbers every listed target instead of a statement per id.
+        if (resolved.order?.length && join.ownCol === 'sourceId') {
+            // Renumber the whole list in one UPDATE — position = its index in
+            // `order`, via a CASE keyed on the ref id — instead of an UPDATE per
+            // id inside the locked transaction. The WHERE bounds it to this
+            // source's rows named in `order`; the `else` keeps any unmatched row
+            // untouched.
+            const order = resolved.order;
+            const cases = order.map((targetId, i) => (0, drizzle_orm_1.sql) `when ${ref} = ${targetId} then ${i}`);
+            await tx
+                .update(join.table)
+                .set({
+                position: (0, drizzle_orm_1.sql) `case ${drizzle_orm_1.sql.join(cases, (0, drizzle_orm_1.sql) ` `)} else ${cols['position']} end`
+            })
+                .where((0, drizzle_orm_1.and)((0, drizzle_orm_1.eq)(own, sourceId), (0, drizzle_orm_1.inArray)(ref, order)));
+        }
+    }
+    /**
+     * Replace a many-relation's links with exactly `values[field]` (array),
+     * position = array index — the **whole-set** write used only when a caller
+     * genuinely submits a relation **array** in the entry body (legacy / bulk).
+     * The editor uses {@link applyDelta} instead. Runs inside the entry's
+     * transaction. **Only an array counts**: a field that's absent or `null`
+     * (`coerceValues` stamps `null` onto every unset field) is left untouched, so
+     * a save that manages a relation purely through deltas can never have its
+     * links cleared here.
+     */
+    async writeLinks(tx, type, sourceId, values, workspaceId, sourceLocale) {
+        for (const [name, spec] of Object.entries(type.fields)) {
+            // Only a genuinely submitted **array** is a whole-set write. Anything
+            // else — key absent, or `null` (which `coerceValues` stamps onto
+            // every unset field) — means "not managing this relation via the
+            // whole-set path"; skip it so the incremental delta path owns it and
+            // a null can't be read as "clear all links".
+            if (!Array.isArray(values[name]))
+                continue;
+            const join = this.joinPlanFor(type, name, spec);
+            if (!join || join.ownCol !== 'sourceId')
+                continue; // owning many only
+            const ids = dedupe(values[name]);
+            await this.assertTargets(tx, join.target, ids, workspaceId, name, sourceLocale);
+            const cols = join.table;
+            const own = cols[join.ownCol];
+            const ref = cols[join.refCol];
+            await tx
+                .delete(join.table)
+                .where(ids.length
+                ? (0, drizzle_orm_1.and)((0, drizzle_orm_1.eq)(own, sourceId), (0, drizzle_orm_1.notInArray)(ref, ids))
+                : (0, drizzle_orm_1.eq)(own, sourceId));
+            if (ids.length) {
+                await tx
+                    .insert(join.table)
+                    .values(ids.map((id, i) => ({
+                    [join.ownCol]: sourceId,
+                    [join.refCol]: id,
+                    position: i
+                })))
+                    .onConflictDoNothing();
+            }
+        }
+    }
+    /**
+     * Count the links of one join-backed relation field for an entry — the
+     * `total` a read would report, without fetching or resolving any page. Runs
+     * on the passed executor (the write transaction when validating a just-saved
+     * entry, so it sees the delta's uncommitted rows). Returns 0 for a relation
+     * that owns no writable links from this side (single FK / inverse-of-single).
+     */
+    async countLinks(exec, type, row, field, spec, workspaceId) {
+        const join = this.joinPlanFor(type, field, spec);
+        if (join) {
+            const cols = join.table;
+            const [{ total }] = await exec
+                .select({ total: (0, drizzle_orm_1.count)() })
+                .from(join.table)
+                .where((0, drizzle_orm_1.eq)(cols[join.ownCol], row['id']));
+            return Number(total);
+        }
+        const inverse = this.inversePlanFor(spec);
+        if (inverse) {
+            const cols = inverse.table;
+            const [{ total }] = await exec
+                .select({ total: (0, drizzle_orm_1.count)() })
+                .from(inverse.table)
+                .where((0, drizzle_orm_1.and)((0, drizzle_orm_1.eq)(cols[inverse.fkCol], row['id']), (0, drizzle_orm_1.eq)(cols['workspaceId'], workspaceId), cols['deletedAt']
+                ? (0, drizzle_orm_1.isNull)(cols['deletedAt'])
+                : undefined));
+            return Number(total);
+        }
+        return 0;
+    }
+    // ---- helpers -----------------------------------------------------------
+    /**
+     * Take the transaction-scoped advisory lock for one physical source list
+     * (`<join table>:<sourceId>`), serializing every appender to that list so no
+     * two concurrent writes read the same `max(position)`. Auto-releases at
+     * commit/rollback. Keyed on the table name too, so distinct join tables that
+     * happen to share a source id don't falsely contend.
+     */
+    async lockSource(tx, table, sourceId) {
+        const key = `${(0, drizzle_orm_1.getTableName)(table)}:${sourceId}`;
+        await tx.execute((0, drizzle_orm_1.sql) `select pg_advisory_xact_lock(${RELATION_APPEND_LOCK_CLASS}, hashtext(${key}))`);
+    }
+    /** Next append position for a source: `max(position) + 1`, else 0. */
+    async nextPosition(tx, table, sourceId) {
+        const cols = table;
+        const [row] = await tx
+            .select({ max: (0, drizzle_orm_1.max)(cols['position']) })
+            .from(table)
+            .where((0, drizzle_orm_1.eq)(cols['sourceId'], sourceId));
+        const current = row?.max;
+        return current == null ? 0 : Number(current) + 1;
+    }
+    /**
+     * Public resolver for callers that hold **raw ids** rather than a live link
+     * set — the revision preview, which reads a historical snapshot's relation id
+     * lists and needs their display titles. Resolves the first `cap` ids (order
+     * preserved) via the same batched lookup as {@link refsFor}; the caller
+     * carries the true count separately and shows a "+N more" past the cap, so a
+     * relation with thousands of links is never resolved whole. A soft-deleted /
+     * foreign id yields a `missing` ref, never a title leak.
+     */
+    async resolveRefs(target, ids, workspaceId, cap) {
+        return this.refsFor(target, ids.slice(0, cap), workspaceId);
+    }
+    /**
+     * Resolve `ids` (in order) to display-ready refs via one lookup on the target
+     * type, scoped to the workspace. Ids with no **live** row drop to an id-only
+     * ref — a soft-deleted (paranoid) target is excluded here just as it is on
+     * the inverse read side, so a trashed record never surfaces its title on the
+     * owning side while it's hidden on the other.
+     */
+    async refsFor(target, ids, workspaceId, visibility) {
+        if (!ids.length)
+            return [];
+        const cols = target.table;
+        const rows = (await this.db
+            .select()
+            .from(target.table)
+            .where((0, drizzle_orm_1.and)((0, drizzle_orm_1.inArray)(cols['id'], [...new Set(ids)]), this.targetVisibleWhere(target, workspaceId, visibility))));
+        const byId = new Map(rows.map((row) => [row['id'], this.rowToRef(target, row)]));
+        // A ref is produced for *every* id, so a link is never silently
+        // dropped — `total` and `items` stay consistent. An id with no live row
+        // is flagged `missing` rather than passed off as a titled record: its
+        // `title` is only the raw id standing in, which the UI must not print.
+        return ids.map((id) => byId.get(id) ?? { id, title: id, missing: true });
+    }
+    /**
+     * The visibility predicate applied to a relation's target rows: the
+     * workspace scope, the soft-delete guard, and — only when the caller asks
+     * for it — the published-only restriction. One definition, so the row read
+     * (`refsFor`) and the windowed link reads that must *count* correctly can't
+     * disagree on what a visible target is.
+     */
+    targetVisibleWhere(target, workspaceId, visibility) {
+        const cols = target.table;
+        return (0, drizzle_orm_1.and)((0, drizzle_orm_1.eq)(cols['workspaceId'], workspaceId), cols['deletedAt'] ? (0, drizzle_orm_1.isNull)(cols['deletedAt']) : undefined, visibility?.publishedOnly && target.publishable
+            ? (0, drizzle_orm_1.eq)(cols['status'], content_type_1.ENTRY_STATUS.Published)
+            : undefined);
+    }
+    /**
+     * The id sub-select of a target's visible rows — how a link read that reads
+     * only the JOIN table (so has no target columns of its own) restricts to
+     * visible targets *inside* its window, keeping `total` honest. `undefined`
+     * when no extra restriction applies, so the predicate collapses away.
+     */
+    visibleTargetIds(target, workspaceId, visibility) {
+        if (!visibility?.publishedOnly)
+            return undefined;
+        const cols = target.table;
+        return this.db
+            .select({ id: cols['id'] })
+            .from(target.table)
+            .where(this.targetVisibleWhere(target, workspaceId, visibility));
+    }
+    /**
+     * `ref IN (visible target ids)`, or `undefined` when no restriction
+     * applies. Wraps {@link visibleTargetIds} for the join-table reads, whose
+     * only handle on the target is the id column in the join row.
+     */
+    visibleTargetIdsPredicate(refColumn, target, workspaceId, visibility) {
+        const visible = this.visibleTargetIds(target, workspaceId, visibility);
+        return visible ? (0, drizzle_orm_1.inArray)(refColumn, visible) : undefined;
+    }
+    /** Build a display ref from a full target row. */
+    rowToRef(target, row) {
+        const ref = {
+            id: row['id'],
+            title: (0, entry_row_1.entryTitle)(target, row)
+        };
+        const slug = (0, entry_row_1.entrySlug)(target, row);
+        if (slug)
+            ref.slug = slug;
+        if (target.publishable)
+            ref.status = row['status'];
+        return ref;
+    }
+    /**
+     * Rewrite a delta's translation-group ids into entry ids, picking each
+     * group's row in the **source entry's own locale**.
+     *
+     * This is the half of the cross-locale rule that makes it usable rather than
+     * merely strict. A client that thinks in stories holds one group id per
+     * story, not one entry id per language; without this it would have to keep a
+     * per-locale id map and pick the right entry for every write — and picking
+     * wrong is exactly what the rule then rejects. Here the server picks, and it
+     * is the only party that knows the source row's locale for certain.
+     *
+     * A group with no row in this locale is a **422** naming the field: the
+     * caller asked to link a story that has not been translated into this
+     * language yet, which is a real content gap rather than a bad request.
+     */
+    async resolveLocaleGroups(runner, target, groupIds, workspaceId, field, sourceLocale) {
+        if (!target.i18n || !sourceLocale) {
+            throw new common_1.BadRequestException(`Relation "${field}" cannot be addressed by locale group — ` +
+                (target.i18n
+                    ? 'this entry is not localized, so there is no locale to resolve into.'
+                    : `"${target.name}" is not a localized content type.`));
+        }
+        const unique = [...new Set(groupIds.filter(Boolean))];
+        if (!unique.length)
+            return new Map();
+        const cols = target.table;
+        const rows = (await runner
+            .select()
+            .from(target.table)
+            .where((0, drizzle_orm_1.and)((0, drizzle_orm_1.inArray)(cols['localeGroupId'], unique), (0, drizzle_orm_1.eq)(cols['workspaceId'], workspaceId), (0, drizzle_orm_1.eq)(cols['locale'], sourceLocale), target.paranoid ? (0, drizzle_orm_1.isNull)(cols['deletedAt']) : undefined)));
+        const byGroup = new Map(rows.map((row) => [
+            row['localeGroupId'],
+            row['id']
+        ]));
+        const missing = unique.filter((id) => !byGroup.has(id));
+        if (missing.length) {
+            throw new common_1.UnprocessableEntityException({
+                message: 'Entry validation failed',
+                issues: missing.map((groupId) => ({
+                    field,
+                    message: `no "${sourceLocale}" entry exists in translation group ` +
+                        `"${groupId}" on "${target.name}" — translate that record ` +
+                        'into this locale before linking it.'
+                }))
+            });
+        }
+        return byGroup;
+    }
+    /**
+     * The **lenient** counterpart of {@link resolveLocaleGroups}: given target
+     * ids held by one row, find the equivalent id in each of `locales` — the
+     * row of the same translation group, in that language.
+     *
+     * Returns `locale → (given id → that locale's id)`. A pair with no row in a
+     * locale is simply **absent** rather than an error, which is the whole
+     * difference. `resolveLocaleGroups` answers an explicit API call naming a
+     * group, where a missing translation is a request to reject; this answers
+     * the implicit sibling sync, where it is a content gap on the *target* and
+     * failing would mean an English save could not be saved until somebody
+     * translated a tag.
+     *
+     * Two queries regardless of how many ids or locales are asked for: one to
+     * read the given ids' groups, one to read those groups' rows in the wanted
+     * locales. Soft-deleted rows are excluded from the **destination** side —
+     * required for determinism, since the `(locale_group_id, locale)` unique
+     * index is partial (`WHERE deleted_at IS NULL`) on a paranoid type, so
+     * trashed rows can legitimately repeat a pair. The source lookup is not
+     * filtered: a link to a trashed row still has a group, and dropping it
+     * would silently unlink siblings whenever a target went to the bin.
+     */
+    async equivalentIdsByLocale(exec, target, ids, locales, workspaceId) {
+        const out = new Map();
+        for (const locale of locales)
+            out.set(locale, new Map());
+        const unique = [...new Set(ids)].filter(Boolean);
+        if (!target.i18n || !unique.length || !locales.length)
+            return out;
+        const cols = target.table;
+        const sourceRows = (await exec
+            .select()
+            .from(target.table)
+            .where((0, drizzle_orm_1.and)((0, drizzle_orm_1.inArray)(cols['id'], unique), (0, drizzle_orm_1.eq)(cols['workspaceId'], workspaceId))));
+        const groupOf = new Map(sourceRows.map((row) => [
+            row['id'],
+            row['localeGroupId']
+        ]));
+        const groups = [...new Set(groupOf.values())].filter(Boolean);
+        if (!groups.length)
+            return out;
+        const siblingRows = (await exec
+            .select()
+            .from(target.table)
+            .where((0, drizzle_orm_1.and)((0, drizzle_orm_1.inArray)(cols['localeGroupId'], groups), (0, drizzle_orm_1.inArray)(cols['locale'], [...locales]), (0, drizzle_orm_1.eq)(cols['workspaceId'], workspaceId), target.paranoid ? (0, drizzle_orm_1.isNull)(cols['deletedAt']) : undefined)));
+        // Keyed by group AND locale, since one group contributes at most one
+        // row per language and the pair is what a sibling asks for.
+        const byGroupLocale = new Map();
+        for (const row of siblingRows) {
+            byGroupLocale.set(groupLocaleKey(row['localeGroupId'], row['locale']), row['id']);
+        }
+        for (const locale of locales) {
+            const bucket = out.get(locale);
+            for (const id of unique) {
+                const group = groupOf.get(id);
+                if (!group)
+                    continue;
+                const equivalent = byGroupLocale.get(groupLocaleKey(group, locale));
+                if (equivalent)
+                    bucket.set(id, equivalent);
+            }
+        }
+        return out;
+    }
+    /**
+     * Replace one join-backed relation field's links for `sourceId` with
+     * exactly `targetIds`, in order — the primitive the locale sibling sync
+     * writes through. Returns whether anything actually changed, so a caller
+     * can leave an already-correct sibling untouched (and unversioned).
+     *
+     * Deliberately **not** {@link applyDelta}: that is an incremental edit from
+     * a client that knows what it changed, while a sync knows only the desired
+     * end state. Deliberately not {@link writeLinks} either — that reads its ids
+     * out of a values bag and re-validates targets the caller may not have.
+     * Here the ids came from a sibling row that already passed those checks.
+     */
+    async replaceLinks(tx, type, sourceId, field, targetIds) {
+        const spec = type.fields[field];
+        const join = spec ? this.joinPlanFor(type, field, spec) : null;
+        if (!join || join.ownCol !== 'sourceId')
+            return false;
+        const cols = join.table;
+        const own = cols[join.ownCol];
+        const ref = cols[join.refCol];
+        const desired = dedupe([...targetIds]);
+        // Compare before writing: an unchanged sibling must not be rewritten,
+        // or every save would re-version the whole translation group.
+        const currentRows = (await tx
+            .select()
+            .from(join.table)
+            .where((0, drizzle_orm_1.eq)(own, sourceId))
+            .orderBy((0, drizzle_orm_1.asc)(cols['position']), (0, drizzle_orm_1.asc)(ref)));
+        const current = currentRows.map((row) => row[join.refCol]);
+        if (current.length === desired.length &&
+            current.every((id, index) => id === desired[index])) {
+            return false;
+        }
+        await tx.delete(join.table).where((0, drizzle_orm_1.eq)(own, sourceId));
+        if (desired.length) {
+            await tx.insert(join.table).values(desired.map((targetId, index) => ({
+                [join.ownCol]: sourceId,
+                [join.refCol]: targetId,
+                position: index
+            })));
+        }
+        return true;
+    }
+    /**
+     * The ordered link ids of **one** join-backed relation field, read on the
+     * passed executor. {@link snapshotLinks} reads every field at once for a
+     * revision; the sync needs one field at a time, and only the ones that
+     * actually propagate.
+     */
+    async linkIdsOf(exec, type, sourceId, field) {
+        const spec = type.fields[field];
+        const join = spec ? this.joinPlanFor(type, field, spec) : null;
+        if (!join)
+            return [];
+        const cols = join.table;
+        const rows = (await exec
+            .select()
+            .from(join.table)
+            .where((0, drizzle_orm_1.eq)(cols[join.ownCol], sourceId))
+            .orderBy((0, drizzle_orm_1.asc)(cols['position']), (0, drizzle_orm_1.asc)(cols[join.refCol])));
+        return rows.map((row) => row[join.refCol]);
+    }
+    /** {@link resolveLocaleGroups} applied to a delta's three id arrays. */
+    async resolveByLocaleGroup(tx, target, delta, workspaceId, field, sourceLocale) {
+        const byGroup = await this.resolveLocaleGroups(tx, target, [
+            ...(delta.link ?? []),
+            ...(delta.unlink ?? []),
+            ...(delta.order ?? [])
+        ], workspaceId, field, sourceLocale);
+        // `unlink` maps through the same table: a group that resolves to a row
+        // which was never linked is simply a no-op delete, as it is by id.
+        const map = (ids) => ids?.map((groupId) => byGroup.get(groupId));
+        return {
+            ...(map(delta.link) ? { link: map(delta.link) } : {}),
+            ...(map(delta.unlink) ? { unlink: map(delta.unlink) } : {}),
+            ...(map(delta.order) ? { order: map(delta.order) } : {})
+        };
+    }
+    /**
+     * Verify every id to be linked exists **in the same workspace** (the join FK
+     * has no workspace constraint of its own). A missing or cross-workspace id is
+     * a uniform 422 — indistinguishable from an invalid id, so no enumeration
+     * signal.
+     *
+     * When `sourceLocale` is given and the target type is localized, the link is
+     * additionally required to stay **inside one locale**. Two i18n types linked
+     * across locales is a broken model, not a preference: the English article
+     * would render the German tag, and because join links are per-row rather
+     * than synced across a translation group, nothing would ever repair it. The
+     * admin has always enforced this in its picker (which offers same-locale
+     * candidates only) — this is the same rule where it cannot be bypassed by
+     * talking to the API directly.
+     *
+     * The caller passes the **source row's own** locale, so the rule reads off
+     * the row being written rather than off a request parameter that may name a
+     * different one. `undefined` (a non-i18n owner) disables the check.
+     */
+    async assertTargets(tx, target, ids, workspaceId, field, sourceLocale) {
+        const unique = [...new Set(ids)].filter((id) => !!id);
+        if (!unique.length)
+            return;
+        const cols = target.table;
+        // Read on the write transaction's own connection (not `this.db`, a
+        // separate pooled connection), so the existence check shares the txn's
+        // snapshot and the workspace advisory lock the write path holds.
+        const rows = (await tx
+            .select()
+            .from(target.table)
+            .where((0, drizzle_orm_1.and)((0, drizzle_orm_1.inArray)(cols['id'], unique), (0, drizzle_orm_1.eq)(cols['workspaceId'], workspaceId))));
+        const present = new Set(rows.map((r) => r['id']));
+        const missing = unique.filter((id) => !present.has(id));
+        if (missing.length) {
+            throw new common_1.UnprocessableEntityException({
+                message: 'Entry validation failed',
+                issues: missing.map(() => ({
+                    field,
+                    message: 'must reference an existing entry'
+                }))
+            });
+        }
+        assertSameLocale(rows, target, field, sourceLocale);
+    }
+    /**
+     * The join-table plan for a relation field, or `null` when it owns no join
+     * table (an owning single relation, or an inverse-of-single). An owning
+     * many-relation uses its own join table (`source→target`); an inverse of a
+     * many-to-many reuses the owning side's join table with the roles swapped.
+     */
+    joinPlanFor(type, field, spec) {
+        if (spec.type !== fields_1.CONTENT_FIELD_TYPE.Relation || !spec.relation)
+            return null;
+        const relation = spec.relation;
+        if (relation.inverse) {
+            const owner = relation.to();
+            const owningField = owner.fields[relation.inverse.field];
+            if (!owningField?.relation?.many)
+                return null; // inverse-of-single
+            return {
+                table: owner.joinTables[relation.inverse.field],
+                ownCol: 'targetId',
+                refCol: 'sourceId',
+                target: relation.to()
+            };
+        }
+        if (relation.many) {
+            return {
+                table: type.joinTables[field],
+                ownCol: 'sourceId',
+                refCol: 'targetId',
+                target: relation.to()
+            };
+        }
+        return null;
+    }
+    /**
+     * The inverse-of-single (one-to-many) plan for a relation field, or `null`:
+     * it reads the owner rows whose FK points back at the editing record, and
+     * owns no writable link from this side.
+     */
+    inversePlanFor(spec) {
+        if (spec.type !== fields_1.CONTENT_FIELD_TYPE.Relation ||
+            !spec.relation?.inverse)
+            return null;
+        const owner = spec.relation.to();
+        const owningField = owner.fields[spec.relation.inverse.field];
+        if (owningField?.relation?.many)
+            return null; // handled as a join plan
+        return {
+            table: owner.table,
+            fkCol: spec.relation.inverse.field,
+            target: owner
+        };
+    }
+};
+exports.RelationLinkService = RelationLinkService;
+exports.RelationLinkService = RelationLinkService = tslib_1.__decorate([
+    (0, common_1.Injectable)(),
+    tslib_1.__param(0, (0, database_1.InjectDatabase)()),
+    tslib_1.__metadata("design:paramtypes", [Object])
+], RelationLinkService);
+/**
+ * The composite map key for "this translation group, in this locale".
+ *
+ * A named helper rather than an inline template so the two call sites cannot
+ * drift apart on the separator — and so the separator is a visible character.
+ * `|` cannot appear in either half: a `locale_group_id` is a uuid, and a locale
+ * slug is `^[a-z]{2,3}(-[a-z0-9]+)*$`, so the pair is unambiguous.
+ */
+function groupLocaleKey(localeGroupId, locale) {
+    return `${localeGroupId}|${locale}`;
+}
+/** De-duplicate a list of ids, preserving order and dropping empties. */
+function dedupe(value) {
+    const seen = new Set();
+    const out = [];
+    for (const item of value ?? []) {
+        if (typeof item === 'string' && item && !seen.has(item)) {
+            seen.add(item);
+            out.push(item);
+        }
+    }
+    return out;
+}