@d-zero/page-cluster 0.5.5 → 0.5.7

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

package/dist/resolve-page-cluster-keys.js

@@ -6,11 +6,13 @@ import { extractLandmarks } from './extract-landmarks.js';
 import { filterFirstPartyStylesheetHrefs } from './filter-first-party-stylesheet-hrefs.js';
 import { jaccardSimilarity } from './jaccard-similarity.js';
 import { mergeCrossBlockClusters } from './merge-cross-block-clusters.js';
+import { mergeValidatedClusters } from './merge-validated-clusters.js';
 import { groupIndicesByBlockKey, resolveBlockKeys } from './pass0-blocking.js';
 import { computePerPageLandmarkInstances } from './per-page-landmark-signatures.js';
 import { removeContentBlocks } from './remove-content-blocks.js';
 import { stageAPerBlock } from './stage-a-per-block.js';
 import { tokenize } from './tokenize.js';
+import { validateClusterPartition } from './validate-cluster-partition.js';
 /**
  * FNV-1a 32-bit hash of a string, used to seed the per-block PRNG so
  * reservoir sampling on the streaming path is deterministic for a given
@@ -257,6 +259,92 @@ function resolveBlockKeysForClustering(blockingPages, options, needReasons) {
     const result = resolveBlockKeys(blockingPages, { ...options, includeReasons: true });
     return { blockKeys: result.blockKeys, reasonsByBlockKey: result.reasonsByBlockKey };
 }
+/**
+ * Runs {@link ./validate-cluster-partition.js | validateClusterPartition}
+ * over Stage B's finished grouping and applies the built-in auto-merge
+ * policy (see `onPartitionReport`'s own JSDoc) directly to `finalKeys`,
+ * mutating it in place — the same in-place style the driver's own
+ * `rootByKey` rewrite loop already uses just before calling this.
+ *
+ * No-ops (returning `rootByKey`/`finalGroupsByRoot` unchanged) when
+ * `onPartitionReport` is `undefined` — the single gate every driver defers
+ * to, mirroring `emitClusterReasons`'s own gate for `onClusterReason`.
+ *
+ * When a merge is applied, `rootByKey` and `finalGroupsByRoot` are folded
+ * according to the same rename so `emitClusterReasons` (called with this
+ * function's return value, not the pre-merge originals) builds each
+ * survivor's `ClusterReason` from its *actual* post-merge membership —
+ * without this, a merged-away key's members would report `finalKeys[i]`
+ * pointing at the survivor while its own stale `ClusterReason.memberCount`
+ * still reflected only its pre-merge share.
+ * @param finalKeys Every page's current final cluster key, in input order.
+ *   Mutated in place when a merge is applied.
+ * @param rootByKey Stage B's own result (see
+ *   {@link ./merge-cross-block-clusters.js | MergeCrossBlockClustersResult}).
+ * @param finalGroupsByRoot Stage B's own result.
+ * @param getPageSignals Given an original page index, returns that page's
+ *   `paths`/`stylesheetHrefs` — `undefined` for an index the caller has no
+ *   record of (defensive; should not occur for indices Stage A/B actually
+ *   retained).
+ * @param onPartitionReport
+ */
+function validateAndMergePartition(finalKeys, rootByKey, finalGroupsByRoot, getPageSignals, onPartitionReport) {
+    if (!onPartitionReport)
+        return { rootByKey, finalGroupsByRoot };
+    const clusteredPages = [];
+    for (const [finalKey, group] of finalGroupsByRoot) {
+        for (const [i, tokens] of group.tokenSets.entries()) {
+            const pageIndex = group.pageIndices[i] ?? -1;
+            if (pageIndex === -1)
+                continue;
+            const signals = getPageSignals(pageIndex);
+            if (!signals)
+                continue;
+            clusteredPages.push({
+                clusterKey: finalKey,
+                tokens,
+                paths: signals.paths,
+                stylesheetHrefs: signals.stylesheetHrefs,
+            });
+        }
+    }
+    const report = validateClusterPartition(clusteredPages);
+    onPartitionReport(report);
+    // `findCrossClusterDuplicates` only ever returns entries that already
+    // satisfy this condition (its exact-match pass sets `similarity: 1`
+    // unconditionally; its near-match pass requires `corroboratedByMirrorAxis`
+    // to accept a pair at all) — this filter is a defensive invariant check,
+    // not something that currently narrows the result, kept so this call site
+    // keeps working correctly if that policy ever loosens.
+    const safeToMerge = report.crossClusterDuplicates.filter((d) => d.similarity === 1 || d.corroboratedByMirrorAxis);
+    if (safeToMerge.length === 0)
+        return { rootByKey, finalGroupsByRoot };
+    const mergedKeys = mergeValidatedClusters(finalKeys, safeToMerge);
+    const renameMap = new Map();
+    for (const [i, mergedKey] of mergedKeys.entries()) {
+        if (finalKeys[i] !== mergedKey)
+            renameMap.set(finalKeys[i], mergedKey);
+        finalKeys[i] = mergedKey;
+    }
+    const mergedFinalGroupsByRoot = new Map();
+    for (const [key, group] of finalGroupsByRoot) {
+        const target = renameMap.get(key) ?? key;
+        const existing = mergedFinalGroupsByRoot.get(target);
+        mergedFinalGroupsByRoot.set(target, {
+            tokenSets: [...(existing?.tokenSets ?? []), ...group.tokenSets],
+            landmarkInstances: [
+                ...(existing?.landmarkInstances ?? []),
+                ...group.landmarkInstances,
+            ],
+            pageIndices: [...(existing?.pageIndices ?? []), ...group.pageIndices],
+        });
+    }
+    const mergedRootByKey = new Map();
+    for (const [unitKey, stageBRoot] of rootByKey) {
+        mergedRootByKey.set(unitKey, renameMap.get(stageBRoot) ?? stageBRoot);
+    }
+    return { rootByKey: mergedRootByKey, finalGroupsByRoot: mergedFinalGroupsByRoot };
+}
 /**
  * Builds and emits one {@link ClusterReason} per final cluster via
  * `onClusterReason`, from data Stage A/B already computed for clustering
@@ -459,7 +547,8 @@ export function resolvePageClusterKeysInMemory(pages, options) {
             finalKeys[i] = rootKey;
         }
     }
-    emitClusterReasons(crossBlockUnits, rootByKey, finalGroupsByRoot, reasonsByBlockKey, siblingUnitKeysByBlock, onClusterReason);
+    const validated = validateAndMergePartition(finalKeys, rootByKey, finalGroupsByRoot, (i) => pages[i], options?.onPartitionReport);
+    emitClusterReasons(crossBlockUnits, validated.rootByKey, validated.finalGroupsByRoot, reasonsByBlockKey, siblingUnitKeysByBlock, onClusterReason);
     return finalKeys;
 }
 /**
@@ -557,7 +646,8 @@ async function resolveSmallCorpusWithProgress(pages, onProgress, options) {
             finalKeys[i] = rootKey;
         }
     }
-    emitClusterReasons(crossBlockUnits, rootByKey, finalGroupsByRoot, reasonsByBlockKey, siblingUnitKeysByBlock, onClusterReason);
+    const validated = validateAndMergePartition(finalKeys, rootByKey, finalGroupsByRoot, (i) => pages[i], options?.onPartitionReport);
+    emitClusterReasons(crossBlockUnits, validated.rootByKey, validated.finalGroupsByRoot, reasonsByBlockKey, siblingUnitKeysByBlock, onClusterReason);
     return finalKeys;
 }
 /**
@@ -844,7 +934,13 @@ export async function resolvePageClusterKeys(pages, options) {
             finalKeys[i] = rootKey;
         }
     }
-    emitClusterReasons(crossBlockUnits, rootByKey, finalGroupsByRoot, reasonsByBlockKey, siblingUnitKeysByBlock, onClusterReason);
+    // `blockingSignals` (built during Pass 0, held for the whole call) has an
+    // entry for every page in the corpus, sampled or not — only the pages
+    // `finalGroupsByRoot` actually kept a token set for (reservoir-sampled
+    // block representatives) end up in the report, per `onPartitionReport`'s
+    // own JSDoc.
+    const validated = validateAndMergePartition(finalKeys, rootByKey, finalGroupsByRoot, (i) => blockingSignals[i], options?.onPartitionReport);
+    emitClusterReasons(crossBlockUnits, validated.rootByKey, validated.finalGroupsByRoot, reasonsByBlockKey, siblingUnitKeysByBlock, onClusterReason);
     return finalKeys;
 }
 /**

package/dist/stage-a-per-block.js

@@ -172,6 +172,7 @@ export function stageAPerBlock(input, options) {
             key: unitKey,
             memberTokenSets: sampledPositions.map((pos) => blockTokenSets[pos]),
             memberLandmarkInstances: sampledPositions.map((pos) => memberLandmarkInstancesByPage[pos]),
+            memberPageIndices: sampledPositions.map((pos) => memberIndices[pos]),
         });
     }
     return { pageKeys, crossBlockUnits };

package/dist/validate-cluster-partition.d.ts

@@ -0,0 +1,70 @@
+import type { ClusterCohesion, ClusterCohesionOptions } from './compute-cluster-cohesion.js';
+import type { DetectMirrorAxisOptions, MirrorAxis } from './detect-mirror-axis.js';
+import type { ClusteredPage, CrossClusterDuplicate } from './find-cross-cluster-duplicates.js';
+/**
+ * Options for {@link validateClusterPartition}, forwarded to the three
+ * checks it composes.
+ */
+export type ValidateClusterPartitionOptions = {
+    readonly mirrorAxis?: DetectMirrorAxisOptions;
+    readonly cohesion?: ClusterCohesionOptions;
+    /**
+     * Only `corroboratedSimilarityThreshold` — `mirrorAxis` itself is always
+     * the axis this function just detected, not independently settable here.
+     */
+    readonly crossClusterDuplicates?: {
+        readonly corroboratedSimilarityThreshold?: number;
+    };
+};
+/**
+ * Structured evidence that a clustering run's partition may need
+ * correcting: which pages are plausibly the same template despite ending up
+ * in different clusters, and which clusters plausibly mix unrelated
+ * templates together. Carries no verdict on whether to act — same design as
+ * {@link ./build-cluster-reason.js | ClusterReason} — a caller decides what
+ * to do with `crossClusterDuplicates` (e.g. via
+ * {@link ./merge-validated-clusters.js | mergeValidatedClusters}) and with
+ * `cohesion`'s `suspicious` flags.
+ */
+export type ClusterPartitionReport = {
+    /**
+     * The mirror axis detected across every page's `paths`, or `null` if
+     * none was found — see
+     * {@link ./detect-mirror-axis.js | detectMirrorAxis}.
+     */
+    readonly mirrorAxis: MirrorAxis | null;
+    /** One entry per distinct cluster key present in `pages`. */
+    readonly cohesion: readonly ClusterCohesion[];
+    /** See {@link ./find-cross-cluster-duplicates.js | findCrossClusterDuplicates}. */
+    readonly crossClusterDuplicates: readonly CrossClusterDuplicate[];
+};
+/**
+ * Validates a finished clustering partition by checking it against itself,
+ * rather than trying to get the clustering right the first time: whether
+ * pages that ended up in different clusters are nonetheless structurally
+ * identical or near-identical (a likely over-split, see
+ * {@link ./find-cross-cluster-duplicates.js | findCrossClusterDuplicates}),
+ * and whether any single cluster's members actually agree with each other
+ * (a likely over-merge, see
+ * {@link ./compute-cluster-cohesion.js | computeClusterCohesion}). Neither
+ * check depends on *how* the partition was produced — this is deliberately
+ * decoupled from `resolvePageClusterKeys`'s own Stage A/B internals so it
+ * can validate a partition regardless of its origin, including a stored one
+ * loaded back from an archive.
+ *
+ * Takes already-tokenized pages rather than raw HTML — a caller with a
+ * `resolvePageClusterKeys` result already has token sets on hand (or can
+ * derive them via {@link ./tokenize.js | tokenize}), and re-tokenizing here
+ * would cost a second full corpus pass for no benefit.
+ * @param pages
+ * @param options
+ * @example
+ * ```ts
+ * const report = validateClusterPartition(pages);
+ * const safeToMerge = report.crossClusterDuplicates.filter(
+ *   (d) => d.similarity === 1 || d.corroboratedByMirrorAxis,
+ * );
+ * const mergedKeys = mergeValidatedClusters(clusterKeys, safeToMerge);
+ * ```
+ */
+export declare function validateClusterPartition(pages: readonly ClusteredPage[], options?: ValidateClusterPartitionOptions): ClusterPartitionReport;

package/dist/validate-cluster-partition.js

@@ -0,0 +1,49 @@
+import { computeClusterCohesion } from './compute-cluster-cohesion.js';
+import { detectMirrorAxis } from './detect-mirror-axis.js';
+import { findCrossClusterDuplicates } from './find-cross-cluster-duplicates.js';
+/**
+ * Validates a finished clustering partition by checking it against itself,
+ * rather than trying to get the clustering right the first time: whether
+ * pages that ended up in different clusters are nonetheless structurally
+ * identical or near-identical (a likely over-split, see
+ * {@link ./find-cross-cluster-duplicates.js | findCrossClusterDuplicates}),
+ * and whether any single cluster's members actually agree with each other
+ * (a likely over-merge, see
+ * {@link ./compute-cluster-cohesion.js | computeClusterCohesion}). Neither
+ * check depends on *how* the partition was produced — this is deliberately
+ * decoupled from `resolvePageClusterKeys`'s own Stage A/B internals so it
+ * can validate a partition regardless of its origin, including a stored one
+ * loaded back from an archive.
+ *
+ * Takes already-tokenized pages rather than raw HTML — a caller with a
+ * `resolvePageClusterKeys` result already has token sets on hand (or can
+ * derive them via {@link ./tokenize.js | tokenize}), and re-tokenizing here
+ * would cost a second full corpus pass for no benefit.
+ * @param pages
+ * @param options
+ * @example
+ * ```ts
+ * const report = validateClusterPartition(pages);
+ * const safeToMerge = report.crossClusterDuplicates.filter(
+ *   (d) => d.similarity === 1 || d.corroboratedByMirrorAxis,
+ * );
+ * const mergedKeys = mergeValidatedClusters(clusterKeys, safeToMerge);
+ * ```
+ */
+export function validateClusterPartition(pages, options) {
+    const mirrorAxis = detectMirrorAxis(pages.map((p) => p.paths), options?.mirrorAxis);
+    const membersByKey = new Map();
+    for (const page of pages) {
+        const members = membersByKey.get(page.clusterKey);
+        if (members)
+            members.push(page.tokens);
+        else
+            membersByKey.set(page.clusterKey, [page.tokens]);
+    }
+    const cohesion = computeClusterCohesion(membersByKey, options?.cohesion);
+    const crossClusterDuplicates = findCrossClusterDuplicates(pages, {
+        mirrorAxis,
+        corroboratedSimilarityThreshold: options?.crossClusterDuplicates?.corroboratedSimilarityThreshold,
+    });
+    return { mirrorAxis, cohesion, crossClusterDuplicates };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@d-zero/page-cluster",
-	"version": "0.5.5",
+	"version": "0.5.7",
 	"description": "Clusters crawled HTML pages by DOM-structure similarity — assigns the same key to pages sharing a template, ignoring text content. CLI-first, with library APIs.",
 	"author": "D-ZERO",
 	"license": "MIT",
@@ -36,6 +36,34 @@
 		"./build-cluster-reason": {
 			"import": "./dist/build-cluster-reason.js",
 			"types": "./dist/build-cluster-reason.d.ts"
+		},
+		"./detect-mirror-axis": {
+			"import": "./dist/detect-mirror-axis.js",
+			"types": "./dist/detect-mirror-axis.d.ts"
+		},
+		"./normalize-path-by-mirror-axis": {
+			"import": "./dist/normalize-path-by-mirror-axis.js",
+			"types": "./dist/normalize-path-by-mirror-axis.d.ts"
+		},
+		"./normalize-href-by-mirror-axis": {
+			"import": "./dist/normalize-href-by-mirror-axis.js",
+			"types": "./dist/normalize-href-by-mirror-axis.d.ts"
+		},
+		"./compute-cluster-cohesion": {
+			"import": "./dist/compute-cluster-cohesion.js",
+			"types": "./dist/compute-cluster-cohesion.d.ts"
+		},
+		"./find-cross-cluster-duplicates": {
+			"import": "./dist/find-cross-cluster-duplicates.js",
+			"types": "./dist/find-cross-cluster-duplicates.d.ts"
+		},
+		"./validate-cluster-partition": {
+			"import": "./dist/validate-cluster-partition.js",
+			"types": "./dist/validate-cluster-partition.d.ts"
+		},
+		"./merge-validated-clusters": {
+			"import": "./dist/merge-validated-clusters.js",
+			"types": "./dist/merge-validated-clusters.d.ts"
 		}
 	},
 	"bin": "dist/cli.js",
@@ -48,8 +76,8 @@
 		"clean": "tsc --build --clean"
 	},
 	"dependencies": {
-		"@d-zero/dealer": "1.10.3",
-		"@d-zero/shared": "0.22.4",
+		"@d-zero/dealer": "1.10.4",
+		"@d-zero/shared": "0.22.5",
 		"htmlparser2": "12.0.0"
 	},
 	"repository": {
@@ -57,5 +85,5 @@
 		"url": "https://github.com/d-zero-dev/tools.git",
 		"directory": "packages/@d-zero/page-cluster"
 	},
-	"gitHead": "97d00b14cd0bf8e71158e582b256649a9ec9ef3e"
+	"gitHead": "1321d85f63db05896135599046924221f4f714c5"
 }