@orthacms/i18n-server 0.0.0-reserve.0

package/dist/lib/copilot/translation-proposal.provider.js

@@ -0,0 +1,419 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TranslationProposalToolProvider = exports.I18N_PROPOSAL_KINDS = void 0;
+const tslib_1 = require("tslib");
+const common_1 = require("@nestjs/common");
+const identity_server_1 = require("@orthacms/identity-server");
+const content_server_1 = require("@orthacms/content-server");
+const tools_server_1 = require("@orthacms/tools-server");
+const locale_registry_service_1 = require("../locales/services/locale-registry.service");
+const locale_group_service_1 = require("../content/services/locale-group.service");
+/** The proposal kinds this plugin declares and applies. */
+exports.I18N_PROPOSAL_KINDS = {
+    /** Create a sibling row of an entry in another locale. */
+    createTranslation: 'i18n.entry.translate',
+    /**
+     * Create several sibling rows — more locales of one record, more records
+     * in one locale, or both — as **one** change.
+     *
+     * Its own kind rather than a repeated `createTranslation`, for the reason
+     * `content.entry.bulk-save` is: a proposal row is the receipt for one tool
+     * call, and "translate this into five languages" written as five rows is
+     * five cards in the transcript for a single instruction, none of which says
+     * what the other four were.
+     */
+    bulkTranslation: 'i18n.entry.bulk-translate'
+};
+/**
+ * The plugin's **write** tools: `i18n_propose_translation` for one locale of one
+ * entry, and `i18n_propose_bulk_translation` for a batch of them.
+ *
+ * Like every propose tool their handlers **write nothing** — they compute the
+ * change and hand it back, and the run engine records and applies it. What they
+ * do is the part a model cannot be trusted to get right on its own: resolve the
+ * locale slug against the configured set, confirm the target locale does not
+ * already exist in the group (a duplicate is a 409 at apply time, after the
+ * card has said the change is happening), and name the source entry so the
+ * applier can inherit its shared values.
+ *
+ * Only **localized** fields are translated. A field the type declares as shared
+ * is one value across the whole group by definition — writing a per-locale
+ * version of it would either be ignored or silently overwrite every sibling,
+ * and neither is something to show a reader as a translation.
+ */
+let TranslationProposalToolProvider = class TranslationProposalToolProvider {
+    registry;
+    locales;
+    groups;
+    grants;
+    toolRegistry;
+    constructor(registry, locales, groups, grants, toolRegistry) {
+        this.registry = registry;
+        this.locales = locales;
+        this.groups = groups;
+        this.grants = grants;
+        this.toolRegistry = toolRegistry;
+    }
+    /**
+     * Register with the shared tool registry once the DI graph is built —
+     * the same catalogue the MCP endpoint serves, narrowed to the `copilot`
+     * surface by each tool's `surfaces`. `@Optional()` because a deployment
+     * may run neither consumer, in which case these simply go unregistered.
+     */
+    onModuleInit() {
+        this.toolRegistry?.register(this);
+    }
+    /** The two i18n write tools — one translation, and the batch. */
+    tools() {
+        return [this.proposeTranslation(), this.proposeBulkTranslation()];
+    }
+    /**
+     * A granted, registered, **localized** type — the gate both write tools
+     * open with.
+     *
+     * The two failures are worth separating: "unknown type" is the uniform
+     * answer every content tool gives a name it cannot reach (it must not
+     * distinguish "no such type" from "not granted here"), while "not
+     * localized" describes a type the caller has already proved it can reach
+     * and is safe — and useful — to say out loud.
+     */
+    async resolveLocalizedType(typeName, workspaceId) {
+        const type = this.registry.get(typeName);
+        const granted = await this.grants.grantedSlugs(workspaceId);
+        if (!type || !granted.has(type.name)) {
+            throw new Error(`Unknown content type "${typeName}" in this workspace.`);
+        }
+        if (!type.i18n) {
+            throw new Error(`Content type "${type.name}" is not localized, so it cannot be translated.`);
+        }
+        return type;
+    }
+    /**
+     * The type's **localized** fields, keyed by name — the only ones a
+     * translation may carry.
+     *
+     * A field the type declares as shared is one value across the whole group
+     * by definition: writing a per-locale version of it would be fanned back
+     * out over every sibling by this plugin's own sync, so a "translated"
+     * shared field silently rewrites every other language.
+     */
+    localizedFields(typeName) {
+        const schema = this.registry.serialize(typeName);
+        return new Map((schema?.fields ?? [])
+            .filter((field) => field.localized)
+            .map((field) => [field.name, field]));
+    }
+    /**
+     * Rejects anything in `values` that is not a localized field, and an empty
+     * bag — the check that makes a translation tool a translation tool.
+     *
+     * `prefix` names which item is at fault in a batch, and is empty for the
+     * single-entry tool so its message is unchanged.
+     */
+    assertTranslatable(values, localized, prefix = '') {
+        const rejected = Object.keys(values).filter((name) => !localized.has(name));
+        if (rejected.length > 0) {
+            throw new Error(`${prefix}These fields are shared across locales and cannot be translated: ` +
+                `${rejected.join(', ')}. Only ${[...localized.keys()].join(', ')} ` +
+                'vary per locale on this type.');
+        }
+        if (Object.keys(values).length === 0) {
+            throw new Error(`${prefix}No translated values were supplied.`);
+        }
+    }
+    /** The field's admin label, when it has one — for the card's diff rows. */
+    labelOf(field) {
+        const label = field?.admin?.['label'];
+        return typeof label === 'string' ? label : undefined;
+    }
+    /** `i18n_propose_translation` — one entry into one locale. */
+    proposeTranslation() {
+        return {
+            name: 'i18n_propose_translation',
+            title: 'Propose a translation',
+            description: 'Propose a translation of an entry into another locale, creating that locale’s ' +
+                'row in the same translation group. This does NOT save anything — it drafts ' +
+                'the change for the user to approve, and the reply will say so. Read the ' +
+                'source entry first (admin_content_get) and translate its text yourself; only ' +
+                'fields the type marks as localized can differ per locale.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    typeName: {
+                        type: 'string',
+                        description: 'The entry’s content type. It must be localized.'
+                    },
+                    id: {
+                        type: 'string',
+                        description: 'The id of the source entry — the row you translated from.'
+                    },
+                    locale: {
+                        type: 'string',
+                        maxLength: 35,
+                        description: 'The locale slug to create, from i18n_locales_list. It must not ' +
+                            'already exist in this entry’s translation group.'
+                    },
+                    values: {
+                        type: 'object',
+                        description: 'The translated values, keyed by field name. Only localized ' +
+                            'fields are accepted; shared fields are copied by the CMS.'
+                    },
+                    summary: {
+                        type: 'string',
+                        maxLength: 200,
+                        description: 'One line for the approval card, e.g. “German translation of ' +
+                            'Spring launch”.'
+                    }
+                },
+                required: ['typeName', 'id', 'locale', 'values', 'summary'],
+                additionalProperties: false
+            },
+            // `content:update` rather than `content:create`: the design's v1
+            // catalogue says so, and it is the right key — a translation is a
+            // change to an existing piece of content, not a new one, which is
+            // exactly how an editor thinks about it.
+            requires: [identity_server_1.PERMISSIONS.CONTENT_UPDATE],
+            readOnly: false,
+            effect: 'propose',
+            // Copilot-only: it reads the admin services (a viewer must see
+            // drafts) or writes through propose-then-apply with the human as
+            // actor. MCP's content tools are the public-API set.
+            surfaces: ['copilot'],
+            handler: async (input, ctx) => {
+                const args = (input ?? {});
+                const type = await this.resolveLocalizedType(args.typeName, ctx.workspaceId);
+                const target = this.locales.get(args.locale);
+                if (!target) {
+                    throw new Error(`Unknown locale "${args.locale}". Call i18n_locales_list for the ` +
+                        'configured slugs.');
+                }
+                // The group read doubles as the existence check on the source
+                // entry: it 404s a missing or soft-deleted row, workspace-scoped.
+                const group = await this.groups.entryLocales(type, args.id, ctx.workspaceId);
+                const existing = group.items.find((item) => item.locale === target.slug);
+                if (existing?.entry) {
+                    throw new Error(`This entry already has a "${target.slug}" translation. Use ` +
+                        'content_propose_update on that row instead.');
+                }
+                const localized = this.localizedFields(type.name);
+                const values = args.values ?? {};
+                this.assertTranslatable(values, localized);
+                return {
+                    kind: exports.I18N_PROPOSAL_KINDS.createTranslation,
+                    target: {
+                        typeName: type.name,
+                        sourceId: args.id,
+                        localeGroupId: group.localeGroupId,
+                        locale: target.slug
+                    },
+                    patch: { values },
+                    summary: args.summary,
+                    changes: Object.entries(values).map(([field, after]) => {
+                        const label = this.labelOf(localized.get(field));
+                        return {
+                            field,
+                            ...(label ? { label } : {}),
+                            after
+                        };
+                    })
+                };
+            }
+        };
+    }
+    /**
+     * `i18n_propose_bulk_translation` — several translations as **one** change.
+     *
+     * The single-entry tool scales badly in both directions users actually push
+     * it: "translate this into German, French and Spanish" is three calls, and
+     * "translate these eight posts into German" is eight. Each one spent a step
+     * of a bounded run and left its own card, so one instruction read back as a
+     * pile of receipts, none of which said what the others were.
+     *
+     * **Why this rather than `content_propose_bulk_save` with a
+     * `localeGroupId`.** That is what a model reached for before, and it is the
+     * shape that quietly breaks a group: a create is a whole row, so every
+     * shared field the batch did not name arrives as `null`, and this plugin's
+     * sync then pushes those nulls onto every sibling — see
+     * {@link TranslationProposalApplier}. Joining a translation group needs the
+     * source's shared values inherited at apply time, which is knowledge that
+     * lives here, so the content tools no longer offer `localeGroupId` at all
+     * and this is the one route in.
+     *
+     * An item is one **(source entry, target locale)** pair, so both shapes are
+     * the same list: five items naming one `id` and five locales, eight naming
+     * eight ids and one locale, or any mixture.
+     */
+    proposeBulkTranslation() {
+        return {
+            name: 'i18n_propose_bulk_translation',
+            title: 'Propose several translations',
+            description: 'Translate one or more entries into one or more locales in a SINGLE change. ' +
+                'Use this instead of calling i18n_propose_translation repeatedly — the user ' +
+                'sees one card listing every translation, and you spend one step instead of ' +
+                'one per language. Each item is one entry translated into one locale: repeat ' +
+                'the same `id` with different locales to translate a record into several ' +
+                'languages, or list different `id`s with the same locale to translate several ' +
+                'records. Read the source entries first (admin_content_get) and translate ' +
+                'their text yourself; only fields the type marks as localized can differ per ' +
+                'locale, and the CMS copies the shared ones. If a translation fails, the ' +
+                'change stops there and the reply says how many landed — do not claim the ' +
+                'whole batch saved without reading it.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    typeName: {
+                        type: 'string',
+                        description: 'The content type every item belongs to. It must be localized.'
+                    },
+                    items: {
+                        type: 'array',
+                        minItems: 1,
+                        maxItems: content_server_1.BULK_MAX_SAVE_ITEMS,
+                        description: `The translations to create (1…${content_server_1.BULK_MAX_SAVE_ITEMS}), applied in order.`,
+                        items: {
+                            type: 'object',
+                            properties: {
+                                id: {
+                                    type: 'string',
+                                    description: 'The id of the source entry — the row you translated from. ' +
+                                        'Any locale of the record will do; they share one translation ' +
+                                        'group.'
+                                },
+                                locale: {
+                                    type: 'string',
+                                    maxLength: 35,
+                                    description: 'The locale slug to create, from i18n_locales_list. It must ' +
+                                        'not already exist in this entry’s translation group.'
+                                },
+                                values: {
+                                    type: 'object',
+                                    description: 'The translated values for THIS locale, keyed by field name. ' +
+                                        'Only localized fields are accepted; shared fields are copied ' +
+                                        'by the CMS.'
+                                }
+                            },
+                            required: ['id', 'locale', 'values'],
+                            additionalProperties: false
+                        }
+                    },
+                    summary: {
+                        type: 'string',
+                        maxLength: 200,
+                        description: 'One line describing the whole batch, shown to the user on the card. ' +
+                            'Write it for a person, e.g. “Translate Spring launch into 3 languages”.'
+                    }
+                },
+                required: ['typeName', 'items', 'summary'],
+                additionalProperties: false
+            },
+            // The same key the single-entry tool takes, and for the same
+            // reason: a translation is a change to existing content, not a new
+            // piece of it. Batching is a way of *asking* — it must not become a
+            // route to authority the one-at-a-time tool was never given
+            // (ADR-0005 §7).
+            requires: [identity_server_1.PERMISSIONS.CONTENT_UPDATE],
+            readOnly: false,
+            effect: 'propose',
+            surfaces: ['copilot'],
+            handler: async (input, ctx) => {
+                const args = (input ?? {});
+                const type = await this.resolveLocalizedType(args.typeName, ctx.workspaceId);
+                const items = args.items ?? [];
+                if (items.length === 0) {
+                    throw new Error('Nothing to translate — `items` was empty. Send at least one translation.');
+                }
+                if (items.length > content_server_1.BULK_MAX_SAVE_ITEMS) {
+                    throw new Error(`Too many translations in one change: ${items.length}, and the limit ` +
+                        `is ${content_server_1.BULK_MAX_SAVE_ITEMS}. Split it into smaller batches.`);
+                }
+                const localized = this.localizedFields(type.name);
+                const changes = [];
+                const patched = [];
+                // One group read per distinct source id: translating one record
+                // into five languages is five items naming the same entry, and
+                // re-reading its group five times would be five identical
+                // queries answering an identical question.
+                const groups = new Map();
+                // Every (group, locale) this batch already claims. Two items
+                // aiming at the same slot is a unique-index violation waiting
+                // to happen halfway through the apply — after the first
+                // translations have already been written.
+                const claimed = new Set();
+                for (const [index, item] of items.entries()) {
+                    const at = `Item ${index + 1}: `;
+                    if (typeof item.id !== 'string' || item.id.length === 0) {
+                        throw new Error(`${at}no source entry \`id\`. Every item names the entry it translates.`);
+                    }
+                    const target = this.locales.get(item.locale);
+                    if (!target) {
+                        throw new Error(`${at}unknown locale "${item.locale}". Call i18n_locales_list for ` +
+                            'the configured slugs.');
+                    }
+                    // Reads the group, and with it proves the source row exists
+                    // in this workspace — so a bad id fails HERE, before
+                    // anything is written, rather than partway through the
+                    // batch. The whole view is cached, not just its group id:
+                    // nothing is written during a propose, so which locales
+                    // exist cannot change under the loop, and every later item
+                    // naming the same entry answers "is this locale taken?"
+                    // from it. Keyed by id rather than by group, which is the
+                    // honest cost of not knowing two ids are siblings until one
+                    // of them has been read.
+                    let group = groups.get(item.id);
+                    if (!group) {
+                        group = await this.groups.entryLocales(type, item.id, ctx.workspaceId);
+                        groups.set(item.id, group);
+                    }
+                    const existing = group.items.find((candidate) => candidate.locale === target.slug);
+                    if (existing?.entry) {
+                        throw new Error(`${at}this entry already has a "${target.slug}" translation. Use ` +
+                            'content_propose_update on that row instead.');
+                    }
+                    const localeGroupId = group.localeGroupId;
+                    const slot = `${localeGroupId}:${target.slug}`;
+                    if (claimed.has(slot)) {
+                        throw new Error(`${at}an earlier item already translates this record into ` +
+                            `"${target.slug}". A record has one row per locale, so send each ` +
+                            'locale of it once.');
+                    }
+                    claimed.add(slot);
+                    const values = item.values ?? {};
+                    this.assertTranslatable(values, localized, at);
+                    patched.push({
+                        sourceId: item.id,
+                        localeGroupId,
+                        locale: target.slug,
+                        values
+                    });
+                    for (const [field, after] of Object.entries(values)) {
+                        changes.push({
+                            // Prefixed by position, because the card keys its
+                            // rows on `field` and five locales translating
+                            // `title` would otherwise collapse into one row.
+                            field: `items[${index}].${field}`,
+                            label: `#${index + 1} ${target.slug} · ${this.labelOf(localized.get(field)) ?? field}`,
+                            after
+                        });
+                    }
+                }
+                return {
+                    kind: exports.I18N_PROPOSAL_KINDS.bulkTranslation,
+                    target: { typeName: type.name },
+                    patch: { items: patched },
+                    summary: args.summary,
+                    changes
+                };
+            }
+        };
+    }
+};
+exports.TranslationProposalToolProvider = TranslationProposalToolProvider;
+exports.TranslationProposalToolProvider = TranslationProposalToolProvider = tslib_1.__decorate([
+    (0, common_1.Injectable)(),
+    tslib_1.__param(0, (0, content_server_1.InjectContentRegistry)()),
+    tslib_1.__param(4, (0, common_1.Optional)()),
+    tslib_1.__metadata("design:paramtypes", [Function, locale_registry_service_1.LocaleRegistryService,
+        locale_group_service_1.LocaleGroupService,
+        content_server_1.WorkspaceGrantsQuery,
+        tools_server_1.ToolRegistry])
+], TranslationProposalToolProvider);

package/dist/lib/domain/errors/index.d.ts

@@ -0,0 +1,4 @@
+export { InvalidLocaleError } from './invalid-locale.error';
+export { InvalidLocaleSetError } from './invalid-locale-set.error';
+export { UnknownLocaleError } from './unknown-locale.error';
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/domain/errors/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/lib/domain/errors/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACnE,OAAO,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/lib/domain/errors/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UnknownLocaleError = exports.InvalidLocaleSetError = exports.InvalidLocaleError = void 0;
+var invalid_locale_error_1 = require("./invalid-locale.error");
+Object.defineProperty(exports, "InvalidLocaleError", { enumerable: true, get: function () { return invalid_locale_error_1.InvalidLocaleError; } });
+var invalid_locale_set_error_1 = require("./invalid-locale-set.error");
+Object.defineProperty(exports, "InvalidLocaleSetError", { enumerable: true, get: function () { return invalid_locale_set_error_1.InvalidLocaleSetError; } });
+var unknown_locale_error_1 = require("./unknown-locale.error");
+Object.defineProperty(exports, "UnknownLocaleError", { enumerable: true, get: function () { return unknown_locale_error_1.UnknownLocaleError; } });

package/dist/lib/domain/errors/invalid-locale-set.error.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Raised by {@link LocaleSet} when the *collection* of locales violates an
+ * invariant no single {@link Locale} can guard — an empty set, a duplicate
+ * slug, not exactly one default, or removing the default. Transport-agnostic;
+ * the plugin factory surfaces it at construction.
+ */
+export declare class InvalidLocaleSetError extends Error {
+    constructor(message: string);
+}
+//# sourceMappingURL=invalid-locale-set.error.d.ts.map

package/dist/lib/domain/errors/invalid-locale-set.error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invalid-locale-set.error.d.ts","sourceRoot":"","sources":["../../../../src/lib/domain/errors/invalid-locale-set.error.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;gBAChC,OAAO,EAAE,MAAM;CAI9B"}

package/dist/lib/domain/errors/invalid-locale-set.error.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InvalidLocaleSetError = void 0;
+/**
+ * Raised by {@link LocaleSet} when the *collection* of locales violates an
+ * invariant no single {@link Locale} can guard — an empty set, a duplicate
+ * slug, not exactly one default, or removing the default. Transport-agnostic;
+ * the plugin factory surfaces it at construction.
+ */
+class InvalidLocaleSetError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'InvalidLocaleSetError';
+    }
+}
+exports.InvalidLocaleSetError = InvalidLocaleSetError;

package/dist/lib/domain/errors/invalid-locale.error.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Raised by {@link Locale.create} when a locale's slug is malformed (not the
+ * lowercase BCP-47-ish shape) or its display name is blank. Transport-agnostic
+ * — the plugin factory surfaces it at construction, so a misconfigured host
+ * fails before boot.
+ */
+export declare class InvalidLocaleError extends Error {
+    constructor(message: string);
+}
+//# sourceMappingURL=invalid-locale.error.d.ts.map

package/dist/lib/domain/errors/invalid-locale.error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invalid-locale.error.d.ts","sourceRoot":"","sources":["../../../../src/lib/domain/errors/invalid-locale.error.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;gBAC7B,OAAO,EAAE,MAAM;CAI9B"}

package/dist/lib/domain/errors/invalid-locale.error.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InvalidLocaleError = void 0;
+/**
+ * Raised by {@link Locale.create} when a locale's slug is malformed (not the
+ * lowercase BCP-47-ish shape) or its display name is blank. Transport-agnostic
+ * — the plugin factory surfaces it at construction, so a misconfigured host
+ * fails before boot.
+ */
+class InvalidLocaleError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'InvalidLocaleError';
+    }
+}
+exports.InvalidLocaleError = InvalidLocaleError;

package/dist/lib/domain/errors/unknown-locale.error.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Raised by {@link LocalePolicy.resolve} when a request names a locale slug
+ * that isn't configured. Transport-agnostic — {@link LocaleRegistryService}
+ * maps it to HTTP 400 (the uniform unknown-locale gate every request path
+ * funnels through).
+ */
+export declare class UnknownLocaleError extends Error {
+    readonly slug: string;
+    constructor(slug: string);
+}
+//# sourceMappingURL=unknown-locale.error.d.ts.map

package/dist/lib/domain/errors/unknown-locale.error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unknown-locale.error.d.ts","sourceRoot":"","sources":["../../../../src/lib/domain/errors/unknown-locale.error.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;aACb,IAAI,EAAE,MAAM;gBAAZ,IAAI,EAAE,MAAM;CAI3C"}

package/dist/lib/domain/errors/unknown-locale.error.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UnknownLocaleError = void 0;
+/**
+ * Raised by {@link LocalePolicy.resolve} when a request names a locale slug
+ * that isn't configured. Transport-agnostic — {@link LocaleRegistryService}
+ * maps it to HTTP 400 (the uniform unknown-locale gate every request path
+ * funnels through).
+ */
+class UnknownLocaleError extends Error {
+    slug;
+    constructor(slug) {
+        super(`Unknown locale "${slug}".`);
+        this.slug = slug;
+        this.name = 'UnknownLocaleError';
+    }
+}
+exports.UnknownLocaleError = UnknownLocaleError;

package/dist/lib/domain/locale-policy.d.ts

@@ -0,0 +1,42 @@
+import type { Locale } from './value-objects/locale';
+import type { LocaleSet } from './value-objects/locale-set';
+/**
+ * The locale **domain policy** — the pure fallback-chain and publish rules of
+ * the i18n context, framework- and database-free so they can be unit-tested
+ * without any content plumbing. It reads a {@link LocaleSet}; it renders no
+ * SQL. The extension adapter's `listScope` builds the equivalent query, but
+ * the *rule* it encodes lives here as the single source of truth.
+ */
+export declare class LocalePolicy {
+    private readonly locales;
+    constructor(locales: LocaleSet);
+    /**
+     * Resolve a request's locale slug: absent → the default locale; unknown →
+     * {@link UnknownLocaleError}. The uniform gate every request-facing path
+     * funnels through.
+     */
+    resolve(slug: string | undefined): Locale;
+    /**
+     * Whether a `localeFallback=default` list should **widen** to the default
+     * locale's rows: true only when default fallback is requested *and* the
+     * requested locale isn't already the default (nothing to widen to
+     * otherwise). The pure form of the extension's `listScope` strict-vs-widen
+     * branch.
+     */
+    shouldWidenToDefault(requested: Locale, fallbackRequested: boolean): boolean;
+    /**
+     * The ordered locales to try when reading a translation group in
+     * `requested`: `[requested]` in strict mode, or `[requested, default]` when
+     * default fallback applies ({@link shouldWidenToDefault}).
+     */
+    fallbackChain(requested: Locale, fallbackRequested: boolean): Locale[];
+    /**
+     * The locales that must hold a row before a translation group is
+     * considered fully published: the **default locale is always required** —
+     * a group can't go live without its canonical translation. A pure rule the
+     * publish flow can consult; the group's own per-sibling validation stays in
+     * the extension adapter.
+     */
+    requiredLocalesForPublish(): Locale[];
+}
+//# sourceMappingURL=locale-policy.d.ts.map

package/dist/lib/domain/locale-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"locale-policy.d.ts","sourceRoot":"","sources":["../../../src/lib/domain/locale-policy.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AACrD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAE5D;;;;;;GAMG;AACH,qBAAa,YAAY;IACT,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,SAAS;IAE/C;;;;OAIG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM;IAOzC;;;;;;OAMG;IACH,oBAAoB,CAChB,SAAS,EAAE,MAAM,EACjB,iBAAiB,EAAE,OAAO,GAC3B,OAAO;IAIV;;;;OAIG;IACH,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,iBAAiB,EAAE,OAAO,GAAG,MAAM,EAAE;IAMtE;;;;;;OAMG;IACH,yBAAyB,IAAI,MAAM,EAAE;CAGxC"}

package/dist/lib/domain/locale-policy.js

@@ -0,0 +1,61 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LocalePolicy = void 0;
+const errors_1 = require("./errors");
+/**
+ * The locale **domain policy** — the pure fallback-chain and publish rules of
+ * the i18n context, framework- and database-free so they can be unit-tested
+ * without any content plumbing. It reads a {@link LocaleSet}; it renders no
+ * SQL. The extension adapter's `listScope` builds the equivalent query, but
+ * the *rule* it encodes lives here as the single source of truth.
+ */
+class LocalePolicy {
+    locales;
+    constructor(locales) {
+        this.locales = locales;
+    }
+    /**
+     * Resolve a request's locale slug: absent → the default locale; unknown →
+     * {@link UnknownLocaleError}. The uniform gate every request-facing path
+     * funnels through.
+     */
+    resolve(slug) {
+        if (slug === undefined)
+            return this.locales.default();
+        const locale = this.locales.get(slug);
+        if (!locale)
+            throw new errors_1.UnknownLocaleError(slug);
+        return locale;
+    }
+    /**
+     * Whether a `localeFallback=default` list should **widen** to the default
+     * locale's rows: true only when default fallback is requested *and* the
+     * requested locale isn't already the default (nothing to widen to
+     * otherwise). The pure form of the extension's `listScope` strict-vs-widen
+     * branch.
+     */
+    shouldWidenToDefault(requested, fallbackRequested) {
+        return fallbackRequested && !requested.equals(this.locales.default());
+    }
+    /**
+     * The ordered locales to try when reading a translation group in
+     * `requested`: `[requested]` in strict mode, or `[requested, default]` when
+     * default fallback applies ({@link shouldWidenToDefault}).
+     */
+    fallbackChain(requested, fallbackRequested) {
+        return this.shouldWidenToDefault(requested, fallbackRequested)
+            ? [requested, this.locales.default()]
+            : [requested];
+    }
+    /**
+     * The locales that must hold a row before a translation group is
+     * considered fully published: the **default locale is always required** —
+     * a group can't go live without its canonical translation. A pure rule the
+     * publish flow can consult; the group's own per-sibling validation stays in
+     * the extension adapter.
+     */
+    requiredLocalesForPublish() {
+        return [this.locales.default()];
+    }
+}
+exports.LocalePolicy = LocalePolicy;