@hops-ops/distributed 0.0.0

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

@@ -0,0 +1,4 @@
+export type { ReplicaFilterEvaluation, ReplicaFilterEvaluationOptions, ReplicaOrderComparison, ReplicaPaginationChange, ReplicaPaginationMaintenanceDecision, ReplicaQueryPlanPath, ReplicaQueryPlanReason, ReplicaQueryPlanReasonCode, ReplicaRelationshipFilterRequest } from './types.js';
+export { evaluateReplicaFilter } from './filter.js';
+export { compareReplicaOrder } from './order.js';
+export { decideReplicaPaginationMaintenance } from './pagination.js';

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

@@ -0,0 +1,3 @@
+export { evaluateReplicaFilter } from './filter.js';
+export { compareReplicaOrder } from './order.js';
+export { decideReplicaPaginationMaintenance } from './pagination.js';

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

@@ -0,0 +1,11 @@
+import type { GraphqlVariables } from '../../types.js';
+import type { ReplicaOrderArtifact, ReplicaValue } from '../types.js';
+import type { OrderDirection, ReplicaOrderComparison, ReplicaQueryPlanPath, ReplicaQueryPlanReason } from './types.js';
+export declare function compareReplicaOrder(artifact: ReplicaOrderArtifact, left: Readonly<Record<string, ReplicaValue>>, right: Readonly<Record<string, ReplicaValue>>, variables?: GraphqlVariables): ReplicaOrderComparison;
+export declare function compareOrderField(field: string, codec: string, nullable: boolean, direction: OrderDirection, left: Readonly<Record<string, ReplicaValue>>, right: Readonly<Record<string, ReplicaValue>>, path: ReplicaQueryPlanPath): ReplicaOrderComparison;
+export declare function compareUtf8(left: string, right: string): -1 | 0 | 1;
+export declare function orderUnknown(reasonValue: ReplicaQueryPlanReason): ReplicaOrderComparison;
+export declare function orderResult(comparison: -1 | 1): ReplicaOrderComparison;
+export declare function isOrderDirection(value: ReplicaValue): value is OrderDirection;
+export declare function hasExplicitNullPlacement(direction: OrderDirection): boolean;
+export declare function invert(value: -1 | 1): -1 | 1;

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

@@ -0,0 +1,158 @@
+import { ORDER_EQUAL, UTF8_ENCODER } from './constants.js';
+import { recordField, resolveInput } from './resolve.js';
+import { isName, isPortableNumericCodec, isRecord, isScalarCodecPair, reason } from './util.js';
+import { validateComparableValues } from './filter.js';
+export function compareReplicaOrder(artifact, left, right, variables = {}) {
+    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' ||
+            fields.has(field.field)) {
+            return orderUnknown(reason('invalid_artifact', ['order', 'fields', index], 'order fields must have unique names, exact scalar-codec pairs, and nullability'));
+        }
+        fields.set(field.field, field);
+    }
+    const tieBreakerFields = new Set();
+    for (const [index, tieBreaker] of artifact.tieBreakers.entries()) {
+        if (!isName(tieBreaker.field) ||
+            !isScalarCodecPair(tieBreaker.scalar, tieBreaker.codec) ||
+            tieBreaker.nullable !== false ||
+            tieBreakerFields.has(tieBreaker.field)) {
+            return orderUnknown(reason('invalid_artifact', ['order', 'tieBreakers', index], 'order tie-breakers must have unique fields and exact scalar-codec pairs'));
+        }
+        tieBreakerFields.add(tieBreaker.field);
+    }
+    const input = resolveInput(artifact.input, variables, ['order_by']);
+    if (input.kind === 'unknown')
+        return orderUnknown(input.reason);
+    const entries = input.kind === 'omitted' || input.value === null
+        ? []
+        : Array.isArray(input.value)
+            ? input.value
+            : isRecord(input.value)
+                ? [input.value]
+                : [];
+    if (input.kind === 'value' &&
+        input.value !== null &&
+        !Array.isArray(input.value) &&
+        !isRecord(input.value)) {
+        return orderUnknown(reason('invalid_order_input', ['order_by'], 'order_by must be an object or a list of objects'));
+    }
+    for (const [index, entry] of entries.entries()) {
+        const path = ['order_by', index];
+        if (!isRecord(entry)) {
+            return orderUnknown(reason('invalid_order_input', path, 'each order_by entry must be an object'));
+        }
+        const pairs = Object.entries(entry);
+        if (pairs.length === 0)
+            continue;
+        if (pairs.length > 1) {
+            return orderUnknown(reason('ambiguous_order_entry', path, 'each order_by entry may declare at most one field'));
+        }
+        const [fieldName, rawDirection] = pairs[0];
+        const field = fields.get(fieldName);
+        if (field === undefined) {
+            return orderUnknown(reason('unknown_field', [...path, fieldName], `order field ${fieldName} is not declared by the artifact`));
+        }
+        if (!isOrderDirection(rawDirection)) {
+            return orderUnknown(reason('invalid_order_direction', [...path, fieldName], `order direction for ${fieldName} is not supported`));
+        }
+        if (field.nullable && !hasExplicitNullPlacement(rawDirection)) {
+            return orderUnknown(reason('implicit_null_order', [...path, fieldName], `nullable order field ${fieldName} requires explicit null placement`));
+        }
+        const compared = compareOrderField(field.field, field.codec, field.nullable, rawDirection, left, right, [...path, fieldName]);
+        if (compared.result !== 'equal')
+            return compared;
+    }
+    for (const [index, tieBreaker] of artifact.tieBreakers.entries()) {
+        const compared = compareOrderField(tieBreaker.field, tieBreaker.codec, false, 'asc', left, right, ['order', 'tieBreakers', index, tieBreaker.field]);
+        if (compared.result !== 'equal')
+            return compared;
+    }
+    if (artifact.tieBreakers.length === 0) {
+        return orderUnknown(reason('invalid_artifact', ['order', 'tieBreakers'], 'equal order values require a complete identity tie-breaker'));
+    }
+    return ORDER_EQUAL;
+}
+export function compareOrderField(field, codec, nullable, direction, left, right, path) {
+    const a = recordField(left, field, path);
+    if (a.kind === 'unknown')
+        return orderUnknown(a.reason);
+    const b = recordField(right, field, path);
+    if (b.kind === 'unknown')
+        return orderUnknown(b.reason);
+    if ((a.value === null || b.value === null) && !nullable) {
+        return orderUnknown(reason('invalid_order_value', path, `non-null order field ${field} contains null`));
+    }
+    if (a.value === null || b.value === null) {
+        if (a.value === null && b.value === null)
+            return ORDER_EQUAL;
+        if (!hasExplicitNullPlacement(direction)) {
+            return orderUnknown(reason('implicit_null_order', path, `nullable order field ${field} requires explicit null placement`));
+        }
+        const nullFirst = direction.endsWith('_nulls_first');
+        return orderResult((a.value === null) === nullFirst ? -1 : 1);
+    }
+    const validity = validateComparableValues(codec, a.value, b.value, path);
+    if (validity !== undefined)
+        return orderUnknown(validity);
+    let comparison;
+    if (isPortableNumericCodec(codec)) {
+        comparison =
+            a.value < b.value
+                ? -1
+                : a.value > b.value
+                    ? 1
+                    : 0;
+    }
+    else if (codec === 'boolean') {
+        comparison =
+            a.value === b.value ? 0 : a.value === false && b.value === true ? -1 : 1;
+    }
+    else if (codec === 'string') {
+        comparison = compareUtf8(a.value, b.value);
+    }
+    else {
+        return orderUnknown(reason('unsupported_codec', path, `codec ${codec} has no certified replica comparator`));
+    }
+    if (comparison === 0)
+        return ORDER_EQUAL;
+    return orderResult(direction.startsWith('desc') ? invert(comparison) : comparison);
+}
+export function compareUtf8(left, right) {
+    if (left === right)
+        return 0;
+    const leftBytes = UTF8_ENCODER.encode(left);
+    const rightBytes = UTF8_ENCODER.encode(right);
+    const length = Math.min(leftBytes.length, rightBytes.length);
+    for (let index = 0; index < length; index += 1) {
+        const a = leftBytes[index];
+        const b = rightBytes[index];
+        if (a !== b)
+            return a < b ? -1 : 1;
+    }
+    return leftBytes.length < rightBytes.length ? -1 : 1;
+}
+export function orderUnknown(reasonValue) {
+    return Object.freeze({ result: 'unknown', reason: reasonValue });
+}
+export function orderResult(comparison) {
+    return Object.freeze({
+        result: comparison < 0 ? 'less' : 'greater'
+    });
+}
+export function isOrderDirection(value) {
+    return (value === 'asc' ||
+        value === 'asc_nulls_first' ||
+        value === 'asc_nulls_last' ||
+        value === 'desc' ||
+        value === 'desc_nulls_first' ||
+        value === 'desc_nulls_last');
+}
+export function hasExplicitNullPlacement(direction) {
+    return direction.includes('_nulls_');
+}
+export function invert(value) {
+    return value === -1 ? 1 : -1;
+}

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

@@ -0,0 +1,6 @@
+import type { ReplicaIndexCoverage, ReplicaPaginationArtifact, ReplicaPaginationDisposition } from '../types.js';
+import type { ReplicaPaginationChange, ReplicaPaginationMaintenanceDecision, ReplicaQueryPlanReason } from './types.js';
+export declare function decideReplicaPaginationMaintenance(artifact: ReplicaPaginationArtifact, coverage: ReplicaIndexCoverage, change: ReplicaPaginationChange): ReplicaPaginationMaintenanceDecision;
+export declare function paginationRevalidate(reasonValue: ReplicaQueryPlanReason): ReplicaPaginationMaintenanceDecision;
+export declare function validatePaginationPolicies(artifact: ReplicaPaginationArtifact): ReplicaQueryPlanReason | undefined;
+export declare function policyForChange(artifact: ReplicaPaginationArtifact, change: ReplicaPaginationChange): ReplicaPaginationDisposition;

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

@@ -0,0 +1,90 @@
+import { PAGINATION_LOCAL } from './constants.js';
+import { reason } from './util.js';
+export function decideReplicaPaginationMaintenance(artifact, coverage, change) {
+    const invalidPolicy = validatePaginationPolicies(artifact);
+    if (invalidPolicy !== undefined)
+        return paginationRevalidate(invalidPolicy);
+    if (coverage.kind === 'unknown') {
+        return paginationRevalidate(reason('unknown_coverage', ['pagination', 'coverage'], 'unknown index coverage cannot be maintained locally'));
+    }
+    if (coverage.kind !== artifact.kind) {
+        return paginationRevalidate(reason('coverage_mismatch', ['pagination', 'coverage'], `artifact coverage ${artifact.kind} does not match index coverage ${coverage.kind}`));
+    }
+    if (artifact.kind === 'cursor') {
+        return paginationRevalidate(reason('cursor_not_certified', ['pagination', 'kind'], 'cursor locality requires a versioned compiler proof IR'));
+    }
+    const policy = policyForChange(artifact, change);
+    if (policy === 'local') {
+        if (artifact.kind !== 'offset' ||
+            change.kind === 'stable_update') {
+            return PAGINATION_LOCAL;
+        }
+        if (coverage.kind === 'offset' &&
+            coverage.offset === 0 &&
+            coverage.limit !== undefined &&
+            coverage.returned !== undefined &&
+            coverage.returned < coverage.limit) {
+            // A non-full first page proves that the server returned the complete
+            // ordered set. The index runtime can therefore apply all optimistic
+            // membership/order changes and truncate back to the declared limit.
+            return PAGINATION_LOCAL;
+        }
+    }
+    const [code, message] = change.kind === 'insert'
+        ? [
+            'insert_changes_offset_window',
+            'an insert is local only for a proven non-full first offset page'
+        ]
+        : change.kind === 'delete'
+            ? [
+                'delete_changes_offset_window',
+                'a delete is local only for a proven non-full first offset page'
+            ]
+            : change.kind === 'reorder'
+                ? [
+                    'reorder_changes_offset_window',
+                    'a reorder is local only for a proven non-full first offset page'
+                ]
+                : [
+                    'invalid_pagination_policy',
+                    'the artifact requires stable updates to revalidate'
+                ];
+    return paginationRevalidate(reason(code, ['pagination', change.kind], message));
+}
+export function paginationRevalidate(reasonValue) {
+    return Object.freeze({
+        decision: 'revalidate',
+        reason: reasonValue
+    });
+}
+export function validatePaginationPolicies(artifact) {
+    if (artifact.kind !== 'complete' &&
+        artifact.kind !== 'offset' &&
+        artifact.kind !== 'cursor') {
+        return reason('invalid_pagination_policy', ['pagination', 'kind'], 'pagination kind must be complete, offset, or cursor');
+    }
+    const values = [
+        ['insert', artifact.insert],
+        ['delete', artifact.delete],
+        ['reorder', artifact.reorder],
+        ['stableUpdate', artifact.stableUpdate]
+    ];
+    for (const [field, value] of values) {
+        if (value !== 'local' && value !== 'revalidate') {
+            return reason('invalid_pagination_policy', ['pagination', field], `pagination policy ${field} must be local or revalidate`);
+        }
+    }
+    const exact = artifact.kind === 'complete'
+        ? values.every(([, value]) => value === 'local')
+        : artifact.kind === 'offset'
+            ? artifact.stableUpdate === 'local'
+            : true;
+    return exact
+        ? undefined
+        : reason('invalid_pagination_policy', ['pagination'], `${artifact.kind} pagination policies do not match the conservative compiler contract`);
+}
+export function policyForChange(artifact, change) {
+    return change.kind === 'stable_update'
+        ? artifact.stableUpdate
+        : artifact[change.kind];
+}

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

@@ -0,0 +1,14 @@
+import type { GraphqlVariables } from '../../types.js';
+import type { ReplicaArgumentValue, ReplicaFilterFieldArtifact, ReplicaFilterOperand, ReplicaValue } from '../types.js';
+import type { ReplicaFilterEvaluationOptions, ReplicaQueryPlanPath, ReplicaQueryPlanReason, ResolvedInput, ResolvedOperand } from './types.js';
+export declare function resolveInput(input: ReplicaArgumentValue | undefined, variables: GraphqlVariables, path: ReplicaQueryPlanPath): ResolvedInput;
+export declare function resolveOperand(operand: ReplicaFilterOperand, field: ReplicaFilterFieldArtifact, options: ReplicaFilterEvaluationOptions, path: ReplicaQueryPlanPath): ResolvedOperand;
+export declare function resolveTrustedPresetOperand(name: string, field: ReplicaFilterFieldArtifact, options: ReplicaFilterEvaluationOptions, path: ReplicaQueryPlanPath): ResolvedOperand;
+export declare function recordField(record: Readonly<Record<string, ReplicaValue>>, field: string, path: ReplicaQueryPlanPath): {
+    readonly kind: 'value';
+    readonly value: ReplicaValue;
+} | {
+    readonly kind: 'unknown';
+    readonly reason: ReplicaQueryPlanReason;
+};
+export declare function uniqueStringList(value: unknown): readonly string[] | undefined;

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

@@ -0,0 +1,163 @@
+import { resolveReplicaArgumentValue } from '../identity.js';
+import { isFiniteNumber, isName, isRecord, isReplicaValue, reason } from './util.js';
+export function resolveInput(input, variables, path) {
+    if (input === undefined)
+        return { kind: 'omitted' };
+    try {
+        const value = resolveReplicaArgumentValue(input, variables);
+        return value === undefined
+            ? { kind: 'omitted' }
+            : { kind: 'value', value };
+    }
+    catch (error) {
+        return {
+            kind: 'unknown',
+            reason: reason('invalid_argument_value', path, error instanceof Error
+                ? error.message
+                : 'plan input could not be resolved')
+        };
+    }
+}
+export function resolveOperand(operand, field, options, path) {
+    if (operand.kind === 'claim') {
+        return resolveTrustedPresetOperand(operand.value.header, field, options, path);
+    }
+    if (operand.kind !== 'lit' || !isRecord(operand.value)) {
+        return {
+            kind: 'unknown',
+            reason: reason('invalid_artifact', path, 'row-policy operand is malformed')
+        };
+    }
+    const literal = operand.value;
+    if (literal.kind === 'null') {
+        return {
+            kind: 'value',
+            value: null,
+            literalKind: literal.kind,
+            source: 'literal'
+        };
+    }
+    if (literal.kind === 'string' &&
+        typeof literal.value === 'string') {
+        return {
+            kind: 'value',
+            value: literal.value,
+            literalKind: literal.kind,
+            source: 'literal'
+        };
+    }
+    if (literal.kind === 'bool' && typeof literal.value === 'boolean') {
+        return {
+            kind: 'value',
+            value: literal.value,
+            literalKind: literal.kind,
+            source: 'literal'
+        };
+    }
+    if ((literal.kind === 'i64' && Number.isSafeInteger(literal.value)) ||
+        (literal.kind === 'f64' && isFiniteNumber(literal.value))) {
+        return {
+            kind: 'value',
+            value: literal.value,
+            literalKind: literal.kind,
+            source: 'literal'
+        };
+    }
+    if (literal.kind === 'json' && isReplicaValue(literal.value)) {
+        return {
+            kind: 'value',
+            value: literal.value,
+            literalKind: literal.kind,
+            source: 'literal'
+        };
+    }
+    return {
+        kind: 'unknown',
+        reason: reason('invalid_artifact', path, 'row-policy literal is not a portable JSON value')
+    };
+}
+export function resolveTrustedPresetOperand(name, field, options, path) {
+    const inventory = options.trustedPresets;
+    if (inventory === undefined) {
+        return {
+            kind: 'unknown',
+            reason: reason('claim_operand', path, `claim ${name} has no authoritative scope-bound preset inventory`)
+        };
+    }
+    const descriptors = new Map();
+    for (const [index, descriptor] of inventory.descriptors.entries()) {
+        if (typeof descriptor?.name !== 'string' ||
+            descriptor.name.length === 0 ||
+            typeof descriptor.codec !== 'string' ||
+            descriptors.has(descriptor.name)) {
+            return {
+                kind: 'unknown',
+                reason: reason('claim_inventory', [...path, 'descriptors', index], 'trusted preset descriptor inventory is malformed or duplicated')
+            };
+        }
+        descriptors.set(descriptor.name, descriptor);
+    }
+    const values = new Map();
+    for (const [index, preset] of inventory.values.entries()) {
+        if (typeof preset?.name !== 'string' ||
+            preset.name.length === 0 ||
+            typeof preset.codec !== 'string' ||
+            values.has(preset.name)) {
+            return {
+                kind: 'unknown',
+                reason: reason('claim_inventory', [...path, 'values', index], 'trusted preset value inventory is malformed or duplicated')
+            };
+        }
+        values.set(preset.name, preset);
+    }
+    if (descriptors.size !== values.size ||
+        [...descriptors].some(([presetName, descriptor]) => values.get(presetName)?.codec !== descriptor.codec)) {
+        return {
+            kind: 'unknown',
+            reason: reason('claim_inventory', path, 'trusted preset descriptors and scope-bound values do not form an exact union')
+        };
+    }
+    const descriptor = descriptors.get(name);
+    const preset = values.get(name);
+    if (descriptor === undefined || preset === undefined) {
+        return {
+            kind: 'unknown',
+            reason: reason('claim_operand', path, `claim ${name} is absent from the selected client surface`)
+        };
+    }
+    if (descriptor.codec !== field.codec) {
+        return {
+            kind: 'unknown',
+            reason: reason('claim_operand', path, `claim ${name} codec ${descriptor.codec} cannot target ${field.field}:${field.codec}`)
+        };
+    }
+    if (!isReplicaValue(preset.value)) {
+        return {
+            kind: 'unknown',
+            reason: reason('claim_inventory', path, `claim ${name} is not a portable replica value`)
+        };
+    }
+    return {
+        kind: 'value',
+        value: preset.value,
+        source: 'trusted_preset'
+    };
+}
+export function recordField(record, field, path) {
+    if (!Object.prototype.hasOwnProperty.call(record, field)) {
+        return {
+            kind: 'unknown',
+            reason: reason('missing_field', path, `record does not contain canonical field ${field}`)
+        };
+    }
+    return { kind: 'value', value: record[field] };
+}
+export function uniqueStringList(value) {
+    if (!Array.isArray(value) || value.some((entry) => !isName(entry))) {
+        return undefined;
+    }
+    const values = value;
+    if (new Set(values).size !== values.length)
+        return undefined;
+    return Object.freeze([...values]);
+}

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

@@ -0,0 +1,89 @@
+import type { DistributedTrustedPreset } from '../../protocol.js';
+import type { ReplicaFilterExpression, ReplicaFilterFieldArtifact, ReplicaFilterLiteral, ReplicaRelationshipArtifact, ReplicaSurfaceTrustedPresetDescriptor, ReplicaValue } from '../types.js';
+export type ReplicaQueryPlanPath = readonly (string | number)[];
+export type ReplicaQueryPlanReasonCode = 'ambiguous_order_entry' | 'claim_operand' | 'claim_inventory' | 'collation_not_portable' | 'coverage_mismatch' | 'cursor_not_certified' | 'delete_changes_offset_window' | 'implicit_null_order' | 'invalid_argument_value' | 'insert_changes_offset_window' | 'invalid_artifact' | 'invalid_filter_input' | 'invalid_filter_value' | 'invalid_order_direction' | 'invalid_order_input' | 'invalid_order_value' | 'invalid_pagination_policy' | 'missing_field' | 'relationship_resolver_required' | 'reorder_changes_offset_window' | 'server_only_policy' | 'sql_null' | 'unknown_coverage' | 'unknown_field' | 'unknown_relationship' | 'unsupported_codec' | 'unsupported_operator';
+export type ReplicaQueryPlanReason = {
+    readonly code: ReplicaQueryPlanReasonCode;
+    readonly path: ReplicaQueryPlanPath;
+    readonly message: string;
+};
+export type ReplicaFilterEvaluation = {
+    readonly result: 'match' | 'no_match';
+} | {
+    readonly result: 'unknown';
+    readonly reason: ReplicaQueryPlanReason;
+};
+export type ReplicaRelationshipFilterRequest = {
+    readonly source: 'caller';
+    readonly relationship: ReplicaRelationshipArtifact;
+    readonly predicate: ReplicaValue;
+    readonly record: Readonly<Record<string, ReplicaValue>>;
+    readonly path: ReplicaQueryPlanPath;
+} | {
+    readonly source: 'row_policy';
+    readonly relationship: ReplicaRelationshipArtifact;
+    readonly predicate: ReplicaFilterExpression;
+    readonly record: Readonly<Record<string, ReplicaValue>>;
+    readonly path: ReplicaQueryPlanPath;
+};
+export type ReplicaFilterEvaluationOptions = {
+    /**
+     * Resolves the server's EXISTS semantics for a relationship predicate.
+     * The resolver is responsible for the target model's row policy as well as
+     * the supplied predicate; omitting it deliberately produces `unknown`.
+     */
+    readonly resolveRelationship?: (request: ReplicaRelationshipFilterRequest) => ReplicaFilterEvaluation;
+    /**
+     * Static compiler-owned descriptor union paired with the current
+     * server-derived, cache-scope-bound values. The evaluator never reads
+     * ambient token claims or caller headers.
+     */
+    readonly trustedPresets?: {
+        readonly descriptors: readonly ReplicaSurfaceTrustedPresetDescriptor[];
+        readonly values: readonly DistributedTrustedPreset[];
+    };
+};
+export type ReplicaOrderComparison = {
+    readonly result: 'less' | 'equal' | 'greater';
+} | {
+    readonly result: 'unknown';
+    readonly reason: ReplicaQueryPlanReason;
+};
+export type ReplicaPaginationChange = {
+    readonly kind: 'insert';
+} | {
+    readonly kind: 'delete';
+} | {
+    readonly kind: 'reorder';
+} | {
+    readonly kind: 'stable_update';
+};
+export type ReplicaPaginationMaintenanceDecision = {
+    readonly decision: 'local';
+} | {
+    readonly decision: 'revalidate';
+    readonly reason: ReplicaQueryPlanReason;
+};
+export type FilterCatalog = {
+    readonly fields: ReadonlyMap<string, ReplicaFilterFieldArtifact>;
+    readonly relationships: ReadonlyMap<string, ReplicaRelationshipArtifact>;
+};
+export type ResolvedInput = {
+    readonly kind: 'omitted';
+} | {
+    readonly kind: 'value';
+    readonly value: ReplicaValue;
+} | {
+    readonly kind: 'unknown';
+    readonly reason: ReplicaQueryPlanReason;
+};
+export type ResolvedOperand = {
+    readonly kind: 'value';
+    readonly value: ReplicaValue;
+    readonly literalKind?: ReplicaFilterLiteral['kind'];
+    readonly source: 'literal' | 'trusted_preset';
+} | {
+    readonly kind: 'unknown';
+    readonly reason: ReplicaQueryPlanReason;
+};
+export type OrderDirection = 'asc' | 'asc_nulls_first' | 'asc_nulls_last' | 'desc' | 'desc_nulls_first' | 'desc_nulls_last';

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,13 @@
+import type { ReplicaValue } from '../types.js';
+import type { ReplicaQueryPlanPath, ReplicaQueryPlanReason, ReplicaQueryPlanReasonCode } from './types.js';
+export declare function reason(code: ReplicaQueryPlanReasonCode, path: ReplicaQueryPlanPath, message: string): ReplicaQueryPlanReason;
+export declare function isScalarCodecPair(scalar: unknown, codec: unknown): boolean;
+export declare function isPortableNumericCodec(codec: string): boolean;
+export declare function isSafeIntegerNumber(value: ReplicaValue): value is number;
+export declare function isInt32(value: ReplicaValue): value is number;
+export declare function isFiniteNumber(value: unknown): value is number;
+export declare function isName(value: unknown): value is string;
+export declare function isRecord(value: ReplicaValue | unknown): value is {
+    readonly [key: string]: ReplicaValue;
+};
+export declare function isReplicaValue(value: unknown, ancestors?: Set<object>): value is ReplicaValue;

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

@@ -0,0 +1,62 @@
+export function reason(code, path, message) {
+    return Object.freeze({
+        code,
+        path: Object.freeze([...path]),
+        message
+    });
+}
+export function isScalarCodecPair(scalar, codec) {
+    if (typeof scalar !== 'string' || typeof codec !== 'string')
+        return false;
+    return (`${scalar}:${codec}` === 'ID:string' ||
+        `${scalar}:${codec}` === 'String:string' ||
+        `${scalar}:${codec}` === 'Bytea:base64' ||
+        `${scalar}:${codec}` ===
+            'Timestamptz:string_unvalidated_timestamp' ||
+        `${scalar}:${codec}` === 'Boolean:boolean' ||
+        `${scalar}:${codec}` === 'Int:int32' ||
+        `${scalar}:${codec}` === 'Float:float64' ||
+        `${scalar}:${codec}` ===
+            'BigInt:json_number_precision_limited' ||
+        `${scalar}:${codec}` === 'JSON:json');
+}
+export function isPortableNumericCodec(codec) {
+    return (codec === 'int32' ||
+        codec === 'float64' ||
+        codec === 'json_number_precision_limited');
+}
+export function isSafeIntegerNumber(value) {
+    return typeof value === 'number' && Number.isSafeInteger(value);
+}
+export function isInt32(value) {
+    return (Number.isInteger(value) &&
+        value >= -2_147_483_648 &&
+        value <= 2_147_483_647);
+}
+export function isFiniteNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value);
+}
+export function isName(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+export function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+export function isReplicaValue(value, ancestors = new Set()) {
+    if (value === null ||
+        typeof value === 'string' ||
+        typeof value === 'boolean' ||
+        isFiniteNumber(value)) {
+        return true;
+    }
+    if (typeof value !== 'object' || ancestors.has(value))
+        return false;
+    ancestors.add(value);
+    const valid = Array.isArray(value)
+        ? value.every((entry) => isReplicaValue(entry, ancestors))
+        : (Object.getPrototypeOf(value) === Object.prototype ||
+            Object.getPrototypeOf(value) === null) &&
+            Object.values(value).every((entry) => isReplicaValue(entry, ancestors));
+    ancestors.delete(value);
+    return valid;
+}

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

@@ -0,0 +1,3 @@
+/** Query plan evaluation; implementation lives in ./query-plan/. */
+export { compareReplicaOrder, decideReplicaPaginationMaintenance, evaluateReplicaFilter } from './query-plan/index.js';
+export type { ReplicaFilterEvaluation, ReplicaFilterEvaluationOptions, ReplicaOrderComparison, ReplicaPaginationChange, ReplicaPaginationMaintenanceDecision, ReplicaQueryPlanPath, ReplicaQueryPlanReason, ReplicaQueryPlanReasonCode, ReplicaRelationshipFilterRequest } from './query-plan/index.js';

package/dist/replica/query-plan.js

@@ -0,0 +1,2 @@
+/** Query plan evaluation; implementation lives in ./query-plan/. */
+export { compareReplicaOrder, decideReplicaPaginationMaintenance, evaluateReplicaFilter } from './query-plan/index.js';

package/dist/replica/revalidation.d.ts

@@ -0,0 +1,9 @@
+import type { GraphqlVariables } from '../types.js';
+import type { ReplicaOperationArtifact, ReplicaRevalidationPlan } from './types.js';
+/**
+ * Compile one validated command inventory into a reusable operation matcher.
+ *
+ * Adapters only forward generated plans; the replica owns knowledge of active
+ * operation artifacts and therefore remains the framework-neutral coordinator.
+ */
+export declare function createReplicaRevalidationMatcher(plan: ReplicaRevalidationPlan): (artifact: ReplicaOperationArtifact<unknown, GraphqlVariables>) => boolean;