@d-zero/page-cluster 0.5.6 → 0.6.0

package/dist/merge-cross-block-clusters.js

@@ -118,6 +118,154 @@ export function computeQuorumCore(memberDistinctiveTokens) {
     }
     return union;
 }
+/**
+ * Minimum ratio a proposed merge's post-merge quorum-core size must retain,
+ * relative to the strongest lineage anchor on either side (see
+ * `anchorByRoot` in {@link filterMergesByCohesion}), or the merge is
+ * discarded.
+ *
+ * Chosen against `merge-cross-block-clusters.spec.ts`'s own fixtures, which
+ * bound both edges this value has to sit between:
+ * - "a hub unit does not absorb several mutually-unrelated units via
+ *   containment" needs a ratio *above* ~`0.3` to reject each absorption (the
+ *   hub's own 10-token core collapses to the 3 tokens the absorbed unit
+ *   happens to also carry).
+ * - the bundled `buildMirroredTemplateFixture` fixture (see
+ *   `resolve-page-cluster-keys.spec.ts`) needs a ratio *at or below* ~`0.8`
+ *   to keep merging every one of its genuine per-mirror units (the same
+ *   template, once per axis value) — above that, some legitimate mirrors
+ *   stop merging because a handful of per-page module drops (this fixture's
+ *   stand-in for optional-section variation) dip just far enough below a
+ *   stricter bar.
+ *
+ * `0.7` sits with margin inside `(0.3, 0.8]` rather than against either
+ * edge. This is a per-step ratio, not an absolute floor — see
+ * `anchorByRoot`'s own JSDoc for why an anchor was needed at all, and for
+ * the residual limitation neither the ratio nor the anchor fixes: many
+ * originally-small-core units chained together one step at a time can each
+ * individually clear this ratio against the previous step's *already-small*
+ * anchor, so a long enough chain of naturally low-information pages can
+ * still end up merged even though no single step looks anomalous. Longer
+ * chains are exactly what {@link ./build-cluster-reason.js | ClusterReason}'s
+ * `blocking` array length and
+ * {@link ./compute-cluster-cohesion.js | computeClusterCohesion}'s
+ * `suspicious` flag are for — this guard reduces how often that happens and
+ * how far it goes, it does not claim to make it impossible.
+ */
+const MIN_COHESION_RATIO = 0.7;
+/**
+ * `computeQuorumCore` without its full-union fallback for empty cores. The
+ * fallback exists so a final `ClusterReason.structuralCoreTokens` is never
+ * empty for a genuinely tiny unit — but it makes core *size* useless as a
+ * cohesion signal: a merge that destroys every token's 80% quorum would
+ * silently read as "core size is now the size of the union", i.e. bigger,
+ * not smaller. {@link filterMergesByCohesion} needs "zero tokens survive
+ * quorum" to mean zero.
+ * @param memberDistinctiveTokens
+ */
+function strictQuorumCoreSize(memberDistinctiveTokens) {
+    const n = memberDistinctiveTokens.length;
+    if (n === 0)
+        return 0;
+    const minCount = Math.ceil(QUORUM_FRACTION * n);
+    const tokenCount = new Map();
+    for (const tokens of memberDistinctiveTokens) {
+        for (const token of tokens) {
+            tokenCount.set(token, (tokenCount.get(token) ?? 0) + 1);
+        }
+    }
+    let coreSize = 0;
+    for (const count of tokenCount.values()) {
+        if (count >= minCount)
+            coreSize++;
+    }
+    return coreSize;
+}
+/**
+ * Filters a round's proposed `[absorbed, root]` merges, rejecting any merge
+ * whose post-merge quorum core would collapse relative to the best core any
+ * single original unit now pooled into either side ever had — the guard
+ * against Stage B's fine/L2 stages successively absorbing unrelated units
+ * into a "catch-all" whose core shrinks toward shell-only tokens with every
+ * additional merge (each individual merge can look locally justified — the
+ * pair's *pre-merge* cores still overlap enough to clear
+ * `CROSS_BLOCK_THRESHOLD`/containment/L2 — while the *post-merge* core keeps
+ * shrinking, which none of those pre-merge checks observe).
+ *
+ * ## Why an anchor, not just the immediately preceding step
+ *
+ * An earlier version compared each merge only against the pool as it stood
+ * after the *previous* accepted merge for that root. That still lets a long
+ * chain erode a core to nothing, one acceptable-looking step at a time: if
+ * each step's ratio is checked only against the *result of the previous
+ * step*, and each step dilutes the pool a little, the reference the ratio is
+ * measured against keeps shrinking right along with the pool being measured
+ * — nothing ever compares the current state back to where the lineage
+ * started, so a chain of many individually-small erosions can compound into
+ * a total collapse no single step's check would have allowed on its own.
+ * `anchorByRoot` fixes this: every original unit's *own*, pre-any-merge core
+ * size (`anchorCoreSizeByKey`, computed once before the round loop) is
+ * carried forward — via `Math.max`, never re-derived from the current pool —
+ * as units merge into a root, so every later merge attempt is still measured
+ * against the strongest evidence its lineage ever had, not against
+ * whatever the lineage has been diluted to by the time of the attempt.
+ *
+ * Merges proposed for the same root are applied incrementally, in the order
+ * given, checking each one against the pool as it stood *after* the
+ * previously accepted merges for that root, so a chain of merges within a
+ * single call cannot each pass by being compared to a `pooled` state that
+ * never reflects the merges already accepted earlier in the same call.
+ *
+ * Two things intentionally do not gate rejection alone:
+ * - `strictQuorumCoreSize` is used instead of `computeQuorumCore`'s size —
+ *   see that function's own JSDoc for why the fallback would invert the
+ *   signal for exactly the merges this guard exists to catch.
+ * - A merge whose post-merge core size is `0` is always rejected, even when
+ *   the anchor was also `0` (which would make the ratio check
+ *   `0 >= ratio * 0` vacuously pass) — otherwise a unit that already lost
+ *   its own core would become a sink that absorbs anything with no further
+ *   resistance.
+ * @param proposedMerges `[absorbedKey, rootKey]` pairs, as produced by the
+ *   fine or L2 stage's own union-find pass.
+ * @param groupDistinctive This round's per-group distinctive token sets,
+ *   keyed by group key. Callers pass the class-name-stripped
+ *   `groupDistinctiveShaped` projection (see
+ *   {@link mergeCrossBlockClusters}'s own body) rather than raw
+ *   `groupDistinctive` — the fine stage's shape-Jaccard merges pair units
+ *   with disjoint raw tokens by construction, and a cohesion check against
+ *   raw tokens would reject every one of those merges outright.
+ * @param anchorByRoot Every current root's strongest lineage core size (see
+ *   above). Mutated in place: an accepted merge's root inherits
+ *   `Math.max(root's anchor, absorbed's anchor)`.
+ */
+function filterMergesByCohesion(proposedMerges, groupDistinctive, anchorByRoot) {
+    const byRoot = new Map();
+    for (const [absorbed, root] of proposedMerges) {
+        const list = byRoot.get(root);
+        if (list)
+            list.push(absorbed);
+        else
+            byRoot.set(root, [absorbed]);
+    }
+    const accepted = [];
+    for (const [root, absorbedKeys] of byRoot) {
+        let pooled = [...(groupDistinctive.get(root) ?? [])];
+        for (const absorbed of absorbedKeys) {
+            const absorbedTokens = groupDistinctive.get(absorbed) ?? [];
+            const candidatePool = [...pooled, ...absorbedTokens];
+            const candidateCoreSize = strictQuorumCoreSize(candidatePool);
+            const referenceCoreSize = Math.max(anchorByRoot.get(root) ?? strictQuorumCoreSize(pooled), anchorByRoot.get(absorbed) ?? strictQuorumCoreSize(absorbedTokens));
+            if (candidateCoreSize > 0 &&
+                candidateCoreSize >= MIN_COHESION_RATIO * referenceCoreSize) {
+                pooled = candidatePool;
+                anchorByRoot.set(root, referenceCoreSize);
+                anchorByRoot.delete(absorbed);
+                accepted.push([absorbed, root]);
+            }
+        }
+    }
+    return accepted;
+}
 /**
  *
  * @param core
@@ -164,6 +312,62 @@ function l2Contained(xSig, ySig) {
     }
     return true;
 }
+/**
+ * Canonical id for an `l2Signature`'s *shape* — its key set, ignoring the
+ * per-key counts — so {@link hasDiscriminatingL2Signatures} can tell whether
+ * two units reduced to the same vocabulary of `main`-anchored shapes,
+ * independent of how many pages contributed to each count.
+ * @param signature
+ */
+function l2SignatureShapeId(signature) {
+    return [...signature.keys()].toSorted().join('');
+}
+/**
+ * Minimum number of units an L2-degeneracy check requires before it will
+ * reject the whole comparison — below this, "every unit shares one shape"
+ * is unremarkable (there is nothing to discriminate between yet), not
+ * evidence the signature itself lacks resolving power.
+ */
+const MIN_L2_PARTICIPANTS_FOR_DEGENERACY_CHECK = 3;
+/**
+ * Whether this round's L2 signatures carry any discriminating power at all,
+ * checked once per round *before* running the `O(l2n²)` containment
+ * comparison rather than discovering it empirically pair by pair.
+ *
+ * `l2Signature` truncates to `main` plus up to 2 shape-stripped levels (see
+ * its own JSDoc); a corpus where the actual template content sits under a
+ * shared `main > article > <wrapper>` chain collapses every unit's
+ * signature to the exact same handful of keys (`main>article>*`, in the
+ * bundled `buildMirroredTemplateFixture` fixture's own case — see
+ * `merge-cross-block-clusters.spec.ts`), at which point `l2Contained`'s
+ * multiset containment degenerates into a plain count comparison with no
+ * structural meaning left. Rather than let that degenerate comparison run
+ * (and rely solely on {@link filterMergesByCohesion} to catch whatever it
+ * proposes), this is checked up front: if every participating unit reduces
+ * to the *same* shape, the signature has already lost all resolving power
+ * for this round, and comparing pairs is wasted work.
+ *
+ * Only total collapse (all participants share one shape) is detected —
+ * partial collapse (e.g. 8 units reducing to 2 shapes that don't line up
+ * with their true 8 templates) is not, and still relies on
+ * {@link filterMergesByCohesion} downstream.
+ * @param l2Keys
+ * @param getL2Sig
+ */
+function hasDiscriminatingL2Signatures(l2Keys, getL2Sig) {
+    const shapeIds = new Set();
+    let participantCount = 0;
+    for (const key of l2Keys) {
+        const sig = getL2Sig(key);
+        if (!sig)
+            continue;
+        participantCount++;
+        shapeIds.add(l2SignatureShapeId(sig));
+        if (shapeIds.size > 1)
+            return true;
+    }
+    return participantCount < MIN_L2_PARTICIPANTS_FOR_DEGENERACY_CHECK;
+}
 /**
  * Merges cross-block clusters (Stage B) via recursive quorum-core comparison.
  *
@@ -198,7 +402,11 @@ export function mergeCrossBlockClusters(units, options) {
             rootByKey: new Map(units.map((u) => [u.key, u.key])),
             finalGroupsByRoot: new Map(units.map((u) => [
                 u.key,
-                { tokenSets: u.memberTokenSets, landmarkInstances: u.memberLandmarkInstances },
+                {
+                    tokenSets: u.memberTokenSets,
+                    landmarkInstances: u.memberLandmarkInstances,
+                    pageIndices: u.memberPageIndices ?? u.memberTokenSets.map(() => -1),
+                },
             ])),
         };
     }
@@ -209,10 +417,26 @@ export function mergeCrossBlockClusters(units, options) {
         groups.set(unit.key, {
             tokenSets: [...unit.memberTokenSets],
             landmarkInstances: [...unit.memberLandmarkInstances],
+            pageIndices: [...(unit.memberPageIndices ?? unit.memberTokenSets.map(() => -1))],
         });
     }
     // Maps every original key to its current root (updated on each merge)
     const keyToRoot = new Map(units.map((u) => [u.key, u.key]));
+    // Each unit's own pre-any-merge core size, carried forward by
+    // `filterMergesByCohesion` as units merge — see that function's own
+    // JSDoc for why an anchor is needed at all. Computed the same way round
+    // 1's own `groupDistinctiveShaped` would (document frequency over the
+    // full initial unit set, then class-name-stripped), so a solo unit's
+    // anchor matches what the very first round would already compute for it.
+    const initialFrequency = computeDocumentFrequency(units.flatMap((u) => u.memberTokenSets));
+    const anchorByRoot = new Map(units.map((u) => {
+        const distinctiveShaped = u.memberTokenSets.map((tokens) => {
+            const { contentTokens } = splitTokensByFrequency(tokens, initialFrequency);
+            const distinctive = contentTokens.size > 0 ? contentTokens : tokens;
+            return new Set([...distinctive].map((t) => shapeToken(t)));
+        });
+        return [u.key, strictQuorumCoreSize(distinctiveShaped)];
+    }));
     /**
      * Applies a list of [absorbed, root] merges to `groups` and `keyToRoot`.
      * All absorbed groups' members are folded into their respective roots.
@@ -229,18 +453,21 @@ export function mergeCrossBlockClusters(units, options) {
                 ...rootG.landmarkInstances,
                 ...absorbedG.landmarkInstances,
             ];
+            const mergedPageIndices = [...rootG.pageIndices, ...absorbedG.pageIndices];
             // Only down-sample when the caller explicitly opts in (streaming
-            // path). Same-index sampling keeps memberTokenSets[i] and
-            // landmarkInstances[i] parallel.
+            // path). Same-index sampling keeps memberTokenSets[i],
+            // landmarkInstances[i], and pageIndices[i] parallel.
             if (capMembers !== undefined && mergedTokenSets.length > capMembers) {
                 const indices = mergedTokenSets.map((_, i) => i);
                 const kept = reservoirSample(indices, capMembers, root);
                 rootG.tokenSets = kept.map((i) => mergedTokenSets[i]);
                 rootG.landmarkInstances = kept.map((i) => mergedLandmarkInstances[i]);
+                rootG.pageIndices = kept.map((i) => mergedPageIndices[i]);
             }
             else {
                 rootG.tokenSets = mergedTokenSets;
                 rootG.landmarkInstances = mergedLandmarkInstances;
+                rootG.pageIndices = mergedPageIndices;
             }
             groups.delete(absorbed);
             for (const [origKey, cur] of keyToRoot) {
@@ -270,6 +497,18 @@ export function mergeCrossBlockClusters(units, options) {
             }
             groupDistinctive.set(key, dist);
         }
+        // Class-name-stripped projection of `groupDistinctive`, for
+        // {@link filterMergesByCohesion} only: the fine stage's own
+        // shape-Jaccard step (below) merges units whose *raw* tokens are
+        // disjoint by construction (same skeleton, different BEM class
+        // names — see `SHAPE_JACCARD_THRESHOLD`'s JSDoc), so a cohesion check
+        // against raw tokens would reject every shape-Jaccard merge outright.
+        // Shaping first lets the guard see that 'section.c-reports' and
+        // 'section.c-projects' both contribute to a shared 'section' token.
+        const groupDistinctiveShaped = new Map();
+        for (const [key, dist] of groupDistinctive) {
+            groupDistinctiveShaped.set(key, dist.map((tokens) => new Set([...tokens].map((t) => shapeToken(t)))));
+        }
         // Quorum core per group
         const cores = new Map();
         for (const key of groupKeys) {
@@ -367,8 +606,9 @@ export function mergeCrossBlockClusters(units, options) {
                 fineMerges.push([gk, rootKey]);
             }
         }
-        if (fineMerges.length > 0) {
-            applyMerges(fineMerges);
+        const acceptedFineMerges = filterMergesByCohesion(fineMerges, groupDistinctiveShaped, anchorByRoot);
+        if (acceptedFineMerges.length > 0) {
+            applyMerges(acceptedFineMerges);
             continue; // next round
         }
         // ---------------------------------------------------------------
@@ -393,6 +633,8 @@ export function mergeCrossBlockClusters(units, options) {
             }
             return shellCache.get(key) ?? new Set();
         };
+        if (!hasDiscriminatingL2Signatures(l2Keys, getL2Sig))
+            break;
         // Collect valid L2 containment pairs and apply via union-find
         // Direction: x is contained in y → x is absorbed by y
         // Multiple pairs can apply in one round if they form consistent groups
@@ -455,13 +697,18 @@ export function mergeCrossBlockClusters(units, options) {
                 l2Merges.push([gk, rootKey]);
             }
         }
-        if (l2Merges.length === 0)
-            break; // fully converged
-        applyMerges(l2Merges);
+        const acceptedL2Merges = filterMergesByCohesion(l2Merges, groupDistinctiveShaped, anchorByRoot);
+        if (acceptedL2Merges.length === 0)
+            break; // fully converged (or every proposal was rejected)
+        applyMerges(acceptedL2Merges);
     }
     const finalGroupsByRoot = new Map([...groups.entries()].map(([root, g]) => [
         root,
-        { tokenSets: g.tokenSets, landmarkInstances: g.landmarkInstances },
+        {
+            tokenSets: g.tokenSets,
+            landmarkInstances: g.landmarkInstances,
+            pageIndices: g.pageIndices,
+        },
     ]));
     return { rootByKey: keyToRoot, finalGroupsByRoot };
 }

package/dist/merge-validated-clusters.d.ts

@@ -0,0 +1,27 @@
+import type { CrossClusterDuplicate } from './find-cross-cluster-duplicates.js';
+/**
+ * Applies a set of confirmed cluster-pair merges to a `clusterKey` array,
+ * via union-find over the distinct cluster keys. Every `duplicates` entry is
+ * merged unconditionally — deciding *which* {@link CrossClusterDuplicate}s
+ * are trustworthy enough to act on (e.g. `similarity === 1` or
+ * `corroboratedByMirrorAxis`) is the caller's job, same separation of
+ * detection from action as
+ * {@link ./find-cross-cluster-duplicates.js | findCrossClusterDuplicates}
+ * itself.
+ *
+ * The surviving key for a merged group is its alphabetically smallest
+ * member — arbitrary but deterministic, so repeated calls on the same input
+ * produce the same output (mirrors the "lower index wins" rule
+ * {@link ./merge-cross-block-clusters.js | mergeCrossBlockClusters}'s own
+ * union-find already uses).
+ * @param clusterKeys Every page's current cluster key, in input order.
+ * @param duplicates Cluster-pair merges to apply.
+ * @example
+ * ```ts
+ * const merged = mergeValidatedClusters(
+ *   clusterKeys,
+ *   duplicates.filter((d) => d.similarity === 1 || d.corroboratedByMirrorAxis),
+ * );
+ * ```
+ */
+export declare function mergeValidatedClusters(clusterKeys: readonly string[], duplicates: readonly CrossClusterDuplicate[]): string[];

package/dist/merge-validated-clusters.js

@@ -0,0 +1,50 @@
+/**
+ * Applies a set of confirmed cluster-pair merges to a `clusterKey` array,
+ * via union-find over the distinct cluster keys. Every `duplicates` entry is
+ * merged unconditionally — deciding *which* {@link CrossClusterDuplicate}s
+ * are trustworthy enough to act on (e.g. `similarity === 1` or
+ * `corroboratedByMirrorAxis`) is the caller's job, same separation of
+ * detection from action as
+ * {@link ./find-cross-cluster-duplicates.js | findCrossClusterDuplicates}
+ * itself.
+ *
+ * The surviving key for a merged group is its alphabetically smallest
+ * member — arbitrary but deterministic, so repeated calls on the same input
+ * produce the same output (mirrors the "lower index wins" rule
+ * {@link ./merge-cross-block-clusters.js | mergeCrossBlockClusters}'s own
+ * union-find already uses).
+ * @param clusterKeys Every page's current cluster key, in input order.
+ * @param duplicates Cluster-pair merges to apply.
+ * @example
+ * ```ts
+ * const merged = mergeValidatedClusters(
+ *   clusterKeys,
+ *   duplicates.filter((d) => d.similarity === 1 || d.corroboratedByMirrorAxis),
+ * );
+ * ```
+ */
+export function mergeValidatedClusters(clusterKeys, duplicates) {
+    const parent = new Map();
+    const find = (key) => {
+        let root = key;
+        while (parent.has(root))
+            root = parent.get(root);
+        // Path compression for cheap repeated lookups within this call.
+        let cur = key;
+        while (cur !== root) {
+            const next = parent.get(cur);
+            parent.set(cur, root);
+            cur = next;
+        }
+        return root;
+    };
+    for (const { clusterKeyA, clusterKeyB } of duplicates) {
+        const rootA = find(clusterKeyA);
+        const rootB = find(clusterKeyB);
+        if (rootA === rootB)
+            continue;
+        const [smaller, larger] = rootA < rootB ? [rootA, rootB] : [rootB, rootA];
+        parent.set(larger, smaller);
+    }
+    return clusterKeys.map((key) => (parent.has(key) ? find(key) : key));
+}

package/dist/normalize-href-by-mirror-axis.d.ts

@@ -0,0 +1,25 @@
+import type { MirrorAxis } from './detect-mirror-axis.js';
+/**
+ * Reduces a URL (typically a stylesheet href) to a shape that is stable
+ * across a detected {@link MirrorAxis}, by replacing every `/<value>/`
+ * occurrence — for any of the axis's known values — with a fixed
+ * placeholder segment. Unlike {@link ./normalize-path-by-mirror-axis.js |
+ * normalizePathByMirrorAxis}, this does not anchor on `axis.position`: an
+ * href's own path structure (e.g. `/assets/en/style.css`) does not
+ * necessarily line up with the page's path depth (e.g. `/en/section/`), so
+ * matching is done by substring rather than by segment index. This is what
+ * lets a per-mirror stylesheet — the same template's CSS duplicated once per
+ * language directory instead of shared from one file — normalize to the
+ * same shape as its sibling mirrors, corroborating that two pages under
+ * different blocking keys are the same template mirrored rather than two
+ * different templates.
+ * @param href A URL string (typically a stylesheet href).
+ * @param axis A `MirrorAxis` from {@link ./detect-mirror-axis.js | detectMirrorAxis}.
+ * @example
+ * ```ts
+ * const axis = { position: 0, values: new Set(['en', 'zh']) };
+ * normalizeHrefByMirrorAxis('https://example.test/en/faq/page.css', axis);
+ * // 'https://example.test/{axis}/faq/page.css'
+ * ```
+ */
+export declare function normalizeHrefByMirrorAxis(href: string, axis: MirrorAxis): string;

package/dist/normalize-href-by-mirror-axis.js

@@ -0,0 +1,30 @@
+/**
+ * Reduces a URL (typically a stylesheet href) to a shape that is stable
+ * across a detected {@link MirrorAxis}, by replacing every `/<value>/`
+ * occurrence — for any of the axis's known values — with a fixed
+ * placeholder segment. Unlike {@link ./normalize-path-by-mirror-axis.js |
+ * normalizePathByMirrorAxis}, this does not anchor on `axis.position`: an
+ * href's own path structure (e.g. `/assets/en/style.css`) does not
+ * necessarily line up with the page's path depth (e.g. `/en/section/`), so
+ * matching is done by substring rather than by segment index. This is what
+ * lets a per-mirror stylesheet — the same template's CSS duplicated once per
+ * language directory instead of shared from one file — normalize to the
+ * same shape as its sibling mirrors, corroborating that two pages under
+ * different blocking keys are the same template mirrored rather than two
+ * different templates.
+ * @param href A URL string (typically a stylesheet href).
+ * @param axis A `MirrorAxis` from {@link ./detect-mirror-axis.js | detectMirrorAxis}.
+ * @example
+ * ```ts
+ * const axis = { position: 0, values: new Set(['en', 'zh']) };
+ * normalizeHrefByMirrorAxis('https://example.test/en/faq/page.css', axis);
+ * // 'https://example.test/{axis}/faq/page.css'
+ * ```
+ */
+export function normalizeHrefByMirrorAxis(href, axis) {
+    let normalized = href;
+    for (const value of axis.values) {
+        normalized = normalized.split(`/${value}/`).join('/{axis}/');
+    }
+    return normalized;
+}

package/dist/normalize-path-by-mirror-axis.d.ts

@@ -0,0 +1,22 @@
+import type { MirrorAxis } from './detect-mirror-axis.js';
+/**
+ * Reduces a page's URL path to a shape that is stable across a detected
+ * {@link MirrorAxis} by replacing the segment at `axis.position` with a
+ * fixed placeholder whenever it is one of the axis's known values. Two pages
+ * that are mirrors of the same content under different axis values (e.g. the
+ * `en` and `zh` copies of the same page) normalize to the same shape; a page
+ * whose segment at that position is *not* one of the axis's values (so it
+ * isn't part of the mirror at all) is left untouched, since collapsing it
+ * too would falsely equate unrelated pages that merely share a path depth.
+ * @param paths A page's URL path segments (e.g. `ExURL.paths`).
+ * @param axis A `MirrorAxis` from {@link ./detect-mirror-axis.js | detectMirrorAxis}.
+ * @example
+ * ```ts
+ * const axis = { position: 0, values: new Set(['en', 'zh']) };
+ * normalizePathByMirrorAxis(['en', 'faq', 'index.html'], axis);
+ * // '{axis}/faq/index.html'
+ * normalizePathByMirrorAxis(['zh', 'faq', 'index.html'], axis);
+ * // '{axis}/faq/index.html' — same shape as the `en` page above
+ * ```
+ */
+export declare function normalizePathByMirrorAxis(paths: readonly string[], axis: MirrorAxis): string;

package/dist/normalize-path-by-mirror-axis.js

@@ -0,0 +1,25 @@
+/**
+ * Reduces a page's URL path to a shape that is stable across a detected
+ * {@link MirrorAxis} by replacing the segment at `axis.position` with a
+ * fixed placeholder whenever it is one of the axis's known values. Two pages
+ * that are mirrors of the same content under different axis values (e.g. the
+ * `en` and `zh` copies of the same page) normalize to the same shape; a page
+ * whose segment at that position is *not* one of the axis's values (so it
+ * isn't part of the mirror at all) is left untouched, since collapsing it
+ * too would falsely equate unrelated pages that merely share a path depth.
+ * @param paths A page's URL path segments (e.g. `ExURL.paths`).
+ * @param axis A `MirrorAxis` from {@link ./detect-mirror-axis.js | detectMirrorAxis}.
+ * @example
+ * ```ts
+ * const axis = { position: 0, values: new Set(['en', 'zh']) };
+ * normalizePathByMirrorAxis(['en', 'faq', 'index.html'], axis);
+ * // '{axis}/faq/index.html'
+ * normalizePathByMirrorAxis(['zh', 'faq', 'index.html'], axis);
+ * // '{axis}/faq/index.html' — same shape as the `en` page above
+ * ```
+ */
+export function normalizePathByMirrorAxis(paths, axis) {
+    return paths
+        .map((segment, i) => i === axis.position && axis.values.has(segment) ? '{axis}' : segment)
+        .join('/');
+}

package/dist/resolve-page-cluster-keys.d.ts

@@ -4,6 +4,7 @@ import type { PerPageLandmarkInstance } from './per-page-landmark-signatures.js'
 import type { ResolveBlockingGroupKeysOptions } from './resolve-blocking-group-keys.js';
 import type { ResolveStructuralClusterKeysOptions } from './resolve-structural-cluster-keys.js';
 import type { TokenizeOptions } from './types.js';
+import type { ClusterPartitionReport } from './validate-cluster-partition.js';
 /**
  * Reinjects each page's *local* (non-corpus-wide) landmark-instance tokens
  * into its block token set for Stage A clustering, restoring exactly the
@@ -201,6 +202,48 @@ export type ResolvePageClusterKeysOptions = TokenizeOptions & ResolveBlockingGro
      * ```
      */
     onClusterReason?: (clusterKey: string, reason: ClusterReason) => void;
+    /**
+     * Optional observability hook invoked once per run with a
+     * {@link ClusterPartitionReport} — evidence that Stage A/B's finished
+     * partition may need correcting, from
+     * {@link ./validate-cluster-partition.js | validateClusterPartition}.
+     *
+     * Setting this option does two things, both gated on its presence the
+     * same way `onClusterReason` gates its own bookkeeping (existing
+     * callers that omit it pay nothing and see no behavior change):
+     *
+     * 1. Computes the report from Stage B's finished grouping (no
+     *    re-tokenization — reuses the token sets Stage A/B already hold).
+     * 2. Applies a fixed, built-in auto-merge policy to the *actual*
+     *    returned cluster keys before this callback (and
+     *    `onClusterReason`) ever sees them: every
+     *    `report.crossClusterDuplicates` entry with `similarity === 1` or
+     *    `corroboratedByMirrorAxis: true` is merged via
+     *    {@link ./merge-validated-clusters.js | mergeValidatedClusters}.
+     *    This is the one part of this library where an option changes the
+     *    returned `clusterKey`s themselves, not just side-channel
+     *    metadata — a caller who wants a *different* merge policy (or
+     *    none at all) should omit this option and call
+     *    `validateClusterPartition`/`findCrossClusterDuplicates`/
+     *    `mergeValidatedClusters` directly on this function's own output.
+     *
+     * On the streaming path (`pageCount > CORPUS_INLINE_THRESHOLD`), the
+     * report is built only from pages Stage A/B actually retained token
+     * sets for — reservoir-sampled block representatives, not pages
+     * assigned in Pass 1b — the same sampling trade-off Stage B itself
+     * already makes for corpora too large to hold in full. Any merge the
+     * sampled evidence justifies is still applied to every page sharing
+     * the merged keys, sampled or not.
+     * @example
+     * ```ts
+     * const keys = await resolvePageClusterKeys(pages, {
+     *   onPartitionReport: (report) => {
+     *     for (const c of report.cohesion) if (c.suspicious) console.warn(c);
+     *   },
+     * });
+     * ```
+     */
+    onPartitionReport?: (report: ClusterPartitionReport) => void;
 };
 /**
  * Corpus size at or below which the async factory-based