@beechcms/core 0.9.5 → 0.9.7

package/dist/engine/ddl.js

@@ -25,7 +25,7 @@ const BRANCH_TYPE_SQL = {
 /**
  * System-defined columns that exist on all content tables.
  */
-export const SYSTEM_COLUMNS = new Set(['id', 'slug', 'status', 'created_at', 'updated_at', 'deleted_at']);
+export const SYSTEM_COLUMNS = new Set(['id', 'slug', 'status', 'created_at', 'updated_at']);
 /**
  * Returns the SQL table name for a given Seed.
  *
@@ -70,8 +70,6 @@ export function vectorTableName(seed) {
  * @returns True if the column is valid, false otherwise.
  */
 export function isValidColumn(seed, col) {
-    if (col === 'deleted_at')
-        return seed.softDelete === true;
     if (SYSTEM_COLUMNS.has(col))
         return true;
     return seed.branches.some(b => b.alias === col);
@@ -127,12 +125,7 @@ export function generateCreateTable(seed) {
     const lines = [
         `CREATE TABLE IF NOT EXISTS ${table} (`,
         `  id         TEXT    NOT NULL PRIMARY KEY,`,
-        // Soft-delete tables carry uniqueness in a PARTIAL unique index instead, so a trashed
-        // row stops reserving its slug. An inline UNIQUE would become a sqlite_autoindex that
-        // no ALTER TABLE can drop later.
-        seed.softDelete
-            ? `  slug       TEXT    NOT NULL,`
-            : `  slug       TEXT    NOT NULL UNIQUE,`,
+        `  slug       TEXT    NOT NULL UNIQUE,`,
         `  status     TEXT    NOT NULL DEFAULT 'draft' CHECK (status IN ('draft', 'review', 'published', 'archived')),`,
     ];
     for (const branch of seed.branches) {
@@ -151,9 +144,7 @@ export function generateCreateTable(seed) {
         }
     }
     lines.push(`  created_at INTEGER NOT NULL DEFAULT (unixepoch()),`);
-    lines.push(`  updated_at INTEGER NOT NULL DEFAULT (unixepoch())` + (seed.softDelete ? ',' : ''));
-    if (seed.softDelete)
-        lines.push(`  deleted_at INTEGER`);
+    lines.push(`  updated_at INTEGER NOT NULL DEFAULT (unixepoch())`);
     lines.push(`);`);
     return lines.join('\n');
 }
@@ -187,10 +178,6 @@ export function generateDraftTable(seed) {
         }
     }
     lines.push(`  _touched_fields  TEXT,`);
-    // Live-row `updated_at` as it stood when this draft was created, written once and never re-based.
-    // Nullable on purpose: drafts created before optimistic-concurrency publish existed carry NULL and
-    // publish unchecked, so enabling this feature cannot block an in-flight draft.
-    lines.push(`  live_snapshot_at  INTEGER,`);
     lines.push(`  updated_at  INTEGER NOT NULL DEFAULT (unixepoch())`);
     lines.push(`);`);
     return lines.join('\n');
@@ -206,21 +193,6 @@ export function generateAddColumn(seed, branch) {
     const { sqlType } = BRANCH_TYPE_SQL[branch.type];
     return `ALTER TABLE ${tableName(seed)} ADD COLUMN ${branch.alias} ${sqlType}${buildForeignKeyClause(branch)};`;
 }
-/**
- * Generates the `ALTER TABLE content_{slug}_drafts ADD COLUMN live_snapshot_at INTEGER` statement
- * for a draft table provisioned before the column existed.
- *
- * System column, not a branch — `generateAddColumn` iterates `seed.branches` and can never emit it.
- * NOT idempotent: `ADD COLUMN` fails when the column is already present and `ISchemaMutator.execDdl`
- * aborts the whole batch on the first failing statement, so the caller MUST check the physical
- * columns first (see `planExtendSeed`).
- *
- * @param seed The seed definition. Caller must have verified `seed.allowDrafts`.
- * @returns The ALTER TABLE statement.
- */
-export function generateAddDraftSnapshotColumn(seed) {
-    return `ALTER TABLE content_${seed.slug}_drafts ADD COLUMN live_snapshot_at INTEGER;`;
-}
 /**
  * Generates SQL index statements for system fields (status, created_at)
  * and indexable branch columns.
@@ -248,11 +220,6 @@ export function generateIndexes(seed) {
             indexes.push(`CREATE INDEX IF NOT EXISTS idx_${slug}_${branch.alias}_bidx ON ${table}(${branch.alias}_bidx);`);
         }
     }
-    if (seed.softDelete) {
-        indexes.push(`CREATE INDEX IF NOT EXISTS idx_${slug}_deleted_at ON ${table}(deleted_at);`);
-        // Active rows only: a trashed row releases its slug for reuse (feature brief §4).
-        indexes.push(`CREATE UNIQUE INDEX IF NOT EXISTS idx_${slug}_slug_active ON ${table}(slug) WHERE deleted_at IS NULL;`);
-    }
     return indexes;
 }
 /**
@@ -366,9 +333,6 @@ export function getExpectedColumns(seed) {
         ...branchCols,
         { name: 'created_at', sqlType: 'INTEGER', notNull: true, isPk: false },
         { name: 'updated_at', sqlType: 'INTEGER', notNull: true, isPk: false },
-        ...(seed.softDelete
-            ? [{ name: 'deleted_at', sqlType: 'INTEGER', notNull: false, isPk: false }]
-            : []),
     ];
 }
 /**
@@ -552,23 +516,3 @@ export function generateRetypeColumn(seed, branch) {
         stmts.push(...rebuild(draftTableName(seed)));
     return stmts;
 }
-/**
- * Additive statements that turn soft delete on for a table that already exists.
- *
- * The partial unique index is emitted for correctness on tables that were CREATED with
- * `softDelete: true`. On a pre-existing table the inline `slug … UNIQUE` survives as a
- * sqlite_autoindex that SQLite cannot drop via ALTER; there the partial index is redundant
- * and a trashed slug stays reserved until the table is rebuilt (see ROADMAP deferral).
- * Returns [] when the seed does not opt in.
- */
-export function generateEnableSoftDelete(seed) {
-    if (!seed.softDelete)
-        return [];
-    const table = tableName(seed);
-    const slug = seed.slug;
-    return [
-        `ALTER TABLE ${table} ADD COLUMN deleted_at INTEGER;`,
-        `CREATE INDEX IF NOT EXISTS idx_${slug}_deleted_at ON ${table}(deleted_at);`,
-        `CREATE UNIQUE INDEX IF NOT EXISTS idx_${slug}_slug_active ON ${table}(slug) WHERE deleted_at IS NULL;`,
-    ];
-}

package/dist/engine/localization.d.ts

@@ -0,0 +1,127 @@
+/**
+ * @module engine/localization
+ * Field-level localization primitives for the Botanical Engine. A localized branch keeps its native
+ * TEXT column and stores a locale dictionary in it (`{"it":"Scarpa","en":"Shoe"}`), so ids, relations
+ * and metrics are untouched and toggling `Branch.localized` never emits DDL. Pure functions: no I/O and
+ * no settings access — callers pass the project's {@link LocaleConfig}.
+ */
+import type { Branch, BranchType, Seed } from './types.js';
+/**
+ * Locale code grammar (v1): ISO 639 language (2–3 lowercase letters), optionally followed by an ISO 3166
+ * region (2 uppercase letters) or a UN M.49 area (3 digits) — `it`, `en`, `pt-BR`, `es-419`. Script
+ * subtags (`zh-Hant`) are outside v1. The grammar doubles as an injection guard: validated codes are
+ * later interpolated into SQLite JSON paths.
+ */
+export declare const LOCALE_CODE_RE: RegExp;
+/** Branch types that may carry `localized: true`. */
+export declare const LOCALIZABLE_BRANCH_TYPES: ReadonlySet<BranchType>;
+/**
+ * Project-level language configuration. Invariant (guaranteed by its producer): `locales` is non-empty,
+ * every entry matches {@link LOCALE_CODE_RE}, and it contains `defaultLocale`.
+ */
+export interface LocaleConfig {
+    readonly locales: readonly string[];
+    readonly defaultLocale: string;
+}
+/** A locale dictionary as stored in the branch column: locale code → value. */
+export type LocalizedDictionary = Record<string, unknown>;
+/**
+ * A validated write for a localized branch: registered locale code → new value, or `null` meaning
+ * "clear this locale". Locales absent from the patch must be left untouched by the write path.
+ */
+export type LocalizedPatch = Record<string, unknown>;
+/** True when `value` is a string matching {@link LOCALE_CODE_RE}. */
+export declare function isLocaleCode(value: unknown): value is string;
+/**
+ * True when the branch is localized AND its type supports it. A malformed definition that slipped past
+ * seed validation (e.g. `localized: true` on a `number`) is treated as not localized, never as a dictionary.
+ */
+export declare function isLocalizedBranch(branch: Pick<Branch, 'type' | 'localized'>): boolean;
+/**
+ * Structural check used on READ paths (no config available): a non-empty plain object whose every key
+ * matches the locale-code grammar. A richtext envelope (`schemaVersion`, `doc`) and a TipTap doc
+ * (`type`, `content`) never match.
+ */
+export declare function isLocaleDictionary(value: unknown): value is LocalizedDictionary;
+/**
+ * Stricter check used on WRITE paths: a locale dictionary with at least one REGISTERED locale key.
+ * Without the registration requirement a legitimate json value such as `{"url": "…", "alt": "…"}` —
+ * whose keys happen to match the grammar — would be read as a dictionary of unregistered locales and
+ * silently emptied.
+ */
+export declare function isLocalizedWriteDictionary(value: unknown, config: LocaleConfig): value is LocalizedDictionary;
+/**
+ * Normalises any accepted write value of a localized branch into a {@link LocalizedPatch}:
+ * - a write dictionary keeps its registered locales, in `config.locales` order; unregistered locale
+ *   keys are dropped;
+ * - any other value (string, richtext doc, non-dictionary json) is the default-locale value;
+ * - `null`, `undefined` and blank strings become `null` ("clear this locale").
+ * Idempotent: a patch passed back in yields the same patch.
+ */
+export declare function toLocalizedPatch(value: unknown, config: LocaleConfig): LocalizedPatch;
+/**
+ * Removes `null` / `undefined` / blank-string entries. Returns `null` when nothing remains, so an
+ * all-cleared dictionary is stored as SQL NULL rather than `{}`. Keys are otherwise preserved as-is —
+ * including locales no longer registered, which must never be dropped by a write (brief §2, no data loss).
+ */
+export declare function compactLocalizedDictionary(value: LocalizedDictionary): LocalizedDictionary | null;
+/**
+ * The settings subset {@link resolveLocaleConfig} reads. Structural, so this module stays free of
+ * settings imports; `SiteSettings` satisfies it.
+ */
+export interface LocaleSettings {
+    readonly locales?: readonly string[] | null;
+    readonly defaultLocale?: string | null;
+    readonly defaultLanguage: string;
+}
+/**
+ * Builds the project's {@link LocaleConfig}, repairing whatever a hand-edited settings row could break so
+ * the LocaleConfig invariant always holds:
+ * - `locales`: the stored list minus invalid codes and duplicates; when nothing remains (never configured,
+ *   `[]`, corrupt), the implicit single-language config `[defaultLanguage]` (brief §2), which keeps the
+ *   feature invisible to a mono-lingual project;
+ * - `defaultLocale`: the stored value when it belongs to `locales`, else `locales[0]`.
+ */
+export declare function resolveLocaleConfig(settings: LocaleSettings): LocaleConfig;
+/**
+ * Merges a write into the value stored for a localized branch. The write path's only way to persist a
+ * localized value, so a translation the write does not mention is never dropped (brief §2):
+ * - `write === null` clears the whole field (an explicit null keeps its pre-localization meaning);
+ * - otherwise the write is normalised with {@link toLocalizedPatch}: every registered locale it names
+ *   overwrites that locale, a `null` entry clears that locale only, and every other stored locale —
+ *   including ones no longer registered — is kept as-is;
+ * - a stored legacy value (written before the branch became localized) is the default-locale value.
+ * @returns The compacted dictionary, or `null` when no locale keeps a value.
+ */
+export declare function applyLocalizedPatch(branch: Pick<Branch, 'type' | 'localized'>, stored: unknown, write: unknown, config: LocaleConfig): LocalizedDictionary | null;
+/** Aliases of the localized branches a write carries — the fields it must merge rather than replace. */
+export declare function localizedAliasesIn(seed: Pick<Seed, 'branches'>, data: Record<string, unknown>): string[];
+/**
+ * Returns `data` with every localized branch it carries merged into `stored` via
+ * {@link applyLocalizedPatch}; other keys pass through untouched. `stored` is the entry's current values
+ * (`null` on create, which only compacts). Returns `data` itself when `config` is undefined or no localized
+ * branch is written.
+ */
+export declare function mergeLocalizedFields(seed: Pick<Seed, 'branches'>, stored: Record<string, unknown> | null, data: Record<string, unknown>, config: LocaleConfig | undefined): Record<string, unknown>;
+/**
+ * Resolves a stored localized value to one language: the requested locale, then the default locale, then the
+ * first stored translation (stored key order), then `null`. A legacy value that is not a dictionary is returned
+ * as-is. Non-localized branches return `value` unchanged. `buildSelectQuery` applies the same chain in SQL, so
+ * filters and ORDER BY compare exactly what a reader sees.
+ */
+export declare function resolveLocalizedValue(branch: Pick<Branch, 'type' | 'localized'>, value: unknown, locale: string, config: LocaleConfig): unknown;
+/**
+ * Returns a copy of `data` with every localized branch resolved to `locale` (default: the default locale)
+ * via {@link resolveLocalizedValue}. Returns `data` itself when `config` is undefined.
+ */
+export declare function resolveLocalizedFields(seed: Pick<Seed, 'branches'>, data: Record<string, unknown>, config: LocaleConfig | undefined, locale?: string): Record<string, unknown>;
+/**
+ * The whole dictionary of a stored localized value, for readers asking every language (`?lang=all`):
+ * a stored dictionary as-is — unregistered locales included, nothing is hidden (brief §2) — a legacy
+ * value as `{ [defaultLocale]: value }` (the write path's reading of it), a blank value as `null`.
+ * Non-localized branches return `value` unchanged.
+ */
+export declare function asLocaleDictionary(branch: Pick<Branch, 'type' | 'localized'>, value: unknown, config: LocaleConfig): unknown;
+/** Returns a copy of `data` with every localized branch it carries passed through {@link asLocaleDictionary}. */
+export declare function asLocaleDictionaries(seed: Pick<Seed, 'branches'>, data: Record<string, unknown>, config: LocaleConfig): Record<string, unknown>;
+//# sourceMappingURL=localization.d.ts.map

package/dist/engine/localization.d.ts.map

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

package/dist/engine/localization.js

@@ -0,0 +1,212 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+import { cleanString, isPlainObject } from './validation/primitives.js';
+/**
+ * Locale code grammar (v1): ISO 639 language (2–3 lowercase letters), optionally followed by an ISO 3166
+ * region (2 uppercase letters) or a UN M.49 area (3 digits) — `it`, `en`, `pt-BR`, `es-419`. Script
+ * subtags (`zh-Hant`) are outside v1. The grammar doubles as an injection guard: validated codes are
+ * later interpolated into SQLite JSON paths.
+ */
+export const LOCALE_CODE_RE = /^[a-z]{2,3}(?:-(?:[A-Z]{2}|[0-9]{3}))?$/;
+/** Branch types that may carry `localized: true`. */
+export const LOCALIZABLE_BRANCH_TYPES = new Set(['text', 'richtext', 'json']);
+/** True when `value` is a string matching {@link LOCALE_CODE_RE}. */
+export function isLocaleCode(value) {
+    return typeof value === 'string' && LOCALE_CODE_RE.test(value);
+}
+/**
+ * True when the branch is localized AND its type supports it. A malformed definition that slipped past
+ * seed validation (e.g. `localized: true` on a `number`) is treated as not localized, never as a dictionary.
+ */
+export function isLocalizedBranch(branch) {
+    return branch.localized === true && LOCALIZABLE_BRANCH_TYPES.has(branch.type);
+}
+/**
+ * Structural check used on READ paths (no config available): a non-empty plain object whose every key
+ * matches the locale-code grammar. A richtext envelope (`schemaVersion`, `doc`) and a TipTap doc
+ * (`type`, `content`) never match.
+ */
+export function isLocaleDictionary(value) {
+    if (!isPlainObject(value))
+        return false;
+    const keys = Object.keys(value);
+    return keys.length > 0 && keys.every(isLocaleCode);
+}
+/**
+ * Stricter check used on WRITE paths: a locale dictionary with at least one REGISTERED locale key.
+ * Without the registration requirement a legitimate json value such as `{"url": "…", "alt": "…"}` —
+ * whose keys happen to match the grammar — would be read as a dictionary of unregistered locales and
+ * silently emptied.
+ */
+export function isLocalizedWriteDictionary(value, config) {
+    return isLocaleDictionary(value) && Object.keys(value).some((key) => config.locales.includes(key));
+}
+function isBlankLocaleValue(value) {
+    return value === null || value === undefined || (typeof value === 'string' && cleanString(value) === '');
+}
+/**
+ * Normalises any accepted write value of a localized branch into a {@link LocalizedPatch}:
+ * - a write dictionary keeps its registered locales, in `config.locales` order; unregistered locale
+ *   keys are dropped;
+ * - any other value (string, richtext doc, non-dictionary json) is the default-locale value;
+ * - `null`, `undefined` and blank strings become `null` ("clear this locale").
+ * Idempotent: a patch passed back in yields the same patch.
+ */
+export function toLocalizedPatch(value, config) {
+    const source = isLocalizedWriteDictionary(value, config)
+        ? value
+        : { [config.defaultLocale]: value };
+    const patch = {};
+    for (const locale of config.locales) {
+        if (!Object.hasOwn(source, locale))
+            continue;
+        patch[locale] = isBlankLocaleValue(source[locale]) ? null : source[locale];
+    }
+    return patch;
+}
+/**
+ * Removes `null` / `undefined` / blank-string entries. Returns `null` when nothing remains, so an
+ * all-cleared dictionary is stored as SQL NULL rather than `{}`. Keys are otherwise preserved as-is —
+ * including locales no longer registered, which must never be dropped by a write (brief §2, no data loss).
+ */
+export function compactLocalizedDictionary(value) {
+    const compact = {};
+    for (const [locale, localeValue] of Object.entries(value)) {
+        if (isBlankLocaleValue(localeValue))
+            continue;
+        compact[locale] = localeValue;
+    }
+    return Object.keys(compact).length > 0 ? compact : null;
+}
+/** Content locale used when neither stored `locales` nor a valid `defaultLanguage` is available. */
+const FALLBACK_LOCALE = 'en';
+/**
+ * Builds the project's {@link LocaleConfig}, repairing whatever a hand-edited settings row could break so
+ * the LocaleConfig invariant always holds:
+ * - `locales`: the stored list minus invalid codes and duplicates; when nothing remains (never configured,
+ *   `[]`, corrupt), the implicit single-language config `[defaultLanguage]` (brief §2), which keeps the
+ *   feature invisible to a mono-lingual project;
+ * - `defaultLocale`: the stored value when it belongs to `locales`, else `locales[0]`.
+ */
+export function resolveLocaleConfig(settings) {
+    const stored = [...new Set((settings.locales ?? []).filter(isLocaleCode))];
+    const implicit = isLocaleCode(settings.defaultLanguage) ? settings.defaultLanguage : FALLBACK_LOCALE;
+    const locales = stored.length > 0 ? stored : [implicit];
+    const defaultLocale = settings.defaultLocale && locales.includes(settings.defaultLocale)
+        ? settings.defaultLocale
+        : locales[0];
+    return { locales, defaultLocale };
+}
+/**
+ * True when a STORED value of a localized branch is a locale dictionary. Text and richtext cannot hold an
+ * object keyed only by locale codes for any other reason; json can (`{"url": "…", "alt": "…"}`), so a json
+ * object counts only when at least one key is a registered locale — otherwise it is a legacy value written
+ * before the branch became localized.
+ */
+function isStoredLocaleDictionary(branch, value, config) {
+    if (!isLocalizedBranch(branch) || !isLocaleDictionary(value))
+        return false;
+    return branch.type !== 'json' || Object.keys(value).some((key) => config.locales.includes(key));
+}
+/**
+ * Merges a write into the value stored for a localized branch. The write path's only way to persist a
+ * localized value, so a translation the write does not mention is never dropped (brief §2):
+ * - `write === null` clears the whole field (an explicit null keeps its pre-localization meaning);
+ * - otherwise the write is normalised with {@link toLocalizedPatch}: every registered locale it names
+ *   overwrites that locale, a `null` entry clears that locale only, and every other stored locale —
+ *   including ones no longer registered — is kept as-is;
+ * - a stored legacy value (written before the branch became localized) is the default-locale value.
+ * @returns The compacted dictionary, or `null` when no locale keeps a value.
+ */
+export function applyLocalizedPatch(branch, stored, write, config) {
+    if (write === null)
+        return null;
+    const merged = isStoredLocaleDictionary(branch, stored, config)
+        ? { ...stored }
+        : isBlankLocaleValue(stored) ? {} : { [config.defaultLocale]: stored };
+    Object.assign(merged, toLocalizedPatch(write, config));
+    return compactLocalizedDictionary(merged);
+}
+/** Aliases of the localized branches a write carries — the fields it must merge rather than replace. */
+export function localizedAliasesIn(seed, data) {
+    return seed.branches
+        .filter((branch) => isLocalizedBranch(branch) && Object.hasOwn(data, branch.alias) && data[branch.alias] !== undefined)
+        .map((branch) => branch.alias);
+}
+/**
+ * Returns `data` with every localized branch it carries merged into `stored` via
+ * {@link applyLocalizedPatch}; other keys pass through untouched. `stored` is the entry's current values
+ * (`null` on create, which only compacts). Returns `data` itself when `config` is undefined or no localized
+ * branch is written.
+ */
+export function mergeLocalizedFields(seed, stored, data, config) {
+    if (!config)
+        return data;
+    const aliases = localizedAliasesIn(seed, data);
+    if (aliases.length === 0)
+        return data;
+    const merged = { ...data };
+    for (const branch of seed.branches) {
+        if (!aliases.includes(branch.alias))
+            continue;
+        merged[branch.alias] = applyLocalizedPatch(branch, stored?.[branch.alias], data[branch.alias], config);
+    }
+    return merged;
+}
+/**
+ * Resolves a stored localized value to one language: the requested locale, then the default locale, then the
+ * first stored translation (stored key order), then `null`. A legacy value that is not a dictionary is returned
+ * as-is. Non-localized branches return `value` unchanged. `buildSelectQuery` applies the same chain in SQL, so
+ * filters and ORDER BY compare exactly what a reader sees.
+ */
+export function resolveLocalizedValue(branch, value, locale, config) {
+    if (!isStoredLocaleDictionary(branch, value, config))
+        return value;
+    if (!isBlankLocaleValue(value[locale]))
+        return value[locale];
+    if (!isBlankLocaleValue(value[config.defaultLocale]))
+        return value[config.defaultLocale];
+    // An implicit config follows `defaultLanguage`; changing it before languages are configured leaves every
+    // dictionary without its default key. Returning null there would blank the public site (brief §2).
+    const firstStored = Object.values(value).find((translation) => !isBlankLocaleValue(translation));
+    return firstStored ?? null;
+}
+/**
+ * Returns a copy of `data` with every localized branch resolved to `locale` (default: the default locale)
+ * via {@link resolveLocalizedValue}. Returns `data` itself when `config` is undefined.
+ */
+export function resolveLocalizedFields(seed, data, config, locale) {
+    if (!config)
+        return data;
+    const target = locale ?? config.defaultLocale;
+    const resolved = { ...data };
+    for (const branch of seed.branches) {
+        if (isLocalizedBranch(branch) && Object.hasOwn(resolved, branch.alias)) {
+            resolved[branch.alias] = resolveLocalizedValue(branch, resolved[branch.alias], target, config);
+        }
+    }
+    return resolved;
+}
+/**
+ * The whole dictionary of a stored localized value, for readers asking every language (`?lang=all`):
+ * a stored dictionary as-is — unregistered locales included, nothing is hidden (brief §2) — a legacy
+ * value as `{ [defaultLocale]: value }` (the write path's reading of it), a blank value as `null`.
+ * Non-localized branches return `value` unchanged.
+ */
+export function asLocaleDictionary(branch, value, config) {
+    if (!isLocalizedBranch(branch))
+        return value;
+    if (isStoredLocaleDictionary(branch, value, config))
+        return value;
+    return isBlankLocaleValue(value) ? null : { [config.defaultLocale]: value };
+}
+/** Returns a copy of `data` with every localized branch it carries passed through {@link asLocaleDictionary}. */
+export function asLocaleDictionaries(seed, data, config) {
+    const expanded = { ...data };
+    for (const branch of seed.branches) {
+        if (isLocalizedBranch(branch) && Object.hasOwn(expanded, branch.alias)) {
+            expanded[branch.alias] = asLocaleDictionary(branch, expanded[branch.alias], config);
+        }
+    }
+    return expanded;
+}

package/dist/engine/privacy.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"privacy.service.d.ts","sourceRoot":"","sources":["../../src/engine/privacy.service.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IAE3C;;;;;OAKG;IACH,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IAE5C;;;;;OAKG;IACH,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;CACzC;AA4BD;;;GAGG;AACH,qBAAa,cAAe,YAAW,eAAe;IACpD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAQ;IAClC,OAAO,CAAC,aAAa,CAAC,CAAoB;IAC1C,OAAO,CAAC,cAAc,CAAC,CAAoB;IAE3C;;;;OAIG;gBACS,SAAS,EAAE,MAAM;IAO7B;;;OAGG;YACW,SAAS;IAmBvB;;OAEG;YACW,UAAU;IAexB;;;OAGG;IACG,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAcjD;;;OAGG;IACG,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAoBlD;;OAEG;IACG,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAa/C"}
+{"version":3,"file":"privacy.service.d.ts","sourceRoot":"","sources":["../../src/engine/privacy.service.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IAE3C;;;;;OAKG;IACH,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IAE5C;;;;;OAKG;IACH,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;CACzC;AA4BD;;;GAGG;AACH,qBAAa,cAAe,YAAW,eAAe;IACpD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAQ;IAClC,OAAO,CAAC,aAAa,CAAC,CAAoB;IAC1C,OAAO,CAAC,cAAc,CAAC,CAAoB;IAE3C;;;;OAIG;IACH,YAAY,SAAS,EAAE,MAAM,EAK5B;IAED;;;OAGG;YACW,SAAS;IAmBvB;;OAEG;YACW,UAAU;IAexB;;;OAGG;IACG,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAYhD;IAED;;;OAGG;IACG,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAkBjD;IAED;;OAEG;IACG,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAY7C;CACF"}

package/dist/engine/query/active-clause.d.ts

@@ -1,7 +1,6 @@
 import type { Seed, TrashedMode } from '../types.js';
 /**
- * Returns the SQL condition (e.g. `ce.deleted_at IS NULL`), or `null` if the
- * seed does not use soft delete or mode is 'any'.
+ * Returns the SQL condition (e.g. `ce.deleted_at IS NULL`), or `null` if mode is 'any'.
  *
  * @param seed - The seed schema definition.
  * @param mode - 'active' (default), 'trashed', or 'any'.
@@ -9,7 +8,7 @@ import type { Seed, TrashedMode } from '../types.js';
  */
 export declare function activeCondition(seed: Seed, mode?: TrashedMode, tableAlias?: string): string | null;
 /**
- * Returns ` AND <activeCondition>` for a soft-delete seed, or `''` otherwise.
+ * Returns ` AND <activeCondition>`, or `''` when mode is 'any'.
  *
  * @param seed - The seed schema definition.
  * @param mode - 'active' (default), 'trashed', or 'any'.

package/dist/engine/query/active-clause.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"active-clause.d.ts","sourceRoot":"","sources":["../../../src/engine/query/active-clause.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAEpD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,IAAI,EACV,IAAI,GAAE,WAAsB,EAC5B,UAAU,CAAC,EAAE,MAAM,GAClB,MAAM,GAAG,IAAI,CAIf;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,IAAI,EACV,IAAI,GAAE,WAAsB,EAC5B,UAAU,CAAC,EAAE,MAAM,GAClB,MAAM,CAGR"}
+{"version":3,"file":"active-clause.d.ts","sourceRoot":"","sources":["../../../src/engine/query/active-clause.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAEpD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,IAAI,EACV,IAAI,GAAE,WAAsB,EAC5B,UAAU,CAAC,EAAE,MAAM,GAClB,MAAM,GAAG,IAAI,CAIf;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,IAAI,EACV,IAAI,GAAE,WAAsB,EAC5B,UAAU,CAAC,EAAE,MAAM,GAClB,MAAM,CAGR"}

package/dist/engine/query/active-clause.js

@@ -1,21 +1,20 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) 2024–2026 Flavio De Musso
 /**
- * Returns the SQL condition (e.g. `ce.deleted_at IS NULL`), or `null` if the
- * seed does not use soft delete or mode is 'any'.
+ * Returns the SQL condition (e.g. `ce.deleted_at IS NULL`), or `null` if mode is 'any'.
  *
  * @param seed - The seed schema definition.
  * @param mode - 'active' (default), 'trashed', or 'any'.
  * @param tableAlias - Optional table or alias qualifier prefix.
  */
 export function activeCondition(seed, mode = 'active', tableAlias) {
-    if (!seed.softDelete || mode === 'any')
+    if (mode === 'any')
         return null;
     const col = tableAlias ? `${tableAlias}.deleted_at` : 'deleted_at';
     return mode === 'trashed' ? `${col} IS NOT NULL` : `${col} IS NULL`;
 }
 /**
- * Returns ` AND <activeCondition>` for a soft-delete seed, or `''` otherwise.
+ * Returns ` AND <activeCondition>`, or `''` when mode is 'any'.
  *
  * @param seed - The seed schema definition.
  * @param mode - 'active' (default), 'trashed', or 'any'.

package/dist/engine/query/query.js

@@ -112,7 +112,7 @@ export function buildSelectQuery(seed, options = {}) {
         joinClause = `LEFT JOIN kanban_positions kp` +
             ` ON kp.seed_slug = ? AND kp.entry_id = ${table}.id AND kp.axis_branch_id = ?`;
         bindings.push(options.kanbanOrder.seedSlug, options.kanbanOrder.axisBranchId);
-        kanbanOrderClause = ` ORDER BY (kp.position IS NULL) ASC, kp.position ASC`;
+        kanbanOrderClause = ` ORDER BY (kp.position IS NULL) ASC, kp.position ASC, ${table}.id ASC`;
     }
     const rtBranches = indexableSearchBranches(seed);
     if (search && rtBranches.length > 0) {
@@ -128,12 +128,10 @@ export function buildSelectQuery(seed, options = {}) {
     // Soft delete: 'active' is the default, so a caller that forgets the option can never
     // observe a trashed row — including the Public API, relation expansion and subqueries,
     // which all reach SQL only through repository.findMany.
-    if (seed.softDelete) {
-        const trashed = options.trashed ?? 'active';
-        const cond = activeCondition(seed, trashed, table);
-        if (cond) {
-            whereClauses.push(cond);
-        }
+    const trashed = options.trashed ?? 'active';
+    const cond = activeCondition(seed, trashed, table);
+    if (cond) {
+        whereClauses.push(cond);
     }
     const groupClauses = [];
     for (const group of filters) {
@@ -202,9 +200,11 @@ export function buildSelectQuery(seed, options = {}) {
             sql += orderedBranch && isSingleChoiceTags(orderedBranch)
                 ? tagsOrderClause(col, orderedBranch, dir, bindings)
                 : ` ORDER BY ${col} ${dir}`;
+            // Unique final key: tied sort values would otherwise page in an undefined order.
+            sql += `, ${table}.id ${dir}`;
         }
         else {
-            sql += ` ORDER BY ${table}.created_at DESC`;
+            sql += ` ORDER BY ${table}.created_at DESC, ${table}.id DESC`;
         }
         if (pagination) {
             sql += ` LIMIT ? OFFSET ?`;

package/dist/engine/query/search-support.d.ts

@@ -0,0 +1,32 @@
+import type { Branch, Seed } from '../types.js';
+/** Resolves a seed slug to its definition; `undefined` when unknown. */
+export type SeedLookup = (slug: string) => Seed | null | undefined;
+/**
+ * How a list search is answered for a seed:
+ * - `fts`: the seed has indexable text/richtext branches, matched through its FTS table.
+ * - `relation`: the seed shows a single relation as its display name, matched against the
+ *   target's display name (plain text only).
+ * - `none`: nothing searchable; the search term is ignored.
+ */
+export type SearchSupport = {
+    mode: 'fts';
+} | {
+    mode: 'relation';
+    branch: Branch;
+    target: Seed;
+    targetBranch: Branch;
+} | {
+    mode: 'none';
+};
+/**
+ * Decides how `seed` can be searched. FTS wins when available; otherwise a single relation
+ * display name is searched through the target's display name, provided that column is plain,
+ * unlocalized, unencrypted text.
+ *
+ * @param seed The seed being listed.
+ * @param lookup Resolves relation targets; without it the relation mode is never chosen.
+ */
+export declare function resolveSearchSupport(seed: Seed, lookup?: SeedLookup): SearchSupport;
+/** True when a list search on `seed` can return filtered results. */
+export declare function isSearchSupported(seed: Seed, lookup?: SeedLookup): boolean;
+//# sourceMappingURL=search-support.d.ts.map

package/dist/engine/query/search-support.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"search-support.d.ts","sourceRoot":"","sources":["../../../src/engine/query/search-support.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,aAAa,CAAA;AAK/C,wEAAwE;AACxE,MAAM,MAAM,UAAU,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI,GAAG,SAAS,CAAA;AAElE;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GACrB;IAAE,IAAI,EAAE,KAAK,CAAA;CAAE,GACf;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,IAAI,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,GACxE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAA;AAEpB;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,EAAE,UAAU,GAAG,aAAa,CAoBnF;AAED,qEAAqE;AACrE,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,EAAE,UAAU,GAAG,OAAO,CAE1E"}

package/dist/engine/query/search-support.js

@@ -0,0 +1,34 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+import { indexableSearchBranches } from '../ddl/ddl.js';
+import { resolveClassification } from '../privacy/policies.js';
+import { isLocalizedBranch } from '../localization/localization.js';
+/**
+ * Decides how `seed` can be searched. FTS wins when available; otherwise a single relation
+ * display name is searched through the target's display name, provided that column is plain,
+ * unlocalized, unencrypted text.
+ *
+ * @param seed The seed being listed.
+ * @param lookup Resolves relation targets; without it the relation mode is never chosen.
+ */
+export function resolveSearchSupport(seed, lookup) {
+    if (indexableSearchBranches(seed).length > 0)
+        return { mode: 'fts' };
+    const branch = seed.branches.find((b) => b.alias === seed.displayNameAlias);
+    if (!lookup || branch?.type !== 'relation' || branch.multiple === true || !branch.targetSeed) {
+        return { mode: 'none' };
+    }
+    const target = lookup(branch.targetSeed);
+    const targetBranch = target?.branches.find((b) => b.alias === target.displayNameAlias);
+    if (!target
+        || targetBranch?.type !== 'text'
+        || isLocalizedBranch(targetBranch)
+        || resolveClassification(targetBranch).storage === 'encrypt') {
+        return { mode: 'none' };
+    }
+    return { mode: 'relation', branch, target, targetBranch };
+}
+/** True when a list search on `seed` can return filtered results. */
+export function isSearchSupported(seed, lookup) {
+    return resolveSearchSupport(seed, lookup).mode !== 'none';
+}

package/dist/engine/query.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../src/engine/query.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,IAAI,EAMJ,aAAa,EACb,kBAAkB,EACnB,MAAM,YAAY,CAAC;AAKpB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,GAAE,aAAkB,GAAG,kBAAkB,CAgH5F"}
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../src/engine/query.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,IAAI,EAMJ,aAAa,EACb,kBAAkB,EACnB,MAAM,YAAY,CAAC;AAKpB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,GAAE,aAAkB,GAAG,kBAAkB,CAoG5F"}