@beechcms/core 0.8.1 → 0.9.1

package/dist/engine/introspection/relation-audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relation-audit.d.ts","sourceRoot":"","sources":["../../../src/engine/introspection/relation-audit.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAU,IAAI,EAAE,MAAM,aAAa,CAAA;AAE/C,OAAO,EAIL,KAAK,mBAAmB,EACzB,MAAM,oBAAoB,CAAA;AAE3B,6DAA6D;AAC7D,MAAM,MAAM,oBAAoB;AAC9B,kFAAkF;AAChF,eAAe;AACjB,2DAA2D;GACzD,iBAAiB;AACnB,4DAA4D;GAC1D,oBAAoB;AACtB,qEAAqE;GACnE,uBAAuB,CAAA;AAE3B,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,oBAAoB,CAAA;IAC3B,6EAA6E;IAC7E,QAAQ,EAAE,MAAM,CAAA;IAChB,+BAA+B;IAC/B,MAAM,EAAE,MAAM,CAAA;IACd;;;OAGG;IACH,YAAY,EAAE,MAAM,CAAA;CACrB;AAkGD;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CACxC,QAAQ,EAAE,mBAAmB,EAC7B,KAAK,EAAE,IAAI,EAAE,GACZ,OAAO,CAAC,sBAAsB,EAAE,CAAC,CAiBnC"}

package/dist/engine/introspection/relation-audit.js

@@ -0,0 +1,103 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+import { junctionTableName } from '../ddl/ddl.js';
+import { assertSafeIdentifier, introspectTable, } from './introspection.js';
+/** Default `ON DELETE` rule, per storage shape (mirrors `engine/ddl`). */
+function effectiveOnDelete(branch) {
+    return (branch.onDelete ?? (branch.multiple === true ? 'CASCADE' : 'SET NULL')).toUpperCase();
+}
+async function countRows(executor, sql) {
+    const rows = await executor.all(sql);
+    return Number(rows[0]?.n ?? 0);
+}
+/** Checks the FK that carries the reference: the `alias` column, or the junction's `target_id`. */
+function fkFindings(seed, branch, fk, location) {
+    const expectedTarget = `content_${branch.targetSeed}`;
+    const expectedRule = effectiveOnDelete(branch);
+    const base = { seed: seed.slug, alias: branch.alias, strandedRows: 0 };
+    const expected = `${location} -> ${expectedTarget}(id) ON DELETE ${expectedRule}`;
+    if (!fk) {
+        return [{ ...base, issue: 'fk_target_mismatch', expected, actual: `${location} has no foreign key` }];
+    }
+    const actual = `${location} -> ${fk.targetTable}(${fk.targetColumn}) ON DELETE ${fk.onDelete}`;
+    const findings = [];
+    if (fk.targetTable !== expectedTarget)
+        findings.push({ ...base, issue: 'fk_target_mismatch', expected, actual });
+    if (fk.onDelete !== expectedRule)
+        findings.push({ ...base, issue: 'fk_on_delete_mismatch', expected, actual });
+    return findings;
+}
+async function auditBranch(executor, seed, branch, contentColumns, contentForeignKeys) {
+    const isMultiple = branch.multiple === true;
+    const junction = junctionTableName(seed.slug, branch.alias);
+    const draftJunction = `${junction}_drafts`;
+    const alias = assertSafeIdentifier(branch.alias);
+    const base = { seed: seed.slug, alias: branch.alias };
+    const liveJunction = await introspectTable(executor, junction);
+    const liveDraftJunction = await introspectTable(executor, draftJunction);
+    const hasColumn = contentColumns.has(alias);
+    if (isMultiple) {
+        if (hasColumn) {
+            const strandedRows = await countRows(executor, `SELECT COUNT(*) AS n FROM content_${seed.slug} WHERE "${alias}" IS NOT NULL`);
+            return [{
+                    ...base,
+                    issue: 'wrong_storage',
+                    expected: `junction ${junction}`,
+                    actual: `${liveJunction.exists ? `junction ${junction} and ` : ''}column content_${seed.slug}.${alias}`,
+                    strandedRows,
+                }];
+        }
+        if (!liveJunction.exists) {
+            return [{ ...base, issue: 'missing_storage', expected: `junction ${junction}`, actual: 'no junction table', strandedRows: 0 }];
+        }
+        const findings = fkFindings(seed, branch, liveJunction.foreignKeys.find(fk => fk.column === 'target_id'), `${junction}.target_id`);
+        if (seed.allowDrafts && !liveDraftJunction.exists) {
+            findings.push({ ...base, issue: 'missing_storage', expected: `drafts junction ${draftJunction}`, actual: 'no drafts junction table', strandedRows: 0 });
+        }
+        return findings;
+    }
+    // Single relation: the value lives in a column; any junction left behind holds stranded links.
+    if (liveJunction.exists || liveDraftJunction.exists) {
+        let strandedRows = 0;
+        if (liveJunction.exists)
+            strandedRows += await countRows(executor, `SELECT COUNT(*) AS n FROM ${junction}`);
+        if (liveDraftJunction.exists)
+            strandedRows += await countRows(executor, `SELECT COUNT(*) AS n FROM ${draftJunction}`);
+        return [{
+                ...base,
+                issue: 'wrong_storage',
+                expected: `column content_${seed.slug}.${alias}`,
+                actual: `${hasColumn ? `column content_${seed.slug}.${alias} and ` : ''}junction ${junction}`,
+                strandedRows,
+            }];
+    }
+    if (!hasColumn) {
+        return [{ ...base, issue: 'missing_storage', expected: `column content_${seed.slug}.${alias}`, actual: 'no column', strandedRows: 0 }];
+    }
+    return fkFindings(seed, branch, contentForeignKeys.get(alias), `content_${seed.slug}.${alias}`);
+}
+/**
+ * Compares every relation branch of the given (active) seeds against the physical tables.
+ *
+ * Seeds whose `content_<slug>` table is missing are skipped: that is plain schema drift and is
+ * reported by the schema diff, not a relation-storage mismatch. Findings are ordered by seed, then
+ * branch order, so the report is deterministic.
+ */
+export async function auditRelationStorage(executor, seeds) {
+    const findings = [];
+    const ordered = [...seeds].sort((a, b) => a.slug.localeCompare(b.slug));
+    // Sequential on purpose: see `introspectSchema`.
+    for (const seed of ordered) {
+        const content = await introspectTable(executor, `content_${assertSafeIdentifier(seed.slug)}`);
+        if (!content.exists)
+            continue;
+        const columns = new Set(content.columns.map(column => column.name));
+        const foreignKeys = new Map(content.foreignKeys.map(fk => [fk.column, fk]));
+        for (const branch of seed.branches) {
+            if (branch.type !== 'relation' || !branch.targetSeed)
+                continue;
+            findings.push(...await auditBranch(executor, seed, branch, columns, foreignKeys));
+        }
+    }
+    return findings;
+}

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

@@ -4,7 +4,7 @@ import type { Branch, Seed } from '../types.js';
  * 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;
+export declare const SCHEMA_FINGERPRINT_VERSION = 2;
 /** The response-shape-bearing subset of a `Branch`. */
 export interface ContractBranch {
     alias: string;
@@ -52,6 +52,7 @@ export interface SchemaContract {
  *   `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.)
+ * - option `color` — presentation only; a color edit cannot change a response byte.
  * - 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

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

@@ -1 +1 @@
-{"version":3,"file":"schema-fingerprint.d.ts","sourceRoot":"","sources":["../../../src/engine/introspection/schema-fingerprint.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,aAAa,CAAA;AAE/C;;;;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"}
+{"version":3,"file":"schema-fingerprint.d.ts","sourceRoot":"","sources":["../../../src/engine/introspection/schema-fingerprint.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,aAAa,CAAA;AAG/C;;;;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;AA4BD;;;;;;;;;;;;;;;;GAgBG;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/introspection/schema-fingerprint.js

@@ -16,21 +16,25 @@
  */
 import { canonicalStringify } from '../../common/canonical-json.js';
 import { resolvePolicies } from '../privacy/policies.js';
+import { isSingleChoiceTags, tagOptionValues } from '../seeds/tag-options.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;
+export const SCHEMA_FINGERPRINT_VERSION = 2;
 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 } : {}),
+        // `tags` always carry the resolved mode, so an omitted `multiple` hashes like `true`.
+        ...(branch.type === 'tags'
+            ? { multiple: !isSingleChoiceTags(branch) }
+            : 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] } : {}),
+        ...(branch.options !== undefined ? { options: tagOptionValues(branch) } : {}),
         requiredOnCreate: branch.requiredOnCreate ?? false,
         requiredOnUpdate: branch.requiredOnUpdate ?? false,
         ...(branch.targetSeed !== undefined ? { targetSeed: branch.targetSeed } : {}),
@@ -55,6 +59,7 @@ function projectBranch(branch) {
  *   `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.)
+ * - option `color` — presentation only; a color edit cannot change a response byte.
  * - 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

package/dist/engine/privacy/policies.d.ts

@@ -7,7 +7,7 @@ import type { ActorContext, Branch, DataClassification, Seed } from '../types.js
  */
 export declare function sha256hex(value: string): Promise<string>;
 /**
- * Verifies if a candidate string matches a stored SHA-256 hash digest.
+ * Verifies if a candidate string matches a stored SHA-256 hash digest, comparing in constant time.
  * @param stored - The expected 64-character SHA-256 hex digest.
  * @param candidate - The raw candidate string to verify.
  * @returns A Promise resolving to true if candidate matches stored digest, false otherwise.

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

@@ -1 +1 @@
-{"version":3,"file":"policies.d.ts","sourceRoot":"","sources":["../../../src/engine/privacy/policies.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,EAAE,kBAAkB,EAAE,IAAI,EAAE,MAAM,aAAa,CAAA;AAGjF;;;;;GAKG;AACH,wBAAsB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAK9D;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAEzF;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,0CAA0C;IAC1C,cAAc,EAAE,kBAAkB,CAAA;IAClC,6FAA6F;IAC7F,OAAO,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,CAAA;IACrC,6FAA6F;IAC7F,gBAAgB,EAAE,MAAM,GAAG,QAAQ,CAAA;IACnC,oFAAoF;IACpF,cAAc,EAAE,MAAM,GAAG,QAAQ,CAAA;CAClC;AAED,0EAA0E;AAC1E,wBAAgB,uBAAuB,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,kBAAkB,CAQxE;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,sBAAsB,CAmC5E;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,CAAC,WAAW,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,CA2BzF;AAuBD;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,IAAI,EAAE,IAAI,EACV,KAAK,GAAE,YAAwC,GAC9C,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAgDzB"}
+{"version":3,"file":"policies.d.ts","sourceRoot":"","sources":["../../../src/engine/privacy/policies.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,EAAE,kBAAkB,EAAE,IAAI,EAAE,MAAM,aAAa,CAAA;AAIjF;;;;;GAKG;AACH,wBAAsB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAK9D;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAEzF;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC,0CAA0C;IAC1C,cAAc,EAAE,kBAAkB,CAAA;IAClC,6FAA6F;IAC7F,OAAO,EAAE,OAAO,GAAG,SAAS,GAAG,MAAM,CAAA;IACrC,6FAA6F;IAC7F,gBAAgB,EAAE,MAAM,GAAG,QAAQ,CAAA;IACnC,oFAAoF;IACpF,cAAc,EAAE,MAAM,GAAG,QAAQ,CAAA;CAClC;AAED,0EAA0E;AAC1E,wBAAgB,uBAAuB,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,kBAAkB,CAQxE;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,sBAAsB,CAmC5E;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,CAAC,WAAW,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,CA+BzF;AAuBD;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,IAAI,EAAE,IAAI,EACV,KAAK,GAAE,YAAwC,GAC9C,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAiDzB"}

package/dist/engine/privacy/policies.js

@@ -1,6 +1,7 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) 2024–2026 Flavio De Musso
 import { isLocaleDictionary, isLocalizedBranch } from '../localization/localization.js';
+import { timingSafeEqual } from '../../webhooks/webhook-crypto.js';
 /**
  * Computes an un-salted SHA-256 hex digest of a string value.
  * Used for basic digest operations.
@@ -14,13 +15,13 @@ export async function sha256hex(value) {
         .join('');
 }
 /**
- * Verifies if a candidate string matches a stored SHA-256 hash digest.
+ * Verifies if a candidate string matches a stored SHA-256 hash digest, comparing in constant time.
  * @param stored - The expected 64-character SHA-256 hex digest.
  * @param candidate - The raw candidate string to verify.
  * @returns A Promise resolving to true if candidate matches stored digest, false otherwise.
  */
 export async function verifyHashField(stored, candidate) {
-    return stored === (await sha256hex(candidate));
+    return timingSafeEqual(stored, await sha256hex(candidate));
 }
 /** Normalizes raw policy strings to canonical DataClassification enum. */
 export function normalizeClassification(raw) {
@@ -89,9 +90,12 @@ export function resolvePolicies(branch) {
     const isEncryptedOrHashed = resolved.storage !== 'plain';
     const defaultVisibility = resolved.authVisibility;
     const isPublicAllowed = branch.policies?.public ?? (resolved.publicVisibility === 'full');
-    const defaultFilter = isRepeater || resolved.storage === 'hash' ? false : branch.policies?.filter ?? true;
-    const defaultSort = isRepeater || isEncryptedOrHashed ? false : branch.policies?.sort ?? true;
-    const defaultSearch = isRepeater || isEncryptedOrHashed ? false : branch.policies?.search ?? true;
+    const visibility = branch.policies?.visibility ?? defaultVisibility;
+    // Concealed values must not be queryable: filter/sort/search leak them
+    const isConcealed = visibility === 'hidden' || visibility === 'masked';
+    const defaultFilter = branch.policies?.filter ?? (isRepeater || resolved.storage === 'hash' ? false : !isConcealed);
+    const defaultSort = branch.policies?.sort ?? (isRepeater || isEncryptedOrHashed ? false : !isConcealed);
+    const defaultSearch = branch.policies?.search ?? (isRepeater || isEncryptedOrHashed ? false : !isConcealed);
     // publicEdit default: true for public fields (unless public: false), false for confidential/internal/restricted
     const defaultPublicEdit = resolved.classification === 'public'
         ? (branch.policies?.publicEdit ?? isPublicAllowed)
@@ -99,7 +103,7 @@ export function resolvePolicies(branch) {
     return {
         classification: resolved.classification,
         privacy: resolved.storage,
-        visibility: branch.policies?.visibility ?? defaultVisibility,
+        visibility,
         search: defaultSearch,
         filter: defaultFilter,
         sort: defaultSort,
@@ -164,6 +168,8 @@ export function filterEntryForActor(data, seed, actor = { type: 'authenticated'
         if (isPublicActor) {
             if (resolved.publicVisibility === 'hidden')
                 continue;
+            if (branch.policies?.public === false)
+                continue;
         }
         else {
             // Authenticated actor check

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

@@ -62,4 +62,17 @@ export declare class PrivacyService implements IPrivacyService {
      */
     hash(plaintext: string): Promise<string>;
 }
+/** Thrown when a protected field is processed but no master key is configured. */
+export declare class PrivacyNotConfiguredError extends Error {
+    constructor();
+}
+/**
+ * Fail-closed {@link IPrivacyService} for installs without a master key.
+ * Never returns plaintext as protected output; legacy non-`v1:` values still read through.
+ */
+export declare class UnconfiguredPrivacyService implements IPrivacyService {
+    encrypt(_plaintext: string): Promise<string>;
+    decrypt(ciphertext: string): Promise<string>;
+    hash(_plaintext: string): Promise<string>;
+}
 //# sourceMappingURL=privacy.service.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"privacy.service.d.ts","sourceRoot":"","sources":["../../../src/engine/privacy/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/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;AAED,kFAAkF;AAClF,qBAAa,yBAA0B,SAAQ,KAAK;;CAKnD;AAED;;;GAGG;AACH,qBAAa,0BAA2B,YAAW,eAAe;IAC1D,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAI5C,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAK5C,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAGhD"}

package/dist/engine/privacy/privacy.service.js

@@ -112,3 +112,27 @@ export class PrivacyService {
             .join('');
     }
 }
+/** Thrown when a protected field is processed but no master key is configured. */
+export class PrivacyNotConfiguredError extends Error {
+    constructor() {
+        super('PRIVACY_MASTER_KEY is not configured: cannot encrypt or hash protected fields');
+        this.name = 'PrivacyNotConfiguredError';
+    }
+}
+/**
+ * Fail-closed {@link IPrivacyService} for installs without a master key.
+ * Never returns plaintext as protected output; legacy non-`v1:` values still read through.
+ */
+export class UnconfiguredPrivacyService {
+    async encrypt(_plaintext) {
+        throw new PrivacyNotConfiguredError();
+    }
+    async decrypt(ciphertext) {
+        if (ciphertext?.startsWith('v1:'))
+            throw new PrivacyNotConfiguredError();
+        return ciphertext;
+    }
+    async hash(_plaintext) {
+        throw new PrivacyNotConfiguredError();
+    }
+}

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

@@ -0,0 +1,19 @@
+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'.
+ *
+ * @param seed - The seed schema definition.
+ * @param mode - 'active' (default), 'trashed', or 'any'.
+ * @param tableAlias - Optional table or alias qualifier prefix.
+ */
+export declare function activeCondition(seed: Seed, mode?: TrashedMode, tableAlias?: string): string | null;
+/**
+ * Returns ` AND <activeCondition>` for a soft-delete seed, or `''` otherwise.
+ *
+ * @param seed - The seed schema definition.
+ * @param mode - 'active' (default), 'trashed', or 'any'.
+ * @param tableAlias - Optional table or alias qualifier prefix.
+ */
+export declare function activeClause(seed: Seed, mode?: TrashedMode, tableAlias?: string): string;
+//# sourceMappingURL=active-clause.d.ts.map

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

@@ -0,0 +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"}

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

@@ -0,0 +1,27 @@
+// 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'.
+ *
+ * @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')
+        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.
+ *
+ * @param seed - The seed schema definition.
+ * @param mode - 'active' (default), 'trashed', or 'any'.
+ * @param tableAlias - Optional table or alias qualifier prefix.
+ */
+export function activeClause(seed, mode = 'active', tableAlias) {
+    const cond = activeCondition(seed, mode, tableAlias);
+    return cond ? ` AND ${cond}` : '';
+}

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

@@ -1,4 +1,4 @@
-import type { Seed, SelectOptions, ParameterizedQuery } from '../types.js';
+import type { Seed, FilterGroup, SelectOptions, ParameterizedQuery } from '../types.js';
 /**
  * Builds a parameterized SQL SELECT query and bindings for a given Seed based on search, filtering, status, and ordering options.
  *
@@ -20,4 +20,17 @@ import type { Seed, SelectOptions, ParameterizedQuery } from '../types.js';
  * ```
  */
 export declare function buildSelectQuery(seed: Seed, options?: SelectOptions): ParameterizedQuery;
+/**
+ * Lists the filter groups `buildSelectQuery` would silently leave out of the WHERE clause: an unknown
+ * column, or a condition whose value cannot be bound for the field type (empty or unparsable
+ * number/date, `in`/`not_in` value that is not an array). An empty `in` is not listed:
+ * it compiles to constant false and still constrains the read. A caller that needs the filter to constrain the read
+ * (e.g. automations resolving placeholders at run time) uses this to refuse the query instead of
+ * running it unconstrained.
+ *
+ * @param seed The seed the filters apply to.
+ * @param filters The filter groups to check.
+ * @returns The groups that would be dropped, in input order.
+ */
+export declare function findUnappliedFilters(seed: Seed, filters: FilterGroup[]): FilterGroup[];
 //# sourceMappingURL=query.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../../src/engine/query/query.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,IAAI,EAMJ,aAAa,EAEb,kBAAkB,EACnB,MAAM,aAAa,CAAC;AAgErB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,GAAE,aAAkB,GAAG,kBAAkB,CA4G5F"}
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../../src/engine/query/query.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,IAAI,EAGJ,WAAW,EAGX,aAAa,EAEb,kBAAkB,EACnB,MAAM,aAAa,CAAC;AA8FrB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,GAAE,aAAkB,GAAG,kBAAkB,CAgH5F;AAGD;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,WAAW,EAAE,GAAG,WAAW,EAAE,CAKtF"}

package/dist/engine/query/query.js

@@ -1,6 +1,9 @@
 import { tableName, ftsTableName, isValidColumn, indexableSearchBranches, SYSTEM_COLUMNS } from '../ddl/ddl.js';
 import { resolveClassification } from '../privacy/policies.js';
 import { isLocaleCode, isLocalizedBranch } from '../localization/localization.js';
+import { activeCondition } from './active-clause.js';
+import { isSingleChoiceTags, tagOptionValues } from '../seeds/tag-options.js';
+import { normalizeTagValue, TAG_OPTIONS_MAX_COUNT } from '../seeds/tag-value.js';
 /** SQLite GLOB twins of `LOCALE_CODE_RE` (`it`, `ast`, `pt-BR`, `es-419`, …). Keep both in sync. */
 const LOCALE_KEY_GLOBS = [
     '[a-z][a-z]',
@@ -57,6 +60,27 @@ function columnSql(seed, table, alias, locale) {
     }
     return alias;
 }
+/** A multiple-choice `tags` column has no meaningful order, so `orderBy` on it is ignored. */
+function isMultipleChoiceTagsColumn(seed, alias) {
+    const branch = seed.branches.find((b) => b.alias === alias);
+    return branch?.type === 'tags' && !isSingleChoiceTags(branch);
+}
+/**
+ * ORDER BY clause for a single-choice tags column: empty values (`NULL`, `[]`) always last, then the option
+ * position (a value outside the options ranks after every option) or, without options, the value alphabetically.
+ * Option values are pushed to `bindings`.
+ */
+function tagsOrderClause(col, branch, dir, bindings) {
+    const head = `(CASE WHEN json_valid(${col}) THEN json_extract(${col}, '$[0]') END)`;
+    const options = tagOptionValues(branch);
+    let rank = head;
+    if (options.length > 0) {
+        const branches = options.map((_, position) => `WHEN ? THEN ${position}`).join(' ');
+        rank = `CASE ${head} ${branches} ELSE ${options.length} END`;
+        bindings.push(...options);
+    }
+    return ` ORDER BY (${head} IS NULL) ASC, ${rank} ${dir}`;
+}
 /**
  * Builds a parameterized SQL SELECT query and bindings for a given Seed based on search, filtering, status, and ordering options.
  *
@@ -106,11 +130,9 @@ export function buildSelectQuery(seed, options = {}) {
     // which all reach SQL only through repository.findMany.
     if (seed.softDelete) {
         const trashed = options.trashed ?? 'active';
-        if (trashed === 'active') {
-            whereClauses.push(`${table}.deleted_at IS NULL`);
-        }
-        else if (trashed === 'trashed') {
-            whereClauses.push(`${table}.deleted_at IS NOT NULL`);
+        const cond = activeCondition(seed, trashed, table);
+        if (cond) {
+            whereClauses.push(cond);
         }
     }
     const groupClauses = [];
@@ -135,6 +157,9 @@ export function buildSelectQuery(seed, options = {}) {
                     if (clause)
                         condClauses.push(clause);
                 }
+                else {
+                    throw new TypeError(`Invalid filter: operator '${op}' is not supported for encrypted field '${group.column}'`);
+                }
             }
             else {
                 const clause = buildFilterCondition(col, group.type, cond, bindings);
@@ -170,10 +195,13 @@ export function buildSelectQuery(seed, options = {}) {
         if (kanbanOrderClause) {
             sql += kanbanOrderClause;
         }
-        else if (orderBy && isValidColumn(seed, orderBy.column)) {
+        else if (orderBy && isValidColumn(seed, orderBy.column) && !isMultipleChoiceTagsColumn(seed, orderBy.column)) {
             const dir = orderBy.dir === 'DESC' ? 'DESC' : 'ASC';
             const col = columnSql(seed, table, orderBy.column, options.locale);
-            sql += ` ORDER BY ${col} ${dir}`;
+            const orderedBranch = seed.branches.find((b) => b.alias === orderBy.column);
+            sql += orderedBranch && isSingleChoiceTags(orderedBranch)
+                ? tagsOrderClause(col, orderedBranch, dir, bindings)
+                : ` ORDER BY ${col} ${dir}`;
         }
         else {
             sql += ` ORDER BY ${table}.created_at DESC`;
@@ -185,6 +213,22 @@ export function buildSelectQuery(seed, options = {}) {
     }
     return { sql, bindings };
 }
+/**
+ * Lists the filter groups `buildSelectQuery` would silently leave out of the WHERE clause: an unknown
+ * column, or a condition whose value cannot be bound for the field type (empty or unparsable
+ * number/date, `in`/`not_in` value that is not an array). An empty `in` is not listed:
+ * it compiles to constant false and still constrains the read. A caller that needs the filter to constrain the read
+ * (e.g. automations resolving placeholders at run time) uses this to refuse the query instead of
+ * running it unconstrained.
+ *
+ * @param seed The seed the filters apply to.
+ * @param filters The filter groups to check.
+ * @returns The groups that would be dropped, in input order.
+ */
+export function findUnappliedFilters(seed, filters) {
+    return filters.filter((group) => !isValidColumn(seed, group.column)
+        || group.conditions.some((cond) => buildFilterCondition('col', group.type, cond, []) === null));
+}
 /**
  * Normalizes user-provided filter values to a format appropriate for SQL execution.
  *
@@ -218,6 +262,35 @@ function normalizeFilterValue(type, value) {
     }
     return value;
 }
+/** On a `tags` column, equality-like operators test membership; `negated` ones are the complement. */
+const TAGS_MEMBERSHIP_OPS = {
+    eq: { op: 'has_tag', negated: false },
+    contains: { op: 'has_tag', negated: false },
+    in: { op: 'has_any_tag', negated: false },
+    neq: { op: 'has_tag', negated: true },
+    not_contains: { op: 'has_tag', negated: true },
+    not_in: { op: 'has_any_tag', negated: true },
+};
+function buildTagsMembershipCondition(col, op, value, bindings) {
+    const { op: membershipOp, negated } = TAGS_MEMBERSHIP_OPS[op];
+    const isSetOp = membershipOp === 'has_any_tag';
+    let tags;
+    if (isSetOp) {
+        if (!Array.isArray(value))
+            return null;
+        tags = value.filter((v) => typeof v === 'string' || typeof v === 'number').map(String);
+        // Same rule as in/not_in: an empty set matches nothing, its negation adds no clause.
+        if (tags.length === 0)
+            return negated ? null : '0';
+    }
+    else {
+        if (typeof value !== 'string' && typeof value !== 'number')
+            return null;
+        tags = [String(value)];
+    }
+    const condition = buildFilterCondition(col, 'tags', { op: membershipOp, value: isSetOp ? tags : tags[0] }, bindings);
+    return negated && condition ? `NOT (${condition})` : condition;
+}
 /**
  * Translates a filter condition into its SQL clause and adds parameters to the bindings list.
  *
@@ -234,21 +307,26 @@ function buildFilterCondition(col, type, cond, bindings) {
         if (type === 'text') {
             return isEmpty ? `(${col} IS NULL OR ${col} = '')` : `(${col} IS NOT NULL AND ${col} != '')`;
         }
-        if (type === 'tags' || type === 'json') {
+        if (type === 'tags' || type === 'json' || type === 'repeater') {
             return isEmpty
                 ? `(${col} IS NULL OR ${col} = '[]' OR ${col} = '{}')`
                 : `(${col} IS NOT NULL AND ${col} != '[]' AND ${col} != '{}')`;
         }
         return isEmpty ? `${col} IS NULL` : `${col} IS NOT NULL`;
     }
+    if (type === 'tags' && Object.hasOwn(TAGS_MEMBERSHIP_OPS, op)) {
+        return buildTagsMembershipCondition(col, op, value, bindings);
+    }
     if (op === 'in' || op === 'not_in') {
-        if (!Array.isArray(value) || value.length === 0)
+        if (!Array.isArray(value))
             return null;
         const normalizedValues = value
             .map((v) => normalizeFilterValue(type, v))
             .filter((v) => v !== null);
+        // Membership in an empty set is false, not "no constraint"; dropping it would widen the result set.
+        // `not_in` over an empty set is vacuously true, so it adds no clause.
         if (normalizedValues.length === 0)
-            return null;
+            return op === 'in' ? '0' : null;
         const placeholders = normalizedValues.map(() => '?').join(', ');
         bindings.push(...normalizedValues);
         return `${col} ${op === 'in' ? 'IN' : 'NOT IN'} (${placeholders})`;
@@ -256,10 +334,24 @@ function buildFilterCondition(col, type, cond, bindings) {
     if (op === 'has_tag' || op === 'has_any_tag' || op === 'has_all_tags') {
         if (type !== 'tags' && type !== 'json')
             return null;
-        const tags = (op === 'has_tag' ? [value] : Array.isArray(value) ? value : [value])
-            .map(t => String(t));
-        if (tags.length === 0)
+        const requested = [...new Set((op === 'has_tag' ? [value] : Array.isArray(value) ? value : [value]).map(t => String(t)))];
+        if (requested.length === 0)
             return null;
+        // One bound parameter per tag and D1 allows 100 per statement: an oversized set is a malformed filter.
+        if (requested.length > TAG_OPTIONS_MAX_COUNT)
+            return null;
+        // A stored `tags` value is always normalized, so the needle is too. One that cannot be normalized
+        // (blank, too long, ill-formed) matches nothing, and `has_all_tags` over it can never be satisfied.
+        let tags = requested;
+        if (type === 'tags') {
+            const normalized = requested.flatMap((t) => {
+                const result = normalizeTagValue(t);
+                return result.ok && result.value.length > 0 ? [result.value] : [];
+            });
+            if (normalized.length === 0 || (op === 'has_all_tags' && normalized.length < requested.length))
+                return '0';
+            tags = [...new Set(normalized)];
+        }
         // json_each on array → value is the element; on object → key is the property name.
         // Tags stored as ["photo"] (array) or {"photo":"#3b82f6"} (object) must both match.
         const tagRef = `CASE json_type(${col}) WHEN 'array' THEN value ELSE key END`;

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;
+}