@beechcms/core 0.8.0 → 0.9.0

package/dist/engine/query/relations.js

@@ -0,0 +1,25 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+/**
+ * Builds the back-reference map from an array of seeds.
+ * Pure function — no side-effects, safe to call at startup and cache forever.
+ */
+export function buildBackrefMap(seeds) {
+    const map = new Map();
+    for (const seed of seeds) {
+        for (const branch of seed.branches) {
+            if (branch.type !== 'relation' || !branch.targetSeed)
+                continue;
+            const existing = map.get(branch.targetSeed) ?? [];
+            existing.push({
+                sourceSlug: seed.slug,
+                branchAlias: branch.alias,
+                branchLabel: branch.label,
+                relationship: branch.multiple === true ? 'multi' : 'single',
+                restricts: branch.onDelete === 'RESTRICT',
+            });
+            map.set(branch.targetSeed, existing);
+        }
+    }
+    return map;
+}

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

@@ -0,0 +1,22 @@
+import type { Branch } from '../types.js';
+/**
+ * Serializes a value for writing to the DB.
+ * boolean → 0/1 | date → Unix timestamp | json/tags/richtext/repeater → JSON string
+ * Localized branches: locale dictionary ↔ compact JSON.
+ *
+ * @param branch The branch definition.
+ * @param value The value to serialize.
+ * @returns The serialized DB value (string, number, or null).
+ */
+export declare function serializeForDb(branch: Branch, value: unknown): string | number | null;
+/**
+ * Deserializes a value read from the DB to its API/JS representation.
+ * 0/1 → boolean | Unix timestamp → ISO 8601 | JSON string → object/array
+ * Localized branches: locale dictionary ↔ compact JSON.
+ *
+ * @param branch The branch definition.
+ * @param value The raw database value.
+ * @returns The deserialized value.
+ */
+export declare function deserializeFromDb(branch: Branch, value: unknown): unknown;
+//# sourceMappingURL=serialize.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"serialize.d.ts","sourceRoot":"","sources":["../../../src/engine/query/serialize.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAEV,MAAM,EAOP,MAAM,aAAa,CAAC;AAoErB;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,CA6CrF;AAGD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CA0CzE"}

package/dist/engine/query/serialize.js

@@ -0,0 +1,175 @@
+import { compactLocalizedDictionary, isLocaleDictionary, isLocalizedBranch } from '../localization/localization.js';
+/**
+ * Checks if a branch represents a multiple asset list field.
+ *
+ * @param branch The branch definition.
+ * @returns True if it's an asset list, false otherwise.
+ */
+function isAssetListBranch(branch) {
+    return branch.type === 'file' && (branch.multiple === true || branch.format === 'asset-list');
+}
+/**
+ * Normalizes an unknown value to a valid HTTP URL string, or null.
+ *
+ * @param value The value to normalize.
+ * @returns The normalized URL string, or null if invalid.
+ */
+function normalizeHttpUrl(value) {
+    if (typeof value !== 'string')
+        return null;
+    const cleaned = value.trim();
+    if (!cleaned)
+        return null;
+    try {
+        const parsed = new URL(cleaned);
+        return parsed.protocol.startsWith('http') ? cleaned : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Safely parses a JSON string, falling back to the raw string on error.
+ *
+ * @param value The string to parse.
+ * @returns The parsed object, or the original string.
+ */
+function parseJsonSafe(value) {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return value;
+    }
+}
+/**
+ * Normalizes raw asset list values to a flat list of valid URL strings.
+ *
+ * @param rawValue The raw value (string, array, or object) to normalize.
+ * @returns An array of unique normalized URL strings.
+ */
+function normalizeAssetListValue(rawValue) {
+    const input = typeof rawValue === 'string' ? parseJsonSafe(rawValue) : rawValue;
+    const values = Array.isArray(input) ? input : [input];
+    const normalized = [];
+    for (const item of values) {
+        if (item == null)
+            continue;
+        const direct = normalizeHttpUrl(item);
+        if (direct) {
+            normalized.push(direct);
+            continue;
+        }
+        if (typeof item === 'object' && !Array.isArray(item)) {
+            const fromObj = normalizeHttpUrl(item.url);
+            if (fromObj)
+                normalized.push(fromObj);
+        }
+    }
+    return [...new Set(normalized)];
+}
+/**
+ * Serializes a value for writing to the DB.
+ * boolean → 0/1 | date → Unix timestamp | json/tags/richtext/repeater → JSON string
+ * Localized branches: locale dictionary ↔ compact JSON.
+ *
+ * @param branch The branch definition.
+ * @param value The value to serialize.
+ * @returns The serialized DB value (string, number, or null).
+ */
+export function serializeForDb(branch, value) {
+    if (value === null || value === undefined)
+        return null;
+    // Must precede the type switch: its `text` case returns null for any object, which would silently
+    // erase a dictionary on a localized text branch.
+    if (isLocalizedBranch(branch) && isLocaleDictionary(value)) {
+        const compact = compactLocalizedDictionary(value);
+        return compact === null ? null : JSON.stringify(compact);
+    }
+    switch (branch.type) {
+        case 'boolean':
+            return value ? 1 : 0;
+        case 'json':
+        case 'tags':
+        case 'richtext':
+            return typeof value === 'string' ? value : JSON.stringify(value);
+        case 'date': {
+            if (typeof value === 'number')
+                return value;
+            if (typeof value === 'string') {
+                const d = new Date(value);
+                if (Number.isNaN(d.getTime()))
+                    return null;
+                if (branch.format === 'date') {
+                    const midnight = Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate());
+                    return Math.floor(midnight / 1000);
+                }
+                return Math.floor(d.getTime() / 1000);
+            }
+            return null;
+        }
+        case 'file':
+            if (isAssetListBranch(branch)) {
+                return Array.isArray(value) ? JSON.stringify(value) : typeof value === 'string' ? value : null;
+            }
+            return typeof value === 'string' ? value : null;
+        case 'repeater':
+            return JSON.stringify(Array.isArray(value) ? value : []);
+        default:
+            return typeof value === 'string' ? value : typeof value === 'number' ? value : null;
+    }
+}
+/**
+ * Deserializes a value read from the DB to its API/JS representation.
+ * 0/1 → boolean | Unix timestamp → ISO 8601 | JSON string → object/array
+ * Localized branches: locale dictionary ↔ compact JSON.
+ *
+ * @param branch The branch definition.
+ * @param value The raw database value.
+ * @returns The deserialized value.
+ */
+export function deserializeFromDb(branch, value) {
+    if (branch.type === 'repeater') {
+        if (typeof value !== 'string' || value.length === 0)
+            return [];
+        const parsed = parseJsonSafe(value);
+        return Array.isArray(parsed) ? parsed : [];
+    }
+    if (value === null || value === undefined)
+        return null;
+    // richtext/json already JSON.parse below; text must opt in. A legacy plain string written before the
+    // branch became localized is returned unchanged — the read-side fallback chain handles it.
+    if (branch.type === 'text' && isLocalizedBranch(branch) && typeof value === 'string' && value.startsWith('{')) {
+        const parsed = parseJsonSafe(value);
+        return isLocaleDictionary(parsed) ? parsed : value;
+    }
+    switch (branch.type) {
+        case 'boolean':
+            return value === 1 || value === true;
+        case 'json':
+        case 'tags':
+        case 'richtext': {
+            if (typeof value === 'string') {
+                try {
+                    return JSON.parse(value);
+                }
+                catch {
+                    return value;
+                }
+            }
+            return value;
+        }
+        case 'date': {
+            if (typeof value !== 'number')
+                return null;
+            const d = new Date(value * 1000);
+            return branch.format === 'date' ? d.toISOString().slice(0, 10) : d.toISOString();
+        }
+        case 'file':
+            if (isAssetListBranch(branch))
+                return normalizeAssetListValue(value);
+            return typeof value === 'string' ? value : null;
+        default:
+            return value;
+    }
+}

package/dist/engine/schema-fingerprint.d.ts

@@ -0,0 +1,73 @@
+import type { Branch, Seed } from './types.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 declare const SCHEMA_FINGERPRINT_VERSION = 1;
+/** The response-shape-bearing subset of a `Branch`. */
+export interface ContractBranch {
+    alias: string;
+    type: Branch['type'];
+    format?: Branch['format'];
+    multiple?: boolean;
+    options?: string[];
+    requiredOnCreate: boolean;
+    requiredOnUpdate: boolean;
+    targetSeed?: string;
+    /** From `resolvePolicies`, so an explicitly-written default hashes like an omitted one. */
+    visibility: 'full' | 'masked' | 'hidden';
+    publicRead: boolean;
+    publicEdit: boolean;
+    minItems?: number;
+    maxItems?: number;
+    /** Present only when true: the dictionary shape is part of the public contract (`?lang=all`, writes). */
+    localized?: boolean;
+    /** Repeater sub-fields, same projection, recursively. */
+    fields?: ContractBranch[];
+}
+/** The response-shape-bearing subset of a `Seed`. */
+export interface ContractSeed {
+    slug: string;
+    displayNameAlias: string;
+    allowDrafts: boolean;
+    allowPublicRead: boolean;
+    allowPublicPost: boolean;
+    allowPublicEdit: boolean;
+    branches: ContractBranch[];
+}
+/** The exact value that gets canonicalized and hashed. */
+export interface SchemaContract {
+    fingerprintVersion: number;
+    seeds: ContractSeed[];
+}
+/**
+ * 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 declare function projectSchemaContract(seeds: Seed[]): SchemaContract;
+/**
+ * `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 declare function computeSchemaFingerprint(seeds: Seed[]): Promise<string>;
+//# sourceMappingURL=schema-fingerprint.d.ts.map

package/dist/engine/schema-fingerprint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-fingerprint.d.ts","sourceRoot":"","sources":["../../src/engine/schema-fingerprint.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AAE9C;;;;GAIG;AACH,eAAO,MAAM,0BAA0B,IAAI,CAAA;AAE3C,uDAAuD;AACvD,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,CAAA;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC,CAAA;IACzB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;IAClB,gBAAgB,EAAE,OAAO,CAAA;IACzB,gBAAgB,EAAE,OAAO,CAAA;IACzB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,2FAA2F;IAC3F,UAAU,EAAE,MAAM,GAAG,QAAQ,GAAG,QAAQ,CAAA;IACxC,UAAU,EAAE,OAAO,CAAA;IACnB,UAAU,EAAE,OAAO,CAAA;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,yGAAyG;IACzG,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,yDAAyD;IACzD,MAAM,CAAC,EAAE,cAAc,EAAE,CAAA;CAC1B;AAED,qDAAqD;AACrD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAA;IACZ,gBAAgB,EAAE,MAAM,CAAA;IACxB,WAAW,EAAE,OAAO,CAAA;IACpB,eAAe,EAAE,OAAO,CAAA;IACxB,eAAe,EAAE,OAAO,CAAA;IACxB,eAAe,EAAE,OAAO,CAAA;IACxB,QAAQ,EAAE,cAAc,EAAE,CAAA;CAC3B;AAED,0DAA0D;AAC1D,MAAM,WAAW,cAAc;IAC7B,kBAAkB,EAAE,MAAM,CAAA;IAC1B,KAAK,EAAE,YAAY,EAAE,CAAA;CACtB;AAyBD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,cAAc,CAenE;AAMD;;;;;;;;;;GAUG;AACH,wBAAsB,wBAAwB,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAI7E"}

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

@@ -1 +1 @@
-{"version":3,"file":"seed-registry.d.ts","sourceRoot":"","sources":["../../src/engine/seed-registry.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AAI9C,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,GAAG,IAAI,IAAI,EAAE,CAAA;IAEb;;;;OAIG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAAA;IAE9B;;;;;OAKG;IACH,kBAAkB,IAAI,IAAI,EAAE,CAAA;IAE5B;;;OAGG;IACH,cAAc,IAAI,IAAI,EAAE,CAAA;IAExB;;;OAGG;IACH,YAAY,IAAI,IAAI,EAAE,CAAA;CACvB;AAID,qBAAa,YAAa,YAAW,aAAa;IAChD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmB;IAC3C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAQ;gBAEzB,KAAK,EAAE,IAAI,EAAE;IAkCzB,GAAG,IAAI,IAAI,EAAE;IAIb,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAI9B,kBAAkB,IAAI,IAAI,EAAE;IAI5B,cAAc,IAAI,IAAI,EAAE;IAIxB,YAAY,IAAI,IAAI,EAAE;CAGvB;AAED;;;GAGG;AACH,qBAAa,oBAAqB,SAAQ,YAAY;CAAG;AAEzD,gFAAgF;AAChF,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAEpE;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,UAAU,CAAC,GAAG,MAAM,CAQjE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,aAAa,CAAC,IAAI,CAAC,GAAG,IAAI,EAAE,CA0F1E"}
+{"version":3,"file":"seed-registry.d.ts","sourceRoot":"","sources":["../../src/engine/seed-registry.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AAI9C,MAAM,WAAW,aAAa;IAC5B;;;;OAIG;IACH,GAAG,IAAI,IAAI,EAAE,CAAA;IAEb;;;;OAIG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAAA;IAE9B;;;;;OAKG;IACH,kBAAkB,IAAI,IAAI,EAAE,CAAA;IAE5B;;;OAGG;IACH,cAAc,IAAI,IAAI,EAAE,CAAA;IAExB;;;OAGG;IACH,YAAY,IAAI,IAAI,EAAE,CAAA;CACvB;AAID,qBAAa,YAAa,YAAW,aAAa;IAChD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmB;IAC3C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAQ;IAErC,YAAY,KAAK,EAAE,IAAI,EAAE,EAgCxB;IAED,GAAG,IAAI,IAAI,EAAE,CAEZ;IAED,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAE7B;IAED,kBAAkB,IAAI,IAAI,EAAE,CAE3B;IAED,cAAc,IAAI,IAAI,EAAE,CAEvB;IAED,YAAY,IAAI,IAAI,EAAE,CAErB;CACF;AAED;;;GAGG;AACH,qBAAa,oBAAqB,SAAQ,YAAY;CAAG;AAEzD,gFAAgF;AAChF,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAEpE;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,UAAU,CAAC,GAAG,MAAM,CAQjE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,aAAa,CAAC,IAAI,CAAC,GAAG,IAAI,EAAE,CA0F1E"}

package/dist/engine/seeds/candidate-ids.d.ts

@@ -0,0 +1,14 @@
+import type { Seed } from '../types.js';
+/**
+ * Fills the id of every branch (and repeater sub-field) that lacks one.
+ *
+ * The stored id wins by alias match; only an alias the stored definition does not know gets a fresh
+ * `nextBranchId`, minted past every stored id and every explicit id anywhere in the candidate, so it
+ * never collides with a later explicit id nor recycles the id of a branch the candidate omits. An id
+ * already present on the candidate is kept as-is: callers that author without ids (hand-written
+ * manifests) must send none rather than invented ones.
+ */
+export declare function resolveCandidateIds<T extends {
+    branches?: unknown;
+}>(candidate: T, stored: Seed | null): T;
+//# sourceMappingURL=candidate-ids.d.ts.map

package/dist/engine/seeds/candidate-ids.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"candidate-ids.d.ts","sourceRoot":"","sources":["../../../src/engine/seeds/candidate-ids.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAU,IAAI,EAAE,MAAM,aAAa,CAAA;AAE/C;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,SAAS;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAE,EAAE,SAAS,EAAE,CAAC,EAAE,MAAM,EAAE,IAAI,GAAG,IAAI,GAAG,CAAC,CAM1G"}

package/dist/engine/seeds/candidate-ids.js

@@ -0,0 +1,40 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+/**
+ * @module engine/seeds/candidate-ids
+ * Resolves branch ids on a candidate seed definition against the stored one.
+ */
+import { nextBranchId } from './seed-registry.js';
+/**
+ * Fills the id of every branch (and repeater sub-field) that lacks one.
+ *
+ * The stored id wins by alias match; only an alias the stored definition does not know gets a fresh
+ * `nextBranchId`, minted past every stored id and every explicit id anywhere in the candidate, so it
+ * never collides with a later explicit id nor recycles the id of a branch the candidate omits. An id
+ * already present on the candidate is kept as-is: callers that author without ids (hand-written
+ * manifests) must send none rather than invented ones.
+ */
+export function resolveCandidateIds(candidate, stored) {
+    const storedBranches = stored?.branches ?? [];
+    return {
+        ...candidate,
+        branches: assignIds(Array.isArray(candidate.branches) ? candidate.branches : [], storedBranches),
+    };
+}
+function assignIds(branches, stored) {
+    const storedByAlias = new Map(stored.map(b => [b.alias, b]));
+    const taken = [...stored, ...branches.filter(b => b.id)];
+    const resolved = [];
+    for (const source of branches) {
+        const match = source.alias === undefined ? undefined : storedByAlias.get(source.alias);
+        const branch = { ...source };
+        if (!branch.id) {
+            branch.id = match?.id || nextBranchId({ branches: taken });
+            taken.push(branch);
+        }
+        if (Array.isArray(source.fields))
+            branch.fields = assignIds(source.fields, match?.fields ?? []);
+        resolved.push(branch);
+    }
+    return resolved;
+}

package/dist/engine/seeds/define-seed.d.ts

@@ -0,0 +1,3 @@
+import type { Seed } from '../types.js';
+export declare function defineSeed(seed: Seed): Seed;
+//# sourceMappingURL=define-seed.d.ts.map

package/dist/engine/seeds/define-seed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-seed.d.ts","sourceRoot":"","sources":["../../../src/engine/seeds/define-seed.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAA;AAEvC,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,CAE3C"}

package/dist/engine/seeds/define-seed.js

@@ -0,0 +1,5 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+export function defineSeed(seed) {
+    return seed;
+}

package/dist/engine/seeds/seed-definition-diff.d.ts

@@ -0,0 +1,38 @@
+import type { Branch, Seed } from '../types.js';
+/** A branch as either side of a comparison carries it: stored (`Branch`, with id) or manifest-authored (id optional). */
+export type BranchDefinitionLike = Omit<Branch, 'id' | 'fields'> & {
+    id?: string;
+    fields?: BranchDefinitionLike[];
+};
+/** A seed as either side of a comparison carries it: stored (`Seed`) or manifest-authored (no layout). */
+export type SeedDefinitionLike = Omit<Seed, 'branches' | 'layout'> & {
+    branches: BranchDefinitionLike[];
+    layout?: unknown;
+};
+/** Seed-level flags the engine treats as `false` when omitted. */
+export declare const SEED_DEFINITION_FLAGS: readonly ["allowDrafts", "allowPublicRead", "allowPublicPost", "allowPublicEdit", "softDelete"];
+/** Branch-level flags the engine treats as `false` when omitted. `multiple` is resolved separately (see normalizeBranchDefinition). */
+export declare const BRANCH_DEFINITION_FLAGS: readonly ["requiredOnCreate", "requiredOnUpdate"];
+/**
+ * Comparable form of one branch definition. Two branches are the same definition iff their canonicalStringify bytes match.
+ *
+ * - `id` is dropped, recursively through `fields`.
+ * - `requiredOnCreate` / `requiredOnUpdate` omitted ≡ `false`.
+ * - `multiple` omitted ≡ `true` on `tags` (single source of truth: `isSingleChoiceTags`), ≡ `false` on every other type.
+ * - Every other key, unknown ones included, is copied unchanged: `options` is compared as declared (values, colors, order).
+ */
+export declare function normalizeBranchDefinition(branch: BranchDefinitionLike): Record<string, unknown>;
+/** Comparable form of one seed definition (branches normalized, order kept). `layout` is server-populated and dropped. */
+export declare function normalizeSeedDefinition(seed: SeedDefinitionLike): Record<string, unknown>;
+export interface SeedDefinitionDiff {
+    /** True when the candidate's comparable definition differs from the stored one. Always true when nothing is stored. */
+    changed: boolean;
+    /**
+     * Aliases, in candidate order, of candidate branches that are new (no stored branch with the same id) or whose
+     * comparable definition differs from the stored branch with the same id. `[]` when nothing is stored.
+     */
+    changedBranches: string[];
+}
+/** Compares a stored seed definition with a candidate whose ids were already resolved ({@link resolveCandidateIds}). Pure. */
+export declare function diffSeedDefinition(stored: Seed | null, candidate: Seed): SeedDefinitionDiff;
+//# sourceMappingURL=seed-definition-diff.d.ts.map

package/dist/engine/seeds/seed-definition-diff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seed-definition-diff.d.ts","sourceRoot":"","sources":["../../../src/engine/seeds/seed-definition-diff.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,aAAa,CAAA;AAI/C,yHAAyH;AACzH,MAAM,MAAM,oBAAoB,GAAG,IAAI,CAAC,MAAM,EAAE,IAAI,GAAG,QAAQ,CAAC,GAAG;IAAE,EAAE,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,oBAAoB,EAAE,CAAA;CAAE,CAAA;AAEnH,0GAA0G;AAC1G,MAAM,MAAM,kBAAkB,GAAG,IAAI,CAAC,IAAI,EAAE,UAAU,GAAG,QAAQ,CAAC,GAAG;IAAE,QAAQ,EAAE,oBAAoB,EAAE,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,CAAA;AAE3H,kEAAkE;AAClE,eAAO,MAAM,qBAAqB,iGAAkG,CAAA;AAEpI,uIAAuI;AACvI,eAAO,MAAM,uBAAuB,mDAAoD,CAAA;AAExF;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,oBAAoB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAO/F;AAED,0HAA0H;AAC1H,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,kBAAkB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAMzF;AAED,MAAM,WAAW,kBAAkB;IACjC,uHAAuH;IACvH,OAAO,EAAE,OAAO,CAAA;IAChB;;;OAGG;IACH,eAAe,EAAE,MAAM,EAAE,CAAA;CAC1B;AAED,8HAA8H;AAC9H,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,IAAI,GAAG,IAAI,EAAE,SAAS,EAAE,IAAI,GAAG,kBAAkB,CAe3F"}

package/dist/engine/seeds/seed-definition-diff.js

@@ -0,0 +1,51 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+import { canonicalStringify } from '../../common/canonical-json.js';
+import { isSingleChoiceTags } from './tag-options.js';
+/** Seed-level flags the engine treats as `false` when omitted. */
+export const SEED_DEFINITION_FLAGS = ['allowDrafts', 'allowPublicRead', 'allowPublicPost', 'allowPublicEdit', 'softDelete'];
+/** Branch-level flags the engine treats as `false` when omitted. `multiple` is resolved separately (see normalizeBranchDefinition). */
+export const BRANCH_DEFINITION_FLAGS = ['requiredOnCreate', 'requiredOnUpdate'];
+/**
+ * Comparable form of one branch definition. Two branches are the same definition iff their canonicalStringify bytes match.
+ *
+ * - `id` is dropped, recursively through `fields`.
+ * - `requiredOnCreate` / `requiredOnUpdate` omitted ≡ `false`.
+ * - `multiple` omitted ≡ `true` on `tags` (single source of truth: `isSingleChoiceTags`), ≡ `false` on every other type.
+ * - Every other key, unknown ones included, is copied unchanged: `options` is compared as declared (values, colors, order).
+ */
+export function normalizeBranchDefinition(branch) {
+    const { id: _id, fields, ...rest } = branch;
+    const normalized = { ...rest };
+    for (const flag of BRANCH_DEFINITION_FLAGS)
+        normalized[flag] = branch[flag] === true;
+    normalized.multiple = branch.type === 'tags' ? !isSingleChoiceTags(branch) : branch.multiple === true;
+    if (fields !== undefined)
+        normalized.fields = fields.map(normalizeBranchDefinition);
+    return normalized;
+}
+/** Comparable form of one seed definition (branches normalized, order kept). `layout` is server-populated and dropped. */
+export function normalizeSeedDefinition(seed) {
+    const { layout: _layout, branches, ...rest } = seed;
+    const normalized = { ...rest };
+    for (const flag of SEED_DEFINITION_FLAGS)
+        normalized[flag] = seed[flag] === true;
+    normalized.branches = (branches ?? []).map(normalizeBranchDefinition);
+    return normalized;
+}
+/** Compares a stored seed definition with a candidate whose ids were already resolved ({@link resolveCandidateIds}). Pure. */
+export function diffSeedDefinition(stored, candidate) {
+    if (stored === null)
+        return { changed: true, changedBranches: [] };
+    const storedById = new Map(stored.branches.map(branch => [branch.id, branch]));
+    const changedBranches = candidate.branches
+        .filter(branch => {
+        const previous = storedById.get(branch.id);
+        return previous === undefined
+            || canonicalStringify(normalizeBranchDefinition(branch)) !== canonicalStringify(normalizeBranchDefinition(previous));
+    })
+        .map(branch => branch.alias);
+    const changed = changedBranches.length > 0
+        || canonicalStringify(normalizeSeedDefinition(candidate)) !== canonicalStringify(normalizeSeedDefinition(stored));
+    return { changed, changedBranches };
+}