@rudra-js/core 0.7.3 → 0.7.5

package/src/reconciliation.ts

@@ -1,25 +1,24 @@
-import { verify } from '@rudra-js/attested';
-import { ALLOWED_PHRASES, claimIn, hostFacts, type HostFacts } from './claim-screening.js';
-import type {
-  Block,
-  GeneratedSpec,
-  ProductReference,
-  RecommendationBasis,
+import { hostFacts, NO_FACTS, unbackedClaim, type HostFacts } from './claim-screening.js';
+import {
+  columnsFor,
+  type Block,
+  type GeneratedSpec,
+  type ProductReference,
+  type RecommendationBasis,
 } from './component-spec.js';
-import { engagedCategories, type SignalDigest } from './signal-digest.js';
-import type { Bundle, Product, TrackingInput } from './tracking-input.js';
+import { categoriesTouchedBySignals, type SignalDigest } from './signal-digest.js';
+import { FIELD_LIMITS, type Bundle, type Product, type TrackingInput } from './tracking-input.js';
 
 const CLAMP = {
   headline: 90,
   subheadline: 140,
   blockTitle: 80,
-  reason: 120,
+  reason: FIELD_LIMITS.reason,
   badge: 24,
   ctaLabel: 32,
   bannerText: 160,
   copyBody: 420,
   rationale: 300,
-
   violationSku: 32,
 } as const;
 
@@ -31,9 +30,7 @@ export function capBlocks(blocks: Block[]): Block[] {
 
 export interface ReconcileResult {
   spec: GeneratedSpec;
-
   isUsable: boolean;
-
   violations: string[];
 }
 
@@ -47,51 +44,66 @@ function clamp(value: string, limit: number): string {
   return `${base.replace(/[.,;:!?-]+$/, '')}…`;
 }
 
-interface Allowlist {
-  allowed: Set<string>;
-  blocked: Set<string>;
-
-  blockedInBundle: Set<string>;
-}
-
-function refusedEverywhere(input: TrackingInput): Set<string> {
-  const refused = new Set<string>();
-  for (const signal of input.signals.dislikes) refused.add(signal.sku);
-  if (input.context.currentSku) refused.add(input.context.currentSku);
-
-  return refused;
+function blockedForBundles(input: TrackingInput): Set<string> {
+  const blocked = new Set<string>();
+  for (const signal of input.signals.dislikes) blocked.add(signal.sku);
+  if (input.context.currentSku) blocked.add(input.context.currentSku);
+  return blocked;
 }
 
-export function neverRecommend(input: TrackingInput): Set<string> {
-  const { signals } = input;
-
-  const blocked = refusedEverywhere(input);
-  for (const signal of [...signals.lastPurchased, ...signals.cart]) {
-    blocked.add(signal.sku);
-  }
-
+export function blockedForPicks(input: TrackingInput): Set<string> {
+  const blocked = blockedForBundles(input);
+  for (const signal of input.signals.lastPurchased) blocked.add(signal.sku);
+  for (const signal of input.signals.cart) blocked.add(signal.sku);
   return blocked;
 }
 
-function buildAllowlist(input: TrackingInput): Allowlist {
-  const allowed = new Set<string>();
+function inStockSkus(input: TrackingInput): Set<string> {
+  const skus = new Set<string>();
   for (const product of input.candidates) {
-    if (product.isInStock) allowed.add(product.sku);
+    if (product.isInStock) skus.add(product.sku);
   }
+  return skus;
+}
 
+interface Run {
+  readonly allowed: ReadonlySet<string>;
+  readonly blockedForPicks: ReadonlySet<string>;
+  readonly blockedForBundles: ReadonlySet<string>;
+  readonly products: ReadonlyMap<string, Product>;
+  readonly digest: SignalDigest;
+  readonly engaged: ReadonlySet<string>;
+  readonly bundles: readonly Bundle[];
+  readonly ourReasons: ReadonlyMap<string, string>;
+  readonly facts: HostFacts;
+  placed: Set<string>;
+  remaining: number;
+  violations: string[];
+}
+
+function startRun(
+  input: TrackingInput,
+  digest: SignalDigest,
+  ourReasons: ReadonlyMap<string, string>,
+): Run {
   return {
-    allowed,
-    blocked: neverRecommend(input),
-    blockedInBundle: refusedEverywhere(input),
+    allowed: inStockSkus(input),
+    blockedForPicks: blockedForPicks(input),
+    blockedForBundles: blockedForBundles(input),
+    products: new Map(input.candidates.map((product) => [product.sku, product])),
+    digest,
+    engaged: categoriesTouchedBySignals(input),
+    bundles: input.bundles,
+    ourReasons,
+    facts: hostFacts(input),
+    placed: new Set(),
+    remaining: digest.maxItems,
+    violations: [],
   };
 }
 
-function verifyBasis(
-  basis: RecommendationBasis,
-  product: Product,
-  digest: SignalDigest,
-  engaged: ReadonlySet<string>,
-): boolean {
+function verifyBasis(basis: RecommendationBasis, product: Product, run: Run): boolean {
+  const { digest } = run;
   switch (basis) {
     case 'most_viewed':
       return digest.topViewed.some((viewed) => viewed.sku === product.sku);
@@ -101,7 +113,7 @@ function verifyBasis(
       return digest.purchasedSkus.length > 0;
     case 'liked_category':
       return (
-        engaged.has(product.category) &&
+        run.engaged.has(product.category) &&
         digest.categoryAffinity.some((affinity) => affinity.category === product.category)
       );
     case 'similar_to_current':
@@ -111,135 +123,82 @@ function verifyBasis(
   }
 }
 
-const NUMERAL = /[\p{Nd}\p{No}\p{Nl}]/u;
-
-const NO_FACTS: readonly string[] = [];
-
-function createPlacementTracker(maxItems: number, facts: HostFacts) {
-  const placedSkus = new Set<string>();
-  const violations: string[] = [];
-  let remaining = maxItems;
-
-  return {
-    violations,
-    facts: facts.pooled,
-    factsFor: (sku: string): readonly string[] => facts.bySku.get(sku) ?? NO_FACTS,
-    get remaining() {
-      return remaining;
-    },
-    hasPlaced: (sku: string) => placedSkus.has(sku),
-    record(violation: string) {
-      violations.push(violation);
-    },
-    place(sku: string) {
-      placedSkus.add(sku);
-      remaining -= 1;
-    },
-  };
+function place(run: Run, sku: string): void {
+  run.placed.add(sku);
+  run.remaining -= 1;
 }
 
-type PlacementTracker = ReturnType<typeof createPlacementTracker>;
-
 function screenClaim(
   value: string | null,
   limit: number,
   field: string,
-  tracker: PlacementTracker,
-  facts: readonly string[] = tracker.facts,
+  run: Run,
+  facts: readonly string[] = run.facts.pooled,
 ): string | null {
   if (value === null) return null;
 
   const clamped = clamp(value, limit);
   if (clamped.length === 0) return null;
 
-  const kind = claimIn(value) ?? claimIn(clamped);
-  if (kind !== null) {
-    tracker.record(`unverifiable-claim:${kind}:${field}`);
-    return null;
-  }
-
-  const weighed = NUMERAL.test(clamped) ? facts : NO_FACTS;
+  const kind = unbackedClaim(value, clamped, facts);
+  if (kind === null) return clamped;
 
-  const result = verify(clamped, { values: weighed, allowedPhrases: ALLOWED_PHRASES });
-  if (!result.quantity.supported) {
-    tracker.record(`unverifiable-claim:quantity:${field}`);
-    return null;
-  }
-  if (!result.wording.supported) {
-    tracker.record(`unverifiable-claim:wording:${field}`);
-    return null;
-  }
-
-  return clamped;
+  run.violations.push(`unverifiable-claim:${kind}:${field}`);
+  return null;
 }
 
-function screenRequired(
-  value: string,
-  limit: number,
-  field: string,
-  tracker: PlacementTracker,
-): string {
-  return screenClaim(value, limit, field, tracker) ?? '';
+function screenRequired(value: string, limit: number, field: string, run: Run): string {
+  return screenClaim(value, limit, field, run) ?? '';
 }
 
-function rejectionFor(sku: string, allowlist: Allowlist, tracker: PlacementTracker): string | null {
+function rejectionFor(sku: string, run: Run): string | null {
   const named = clamp(sku, CLAMP.violationSku);
-
-  if (!allowlist.allowed.has(sku)) return `unknown-sku:${named}`;
-  if (allowlist.blocked.has(sku)) return `blocked-sku:${named}`;
-  if (tracker.hasPlaced(sku)) return `duplicate-sku:${named}`;
-  if (tracker.remaining <= 0) return `budget:dropped:${named}`;
+  if (!run.allowed.has(sku)) return `unknown-sku:${named}`;
+  if (run.blockedForPicks.has(sku)) return `blocked-sku:${named}`;
+  if (run.placed.has(sku)) return `duplicate-sku:${named}`;
+  if (run.remaining <= 0) return `budget:dropped:${named}`;
   return null;
 }
 
-function reconcileItems(
-  items: ProductReference[],
-  allowlist: Allowlist,
-  candidatesBySku: Map<string, Product>,
-  digest: SignalDigest,
-  engaged: ReadonlySet<string>,
-  tracker: PlacementTracker,
-  ourReasons: ReadonlyMap<string, string>,
-): ProductReference[] {
+function takeSlot(sku: string, run: Run): string | null {
+  const rejection = rejectionFor(sku, run);
+  if (rejection !== null) {
+    run.violations.push(rejection);
+    return null;
+  }
+  place(run, sku);
+  return sku;
+}
+
+function reconcileItems(items: ProductReference[], run: Run): ProductReference[] {
   const kept: ProductReference[] = [];
 
   for (const item of items) {
-    const rejection = rejectionFor(item.sku, allowlist, tracker);
-    if (rejection) {
-      tracker.record(rejection);
-      continue;
-    }
-
-    const product = candidatesBySku.get(item.sku);
+    if (takeSlot(item.sku, run) === null) continue;
 
+    const product = run.products.get(item.sku);
     if (!product) continue;
 
-    tracker.place(item.sku);
-
-    const hasSupportedBasis = verifyBasis(item.basis, product, digest, engaged);
-    if (!hasSupportedBasis) tracker.record(`unsupported-basis:${item.basis}:${item.sku}`);
-
-    const isOurs = item.reason !== null && ourReasons.get(item.sku) === item.reason;
-
-    const own = tracker.factsFor(item.sku);
-
-    let reason: string | null = null;
-    let badge: string | null = null;
-    if (hasSupportedBasis) {
-      reason = isOurs
-        ? clamp(item.reason ?? '', CLAMP.reason) || null
-        : screenClaim(item.reason, CLAMP.reason, `reason:${item.sku}`, tracker, own);
-
-      badge = screenClaim(item.badge, CLAMP.badge, `badge:${item.sku}`, tracker, own);
+    if (!verifyBasis(item.basis, product, run)) {
+      run.violations.push(`unsupported-basis:${item.basis}:${item.sku}`);
+      kept.push({
+        sku: item.sku,
+        basis: 'popular',
+        reason: null,
+        badge: null,
+        emphasis: item.emphasis,
+      });
+      continue;
     }
 
-    kept.push({
-      sku: item.sku,
-      basis: hasSupportedBasis ? item.basis : 'popular',
-      reason,
-      badge,
-      emphasis: item.emphasis,
-    });
+    const own = run.facts.bySku.get(item.sku) ?? NO_FACTS;
+    const reason =
+      item.reason !== null && run.ourReasons.get(item.sku) === item.reason
+        ? clamp(item.reason, CLAMP.reason) || null
+        : screenClaim(item.reason, CLAMP.reason, `reason:${item.sku}`, run, own);
+    const badge = screenClaim(item.badge, CLAMP.badge, `badge:${item.sku}`, run, own);
+
+    kept.push({ sku: item.sku, basis: item.basis, reason, badge, emphasis: item.emphasis });
   }
 
   return kept;
@@ -254,16 +213,14 @@ interface BundleFit {
 function fitOf(
   bundle: Bundle,
   digest: SignalDigest,
-  candidatesBySku: Map<string, Product>,
+  products: ReadonlyMap<string, Product>,
 ): BundleFit {
   const fit: BundleFit = { cartHits: 0, viewedHits: 0, categoryHits: 0 };
-
   for (const sku of bundle.skus) {
     if (digest.cartSkus.includes(sku)) fit.cartHits += 1;
     else if (digest.topViewed.some((viewed) => viewed.sku === sku)) fit.viewedHits += 1;
-    else if (candidatesBySku.get(sku)?.category === digest.currentCategory) fit.categoryHits += 1;
+    else if (products.get(sku)?.category === digest.currentCategory) fit.categoryHits += 1;
   }
-
   return fit;
 }
 
@@ -274,28 +231,19 @@ function isBetterFit(fit: BundleFit, best: BundleFit | undefined): boolean {
   return fit.categoryHits > best.categoryHits;
 }
 
-function chooseBundle(
-  bundles: readonly Bundle[],
-  allowlist: Allowlist,
-  digest: SignalDigest,
-  candidatesBySku: Map<string, Product>,
-  tracker: PlacementTracker,
-): Bundle | undefined {
+function chooseBundle(run: Run): Bundle | undefined {
   let best: Bundle | undefined;
   let bestFit: BundleFit | undefined;
 
-  for (const bundle of bundles) {
-    if (bundle.skus.length > tracker.remaining) continue;
+  for (const bundle of run.bundles) {
+    if (bundle.skus.length > run.remaining) continue;
 
-    let isPlaceable = true;
-    for (const sku of bundle.skus) {
-      if (!allowlist.allowed.has(sku)) isPlaceable = false;
-      if (allowlist.blockedInBundle.has(sku)) isPlaceable = false;
-      if (tracker.hasPlaced(sku)) isPlaceable = false;
-    }
+    const isPlaceable = bundle.skus.every(
+      (sku) => run.allowed.has(sku) && !run.blockedForBundles.has(sku) && !run.placed.has(sku),
+    );
     if (!isPlaceable) continue;
 
-    const fit = fitOf(bundle, digest, candidatesBySku);
+    const fit = fitOf(bundle, run.digest, run.products);
     if (isBetterFit(fit, bestFit)) {
       best = bundle;
       bestFit = fit;
@@ -310,154 +258,109 @@ export function bundleForShopper(
   digest: SignalDigest,
   spokenFor: readonly string[],
 ): Bundle | undefined {
-  const allowlist = buildAllowlist(input);
-  const candidatesBySku = new Map(input.candidates.map((product) => [product.sku, product]));
-  const tracker = createPlacementTracker(digest.maxItems, hostFacts(input));
-
-  for (const sku of spokenFor) tracker.place(sku);
+  const run = startRun(input, digest, new Map());
+  for (const sku of spokenFor) place(run, sku);
 
-  return chooseBundle(input.bundles, allowlist, digest, candidatesBySku, tracker);
+  return chooseBundle(run);
 }
 
 export function placeableHeroSkus(blocks: readonly Block[], input: TrackingInput): string[] {
-  const allowlist = buildAllowlist(input);
-
+  const allowed = inStockSkus(input);
+  const blocked = blockedForPicks(input);
   const skus: string[] = [];
   for (const block of blocks) {
-    if (block.kind !== 'hero') continue;
-    if (block.sku === null) continue;
-    if (!allowlist.allowed.has(block.sku) || allowlist.blocked.has(block.sku)) continue;
-    if (skus.includes(block.sku)) continue;
-    skus.push(block.sku);
+    if (block.kind !== 'hero' || block.sku === null) continue;
+    if (!allowed.has(block.sku) || blocked.has(block.sku)) continue;
+    if (!skus.includes(block.sku)) skus.push(block.sku);
   }
-
   return skus;
 }
 
-function reconcileBlock(
-  block: Block,
-  allowlist: Allowlist,
-  candidatesBySku: Map<string, Product>,
-  digest: SignalDigest,
-  engaged: ReadonlySet<string>,
-  bundles: readonly Bundle[],
-  tracker: PlacementTracker,
-  ourReasons: ReadonlyMap<string, string>,
-): Block | null {
+function reconcileBlock(block: Block, run: Run): Block | null {
   switch (block.kind) {
     case 'hero': {
-      let sku = block.sku;
-      if (sku !== null) {
-        const rejection = rejectionFor(sku, allowlist, tracker);
-        if (rejection) {
-          tracker.record(rejection);
-
-          sku = null;
-        } else {
-          tracker.place(sku);
-        }
-      }
-
-      const headline = screenRequired(block.headline, CLAMP.headline, 'hero-headline', tracker);
+      const sku = block.sku === null ? null : takeSlot(block.sku, run);
+      const headline = screenRequired(block.headline, CLAMP.headline, 'hero-headline', run);
       if (headline.length === 0 && sku === null) {
-        tracker.record('empty-block:hero');
+        run.violations.push('empty-block:hero');
         return null;
       }
       return {
         kind: 'hero',
         headline,
-        body: screenClaim(block.body, CLAMP.subheadline, 'hero-body', tracker),
+        body: screenClaim(block.body, CLAMP.subheadline, 'hero-body', run),
         sku,
-        ctaLabel: screenClaim(block.ctaLabel, CLAMP.ctaLabel, 'hero-cta', tracker),
+        ctaLabel: screenClaim(block.ctaLabel, CLAMP.ctaLabel, 'hero-cta', run),
       };
     }
 
     case 'grid': {
-      const items = reconcileItems(
-        block.items,
-        allowlist,
-        candidatesBySku,
-        digest,
-        engaged,
-        tracker,
-        ourReasons,
-      );
+      const items = reconcileItems(block.items, run);
       if (items.length === 0) {
-        tracker.record('empty-block:grid');
+        run.violations.push('empty-block:grid');
         return null;
       }
       return {
         kind: 'grid',
-        title: screenClaim(block.title, CLAMP.blockTitle, 'grid-title', tracker),
-
-        columns: Math.min(block.columns, Math.max(2, items.length)) as 2 | 3 | 4,
+        title: screenClaim(block.title, CLAMP.blockTitle, 'grid-title', run),
+        columns: columnsFor(items.length, block.columns),
         items,
       };
     }
 
     case 'carousel': {
-      const items = reconcileItems(
-        block.items,
-        allowlist,
-        candidatesBySku,
-        digest,
-        engaged,
-        tracker,
-        ourReasons,
-      );
+      const items = reconcileItems(block.items, run);
       if (items.length === 0) {
-        tracker.record('empty-block:carousel');
+        run.violations.push('empty-block:carousel');
         return null;
       }
       return {
         kind: 'carousel',
-        title: screenClaim(block.title, CLAMP.blockTitle, 'carousel-title', tracker),
+        title: screenClaim(block.title, CLAMP.blockTitle, 'carousel-title', run),
         items,
       };
     }
 
     case 'banner': {
-      const text = screenRequired(block.text, CLAMP.bannerText, 'banner-text', tracker);
+      const text = screenRequired(block.text, CLAMP.bannerText, 'banner-text', run);
       if (text.length === 0) {
-        tracker.record('empty-block:banner');
+        run.violations.push('empty-block:banner');
         return null;
       }
       return {
         kind: 'banner',
         tone: block.tone,
         text,
-        ctaLabel: screenClaim(block.ctaLabel, CLAMP.ctaLabel, 'banner-cta', tracker),
+        ctaLabel: screenClaim(block.ctaLabel, CLAMP.ctaLabel, 'banner-cta', run),
       };
     }
 
     case 'copy': {
-      const body = screenRequired(block.body, CLAMP.copyBody, 'copy-body', tracker);
+      const body = screenRequired(block.body, CLAMP.copyBody, 'copy-body', run);
       if (body.length === 0) {
-        tracker.record('empty-block:copy');
+        run.violations.push('empty-block:copy');
         return null;
       }
       return {
         kind: 'copy',
-        title: screenClaim(block.title, CLAMP.blockTitle, 'copy-title', tracker),
+        title: screenClaim(block.title, CLAMP.blockTitle, 'copy-title', run),
         body,
       };
     }
 
     case 'bundle': {
-      const chosen = chooseBundle(bundles, allowlist, digest, candidatesBySku, tracker);
+      const chosen = chooseBundle(run);
       if (!chosen) {
-        tracker.record('no-bundle');
+        run.violations.push('no-bundle');
         return null;
       }
 
-      for (const sku of chosen.skus) tracker.place(sku);
-
+      for (const sku of chosen.skus) place(run, sku);
       return {
         kind: 'bundle',
-        title: screenClaim(block.title, CLAMP.blockTitle, 'bundle-title', tracker),
-        body: screenClaim(block.body, CLAMP.subheadline, 'bundle-body', tracker),
-        ctaLabel: screenClaim(block.ctaLabel, CLAMP.ctaLabel, 'bundle-cta', tracker),
-
+        title: screenClaim(block.title, CLAMP.blockTitle, 'bundle-title', run),
+        body: screenClaim(block.body, CLAMP.subheadline, 'bundle-body', run),
+        ctaLabel: screenClaim(block.ctaLabel, CLAMP.ctaLabel, 'bundle-cta', run),
         bundleId: chosen.id,
       };
     }
@@ -478,44 +381,32 @@ export function reconcileSpec(
   generated: GeneratedSpec,
   input: TrackingInput,
   digest: SignalDigest,
-
   ourReasons: ReadonlyMap<string, string> = new Map(),
 ): ReconcileResult {
-  const allowlist = buildAllowlist(input);
-  const candidatesBySku = new Map(input.candidates.map((product) => [product.sku, product]));
-  const engaged = engagedCategories(input);
-  const tracker = createPlacementTracker(digest.maxItems, hostFacts(input));
+  const run = startRun(input, digest, ourReasons);
 
   if (generated.blocks.length > MAX_BLOCKS) {
-    tracker.record(`too-many-blocks:${generated.blocks.length}`);
+    run.violations.push(`too-many-blocks:${generated.blocks.length}`);
   }
 
   const blocks: Block[] = [];
   for (const block of capBlocks(generated.blocks)) {
-    const reconciled = reconcileBlock(
-      block,
-      allowlist,
-      candidatesBySku,
-      digest,
-      engaged,
-      input.bundles,
-      tracker,
-      ourReasons,
-    );
+    const reconciled = reconcileBlock(block, run);
     if (reconciled !== null) blocks.push(reconciled);
   }
 
   const spec: GeneratedSpec = {
     tone: generated.tone,
-    headline: screenRequired(generated.headline, CLAMP.headline, 'headline', tracker),
-    subheadline: screenClaim(generated.subheadline, CLAMP.subheadline, 'subheadline', tracker),
+    headline: screenRequired(generated.headline, CLAMP.headline, 'headline', run),
+    subheadline: screenClaim(generated.subheadline, CLAMP.subheadline, 'subheadline', run),
     blocks,
-    rationale: screenRequired(generated.rationale, CLAMP.rationale, 'rationale', tracker),
+    rationale: screenRequired(generated.rationale, CLAMP.rationale, 'rationale', run),
   };
 
-  if (!showsAnyProduct(blocks)) tracker.record('unusable:no-products');
-  if (spec.headline.length === 0) tracker.record('unusable:no-headline');
-  const isUsable = showsAnyProduct(blocks) && spec.headline.length > 0;
+  const hasProducts = showsAnyProduct(blocks);
+  if (!hasProducts) run.violations.push('unusable:no-products');
+  if (spec.headline.length === 0) run.violations.push('unusable:no-headline');
+  const isUsable = hasProducts && spec.headline.length > 0;
 
-  return { spec, isUsable, violations: tracker.violations };
+  return { spec, isUsable, violations: run.violations };
 }