@byline/core 6.6.0 → 6.7.1

package/dist/storage/locale-resolution.d.ts

@@ -0,0 +1,76 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import type { LocaleVisibility, MissingLocalePolicy, ReadMode } from '../@types/index.js';
+import type { FlattenedFieldValue } from './storage-row-types.js';
+/**
+ * One version's entry in the `byline_document_version_locales` ledger: the
+ * concrete locales its content is complete in, or `localeAgnostic` when the
+ * version carries only the `'all'` sentinel (no localized content).
+ */
+export interface VersionLocaleLedger {
+    availableLocales: readonly string[];
+    localeAgnostic: boolean;
+}
+/**
+ * Derive a completeness ledger from loaded store rows, using the same rule the
+ * write path records: a locale is complete when it covers every localized field
+ * path the source locale has; a version with no localized rows is
+ * locale-agnostic. Used only for versions written before the ledger existed and
+ * not yet backfilled. It can only see the rows a read loaded, so a projected
+ * read of such a version may still misjudge completeness.
+ */
+export declare function deriveVersionLocaleLedger(rows: readonly FlattenedFieldValue[], sourceLocale: string): VersionLocaleLedger;
+/**
+ * The per-document facts a locale-eligibility decision needs. `ledger` is the
+ * selected version's completeness ledger; `availableLocales` is the document's
+ * saved editorial checkbox set; `advertiseLocales` is the collection's opt-in
+ * to that control.
+ */
+export interface LocaleEligibility {
+    visibility: LocaleVisibility;
+    sourceLocale: string;
+    ledger: VersionLocaleLedger;
+    advertiseLocales: boolean;
+    availableLocales: readonly string[];
+}
+/**
+ * The locale visibility a read uses: an explicit `localeVisibility` wins;
+ * otherwise `status: 'any'` implies `'editorial'` and an omitted or
+ * `'published'` status implies `'public'`. Resolving visibility never grants
+ * access; callers still authorize `'editorial'` separately.
+ */
+export declare function resolveLocaleVisibility(status: ReadMode | undefined, explicit?: LocaleVisibility): LocaleVisibility;
+/** The outcome of one read's language decision for one document version. */
+export interface ReadLocaleDecision {
+    /** The locale to restore fields in; `undefined` for a multi-locale (`'all'`) read. */
+    restoreLocale: string | undefined;
+    /** The `resolvedLocale` read metadata: the locale the fields were selected in, or `null`. */
+    resolvedLocale: string | null;
+    /** `true` when localized values must be withheld and only non-localized values returned. */
+    withholdLocalized: boolean;
+}
+/**
+ * Decide, for one document version, which locale a read restores, what it
+ * reports as `resolvedLocale`, and whether localized values must be withheld.
+ * Shared by every storage adapter so the language decision is identical across
+ * engines and is made from the whole version, before any field projection.
+ *
+ *   - `locale: 'all'` restores locale maps and reports `null`.
+ *   - A locale-agnostic version restores the requested locale and reports `null`.
+ *   - `'fallback'` restores and reports the first eligible chain entry.
+ *   - `'omit'`, `'empty'` and an omitted policy are exact: an eligible locale is
+ *     restored and reported. Under `'public'` visibility an ineligible locale
+ *     withholds localized values and reports `null`; under `'editorial'` the
+ *     exact locale is restored even when partial.
+ */
+export declare function resolveReadLocale(params: {
+    locale: string;
+    chain: readonly string[];
+    onMissingLocale: MissingLocalePolicy | undefined;
+    eligibility: LocaleEligibility;
+}): ReadLocaleDecision;

package/dist/storage/locale-resolution.js

@@ -0,0 +1,122 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+/**
+ * Derive a completeness ledger from loaded store rows, using the same rule the
+ * write path records: a locale is complete when it covers every localized field
+ * path the source locale has; a version with no localized rows is
+ * locale-agnostic. Used only for versions written before the ledger existed and
+ * not yet backfilled. It can only see the rows a read loaded, so a projected
+ * read of such a version may still misjudge completeness.
+ */
+export function deriveVersionLocaleLedger(rows, sourceLocale) {
+    const pathsByLocale = new Map();
+    for (const row of rows) {
+        if (row.locale === 'all' || row.field_type === 'meta')
+            continue;
+        let paths = pathsByLocale.get(row.locale);
+        if (paths == null) {
+            paths = new Set();
+            pathsByLocale.set(row.locale, paths);
+        }
+        paths.add(row.field_path.join('.'));
+    }
+    if (pathsByLocale.size === 0)
+        return { availableLocales: [], localeAgnostic: true };
+    const canonical = pathsByLocale.get(sourceLocale) ?? new Set();
+    const availableLocales = [];
+    for (const [locale, paths] of pathsByLocale) {
+        let covers = true;
+        for (const path of canonical) {
+            if (!paths.has(path)) {
+                covers = false;
+                break;
+            }
+        }
+        if (covers)
+            availableLocales.push(locale);
+    }
+    return { availableLocales, localeAgnostic: false };
+}
+/**
+ * Whether `locale` may be delivered for one document version.
+ *
+ *   - A locale-agnostic version renders identically everywhere: always eligible.
+ *   - The source locale is always eligible, whatever its checkbox says.
+ *   - Any other locale must be complete on the selected version.
+ *   - Under `'public'` visibility in a collection with `advertiseLocales`, it
+ *     must also be checked in the document's editorial set. An empty set
+ *     authorizes no additional translation.
+ */
+function isLocaleEligible(locale, eligibility) {
+    const { visibility, sourceLocale, ledger, advertiseLocales, availableLocales } = eligibility;
+    if (ledger.localeAgnostic)
+        return true;
+    if (locale === sourceLocale)
+        return true;
+    if (!ledger.availableLocales.includes(locale))
+        return false;
+    if (visibility === 'editorial' || !advertiseLocales)
+        return true;
+    return availableLocales.includes(locale);
+}
+/**
+ * Walk `chain` (`[requested, …, floor]`) and return the first locale eligible
+ * under `eligibility`. Every candidate must pass, so a withheld intermediate
+ * locale can never be selected. The floor is terminal and returned when no
+ * earlier candidate qualifies.
+ */
+function resolveEligibleLocale(chain, eligibility) {
+    for (const candidate of chain) {
+        if (isLocaleEligible(candidate, eligibility))
+            return candidate;
+    }
+    // biome-ignore lint/style/noNonNullAssertion: a locale chain always has a floor
+    return chain[chain.length - 1];
+}
+/**
+ * The locale visibility a read uses: an explicit `localeVisibility` wins;
+ * otherwise `status: 'any'` implies `'editorial'` and an omitted or
+ * `'published'` status implies `'public'`. Resolving visibility never grants
+ * access; callers still authorize `'editorial'` separately.
+ */
+export function resolveLocaleVisibility(status, explicit) {
+    if (explicit != null)
+        return explicit;
+    return status === 'any' ? 'editorial' : 'public';
+}
+/**
+ * Decide, for one document version, which locale a read restores, what it
+ * reports as `resolvedLocale`, and whether localized values must be withheld.
+ * Shared by every storage adapter so the language decision is identical across
+ * engines and is made from the whole version, before any field projection.
+ *
+ *   - `locale: 'all'` restores locale maps and reports `null`.
+ *   - A locale-agnostic version restores the requested locale and reports `null`.
+ *   - `'fallback'` restores and reports the first eligible chain entry.
+ *   - `'omit'`, `'empty'` and an omitted policy are exact: an eligible locale is
+ *     restored and reported. Under `'public'` visibility an ineligible locale
+ *     withholds localized values and reports `null`; under `'editorial'` the
+ *     exact locale is restored even when partial.
+ */
+export function resolveReadLocale(params) {
+    const { locale, chain, onMissingLocale, eligibility } = params;
+    if (locale === 'all') {
+        return { restoreLocale: undefined, resolvedLocale: null, withholdLocalized: false };
+    }
+    if (eligibility.ledger.localeAgnostic) {
+        return { restoreLocale: locale, resolvedLocale: null, withholdLocalized: false };
+    }
+    if (onMissingLocale === 'fallback') {
+        const selected = resolveEligibleLocale(chain, eligibility);
+        return { restoreLocale: selected, resolvedLocale: selected, withholdLocalized: false };
+    }
+    if (eligibility.visibility === 'public' && !isLocaleEligible(locale, eligibility)) {
+        return { restoreLocale: locale, resolvedLocale: null, withholdLocalized: true };
+    }
+    return { restoreLocale: locale, resolvedLocale: locale, withholdLocalized: false };
+}

package/dist/storage/locale-resolution.test.node.d.ts

@@ -0,0 +1,8 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+export {};

package/dist/storage/locale-resolution.test.node.js

@@ -0,0 +1,245 @@
+/**
+ * This Source Code is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * Copyright (c) Infonomic Company Limited
+ */
+import { describe, expect, it } from 'vitest';
+import { deriveVersionLocaleLedger, resolveLocaleVisibility, resolveReadLocale, } from './locale-resolution.js';
+// The eligibility rule and the fallback walk are private to the module; these
+// helpers observe them through `resolveReadLocale`, the only adapter-facing
+// entry point. A locale is eligible exactly when a fallback read toward the
+// source selects it, and the walk's result is the locale that read restores.
+function isLocaleEligible(locale, eligibility) {
+    const chain = locale === eligibility.sourceLocale ? [locale] : [locale, eligibility.sourceLocale];
+    return (resolveReadLocale({ locale, chain, onMissingLocale: 'fallback', eligibility }).restoreLocale ===
+        locale);
+}
+function resolveEligibleLocale(chain, eligibility) {
+    const decision = resolveReadLocale({
+        locale: chain[0],
+        chain,
+        onMissingLocale: 'fallback',
+        eligibility,
+    });
+    return decision.restoreLocale;
+}
+describe('deriveVersionLocaleLedger', () => {
+    const row = (locale, path, field_type = 'text') => ({ locale, field_path: path.split('.'), field_type });
+    it('records the locales that cover every source-locale localized path', () => {
+        const ledger = deriveVersionLocaleLedger([
+            row('en', 'title'),
+            row('en', 'body'),
+            row('de', 'title'),
+            row('de', 'body'),
+            row('fr', 'title'),
+            row('all', 'sku'),
+            row('all', 'content.0', 'meta'),
+        ], 'en');
+        expect(ledger).toEqual({ availableLocales: ['en', 'de'], localeAgnostic: false });
+    });
+    it('marks a version with no localized rows as locale-agnostic', () => {
+        expect(deriveVersionLocaleLedger([row('all', 'sku')], 'en')).toEqual({
+            availableLocales: [],
+            localeAgnostic: true,
+        });
+    });
+});
+describe('isLocaleEligible', () => {
+    const base = {
+        visibility: 'public',
+        sourceLocale: 'en',
+        ledger: { availableLocales: ['en', 'es', 'de'], localeAgnostic: false },
+        advertiseLocales: true,
+        availableLocales: ['de'],
+    };
+    it('public: a complete and checked translation is eligible', () => {
+        expect(isLocaleEligible('de', base)).toBe(true);
+    });
+    it('public: a complete but unchecked translation is not eligible', () => {
+        expect(isLocaleEligible('es', base)).toBe(false);
+    });
+    it('public: a checked but incomplete translation is not eligible', () => {
+        expect(isLocaleEligible('fr', { ...base, availableLocales: ['fr'] })).toBe(false);
+    });
+    it('public: the source is eligible even when its checkbox is off', () => {
+        expect(isLocaleEligible('en', { ...base, availableLocales: [] })).toBe(true);
+    });
+    it('public: an empty advertised set authorizes no additional translation', () => {
+        expect(isLocaleEligible('de', { ...base, availableLocales: [] })).toBe(false);
+    });
+    it('public: a collection without advertiseLocales is gated by completeness alone', () => {
+        const optOut = { ...base, advertiseLocales: false, availableLocales: [] };
+        expect(isLocaleEligible('es', optOut)).toBe(true);
+        expect(isLocaleEligible('fr', optOut)).toBe(false);
+    });
+    it('a locale-agnostic version is eligible in every locale', () => {
+        const agnostic = { ...base, ledger: { availableLocales: [], localeAgnostic: true } };
+        expect(isLocaleEligible('fr', agnostic)).toBe(true);
+    });
+    it('editorial: a complete but unchecked translation is eligible', () => {
+        expect(isLocaleEligible('es', { ...base, visibility: 'editorial' })).toBe(true);
+    });
+    it('editorial: completeness is still required', () => {
+        expect(isLocaleEligible('fr', { ...base, visibility: 'editorial' })).toBe(false);
+    });
+});
+describe('resolveEligibleLocale', () => {
+    const base = {
+        visibility: 'public',
+        sourceLocale: 'en',
+        ledger: { availableLocales: ['en', 'es', 'es-MX'], localeAgnostic: false },
+        advertiseLocales: true,
+        availableLocales: [],
+    };
+    it('public: an unchecked translation falls back to the source', () => {
+        expect(resolveEligibleLocale(['es', 'en'], base)).toBe('en');
+    });
+    it('editorial: the same unchecked translation is selected', () => {
+        expect(resolveEligibleLocale(['es', 'en'], { ...base, visibility: 'editorial' })).toBe('es');
+    });
+    it('public: a withheld intermediate candidate is skipped', () => {
+        // Named fallback chains are not configurable yet; this pins that every
+        // candidate must satisfy the policy if they are added later.
+        const eligibility = { ...base, availableLocales: ['es'] };
+        expect(resolveEligibleLocale(['es-MX', 'es', 'en'], eligibility)).toBe('es');
+        expect(resolveEligibleLocale(['es-MX', 'es', 'en'], base)).toBe('en');
+    });
+    it('returns the floor when nothing earlier qualifies', () => {
+        expect(resolveEligibleLocale(['fr', 'en'], base)).toBe('en');
+    });
+});
+describe('resolveLocaleVisibility', () => {
+    it('defaults to public for an omitted or published status', () => {
+        expect(resolveLocaleVisibility(undefined)).toBe('public');
+        expect(resolveLocaleVisibility('published')).toBe('public');
+    });
+    it('defaults to editorial for status any', () => {
+        expect(resolveLocaleVisibility('any')).toBe('editorial');
+    });
+    it('an explicit value wins over the status default', () => {
+        expect(resolveLocaleVisibility('published', 'editorial')).toBe('editorial');
+        expect(resolveLocaleVisibility('any', 'public')).toBe('public');
+    });
+});
+describe('resolveReadLocale — the seven resolvedLocale result types', () => {
+    const eligibility = (overrides = {}) => ({
+        visibility: 'public',
+        sourceLocale: 'en',
+        // Spanish complete but unchecked; German partial (not in the ledger).
+        ledger: { availableLocales: ['en', 'es'], localeAgnostic: false },
+        advertiseLocales: true,
+        availableLocales: [],
+        ...overrides,
+    });
+    const chain = (locale) => (locale === 'en' ? ['en'] : [locale, 'en']);
+    it('R1: fallback reports the selected permitted locale, including the source', () => {
+        expect(resolveReadLocale({
+            locale: 'es',
+            chain: chain('es'),
+            onMissingLocale: 'fallback',
+            eligibility: eligibility({ availableLocales: ['es'] }),
+        })).toEqual({ restoreLocale: 'es', resolvedLocale: 'es', withholdLocalized: false });
+        expect(resolveReadLocale({
+            locale: 'es',
+            chain: chain('es'),
+            onMissingLocale: 'fallback',
+            eligibility: eligibility(),
+        })).toEqual({ restoreLocale: 'en', resolvedLocale: 'en', withholdLocalized: false });
+        expect(resolveReadLocale({
+            locale: 'es',
+            chain: chain('es'),
+            onMissingLocale: 'fallback',
+            eligibility: eligibility({ visibility: 'editorial' }),
+        })).toEqual({ restoreLocale: 'es', resolvedLocale: 'es', withholdLocalized: false });
+    });
+    it('R2: omit reports the requested locale', () => {
+        expect(resolveReadLocale({
+            locale: 'es',
+            chain: chain('es'),
+            onMissingLocale: 'omit',
+            eligibility: eligibility({ availableLocales: ['es'] }),
+        })).toEqual({ restoreLocale: 'es', resolvedLocale: 'es', withholdLocalized: false });
+    });
+    it('R3: public empty with an eligible locale reports it, with no fallback', () => {
+        expect(resolveReadLocale({
+            locale: 'es',
+            chain: chain('es'),
+            onMissingLocale: 'empty',
+            eligibility: eligibility({ availableLocales: ['es'] }),
+        })).toEqual({ restoreLocale: 'es', resolvedLocale: 'es', withholdLocalized: false });
+    });
+    it('R4: public empty with an unavailable translation withholds values and reports null', () => {
+        // Complete but unchecked.
+        expect(resolveReadLocale({
+            locale: 'es',
+            chain: chain('es'),
+            onMissingLocale: 'empty',
+            eligibility: eligibility(),
+        })).toEqual({ restoreLocale: 'es', resolvedLocale: null, withholdLocalized: true });
+        // Checked but incomplete.
+        expect(resolveReadLocale({
+            locale: 'de',
+            chain: chain('de'),
+            onMissingLocale: 'empty',
+            eligibility: eligibility({ availableLocales: ['de'] }),
+        })).toEqual({ restoreLocale: 'de', resolvedLocale: null, withholdLocalized: true });
+        // An omitted policy is exact, like empty.
+        expect(resolveReadLocale({
+            locale: 'es',
+            chain: chain('es'),
+            onMissingLocale: undefined,
+            eligibility: eligibility(),
+        }).withholdLocalized).toBe(true);
+    });
+    it('R4: public empty still serves the source even when its checkbox is off', () => {
+        expect(resolveReadLocale({
+            locale: 'en',
+            chain: chain('en'),
+            onMissingLocale: 'empty',
+            eligibility: eligibility(),
+        })).toEqual({ restoreLocale: 'en', resolvedLocale: 'en', withholdLocalized: false });
+    });
+    it('R5: editorial empty reports the requested locale even when partial', () => {
+        expect(resolveReadLocale({
+            locale: 'de',
+            chain: chain('de'),
+            onMissingLocale: 'empty',
+            eligibility: eligibility({ visibility: 'editorial' }),
+        })).toEqual({ restoreLocale: 'de', resolvedLocale: 'de', withholdLocalized: false });
+    });
+    it('R6: a multi-locale read reports null and restores locale maps', () => {
+        expect(resolveReadLocale({
+            locale: 'all',
+            chain: ['all'],
+            onMissingLocale: 'empty',
+            eligibility: eligibility({ visibility: 'editorial' }),
+        })).toEqual({ restoreLocale: undefined, resolvedLocale: null, withholdLocalized: false });
+    });
+    it('R7: a locale-agnostic version reports null under every policy', () => {
+        const agnostic = eligibility({ ledger: { availableLocales: [], localeAgnostic: true } });
+        for (const onMissingLocale of ['fallback', 'omit', 'empty', undefined]) {
+            expect(resolveReadLocale({
+                locale: 'es',
+                chain: chain('es'),
+                onMissingLocale,
+                eligibility: agnostic,
+            })).toEqual({ restoreLocale: 'es', resolvedLocale: null, withholdLocalized: false });
+        }
+    });
+    it('a non-advertised collection withholds an incomplete translation publicly', () => {
+        expect(resolveReadLocale({
+            locale: 'de',
+            chain: chain('de'),
+            onMissingLocale: 'empty',
+            eligibility: eligibility({ advertiseLocales: false }),
+        }).withholdLocalized).toBe(true);
+        expect(resolveReadLocale({
+            locale: 'es',
+            chain: chain('es'),
+            onMissingLocale: 'empty',
+            eligibility: eligibility({ advertiseLocales: false }),
+        })).toEqual({ restoreLocale: 'es', resolvedLocale: 'es', withholdLocalized: false });
+    });
+});

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/core",
   "private": false,
   "license": "MPL-2.0",
-  "version": "6.6.0",
+  "version": "6.7.1",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -87,7 +87,7 @@
     "sharp": "^0.35.4",
     "uuid": "^14.0.2",
     "zod": "^4.6.5",
-    "@byline/auth": "6.6.0"
+    "@byline/auth": "6.7.1"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.14",

package/dist/schemas/zod/review-comparison-probe.test.node.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/schemas/zod/review-comparison-probe.test.node.js

@@ -1,26 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { defineCollection } from '../../@types/collection-types.js';
-import { createCollectionSchemas } from './builder.js';
-const collection = defineCollection({
-    path: 'review-probe', labels: { singular: 'Probe', plural: 'Probes' },
-    fields: [{ name: 'choice', type: 'select', options: [{ label: 'A', value: 'a' }] }],
-});
-const schemas = createCollectionSchemas(collection);
-const doc = {
-    id: '550e8400-e29b-41d4-a716-446655440000', status: 'draft',
-    createdAt: '2026-09-16T12:00:00.000Z', updatedAt: '2026-09-16T12:00:00.000Z',
-    fields: { choice: 'a' },
-};
-const response = {
-    docs: [doc], meta: { page: 1, pageSize: 10, total: 1, totalPages: 1 },
-    included: { collection: { id: 'review-probe', path: collection.path, labels: collection.labels } },
-};
-describe('review comparison: invalid values reject a read response', () => {
-    it('accepts a valid response', () => expect(schemas.list.safeParse(response).success).toBe(true));
-    it('rejects the response if one document has an invalid select', () => {
-        expect(schemas.list.safeParse({ ...response, docs: [doc, { ...doc, fields: { choice: 'bogus' } }] }).success).toBe(false);
-    });
-    it('rejects the response if one document has an invalid status', () => {
-        expect(schemas.list.safeParse({ ...response, docs: [doc, { ...doc, status: 'bogus' }] }).success).toBe(false);
-    });
-});