@hops-ops/distributed 0.0.0

package/dist/replica/persistence/types.d.ts

@@ -0,0 +1,54 @@
+import type { ReplicaAuthoritativeScope, ReplicaDehydratedState } from '../types.js';
+export declare const REPLICA_OFFLINE_COMMAND_OUTBOX_SUPPORTED: false;
+export type ReplicaPersistenceModelPolicy = {
+    /**
+     * Durable storage is an explicit per-model choice. `memory-only` is always
+     * honored, even when the model is otherwise non-sensitive.
+     */
+    readonly retention: 'persist-confirmed' | 'memory-only';
+    /**
+     * Sensitivity must be classified explicitly. Sensitive or unclassified
+     * models are never written to durable storage.
+     */
+    readonly sensitive: boolean;
+};
+export type ReplicaPersistencePolicy = {
+    readonly models: Readonly<Record<string, ReplicaPersistenceModelPolicy>>;
+};
+export type ReplicaIndexedDbFactory = Pick<IDBFactory, 'open'>;
+export type ReplicaIndexedDbPersistenceOptions = {
+    /**
+     * Defaults to the browser's IndexedDB factory. Supplying a factory makes the
+     * boundary deterministic in tests and non-window runtimes.
+     */
+    readonly indexedDB?: ReplicaIndexedDbFactory;
+    readonly databaseName?: string;
+    /**
+     * Missing models, missing policy, `memory-only`, and `sensitive: true` all
+     * fail closed. A model persists only when both fields explicitly allow it.
+     */
+    readonly policy?: ReplicaPersistencePolicy;
+};
+export interface ReplicaIndexedDbPersistence {
+    readonly supportsOfflineCommandOutbox: false;
+    /**
+     * Validate, policy-filter, and persist one confirmed dehydration envelope.
+     *
+     * Returns false when policy leaves no durable records or causal fences.
+     * Malformed caller input rejects rather than entering durable storage.
+     */
+    save(state: ReplicaDehydratedState): Promise<boolean>;
+    /**
+     * Restore only after the caller has independently obtained the exact current
+     * server scope. Corrupt, unsupported, or mismatched entries are deleted and
+     * return undefined.
+     */
+    restore(authoritativeScope: ReplicaAuthoritativeScope): Promise<ReplicaDehydratedState | undefined>;
+    /** Delete confirmed state for exactly one independently authoritative scope. */
+    discard(authoritativeScope: ReplicaAuthoritativeScope): Promise<void>;
+    /**
+     * Close this instance's database handle. Persistence deliberately performs
+     * no BroadcastChannel, leader election, or active multi-tab synchronization.
+     */
+    close(): void;
+}

package/dist/replica/persistence/types.js

@@ -0,0 +1 @@
+export const REPLICA_OFFLINE_COMMAND_OUTBOX_SUPPORTED = false;

package/dist/replica/persistence.d.ts

@@ -0,0 +1,3 @@
+/** Confirmed-state IndexedDB persistence; implementation in ./persistence/. */
+export { createReplicaIndexedDbPersistence, REPLICA_OFFLINE_COMMAND_OUTBOX_SUPPORTED } from './persistence/index.js';
+export type { ReplicaIndexedDbFactory, ReplicaIndexedDbPersistence, ReplicaIndexedDbPersistenceOptions, ReplicaPersistenceModelPolicy, ReplicaPersistencePolicy } from './persistence/index.js';

package/dist/replica/persistence.js

@@ -0,0 +1,2 @@
+/** Confirmed-state IndexedDB persistence; implementation in ./persistence/. */
+export { createReplicaIndexedDbPersistence, REPLICA_OFFLINE_COMMAND_OUTBOX_SUPPORTED } from './persistence/index.js';

package/dist/replica/query-plan/constants.d.ts

@@ -0,0 +1,13 @@
+export declare const FILTER_MATCH: Readonly<{
+    result: "match";
+}>;
+export declare const FILTER_NO_MATCH: Readonly<{
+    result: "no_match";
+}>;
+export declare const ORDER_EQUAL: Readonly<{
+    result: "equal";
+}>;
+export declare const PAGINATION_LOCAL: Readonly<{
+    decision: "local";
+}>;
+export declare const UTF8_ENCODER: TextEncoder;

package/dist/replica/query-plan/constants.js

@@ -0,0 +1,7 @@
+export const FILTER_MATCH = Object.freeze({ result: 'match' });
+export const FILTER_NO_MATCH = Object.freeze({ result: 'no_match' });
+export const ORDER_EQUAL = Object.freeze({ result: 'equal' });
+export const PAGINATION_LOCAL = Object.freeze({
+    decision: 'local'
+});
+export const UTF8_ENCODER = new TextEncoder();

package/dist/replica/query-plan/filter.d.ts

@@ -0,0 +1,39 @@
+import type { GraphqlVariables } from '../../types.js';
+import type { ReplicaFilterArtifact, ReplicaFilterExpression, ReplicaFilterFieldArtifact, ReplicaFilterOperator, ReplicaRelationshipArtifact, ReplicaRelationshipKeyMapping, ReplicaValue } from '../types.js';
+import type { FilterCatalog, ReplicaFilterEvaluation, ReplicaFilterEvaluationOptions, ReplicaQueryPlanPath, ReplicaQueryPlanReason, ResolvedOperand } from './types.js';
+export declare function evaluateReplicaFilter(artifact: ReplicaFilterArtifact, record: Readonly<Record<string, ReplicaValue>>, variables?: GraphqlVariables, options?: ReplicaFilterEvaluationOptions): ReplicaFilterEvaluation;
+export declare function evaluateCallerWhere(value: ReplicaValue, record: Readonly<Record<string, ReplicaValue>>, catalog: FilterCatalog, options: ReplicaFilterEvaluationOptions, path: ReplicaQueryPlanPath): ReplicaFilterEvaluation;
+export declare function evaluateCallerField(field: ReplicaFilterFieldArtifact, value: ReplicaValue, record: Readonly<Record<string, ReplicaValue>>, path: ReplicaQueryPlanPath): ReplicaFilterEvaluation;
+export declare function evaluateClientOperator(field: ReplicaFilterFieldArtifact, operator: ReplicaFilterOperator, left: ReplicaValue, rhs: ReplicaValue, path: ReplicaQueryPlanPath): ReplicaFilterEvaluation;
+export declare function evaluateRowPolicy(artifact: ReplicaFilterArtifact, record: Readonly<Record<string, ReplicaValue>>, catalog: FilterCatalog, options: ReplicaFilterEvaluationOptions, path: ReplicaQueryPlanPath): ReplicaFilterEvaluation;
+export declare function evaluatePolicyExpression(expression: ReplicaFilterExpression, record: Readonly<Record<string, ReplicaValue>>, catalog: FilterCatalog, options: ReplicaFilterEvaluationOptions, path: ReplicaQueryPlanPath): ReplicaFilterEvaluation;
+export declare function evaluateComparison(codec: string, operator: ReplicaFilterOperator, left: ReplicaValue, right: ReplicaValue, path: ReplicaQueryPlanPath): ReplicaFilterEvaluation;
+export declare function evaluateIn(codec: string, left: ReplicaValue, values: readonly ReplicaValue[], negated: boolean, path: ReplicaQueryPlanPath): ReplicaFilterEvaluation;
+export declare function validateComparableValues(codec: string, left: ReplicaValue, right: ReplicaValue, path: ReplicaQueryPlanPath): ReplicaQueryPlanReason | undefined;
+/**
+ * Protocol v1 orders strings by their unsigned UTF-8 bytes. The GraphQL SQL
+ * compiler emits the matching binary collation for every textual ORDER BY,
+ * making optimistic index maintenance identical on SQLite and PostgreSQL.
+ */
+export declare function validateRowPolicyLiteral(field: ReplicaFilterFieldArtifact, operand: Extract<ResolvedOperand, {
+    readonly kind: 'value';
+}>, path: ReplicaQueryPlanPath, operator?: ReplicaFilterOperator): ReplicaQueryPlanReason | undefined;
+export declare function filterCatalog(artifact: ReplicaFilterArtifact): FilterCatalog | {
+    readonly reason: ReplicaQueryPlanReason;
+};
+export declare function relationshipArtifact(value: unknown, path: ReplicaQueryPlanPath): {
+    readonly value: ReplicaRelationshipArtifact;
+} | {
+    readonly reason: ReplicaQueryPlanReason;
+};
+export declare function relationshipKeyMapping(value: unknown, dependencies: readonly string[], path: ReplicaQueryPlanPath): {
+    readonly value: ReplicaRelationshipKeyMapping;
+} | {
+    readonly reason: ReplicaQueryPlanReason;
+};
+export declare function filterAnd(values: readonly ReplicaFilterEvaluation[]): ReplicaFilterEvaluation;
+export declare function filterOr(values: readonly ReplicaFilterEvaluation[]): ReplicaFilterEvaluation;
+export declare function filterNot(value: ReplicaFilterEvaluation): ReplicaFilterEvaluation;
+export declare function filterUnknown(reasonValue: ReplicaQueryPlanReason): ReplicaFilterEvaluation;
+export declare function isFilterOperator(value: string): value is ReplicaFilterOperator;
+export declare function isOperatorScalarCompatible(scalar: string, operator: ReplicaFilterOperator): boolean;

package/dist/replica/query-plan/filter.js

@@ -0,0 +1,544 @@
+import { FILTER_MATCH, FILTER_NO_MATCH } from './constants.js';
+import { recordField, resolveInput, resolveOperand, uniqueStringList } from './resolve.js';
+import { isFiniteNumber, isInt32, isName, isPortableNumericCodec, isRecord, isSafeIntegerNumber, isScalarCodecPair, reason } from './util.js';
+export function evaluateReplicaFilter(artifact, record, variables = {}, options = {}) {
+    const catalog = filterCatalog(artifact);
+    if ('reason' in catalog)
+        return filterUnknown(catalog.reason);
+    const input = resolveInput(artifact.input, variables, ['where']);
+    const caller = input.kind === 'unknown'
+        ? filterUnknown(input.reason)
+        : input.kind === 'omitted' || input.value === null
+            ? FILTER_MATCH
+            : evaluateCallerWhere(input.value, record, catalog, options, ['where']);
+    const policy = evaluateRowPolicy(artifact, record, catalog, options, ['rowPolicy']);
+    return filterAnd([caller, policy]);
+}
+export function evaluateCallerWhere(value, record, catalog, options, path) {
+    if (value === null)
+        return FILTER_MATCH;
+    if (!isRecord(value)) {
+        return filterUnknown(reason('invalid_filter_input', path, 'where predicates must be objects'));
+    }
+    const predicates = [];
+    for (const [key, predicate] of Object.entries(value)) {
+        const predicatePath = [...path, key];
+        if (key === '_and' || key === '_or') {
+            if (predicate === null)
+                continue;
+            const items = Array.isArray(predicate)
+                ? predicate
+                : isRecord(predicate)
+                    ? [predicate]
+                    : undefined;
+            if (items === undefined) {
+                predicates.push(filterUnknown(reason('invalid_filter_input', predicatePath, `${key} must be an object or list of objects`)));
+                continue;
+            }
+            // The server treats both empty caller lists as no predicate (TRUE).
+            if (items.length === 0)
+                continue;
+            const evaluated = items.map((item, index) => evaluateCallerWhere(item, record, catalog, options, [...predicatePath, index]));
+            predicates.push(key === '_and' ? filterAnd(evaluated) : filterOr(evaluated));
+            continue;
+        }
+        if (key === '_not') {
+            if (predicate === null) {
+                predicates.push(FILTER_NO_MATCH);
+            }
+            else {
+                predicates.push(filterNot(evaluateCallerWhere(predicate, record, catalog, options, predicatePath)));
+            }
+            continue;
+        }
+        const field = catalog.fields.get(key);
+        if (field !== undefined) {
+            predicates.push(evaluateCallerField(field, predicate, record, predicatePath));
+            continue;
+        }
+        const relationship = catalog.relationships.get(key);
+        if (relationship !== undefined) {
+            const resolver = options.resolveRelationship;
+            predicates.push(resolver === undefined
+                ? filterUnknown(reason('relationship_resolver_required', predicatePath, `relationship predicate ${key} requires an explicit resolver`))
+                : resolver({
+                    source: 'caller',
+                    relationship,
+                    predicate,
+                    record,
+                    path: Object.freeze(predicatePath)
+                }));
+            continue;
+        }
+        predicates.push(filterUnknown(reason('unknown_field', predicatePath, `where field ${key} is not declared by the artifact`)));
+    }
+    return filterAnd(predicates);
+}
+export function evaluateCallerField(field, value, record, path) {
+    if (value === null)
+        return FILTER_MATCH;
+    if (!isRecord(value)) {
+        return filterUnknown(reason('invalid_filter_input', path, `comparison expression for ${field.field} must be an object`));
+    }
+    const predicates = [];
+    for (const [rawOperator, rhs] of Object.entries(value)) {
+        const operatorPath = [...path, rawOperator];
+        if (!isFilterOperator(rawOperator) ||
+            !field.operators.includes(rawOperator)) {
+            predicates.push(filterUnknown(reason('unsupported_operator', operatorPath, `operator ${rawOperator} is not declared for ${field.field}`)));
+            continue;
+        }
+        const left = recordField(record, field.field, operatorPath);
+        if (left.kind === 'unknown') {
+            predicates.push(filterUnknown(left.reason));
+            continue;
+        }
+        predicates.push(evaluateClientOperator(field, rawOperator, left.value, rhs, operatorPath));
+    }
+    return filterAnd(predicates);
+}
+export function evaluateClientOperator(field, operator, left, rhs, path) {
+    if (operator === '_is_null') {
+        if (rhs !== null && typeof rhs !== 'boolean') {
+            return filterUnknown(reason('invalid_filter_value', path, '_is_null must be a boolean or null'));
+        }
+        const wantsNull = rhs === true;
+        return (left === null) === wantsNull ? FILTER_MATCH : FILTER_NO_MATCH;
+    }
+    if (operator === '_in' || operator === '_nin') {
+        if (rhs === null) {
+            return filterUnknown(reason('invalid_filter_value', path, `${operator} requires a list`));
+        }
+        const values = Array.isArray(rhs) ? rhs : [rhs];
+        return evaluateIn(field.codec, left, values, operator === '_nin', path);
+    }
+    return evaluateComparison(field.codec, operator, left, rhs, path);
+}
+export function evaluateRowPolicy(artifact, record, catalog, options, path) {
+    const policy = artifact.rowPolicy;
+    if (policy.kind === 'unrestricted')
+        return FILTER_MATCH;
+    if (policy.kind === 'server_only') {
+        return filterUnknown(reason('server_only_policy', path, 'server-only row policy cannot be evaluated in the replica'));
+    }
+    if (policy.kind !== 'predicate' || !isRecord(policy.expression)) {
+        return filterUnknown(reason('invalid_artifact', path, 'row policy artifact is malformed'));
+    }
+    return evaluatePolicyExpression(policy.expression, record, catalog, options, [...path, 'expression']);
+}
+export function evaluatePolicyExpression(expression, record, catalog, options, path) {
+    if (expression.kind === 'and' || expression.kind === 'or') {
+        if (!Array.isArray(expression.value)) {
+            return filterUnknown(reason('invalid_artifact', path, 'row-policy boolean value must be a list'));
+        }
+        const evaluated = expression.value.map((item, index) => evaluatePolicyExpression(item, record, catalog, options, [...path, expression.kind, index]));
+        // Unlike caller `_or: []`, a row-policy Or([]) is SQL FALSE.
+        return expression.kind === 'and' ? filterAnd(evaluated) : filterOr(evaluated);
+    }
+    if (expression.kind === 'not') {
+        return filterNot(evaluatePolicyExpression(expression.value, record, catalog, options, [...path, 'not']));
+    }
+    if (expression.kind === 'rel') {
+        const field = expression.value.field;
+        const relationshipPath = [...path, 'rel', field];
+        const relationship = catalog.relationships.get(field);
+        if (relationship === undefined) {
+            return filterUnknown(reason('unknown_relationship', relationshipPath, `row policy relationship ${field} is not declared by the artifact`));
+        }
+        const resolver = options.resolveRelationship;
+        return resolver === undefined
+            ? filterUnknown(reason('relationship_resolver_required', relationshipPath, `row policy relationship ${field} requires an explicit resolver`))
+            : resolver({
+                source: 'row_policy',
+                relationship,
+                predicate: expression.value.predicate,
+                record,
+                path: Object.freeze(relationshipPath)
+            });
+    }
+    if (expression.kind !== 'cmp' &&
+        expression.kind !== 'in' &&
+        expression.kind !== 'is_null') {
+        return filterUnknown(reason('invalid_artifact', path, 'row policy expression kind is unsupported'));
+    }
+    const column = expression.value.column;
+    const field = catalog.fields.get(column);
+    const columnPath = [...path, expression.kind, column];
+    if (field === undefined) {
+        return filterUnknown(reason('unknown_field', columnPath, `row policy field ${column} is not declared by the artifact`));
+    }
+    const left = recordField(record, column, columnPath);
+    if (left.kind === 'unknown')
+        return filterUnknown(left.reason);
+    if (expression.kind === 'is_null') {
+        if (typeof expression.value.is_null !== 'boolean') {
+            return filterUnknown(reason('invalid_artifact', [...columnPath, 'is_null'], 'row-policy is_null must be a boolean'));
+        }
+        return (left.value === null) === expression.value.is_null
+            ? FILTER_MATCH
+            : FILTER_NO_MATCH;
+    }
+    if (expression.kind === 'cmp') {
+        const operator = `_${expression.value.op}`;
+        if (!isFilterOperator(operator) ||
+            !isOperatorScalarCompatible(field.scalar, operator)) {
+            return filterUnknown(reason('invalid_artifact', [...columnPath, 'op'], `row-policy operator ${expression.value.op} cannot target ${field.scalar}`));
+        }
+        const operand = resolveOperand(expression.value.rhs, field, options, [...columnPath, 'rhs']);
+        if (operand.kind === 'unknown')
+            return filterUnknown(operand.reason);
+        const literalValidity = validateRowPolicyLiteral(field, operand, [...columnPath, 'rhs'], operator);
+        if (literalValidity !== undefined)
+            return filterUnknown(literalValidity);
+        return evaluateComparison(field.codec, `_${expression.value.op}`, left.value, operand.value, columnPath);
+    }
+    if (expression.kind === 'in') {
+        if (typeof expression.value.negated !== 'boolean' ||
+            !Array.isArray(expression.value.values)) {
+            return filterUnknown(reason('invalid_artifact', columnPath, 'row-policy IN values must be a list and negated must be a boolean'));
+        }
+        const values = [];
+        for (const [index, operand] of expression.value.values.entries()) {
+            const operandPath = [...columnPath, 'values', index];
+            const resolved = resolveOperand(operand, field, options, operandPath);
+            if (resolved.kind === 'unknown')
+                return filterUnknown(resolved.reason);
+            const literalValidity = validateRowPolicyLiteral(field, resolved, operandPath);
+            if (literalValidity !== undefined)
+                return filterUnknown(literalValidity);
+            values.push(resolved.value);
+        }
+        return evaluateIn(field.codec, left.value, values, expression.value.negated, columnPath);
+    }
+    return filterUnknown(reason('invalid_artifact', path, 'row policy expression kind is unsupported'));
+}
+export function evaluateComparison(codec, operator, left, right, path) {
+    if (operator === '_like' ||
+        operator === '_ilike' ||
+        operator === '_contains' ||
+        operator === '_contained_in' ||
+        operator === '_has_key') {
+        return filterUnknown(reason('unsupported_operator', path, `${operator} has no certified cross-dialect replica evaluator`));
+    }
+    if (left === null || right === null) {
+        return filterUnknown(reason('sql_null', path, 'SQL comparison with null is unknown'));
+    }
+    const validity = validateComparableValues(codec, left, right, path);
+    if (validity !== undefined)
+        return filterUnknown(validity);
+    if (operator === '_eq' || operator === '_neq') {
+        if (codec === 'string' && left !== right) {
+            return filterUnknown(reason('collation_not_portable', path, 'non-identical strings require an explicit server collation contract'));
+        }
+        const equal = left === right;
+        return equal === (operator === '_eq') ? FILTER_MATCH : FILTER_NO_MATCH;
+    }
+    if (operator !== '_gt' &&
+        operator !== '_gte' &&
+        operator !== '_lt' &&
+        operator !== '_lte') {
+        return filterUnknown(reason('unsupported_operator', path, `operator ${operator} is not portable`));
+    }
+    if (!isPortableNumericCodec(codec)) {
+        return filterUnknown(reason('unsupported_operator', path, `${operator} is portable only for certified numeric codecs`));
+    }
+    const a = left;
+    const b = right;
+    const matches = operator === '_gt'
+        ? a > b
+        : operator === '_gte'
+            ? a >= b
+            : operator === '_lt'
+                ? a < b
+                : a <= b;
+    return matches ? FILTER_MATCH : FILTER_NO_MATCH;
+}
+export function evaluateIn(codec, left, values, negated, path) {
+    // Server compilation special-cases empty lists before evaluating the column.
+    if (values.length === 0)
+        return negated ? FILTER_MATCH : FILTER_NO_MATCH;
+    if (left === null) {
+        return filterUnknown(reason('sql_null', path, 'SQL IN comparison with a null column is unknown'));
+    }
+    // GraphQL rejects a type-invalid list before SQL runs. Validate every
+    // non-null candidate before allowing a later equality to establish truth.
+    // SQL NULL is different: a concrete equality may still dominate UNKNOWN.
+    for (const [index, candidate] of values.entries()) {
+        if (candidate === null)
+            continue;
+        const validity = validateComparableValues(codec, left, candidate, [...path, index]);
+        if (validity !== undefined)
+            return filterUnknown(validity);
+    }
+    let firstUnknown;
+    for (const [index, candidate] of values.entries()) {
+        if (candidate === null) {
+            firstUnknown ??= reason('sql_null', [...path, index], 'SQL IN list containing null can produce an unknown result');
+            continue;
+        }
+        if (left === candidate)
+            return negated ? FILTER_NO_MATCH : FILTER_MATCH;
+        if (codec === 'string') {
+            firstUnknown ??= reason('collation_not_portable', [...path, index], 'non-identical strings in SQL IN require an explicit server collation contract');
+        }
+    }
+    if (firstUnknown !== undefined)
+        return filterUnknown(firstUnknown);
+    return negated ? FILTER_MATCH : FILTER_NO_MATCH;
+}
+export function validateComparableValues(codec, left, right, path) {
+    if (codec === 'string') {
+        return typeof left === 'string' && typeof right === 'string'
+            ? undefined
+            : reason('invalid_filter_value', path, 'string codec requires string values');
+    }
+    if (codec === 'boolean') {
+        return typeof left === 'boolean' && typeof right === 'boolean'
+            ? undefined
+            : reason('invalid_filter_value', path, 'boolean codec requires boolean values');
+    }
+    if (codec === 'int32') {
+        return isInt32(left) && isInt32(right)
+            ? undefined
+            : reason('invalid_filter_value', path, 'int32 codec requires signed 32-bit integer values');
+    }
+    if (codec === 'float64') {
+        return isFiniteNumber(left) && isFiniteNumber(right)
+            ? undefined
+            : reason('invalid_filter_value', path, 'float64 codec requires finite number values');
+    }
+    if (codec === 'json_number_precision_limited') {
+        return isSafeIntegerNumber(left) && isSafeIntegerNumber(right)
+            ? undefined
+            : reason('invalid_filter_value', path, 'BigInt codec requires JavaScript-safe integer values');
+    }
+    return reason('unsupported_codec', path, `codec ${codec} has no certified replica comparison semantics`);
+}
+/**
+ * Protocol v1 orders strings by their unsigned UTF-8 bytes. The GraphQL SQL
+ * compiler emits the matching binary collation for every textual ORDER BY,
+ * making optimistic index maintenance identical on SQLite and PostgreSQL.
+ */
+export function validateRowPolicyLiteral(field, operand, path, operator) {
+    if (operand.source === 'trusted_preset')
+        return undefined;
+    const literalKind = operand.literalKind;
+    if (literalKind === undefined) {
+        return reason('invalid_artifact', path, 'row-policy literal is missing its tagged kind');
+    }
+    if (literalKind === 'null')
+        return undefined;
+    const expected = field.scalar === 'ID' ||
+        field.scalar === 'String' ||
+        field.scalar === 'Timestamptz'
+        ? ['string']
+        : field.scalar === 'Boolean'
+            ? ['bool']
+            : field.scalar === 'Int' || field.scalar === 'BigInt'
+                ? ['i64']
+                : field.scalar === 'Float'
+                    ? ['f64', 'i64']
+                    : field.scalar === 'JSON'
+                        ? operator === '_has_key'
+                            ? ['string']
+                            : ['json']
+                        : undefined;
+    if (expected?.includes(literalKind))
+        return undefined;
+    return reason('invalid_artifact', path, expected === undefined
+        ? `scalar ${field.scalar} has no non-null row-policy literal encoding`
+        : `row-policy literal kind ${literalKind} cannot target ${field.scalar}; expected ${expected.join(' or ')}`);
+}
+export function filterCatalog(artifact) {
+    const fields = new Map();
+    for (const [index, field] of artifact.fields.entries()) {
+        if (!isName(field.field) ||
+            !isScalarCodecPair(field.scalar, field.codec) ||
+            typeof field.nullable !== 'boolean' ||
+            !Array.isArray(field.operators) ||
+            fields.has(field.field)) {
+            return {
+                reason: reason('invalid_artifact', ['filter', 'fields', index], 'filter fields must have unique names, exact scalar-codec pairs, nullability, and operators')
+            };
+        }
+        const operators = new Set();
+        for (const [operatorIndex, operator] of field.operators.entries()) {
+            if (!isFilterOperator(operator) ||
+                !isOperatorScalarCompatible(field.scalar, operator) ||
+                operators.has(operator)) {
+                return {
+                    reason: reason('invalid_artifact', ['filter', 'fields', index, 'operators', operatorIndex], 'filter operators must be unique and compatible with the field scalar')
+                };
+            }
+            operators.add(operator);
+        }
+        fields.set(field.field, field);
+    }
+    const relationships = new Map();
+    for (const [index, value] of artifact.relationships.entries()) {
+        const parsed = relationshipArtifact(value, [
+            'filter',
+            'relationships',
+            index
+        ]);
+        if ('reason' in parsed)
+            return parsed;
+        const relationship = parsed.value;
+        if (relationships.has(relationship.field)) {
+            return {
+                reason: reason('invalid_artifact', ['filter', 'relationships', index], 'filter relationship descriptors must have unique fields')
+            };
+        }
+        relationships.set(relationship.field, relationship);
+    }
+    return { fields, relationships };
+}
+export function relationshipArtifact(value, path) {
+    if (!isRecord(value) ||
+        !isName(value.field) ||
+        !isName(value.targetModel) ||
+        (value.kind !== 'has_many' &&
+            value.kind !== 'belongs_to' &&
+            value.kind !== 'many_to_many') ||
+        (value.maintenance !== 'local' && value.maintenance !== 'revalidate')) {
+        return {
+            reason: reason('invalid_artifact', path, 'relationship descriptor has invalid field, target, kind, or maintenance')
+        };
+    }
+    const dependencies = uniqueStringList(value.dependencies);
+    if (dependencies === undefined || dependencies.length === 0) {
+        return {
+            reason: reason('invalid_artifact', [...path, 'dependencies'], 'relationship dependencies must be a non-empty unique string list')
+        };
+    }
+    const keyMapping = relationshipKeyMapping(value.keyMapping, dependencies, [...path, 'keyMapping']);
+    if ('reason' in keyMapping)
+        return keyMapping;
+    const localMapping = keyMapping.value.kind === 'direct' || keyMapping.value.kind === 'through';
+    if (!localMapping && value.maintenance !== 'revalidate') {
+        return {
+            reason: reason('invalid_artifact', [...path, 'maintenance'], 'opaque and embedded mappings must use revalidation maintenance')
+        };
+    }
+    return {
+        value: Object.freeze({
+            field: value.field,
+            targetModel: value.targetModel,
+            kind: value.kind,
+            keyMapping: keyMapping.value,
+            maintenance: value.maintenance,
+            dependencies
+        })
+    };
+}
+export function relationshipKeyMapping(value, dependencies, path) {
+    if (!isRecord(value) || !isName(value.kind)) {
+        return {
+            reason: reason('invalid_artifact', path, 'relationship key mapping must declare a supported kind')
+        };
+    }
+    if (value.kind === 'embedded') {
+        return { value: Object.freeze({ kind: 'embedded' }) };
+    }
+    const local = uniqueStringList(value.local);
+    const remote = uniqueStringList(value.remote);
+    if (local === undefined ||
+        remote === undefined ||
+        local.length === 0 ||
+        local.length !== remote.length) {
+        return {
+            reason: reason('invalid_artifact', path, 'relationship key lists must be unique, non-empty, and equally sized')
+        };
+    }
+    if (value.kind === 'direct') {
+        return {
+            value: Object.freeze({ kind: 'direct', local, remote })
+        };
+    }
+    if (value.kind === 'through' &&
+        isName(value.table) &&
+        dependencies.includes(value.table) &&
+        isName(value.sourceForeignKey) &&
+        isName(value.targetForeignKey)) {
+        return {
+            value: Object.freeze({
+                kind: 'through',
+                local,
+                remote,
+                table: value.table,
+                sourceForeignKey: value.sourceForeignKey,
+                targetForeignKey: value.targetForeignKey
+            })
+        };
+    }
+    if (value.kind === 'through_opaque' &&
+        isName(value.dependency) &&
+        dependencies.includes(value.dependency)) {
+        return {
+            value: Object.freeze({
+                kind: 'through_opaque',
+                local,
+                remote,
+                dependency: value.dependency
+            })
+        };
+    }
+    return {
+        reason: reason('invalid_artifact', path, 'relationship key mapping is incomplete or references an undeclared dependency')
+    };
+}
+export function filterAnd(values) {
+    let firstUnknown;
+    for (const value of values) {
+        if (value.result === 'no_match')
+            return FILTER_NO_MATCH;
+        if (value.result === 'unknown')
+            firstUnknown ??= value.reason;
+    }
+    return firstUnknown === undefined ? FILTER_MATCH : filterUnknown(firstUnknown);
+}
+export function filterOr(values) {
+    let firstUnknown;
+    for (const value of values) {
+        if (value.result === 'match')
+            return FILTER_MATCH;
+        if (value.result === 'unknown')
+            firstUnknown ??= value.reason;
+    }
+    return firstUnknown === undefined ? FILTER_NO_MATCH : filterUnknown(firstUnknown);
+}
+export function filterNot(value) {
+    if (value.result === 'unknown')
+        return value;
+    return value.result === 'match' ? FILTER_NO_MATCH : FILTER_MATCH;
+}
+export function filterUnknown(reasonValue) {
+    return Object.freeze({ result: 'unknown', reason: reasonValue });
+}
+export function isFilterOperator(value) {
+    return (value === '_eq' ||
+        value === '_neq' ||
+        value === '_gt' ||
+        value === '_gte' ||
+        value === '_lt' ||
+        value === '_lte' ||
+        value === '_in' ||
+        value === '_nin' ||
+        value === '_is_null' ||
+        value === '_like' ||
+        value === '_ilike' ||
+        value === '_contains' ||
+        value === '_contained_in' ||
+        value === '_has_key');
+}
+export function isOperatorScalarCompatible(scalar, operator) {
+    if (operator === '_like' || operator === '_ilike') {
+        return scalar === 'String';
+    }
+    if (operator === '_contains' ||
+        operator === '_contained_in' ||
+        operator === '_has_key') {
+        return scalar === 'JSON';
+    }
+    return true;
+}