@beechcms/core 0.8.0 → 0.8.1

package/dist/engine/introspection/schema-fingerprint.js

@@ -0,0 +1,97 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+/**
+ * @module engine/schema-fingerprint
+ * A deterministic name for "the shape this API answers in".
+ *
+ * Computed from live seed definitions (`introspectSeedDefinitions`), embedded in generated client
+ * types at build time (sprint 3), returned on every public response as `X-Schema-Revision`
+ * (sprint 4), and compared by the client at request time (sprint 5). Both ends MUST compute it
+ * with this function — two implementations would be free to disagree, and a drift detector whose
+ * ends disagree is worse than none.
+ *
+ * What is hashed is a CONTRACT PROJECTION, not the whole seed definition: labels, hints, dashboard
+ * icons and layout cannot change a single response byte, and hashing them would fire a hard
+ * `BeechProblem` in someone else's production client over a typo fix.
+ */
+import { canonicalStringify } from '../../common/canonical-json.js';
+import { resolvePolicies } from '../privacy/policies.js';
+/**
+ * Bumped ONLY when the projection below or the canonical byte format changes — i.e. when
+ * fingerprints computed by two builds are no longer comparable. It is carried in the fingerprint
+ * string itself so a version skew reads as a mismatch instead of as an accidental match.
+ */
+export const SCHEMA_FINGERPRINT_VERSION = 1;
+function projectBranch(branch) {
+    const policies = resolvePolicies(branch);
+    return {
+        alias: branch.alias,
+        type: branch.type,
+        ...(branch.format !== undefined ? { format: branch.format } : {}),
+        ...(branch.multiple !== undefined ? { multiple: branch.multiple } : {}),
+        // Option order is the contract: it is the order a select renders and a union type lists.
+        ...(branch.options !== undefined ? { options: [...branch.options] } : {}),
+        requiredOnCreate: branch.requiredOnCreate ?? false,
+        requiredOnUpdate: branch.requiredOnUpdate ?? false,
+        ...(branch.targetSeed !== undefined ? { targetSeed: branch.targetSeed } : {}),
+        visibility: policies.visibility,
+        publicRead: policies.public,
+        publicEdit: policies.publicEdit,
+        ...(branch.minItems !== undefined ? { minItems: branch.minItems } : {}),
+        ...(branch.maxItems !== undefined ? { maxItems: branch.maxItems } : {}),
+        // Spread only when true so every schema without localized branches keeps its fingerprint.
+        ...(branch.localized === true ? { localized: true } : {}),
+        ...(branch.fields ? { fields: branch.fields.map(projectBranch) } : {}),
+    };
+}
+/**
+ * Reduces seeds to what a response shape depends on.
+ *
+ * Deliberately EXCLUDED, and each for a reason a future reader must not "fix":
+ * - `id` (`br_XX`) — a stable internal handle; it never appears in a payload, and minting order
+ *   differs between an environment built by migration and one grown through the dashboard.
+ * - `label`, `labelPlural`, `hint`, `dashboard`, `layout` — presentation, never response shape.
+ * - `retentionDays`, `onDelete`, `policies.search|filter|sort`, `numberOptions`, `fileOptions`,
+ *   `policies.classification|privacy` — behaviour and storage concerns that leave the response
+ *   shape identical. (`privacy` DOES change a stored value's encoding, but the API type stays
+ *   `string`; drift there is a data concern, not a type concern.)
+ * - anything physical (column order, index names) — see the VETO Audit.
+ *
+ * Seeds are sorted by slug; BRANCH ORDER IS PRESERVED, because it is the declared field order the
+ * generated types and the dashboard form both follow.
+ */
+export function projectSchemaContract(seeds) {
+    return {
+        fingerprintVersion: SCHEMA_FINGERPRINT_VERSION,
+        seeds: [...seeds]
+            .sort((a, b) => a.slug.localeCompare(b.slug))
+            .map(seed => ({
+            slug: seed.slug,
+            displayNameAlias: seed.displayNameAlias,
+            allowDrafts: seed.allowDrafts ?? false,
+            allowPublicRead: seed.allowPublicRead ?? false,
+            allowPublicPost: seed.allowPublicPost ?? false,
+            allowPublicEdit: seed.allowPublicEdit ?? false,
+            branches: seed.branches.map(projectBranch),
+        })),
+    };
+}
+function toHex(buffer) {
+    return Array.from(new Uint8Array(buffer), byte => byte.toString(16).padStart(2, '0')).join('');
+}
+/**
+ * `v{VERSION}:{32 lowercase hex}` — SHA-256 over the canonical JSON of the contract projection,
+ * truncated to 128 bits.
+ *
+ * Truncation is deliberate: this value travels on EVERY public response as `X-Schema-Revision`,
+ * and 128 bits of a SHA-256 digest carries no realistic collision risk for a value space of a few
+ * hundred schema revisions. It is a revision marker, never a security token.
+ *
+ * Web Crypto only — the same API the Worker and Node ≥ 18 both expose, as `webhook-crypto.ts`
+ * already relies on. `@beechcms/core` gains no dependency.
+ */
+export async function computeSchemaFingerprint(seeds) {
+    const bytes = new TextEncoder().encode(canonicalStringify(projectSchemaContract(seeds)));
+    const digest = await crypto.subtle.digest('SHA-256', bytes);
+    return `v${SCHEMA_FINGERPRINT_VERSION}:${toHex(digest).slice(0, 32)}`;
+}

package/dist/engine/introspection.d.ts

@@ -0,0 +1,101 @@
+/**
+ * @module engine/introspection
+ * Reads live schema state out of D1 through an INJECTED executor.
+ *
+ * Executor-agnostic on purpose: the CLI reaches D1 through a synchronous shell/SQLite path
+ * (`queryD1`) and the Worker through its `D1Database` binding, and neither tier may import the
+ * other (`graphify path "createBeechApp" "queryD1"` must keep returning no path). `@beechcms/core`
+ * owns the STATEMENTS and the SHAPES; the caller owns the connection.
+ *
+ * Read-only by contract: every statement here is a `PRAGMA` or a `SELECT`. Schema mutation stays
+ * the exclusive business of the Botanical Engine's DDL path (`engine/seed-ddl.ts`).
+ */
+import type { Seed } from './types.js';
+/**
+ * The one capability the introspection primitive needs from a database connection.
+ *
+ * Implementations MUST: execute the statement as-is, return one object per row with column names
+ * as keys, and reject/throw on failure. They MUST NOT cache, batch, rewrite or retry — a stale
+ * answer here becomes a wrong fingerprint, which becomes a false "your types are stale" error in
+ * someone else's production client.
+ */
+export interface SchemaQueryExecutor {
+    all<T extends Record<string, unknown>>(sql: string): Promise<T[]>;
+}
+/** Thrown when live state cannot be read or cannot be trusted. */
+export declare class IntrospectionError extends Error {
+    readonly cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+/** One physical column, as SQLite reports it. */
+export interface LiveColumn {
+    name: string;
+    /** Declared storage type, upper-cased (`TEXT` | `INTEGER` | `REAL` | …). */
+    sqlType: string;
+    notNull: boolean;
+    isPk: boolean;
+    /** Declared DEFAULT expression verbatim, or null. */
+    defaultValue: string | null;
+}
+/** One foreign-key constraint on a physical table. */
+export interface LiveForeignKey {
+    /** Local column carrying the reference. */
+    column: string;
+    /** Referenced table, e.g. `content_team`. */
+    targetTable: string;
+    /** Referenced column, e.g. `id`. */
+    targetColumn: string;
+    /** Upper-cased, e.g. `SET NULL`. */
+    onDelete: string;
+    /** Upper-cased, e.g. `NO ACTION`. */
+    onUpdate: string;
+}
+/** One index on a physical table. SQLite's implicit `sqlite_autoindex_*` entries are excluded. */
+export interface LiveIndex {
+    name: string;
+    unique: boolean;
+}
+/** The physical state of one table. `exists: false` means SQLite reports no such table. */
+export interface LiveTable {
+    name: string;
+    exists: boolean;
+    /** Physical order, as returned by `PRAGMA table_info` (cid order). */
+    columns: LiveColumn[];
+    /** Sorted by `column`, then `targetTable`, for deterministic output. */
+    foreignKeys: LiveForeignKey[];
+    /** Sorted by `name`. */
+    indexes: LiveIndex[];
+}
+/** The physical state of a set of tables. `tables` is sorted by name. */
+export interface LiveSchema {
+    tables: LiveTable[];
+}
+/** Returns `name` unchanged when it is a safe SQL identifier; throws otherwise. */
+export declare function assertSafeIdentifier(name: string): string;
+/**
+ * Physical state of one table. A table SQLite does not know returns `{ exists: false }` with empty
+ * lists rather than throwing: "missing" is a legitimate diff outcome, not an error.
+ *
+ * `PRAGMA table_info` answers an unknown table with zero rows on the SQLite path and raises on some
+ * wrangler paths, so both outcomes collapse to the same result.
+ */
+export declare function introspectTable(executor: SchemaQueryExecutor, table: string): Promise<LiveTable>;
+/**
+ * Names of the physical tables SQLite holds, optionally restricted to a `LIKE` prefix
+ * (e.g. `content_`). Sorted, `sqlite_*` internals excluded.
+ */
+export declare function listTables(executor: SchemaQueryExecutor, prefix?: string): Promise<string[]>;
+/**
+ * Physical state of several tables at once. With no explicit list, every `content_*` table is
+ * introspected — the set a schema export or a drift check cares about.
+ */
+export declare function introspectSchema(executor: SchemaQueryExecutor, tables?: string[]): Promise<LiveSchema>;
+/**
+ * The DECLARED schema: every active seed definition, read live from D1.
+ *
+ * This — not `beech.schema.ts` — is the source of truth for generated types and for the schema
+ * fingerprint (feature brief, business rule 1). The manifest file is a desired-state artifact and
+ * may legitimately be ahead of, or behind, what is deployed.
+ */
+export declare function introspectSeedDefinitions(executor: SchemaQueryExecutor): Promise<Seed[]>;
+//# sourceMappingURL=introspection.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"introspection.d.ts","sourceRoot":"","sources":["../../src/engine/introspection.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AAEtC;;;;;;;GAOG;AACH,MAAM,WAAW,mBAAmB;IAClC,GAAG,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAAA;CAClE;AAED,kEAAkE;AAClE,qBAAa,kBAAmB,SAAQ,KAAK;IACd,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO;gBAAzC,OAAO,EAAE,MAAM,EAAW,KAAK,CAAC,EAAE,OAAO,YAAA;CAItD;AAED,iDAAiD;AACjD,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,4EAA4E;IAC5E,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,OAAO,CAAA;IAChB,IAAI,EAAE,OAAO,CAAA;IACb,qDAAqD;IACrD,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;CAC5B;AAED,sDAAsD;AACtD,MAAM,WAAW,cAAc;IAC7B,2CAA2C;IAC3C,MAAM,EAAE,MAAM,CAAA;IACd,6CAA6C;IAC7C,WAAW,EAAE,MAAM,CAAA;IACnB,oCAAoC;IACpC,YAAY,EAAE,MAAM,CAAA;IACpB,oCAAoC;IACpC,QAAQ,EAAE,MAAM,CAAA;IAChB,qCAAqC;IACrC,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED,kGAAkG;AAClG,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,OAAO,CAAA;CAChB;AAED,2FAA2F;AAC3F,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,OAAO,CAAA;IACf,sEAAsE;IACtE,OAAO,EAAE,UAAU,EAAE,CAAA;IACrB,wEAAwE;IACxE,WAAW,EAAE,cAAc,EAAE,CAAA;IAC7B,wBAAwB;IACxB,OAAO,EAAE,SAAS,EAAE,CAAA;CACrB;AAED,yEAAyE;AACzE,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,SAAS,EAAE,CAAA;CACpB;AA6CD,mFAAmF;AACnF,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAOzD;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CACnC,QAAQ,EAAE,mBAAmB,EAC7B,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,SAAS,CAAC,CAgDpB;AAED;;;GAGG;AACH,wBAAsB,UAAU,CAC9B,QAAQ,EAAE,mBAAmB,EAC7B,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,MAAM,EAAE,CAAC,CAOnB;AAED;;;GAGG;AACH,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,mBAAmB,EAC7B,MAAM,CAAC,EAAE,MAAM,EAAE,GAChB,OAAO,CAAC,UAAU,CAAC,CAUrB;AAED;;;;;;GAMG;AACH,wBAAsB,yBAAyB,CAC7C,QAAQ,EAAE,mBAAmB,GAC5B,OAAO,CAAC,IAAI,EAAE,CAAC,CAoBjB"}

package/dist/engine/introspection.js

@@ -0,0 +1,127 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+/** Thrown when live state cannot be read or cannot be trusted. */
+export class IntrospectionError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = 'IntrospectionError';
+    }
+}
+/**
+ * SQLite identifiers cannot be bound as parameters, so every table name reaching a PRAGMA is
+ * interpolated — and therefore must be proven safe first. Table names in this system are always
+ * `content_{slug}` / `rel_{slug}_{alias}` / a structural table, all of which match this pattern.
+ */
+const SAFE_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** Returns `name` unchanged when it is a safe SQL identifier; throws otherwise. */
+export function assertSafeIdentifier(name) {
+    if (!SAFE_IDENTIFIER.test(name)) {
+        throw new IntrospectionError(`Refusing to introspect '${name}': not a plain SQL identifier. Table names are never user input in BeechCMS.`);
+    }
+    return name;
+}
+/**
+ * Physical state of one table. A table SQLite does not know returns `{ exists: false }` with empty
+ * lists rather than throwing: "missing" is a legitimate diff outcome, not an error.
+ *
+ * `PRAGMA table_info` answers an unknown table with zero rows on the SQLite path and raises on some
+ * wrangler paths, so both outcomes collapse to the same result.
+ */
+export async function introspectTable(executor, table) {
+    const name = assertSafeIdentifier(table);
+    const empty = { name, exists: false, columns: [], foreignKeys: [], indexes: [] };
+    let info;
+    try {
+        info = await executor.all(`PRAGMA table_info(${name})`);
+    }
+    catch {
+        return empty;
+    }
+    if (info.length === 0)
+        return empty;
+    const columns = info.map(row => ({
+        name: row.name,
+        sqlType: String(row.type ?? '').toUpperCase(),
+        notNull: row.notnull === 1,
+        isPk: row.pk > 0,
+        defaultValue: row.dflt_value ?? null,
+    }));
+    let fkRows = [];
+    let indexRows = [];
+    try {
+        fkRows = await executor.all(`PRAGMA foreign_key_list(${name})`);
+        indexRows = await executor.all(`PRAGMA index_list(${name})`);
+    }
+    catch {
+        // A table with neither FKs nor indexes answers with zero rows on some drivers and raises on
+        // others; an unreadable constraint list must not hide the column list we already have.
+    }
+    const foreignKeys = fkRows
+        .map(row => ({
+        column: row.from,
+        targetTable: row.table,
+        targetColumn: row.to ?? 'id',
+        onDelete: String(row.on_delete ?? '').toUpperCase(),
+        onUpdate: String(row.on_update ?? '').toUpperCase(),
+    }))
+        .sort((a, b) => a.column.localeCompare(b.column) || a.targetTable.localeCompare(b.targetTable));
+    const indexes = indexRows
+        // Implicit indexes SQLite mints for UNIQUE/PK are not schema an author declared, and their
+        // names are not stable across environments.
+        .filter(row => !row.name.startsWith('sqlite_autoindex_'))
+        .map(row => ({ name: row.name, unique: row.unique === 1 }))
+        .sort((a, b) => a.name.localeCompare(b.name));
+    return { name, exists: true, columns, foreignKeys, indexes };
+}
+/**
+ * Names of the physical tables SQLite holds, optionally restricted to a `LIKE` prefix
+ * (e.g. `content_`). Sorted, `sqlite_*` internals excluded.
+ */
+export async function listTables(executor, prefix) {
+    if (prefix !== undefined)
+        assertSafeIdentifier(`${prefix}x`);
+    const filter = prefix ? ` AND name LIKE '${prefix}%'` : '';
+    const rows = await executor.all(`SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%'${filter} ORDER BY name ASC`);
+    return rows.map(row => row.name);
+}
+/**
+ * Physical state of several tables at once. With no explicit list, every `content_*` table is
+ * introspected — the set a schema export or a drift check cares about.
+ */
+export async function introspectSchema(executor, tables) {
+    const names = tables ?? await listTables(executor, 'content_');
+    const sorted = [...names].sort((a, b) => a.localeCompare(b));
+    const result = [];
+    // Sequential on purpose: the CLI executor is a synchronous shell/SQLite call behind a Promise,
+    // and D1 rejects unbounded concurrent statements from one request.
+    for (const name of sorted) {
+        result.push(await introspectTable(executor, name));
+    }
+    return { tables: result };
+}
+/**
+ * The DECLARED schema: every active seed definition, read live from D1.
+ *
+ * This — not `beech.schema.ts` — is the source of truth for generated types and for the schema
+ * fingerprint (feature brief, business rule 1). The manifest file is a desired-state artifact and
+ * may legitimately be ahead of, or behind, what is deployed.
+ */
+export async function introspectSeedDefinitions(executor) {
+    let rows;
+    try {
+        rows = await executor.all(`SELECT slug, definition FROM seeds WHERE status = 'active' ORDER BY slug ASC`);
+    }
+    catch (error) {
+        throw new IntrospectionError('Failed to read the `seeds` table from D1.', error);
+    }
+    return rows.map(row => {
+        try {
+            return JSON.parse(row.definition);
+        }
+        catch (error) {
+            throw new IntrospectionError(`Seed '${row.slug}' holds a definition that is not valid JSON; D1 state is corrupt.`, error);
+        }
+    });
+}

package/dist/engine/localization/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/localization.d.ts.map

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