@plumix/core 0.1.0

package/dist/rpc/meta/core.js

@@ -0,0 +1,795 @@
+import { sql } from "drizzle-orm";
+import { eq } from "../../db/index.js";
+import { MetaReferenceError } from "./errors.js";
+// Shared meta plumbing for every entity that stores a `meta` JSON
+// column (entries, terms, and — eventually — users). The storage
+// contract: writes merge into the bag via SQLite `json_set` /
+// `json_remove`; reads come back already-parsed via drizzle's
+// `mode: "json"`. Per-entity specializations in `procedures/{entry,
+// term}/meta.ts` thread the right table + action name through these
+// helpers.
+/** Per-value byte cap after JSON encoding. 256 KiB fits any realistic
+ *  plugin config while bounding adversarial payloads. */
+const MAX_META_VALUE_BYTES = 256 * 1024;
+export class MetaSanitizationError extends Error {
+    static {
+        MetaSanitizationError.prototype.name = "MetaSanitizationError";
+    }
+    key;
+    reason;
+    constructor(key, reason) {
+        super(`meta key "${key}" failed sanitization: ${reason}`);
+        this.key = key;
+        this.reason = reason;
+    }
+    static notRegistered(ctx) {
+        return new MetaSanitizationError(ctx.key, "not_registered");
+    }
+    static invalidValue(ctx) {
+        return new MetaSanitizationError(ctx.key, "invalid_value");
+    }
+    static valueTooLarge(ctx) {
+        return new MetaSanitizationError(ctx.key, "value_too_large");
+    }
+}
+/**
+ * Validate an incoming meta map against a field-lookup fn produced by
+ * the caller (entry vs term differ only in which registry they walk).
+ * Unregistered keys and type-coercion failures throw so the caller can
+ * surface them as 4xx before any write. `null` / `undefined` values
+ * are deletion requests; everything else is coerced + sanitized.
+ */
+export function sanitizeMetaInput(findField, input) {
+    if (input === undefined)
+        return null;
+    const upserts = new Map();
+    const deletes = [];
+    for (const [key, rawValue] of Object.entries(input)) {
+        const field = findField(key);
+        if (!field) {
+            throw MetaSanitizationError.notRegistered({ key });
+        }
+        if (rawValue === null || rawValue === undefined) {
+            deletes.push(key);
+            continue;
+        }
+        const coerced = coerceToType(field.type, key, rawValue);
+        const sanitized = field.sanitize
+            ? runSanitize(field.sanitize, key, coerced)
+            : coerced;
+        assertEncodedSize(key, sanitized);
+        upserts.set(key, sanitized);
+    }
+    return { upserts, deletes };
+}
+/**
+ * Run a field's sanitize callback inside a try/catch — any thrown
+ * `MetaSanitizationError` propagates as-is (so callbacks that already
+ * use the precise error type can opt into specific reasons), but
+ * generic errors (including plain `Error("invalid_value")` thrown
+ * from builder-injected default sanitizers) are translated into a
+ * uniform `invalid_value` failure. Callbacks therefore stay free to
+ * throw vanilla errors without importing the package-internal error
+ * class.
+ */
+function runSanitize(sanitize, key, value) {
+    try {
+        return sanitize(value);
+    }
+    catch (error) {
+        if (error instanceof MetaSanitizationError)
+            throw error;
+        // Buggy sanitize callbacks otherwise round to a generic
+        // `invalid_value` envelope, which is fine for the editor's UX
+        // but loses the underlying stack. Log it before translating so
+        // server logs preserve the diagnostic trail.
+        console.error(`[plumix] sanitize callback for meta key ${JSON.stringify(key)} threw:`, error);
+        throw MetaSanitizationError.invalidValue({ key });
+    }
+}
+/**
+ * Thin wrapper that translates a thrown `MetaSanitizationError` into
+ * the RPC handler's CONFLICT envelope.
+ */
+export function sanitizeMetaForRpc(findField, input, errors) {
+    try {
+        return sanitizeMetaInput(findField, input);
+    }
+    catch (error) {
+        if (error instanceof MetaSanitizationError) {
+            throw errors.CONFLICT({
+                data: { reason: `meta_${error.reason}`, key: error.key },
+            });
+        }
+        throw error;
+    }
+}
+/**
+ * Walk a sanitized patch, group every reference upsert by
+ * `(kind, scope)`, and issue one `LookupAdapter.list({ ids })`
+ * query per group to confirm all upserted IDs are real and in
+ * scope **at validation time**. Throws `invalid_value` for any id
+ * missing from its group's live-id set — same surface whether the
+ * adapter is unregistered, the target is gone, or scope rejected
+ * it. Sync `sanitize` callbacks can't run DB queries, so this is a
+ * separate async step the RPC procedures invoke between
+ * sanitisation and `applyMetaPatch`.
+ *
+ * TOCTOU note: validate runs in a separate query from the eventual
+ * `applyMetaPatch`, and callers don't share a transaction. A
+ * concurrent delete between validate and apply leaves an orphan id
+ * in the meta bag; `filterMetaOrphans` masks it on read. Wrap the
+ * validate/apply pair in `ctx.db.transaction()` if a caller needs
+ * serializable consistency.
+ */
+export async function validateMetaReferences(ctx, findField, patch) {
+    const groups = new Map();
+    for (const [key, value] of patch.upserts) {
+        const field = findField(key);
+        const target = referenceTargetOf(field);
+        if (target) {
+            const registered = ctx.plugins.lookupAdapters.get(target.kind);
+            if (!registered) {
+                throw MetaSanitizationError.invalidValue({ key });
+            }
+            const ids = referenceIdsForValidation(key, value, target, fieldMax(field));
+            const group = upsertGroup(groups, target, registered);
+            for (const id of ids)
+                group.ids.add(id);
+            group.contributions.push({
+                errorKey: key,
+                ids,
+                applyNormalize: (rowsById) => {
+                    if (target.valueShape !== "object")
+                        return;
+                    if (target.multiple) {
+                        patch.upserts.set(key, ids.map((id) => buildCachedReference(id, rowsById)));
+                        return;
+                    }
+                    const [singleId] = ids;
+                    if (singleId !== undefined) {
+                        patch.upserts.set(key, buildCachedReference(singleId, rowsById));
+                    }
+                },
+            });
+            continue;
+        }
+        // Repeater fields don't carry a `referenceTarget` themselves but
+        // their rows can. Walk into rows so nested `entry` / `term` /
+        // `user` / `media` refs flow through the same `(kind, scope)`
+        // batch as top-level fields. Errors attribute to the top-level
+        // repeater key — the row index + subKey live in the developer
+        // log, not the wire response (per slice acceptance).
+        if (!isRepeaterField(field))
+            continue;
+        if (!Array.isArray(value))
+            continue;
+        collectRepeaterReferences(ctx, key, field, value, groups);
+    }
+    for (const group of groups.values()) {
+        if (group.ids.size === 0)
+            continue;
+        const liveRows = await fetchLiveRows(ctx, group.registered, group.scope, group.ids, "validateMetaReferences");
+        const rowsById = new Map(liveRows.map((r) => [r.id, r]));
+        for (const contribution of group.contributions) {
+            for (const id of contribution.ids) {
+                if (!rowsById.has(id)) {
+                    if (contribution.diagnostic !== undefined) {
+                        // Wire error keys on the top-level field; this log line
+                        // is the only place the row index + subKey surface, so
+                        // an engineer debugging a `meta_invalid_value` on a
+                        // repeater can locate the offending subField without
+                        // bisecting the saved bag. `JSON.stringify(id)` escapes
+                        // control characters so a user-supplied id with newlines
+                        // can't poison the log stream.
+                        console.error(`[plumix] meta repeater ${JSON.stringify(contribution.errorKey)} ` +
+                            `row ${String(contribution.diagnostic.rowIdx)} ` +
+                            `subField ${JSON.stringify(contribution.diagnostic.subKey)} ` +
+                            `references missing id ${JSON.stringify(id)}`);
+                    }
+                    throw MetaSanitizationError.invalidValue({
+                        key: contribution.errorKey,
+                    });
+                }
+            }
+            contribution.applyNormalize(rowsById);
+        }
+    }
+}
+function isRepeaterField(field) {
+    if (!field)
+        return false;
+    return field.inputType === "repeater";
+}
+function collectRepeaterReferences(ctx, topKey, field, rows, groups) {
+    // Nested repeaters are rejected at registration by `repeater()`, so
+    // any subField that's itself a repeater wouldn't get here in
+    // practice. We don't recurse into subField repeaters either way —
+    // single-source-of-truth on the registration guard.
+    for (const [rowIdx, row] of rows.entries()) {
+        if (!row || typeof row !== "object" || Array.isArray(row))
+            continue;
+        const rowObj = row;
+        for (const subField of field.subFields) {
+            const target = referenceTargetOf(subField);
+            if (!target)
+                continue;
+            const subValue = rowObj[subField.key];
+            if (subValue === undefined || subValue === null)
+                continue;
+            const registered = ctx.plugins.lookupAdapters.get(target.kind);
+            if (!registered) {
+                throw MetaSanitizationError.invalidValue({ key: topKey });
+            }
+            const ids = referenceIdsForValidation(topKey, subValue, target, fieldMax(subField));
+            const group = upsertGroup(groups, target, registered);
+            for (const id of ids)
+                group.ids.add(id);
+            const subKey = subField.key;
+            group.contributions.push({
+                errorKey: topKey,
+                ids,
+                diagnostic: { rowIdx, subKey },
+                applyNormalize: (rowsById) => {
+                    if (target.valueShape !== "object")
+                        return;
+                    // Rewrite the row's cached-object value in place — the
+                    // top-level upsert array is the live storage shape, so
+                    // mutating an object inside it is what the caller will
+                    // serialize.
+                    if (target.multiple) {
+                        rowObj[subKey] = ids.map((id) => buildCachedReference(id, rowsById));
+                        return;
+                    }
+                    const [singleId] = ids;
+                    if (singleId !== undefined) {
+                        rowObj[subKey] = buildCachedReference(singleId, rowsById);
+                    }
+                },
+            });
+        }
+    }
+}
+function upsertGroup(groups, target, registered) {
+    const groupKey = referenceGroupKey(target);
+    let group = groups.get(groupKey);
+    if (!group) {
+        group = {
+            registered,
+            scope: target.scope,
+            ids: new Set(),
+            contributions: [],
+        };
+        groups.set(groupKey, group);
+    }
+    return group;
+}
+// Adapter cached fields override anything; user-supplied non-id keys
+// don't survive. Per-usage user fields (e.g. alt overrides) are a
+// post-v0.1 feature — when added, this is where they'd merge in.
+function buildCachedReference(id, rowsById) {
+    const row = rowsById.get(id);
+    return { id, ...(row?.cached ?? {}) };
+}
+// Defense-in-depth ceiling on the internal-aggregated id-batch size.
+// Above this, the live-id fetch throws rather than silently truncating.
+// The wire cap (100) and per-field cap (`HARD_MULTI_REFERENCE_LIMIT`,
+// 100) keep external + per-field batches small; this ceiling only
+// kicks in if many fields share `(kind, scope)` and aggregate.
+const MAX_REFERENCE_GROUP_BATCH = 1000;
+// Same kind + same scope = same SQL filter, so they batch into one
+// `list({ ids })` call. JSON.stringify is good enough for the scope
+// shapes we ship (`UserFieldScope`, `EntryFieldScope`,
+// `TermFieldScope` are all simple objects with stable key order at
+// build time). Plugin authors who construct scopes with non-stable
+// key order get separate groups — extra query, no correctness issue.
+//
+// `::` separator is collision-safe by construction: `kind` is
+// constrained to `[a-z][a-z0-9_-]{0,63}` (no colons) by the lookup
+// RPC schema, and core registers `user`/`entry`/`term` directly.
+//
+// `LookupAdapter` requires JSON-serializable scope; rethrow with a
+// clear message if `JSON.stringify` rejects (BigInt, cycle, function)
+// rather than letting the downstream read crash with a generic.
+function referenceGroupKey(target) {
+    try {
+        return `${target.kind}::${JSON.stringify(target.scope ?? null)}`;
+    }
+    catch (cause) {
+        throw MetaReferenceError.scopeNotSerializable(target.kind, cause);
+    }
+}
+// Run one `list({ ids })` per group, throwing if the aggregated batch
+// blew past `MAX_REFERENCE_GROUP_BATCH`. The wire schema caps `ids` at
+// 100 per-request and `HARD_MULTI_REFERENCE_LIMIT` caps each field at
+// 100, so we only hit the ceiling when many fields share `(kind, scope)`
+// and aggregate — at which point throwing beats silent truncation
+// (truncation would either reject valid writes or hide live targets).
+//
+// Returns `LookupResult[]` rather than just live ids so the validator
+// can read `cached` for the cached-object normalize step. Callers that
+// only care about presence build a `Set` from the row ids.
+async function fetchLiveRows(ctx, registered, scope, ids, callsite) {
+    if (ids.size > MAX_REFERENCE_GROUP_BATCH) {
+        throw MetaReferenceError.batchSizeExceeded(callsite, ids.size, MAX_REFERENCE_GROUP_BATCH);
+    }
+    const idList = [...ids];
+    return registered.adapter.list(ctx, {
+        ids: idList,
+        scope,
+        limit: idList.length,
+    });
+}
+// Defensive upper bound on multi-reference array length, applied
+// per-field before grouping. Even with the batched `list({ ids })`
+// path, an unbounded array still pulls 10k rows in one query — the
+// cap protects the wire / response size. 100 covers any realistic
+// multi-reference field (authors, tags, related entries); fields
+// can declare a lower `max` and the validator picks the smaller.
+const HARD_MULTI_REFERENCE_LIMIT = 100;
+// Validates the wire shape of a reference value and returns the ids
+// to feed into the group's batched `list({ ids })` call. Four shapes
+// are accepted, dispatching on `target.multiple` + `target.valueShape`:
+//
+//  - multi=true,  valueShape="id"  (default): string[] of non-empty ids
+//  - multi=true,  valueShape="object":        `{ id }[]` — each item a
+//                                             cached-object reference
+//                                             (or bare strings for
+//                                             leniency on first write)
+//  - multi=false, valueShape="id"  (default): bare string id
+//  - multi=false, valueShape="object":        `{ id: string, ... }`
+//                                             (or a bare string for
+//                                             leniency on first write)
+function referenceIdsForValidation(key, value, target, max) {
+    if (target.multiple) {
+        if (!Array.isArray(value)) {
+            throw MetaSanitizationError.invalidValue({ key });
+        }
+        if (value.length > HARD_MULTI_REFERENCE_LIMIT) {
+            throw MetaSanitizationError.valueTooLarge({ key });
+        }
+        if (max !== undefined && value.length > max) {
+            throw MetaSanitizationError.invalidValue({ key });
+        }
+        if (target.valueShape === "object") {
+            // Lenient on input: each item can be `"42"` (first-write
+            // convenience) or `{ id: "42", ... }`. Always rewritten to the
+            // canonical `{ id, ...cached }` shape after the live-id check.
+            const ids = [];
+            for (const item of value) {
+                if (typeof item === "string" && item !== "") {
+                    ids.push(item);
+                    continue;
+                }
+                const id = extractStringId(item);
+                if (id !== null && id !== "") {
+                    ids.push(id);
+                    continue;
+                }
+                throw MetaSanitizationError.invalidValue({ key });
+            }
+            return ids;
+        }
+        for (const item of value) {
+            if (typeof item !== "string" || item === "") {
+                throw MetaSanitizationError.invalidValue({ key });
+            }
+        }
+        return value;
+    }
+    if (target.valueShape === "object") {
+        // Lenient on input: accept either `"42"` (first-write convenience)
+        // or `{ id: "42", ... }`. Always rewritten to the canonical
+        // `{ id, ...cached }` shape after the live-id check.
+        if (typeof value === "string" && value !== "")
+            return [value];
+        const id = extractStringId(value);
+        if (id !== null && id !== "")
+            return [id];
+        throw MetaSanitizationError.invalidValue({ key });
+    }
+    if (typeof value !== "string") {
+        throw MetaSanitizationError.invalidValue({ key });
+    }
+    return [value];
+}
+// Returns the `id` string of a `{ id: string, ... }` object, or null
+// for any other shape (string, array, null, primitive, missing key).
+function extractStringId(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return null;
+    }
+    const id = value.id;
+    return typeof id === "string" ? id : null;
+}
+function fieldMax(field) {
+    return field?.max;
+}
+/**
+ * RPC-shaped wrapper around `validateMetaReferences` — same envelope
+ * translation as `sanitizeMetaForRpc`. Procedures call this right
+ * after `sanitizeMetaForRpc` so reference validation rides on the
+ * same `meta_invalid_value` error surface authors already match on.
+ */
+export async function validateMetaReferencesForRpc(ctx, findField, patch, errors) {
+    try {
+        await validateMetaReferences(ctx, findField, patch);
+    }
+    catch (error) {
+        if (error instanceof MetaSanitizationError) {
+            throw errors.CONFLICT({
+                data: { reason: `meta_${error.reason}`, key: error.key },
+            });
+        }
+        throw error;
+    }
+}
+/**
+ * Yield every reference-field occurrence in a decoded meta bag: top-level
+ * reference fields, plus reference subFields inside each repeater row. One
+ * structural walk so the orphan-strip pass doesn't reinline the
+ * top-level/repeater traversal twice.
+ */
+function* referenceOccurrences(entries, findField) {
+    for (const [key, value] of entries) {
+        const field = findField(key);
+        const target = referenceTargetOf(field);
+        if (target) {
+            yield { key, target, value };
+            continue;
+        }
+        if (!isRepeaterField(field))
+            continue;
+        if (!Array.isArray(value))
+            continue;
+        for (const [rowIdx, row] of value.entries()) {
+            if (!row || typeof row !== "object" || Array.isArray(row))
+                continue;
+            const rowObj = row;
+            for (const subField of field.subFields) {
+                const subTarget = referenceTargetOf(subField);
+                if (!subTarget)
+                    continue;
+                yield {
+                    key,
+                    target: subTarget,
+                    value: rowObj[subField.key],
+                    nested: { rowIdx, subKey: subField.key },
+                };
+            }
+        }
+    }
+}
+export async function filterMetaOrphans(ctx, findField, decoded) {
+    const candidates = [];
+    const groups = new Map();
+    // Top-level refs and repeater-row subField refs get identical orphan-strip
+    // treatment, so the single `referenceOccurrences` walk feeds both. Nested
+    // candidates carry their `rowIdx`/`subKey`; Pass 3 rewrites the row slot in
+    // a per-key clone so the caller's `decoded` bag stays untouched.
+    for (const occ of referenceOccurrences(Object.entries(decoded), findField)) {
+        const registered = ctx.plugins.lookupAdapters.get(occ.target.kind);
+        if (!registered)
+            continue;
+        const ids = orphanCandidateIds(occ.target, occ.value);
+        if (ids === null)
+            continue; // non-array multi / non-string single — leave untouched
+        const groupKey = referenceGroupKey(occ.target);
+        candidates.push({
+            key: occ.key,
+            multiple: occ.target.multiple === true,
+            valueShape: occ.target.valueShape ?? "id",
+            groupKey,
+            ids,
+            nested: occ.nested,
+        });
+        if (ids.length === 0)
+            continue;
+        let group = groups.get(groupKey);
+        if (!group) {
+            group = { registered, scope: occ.target.scope, ids: new Set() };
+            groups.set(groupKey, group);
+        }
+        for (const id of ids)
+            group.ids.add(id);
+    }
+    // Pass 2: one `list({ ids })` per group, keyed for O(1) apply lookup.
+    const liveIdsByGroup = new Map();
+    for (const [groupKey, group] of groups) {
+        const rows = await fetchLiveRows(ctx, group.registered, group.scope, group.ids, "filterMetaOrphans");
+        liveIdsByGroup.set(groupKey, new Set(rows.map((row) => row.id)));
+    }
+    // Pass 3: apply the filter. Orphan handling differs by shape:
+    //  - multi + id: filter the string[] in place, dropping missing
+    //  - multi + object: filter the object[] preserving order
+    //  - single + id: null on missing
+    //  - single + object: null on missing; otherwise keep the stored
+    //    cached value as-is (no read-time refresh — write rewrites)
+    // Nested-in-repeater candidates rewrite the row's subField slot in
+    // a per-key cloned array so the input bag stays untouched.
+    const out = { ...decoded };
+    const empty = new Set();
+    for (const candidate of candidates) {
+        const { key, multiple, valueShape, groupKey, ids, nested } = candidate;
+        const liveIds = liveIdsByGroup.get(groupKey) ?? empty;
+        if (nested !== undefined) {
+            const rowObj = takeWritableRow(out, decoded, key, nested.rowIdx);
+            if (!rowObj)
+                continue;
+            applyOrphanToSlot(rowObj, nested.subKey, multiple, valueShape, ids, liveIds);
+            continue;
+        }
+        if (multiple) {
+            if (valueShape === "object") {
+                const stored = decoded[key];
+                out[key] = stored.filter((item) => {
+                    const id = extractStringId(item);
+                    return id !== null && liveIds.has(id);
+                });
+                continue;
+            }
+            out[key] = ids.filter((id) => liveIds.has(id));
+            continue;
+        }
+        const [singleId] = ids;
+        if (singleId === undefined)
+            continue; // single non-string already filtered upstream
+        if (!liveIds.has(singleId))
+            out[key] = null;
+    }
+    return out;
+}
+function takeWritableRow(out, decoded, key, rowIdx) {
+    // Lazily clone the rows array (and the targeted row inside it) on
+    // first nested write so the caller's `decoded` bag stays untouched.
+    // Subsequent nested writes hit the same cloned array.
+    let arr = out[key];
+    if (arr === decoded[key]) {
+        if (!Array.isArray(arr))
+            return null;
+        const cloned = arr.map((row) => row && typeof row === "object" && !Array.isArray(row)
+            ? { ...row }
+            : row);
+        out[key] = cloned;
+        arr = cloned;
+    }
+    if (!Array.isArray(arr))
+        return null;
+    const row = arr[rowIdx];
+    if (!row || typeof row !== "object" || Array.isArray(row))
+        return null;
+    return row;
+}
+function applyOrphanToSlot(rowObj, subKey, multiple, valueShape, ids, liveIds) {
+    if (multiple) {
+        if (valueShape === "object") {
+            const stored = rowObj[subKey];
+            rowObj[subKey] = stored.filter((item) => {
+                const id = extractStringId(item);
+                return id !== null && liveIds.has(id);
+            });
+            return;
+        }
+        rowObj[subKey] = ids.filter((id) => liveIds.has(id));
+        return;
+    }
+    const [singleId] = ids;
+    if (singleId === undefined)
+        return;
+    if (!liveIds.has(singleId))
+        rowObj[subKey] = null;
+}
+// Returns `null` to mean "no candidates from this key" (skip), or
+// the ids to feed into the group's batch query. Mirrors the storage-
+// shape guards in the apply step so we don't enqueue work that's
+// going to be skipped. Cached-object values (`valueShape === "object"`)
+// extract `id` from the object — the rest of the cached fields are
+// trusted on read (refresh happens on next write via the validator's
+// normalize step, not on every render).
+function orphanCandidateIds(target, value) {
+    if (target.multiple) {
+        if (!Array.isArray(value))
+            return null;
+        if (target.valueShape === "object") {
+            const ids = [];
+            for (const item of value) {
+                const id = extractStringId(item);
+                if (id !== null)
+                    ids.push(id);
+            }
+            return ids;
+        }
+        return value.filter((id) => typeof id === "string");
+    }
+    if (target.valueShape === "object") {
+        const id = extractStringId(value);
+        return id !== null ? [id] : null;
+    }
+    return typeof value === "string" ? [value] : null;
+}
+function referenceTargetOf(field) {
+    if (!field)
+        return undefined;
+    return field
+        .referenceTarget;
+}
+/**
+ * Decode a raw meta bag (as returned by drizzle's JSON-mode column)
+ * into the plugin-typed shape RPC consumers expect. Unregistered keys
+ * pass through untouched — the row exists in the DB but the plugin
+ * that wrote it is no longer installed; we don't pretend to know its
+ * shape.
+ */
+export function decodeMetaBag(findField, raw) {
+    if (!raw)
+        return {};
+    const out = {};
+    for (const [key, value] of Object.entries(raw)) {
+        const field = findField(key);
+        out[key] = field ? coerceOnRead(field.type, value) : value;
+    }
+    return out;
+}
+export function isEmptyMetaPatch(patch) {
+    return (patch === null || (patch.upserts.size === 0 && patch.deletes.length === 0));
+}
+/**
+ * Merge a validated patch into the given `meta` JSON column for the
+ * row identified by `idColumn = id`. Uses SQLite `json_set` /
+ * `json_remove` so concurrent updaters touching disjoint keys don't
+ * clobber each other at the row level. Deletes nest inside sets so a
+ * caller clearing + re-setting the same key in one request behaves
+ * predictably.
+ */
+export async function applyMetaPatch(ctx, table, idColumn, id, patch) {
+    if (isEmptyMetaPatch(patch))
+        return;
+    let expr = sql `${table.meta}`;
+    if (patch.deletes.length > 0) {
+        const paths = patch.deletes.map((k) => sql `${metaJsonPath(k)}`);
+        expr = sql `json_remove(${expr}, ${sql.join(paths, sql `, `)})`;
+    }
+    if (patch.upserts.size > 0) {
+        const pairs = Array.from(patch.upserts, ([key, value]) => sql `${metaJsonPath(key)}, json(${JSON.stringify(value)})`);
+        expr = sql `json_set(${expr}, ${sql.join(pairs, sql `, `)})`;
+    }
+    await ctx.db
+        // drizzle's `update(table)` wants an `AnyTable` shape; our generic
+        // constraint only pins `meta`, so the update helper accepts any
+        // sqlite table via structural matching. Cast keeps the helper
+        // reusable across tables without widening the public types.
+        .update(table)
+        .set({ meta: expr })
+        .where(eq(idColumn, id));
+}
+/**
+ * Load + decode the full meta bag for a single row. Returns empty
+ * when the row is missing (deleted mid-flight) or has no saved meta.
+ */
+export async function loadMeta(ctx, table, idColumn, id, findField) {
+    const [row] = (await ctx.db
+        .select({ meta: table.meta })
+        .from(table)
+        .where(eq(idColumn, id)));
+    return decodeMetaBag(findField, row?.meta);
+}
+// --- internals below ---------------------------------------------------
+function coerceToType(type, key, value) {
+    switch (type) {
+        case "string":
+            return coerceString(key, value);
+        case "number":
+            return coerceNumber(key, value);
+        case "boolean":
+            return coerceBoolean(key, value);
+        case "json":
+            return coerceJson(key, value);
+    }
+}
+function coerceString(key, value) {
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "number" && Number.isFinite(value))
+        return String(value);
+    if (typeof value === "boolean")
+        return String(value);
+    throw MetaSanitizationError.invalidValue({ key });
+}
+function coerceNumber(key, value) {
+    if (typeof value === "number" && Number.isFinite(value))
+        return value;
+    if (typeof value === "string") {
+        // Empty string comes from cleared form inputs; the admin dispatcher
+        // already sends `null` for those, but a direct RPC caller might send
+        // "" — reject here so we don't silently coerce to 0 (`Number("") === 0`).
+        if (value.trim() === "") {
+            throw MetaSanitizationError.invalidValue({ key });
+        }
+        const parsed = Number(value);
+        if (Number.isFinite(parsed))
+            return parsed;
+    }
+    if (typeof value === "boolean")
+        return value ? 1 : 0;
+    throw MetaSanitizationError.invalidValue({ key });
+}
+function coerceBoolean(key, value) {
+    if (typeof value === "boolean")
+        return value;
+    if (value === 1 || value === "1" || value === "true")
+        return true;
+    if (value === 0 || value === "0" || value === "false")
+        return false;
+    throw MetaSanitizationError.invalidValue({ key });
+}
+function coerceJson(key, value) {
+    // json keys take anything round-trippable through JSON.stringify —
+    // we reject values that throw (BigInt) or silently drop (functions,
+    // Symbols) so reads don't hand back `undefined` for something a
+    // plugin thought it stored. TS types JSON.stringify as always-
+    // string, but at runtime it returns `undefined` for unserializable
+    // inputs — hence the cast.
+    try {
+        const encoded = JSON.stringify(value);
+        if (encoded === undefined) {
+            throw MetaSanitizationError.invalidValue({ key });
+        }
+        return JSON.parse(encoded);
+    }
+    catch {
+        throw MetaSanitizationError.invalidValue({ key });
+    }
+}
+function assertEncodedSize(key, value) {
+    const encoded = JSON.stringify(value);
+    if (encoded === undefined)
+        return; // already caught in coerceJson
+    const byteLength = new TextEncoder().encode(encoded).length;
+    if (byteLength > MAX_META_VALUE_BYTES) {
+        throw MetaSanitizationError.valueTooLarge({ key });
+    }
+}
+// Mirror the write-side accepted tokens instead of `Boolean(value)` — the
+// latter would flip `"false"` → `true`, silently inverting rows persisted
+// via `type: "json"` before a plugin tightened the field to `boolean`.
+const TRUTHY_BOOLEAN_TOKENS = new Set([1, "1", "true"]);
+const FALSY_BOOLEAN_TOKENS = new Set([0, "0", "false"]);
+function coerceBooleanOnRead(value) {
+    if (typeof value === "boolean")
+        return value;
+    if (TRUTHY_BOOLEAN_TOKENS.has(value))
+        return true;
+    if (FALSY_BOOLEAN_TOKENS.has(value))
+        return false;
+    return value;
+}
+function coerceOnRead(type, value) {
+    // Reads are forgiving — the row was validated on write but a
+    // schema change (e.g. a plugin flipping `number` → `string`)
+    // shouldn't 500 the editor. We coerce when we can and fall through
+    // to the raw value otherwise.
+    switch (type) {
+        case "string":
+            return typeof value === "string" ? value : String(value);
+        case "number":
+            return typeof value === "number" ? value : Number(value);
+        case "boolean":
+            return coerceBooleanOnRead(value);
+        case "json":
+            return value;
+    }
+}
+// SQLite's JSON path `$.label` only accepts `[A-Za-z0-9_]` in unquoted
+// labels, but valid meta keys may include `-` or `:` (see the input
+// schema regex). The double-quoted label form `$."foo-bar"` handles
+// them; the RPC input schema already rejects `"` and `\`, but belt-and-
+// braces matters here because non-RPC callers (tests, hook listeners,
+// future surfaces) could bypass that schema and trigger SQL injection
+// via a crafted path.
+function metaJsonPath(key) {
+    if (/["\\]/.test(key)) {
+        throw MetaReferenceError.metaKeyForbiddenChars(key);
+    }
+    return `$."${key}"`;
+}
+//# sourceMappingURL=core.js.map