@orthacms/content-server 0.0.0-reserve.0

package/dist/lib/entries/types/entry-list-view.d.ts

@@ -0,0 +1,205 @@
+import type { EntryStatus } from '../../types/content-type';
+/** Re-exported so list-view consumers get publish state from one source. */
+export type { EntryStatus };
+/**
+ * One entry as served to the admin records table: the storage envelope plus a
+ * `values` bag keyed by field name. Mirrors the admin's `EntryRecord` — the
+ * wire contract the dynamic table renders from. `status` is present only on
+ * `publishable` types (see {@link EntryEnvelope}).
+ */
+export interface EntryRecord {
+    /** Entry id (the `:entryId` route segment). */
+    id: string;
+    /** Publication status — only on `publishable` types. */
+    status?: EntryStatus;
+    /**
+     * ISO timestamp of when this entry last went live, or `null` if it never has
+     * (or was explicitly unpublished) — only on `publishable` types.
+     *
+     * It **survives an edit**: saving a published entry moves it back to `draft`
+     * while its published *version* stays live in history, so `status: 'draft'`
+     * with a `publishedAt` means "published content plus unpublished changes"
+     * (the admin's **Modified** state), which a plain draft has never had.
+     */
+    publishedAt?: string | null;
+    /** Locale slug of this row — only on `i18n` types. */
+    locale?: string;
+    /** Shared translation-group id — only on `i18n` types. */
+    localeGroupId?: string;
+    /** ISO creation timestamp. */
+    createdAt: string;
+    /** ISO last-updated timestamp. */
+    updatedAt: string;
+    /** Field values, keyed by field name. */
+    values: Record<string, unknown>;
+    /**
+     * A capped **preview** of this entry's relation links, keyed by relation
+     * field name — present only when the caller opts in with
+     * `?relations=preview&relationFields=<names>` (the records table, for its
+     * visible relation columns). Each field carries at most one page of refs
+     * plus its true `total`, so a record with thousands of links contributes one
+     * page here; the table's dropdown pages through the rest via
+     * `GET /content/:type/:id/relations/:field`.
+     *
+     * Additive to {@link values}, never a replacement: an owning single
+     * relation still passes through `values` as its raw FK, which is what a save
+     * submits back.
+     */
+    relations?: Record<string, RelationFieldView>;
+}
+/** The paginated envelope, matching the admin list-page convention. */
+export interface EntryListView {
+    items: EntryRecord[];
+    total: number;
+    page: number;
+    pageSize: number;
+}
+/**
+ * One linked record on a relation field, resolved for display: the target id
+ * plus a pre-derived {@link EntryRecord} title (and publish `status` for a
+ * publishable target). Lets the admin render an assigned relation by title —
+ * and seed the form value with the id — without a per-id round-trip.
+ */
+export interface RelationRef {
+    /** The linked entry's id (what a save submits back). */
+    id: string;
+    /** Display title (first text/select field, else the id). */
+    title: string;
+    /**
+     * URL-ish handle for the record — the value of its slug field (a field with
+     * `admin.widget === 'slug'`, else one literally named `slug`) when non-empty.
+     * Absent when the target has no slug field; the admin falls back to a
+     * slugified title for display.
+     */
+    slug?: string;
+    /** Publish status — present only for publishable target types. */
+    status?: EntryStatus;
+    /**
+     * The link exists but its target row could not be resolved — soft-deleted,
+     * or outside the workspace. `title` then stands in as the raw id, which is
+     * not displayable, so the ref is flagged and the admin renders it as an
+     * unavailable record instead of printing an FK.
+     */
+    missing?: true;
+}
+/**
+ * One attached asset on a media field, resolved for display: the asset id plus
+ * the facts the admin renders (name, thumbnail url, kind/MIME). Mirrors
+ * {@link RelationRef} — an asset that can't be resolved (deleted / cross-
+ * workspace) is an id-only ref flagged `missing`, so the UI shows "Unavailable
+ * asset" rather than a raw uuid.
+ */
+export interface MediaRef {
+    /** The asset id (what a save submits back). */
+    id: string;
+    /** Original file name / display label. */
+    name: string;
+    /** Raw-stream route for the **original** bytes (download, or the fallback). */
+    url: string;
+    /**
+     * Route for the small (~320px) derivative the media plugin generated, when
+     * there is one — what an editor tile or a version-preview chip renders, so a
+     * form full of media doesn't pull full-size originals. Absent for a
+     * non-image, an SVG, or an image too small to derive.
+     */
+    thumbUrl?: string;
+    /** Route for the larger (~1280px) derivative, same caveats as {@link thumbUrl}. */
+    previewUrl?: string;
+    /** Coarse kind — image/video/audio/document/archive. */
+    kind: string;
+    /** MIME type, e.g. `image/png`. */
+    mimeType: string;
+    /**
+     * The text alternative **this usage** publishes with — the value's own
+     * `alt` where it has one, the asset row's default otherwise, and `''` when
+     * the usage is marked {@link decorative} (`ORT-83`).
+     */
+    alt?: string | null;
+    /**
+     * The author marked this usage purely presentational, so it publishes with
+     * an empty `alt` and a screen reader skips it.
+     *
+     * Distinct from an absent {@link alt}, which means nobody has answered the
+     * question yet — the distinction WCAG 1.1.1 turns on, and what a required
+     * media field's publish gate checks for.
+     */
+    decorative?: true;
+    /** The asset could not be resolved (deleted or outside the workspace). */
+    missing?: true;
+}
+/**
+ * One relation field's links: a **windowed** page of resolved refs plus the
+ * `total` count across the whole set. A many/inverse relation can hold far more
+ * links than fit in one payload, so the editor pages through them (infinite
+ * scroll) rather than loading every id; a single relation is a `total` of 0/1.
+ */
+export interface RelationFieldView {
+    items: RelationRef[];
+    /** Total links on this field (across all pages). */
+    total: number;
+}
+/**
+ * The relation links of one entry, keyed by relation field name — every relation
+ * field (owning single/many **and** inverse back-references), each a **first
+ * page** of links + its total, so the editor has one source for what's linked
+ * and its counts. Further pages come from the per-field read.
+ */
+export interface EntryRelationsView {
+    relations: Record<string, RelationFieldView>;
+}
+/**
+ * The attached assets of one entry, keyed by media field name — each field's
+ * ordered {@link MediaRef}s (name / thumbnail url / kind), so the editor renders
+ * assigned media by thumbnail without a per-id round-trip. Empty when no media
+ * resolver is bound. A `multiple` field's list preserves the stored order, with
+ * a deleted/cross-workspace asset kept as a `missing` ref.
+ */
+export interface EntryMediaView {
+    media: Record<string, MediaRef[]>;
+}
+/**
+ * An incremental change to one many/inverse relation field — the wire body of
+ * `POST /content/:type/:id/relations/:field`. Only the diff crosses the wire, so
+ * a relation with thousands of links never has to be sent (or held) in full.
+ * `order` renumbers the listed ids (owning many-relations only); it's ignored
+ * for the inverse side, which doesn't own the order.
+ */
+export interface RelationDelta {
+    /** Target ids to link (append; re-linking an existing pair is a no-op). */
+    link?: string[];
+    /** Target ids to unlink. */
+    unlink?: string[];
+    /** Desired order of the listed target ids (owning many-relations only). */
+    order?: string[];
+    /**
+     * The target of an owning **single** relation — the one-value counterpart of
+     * `link`, and the only key a single relation accepts here. `null` clears it.
+     *
+     * A single relation is a column on the row, so it is normally set through
+     * `values`. It is settable here too for one reason: `values` carries the
+     * content type's own contract, where a relation field means *an entry id* —
+     * there is no room in it for `by`, so without this key a single relation
+     * could not be addressed by translation group at all while a many-relation
+     * could. Sending the same field in both `values` and here is a 400.
+     */
+    set?: string | null;
+    /**
+     * How the uuids above name their targets. `id` (the default) is a literal
+     * entry id; `localeGroup` reads them as **translation group** ids, each
+     * resolved to that group's row in the *source entry's own locale*.
+     *
+     * The group form exists because a client that holds "this tag" as a concept
+     * holds its group id, not one id per language — and links may not cross
+     * locales, so linking by id forces it to keep a per-locale id map and pick
+     * the right one for every write. With `localeGroup` the server picks, which
+     * is the only party that knows the source row's locale for certain.
+     *
+     * Only meaningful when both sides are localized; anything else is a 400.
+     */
+    by?: RelationDeltaAddressing;
+}
+/** @see RelationDelta.by */
+export declare const RELATION_DELTA_ADDRESSING: readonly ["id", "localeGroup"];
+/** @see RelationDelta.by */
+export type RelationDeltaAddressing = (typeof RELATION_DELTA_ADDRESSING)[number];
+//# sourceMappingURL=entry-list-view.d.ts.map

package/dist/lib/entries/types/entry-list-view.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entry-list-view.d.ts","sourceRoot":"","sources":["../../../../src/lib/entries/types/entry-list-view.ts"],"names":[],"mappings":"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"}

package/dist/lib/entries/types/entry-list-view.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RELATION_DELTA_ADDRESSING = void 0;
+/** @see RelationDelta.by */
+exports.RELATION_DELTA_ADDRESSING = ['id', 'localeGroup'];

package/dist/lib/entries/types/filter-surface.d.ts

@@ -0,0 +1,35 @@
+import type { ScalarFieldType } from '@orthacms/utils-server';
+/**
+ * One filterable path offered to the admin's query builder, produced by
+ * `buildEntryFilterSurface`. Flat and dotted (`author.name`) — the same
+ * string the query-builder puts on the wire as a rule's `field`, walked
+ * segment-by-segment by `parseFilterTree` against the sibling
+ * `FilterSchema`. The two are built in one traversal so they cannot drift.
+ */
+export interface WireFilterField {
+    /** Dotted path — `author.name`. Serialised verbatim as a rule `field`. */
+    path: string;
+    /** Human label for the leaf segment (the relation label for an `id` picker). */
+    label: string;
+    /** Coercion type; matches the admin's `FIELD_TYPE`. */
+    type: ScalarFieldType;
+    /** Allowed values — present only for `enum`. */
+    enumValues?: readonly string[];
+    /**
+     * Breadcrumb of relation labels, root-first — `['Author']` for
+     * `author.name`, `['Author','Company']` for `author.company.name`.
+     * Empty for a root field. Groups the field picker; never serialised.
+     */
+    group: readonly string[];
+    /**
+     * For a relation's own `id` field: the target content type name. Tells
+     * the admin to render a record picker instead of a raw uuid input.
+     * `author.id` → `'author'`.
+     */
+    relationTarget?: string;
+}
+/** Response body of `GET /content-schema/:name/filter-fields`. */
+export interface FilterFieldsResponse {
+    fields: WireFilterField[];
+}
+//# sourceMappingURL=filter-surface.d.ts.map

package/dist/lib/entries/types/filter-surface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filter-surface.d.ts","sourceRoot":"","sources":["../../../../src/lib/entries/types/filter-surface.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAE9D;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC5B,0EAA0E;IAC1E,IAAI,EAAE,MAAM,CAAC;IACb,gFAAgF;IAChF,KAAK,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,IAAI,EAAE,eAAe,CAAC;IACtB,gDAAgD;IAChD,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B;;;;OAIG;IACH,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,kEAAkE;AAClE,MAAM,WAAW,oBAAoB;IACjC,MAAM,EAAE,eAAe,EAAE,CAAC;CAC7B"}

package/dist/lib/entries/types/filter-surface.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/lib/extension/entry-extension-boot-check.d.ts

@@ -0,0 +1,16 @@
+import { type OnApplicationBootstrap } from '@nestjs/common';
+import type { ContentTypeRegistry } from '../registry/content-type-registry';
+import { type ContentEntryExtension } from './entry-extension';
+/**
+ * Fails boot when a registered content type declares `i18n: true` but no
+ * {@link ContentEntryExtension} is bound. Without an extension nothing stamps
+ * the NOT NULL `locale` column, so the first create would 500 — a clear boot
+ * error ("register the i18n plugin") beats a broken first request.
+ */
+export declare class EntryExtensionBootCheck implements OnApplicationBootstrap {
+    private readonly registry;
+    private readonly extension?;
+    constructor(registry: ContentTypeRegistry, extension?: ContentEntryExtension | undefined);
+    onApplicationBootstrap(): void;
+}
+//# sourceMappingURL=entry-extension-boot-check.d.ts.map

package/dist/lib/extension/entry-extension-boot-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entry-extension-boot-check.d.ts","sourceRoot":"","sources":["../../../src/lib/extension/entry-extension-boot-check.ts"],"names":[],"mappings":"AAAA,OAAO,EAIH,KAAK,sBAAsB,EAC9B,MAAM,gBAAgB,CAAC;AAExB,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mCAAmC,CAAC;AAC7E,OAAO,EAEH,KAAK,qBAAqB,EAC7B,MAAM,mBAAmB,CAAC;AAE3B;;;;;GAKG;AACH,qBACa,uBAAwB,YAAW,sBAAsB;IAG9D,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAGzB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC;gBAHV,QAAQ,EAAE,mBAAmB,EAG7B,SAAS,CAAC,EAAE,qBAAqB,YAAA;IAGtD,sBAAsB,IAAI,IAAI;CAcjC"}

package/dist/lib/extension/entry-extension-boot-check.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EntryExtensionBootCheck = void 0;
+const tslib_1 = require("tslib");
+const common_1 = require("@nestjs/common");
+const content_tokens_1 = require("../content.tokens");
+const entry_extension_1 = require("./entry-extension");
+/**
+ * Fails boot when a registered content type declares `i18n: true` but no
+ * {@link ContentEntryExtension} is bound. Without an extension nothing stamps
+ * the NOT NULL `locale` column, so the first create would 500 — a clear boot
+ * error ("register the i18n plugin") beats a broken first request.
+ */
+let EntryExtensionBootCheck = class EntryExtensionBootCheck {
+    registry;
+    extension;
+    constructor(registry, extension) {
+        this.registry = registry;
+        this.extension = extension;
+    }
+    onApplicationBootstrap() {
+        if (this.extension)
+            return;
+        const orphaned = this.registry
+            .all()
+            .filter((type) => type.i18n)
+            .map((type) => `"${type.name}"`);
+        if (orphaned.length) {
+            throw new Error(`Content type(s) ${orphaned.join(', ')} declare i18n: true, but no ` +
+                `CONTENT_ENTRY_EXTENSION is bound. Register a localization plugin ` +
+                `(e.g. I18nServerPlugin) after ContentPlugin, or drop the flag.`);
+        }
+    }
+};
+exports.EntryExtensionBootCheck = EntryExtensionBootCheck;
+exports.EntryExtensionBootCheck = EntryExtensionBootCheck = tslib_1.__decorate([
+    (0, common_1.Injectable)(),
+    tslib_1.__param(0, (0, content_tokens_1.InjectContentRegistry)()),
+    tslib_1.__param(1, (0, common_1.Optional)()),
+    tslib_1.__param(1, (0, common_1.Inject)(entry_extension_1.CONTENT_ENTRY_EXTENSION)),
+    tslib_1.__metadata("design:paramtypes", [Function, Object])
+], EntryExtensionBootCheck);

package/dist/lib/extension/entry-extension.d.ts

@@ -0,0 +1,225 @@
+/**
+ * The entries **extension port** — the seam through which a downstream plugin
+ * (e.g. a localization plugin) extends the generic entries pipeline without
+ * this package knowing its domain. Content-server *declares* the port and
+ * consults it optionally (`@Optional()` injection) from {@link EntriesService}
+ * and {@link EntryWriterService}; the extending plugin *binds* an
+ * implementation to {@link CONTENT_ENTRY_EXTENSION} in its own module — the
+ * same inversion as identity's `CONTENT_CATALOG`, with the roles swapped.
+ *
+ * Every method is called unconditionally when an extension is bound, for every
+ * content type — an implementation MUST no-op (return `undefined` / `{}`) for
+ * types it doesn't apply to, so binding an extension never changes the
+ * behavior of unrelated types.
+ *
+ * NestJS-free on purpose (types + a Symbol only): implementations live in
+ * other packages, and keeping decorators out means this file could move into
+ * a decorator-free subpath without churn.
+ *
+ * Currently a **single binding**: one provider per app. If a second extension
+ * ever needs to coexist, bind a composite that fans out to both — the port's
+ * shape (SQL fragments AND-ed, column bags merged) composes cleanly.
+ */
+import type { SQL } from 'drizzle-orm';
+import type { Database } from '@orthacms/database';
+import type { FieldSchema, ParsedRule } from '@orthacms/utils-server';
+import type { AnyContentType } from '../types/content-type';
+/** DI token an extension plugin binds its {@link ContentEntryExtension} to. */
+export declare const CONTENT_ENTRY_EXTENSION: unique symbol;
+/**
+ * Extension-owned request parameters, forwarded verbatim from the wire
+ * (`?locale=` / `?localeFallback=` on reads, `body.locale` on create).
+ * Content-server declares them on its DTOs — the strict global
+ * `ValidationPipe` rejects undeclared keys, so a generic bag isn't possible —
+ * but never interprets them; their semantics live entirely behind the port.
+ */
+export interface EntryScopeParams {
+    /** Locale slug the request targets; validated by the extension. */
+    locale?: string;
+    /**
+     * `'default'` widens {@link ContentEntryExtension.listScope} to fall back
+     * to the default locale where the requested one is missing (used by the
+     * admin's relation picker); absent = strict.
+     */
+    localeFallback?: string;
+    /**
+     * On **create**, the existing translation group the new row joins (making
+     * it a sibling). Absent → the row starts its own fresh group. Validated by
+     * the extension against the workspace.
+     */
+    localeGroupId?: string;
+}
+/**
+ * Which write {@link ContentEntryExtension.afterUpdate} is running inside.
+ *
+ * The two are not symmetric, which is why the hook has to be told them apart.
+ * On an **update** the edited row is the authority: what it now holds is what
+ * the extension propagates outward. On a **create** it is the opposite — the
+ * new row is the one with gaps to fill (a translation arrives carrying the
+ * source's shared values but none of its links), so an extension that treated
+ * it as the authority would push those gaps onto rows that were already right.
+ */
+export interface EntryWriteContext {
+    /** True when the row was just INSERTed; false on an update. */
+    created: boolean;
+}
+/**
+ * What a write of one entry would **also** rewrite, beyond the row addressed.
+ *
+ * The entries pipeline does not know that a save can travel: an extension's
+ * {@link ContentEntryExtension.afterUpdate} may rewrite a whole set of related
+ * rows (the i18n plugin propagates a type's *shared* fields onto every sibling
+ * in the translation group), and the caller that asked for "change this one
+ * entry" has no way to see it. Everywhere a person types the change that is
+ * tolerable — they are looking at the record and its language switcher. It is
+ * not tolerable where an **agent** composes the change and it applies with no
+ * human in between ([ADR-0009](../../../../../../docs/adr/0009-copilot-applies-directly.md)),
+ * which is what this exists for: the copilot's propose tools ask before they
+ * draft, so the receipt names the blast radius instead of reading as a
+ * single-entry edit.
+ *
+ * It describes; it does not decide. Propagating shared values IS the contract —
+ * "shared" means shared — so refusing the write would take away the only way to
+ * edit a shared field at all. The defect was that nobody was told.
+ */
+export interface EntryWriteFanout {
+    /**
+     * The names of the fields **in the submitted values** whose value travels
+     * to the other rows — a subset of what was asked for, never the whole type.
+     */
+    fields: readonly string[];
+    /**
+     * The other rows, named the way a person would recognise them (locale
+     * slugs, for the i18n extension). Never empty: an extension returns
+     * `undefined` rather than an empty description.
+     */
+    locales: readonly string[];
+}
+/** Context handed to {@link EntryFilterExtension.resolve} with each rule. */
+export interface EntryFilterContext {
+    /** The content type the list request targets. */
+    type: AnyContentType;
+    /** The requesting workspace — every emitted subquery MUST scope to it. */
+    workspaceId: string;
+}
+/**
+ * Virtual filter fields an extension contributes to one type's `?filter=`
+ * schema — e.g. "has locale", "locale count" — resolved to SQL subqueries by
+ * the extension itself via the filter engine's `resolveExtension` hook.
+ */
+export interface EntryFilterExtension {
+    /**
+     * Parser declarations for the virtual fields, merged into the type's
+     * `FilterSchema.fields` and registered as `extensionFields` (so the
+     * translator routes them here instead of to a column).
+     */
+    fields: FieldSchema;
+    /** Translate one virtual-field rule into a SQL predicate. */
+    resolve(rule: ParsedRule, context: EntryFilterContext): Promise<SQL>;
+}
+/**
+ * A transaction handle of the shared Drizzle client — what
+ * {@link ContentEntryExtension.afterUpdate} receives so its writes commit or
+ * roll back with the triggering update.
+ */
+export type EntryTransaction = Parameters<Parameters<Database['transaction']>[0]>[0];
+/**
+ * The operations the entries pipeline consults an extension for. All methods
+ * are required — a no-op is `undefined`/`{}`, keeping call sites branch-free.
+ */
+export interface ContentEntryExtension {
+    /**
+     * An extra predicate AND-ed into the list WHERE (alongside the workspace
+     * scope, search, filter tree, and soft-delete guard). Interprets and
+     * validates {@link EntryScopeParams} — throw a `BadRequestException` for
+     * an invalid value. Return `undefined` to add nothing.
+     */
+    listScope(type: AnyContentType, workspaceId: string, params: EntryScopeParams): SQL | undefined;
+    /**
+     * Virtual filter fields for the type's `?filter=` schema, or `undefined`
+     * when the extension adds none for this type.
+     */
+    filterExtension(type: AnyContentType): EntryFilterExtension | undefined;
+    /**
+     * Extra envelope columns stamped onto the INSERT of a create (merged over
+     * the field columns + `workspaceId`). Interprets/validates
+     * {@link EntryScopeParams} — may throw (e.g. an unknown locale or a
+     * `localeGroupId` that names no group in the workspace). Return `{}` to add
+     * nothing. May be async (the group check reads the DB); the caller awaits.
+     */
+    createColumns(type: AnyContentType, workspaceId: string, params: EntryScopeParams): Record<string, unknown> | Promise<Record<string, unknown>>;
+    /**
+     * Runs as the **first statement inside the create and update
+     * transactions**, before the row itself is touched — the seam for taking a
+     * deterministic, transaction-scoped lock over the wider set the extension
+     * will write in {@link afterUpdate}.
+     *
+     * It exists because ordering the extension's own locks is not enough. By
+     * the time {@link afterUpdate} runs, this transaction already holds a row
+     * lock on the entry being saved (the pipeline's `UPDATE … RETURNING`), and
+     * that lock was taken outside any ordering the extension controls. Two
+     * concurrent saves on two members of the same extension-defined set (two
+     * locales of one translation group) therefore each hold a row the other is
+     * about to request — a textbook lock-order inversion that Postgres resolves
+     * by aborting one with `deadlock detected` (SQLSTATE 40P01), surfacing as a
+     * 500. A lock taken *here* precedes every row lock, so it imposes a total
+     * order on the set and the inversion becomes unreachable.
+     *
+     * Optional: an extension that writes only the row it was handed needs
+     * nothing. `params` carries the extension-owned scope of the write
+     * ({@link EntryScopeParams}) — on an update the pipeline fills in the
+     * **stored** row's values, not the request's, since that is the set the
+     * write actually contends on.
+     */
+    beforeWrite?(tx: EntryTransaction, type: AnyContentType, params: EntryScopeParams, workspaceId: string): Promise<void>;
+    /**
+     * Runs inside the **create and update** transactions, after the row's
+     * columns and relation deltas are written — e.g. to propagate shared values
+     * to sibling rows (so a newly-created sibling lands consistent with its
+     * group, and an edit re-syncs). A throw rolls the whole save back. The
+     * implementation must no-op when there are no siblings to affect.
+     *
+     * Returns the **other rows it changed**, if any. The entries pipeline
+     * appends a revision for each, in the same transaction — so a row whose
+     * values an extension rewrote gets the history entry it earned, instead of
+     * its timeline silently skipping the change.
+     *
+     * Revision writing deliberately stays here rather than in the extension:
+     * numbering is serialized per entry by an advisory lock, and a second
+     * writer allocating numbers out-of-band is how duplicate versions happen.
+     *
+     * An implementation MAY amend `row` **in place** for columns it derives for
+     * that row itself (the i18n sync resolves a mirrored relation into the new
+     * row's own locale on create). The caller snapshots `row` *after* this
+     * call, so an in-place amendment lands in the revision; writing only to the
+     * database would leave the first version describing something the row never
+     * held.
+     */
+    afterUpdate(tx: EntryTransaction, type: AnyContentType, row: Record<string, unknown>, values: Record<string, unknown>, workspaceId: string, context: EntryWriteContext): Promise<Record<string, unknown>[] | void>;
+    /**
+     * What a write of `values` onto `entryId` would rewrite **besides that
+     * row** — the read-only counterpart of {@link afterUpdate}, answered before
+     * anything is written.
+     *
+     * The pipeline itself never calls it: a save just saves, and the fan-out is
+     * the extension's own contract. It is asked by callers that have to
+     * *describe* a change before making it — the copilot's `content_propose_*`
+     * tools, whose receipt is the only place a user learns their content moved.
+     *
+     * Return `undefined` — not an empty description — when the write touches
+     * nothing else: the type is not the extension's, no field in `values`
+     * travels, or the row has no companions. Callers treat `undefined` as "an
+     * ordinary single-row edit" and say nothing, which is the common case and
+     * must stay silent.
+     *
+     * Reads only, and takes **no locks**: it runs outside the write
+     * transaction and its answer is advisory by construction — a sibling can
+     * appear between the description and the write. Locking here would put a
+     * `FOR UPDATE` on a translation group for the duration of a model's turn.
+     *
+     * Optional: an extension that only ever writes the row it was handed has
+     * nothing to describe.
+     */
+    describeFanout?(type: AnyContentType, entryId: string, values: Record<string, unknown>, workspaceId: string): Promise<EntryWriteFanout | undefined>;
+}
+//# sourceMappingURL=entry-extension.d.ts.map

package/dist/lib/extension/entry-extension.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entry-extension.d.ts","sourceRoot":"","sources":["../../../src/lib/extension/entry-extension.ts"],"names":[],"mappings":"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"}

package/dist/lib/extension/entry-extension.js

@@ -0,0 +1,27 @@
+"use strict";
+/**
+ * The entries **extension port** — the seam through which a downstream plugin
+ * (e.g. a localization plugin) extends the generic entries pipeline without
+ * this package knowing its domain. Content-server *declares* the port and
+ * consults it optionally (`@Optional()` injection) from {@link EntriesService}
+ * and {@link EntryWriterService}; the extending plugin *binds* an
+ * implementation to {@link CONTENT_ENTRY_EXTENSION} in its own module — the
+ * same inversion as identity's `CONTENT_CATALOG`, with the roles swapped.
+ *
+ * Every method is called unconditionally when an extension is bound, for every
+ * content type — an implementation MUST no-op (return `undefined` / `{}`) for
+ * types it doesn't apply to, so binding an extension never changes the
+ * behavior of unrelated types.
+ *
+ * NestJS-free on purpose (types + a Symbol only): implementations live in
+ * other packages, and keeping decorators out means this file could move into
+ * a decorator-free subpath without churn.
+ *
+ * Currently a **single binding**: one provider per app. If a second extension
+ * ever needs to coexist, bind a composite that fans out to both — the port's
+ * shape (SQL fragments AND-ed, column bags merged) composes cleanly.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONTENT_ENTRY_EXTENSION = void 0;
+/** DI token an extension plugin binds its {@link ContentEntryExtension} to. */
+exports.CONTENT_ENTRY_EXTENSION = Symbol('CONTENT_ENTRY_EXTENSION');