@rubytech/create-maxy-code 0.1.132 → 0.1.138

package/payload/platform/lib/graph-search/src/boosts.ts

@@ -0,0 +1,61 @@
+/**
+ * Score boosts (Task 308).
+ *
+ * Two post-fetch score adjustments that re-rank hybrid hits using
+ * properties that the typed-edge hook (Task 305) and compiled-truth
+ * migration (Task 306) populate. Both are no-ops on the current corpus
+ * until those tasks land — the boost reads a missing property as zero
+ * and adds nothing.
+ *
+ * Boosts are pure functions over the scored hit array. They never query
+ * Neo4j; the data they read is already on each hit's `properties` map.
+ */
+
+export interface ScoredHit {
+  nodeId: string;
+  properties: Record<string, unknown>;
+  score: number;
+}
+
+/**
+ * Add a flat fractional bump to any hit whose node carries a non-null
+ * `compiledTruth` property. Authoritative summaries beat noisy timeline
+ * fragments — this puts compiled rows ahead when the score is close.
+ *
+ * Default weight 0.15 (+15%); the brief reserves room to tune.
+ */
+export function applyCompiledTruthBoost<T extends ScoredHit>(
+  hits: T[],
+  weight = 0.15,
+): T[] {
+  if (weight < 0 || weight > 1) {
+    throw new Error(`applyCompiledTruthBoost: weight must be in [0,1], got ${weight}`);
+  }
+  return hits.map((hit) => {
+    const compiled = hit.properties["compiledTruth"];
+    if (compiled === null || compiled === undefined || compiled === "") return hit;
+    return { ...hit, score: hit.score * (1 + weight) };
+  });
+}
+
+/**
+ * Log-weighted boost scaled by inbound MENTIONS edge count.
+ *
+ * Formula: `bump = clamp(0.05 + 0.05 * log10(count), 0.05, 0.25)` when
+ * count > 0; zero otherwise. So 1 backlink → +5%, 10 → +10%, 100 → +15%,
+ * 1000 → +20%, 10000+ → capped at +25%. Backlink-rich nodes (the
+ * graph's natural authorities) surface higher.
+ *
+ * Reads from `hit.properties.backlinkCount` — a property Task 305's
+ * post-write hook maintains. Until 305 lands the count is absent and
+ * the boost is identity.
+ */
+export function applyBacklinkBoost<T extends ScoredHit>(hits: T[]): T[] {
+  return hits.map((hit) => {
+    const raw = hit.properties["backlinkCount"];
+    const count = typeof raw === "number" ? raw : Number(raw);
+    if (!Number.isFinite(count) || count <= 0) return hit;
+    const bump = Math.max(0.05, Math.min(0.25, 0.05 + 0.05 * Math.log10(count)));
+    return { ...hit, score: hit.score * (1 + bump) };
+  });
+}

package/payload/platform/lib/graph-search/src/dedup.ts

@@ -0,0 +1,108 @@
+/**
+ * 4-layer dedup (Task 308).
+ *
+ * Strict superset of the previous nodeId-only dedup. Catches duplicate
+ * representations the typed-edge hook (Task 305) and document-ingest
+ * pipeline will inevitably create: slug variants, canonical-name
+ * variants, and content-hash duplicates.
+ *
+ * Order: hits are sorted by descending score FIRST, then walked. The
+ * highest-score representative wins on every layer; later entries with
+ * the same key on any active layer are dropped. Missing values on a
+ * layer (no `slug`, no `canonicalName`, no derivable hash) are not
+ * collisions — they simply skip that layer for that row.
+ */
+
+import { createHash } from "node:crypto";
+
+export type DedupLayer = "nodeId" | "slug" | "canonicalName" | "contentHash";
+
+export const DEFAULT_LAYERS: DedupLayer[] = [
+  "nodeId",
+  "slug",
+  "canonicalName",
+  "contentHash",
+];
+
+interface DedupHit {
+  nodeId: string;
+  properties: Record<string, unknown>;
+  score: number;
+}
+
+function readSlug(props: Record<string, unknown>): string | null {
+  const slug = props["slug"];
+  return typeof slug === "string" && slug.length > 0 ? slug : null;
+}
+
+function readCanonicalName(props: Record<string, unknown>): string | null {
+  const canonical = props["canonicalName"];
+  if (typeof canonical === "string" && canonical.length > 0) {
+    return canonical.toLowerCase();
+  }
+  const name = props["name"];
+  if (typeof name === "string" && name.length > 0) {
+    return name.toLowerCase();
+  }
+  return null;
+}
+
+function readContentHash(props: Record<string, unknown>): string | null {
+  const compiled = props["compiledTruth"];
+  const content = props["content"];
+  const source = (typeof compiled === "string" && compiled.length > 0)
+    ? compiled
+    : (typeof content === "string" && content.length > 0 ? content : null);
+  if (source === null) return null;
+  return createHash("sha256").update(source).digest("hex").slice(0, 16);
+}
+
+/**
+ * Dedup `hits` across the requested layers. Returns a new array with the
+ * highest-scoring representative per collision class, in original
+ * descending-score order.
+ */
+export function dedup<T extends DedupHit>(
+  hits: T[],
+  layers: DedupLayer[] = DEFAULT_LAYERS,
+): T[] {
+  const sorted = [...hits].sort((a, b) => b.score - a.score);
+  const seen = new Map<DedupLayer, Set<string>>();
+  for (const layer of layers) seen.set(layer, new Set());
+  const out: T[] = [];
+
+  for (const hit of sorted) {
+    let collision = false;
+    const keys: Array<[DedupLayer, string]> = [];
+
+    for (const layer of layers) {
+      let key: string | null;
+      switch (layer) {
+        case "nodeId":
+          key = hit.nodeId;
+          break;
+        case "slug":
+          key = readSlug(hit.properties);
+          break;
+        case "canonicalName":
+          key = readCanonicalName(hit.properties);
+          break;
+        case "contentHash":
+          key = readContentHash(hit.properties);
+          break;
+      }
+      if (key === null) continue;
+      if (seen.get(layer)!.has(key)) {
+        collision = true;
+        break;
+      }
+      keys.push([layer, key]);
+    }
+
+    if (collision) continue;
+    for (const [layer, key] of keys) seen.get(layer)!.add(key);
+    out.push(hit);
+  }
+
+  return out;
+}