hikoutei 0.6.0 → 0.7.0

package/dist/api/queryNormalization.js

@@ -0,0 +1,262 @@
+import { HIKOUTEI_ERROR_CODES, HikouteiError } from "./errors.js";
+import { HIKOUTEI_QUERY_OPERATORS, HIKOUTEI_SORT_DIRECTIONS, } from "./query.js";
+/** Normalizes a public collection query after validating descriptor-owned fields and values. */
+export function normalizeEntityQuery(descriptor, where, options) {
+    const normalizedOptions = normalizeFindOptions(options, true);
+    return {
+        tableName: descriptor.tableName,
+        primaryKeyColumn: descriptor.primaryKey,
+        predicate: normalizeFilter(descriptor, where),
+        orderBy: normalizeOrderBy(descriptor, normalizedOptions.orderBy, {
+            paged: normalizedOptions.limit !== undefined || normalizedOptions.offset !== undefined,
+        }),
+        ...(normalizedOptions.limit === undefined ? {} : { limit: normalizedOptions.limit }),
+        ...(normalizedOptions.offset === undefined ? {} : { offset: normalizedOptions.offset }),
+    };
+}
+/** Normalizes a public single-row query and applies an internal limit of one. */
+export function normalizeEntityFindOneQuery(descriptor, where, options) {
+    const normalizedOptions = normalizeFindOptions(options, false);
+    return {
+        tableName: descriptor.tableName,
+        primaryKeyColumn: descriptor.primaryKey,
+        predicate: normalizeFilter(descriptor, where),
+        orderBy: normalizeOrderBy(descriptor, normalizedOptions.orderBy, { paged: false }),
+        limit: 1,
+    };
+}
+function normalizeFindOptions(input, allowPaging) {
+    if (input === undefined) {
+        return { orderBy: undefined, limit: undefined, offset: undefined };
+    }
+    if (!isPlainRecord(input)) {
+        throwInvalidQuery("query options must be an object.");
+    }
+    const allowed = allowPaging
+        ? new Set(["orderBy", "limit", "offset"])
+        : new Set(["orderBy"]);
+    for (const key of Object.keys(input)) {
+        if (!allowed.has(key)) {
+            throwInvalidQuery(`query option "${key}" is not supported here.`);
+        }
+    }
+    const limit = input.limit;
+    const offset = input.offset;
+    requirePageValue(limit, "limit");
+    requirePageValue(offset, "offset");
+    return {
+        orderBy: input.orderBy,
+        limit: limit,
+        offset: offset,
+    };
+}
+function normalizeFilter(descriptor, input) {
+    if (!isPlainRecord(input)) {
+        throwInvalidQuery("query filter must be an object.");
+    }
+    const predicates = [];
+    for (const [field, rawCondition] of Object.entries(input)) {
+        const property = requireProperty(descriptor, field);
+        if (isOperatorObject(rawCondition)) {
+            predicates.push(...normalizeOperatorObject(descriptor, property, rawCondition));
+        }
+        else {
+            const value = requirePropertyValue(descriptor, property, rawCondition, { allowNull: true });
+            predicates.push(value === null
+                ? { kind: "null", field, operator: "is_null" }
+                : { kind: "comparison", field, operator: "eq", value });
+        }
+    }
+    return combineAll(predicates);
+}
+function normalizeOperatorObject(descriptor, property, input) {
+    const entries = Object.entries(input);
+    if (entries.length === 0) {
+        throwInvalidQuery(`filter operator object for "${property.name}" must not be empty.`);
+    }
+    const predicates = [];
+    for (const [operator, operand] of entries) {
+        if (!isQueryOperator(operator)) {
+            throwInvalidQuery(`filter "${property.name}" has unknown operator "${operator}".`);
+        }
+        if (!isOperatorAllowed(property.type, operator)) {
+            throwInvalidQuery(`operator "${operator}" is not valid for ${property.type} field "${property.name}".`);
+        }
+        if (operator === "in" || operator === "nin") {
+            predicates.push(normalizeSetPredicate(descriptor, property, operator, operand));
+            continue;
+        }
+        if (operator === "like") {
+            const value = requirePropertyValue(descriptor, property, operand, { allowNull: false });
+            if (typeof value !== "string") {
+                throwInvalidQuery(`operator "like" requires a string pattern for "${property.name}".`);
+            }
+            predicates.push({ kind: "like", field: property.name, pattern: value });
+            continue;
+        }
+        const allowNull = operator === "eq" || operator === "ne";
+        const value = requirePropertyValue(descriptor, property, operand, { allowNull });
+        if (value === null) {
+            predicates.push({
+                kind: "null",
+                field: property.name,
+                operator: operator === "eq" ? "is_null" : "is_not_null",
+            });
+        }
+        else if (operator === "ne" && property.nullable) {
+            predicates.push({
+                kind: "any",
+                predicates: [
+                    { kind: "null", field: property.name, operator: "is_null" },
+                    { kind: "comparison", field: property.name, operator, value },
+                ],
+            });
+        }
+        else {
+            predicates.push({ kind: "comparison", field: property.name, operator, value });
+        }
+    }
+    return predicates;
+}
+function normalizeSetPredicate(descriptor, property, operator, operand) {
+    if (!Array.isArray(operand)) {
+        throwInvalidQuery(`operator "${operator}" requires an array for "${property.name}".`);
+    }
+    if (operand.length === 0)
+        return { kind: "constant", value: operator === "nin" };
+    const values = [];
+    let containsNull = false;
+    for (const rawValue of [...operand]) {
+        const value = requirePropertyValue(descriptor, property, rawValue, { allowNull: true });
+        if (value === null)
+            containsNull = true;
+        else
+            values.push(value);
+    }
+    const setPredicate = values.length === 0
+        ? undefined
+        : { kind: "set", field: property.name, operator, values: [...values] };
+    if (!containsNull) {
+        if (operator === "nin" && property.nullable && setPredicate !== undefined) {
+            return {
+                kind: "any",
+                predicates: [
+                    { kind: "null", field: property.name, operator: "is_null" },
+                    setPredicate,
+                ],
+            };
+        }
+        return setPredicate ?? { kind: "constant", value: operator === "nin" };
+    }
+    const nullPredicate = {
+        kind: "null",
+        field: property.name,
+        operator: operator === "in" ? "is_null" : "is_not_null",
+    };
+    if (setPredicate === undefined)
+        return nullPredicate;
+    return operator === "in"
+        ? { kind: "any", predicates: [nullPredicate, setPredicate] }
+        : { kind: "all", predicates: [nullPredicate, setPredicate] };
+}
+function normalizeOrderBy(descriptor, input, options) {
+    if (input === undefined) {
+        return options.paged
+            ? [{ field: descriptor.primaryKey, direction: HIKOUTEI_SORT_DIRECTIONS.ASC }]
+            : [];
+    }
+    if (!isPlainRecord(input))
+        throwInvalidQuery("orderBy must be an object.");
+    const entries = Object.entries(input);
+    if (entries.length === 0)
+        throwInvalidQuery("orderBy must not be empty.");
+    const orderBy = [];
+    for (const [field, direction] of entries) {
+        requireProperty(descriptor, field);
+        if (!isSortDirection(direction)) {
+            throwInvalidQuery(`orderBy direction for "${field}" must be "asc" or "desc".`);
+        }
+        orderBy.push({ field, direction });
+    }
+    if (!orderBy.some((order) => order.field === descriptor.primaryKey)) {
+        orderBy.push({ field: descriptor.primaryKey, direction: HIKOUTEI_SORT_DIRECTIONS.ASC });
+    }
+    return orderBy;
+}
+function combineAll(predicates) {
+    if (predicates.length === 0)
+        return { kind: "constant", value: true };
+    if (predicates.length === 1)
+        return predicates[0];
+    return { kind: "all", predicates: [...predicates] };
+}
+function requireProperty(descriptor, field) {
+    const property = descriptor.properties.find((candidate) => candidate.name === field);
+    if (property === undefined) {
+        throw new HikouteiError(HIKOUTEI_ERROR_CODES.INVALID_SCALAR_VALUE, `"${field}" is not a declared property of entity "${descriptor.name}".`);
+    }
+    return property;
+}
+function requirePropertyValue(descriptor, property, value, options) {
+    if (value === undefined) {
+        throw new HikouteiError(HIKOUTEI_ERROR_CODES.INVALID_SCALAR_VALUE, `filter "${property.name}" must not be undefined in entity "${descriptor.name}".`);
+    }
+    if (value === null) {
+        if (options.allowNull && property.nullable)
+            return null;
+        throw new HikouteiError(HIKOUTEI_ERROR_CODES.INVALID_SCALAR_VALUE, `filter "${property.name}" cannot be null in this query for entity "${descriptor.name}".`);
+    }
+    switch (property.type) {
+        case "date":
+            if (value instanceof Date && Number.isFinite(value.getTime()))
+                return new Date(value.getTime());
+            break;
+        case "string":
+            if (typeof value === "string")
+                return value;
+            break;
+        case "number":
+            if (typeof value === "number" && Number.isFinite(value))
+                return value;
+            break;
+        case "boolean":
+            if (typeof value === "boolean")
+                return value;
+            break;
+    }
+    throw new HikouteiError(HIKOUTEI_ERROR_CODES.INVALID_SCALAR_VALUE, `filter "${property.name}" expected ${property.type} in entity "${descriptor.name}".`);
+}
+function isOperatorAllowed(type, operator) {
+    if (operator === "eq" || operator === "ne" || operator === "in" || operator === "nin") {
+        return true;
+    }
+    if (operator === "like")
+        return type === "string";
+    return type === "string" || type === "number" || type === "date";
+}
+function isQueryOperator(value) {
+    return Object.values(HIKOUTEI_QUERY_OPERATORS).some((operator) => operator === value);
+}
+function isSortDirection(value) {
+    return value === HIKOUTEI_SORT_DIRECTIONS.ASC || value === HIKOUTEI_SORT_DIRECTIONS.DESC;
+}
+function isOperatorObject(value) {
+    return isPlainRecord(value) && !(value instanceof Date);
+}
+function isPlainRecord(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function requirePageValue(value, label) {
+    if (value === undefined)
+        return;
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
+        throw new HikouteiError(HIKOUTEI_ERROR_CODES.INVALID_SCALAR_VALUE, `${label} must be a non-negative safe integer.`);
+    }
+}
+function throwInvalidQuery(message) {
+    throw new HikouteiError(HIKOUTEI_ERROR_CODES.INVALID_QUERY, message);
+}
+//# sourceMappingURL=queryNormalization.js.map

package/dist/api/queryNormalization.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queryNormalization.js","sourceRoot":"","sources":["../../src/api/queryNormalization.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,oBAAoB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAClE,OAAO,EACL,wBAAwB,EACxB,wBAAwB,GAEzB,MAAM,YAAY,CAAC;AAQpB,gGAAgG;AAChG,MAAM,UAAU,oBAAoB,CAClC,UAA4C,EAC5C,KAAc,EACd,OAAgB;IAEhB,MAAM,iBAAiB,GAAG,oBAAoB,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IAC9D,OAAO;QACL,SAAS,EAAE,UAAU,CAAC,SAAS;QAC/B,gBAAgB,EAAE,UAAU,CAAC,UAAU;QACvC,SAAS,EAAE,eAAe,CAAC,UAAU,EAAE,KAAK,CAAC;QAC7C,OAAO,EAAE,gBAAgB,CAAC,UAAU,EAAE,iBAAiB,CAAC,OAAO,EAAE;YAC/D,KAAK,EAAE,iBAAiB,CAAC,KAAK,KAAK,SAAS,IAAI,iBAAiB,CAAC,MAAM,KAAK,SAAS;SACvF,CAAC;QACF,GAAG,CAAC,iBAAiB,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,iBAAiB,CAAC,KAAK,EAAE,CAAC;QACpF,GAAG,CAAC,iBAAiB,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,iBAAiB,CAAC,MAAM,EAAE,CAAC;KACxF,CAAC;AACJ,CAAC;AAED,iFAAiF;AACjF,MAAM,UAAU,2BAA2B,CACzC,UAA4C,EAC5C,KAAc,EACd,OAAgB;IAEhB,MAAM,iBAAiB,GAAG,oBAAoB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IAC/D,OAAO;QACL,SAAS,EAAE,UAAU,CAAC,SAAS;QAC/B,gBAAgB,EAAE,UAAU,CAAC,UAAU;QACvC,SAAS,EAAE,eAAe,CAAC,UAAU,EAAE,KAAK,CAAC;QAC7C,OAAO,EAAE,gBAAgB,CAAC,UAAU,EAAE,iBAAiB,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;QAClF,KAAK,EAAE,CAAC;KACT,CAAC;AACJ,CAAC;AAQD,SAAS,oBAAoB,CAAC,KAAc,EAAE,WAAoB;IAChE,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;IACrE,CAAC;IACD,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1B,iBAAiB,CAAC,kCAAkC,CAAC,CAAC;IACxD,CAAC;IACD,MAAM,OAAO,GAAG,WAAW;QACzB,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,SAAS,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC;QACzC,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC;IACzB,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACrC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YACtB,iBAAiB,CAAC,iBAAiB,GAAG,0BAA0B,CAAC,CAAC;QACpE,CAAC;IACH,CAAC;IACD,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC;IAC1B,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;IAC5B,gBAAgB,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IACjC,gBAAgB,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IACnC,OAAO;QACL,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,KAAK,EAAE,KAA2B;QAClC,MAAM,EAAE,MAA4B;KACrC,CAAC;AACJ,CAAC;AAED,SAAS,eAAe,CACtB,UAA4C,EAC5C,KAAc;IAEd,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1B,iBAAiB,CAAC,iCAAiC,CAAC,CAAC;IACvD,CAAC;IACD,MAAM,UAAU,GAA4B,EAAE,CAAC;IAC/C,KAAK,MAAM,CAAC,KAAK,EAAE,YAAY,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1D,MAAM,QAAQ,GAAG,eAAe,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;QACpD,IAAI,gBAAgB,CAAC,YAAY,CAAC,EAAE,CAAC;YACnC,UAAU,CAAC,IAAI,CAAC,GAAG,uBAAuB,CAAC,UAAU,EAAE,QAAQ,EAAE,YAAY,CAAC,CAAC,CAAC;QAClF,CAAC;aAAM,CAAC;YACN,MAAM,KAAK,GAAG,oBAAoB,CAAC,UAAU,EAAE,QAAQ,EAAE,YAAY,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YAC5F,UAAU,CAAC,IAAI,CAAC,KAAK,KAAK,IAAI;gBAC5B,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE;gBAC9C,CAAC,CAAC,EAAE,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;QAC5D,CAAC;IACH,CAAC;IACD,OAAO,UAAU,CAAC,UAAU,CAAC,CAAC;AAChC,CAAC;AAED,SAAS,uBAAuB,CAC9B,UAA4C,EAC5C,QAAgE,EAChE,KAAwC;IAExC,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IACtC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,iBAAiB,CAAC,+BAA+B,QAAQ,CAAC,IAAI,sBAAsB,CAAC,CAAC;IACxF,CAAC;IACD,MAAM,UAAU,GAA4B,EAAE,CAAC;IAC/C,KAAK,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,IAAI,OAAO,EAAE,CAAC;QAC1C,IAAI,CAAC,eAAe,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC/B,iBAAiB,CAAC,WAAW,QAAQ,CAAC,IAAI,2BAA2B,QAAQ,IAAI,CAAC,CAAC;QACrF,CAAC;QACD,IAAI,CAAC,iBAAiB,CAAC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,EAAE,CAAC;YAChD,iBAAiB,CACf,aAAa,QAAQ,sBAAsB,QAAQ,CAAC,IAAI,WAAW,QAAQ,CAAC,IAAI,IAAI,CACrF,CAAC;QACJ,CAAC;QACD,IAAI,QAAQ,KAAK,IAAI,IAAI,QAAQ,KAAK,KAAK,EAAE,CAAC;YAC5C,UAAU,CAAC,IAAI,CAAC,qBAAqB,CAAC,UAAU,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC;YAChF,SAAS;QACX,CAAC;QACD,IAAI,QAAQ,KAAK,MAAM,EAAE,CAAC;YACxB,MAAM,KAAK,GAAG,oBAAoB,CAAC,UAAU,EAAE,QAAQ,EAAE,OAAO,EAAE,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,CAAC;YACxF,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;gBAC9B,iBAAiB,CAAC,kDAAkD,QAAQ,CAAC,IAAI,IAAI,CAAC,CAAC;YACzF,CAAC;YACD,UAAU,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;YACxE,SAAS;QACX,CAAC;QACD,MAAM,SAAS,GAAG,QAAQ,KAAK,IAAI,IAAI,QAAQ,KAAK,IAAI,CAAC;QACzD,MAAM,KAAK,GAAG,oBAAoB,CAAC,UAAU,EAAE,QAAQ,EAAE,OAAO,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC;QACjF,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;YACnB,UAAU,CAAC,IAAI,CAAC;gBACd,IAAI,EAAE,MAAM;gBACZ,KAAK,EAAE,QAAQ,CAAC,IAAI;gBACpB,QAAQ,EAAE,QAAQ,KAAK,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,aAAa;aACxD,CAAC,CAAC;QACL,CAAC;aAAM,IAAI,QAAQ,KAAK,IAAI,IAAI,QAAQ,CAAC,QAAQ,EAAE,CAAC;YAClD,UAAU,CAAC,IAAI,CAAC;gBACd,IAAI,EAAE,KAAK;gBACX,UAAU,EAAE;oBACV,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE;oBAC3D,EAAE,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE;iBAC9D;aACF,CAAC,CAAC;QACL,CAAC;aAAM,CAAC;YACN,UAAU,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAC;QACjF,CAAC;IACH,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,SAAS,qBAAqB,CAC5B,UAA4C,EAC5C,QAAgE,EAChE,QAAsB,EACtB,OAAgB;IAEhB,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QAC5B,iBAAiB,CAAC,aAAa,QAAQ,4BAA4B,QAAQ,CAAC,IAAI,IAAI,CAAC,CAAC;IACxF,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,QAAQ,KAAK,KAAK,EAAE,CAAC;IAEjF,MAAM,MAAM,GAA4C,EAAE,CAAC;IAC3D,IAAI,YAAY,GAAG,KAAK,CAAC;IACzB,KAAK,MAAM,QAAQ,IAAI,CAAC,GAAG,OAAO,CAAC,EAAE,CAAC;QACpC,MAAM,KAAK,GAAG,oBAAoB,CAAC,UAAU,EAAE,QAAQ,EAAE,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACxF,IAAI,KAAK,KAAK,IAAI;YAAE,YAAY,GAAG,IAAI,CAAC;;YACnC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC1B,CAAC;IACD,MAAM,YAAY,GAAsC,MAAM,CAAC,MAAM,KAAK,CAAC;QACzE,CAAC,CAAC,SAAS;QACX,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,GAAG,MAAM,CAAC,EAAE,CAAC;IACzE,IAAI,CAAC,YAAY,EAAE,CAAC;QAClB,IAAI,QAAQ,KAAK,KAAK,IAAI,QAAQ,CAAC,QAAQ,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;YAC1E,OAAO;gBACL,IAAI,EAAE,KAAK;gBACX,UAAU,EAAE;oBACV,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE;oBAC3D,YAAY;iBACb;aACF,CAAC;QACJ,CAAC;QACD,OAAO,YAAY,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,QAAQ,KAAK,KAAK,EAAE,CAAC;IACzE,CAAC;IAED,MAAM,aAAa,GAA0B;QAC3C,IAAI,EAAE,MAAM;QACZ,KAAK,EAAE,QAAQ,CAAC,IAAI;QACpB,QAAQ,EAAE,QAAQ,KAAK,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,aAAa;KACxD,CAAC;IACF,IAAI,YAAY,KAAK,SAAS;QAAE,OAAO,aAAa,CAAC;IACrD,OAAO,QAAQ,KAAK,IAAI;QACtB,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC,aAAa,EAAE,YAAY,CAAC,EAAE;QAC5D,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC,aAAa,EAAE,YAAY,CAAC,EAAE,CAAC;AACjE,CAAC;AAED,SAAS,gBAAgB,CACvB,UAA4C,EAC5C,KAAc,EACd,OAAoC;IAEpC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,OAAO,OAAO,CAAC,KAAK;YAClB,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,UAAU,CAAC,UAAU,EAAE,SAAS,EAAE,wBAAwB,CAAC,GAAG,EAAE,CAAC;YAC7E,CAAC,CAAC,EAAE,CAAC;IACT,CAAC;IACD,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC;QAAE,iBAAiB,CAAC,4BAA4B,CAAC,CAAC;IAC3E,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IACtC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,iBAAiB,CAAC,4BAA4B,CAAC,CAAC;IAE1E,MAAM,OAAO,GAAwB,EAAE,CAAC;IACxC,KAAK,MAAM,CAAC,KAAK,EAAE,SAAS,CAAC,IAAI,OAAO,EAAE,CAAC;QACzC,eAAe,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;QACnC,IAAI,CAAC,eAAe,CAAC,SAAS,CAAC,EAAE,CAAC;YAChC,iBAAiB,CAAC,0BAA0B,KAAK,4BAA4B,CAAC,CAAC;QACjF,CAAC;QACD,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;IACrC,CAAC;IACD,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,KAAK,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;QACpE,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,UAAU,CAAC,UAAU,EAAE,SAAS,EAAE,wBAAwB,CAAC,GAAG,EAAE,CAAC,CAAC;IAC1F,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,SAAS,UAAU,CAAC,UAA4C;IAC9D,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IACtE,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,UAAU,CAAC,CAAC,CAA0B,CAAC;IAC3E,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC,GAAG,UAAU,CAAC,EAAE,CAAC;AACtD,CAAC;AAED,SAAS,eAAe,CACtB,UAA4C,EAC5C,KAAa;IAEb,MAAM,QAAQ,GAAG,UAAU,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,IAAI,KAAK,KAAK,CAAC,CAAC;IACrF,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,MAAM,IAAI,aAAa,CACrB,oBAAoB,CAAC,oBAAoB,EACzC,IAAI,KAAK,2CAA2C,UAAU,CAAC,IAAI,IAAI,CACxE,CAAC;IACJ,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,SAAS,oBAAoB,CAC3B,UAA4C,EAC5C,QAAgE,EAChE,KAAc,EACd,OAAwC;IAExC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,MAAM,IAAI,aAAa,CACrB,oBAAoB,CAAC,oBAAoB,EACzC,WAAW,QAAQ,CAAC,IAAI,sCAAsC,UAAU,CAAC,IAAI,IAAI,CAClF,CAAC;IACJ,CAAC;IACD,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QACnB,IAAI,OAAO,CAAC,SAAS,IAAI,QAAQ,CAAC,QAAQ;YAAE,OAAO,IAAI,CAAC;QACxD,MAAM,IAAI,aAAa,CACrB,oBAAoB,CAAC,oBAAoB,EACzC,WAAW,QAAQ,CAAC,IAAI,8CAA8C,UAAU,CAAC,IAAI,IAAI,CAC1F,CAAC;IACJ,CAAC;IACD,QAAQ,QAAQ,CAAC,IAAI,EAAE,CAAC;QACtB,KAAK,MAAM;YACT,IAAI,KAAK,YAAY,IAAI,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC;gBAAE,OAAO,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;YAChG,MAAM;QACR,KAAK,QAAQ;YACX,IAAI,OAAO,KAAK,KAAK,QAAQ;gBAAE,OAAO,KAAK,CAAC;YAC5C,MAAM;QACR,KAAK,QAAQ;YACX,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;gBAAE,OAAO,KAAK,CAAC;YACtE,MAAM;QACR,KAAK,SAAS;YACZ,IAAI,OAAO,KAAK,KAAK,SAAS;gBAAE,OAAO,KAAK,CAAC;YAC7C,MAAM;IACV,CAAC;IACD,MAAM,IAAI,aAAa,CACrB,oBAAoB,CAAC,oBAAoB,EACzC,WAAW,QAAQ,CAAC,IAAI,cAAc,QAAQ,CAAC,IAAI,eAAe,UAAU,CAAC,IAAI,IAAI,CACtF,CAAC;AACJ,CAAC;AAED,SAAS,iBAAiB,CACxB,IAAoE,EACpE,QAAuB;IAEvB,IAAI,QAAQ,KAAK,IAAI,IAAI,QAAQ,KAAK,IAAI,IAAI,QAAQ,KAAK,IAAI,IAAI,QAAQ,KAAK,KAAK,EAAE,CAAC;QACtF,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,QAAQ,KAAK,MAAM;QAAE,OAAO,IAAI,KAAK,QAAQ,CAAC;IAClD,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,MAAM,CAAC;AACnE,CAAC;AAKD,SAAS,eAAe,CAAC,KAAa;IACpC,OAAO,MAAM,CAAC,MAAM,CAAC,wBAAwB,CAAC,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,KAAK,KAAK,CAAC,CAAC;AACxF,CAAC;AAED,SAAS,eAAe,CAAC,KAAc;IACrC,OAAO,KAAK,KAAK,wBAAwB,CAAC,GAAG,IAAI,KAAK,KAAK,wBAAwB,CAAC,IAAI,CAAC;AAC3F,CAAC;AAED,SAAS,gBAAgB,CAAC,KAAc;IACtC,OAAO,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,KAAK,YAAY,IAAI,CAAC,CAAC;AAC1D,CAAC;AAED,SAAS,aAAa,CAAC,KAAc;IACnC,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACtF,MAAM,SAAS,GAAG,MAAM,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;IAC/C,OAAO,SAAS,KAAK,MAAM,CAAC,SAAS,IAAI,SAAS,KAAK,IAAI,CAAC;AAC9D,CAAC;AAED,SAAS,gBAAgB,CAAC,KAAc,EAAE,KAAa;IACrD,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO;IAChC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;QAC3E,MAAM,IAAI,aAAa,CACrB,oBAAoB,CAAC,oBAAoB,EACzC,GAAG,KAAK,uCAAuC,CAChD,CAAC;IACJ,CAAC;AACH,CAAC;AAED,SAAS,iBAAiB,CAAC,OAAe;IACxC,MAAM,IAAI,aAAa,CAAC,oBAAoB,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC;AACvE,CAAC"}

package/dist/internal/syncStatus.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Read-only observability over the local SQLite authority for first-party
+ * tooling (the `hikoutei-mcp` server).
+ *
+ * This module is deliberately NOT part of the public application contract:
+ * it is exposed only through the unstable `hikoutei/internal/sync-status`
+ * subpath so the MCP layer can report outbox delivery state and unresolved
+ * conflicts without widening `src/index.ts`. It opens its own read-only
+ * `node:sqlite` connection and never mutates the database, so it coexists
+ * with a running sync worker (the WAL lets multiple readers share the file).
+ *
+ * Failure model: malformed arguments raise a structured
+ * {@link HikouteiSyncStatusError}; a database file that does not exist yet or
+ * a database without sync tables (local-only mode) is not an error — it maps
+ * to `{ mode: "local" }` and an empty conflict list respectively.
+ */
+import { CONFLICT_STATUSES } from "../domain/model/constants.js";
+/** Stable machine-readable codes raised by the internal status reader. */
+export declare const HIKOUTEI_SYNC_STATUS_ERROR_CODES: {
+    /** The dbName argument is not a non-empty string. */
+    readonly INVALID_DB_NAME: "invalid_db_name";
+    /** The SQLite file exists but could not be opened read-only. */
+    readonly OPEN_FAILED: "open_failed";
+    /** A status query failed against an unexpected storage state. */
+    readonly READ_FAILED: "read_failed";
+};
+/** Closed set of internal status-reader error codes. */
+export type HikouteiSyncStatusErrorCode = (typeof HIKOUTEI_SYNC_STATUS_ERROR_CODES)[keyof typeof HIKOUTEI_SYNC_STATUS_ERROR_CODES];
+/** Structured error raised by this module; never part of the public API. */
+export declare class HikouteiSyncStatusError extends Error {
+    readonly code: HikouteiSyncStatusErrorCode;
+    constructor(code: HikouteiSyncStatusErrorCode, message: string, cause?: unknown);
+}
+/** Plain scalar value extracted from a stored normalized cell. */
+export type HikouteiStoredValue = string | number | boolean | null;
+/** Unresolved conflict lifecycle states surfaced by `listHikouteiConflicts`. */
+export type HikouteiOpenConflictStatus = (typeof CONFLICT_STATUSES)["OPEN"] | (typeof CONFLICT_STATUSES)["NEEDS_REBASE"];
+/** Delivery-focused counts over the durable Sheet effect outbox. */
+export interface HikouteiSyncEffectCounts {
+    readonly pending: number;
+    readonly processing: number;
+    readonly deliveryUncertain: number;
+    readonly failed: number;
+}
+/** Unresolved conflict counts. */
+export interface HikouteiSyncConflictCounts {
+    readonly open: number;
+    readonly needsRebase: number;
+}
+/**
+ * Sync observability snapshot.
+ *
+ * - `{ mode: "local" }`: no sync tables exist (local-only runtime, or the
+ *   database file has not been created yet).
+ * - `{ mode: "sync" }`: sync state exists; `spreadsheetId` is the bound
+ *   spreadsheet's ID (full URLs are never returned) or `null` when the
+ *   authority row has not been written yet.
+ */
+export type HikouteiSyncStatus = {
+    readonly mode: "local";
+} | {
+    readonly mode: "sync";
+    readonly spreadsheetId: string | null;
+    readonly effects: HikouteiSyncEffectCounts;
+    readonly conflicts: HikouteiSyncConflictCounts;
+};
+/** One unresolved human-edit conflict, values decoded to plain scalars. */
+export interface HikouteiConflictSummary {
+    readonly conflictId: string;
+    readonly entityId: string;
+    readonly fieldName: string;
+    readonly userValue: HikouteiStoredValue;
+    readonly currentCanonicalValue: HikouteiStoredValue;
+    readonly userBaseRevision: number;
+    readonly currentCanonicalRevision: number;
+    readonly candidateEpoch: number;
+    readonly status: HikouteiOpenConflictStatus;
+    readonly updatedAt: number;
+}
+/** Options accepted by the read-only status queries. */
+export interface HikouteiSyncStatusOptions {
+    /** SQLite database path, URI, or `:memory:` used by the runtime. */
+    readonly dbName: string;
+}
+/** Options accepted by `listHikouteiConflicts`. */
+export interface HikouteiConflictListOptions extends HikouteiSyncStatusOptions {
+    /** Maximum number of conflicts to return; default 50, capped at 500. */
+    readonly limit?: number;
+}
+/** Default conflict page size when `limit` is omitted. */
+export declare const DEFAULT_CONFLICT_LIST_LIMIT = 50;
+/** Hard upper bound for one conflict page; protects caller context windows. */
+export declare const MAX_CONFLICT_LIST_LIMIT = 500;
+/**
+ * Reads a delivery/conflict snapshot from the SQLite authority.
+ *
+ * Returns `{ mode: "local" }` when the database file does not exist yet or
+ * was created by a local-only runtime (no sync tables). Never writes, never
+ * opens the network, and never returns spreadsheet URLs — only the ID.
+ */
+export declare function readHikouteiSyncStatus(options: HikouteiSyncStatusOptions): Promise<HikouteiSyncStatus>;
+/**
+ * Lists unresolved (OPEN / NEEDS_REBASE) conflicts, newest first.
+ *
+ * Stored cell values are decoded from normalized cells into plain scalars;
+ * a value that fails decoding falls back to its raw stored text so a corrupt
+ * row can still be inspected instead of failing the whole listing. Returns
+ * an empty list for local-only databases.
+ */
+export declare function listHikouteiConflicts(options: HikouteiConflictListOptions): Promise<readonly HikouteiConflictSummary[]>;
+//# sourceMappingURL=syncStatus.d.ts.map

package/dist/internal/syncStatus.d.ts.map

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

package/dist/internal/syncStatus.js

@@ -0,0 +1,265 @@
+/**
+ * Read-only observability over the local SQLite authority for first-party
+ * tooling (the `hikoutei-mcp` server).
+ *
+ * This module is deliberately NOT part of the public application contract:
+ * it is exposed only through the unstable `hikoutei/internal/sync-status`
+ * subpath so the MCP layer can report outbox delivery state and unresolved
+ * conflicts without widening `src/index.ts`. It opens its own read-only
+ * `node:sqlite` connection and never mutates the database, so it coexists
+ * with a running sync worker (the WAL lets multiple readers share the file).
+ *
+ * Failure model: malformed arguments raise a structured
+ * {@link HikouteiSyncStatusError}; a database file that does not exist yet or
+ * a database without sync tables (local-only mode) is not an error — it maps
+ * to `{ mode: "local" }` and an empty conflict list respectively.
+ */
+import { existsSync } from "node:fs";
+import { EFFECT_STATUSES } from "@hikoutei/ikisaki";
+import { CONFLICT_STATUSES } from "../domain/model/constants.js";
+import { isNormalizedCell } from "../shared/encoding/index.js";
+/** Stable machine-readable codes raised by the internal status reader. */
+export const HIKOUTEI_SYNC_STATUS_ERROR_CODES = {
+    /** The dbName argument is not a non-empty string. */
+    INVALID_DB_NAME: "invalid_db_name",
+    /** The SQLite file exists but could not be opened read-only. */
+    OPEN_FAILED: "open_failed",
+    /** A status query failed against an unexpected storage state. */
+    READ_FAILED: "read_failed",
+};
+/** Structured error raised by this module; never part of the public API. */
+export class HikouteiSyncStatusError extends Error {
+    code;
+    constructor(code, message, cause) {
+        super(message);
+        this.name = "HikouteiSyncStatusError";
+        this.code = code;
+        if (cause !== undefined) {
+            // `Error.cause` (ES2022) carries the underlying storage failure for
+            // diagnostics; optional parameter properties cannot use `override`.
+            this.cause = cause;
+        }
+    }
+}
+/** Default conflict page size when `limit` is omitted. */
+export const DEFAULT_CONFLICT_LIST_LIMIT = 50;
+/** Hard upper bound for one conflict page; protects caller context windows. */
+export const MAX_CONFLICT_LIST_LIMIT = 500;
+/** In-memory SQLite marker; read-only observability cannot cross connections. */
+const MEMORY_DB_NAME = ":memory:";
+/**
+ * Reads a delivery/conflict snapshot from the SQLite authority.
+ *
+ * Returns `{ mode: "local" }` when the database file does not exist yet or
+ * was created by a local-only runtime (no sync tables). Never writes, never
+ * opens the network, and never returns spreadsheet URLs — only the ID.
+ */
+export async function readHikouteiSyncStatus(options) {
+    const dbName = requireValidDbName(options);
+    if (isMemoryDb(dbName) || !existsSync(dbName)) {
+        return { mode: "local" };
+    }
+    return withReadOnlyConnection(dbName, (database) => {
+        if (!syncTablesExist(database))
+            return { mode: "local" };
+        return {
+            mode: "sync",
+            spreadsheetId: readSpreadsheetId(database),
+            effects: readEffectCounts(database),
+            conflicts: readConflictCounts(database),
+        };
+    });
+}
+/**
+ * Lists unresolved (OPEN / NEEDS_REBASE) conflicts, newest first.
+ *
+ * Stored cell values are decoded from normalized cells into plain scalars;
+ * a value that fails decoding falls back to its raw stored text so a corrupt
+ * row can still be inspected instead of failing the whole listing. Returns
+ * an empty list for local-only databases.
+ */
+export async function listHikouteiConflicts(options) {
+    const dbName = requireValidDbName(options);
+    // Input validation runs before the existence check so malformed arguments
+    // always reject, independent of database state.
+    const limit = resolveLimit(options.limit);
+    if (isMemoryDb(dbName) || !existsSync(dbName)) {
+        return [];
+    }
+    return withReadOnlyConnection(dbName, (database) => {
+        if (!tableExists(database, "sync_conflict"))
+            return [];
+        const rows = database
+            .prepare(`SELECT conflict_id, entity_id, field_name, user_value, current_canonical_value,
+                user_base_revision, current_canonical_revision, candidate_epoch, status, updated_at
+           FROM sync_conflict
+          WHERE status IN (?, ?)
+          ORDER BY updated_at DESC
+          LIMIT ?`)
+            .all(CONFLICT_STATUSES.OPEN, CONFLICT_STATUSES.NEEDS_REBASE, limit);
+        return rows.map(toConflictSummary);
+    });
+}
+/** Validates the options object and returns the non-empty dbName. */
+function requireValidDbName(options) {
+    if (options === null || typeof options !== "object") {
+        throw new HikouteiSyncStatusError(HIKOUTEI_SYNC_STATUS_ERROR_CODES.INVALID_DB_NAME, "sync-status options must be an object with a dbName string.");
+    }
+    const dbName = options.dbName;
+    if (typeof dbName !== "string" || dbName.trim() === "") {
+        throw new HikouteiSyncStatusError(HIKOUTEI_SYNC_STATUS_ERROR_CODES.INVALID_DB_NAME, "sync-status dbName must be a non-empty string.");
+    }
+    return dbName;
+}
+/** Clamps and validates the conflict page size. */
+function resolveLimit(limit) {
+    if (limit === undefined)
+        return DEFAULT_CONFLICT_LIST_LIMIT;
+    if (!Number.isInteger(limit) || limit < 1) {
+        throw new HikouteiSyncStatusError(HIKOUTEI_SYNC_STATUS_ERROR_CODES.READ_FAILED, "sync-status limit must be a positive integer.");
+    }
+    return Math.min(limit, MAX_CONFLICT_LIST_LIMIT);
+}
+/** True when the path names an in-memory database. */
+function isMemoryDb(dbName) {
+    return dbName === MEMORY_DB_NAME || dbName.startsWith("file::memory:");
+}
+/**
+ * Loads the `node:sqlite` built-in without a module specifier.
+ *
+ * `process.getBuiltinModule` (Node 22.3+) keeps bundlers and test runners
+ * from trying to resolve `node:sqlite` as a package; the same approach is
+ * used by MikroORM's NodeSqliteDialect. Returns null when the runtime
+ * lacks the built-in.
+ */
+function loadNodeSqlite() {
+    const candidate = process.getBuiltinModule;
+    if (typeof candidate !== "function")
+        return null;
+    const module = candidate.call(process, "node:sqlite");
+    return module ?? null;
+}
+/**
+ * Opens a read-only connection, runs the callback, and always closes it.
+ *
+ * A second connection to the same file is safe because it never writes;
+ * open failures are classified as `open_failed` instead of surfacing the
+ * raw node:sqlite error.
+ */
+function withReadOnlyConnection(dbName, read) {
+    const nodeSqlite = loadNodeSqlite();
+    if (nodeSqlite === null) {
+        throw new HikouteiSyncStatusError(HIKOUTEI_SYNC_STATUS_ERROR_CODES.OPEN_FAILED, "this Node runtime does not provide the node:sqlite built-in (Node 22.5+ required)");
+    }
+    let database;
+    try {
+        database = new nodeSqlite.DatabaseSync(dbName, { readOnly: true });
+    }
+    catch (error) {
+        throw new HikouteiSyncStatusError(HIKOUTEI_SYNC_STATUS_ERROR_CODES.OPEN_FAILED, `could not open ${dbName} read-only: ${messageOf(error)}`, error);
+    }
+    try {
+        return read(database);
+    }
+    catch (error) {
+        if (error instanceof HikouteiSyncStatusError)
+            throw error;
+        throw new HikouteiSyncStatusError(HIKOUTEI_SYNC_STATUS_ERROR_CODES.READ_FAILED, `status query failed on ${dbName}: ${messageOf(error)}`, error);
+    }
+    finally {
+        database.close();
+    }
+}
+/** True when the durable sync tables are present in this database. */
+function syncTablesExist(database) {
+    return tableExists(database, "sheet_effect_outbox");
+}
+/** Checks sqlite_master for one table name. */
+function tableExists(database, tableName) {
+    const row = database
+        .prepare("SELECT 1 AS present FROM sqlite_master WHERE type = 'table' AND name = ?")
+        .get(tableName);
+    return row !== undefined;
+}
+/** Reads the bound spreadsheet ID, or null when no registry row exists yet. */
+function readSpreadsheetId(database) {
+    // Provisioning registers physical sheets eagerly, so the registry knows
+    // the bound spreadsheet even before the writer claims an authority row.
+    const registryRow = database
+        .prepare("SELECT spreadsheet_id FROM physical_sheet_registry LIMIT 1")
+        .get();
+    if (registryRow !== undefined)
+        return registryRow.spreadsheet_id;
+    const authorityRow = database
+        .prepare("SELECT spreadsheet_id FROM spreadsheet_authority LIMIT 1")
+        .get();
+    return authorityRow === undefined ? null : authorityRow.spreadsheet_id;
+}
+/** Counts outbox effects by the delivery-relevant statuses. */
+function readEffectCounts(database) {
+    const rows = database
+        .prepare("SELECT status, COUNT(*) AS count FROM sheet_effect_outbox GROUP BY status")
+        .all();
+    const byStatus = new Map(rows.map((row) => [row.status, row.count]));
+    return {
+        pending: byStatus.get(EFFECT_STATUSES.PENDING) ?? 0,
+        processing: byStatus.get(EFFECT_STATUSES.PROCESSING) ?? 0,
+        deliveryUncertain: byStatus.get(EFFECT_STATUSES.DELIVERY_UNCERTAIN) ?? 0,
+        failed: byStatus.get(EFFECT_STATUSES.FAILED) ?? 0,
+    };
+}
+/** Counts unresolved conflicts by status. */
+function readConflictCounts(database) {
+    const rows = database
+        .prepare("SELECT status, COUNT(*) AS count FROM sync_conflict WHERE status IN (?, ?) GROUP BY status")
+        .all(CONFLICT_STATUSES.OPEN, CONFLICT_STATUSES.NEEDS_REBASE);
+    const byStatus = new Map(rows.map((row) => [row.status, row.count]));
+    return {
+        open: byStatus.get(CONFLICT_STATUSES.OPEN) ?? 0,
+        needsRebase: byStatus.get(CONFLICT_STATUSES.NEEDS_REBASE) ?? 0,
+    };
+}
+/** Maps one raw conflict row to the summary contract, decoding stored cells. */
+function toConflictSummary(row) {
+    const status = row.status === CONFLICT_STATUSES.NEEDS_REBASE
+        ? CONFLICT_STATUSES.NEEDS_REBASE
+        : CONFLICT_STATUSES.OPEN;
+    return {
+        conflictId: String(row.conflict_id),
+        entityId: String(row.entity_id),
+        fieldName: String(row.field_name),
+        userValue: decodeStoredValue(row.user_value),
+        currentCanonicalValue: decodeStoredValue(row.current_canonical_value),
+        userBaseRevision: Number(row.user_base_revision),
+        currentCanonicalRevision: Number(row.current_canonical_revision),
+        candidateEpoch: Number(row.candidate_epoch),
+        status,
+        updatedAt: Number(row.updated_at),
+    };
+}
+/**
+ * Decodes one stored normalized-cell JSON value into a plain scalar.
+ *
+ * Falls back to the raw stored text when the payload is not valid JSON or
+ * not a normalized cell, so a partially corrupt row remains inspectable.
+ */
+function decodeStoredValue(raw) {
+    if (raw === null || raw === undefined)
+        return null;
+    const text = String(raw);
+    try {
+        const parsed = JSON.parse(text);
+        if (isNormalizedCell(parsed)) {
+            return parsed === null ? null : parsed.value;
+        }
+    }
+    catch {
+        // fall through to the raw text
+    }
+    return text;
+}
+/** Best-effort human-readable message from an unknown error. */
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=syncStatus.js.map