@hops-ops/distributed 0.0.0

package/dist/replica/index-maintenance/engine.js

@@ -0,0 +1,677 @@
+import { replicaIndexKey, resolveArguments } from '../identity.js';
+import { compareReplicaOrder, decideReplicaPaginationMaintenance, evaluateReplicaFilter } from '../query-plan.js';
+import { compareCodeUnits } from '../../lib/compare-code-units.js';
+export function formatReplicaIndexStaleReason(reasonValue) {
+    const path = reasonValue.path.length === 0
+        ? ''
+        : `:${reasonValue.path.map(String).join('.')}`;
+    return `query-plan:${reasonValue.code}${path}`;
+}
+export function compilePlans(registration, artifact, variables) {
+    const plans = [];
+    const trustedPresets = artifact.protocol.trustedPresets;
+    for (const [index, root] of artifact.roots.entries()) {
+        const path = ['roots', index, root.field];
+        const targetModel = selectionModel(root.selection);
+        const kind = targetModel === undefined ? 'snapshot' : 'entity';
+        const argumentsValue = resolveArguments(root.arguments, variables, root.coverage);
+        plans.push(plan({
+            registration,
+            kind,
+            exactIndexKey: replicaIndexKey({
+                field: root.field,
+                arguments: argumentsValue
+            }),
+            targetModel,
+            field: root.field,
+            arguments: argumentsValue,
+            dependencies: root.dependencies,
+            cardinality: root.cardinality,
+            filter: root.filter,
+            order: root.order,
+            pagination: root.pagination,
+            coverage: root.coverage,
+            variables,
+            trustedPresets,
+            path
+        }));
+        compileSelectionPlans(plans, registration, root.selection, targetModel, variables, trustedPresets, path);
+    }
+    return Object.freeze(plans);
+}
+export function compileSelectionPlans(output, registration, selection, parentModel, variables, trustedPresets, path) {
+    for (const [index, member] of selection.members.entries()) {
+        if (member.kind !== 'branch')
+            continue;
+        compileBranchPlan(output, registration, member, parentModel, variables, trustedPresets, [...path, 'members', index, member.field]);
+    }
+}
+export function compileBranchPlan(output, registration, branch, parentModel, variables, trustedPresets, path) {
+    const argumentsValue = resolveArguments(branch.arguments, variables, branch.coverage);
+    const targetModel = selectionModel(branch.selection);
+    output.push(plan({
+        registration,
+        kind: branch.semantic === 'relationship' ? 'relationship' : 'snapshot',
+        parentModel,
+        targetModel,
+        field: branch.field,
+        arguments: argumentsValue,
+        dependencies: branch.dependencies,
+        cardinality: branch.cardinality,
+        filter: branch.filter,
+        order: branch.order,
+        pagination: branch.pagination,
+        coverage: branch.coverage,
+        relationship: branch.relationship,
+        variables,
+        trustedPresets,
+        path
+    }));
+    compileSelectionPlans(output, registration, branch.selection, targetModel ?? parentModel, variables, trustedPresets, path);
+}
+export function plan(value) {
+    const signature = canonicalValue({
+        kind: value.kind,
+        parentModel: value.parentModel ?? null,
+        targetModel: value.targetModel ?? null,
+        field: value.field,
+        arguments: value.arguments,
+        dependencies: [...value.dependencies].sort(compareCodeUnits),
+        cardinality: value.cardinality,
+        filter: value.filter ?? null,
+        order: value.order ?? null,
+        pagination: value.pagination ?? null,
+        coverage: value.coverage ?? null,
+        relationship: value.relationship ?? null,
+        trustedPresets: value.trustedPresets
+    });
+    return Object.freeze({
+        ...value,
+        arguments: cloneRecord(value.arguments),
+        dependencies: Object.freeze([...new Set(value.dependencies)].sort(compareCodeUnits)),
+        trustedPresets: Object.freeze(value.trustedPresets.map((descriptor) => Object.freeze({ name: descriptor.name, codec: descriptor.codec }))),
+        path: Object.freeze([...value.path]),
+        signature
+    });
+}
+export function selectionModel(selection) {
+    return selection.storage.kind === 'normalized'
+        ? selection.storage.model
+        : undefined;
+}
+export function instantiatePlans(plans, indexes) {
+    const result = new Map();
+    for (const value of plans) {
+        if (value.exactIndexKey !== undefined) {
+            if (indexes.has(value.exactIndexKey)) {
+                appendPlan(result, value.exactIndexKey, value);
+            }
+            continue;
+        }
+        for (const index of indexes.values()) {
+            const parent = index.metadata.parent;
+            if (parent === undefined ||
+                index.metadata.field !== value.field ||
+                replicaIndexKey({
+                    parent,
+                    field: value.field,
+                    arguments: value.arguments
+                }) !== index.key ||
+                (value.parentModel !== undefined &&
+                    !recordKeyMatchesModel(parent, value.parentModel))) {
+                continue;
+            }
+            appendPlan(result, index.key, value);
+        }
+    }
+    return result;
+}
+export function appendPlan(output, key, value) {
+    const current = output.get(key) ?? [];
+    if (current.some((candidate) => candidate.registration === value.registration &&
+        candidate.signature === value.signature)) {
+        return;
+    }
+    current.push(value);
+    output.set(key, current);
+}
+export function applyLayers(base, layers) {
+    const records = new Map();
+    for (const input of base) {
+        validateName(input.key, 'record key');
+        validateName(input.model, 'record model');
+        if (records.has(input.key)) {
+            throw new TypeError(`duplicate maintenance record: ${input.key}`);
+        }
+        records.set(input.key, {
+            key: input.key,
+            model: input.model,
+            fields: { ...input.fields }
+        });
+    }
+    const baseRecords = new Map([...records].map(([key, record]) => [
+        key,
+        {
+            key: record.key,
+            model: record.model,
+            fields: { ...record.fields }
+        }
+    ]));
+    const recordChanges = [];
+    const relationshipChanges = [];
+    const invalidatedDependencies = new Set();
+    const allDependencies = new Set();
+    const layerIds = new Set();
+    for (const layer of layers) {
+        validateName(layer.id, 'semantic layer id');
+        if (layerIds.has(layer.id)) {
+            throw new TypeError(`duplicate semantic layer: ${layer.id}`);
+        }
+        layerIds.add(layer.id);
+        for (const change of layer.changes) {
+            if (change.kind === 'invalidate') {
+                for (const dependency of validateDependencies(change.dependencies)) {
+                    invalidatedDependencies.add(dependency);
+                    allDependencies.add(dependency);
+                }
+                continue;
+            }
+            if (isRelationshipChange(change)) {
+                validateName(change.sourceModel, 'relationship source model');
+                validateName(change.field, 'relationship field');
+                validateName(change.targetModel, 'relationship target model');
+                validateName(change.sourceKey, 'relationship source key');
+                validateName(change.targetKey, 'relationship target key');
+                for (const dependency of validateDependencies(change.dependencies)) {
+                    allDependencies.add(dependency);
+                }
+                relationshipChanges.push(change);
+                continue;
+            }
+            validateName(change.model, 'record change model');
+            validateName(change.key, 'record change key');
+            for (const dependency of validateDependencies(change.dependencies ?? [])) {
+                allDependencies.add(dependency);
+            }
+            recordChanges.push(change);
+            if (change.kind === 'delete') {
+                records.delete(change.key);
+                continue;
+            }
+            const current = records.get(change.key);
+            if (current !== undefined && current.model !== change.model) {
+                throw new TypeError(`record model changed for ${change.key}`);
+            }
+            records.set(change.key, {
+                key: change.key,
+                model: change.model,
+                fields: { ...(current?.fields ?? {}), ...change.fields }
+            });
+        }
+    }
+    return {
+        baseRecords,
+        records,
+        recordChanges: Object.freeze(recordChanges),
+        relationshipChanges: Object.freeze(relationshipChanges),
+        invalidatedDependencies,
+        allDependencies
+    };
+}
+export function validateIndexes(input) {
+    const indexes = new Map();
+    for (const index of input) {
+        validateName(index.key, 'index key');
+        if (indexes.has(index.key)) {
+            throw new TypeError(`duplicate maintenance index: ${index.key}`);
+        }
+        indexes.set(index.key, index);
+    }
+    return indexes;
+}
+export function planAffected(planValue, index, changes) {
+    if (planValue.kind === 'snapshot' &&
+        intersects(planValue.dependencies, changes.allDependencies)) {
+        return true;
+    }
+    if (intersects(planValue.dependencies, changes.invalidatedDependencies)) {
+        return true;
+    }
+    if (planValue.targetModel !== undefined &&
+        changes.recordChanges.some(({ model }) => model === planValue.targetModel)) {
+        return true;
+    }
+    if (planValue.kind === 'relationship' &&
+        planValue.parentModel !== undefined &&
+        changes.recordChanges.some((change) => parentRecordChangeAffectsRelationship(planValue, index, change))) {
+        return true;
+    }
+    return changes.relationshipChanges.some((change) => relationshipChangeMatches(planValue, index, change));
+}
+export function evaluatePlan(planValue, index, changes, trustedPresets) {
+    if (planValue.kind === 'snapshot') {
+        return stale(index.key, reason('aggregate_dependency_changed', planValue.path, 'an aggregate or embedded query snapshot dependency changed'));
+    }
+    if (intersects(planValue.dependencies, changes.invalidatedDependencies)) {
+        return stale(index.key, reason('dependency_changed', planValue.path, 'a declared dependency changed without locally provable row evidence'));
+    }
+    /*
+     * Freshness and structure are independent. Revalidation deliberately marks
+     * a complete index stale while retaining its last authoritative membership.
+     * Pending semantic layers must keep rebasing over that membership; the
+     * derived write preserves the stale metadata until the network result lands.
+     */
+    if (!index.complete) {
+        return stale(index.key, reason('index_incomplete', ['indexes', index.key], 'only a structurally complete index can be maintained locally'));
+    }
+    if (planValue.cardinality !== 'many') {
+        const targetChanges = changes.recordChanges.filter((change) => change.model === planValue.targetModel);
+        if (changes.relationshipChanges.length === 0 &&
+            targetChanges.length > 0 &&
+            targetChanges.every((change) => change.kind === 'upsert' && index.records.includes(change.key))) {
+            // Updating fields on the already-selected singular identity cannot
+            // change that index's membership. The sparse record dependency will
+            // still publish selected field changes to the UI.
+            return unchanged(index.key);
+        }
+        return stale(index.key, reason('unsupported_cardinality', planValue.path, 'local query-index maintenance is limited to collection fields'));
+    }
+    if (index.metadata.field !== planValue.field ||
+        !sameValue(index.metadata.arguments, planValue.arguments)) {
+        return stale(index.key, reason('invalid_index_metadata', ['indexes', index.key], 'stored index metadata does not match its compiler plan'));
+    }
+    const duplicate = firstDuplicate(index.records);
+    if (duplicate !== undefined) {
+        return stale(index.key, reason('duplicate_index_record', ['indexes', index.key], `stored index contains duplicate record ${duplicate}`));
+    }
+    if (planValue.kind === 'relationship' &&
+        planValue.relationship?.maintenance !== 'local') {
+        return stale(index.key, reason('relationship_maintenance_revalidate', planValue.path, 'the compiler marked this relationship as revalidation-only'));
+    }
+    return maintainEntityIndex(planValue, index, changes, trustedPresets);
+}
+export function maintainEntityIndex(planValue, index, changes, trustedPresets) {
+    const current = [...index.records];
+    const members = new Set(current);
+    const candidates = new Set();
+    for (const change of changes.recordChanges) {
+        if (change.model === planValue.targetModel)
+            candidates.add(change.key);
+    }
+    const relationshipOverrides = new Map();
+    if (planValue.kind === 'relationship') {
+        const parentChanged = changes.recordChanges.some((change) => parentRecordChangeAffectsRelationship(planValue, index, change));
+        if (parentChanged) {
+            return stale(index.key, reason('relationship_mapping_unknown', planValue.path, 'a parent-key dependency changed and sparse target coverage cannot prove the new relationship'));
+        }
+        for (const change of changes.relationshipChanges) {
+            if (!relationshipChangeMatches(planValue, index, change))
+                continue;
+            const missing = planValue.relationship.dependencies.filter((dependency) => !change.dependencies.includes(dependency));
+            if (missing.length > 0) {
+                return stale(index.key, reason('relationship_dependency_missing', planValue.path, `relationship change omits declared dependencies: ${missing.join(', ')}`));
+            }
+            candidates.add(change.targetKey);
+            relationshipOverrides.set(change.targetKey, change.kind === 'link');
+        }
+    }
+    let inserted = false;
+    let removed = false;
+    for (const key of candidates) {
+        const record = changes.records.get(key);
+        let related = true;
+        if (planValue.kind === 'relationship') {
+            const override = relationshipOverrides.get(key);
+            if (override !== undefined) {
+                related = override;
+            }
+            else if (members.has(key)) {
+                related = true;
+            }
+            else {
+                const relation = relationshipMembership(planValue, index, record, changes.records);
+                if ('reason' in relation)
+                    return stale(index.key, relation.reason);
+                related = relation.related;
+            }
+        }
+        if (record === undefined || !related) {
+            if (members.delete(key))
+                removed = true;
+            continue;
+        }
+        const filter = evaluateMembership(planValue, record, trustedPresets);
+        if ('reason' in filter)
+            return stale(index.key, filter.reason);
+        if (filter.matches) {
+            if (!members.has(key)) {
+                members.add(key);
+                inserted = true;
+            }
+        }
+        else if (members.delete(key)) {
+            removed = true;
+        }
+    }
+    let activeOrderChanged = false;
+    if (planValue.order !== undefined) {
+        for (const key of candidates) {
+            if (!members.has(key))
+                continue;
+            const before = changes.baseRecords.get(key);
+            const after = changes.records.get(key);
+            if (before === undefined || after === undefined)
+                continue;
+            const compared = compareReplicaOrder(planValue.order, before.fields, after.fields, planValue.variables);
+            if (compared.result === 'unknown') {
+                return stale(index.key, compared.reason);
+            }
+            if (compared.result !== 'equal') {
+                activeOrderChanged = true;
+                break;
+            }
+        }
+    }
+    let records = current.filter((key) => members.has(key));
+    for (const key of members) {
+        if (!records.includes(key))
+            records.push(key);
+    }
+    const needsOrder = inserted || activeOrderChanged;
+    if (needsOrder) {
+        if (planValue.order === undefined && inserted) {
+            return stale(index.key, reason('missing_order_plan', planValue.path, 'an inserted record cannot be positioned without a compiler order plan'));
+        }
+        if (planValue.order !== undefined) {
+            const sorted = sortRecords(records, planValue.order, changes.records, planValue.variables, planValue.path);
+            if ('reason' in sorted)
+                return stale(index.key, sorted.reason);
+            records = [...sorted.records];
+        }
+    }
+    const reordered = !inserted &&
+        !removed &&
+        (activeOrderChanged || !sameStringList(records, current));
+    const changeKind = inserted
+        ? 'insert'
+        : removed
+            ? 'delete'
+            : reordered
+                ? 'reorder'
+                : 'stable_update';
+    if (planValue.pagination === undefined) {
+        if (changeKind === 'stable_update' &&
+            sameStringList(records, current)) {
+            // An uncertified collection can still prove a membership/order no-op;
+            // that stable update needs no index write or revalidation.
+            return unchanged(index.key);
+        }
+        return stale(index.key, reason('invalid_artifact', planValue.path, 'collection plan is missing its pagination maintenance contract'));
+    }
+    const coverageReason = certifyOffsetCoverage(planValue, index, current.length, changeKind);
+    if (coverageReason !== undefined) {
+        return stale(index.key, coverageReason);
+    }
+    const pagination = decideReplicaPaginationMaintenance(planValue.pagination, index.metadata.coverage, { kind: changeKind });
+    if (pagination.decision === 'revalidate') {
+        return stale(index.key, pagination.reason);
+    }
+    if (planValue.pagination.kind === 'offset' &&
+        index.metadata.coverage.kind === 'offset' &&
+        index.metadata.coverage.offset === 0 &&
+        index.metadata.coverage.limit !== undefined &&
+        records.length > index.metadata.coverage.limit) {
+        // Locality above is possible only because the base first page was
+        // non-full, so this is the complete optimistic ordered set. Preserve the
+        // operation's exact window when stacked optimistic inserts cross its
+        // limit.
+        records = records.slice(0, index.metadata.coverage.limit);
+    }
+    return sameStringList(records, current)
+        ? unchanged(index.key)
+        : write(index.key, records);
+}
+export function certifyOffsetCoverage(planValue, index, confirmedRecords, changeKind) {
+    if (planValue.pagination?.kind !== 'offset' ||
+        changeKind === 'stable_update') {
+        return undefined;
+    }
+    const artifact = planValue.coverage;
+    const coverage = index.metadata.coverage;
+    if (artifact?.kind !== 'offset' || coverage.kind !== 'offset') {
+        return reason('invalid_index_metadata', ['indexes', index.key, 'coverage'], 'offset pagination locality requires its exact compiler coverage contract');
+    }
+    const expectedOffset = artifact.offsetArgument === undefined
+        ? 0
+        : planValue.arguments[artifact.offsetArgument];
+    const configuredLimit = artifact.limitArgument === undefined
+        ? artifact.defaultLimit
+        : planValue.arguments[artifact.limitArgument];
+    const expectedLimit = typeof configuredLimit === 'number' &&
+        typeof artifact.maxLimit === 'number'
+        ? Math.min(configuredLimit, artifact.maxLimit)
+        : configuredLimit;
+    if (typeof expectedOffset !== 'number' ||
+        !Number.isSafeInteger(expectedOffset) ||
+        expectedOffset < 0 ||
+        (typeof expectedLimit !== 'number' &&
+            expectedLimit !== undefined) ||
+        (typeof expectedLimit === 'number' &&
+            (!Number.isSafeInteger(expectedLimit) || expectedLimit < 0)) ||
+        coverage.offset !== expectedOffset ||
+        coverage.limit !== expectedLimit ||
+        coverage.returned !== confirmedRecords ||
+        coverage.hasNext === true) {
+        return reason('invalid_index_metadata', ['indexes', index.key, 'coverage'], 'offset coverage does not match the request, confirmed index size, or observed page boundary');
+    }
+    return undefined;
+}
+export function parentRecordChangeAffectsRelationship(planValue, index, change) {
+    if (change.model !== planValue.parentModel ||
+        change.key !== index.metadata.parent) {
+        return false;
+    }
+    if (change.kind === 'delete')
+        return true;
+    const relationship = planValue.relationship;
+    if (relationship === undefined) {
+        // A forged relationship branch without its compiler-owned mapping must
+        // be evaluated and rejected instead of silently ignoring a parent change.
+        return true;
+    }
+    const mapping = relationship.keyMapping;
+    const mappingFields = mapping.kind === 'embedded' ? Object.freeze([]) : mapping.local;
+    if (mappingFields.some((field) => Object.prototype.hasOwnProperty.call(change.fields, field))) {
+        return true;
+    }
+    const dependencies = new Set(change.dependencies ?? []);
+    return relationship.dependencies.some((dependency) => dependencies.has(dependency));
+}
+export function relationshipMembership(planValue, index, target, records) {
+    if (target === undefined)
+        return { related: false };
+    const relationship = planValue.relationship;
+    const parentKey = index.metadata.parent;
+    if (relationship === undefined || parentKey === undefined) {
+        return {
+            reason: reason('relationship_mapping_unknown', planValue.path, 'relationship plan or parent identity is unavailable')
+        };
+    }
+    if (relationship.keyMapping.kind !== 'direct') {
+        return {
+            reason: reason('relationship_mapping_unknown', planValue.path, 'a non-member through/opaque relationship requires explicit link evidence')
+        };
+    }
+    const parent = records.get(parentKey);
+    if (parent === undefined) {
+        return {
+            reason: reason('missing_parent_record', planValue.path, 'relationship parent record is absent')
+        };
+    }
+    for (let indexValue = 0; indexValue < relationship.keyMapping.local.length; indexValue += 1) {
+        const local = relationship.keyMapping.local[indexValue];
+        const remote = relationship.keyMapping.remote[indexValue];
+        if (!Object.prototype.hasOwnProperty.call(parent.fields, local) ||
+            !Object.prototype.hasOwnProperty.call(target.fields, remote)) {
+            return {
+                reason: reason('missing_field', [...planValue.path, 'relationship', local, remote], 'relationship key fields are not completely present')
+            };
+        }
+        if (!sameValue(parent.fields[local], target.fields[remote])) {
+            return { related: false };
+        }
+    }
+    return { related: true };
+}
+export function evaluateMembership(planValue, record, trustedPresets) {
+    if (planValue.filter === undefined)
+        return { matches: true };
+    const evaluated = evaluateReplicaFilter(planValue.filter, record.fields, planValue.variables, {
+        trustedPresets: {
+            descriptors: planValue.trustedPresets,
+            values: trustedPresets
+        }
+    });
+    return evaluated.result === 'unknown'
+        ? { reason: evaluated.reason }
+        : { matches: evaluated.result === 'match' };
+}
+export function sortRecords(keys, order, records, variables, path) {
+    let unknown;
+    const sorted = [...keys].sort((leftKey, rightKey) => {
+        if (unknown !== undefined || leftKey === rightKey)
+            return 0;
+        const left = records.get(leftKey);
+        const right = records.get(rightKey);
+        if (left === undefined || right === undefined) {
+            unknown = reason('missing_index_record', path, `ordered index references missing record ${left === undefined ? leftKey : rightKey}`);
+            return 0;
+        }
+        const compared = compareReplicaOrder(order, left.fields, right.fields, variables);
+        if (compared.result === 'unknown') {
+            unknown = compared.reason;
+            return 0;
+        }
+        if (compared.result === 'equal') {
+            unknown = reason('non_unique_order', path, `distinct records ${leftKey} and ${rightKey} have no deterministic order`);
+            return 0;
+        }
+        return compared.result === 'less' ? -1 : 1;
+    });
+    return unknown === undefined
+        ? { records: Object.freeze(sorted) }
+        : { reason: unknown };
+}
+export function relationshipChangeMatches(planValue, index, change) {
+    return (planValue.kind === 'relationship' &&
+        planValue.parentModel === change.sourceModel &&
+        planValue.field === change.field &&
+        planValue.targetModel === change.targetModel &&
+        index.metadata.parent === change.sourceKey);
+}
+export function isRelationshipChange(change) {
+    return change.kind === 'link' || change.kind === 'unlink';
+}
+export function validateDependencies(value) {
+    if (!Array.isArray(value))
+        throw new TypeError('dependencies must be an array');
+    const seen = new Set();
+    for (const dependency of value) {
+        validateName(dependency, 'dependency');
+        if (seen.has(dependency)) {
+            throw new TypeError(`duplicate dependency: ${dependency}`);
+        }
+        seen.add(dependency);
+    }
+    return value;
+}
+export function intersects(left, right) {
+    return left.some((value) => right.has(value));
+}
+export function recordKeyMatchesModel(key, model) {
+    return key.startsWith(`record:${encodeURIComponent(model)}:`);
+}
+export function firstDuplicate(values) {
+    const seen = new Set();
+    for (const value of values) {
+        if (seen.has(value))
+            return value;
+        seen.add(value);
+    }
+    return undefined;
+}
+export function write(indexKey, records) {
+    return Object.freeze({
+        kind: 'write',
+        indexKey,
+        records: Object.freeze([...records]),
+        complete: true
+    });
+}
+export function stale(indexKey, reasonValue) {
+    return Object.freeze({
+        kind: 'stale',
+        indexKey,
+        reason: reasonValue
+    });
+}
+export function unchanged(indexKey) {
+    return Object.freeze({ kind: 'unchanged', indexKey });
+}
+export function reason(code, path, message) {
+    return Object.freeze({
+        code,
+        path: Object.freeze([...path]),
+        message
+    });
+}
+export function sameStringList(left, right) {
+    return (left.length === right.length &&
+        left.every((value, index) => value === right[index]));
+}
+export function sameValue(left, right) {
+    return canonicalValue(left) === canonicalValue(right);
+}
+export function cloneRecord(value) {
+    return Object.freeze(Object.fromEntries(Object.entries(value)
+        .sort(([left], [right]) => compareCodeUnits(left, right))
+        .map(([key, entry]) => [key, cloneValue(entry)])));
+}
+export function cloneValue(value) {
+    if (Array.isArray(value))
+        return Object.freeze(value.map(cloneValue));
+    if (value !== null && typeof value === 'object') {
+        return cloneRecord(value);
+    }
+    return value;
+}
+export function canonicalValue(value) {
+    if (value === null)
+        return 'null';
+    if (typeof value === 'string')
+        return JSON.stringify(value);
+    if (typeof value === 'boolean')
+        return value ? 'true' : 'false';
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value))
+            throw new TypeError('canonical values must be finite');
+        return Object.is(value, -0) ? '0' : JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map(canonicalValue).join(',')}]`;
+    }
+    if (typeof value === 'object') {
+        const entries = Object.entries(value)
+            .filter(([, entry]) => entry !== undefined)
+            .sort(([left], [right]) => compareCodeUnits(left, right));
+        return `{${entries
+            .map(([key, entry]) => `${JSON.stringify(key)}:${canonicalValue(entry)}`)
+            .join(',')}}`;
+    }
+    throw new TypeError('canonical values must be JSON-compatible');
+}
+export function validateName(value, description) {
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new TypeError(`${description} must be a non-empty string`);
+    }
+}

package/dist/replica/index-maintenance/implementation.d.ts

@@ -0,0 +1,4 @@
+/** Re-export surface for index-maintenance modules (body-split). */
+export * from './types.js';
+export * from './engine.js';
+export * from './registry.js';

package/dist/replica/index-maintenance/implementation.js

@@ -0,0 +1,4 @@
+/** Re-export surface for index-maintenance modules (body-split). */
+export * from './types.js';
+export * from './engine.js';
+export * from './registry.js';

package/dist/replica/index-maintenance/index.d.ts

@@ -0,0 +1,2 @@
+export { createReplicaIndexMaintenanceRegistry, formatReplicaIndexStaleReason } from './implementation.js';
+export type { ReplicaIndexDependencyChange, ReplicaIndexMaintenanceDecision, ReplicaIndexMaintenanceIndex, ReplicaIndexMaintenanceReason, ReplicaIndexMaintenanceReasonCode, ReplicaIndexMaintenanceRecord, ReplicaIndexMaintenanceRegistry, ReplicaIndexMaintenanceSnapshot, ReplicaIndexPlanRegistration, ReplicaIndexRecordChange, ReplicaIndexRelationshipChange, ReplicaIndexSemanticChange, ReplicaIndexSemanticLayer } from './implementation.js';