@orthacms/content-server 0.4.2 → 0.5.0

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

@@ -0,0 +1,149 @@
+"use strict";
+/**
+ * The **virtual filter-field registry** — how more than one plugin contributes
+ * fields to a content type's `?filter=` surface.
+ *
+ * `CONTENT_ENTRY_EXTENSION.filterExtension` already declares virtual fields
+ * (i18n's `hasLocale` / `missingLocale` / `localeCount`), but that port is a
+ * documented **single binding**: one provider per app, and i18n holds it. Nest
+ * has no multi-provider, so a second plugin binding the token would silently
+ * replace the first — for a filter surface that means fields quietly vanishing
+ * from the picker and saved filters starting to 400.
+ *
+ * So a plugin registers here instead (`@orthacms/segments-server` contributes
+ * "can be seen by" / "cannot be seen by" / "restricted"), the same shape and the
+ * same reason as `contentReadScopeRegistrar`. The bound extension keeps its
+ * method; {@link EntryFilterProviderRegistry.compose} folds the two together
+ * into the one `EntryFilterExtension` the query path already knows how to use,
+ * so nothing downstream changed.
+ *
+ * ## What a contribution owes
+ *
+ * **Every emitted subquery MUST scope to the workspace it is handed.** A virtual
+ * field is a subquery over a table this package knows nothing about; one that
+ * forgets the workspace turns a filter into a cross-tenant read.
+ *
+ * **Only declare fields you can answer, with only the operators you support.**
+ * The declared `fields` become the SQL whitelist, so an operator the resolver
+ * refuses reaches the user as "couldn't load this collection" over a rule the
+ * picker itself proposed. Narrow the operator set in the admin's `FilterField`
+ * to match.
+ *
+ * **A filter narrows what is listed; it is not a visibility rule.** Reachability
+ * is `CONTENT_READ_SCOPE`'s job and is applied separately. A field here must not
+ * be relied on to hide anything.
+ */
+var EntryFilterProviderRegistry_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EntryFilterProviderRegistry = void 0;
+exports.entryFilterProviderRegistrar = entryFilterProviderRegistrar;
+const tslib_1 = require("tslib");
+const common_1 = require("@nestjs/common");
+/** Every registered provider, in registration order. */
+let EntryFilterProviderRegistry = EntryFilterProviderRegistry_1 = class EntryFilterProviderRegistry {
+    logger = new common_1.Logger(EntryFilterProviderRegistry_1.name);
+    providers = [];
+    /** Adds a provider. Registering the same instance twice is a no-op. */
+    register(provider) {
+        if (!this.providers.includes(provider)) {
+            this.providers.push(provider);
+        }
+    }
+    /**
+     * Fold the bound extension's contribution and every registered provider's
+     * into one {@link EntryFilterExtension}.
+     *
+     * Returns `undefined` when nobody contributed anything, so a type with no
+     * virtual fields builds exactly the surface it did before this registry
+     * existed — and `entries.service` keeps its "no extension, no
+     * `resolveExtension`" branch.
+     *
+     * `resolve` routes by the rule's **field name**, to whoever declared it.
+     * A name declared twice is kept by its first declarer and the duplicate is
+     * dropped with a warning: silently letting the last writer win would make
+     * the meaning of a saved filter depend on plugin registration order.
+     */
+    compose(type, bound) {
+        const contributions = [
+            ...(bound ? [bound] : []),
+            ...this.providers
+                .map((provider) => provider.filterFor(type))
+                .filter((entry) => !!entry)
+        ];
+        if (!contributions.length)
+            return undefined;
+        if (contributions.length === 1)
+            return contributions[0];
+        const fields = {};
+        const owners = new Map();
+        for (const contribution of contributions) {
+            for (const [name, spec] of Object.entries(contribution.fields)) {
+                if (owners.has(name)) {
+                    this.logger.warn(`Two plugins declare the filter field "${name}" on "${type.name}"; keeping the first.`);
+                    continue;
+                }
+                owners.set(name, contribution);
+                fields[name] = spec;
+            }
+        }
+        return {
+            fields,
+            resolve: (rule, context) => {
+                const owner = owners.get(rule.path[0]);
+                if (!owner) {
+                    // Unreachable through the parser — a rule only gets here
+                    // after its name was whitelisted from `fields` above — but a
+                    // thrown error beats a silently-true predicate if it ever is.
+                    throw new Error(`No provider owns the filter field "${rule.path[0]}".`);
+                }
+                return owner.resolve(rule, context);
+            }
+        };
+    }
+};
+exports.EntryFilterProviderRegistry = EntryFilterProviderRegistry;
+exports.EntryFilterProviderRegistry = EntryFilterProviderRegistry = EntryFilterProviderRegistry_1 = tslib_1.__decorate([
+    (0, common_1.Injectable)()
+], EntryFilterProviderRegistry);
+/** Registers a plugin's filter providers with content at bootstrap. */
+class EntryFilterBootstrapper {
+    label;
+    registry;
+    providers;
+    logger = new common_1.Logger(EntryFilterBootstrapper.name);
+    constructor(label, registry, providers) {
+        this.label = label;
+        this.registry = registry;
+        this.providers = providers;
+    }
+    onApplicationBootstrap() {
+        // A deployment without `ContentPlugin` is not a real configuration, but
+        // a binding plugin should still boot rather than fail on an injection it
+        // cannot influence.
+        if (!this.registry)
+            return;
+        for (const provider of this.providers) {
+            this.registry.register(provider);
+        }
+        this.logger.log(`Registered the ${this.label} filter fields with content.`);
+    }
+}
+/**
+ * Builds the DI provider that registers `providers` with content's filter-field
+ * registry at bootstrap.
+ *
+ * A factory with an explicit `inject` list rather than a class with reflected
+ * parameters, for the reason `contentReadScopeRegistrar` documents: an optional
+ * dependency typed `Foo | null` emits `Object` for `design:paramtypes`, Nest
+ * injects `undefined` with no error, and the plugin registers nothing.
+ */
+function entryFilterProviderRegistrar(label, ...providers) {
+    return {
+        provide: `ENTRY_FILTER_PROVIDER_REGISTRAR_${label.toUpperCase()}`,
+        useFactory: (registry, ...resolved) => new EntryFilterBootstrapper(label, registry, resolved),
+        inject: [
+            { token: EntryFilterProviderRegistry, optional: true },
+            ...providers
+        ]
+    };
+}

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

@@ -0,0 +1,185 @@
+/**
+ * The **entry-write extension port** — how a downstream plugin stores state of
+ * its own *about* an entry, inside the entry's own write transaction and inside
+ * the entry's own version history.
+ *
+ * Content-server declares the port, calls it from `EntryWriterService`, and
+ * records what it returns in the revision snapshot's `extra` bag;
+ * `@orthacms/segments-server` binds one for reader entitlements, so who may read
+ * a record is set on Save, committed with the record, captured by the version,
+ * and put back when a version is restored.
+ *
+ * ## Why not a second HTTP call
+ *
+ * Nothing forced this port on us — segments already had a `PUT` of its own, and
+ * the admin could call it after saving. Three properties are what it buys, none
+ * of which a second request has:
+ *
+ * - **One transaction.** The entry, its links, its audiences and the version
+ *   recording all three commit together or not at all. Two requests can land
+ *   half a change: an entry saved and its restriction not applied.
+ * - **A truthful version.** A revision is built *inside* the write, so a
+ *   separate later request could only ever be captured by the **next** save —
+ *   the version would record the access the entry used to have.
+ * - **A restorable one.** Restoring version 3 re-applies its snapshot through
+ *   the same writer, so the extension's own state travels with it. Without that,
+ *   "go back to Tuesday" would put Tuesday's words in front of today's readers.
+ *
+ * ## Why a registry rather than a DI token
+ *
+ * Nest has **no multi-provider**: two dynamic modules binding one token do not
+ * merge, the second silently replaces the first. For this port the loss would be
+ * silent in the worst way — an extension that stopped being called writes
+ * nothing and captures nothing, so a restriction quietly stops applying. So a
+ * plugin registers through {@link entryWriteExtensionRegistrar}, the same shape
+ * and the same reason as `contentReadScopeRegistrar` and `copilotToolsRegistrar`.
+ *
+ * ## Why not `CONTENT_ENTRY_EXTENSION`
+ *
+ * That port is a documented **single binding** and i18n holds it. It also
+ * answers a different question: it extends how *this package's own* row is
+ * written (envelope columns, sibling sync). This one is about state a
+ * **different plugin** owns, in a table content-server knows nothing about, and
+ * the two must be able to coexist — an i18n installation with segments enabled
+ * is the ordinary case, not a conflict.
+ *
+ * ## Two rules an implementation must keep
+ *
+ * **Use the executor you are handed, never a connection of your own.** It is the
+ * save's transaction; a write on any other connection commits separately and
+ * takes the atomicity above with it.
+ *
+ * **`capture` is called for every snapshot, `apply` only when asked.** A save
+ * that carried nothing for an extension must leave that extension's state alone
+ * — but its *version* still has to record what the state was, or restoring that
+ * version would read as "this had no audiences" and open the entry up.
+ */
+import { type Provider, type Type } from '@nestjs/common';
+import type { DbTransaction } from '../entries/infrastructure/persistence/relation-link.service';
+import type { AnyContentType } from '../types/content-type';
+/** The entry an extension is reading or writing state for. */
+export interface EntryWriteExtensionTarget {
+    /**
+     * The save's own transaction. Every read and write an extension makes MUST
+     * go through it — a write on another connection commits on its own, which is
+     * the whole thing this port exists to prevent.
+     */
+    readonly executor: DbTransaction;
+    /** The content type being saved. */
+    readonly type: AnyContentType;
+    /** The row's id. On a create, the row that has just been inserted. */
+    readonly entryId: string;
+    /** The workspace the entry belongs to. */
+    readonly workspaceId: string;
+}
+/** A write: the target, plus what the caller sent for this extension. */
+export interface EntryWriteExtensionInput extends EntryWriteExtensionTarget {
+    /**
+     * The caller's value under this extension's {@link EntryWriteExtension.key},
+     * verbatim and **unvalidated** — content-server declares the bag as opaque
+     * and never looks inside it, exactly as it does for `locale`. An extension
+     * validates its own slice and throws a `BadRequestException` /
+     * `UnprocessableEntityException` on a bad one, which rolls the save back.
+     *
+     * On a **restore** this is the value the restored version captured, so the
+     * same code path puts state back that put it there.
+     */
+    readonly value: unknown;
+}
+/** One plugin's state alongside an entry, written and versioned with it. */
+export interface EntryWriteExtension {
+    /**
+     * The extension's slot — in the request's `extensions` bag and in the
+     * revision snapshot's `extra`. Must be stable: a stored snapshot names it,
+     * so renaming the key orphans every version already captured.
+     */
+    readonly key: string;
+    /**
+     * Write this extension's state for the entry, on the save's transaction.
+     *
+     * Called **only** when the request carried a value under {@link key} — a
+     * save that said nothing about audiences must not clear them.
+     *
+     * Return the ids of **other** entries this write also changed — the locale
+     * siblings segments writes an entry's audiences to, for instance. Content
+     * appends a revision for each, exactly as it does for the rows i18n's shared
+     * -field sync rewrote: a row whose stored state moved while its timeline did
+     * not is a history that hides the change and, on the next restore, undoes
+     * it. Return nothing when only the named entry changed.
+     */
+    apply(input: EntryWriteExtensionInput): Promise<readonly string[] | void>;
+    /**
+     * What the revision should record, read back on the same transaction so it
+     * reflects what actually committed.
+     *
+     * Called for **every** snapshot, including a save that never mentioned this
+     * extension and including the locale siblings an extension rewrote — a
+     * version that omitted the state it did not change would read, on restore,
+     * as a version that had none.
+     *
+     * Return `undefined` to record nothing (the key is then absent from `extra`,
+     * which is what an unconfigured installation should produce).
+     */
+    capture(target: EntryWriteExtensionTarget): Promise<unknown>;
+    /**
+     * A row has just been **inserted** — a chance to give it whatever the rest
+     * of its locale group already has.
+     *
+     * Optional, and called on every create **after** {@link apply}, so an
+     * extension that has just been told what to store is not asked to inherit
+     * over it. It exists because `apply` runs only for keys the caller sent, and
+     * "create a translation" sends none: without this, translating a restricted
+     * article produced a public German copy of it, which is the failure mode a
+     * reader notices and an editor never does.
+     *
+     * The equivalent for content's own columns is `CONTENT_ENTRY_EXTENSION`'s
+     * create-only relation inheritance; this is the same posture for state a
+     * different plugin owns.
+     */
+    inherit?(target: EntryWriteExtensionTarget): Promise<void>;
+}
+/** Every registered extension, in registration order. */
+export declare class EntryWriteExtensionRegistry {
+    private readonly extensions;
+    /** Adds an extension. Registering the same instance twice is a no-op. */
+    register(extension: EntryWriteExtension): void;
+    /** Whether anything is registered — the check that keeps a bare install free. */
+    get configured(): boolean;
+    /**
+     * Run every extension the caller sent a value for.
+     *
+     * An unknown key is **ignored**, not an error: the bag is forwarded from a
+     * client that may be talking to an installation without that plugin, and
+     * failing the whole save over it would make a request that works on one
+     * deployment a 400 on another. What the save then records is the truth —
+     * `capture` reports no state for a key nothing owns.
+     */
+    applyAll(target: EntryWriteExtensionTarget, inputs: Record<string, unknown> | undefined): Promise<string[]>;
+    /**
+     * Let every extension that wants to give a **just-inserted** row what its
+     * locale group already holds.
+     *
+     * Runs after {@link applyAll} on a create, and only there: an extension the
+     * caller just told what to store must not then inherit over it.
+     */
+    inheritAll(target: EntryWriteExtensionTarget): Promise<void>;
+    /**
+     * Everything the extensions hold for one entry, keyed by extension.
+     *
+     * Returns `undefined` — not an empty object — when there is nothing to
+     * record, so a snapshot taken on an installation with no extensions is
+     * byte-for-byte what it was before this port existed.
+     */
+    captureAll(target: EntryWriteExtensionTarget): Promise<Record<string, unknown> | undefined>;
+}
+/**
+ * Builds the DI provider that registers `extensions` with content's entry-write
+ * registry at bootstrap.
+ *
+ * A factory with an explicit `inject` list rather than a class with reflected
+ * parameters, for the reason `contentReadScopeRegistrar` documents: an optional
+ * dependency typed `Foo | null` emits `Object` for `design:paramtypes`, Nest
+ * injects `undefined` with no error, and the plugin registers nothing.
+ */
+export declare function entryWriteExtensionRegistrar(label: string, ...extensions: Type<EntryWriteExtension>[]): Provider;
+//# sourceMappingURL=entry-write-extension.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"entry-write-extension.d.ts","sourceRoot":"","sources":["../../../src/lib/extension/entry-write-extension.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AAEH,OAAO,EAIH,KAAK,QAAQ,EACb,KAAK,IAAI,EACZ,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6DAA6D,CAAC;AACjG,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE5D,8DAA8D;AAC9D,MAAM,WAAW,yBAAyB;IACtC;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,oCAAoC;IACpC,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,sEAAsE;IACtE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,0CAA0C;IAC1C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAChC;AAED,yEAAyE;AACzE,MAAM,WAAW,wBAAyB,SAAQ,yBAAyB;IACvE;;;;;;;;;OASG;IACH,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CAC3B;AAED,4EAA4E;AAC5E,MAAM,WAAW,mBAAmB;IAChC;;;;OAIG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAErB;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,KAAK,EAAE,wBAAwB,GAAG,OAAO,CAAC,SAAS,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC;IAE1E;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,MAAM,EAAE,yBAAyB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAE7D;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,CAAC,MAAM,EAAE,yBAAyB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9D;AAED,yDAAyD;AACzD,qBACa,2BAA2B;IACpC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA6B;IAExD,yEAAyE;IACzE,QAAQ,CAAC,SAAS,EAAE,mBAAmB,GAAG,IAAI;IAM9C,iFAAiF;IACjF,IAAI,UAAU,IAAI,OAAO,CAExB;IAED;;;;;;;;OAQG;IACG,QAAQ,CACV,MAAM,EAAE,yBAAyB,EACjC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAC5C,OAAO,CAAC,MAAM,EAAE,CAAC;IAmBpB;;;;;;OAMG;IACG,UAAU,CAAC,MAAM,EAAE,yBAAyB,GAAG,OAAO,CAAC,IAAI,CAAC;IAMlE;;;;;;OAMG;IACG,UAAU,CACZ,MAAM,EAAE,yBAAyB,GAClC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;CASlD;AA0BD;;;;;;;;GAQG;AACH,wBAAgB,4BAA4B,CACxC,KAAK,EAAE,MAAM,EACb,GAAG,UAAU,EAAE,IAAI,CAAC,mBAAmB,CAAC,EAAE,GAC3C,QAAQ,CAYV"}

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

@@ -0,0 +1,182 @@
+"use strict";
+/**
+ * The **entry-write extension port** — how a downstream plugin stores state of
+ * its own *about* an entry, inside the entry's own write transaction and inside
+ * the entry's own version history.
+ *
+ * Content-server declares the port, calls it from `EntryWriterService`, and
+ * records what it returns in the revision snapshot's `extra` bag;
+ * `@orthacms/segments-server` binds one for reader entitlements, so who may read
+ * a record is set on Save, committed with the record, captured by the version,
+ * and put back when a version is restored.
+ *
+ * ## Why not a second HTTP call
+ *
+ * Nothing forced this port on us — segments already had a `PUT` of its own, and
+ * the admin could call it after saving. Three properties are what it buys, none
+ * of which a second request has:
+ *
+ * - **One transaction.** The entry, its links, its audiences and the version
+ *   recording all three commit together or not at all. Two requests can land
+ *   half a change: an entry saved and its restriction not applied.
+ * - **A truthful version.** A revision is built *inside* the write, so a
+ *   separate later request could only ever be captured by the **next** save —
+ *   the version would record the access the entry used to have.
+ * - **A restorable one.** Restoring version 3 re-applies its snapshot through
+ *   the same writer, so the extension's own state travels with it. Without that,
+ *   "go back to Tuesday" would put Tuesday's words in front of today's readers.
+ *
+ * ## Why a registry rather than a DI token
+ *
+ * Nest has **no multi-provider**: two dynamic modules binding one token do not
+ * merge, the second silently replaces the first. For this port the loss would be
+ * silent in the worst way — an extension that stopped being called writes
+ * nothing and captures nothing, so a restriction quietly stops applying. So a
+ * plugin registers through {@link entryWriteExtensionRegistrar}, the same shape
+ * and the same reason as `contentReadScopeRegistrar` and `copilotToolsRegistrar`.
+ *
+ * ## Why not `CONTENT_ENTRY_EXTENSION`
+ *
+ * That port is a documented **single binding** and i18n holds it. It also
+ * answers a different question: it extends how *this package's own* row is
+ * written (envelope columns, sibling sync). This one is about state a
+ * **different plugin** owns, in a table content-server knows nothing about, and
+ * the two must be able to coexist — an i18n installation with segments enabled
+ * is the ordinary case, not a conflict.
+ *
+ * ## Two rules an implementation must keep
+ *
+ * **Use the executor you are handed, never a connection of your own.** It is the
+ * save's transaction; a write on any other connection commits separately and
+ * takes the atomicity above with it.
+ *
+ * **`capture` is called for every snapshot, `apply` only when asked.** A save
+ * that carried nothing for an extension must leave that extension's state alone
+ * — but its *version* still has to record what the state was, or restoring that
+ * version would read as "this had no audiences" and open the entry up.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EntryWriteExtensionRegistry = void 0;
+exports.entryWriteExtensionRegistrar = entryWriteExtensionRegistrar;
+const tslib_1 = require("tslib");
+const common_1 = require("@nestjs/common");
+/** Every registered extension, in registration order. */
+let EntryWriteExtensionRegistry = class EntryWriteExtensionRegistry {
+    extensions = [];
+    /** Adds an extension. Registering the same instance twice is a no-op. */
+    register(extension) {
+        if (!this.extensions.includes(extension)) {
+            this.extensions.push(extension);
+        }
+    }
+    /** Whether anything is registered — the check that keeps a bare install free. */
+    get configured() {
+        return this.extensions.length > 0;
+    }
+    /**
+     * Run every extension the caller sent a value for.
+     *
+     * An unknown key is **ignored**, not an error: the bag is forwarded from a
+     * client that may be talking to an installation without that plugin, and
+     * failing the whole save over it would make a request that works on one
+     * deployment a 400 on another. What the save then records is the truth —
+     * `capture` reports no state for a key nothing owns.
+     */
+    async applyAll(target, inputs) {
+        if (!inputs || !this.extensions.length)
+            return [];
+        // Every *other* entry the extensions changed, so the caller can give
+        // each one the revision its moved state deserves. Deduplicated, and the
+        // named entry is dropped: it gets its own snapshot either way.
+        const alsoChanged = new Set();
+        for (const extension of this.extensions) {
+            if (!(extension.key in inputs))
+                continue;
+            const touched = await extension.apply({
+                ...target,
+                value: inputs[extension.key]
+            });
+            for (const id of touched ?? []) {
+                if (id !== target.entryId)
+                    alsoChanged.add(id);
+            }
+        }
+        return [...alsoChanged];
+    }
+    /**
+     * Let every extension that wants to give a **just-inserted** row what its
+     * locale group already holds.
+     *
+     * Runs after {@link applyAll} on a create, and only there: an extension the
+     * caller just told what to store must not then inherit over it.
+     */
+    async inheritAll(target) {
+        for (const extension of this.extensions) {
+            await extension.inherit?.(target);
+        }
+    }
+    /**
+     * Everything the extensions hold for one entry, keyed by extension.
+     *
+     * Returns `undefined` — not an empty object — when there is nothing to
+     * record, so a snapshot taken on an installation with no extensions is
+     * byte-for-byte what it was before this port existed.
+     */
+    async captureAll(target) {
+        if (!this.extensions.length)
+            return undefined;
+        const extra = {};
+        for (const extension of this.extensions) {
+            const value = await extension.capture(target);
+            if (value !== undefined)
+                extra[extension.key] = value;
+        }
+        return Object.keys(extra).length ? extra : undefined;
+    }
+};
+exports.EntryWriteExtensionRegistry = EntryWriteExtensionRegistry;
+exports.EntryWriteExtensionRegistry = EntryWriteExtensionRegistry = tslib_1.__decorate([
+    (0, common_1.Injectable)()
+], EntryWriteExtensionRegistry);
+/** Registers a plugin's entry-write extensions with content at bootstrap. */
+class EntryWriteExtensionBootstrapper {
+    label;
+    registry;
+    extensions;
+    logger = new common_1.Logger(EntryWriteExtensionBootstrapper.name);
+    constructor(label, registry, extensions) {
+        this.label = label;
+        this.registry = registry;
+        this.extensions = extensions;
+    }
+    onApplicationBootstrap() {
+        // A deployment without `ContentPlugin` is not a real configuration, but
+        // a binding plugin should still boot rather than fail on an injection it
+        // cannot influence.
+        if (!this.registry)
+            return;
+        for (const extension of this.extensions) {
+            this.registry.register(extension);
+        }
+        this.logger.log(`Registered the ${this.label} entry-write extension with content.`);
+    }
+}
+/**
+ * Builds the DI provider that registers `extensions` with content's entry-write
+ * registry at bootstrap.
+ *
+ * A factory with an explicit `inject` list rather than a class with reflected
+ * parameters, for the reason `contentReadScopeRegistrar` documents: an optional
+ * dependency typed `Foo | null` emits `Object` for `design:paramtypes`, Nest
+ * injects `undefined` with no error, and the plugin registers nothing.
+ */
+function entryWriteExtensionRegistrar(label, ...extensions) {
+    return {
+        provide: `ENTRY_WRITE_EXTENSION_REGISTRAR_${label.toUpperCase()}`,
+        useFactory: (registry, ...resolved) => new EntryWriteExtensionBootstrapper(label, registry, resolved),
+        inject: [
+            { token: EntryWriteExtensionRegistry, optional: true },
+            ...extensions
+        ]
+    };
+}

package/dist/lib/extension/read-scope.d.ts

@@ -0,0 +1,107 @@
+/**
+ * The **read scope port** — the seam a downstream plugin uses to narrow what
+ * the public content API returns, without this package knowing why.
+ *
+ * Content-server declares the port and consults it from `PublicEntriesQuery`
+ * and `PublicExpansionQuery`; an implementing plugin
+ * (`@orthacms/segments-server`, for reader entitlements) registers a scope
+ * through {@link contentReadScopeRegistrar}. Every fragment returned is AND-ed
+ * onto the visibility predicate the public read already states, so a scope can
+ * only ever *subtract* rows — there is no shape of return value that widens a
+ * read.
+ *
+ * ## Why a registry rather than a DI token
+ *
+ * The port takes any number of independent narrowings, and Nest has **no
+ * multi-provider**: two dynamic modules binding the same token do not merge,
+ * the second silently replaces the first. A second scoping plugin would
+ * therefore switch the first one off, with nothing to notice it — which for a
+ * visibility rule means content quietly becoming visible. So registration is a
+ * runtime `register(...)` call against a registry this module owns, the same
+ * shape and the same reason as `copilotToolsRegistrar`.
+ *
+ * ## Why not `CONTENT_ENTRY_EXTENSION`
+ *
+ * That port is documented as a **single binding**: one provider per app, and
+ * i18n already holds it. Its own note suggests binding a composite when a
+ * second extension appears, and for a write-pipeline extension that composes
+ * cleanly — but "narrow a read" and "extend a write" are different
+ * responsibilities with different failure modes. A composite would fuse i18n
+ * and entitlements into one provider, where a fault in either silently drops
+ * the other's clause.
+ *
+ * ## Two constraints on an implementation
+ *
+ * **Synchronous.** The predicate is assembled inside the query builder, and
+ * making that path async would ripple through every public read for the benefit
+ * of one provider. A scope that needs I/O — resolving who the caller is, say —
+ * must do it earlier in the request (a guard, an interceptor, middleware) and
+ * read the result from its own request-scoped state here.
+ *
+ * **Public reads only.** These fragments are not applied to the admin's own
+ * entries list. An admin caller is a member of the workspace looking at their
+ * own CMS, while a reader entitlement is about who may *consume* published
+ * content, and scoping the editor's list by it would hide from an author the
+ * very rows they are responsible for. The same split content grants already
+ * make.
+ */
+import { type Provider, type Type } from '@nestjs/common';
+import type { SQL } from 'drizzle-orm';
+import type { AnyContentType } from '../types/content-type';
+/** What a scope is told about the read it is narrowing. */
+export interface ContentReadScopeContext {
+    /** The content type being read. Its table is `type.table`. */
+    readonly type: AnyContentType;
+    /**
+     * The workspace the request resolved to. Every emitted fragment MUST stay
+     * inside it — a subquery that forgets the workspace turns one tenant's
+     * scope into a cross-tenant read.
+     */
+    readonly workspaceId: string;
+}
+/**
+ * One contributed narrowing of the public read.
+ *
+ * Returning `undefined` means "nothing to add for this read", which is how an
+ * implementation opts out per type, per workspace, or entirely — a plugin that
+ * is installed but unconfigured must return `undefined` rather than a fragment
+ * matching everything, so an unconfigured install pays nothing at all.
+ */
+export interface ContentReadScope {
+    /** A predicate AND-ed onto the public visibility rule. */
+    scope(context: ContentReadScopeContext): SQL | undefined;
+}
+/**
+ * Every registered narrowing, in registration order.
+ *
+ * Order does not affect the result — the fragments are AND-ed — but it is kept
+ * stable so a query log reads the same way twice.
+ */
+export declare class ContentReadScopeRegistry {
+    private readonly scopes;
+    /** Adds a scope. Registering the same instance twice is a no-op. */
+    register(scope: ContentReadScope): void;
+    /** Every registered scope. Empty on an installation with none. */
+    all(): readonly ContentReadScope[];
+    /**
+     * The fragments for one read, ready to be spread into `and(...)`.
+     *
+     * Returns an empty array — not a fragment matching everything — when
+     * nothing is registered, which is the state every installation without a
+     * scoping plugin stays in.
+     */
+    fragments(context: ContentReadScopeContext): (SQL | undefined)[];
+}
+/**
+ * Builds the DI provider that registers `scopes` with content's read-scope
+ * registry at bootstrap.
+ *
+ * A factory with an explicit `inject` list rather than a class with reflected
+ * parameters, for the reason `copilotToolsRegistrar` documents: an optional
+ * dependency typed as `Foo | null` emits `Object` for `design:paramtypes`, Nest
+ * injects `undefined` with no error, and the plugin ends up registering
+ * nothing. Here that failure would mean a visibility rule that silently stopped
+ * being applied.
+ */
+export declare function contentReadScopeRegistrar(label: string, ...scopes: Type<ContentReadScope>[]): Provider;
+//# sourceMappingURL=read-scope.d.ts.map

package/dist/lib/extension/read-scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-scope.d.ts","sourceRoot":"","sources":["../../../src/lib/extension/read-scope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAEH,OAAO,EAIH,KAAK,QAAQ,EACb,KAAK,IAAI,EACZ,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,aAAa,CAAC;AACvC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE5D,2DAA2D;AAC3D,MAAM,WAAW,uBAAuB;IACpC,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAChC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,gBAAgB;IAC7B,0DAA0D;IAC1D,KAAK,CAAC,OAAO,EAAE,uBAAuB,GAAG,GAAG,GAAG,SAAS,CAAC;CAC5D;AAED;;;;;GAKG;AACH,qBACa,wBAAwB;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0B;IAEjD,oEAAoE;IACpE,QAAQ,CAAC,KAAK,EAAE,gBAAgB,GAAG,IAAI;IAMvC,kEAAkE;IAClE,GAAG,IAAI,SAAS,gBAAgB,EAAE;IAIlC;;;;;;OAMG;IACH,SAAS,CAAC,OAAO,EAAE,uBAAuB,GAAG,CAAC,GAAG,GAAG,SAAS,CAAC,EAAE;CAMnE;AA4BD;;;;;;;;;;GAUG;AACH,wBAAgB,yBAAyB,CACrC,KAAK,EAAE,MAAM,EACb,GAAG,MAAM,EAAE,IAAI,CAAC,gBAAgB,CAAC,EAAE,GACpC,QAAQ,CASV"}