mongo-query-normalizer 0.1.0 → 0.2.1

package/dist/scope/rewrite/prune-impossible-branches.d.ts

@@ -0,0 +1,6 @@
+import type { QueryNode } from "../../ast/types";
+import type { ScopeTraceEvent } from "../../types";
+import type { ConstraintSet } from "../context/constraint-set";
+import type { ScopeSafetyPolicy } from "../safety/scope-safety-policy";
+export declare function pruneImpossibleOrBranch(branch: QueryNode, inherited: ConstraintSet, policy: ScopeSafetyPolicy, onTrace?: (event: ScopeTraceEvent) => void): QueryNode | null;
+//# sourceMappingURL=prune-impossible-branches.d.ts.map

package/dist/scope/rewrite/prune-impossible-branches.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prune-impossible-branches.d.ts","sourceRoot":"","sources":["../../../src/scope/rewrite/prune-impossible-branches.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAGvE,wBAAgB,uBAAuB,CACnC,MAAM,EAAE,SAAS,EACjB,SAAS,EAAE,aAAa,EACxB,MAAM,EAAE,iBAAiB,EACzB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,GAC3C,SAAS,GAAG,IAAI,CAyBlB"}

package/dist/scope/rewrite/prune-impossible-branches.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pruneImpossibleOrBranch = pruneImpossibleOrBranch;
+const builders_1 = require("../../ast/builders");
+const analyze_branch_satisfiability_1 = require("../analysis/analyze-branch-satisfiability");
+function pruneImpossibleOrBranch(branch, inherited, policy, onTrace) {
+    if (!policy.allowBranchPruning || !policy.allowOrPropagation) {
+        onTrace?.({
+            type: "prune-branch",
+            outcome: "skipped-by-policy",
+            detail: "branch pruning or $or propagation disabled by scope safety policy",
+        });
+        return null;
+    }
+    const explained = (0, analyze_branch_satisfiability_1.explainBranchSatisfiability)(branch, inherited, policy);
+    onTrace?.({
+        type: "or-branch-inherited",
+        satisfiabilityCheck: "ran",
+        satisfiable: explained.satisfiable,
+        detail: explained.reason,
+    });
+    if (!explained.satisfiable) {
+        onTrace?.({
+            type: "prune-branch",
+            outcome: "pruned-to-false",
+            detail: explained.reason,
+        });
+        return (0, builders_1.falseNode)();
+    }
+    return null;
+}
+//# sourceMappingURL=prune-impossible-branches.js.map

package/dist/scope/rewrite/prune-impossible-branches.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prune-impossible-branches.js","sourceRoot":"","sources":["../../../src/scope/rewrite/prune-impossible-branches.ts"],"names":[],"mappings":";;AAOA,0DA8BC;AArCD,iDAA+C;AAK/C,6FAAwF;AAExF,SAAgB,uBAAuB,CACnC,MAAiB,EACjB,SAAwB,EACxB,MAAyB,EACzB,OAA0C;IAE1C,IAAI,CAAC,MAAM,CAAC,kBAAkB,IAAI,CAAC,MAAM,CAAC,kBAAkB,EAAE,CAAC;QAC3D,OAAO,EAAE,CAAC;YACN,IAAI,EAAE,cAAc;YACpB,OAAO,EAAE,mBAAmB;YAC5B,MAAM,EAAE,mEAAmE;SAC9E,CAAC,CAAC;QACH,OAAO,IAAI,CAAC;IAChB,CAAC;IACD,MAAM,SAAS,GAAG,IAAA,2DAA2B,EAAC,MAAM,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC;IACzE,OAAO,EAAE,CAAC;QACN,IAAI,EAAE,qBAAqB;QAC3B,mBAAmB,EAAE,KAAK;QAC1B,WAAW,EAAE,SAAS,CAAC,WAAW;QAClC,MAAM,EAAE,SAAS,CAAC,MAAM;KAC3B,CAAC,CAAC;IACH,IAAI,CAAC,SAAS,CAAC,WAAW,EAAE,CAAC;QACzB,OAAO,EAAE,CAAC;YACN,IAAI,EAAE,cAAc;YACpB,OAAO,EAAE,iBAAiB;YAC1B,MAAM,EAAE,SAAS,CAAC,MAAM;SAC3B,CAAC,CAAC;QACH,OAAO,IAAA,oBAAS,GAAE,CAAC;IACvB,CAAC;IACD,OAAO,IAAI,CAAC;AAChB,CAAC"}

package/dist/scope/rewrite/remove-covered-local-constraints.d.ts

@@ -0,0 +1,6 @@
+import type { QueryNode } from "../../ast/types";
+import type { ScopeTraceEvent } from "../../types";
+import type { ConstraintSet } from "../context/constraint-set";
+import type { ScopeSafetyPolicy } from "../safety/scope-safety-policy";
+export declare function removeCoveredLocalConstraints(branch: QueryNode, inherited: ConstraintSet, policy: ScopeSafetyPolicy, onTrace?: (event: ScopeTraceEvent) => void): QueryNode;
+//# sourceMappingURL=remove-covered-local-constraints.d.ts.map

package/dist/scope/rewrite/remove-covered-local-constraints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"remove-covered-local-constraints.d.ts","sourceRoot":"","sources":["../../../src/scope/rewrite/remove-covered-local-constraints.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAa,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC/D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAavE,wBAAgB,6BAA6B,CACzC,MAAM,EAAE,SAAS,EACjB,SAAS,EAAE,aAAa,EACxB,MAAM,EAAE,iBAAiB,EACzB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,GAC3C,SAAS,CA8DX"}

package/dist/scope/rewrite/remove-covered-local-constraints.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.removeCoveredLocalConstraints = removeCoveredLocalConstraints;
+const builders_1 = require("../../ast/builders");
+const guards_1 = require("../../ast/guards");
+const value_equality_1 = require("../../predicate/utils/value-equality");
+function isSingleEqField(node) {
+    if (node.predicates.length !== 1) {
+        return null;
+    }
+    const p = node.predicates[0];
+    if (p.op === "$eq" || (!p.opaque && p.op === "$eq")) {
+        return { value: p.value };
+    }
+    return null;
+}
+function removeCoveredLocalConstraints(branch, inherited, policy, onTrace) {
+    if (!policy.allowConstraintCoverageElimination) {
+        onTrace?.({
+            type: "coverage-removal",
+            outcome: "unchanged",
+            detail: "coverage elimination disabled by scope safety policy",
+        });
+        return branch;
+    }
+    if (policy.bailoutOnUnsupportedScopeMix && inherited.metadata.hasUnsupportedSemantics) {
+        onTrace?.({
+            type: "coverage-removal",
+            outcome: "unchanged",
+            detail: "preserve: inherited constraints flagged unsupported for scope mix bailout",
+        });
+        return branch;
+    }
+    if (!(0, guards_1.isFieldNode)(branch)) {
+        onTrace?.({
+            type: "coverage-removal",
+            outcome: "unchanged",
+            detail: "not a field leaf; no single-field coverage strip",
+        });
+        return branch;
+    }
+    const inheritedAtoms = inherited.byField.get(branch.field) ?? [];
+    const eqInherited = inheritedAtoms.find((a) => a.kind === "eq");
+    if (!eqInherited || eqInherited.kind !== "eq") {
+        onTrace?.({
+            type: "coverage-removal",
+            outcome: "unchanged",
+            detail: "no inherited eq constraint on this field",
+        });
+        return branch;
+    }
+    const localEq = isSingleEqField(branch);
+    if (!localEq) {
+        onTrace?.({
+            type: "coverage-removal",
+            outcome: "unchanged",
+            detail: "local field is not a single $eq; conservative preserve",
+        });
+        return branch;
+    }
+    if (!(0, value_equality_1.valuesEqual)(eqInherited.value, localEq.value)) {
+        onTrace?.({
+            type: "coverage-removal",
+            outcome: "unchanged",
+            detail: "local $eq differs from inherited $eq",
+        });
+        return branch;
+    }
+    onTrace?.({
+        type: "coverage-removal",
+        outcome: "replaced-with-true",
+        detail: "local $eq redundant with inherited $eq on same field",
+    });
+    return (0, builders_1.trueNode)();
+}
+//# sourceMappingURL=remove-covered-local-constraints.js.map

package/dist/scope/rewrite/remove-covered-local-constraints.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"remove-covered-local-constraints.js","sourceRoot":"","sources":["../../../src/scope/rewrite/remove-covered-local-constraints.ts"],"names":[],"mappings":"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"}

package/dist/scope/safety/scope-safety-policy.d.ts

@@ -0,0 +1,10 @@
+export type ScopeSafetyPolicy = {
+    allowBranchPruning: boolean;
+    allowConstraintCoverageElimination: boolean;
+    allowSingleBranchCollapse: boolean;
+    allowOrPropagation: boolean;
+    allowAndPropagation: boolean;
+    bailoutOnUnsupportedScopeMix: boolean;
+};
+export declare const DEFAULT_SCOPE_SAFETY_POLICY: ScopeSafetyPolicy;
+//# sourceMappingURL=scope-safety-policy.d.ts.map

package/dist/scope/safety/scope-safety-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-safety-policy.d.ts","sourceRoot":"","sources":["../../../src/scope/safety/scope-safety-policy.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,iBAAiB,GAAG;IAC5B,kBAAkB,EAAE,OAAO,CAAC;IAC5B,kCAAkC,EAAE,OAAO,CAAC;IAC5C,yBAAyB,EAAE,OAAO,CAAC;IACnC,kBAAkB,EAAE,OAAO,CAAC;IAC5B,mBAAmB,EAAE,OAAO,CAAC;IAC7B,4BAA4B,EAAE,OAAO,CAAC;CACzC,CAAC;AAEF,eAAO,MAAM,2BAA2B,EAAE,iBAOzC,CAAC"}

package/dist/scope/safety/scope-safety-policy.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_SCOPE_SAFETY_POLICY = void 0;
+exports.DEFAULT_SCOPE_SAFETY_POLICY = {
+    allowBranchPruning: true,
+    allowConstraintCoverageElimination: true,
+    allowSingleBranchCollapse: true,
+    allowOrPropagation: true,
+    allowAndPropagation: true,
+    bailoutOnUnsupportedScopeMix: true,
+};
+//# sourceMappingURL=scope-safety-policy.js.map

package/dist/scope/safety/scope-safety-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-safety-policy.js","sourceRoot":"","sources":["../../../src/scope/safety/scope-safety-policy.ts"],"names":[],"mappings":";;;AASa,QAAA,2BAA2B,GAAsB;IAC1D,kBAAkB,EAAE,IAAI;IACxB,kCAAkC,EAAE,IAAI;IACxC,yBAAyB,EAAE,IAAI;IAC/B,kBAAkB,EAAE,IAAI;IACxB,mBAAmB,EAAE,IAAI;IACzB,4BAA4B,EAAE,IAAI;CACrC,CAAC"}

package/dist/types.d.ts

@@ -1,8 +1,11 @@
+import type { PredicateSafetyPolicy } from "./predicate/safety/predicate-safety-policy";
+import type { ScopeSafetyPolicy } from "./scope/safety/scope-safety-policy";
+import type { ConstraintExtractionRejection } from "./scope/context/constraint-set";
 /**
  * MongoDB 查询对象（规范化入口的输入/输出形状）
  */
 export type Query = Record<string, unknown>;
-export type NormalizeLevel = "shape" | "predicate" | "logical" | "experimental";
+export type NormalizeLevel = "shape" | "predicate" | "scope";
 export interface NormalizeRules {
     flattenLogical: boolean;
     removeEmptyLogical: boolean;
@@ -14,7 +17,6 @@ export interface NormalizeRules {
     sortLogicalChildren: boolean;
     sortFieldPredicates: boolean;
     detectCommonPredicatesInOr: boolean;
-    hoistCommonPredicatesFromOr: boolean;
 }
 export interface NormalizeSafety {
     maxNormalizeDepth: number;
@@ -23,18 +25,36 @@ export interface NormalizeSafety {
 export interface NormalizeObserve {
     collectWarnings: boolean;
     collectMetrics: boolean;
+    /** When true, `meta.predicateTraces` lists per-field planner and skip signals. */
+    collectPredicateTraces: boolean;
+    /** When true, `meta.scopeTrace` records propagation / prune / coverage decisions. */
+    collectScopeTraces: boolean;
+}
+export interface NormalizePredicateOptions {
+    safetyPolicy: PredicateSafetyPolicy;
+}
+export interface NormalizeScopeLayerOptions {
+    safetyPolicy: ScopeSafetyPolicy;
 }
 export interface NormalizeOptions {
     level?: NormalizeLevel;
     rules?: Partial<NormalizeRules>;
     safety?: Partial<NormalizeSafety>;
     observe?: Partial<NormalizeObserve>;
+    predicate?: {
+        safetyPolicy?: Partial<PredicateSafetyPolicy>;
+    };
+    scope?: {
+        safetyPolicy?: Partial<ScopeSafetyPolicy>;
+    };
 }
 export interface ResolvedNormalizeOptions {
     level: NormalizeLevel;
     rules: NormalizeRules;
     safety: NormalizeSafety;
     observe: NormalizeObserve;
+    predicate: NormalizePredicateOptions;
+    scope: NormalizeScopeLayerOptions;
 }
 export interface NodeStats {
     nodeCount: number;
@@ -44,6 +64,51 @@ export interface NodeStats {
 }
 /** 对外名称：`meta.stats` 中 before/after 的树统计。 */
 export type NormalizeStats = NodeStats;
+export type PredicateCapabilitySkipTrace = {
+    id: string;
+    reason: string;
+};
+export type PredicateFieldTrace = {
+    field: string;
+    atomKinds: string[];
+    appliedCapabilityIds: string[];
+    skippedCapabilities: PredicateCapabilitySkipTrace[];
+    contradiction: boolean;
+    /** When set, identifies the capability that first reported local contradiction. */
+    contradictionCapabilityId?: string;
+    hadCoverage: boolean;
+    /** Number of predicate atoms removed as redundant (same round). */
+    coverageAtomCount: number;
+    hadTighten: boolean;
+    /** True when this field normalized to an unsatisfiable selector (FalseNode → IMPOSSIBLE_SELECTOR). */
+    impossibleEmitted: boolean;
+};
+export type ScopeTraceEvent = {
+    type: "or-branch-inherited";
+    satisfiabilityCheck: "skipped" | "ran";
+    satisfiable?: boolean;
+    detail: string;
+} | {
+    type: "prune-branch";
+    outcome: "pruned-to-false" | "skipped-by-policy";
+    detail: string;
+} | {
+    type: "coverage-removal";
+    outcome: "replaced-with-true" | "unchanged";
+    detail: string;
+} | {
+    type: "collapse-or";
+    outcome: "collapsed-single-child" | "unchanged";
+    detail: string;
+} | {
+    type: "and-propagation";
+    outcome: "applied" | "skipped-by-policy";
+    detail: string;
+};
+export type ScopeNormalizationTrace = {
+    constraintRejections: ConstraintExtractionRejection[];
+    events: ScopeTraceEvent[];
+};
 export interface NormalizeMeta {
     changed: boolean;
     level: NormalizeLevel;
@@ -58,6 +123,8 @@ export interface NormalizeMeta {
         before: NodeStats;
         after: NodeStats;
     };
+    predicateTraces?: PredicateFieldTrace[];
+    scopeTrace?: ScopeNormalizationTrace;
 }
 export interface NormalizeResult<Q = Query> {
     query: Q;
@@ -66,5 +133,6 @@ export interface NormalizeResult<Q = Query> {
 /**
  * FalseNode 编译结果：不可满足选择器（与设计文档一致）
  */
+/** Canonical unsatisfiable filter: no document has a missing top-level `_id` in normal collections. */
 export declare const IMPOSSIBLE_SELECTOR: Query;
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE5C,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,WAAW,GAAG,SAAS,GAAG,cAAc,CAAC;AAEhF,MAAM,WAAW,cAAc;IAC3B,cAAc,EAAE,OAAO,CAAC;IACxB,kBAAkB,EAAE,OAAO,CAAC;IAC5B,0BAA0B,EAAE,OAAO,CAAC;IACpC,qBAAqB,EAAE,OAAO,CAAC;IAC/B,yBAAyB,EAAE,OAAO,CAAC;IACnC,yBAAyB,EAAE,OAAO,CAAC;IACnC,sBAAsB,EAAE,OAAO,CAAC;IAChC,mBAAmB,EAAE,OAAO,CAAC;IAC7B,mBAAmB,EAAE,OAAO,CAAC;IAC7B,0BAA0B,EAAE,OAAO,CAAC;IACpC,2BAA2B,EAAE,OAAO,CAAC;CACxC;AAED,MAAM,WAAW,eAAe;IAC5B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,kBAAkB,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,gBAAgB;IAC7B,eAAe,EAAE,OAAO,CAAC;IACzB,cAAc,EAAE,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,gBAAgB;IAC7B,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB,KAAK,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC;IAChC,MAAM,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC;IAClC,OAAO,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAC;CACvC;AAED,MAAM,WAAW,wBAAwB;IACrC,KAAK,EAAE,cAAc,CAAC;IACtB,KAAK,EAAE,cAAc,CAAC;IACtB,MAAM,EAAE,eAAe,CAAC;IACxB,OAAO,EAAE,gBAAgB,CAAC;CAC7B;AAED,MAAM,WAAW,SAAS;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACnB;AAED,6CAA6C;AAC7C,MAAM,MAAM,cAAc,GAAG,SAAS,CAAC;AAEvC,MAAM,WAAW,aAAa;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,cAAc,CAAC;IACtB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE;QACJ,MAAM,EAAE,SAAS,CAAC;QAClB,KAAK,EAAE,SAAS,CAAC;KACpB,CAAC;CACL;AAED,MAAM,WAAW,eAAe,CAAC,CAAC,GAAG,KAAK;IACtC,KAAK,EAAE,CAAC,CAAC;IACT,IAAI,EAAE,aAAa,CAAC;CACvB;AAED;;GAEG;AACH,eAAO,MAAM,mBAAmB,EAAE,KAA2C,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,4CAA4C,CAAC;AACxF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oCAAoC,CAAC;AAC5E,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,gCAAgC,CAAC;AAEpF;;GAEG;AACH,MAAM,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE5C,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,WAAW,GAAG,OAAO,CAAC;AAE7D,MAAM,WAAW,cAAc;IAC3B,cAAc,EAAE,OAAO,CAAC;IACxB,kBAAkB,EAAE,OAAO,CAAC;IAC5B,0BAA0B,EAAE,OAAO,CAAC;IACpC,qBAAqB,EAAE,OAAO,CAAC;IAC/B,yBAAyB,EAAE,OAAO,CAAC;IACnC,yBAAyB,EAAE,OAAO,CAAC;IACnC,sBAAsB,EAAE,OAAO,CAAC;IAChC,mBAAmB,EAAE,OAAO,CAAC;IAC7B,mBAAmB,EAAE,OAAO,CAAC;IAC7B,0BAA0B,EAAE,OAAO,CAAC;CACvC;AAED,MAAM,WAAW,eAAe;IAC5B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,kBAAkB,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,gBAAgB;IAC7B,eAAe,EAAE,OAAO,CAAC;IACzB,cAAc,EAAE,OAAO,CAAC;IACxB,kFAAkF;IAClF,sBAAsB,EAAE,OAAO,CAAC;IAChC,qFAAqF;IACrF,kBAAkB,EAAE,OAAO,CAAC;CAC/B;AAED,MAAM,WAAW,yBAAyB;IACtC,YAAY,EAAE,qBAAqB,CAAC;CACvC;AAED,MAAM,WAAW,0BAA0B;IACvC,YAAY,EAAE,iBAAiB,CAAC;CACnC;AAED,MAAM,WAAW,gBAAgB;IAC7B,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB,KAAK,CAAC,EAAE,OAAO,CAAC,cAAc,CAAC,CAAC;IAChC,MAAM,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,CAAC;IAClC,OAAO,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAC;IACpC,SAAS,CAAC,EAAE;QACR,YAAY,CAAC,EAAE,OAAO,CAAC,qBAAqB,CAAC,CAAC;KACjD,CAAC;IACF,KAAK,CAAC,EAAE;QACJ,YAAY,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAC;KAC7C,CAAC;CACL;AAED,MAAM,WAAW,wBAAwB;IACrC,KAAK,EAAE,cAAc,CAAC;IACtB,KAAK,EAAE,cAAc,CAAC;IACtB,MAAM,EAAE,eAAe,CAAC;IACxB,OAAO,EAAE,gBAAgB,CAAC;IAC1B,SAAS,EAAE,yBAAyB,CAAC;IACrC,KAAK,EAAE,0BAA0B,CAAC;CACrC;AAED,MAAM,WAAW,SAAS;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACnB;AAED,6CAA6C;AAC7C,MAAM,MAAM,cAAc,GAAG,SAAS,CAAC;AAEvC,MAAM,MAAM,4BAA4B,GAAG;IACvC,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,oBAAoB,EAAE,MAAM,EAAE,CAAC;IAC/B,mBAAmB,EAAE,4BAA4B,EAAE,CAAC;IACpD,aAAa,EAAE,OAAO,CAAC;IACvB,mFAAmF;IACnF,yBAAyB,CAAC,EAAE,MAAM,CAAC;IACnC,WAAW,EAAE,OAAO,CAAC;IACrB,mEAAmE;IACnE,iBAAiB,EAAE,MAAM,CAAC;IAC1B,UAAU,EAAE,OAAO,CAAC;IACpB,sGAAsG;IACtG,iBAAiB,EAAE,OAAO,CAAC;CAC9B,CAAC;AAEF,MAAM,MAAM,eAAe,GACrB;IACI,IAAI,EAAE,qBAAqB,CAAC;IAC5B,mBAAmB,EAAE,SAAS,GAAG,KAAK,CAAC;IACvC,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;CAClB,GACD;IACI,IAAI,EAAE,cAAc,CAAC;IACrB,OAAO,EAAE,iBAAiB,GAAG,mBAAmB,CAAC;IACjD,MAAM,EAAE,MAAM,CAAC;CAClB,GACD;IACI,IAAI,EAAE,kBAAkB,CAAC;IACzB,OAAO,EAAE,oBAAoB,GAAG,WAAW,CAAC;IAC5C,MAAM,EAAE,MAAM,CAAC;CAClB,GACD;IACI,IAAI,EAAE,aAAa,CAAC;IACpB,OAAO,EAAE,wBAAwB,GAAG,WAAW,CAAC;IAChD,MAAM,EAAE,MAAM,CAAC;CAClB,GACD;IACI,IAAI,EAAE,iBAAiB,CAAC;IACxB,OAAO,EAAE,SAAS,GAAG,mBAAmB,CAAC;IACzC,MAAM,EAAE,MAAM,CAAC;CAClB,CAAC;AAER,MAAM,MAAM,uBAAuB,GAAG;IAClC,oBAAoB,EAAE,6BAA6B,EAAE,CAAC;IACtD,MAAM,EAAE,eAAe,EAAE,CAAC;CAC7B,CAAC;AAEF,MAAM,WAAW,aAAa;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,cAAc,CAAC;IACtB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE;QACJ,MAAM,EAAE,SAAS,CAAC;QAClB,KAAK,EAAE,SAAS,CAAC;KACpB,CAAC;IACF,eAAe,CAAC,EAAE,mBAAmB,EAAE,CAAC;IACxC,UAAU,CAAC,EAAE,uBAAuB,CAAC;CACxC;AAED,MAAM,WAAW,eAAe,CAAC,CAAC,GAAG,KAAK;IACtC,KAAK,EAAE,CAAC,CAAC;IACT,IAAI,EAAE,aAAa,CAAC;CACvB;AAED;;GAEG;AACH,uGAAuG;AACvG,eAAO,MAAM,mBAAmB,EAAE,KAA4C,CAAC"}

package/dist/types.js

@@ -4,5 +4,6 @@ exports.IMPOSSIBLE_SELECTOR = void 0;
 /**
  * FalseNode 编译结果：不可满足选择器（与设计文档一致）
  */
-exports.IMPOSSIBLE_SELECTOR = { $expr: { $eq: [1, 0] } };
+/** Canonical unsatisfiable filter: no document has a missing top-level `_id` in normal collections. */
+exports.IMPOSSIBLE_SELECTOR = { _id: { $exists: false } };
 //# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";;;AA4EA;;GAEG;AACU,QAAA,mBAAmB,GAAU,EAAE,KAAK,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAW,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";;;AA2JA;;GAEG;AACH,uGAAuG;AAC1F,QAAA,mBAAmB,GAAU,EAAE,GAAG,EAAE,EAAE,OAAO,EAAE,KAAK,EAAE,EAAW,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mongo-query-normalizer",
-  "version": "0.1.0",
-  "description": "Observable, level-based normalizer for MongoDB query objects. Defaults to conservative shape stabilization; higher levels are preview surfaces in v0.1.0. Predictable output and metadata—not planner optimization.",
+  "version": "0.2.1",
+  "description": "Observable, level-based normalizer for MongoDB query objects. Defaults to conservative shape stabilization; optional predicate and scope levels with documented contracts. Predictable output and metadata—not planner optimization.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
@@ -13,11 +13,13 @@
   "scripts": {
     "build": "tsc",
     "test": "npm run build && npm run test:unit && npm run test:semantic",
+    "test:api": "mocha \"test/api/**/*.test.js\"",
+    "test:levels": "mocha \"test/levels/**/*.test.js\" \"test/contracts/*.test.js\"",
     "test:unit": "mocha \"test/**/*.test.js\" --ignore \"test/semantic/**/*.test.js\" --ignore \"test/regression/**/*.test.js\" --ignore \"test/property/**/*.test.js\"",
     "test:semantic": "mocha --require ./test/helpers/mocha-semantic-hooks.js \"test/semantic/**/*.test.js\" \"test/regression/**/*.test.js\" \"test/property/**/*.test.js\"",
     "test:semantic:quick": "FC_SEED=42 FC_RUNS=45 mocha --require ./test/helpers/mocha-semantic-hooks.js \"test/semantic/**/*.test.js\" \"test/regression/**/*.test.js\" \"test/property/**/*.test.js\"",
     "test:semantic:ci": "FC_RUNS=200 FC_SEED=42 mocha --require ./test/helpers/mocha-semantic-hooks.js \"test/semantic/**/*.test.js\" \"test/regression/**/*.test.js\" \"test/property/**/*.test.js\"",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm test && npm run build"
   },
   "author": "",
   "license": "ISC",
@@ -48,4 +50,4 @@
     "mongodb-memory-server": "^11.0.1",
     "typescript": "^5.0.0"
   }
-}
+}