@agent-pattern-labs/leads-rig 0.1.7 → 0.1.9

package/bin/lead-harness.mjs

@@ -17,6 +17,7 @@ const commands = {
   validate: 'scripts/validate-leads.mjs',
   manifest: 'scripts/manifest.mjs',
   ingest: 'scripts/ingest.mjs',
+  'enrich:platform': 'scripts/enrich-platform.mjs',
   batch: 'scripts/batch-orchestrator.mjs',
   verify: 'verify-pipeline.mjs',
   sync: 'bin/sync.mjs',
@@ -186,6 +187,7 @@ Core commands:
   validate      Validate lead artifacts against the local contract
   manifest      Build/update data/lead-manifest.json from lead artifacts
   ingest        Submit a validated payload to the configured ingest API
+  enrich:platform  Measure public activity and select a refreshable primary platform
   verify        Run the full harness verification gate
   sync          Re-run consumer-project symlink sync
 

package/docs/ARCHITECTURE.md

@@ -82,4 +82,16 @@ The package also carries the `@agent-pattern-labs/iso-*` helper ecosystem for tr
 - page visits
 - ingest requests
 
+Lead records preserve optional enrichment fields such as `linkedinUrl`, `phone`,
+`address`, `streetAddress`, `location`, `city`, `region`, `postalCode`, and
+`country` through normalization, deduplication, and ingest.
+
+Primary-platform enrichment adds person-matched `socialProfiles` plus a compact
+consumer-facing selection (`primaryPlatform`, URL, confidence, method,
+evidence, checked timestamp, and next-refresh timestamp). Dated activity is
+measured only through official public GitHub, Bluesky, or YouTube endpoints.
+Networks without a permitted activity endpoint remain presence-only. The
+default refresh interval is seven days, and a fresh checkpoint prevents repeat
+requests.
+
 The validator intentionally accepts the same defaults the local runtime normalizes, but it fails missing source evidence, invalid URL fields, invalid `emailType`, invalid `verificationStatus`, invalid confidence, person leads without email, and generic catch-all inboxes such as `info@`, `hello@`, or similar organizational aliases. Any email record must be a named `person` lead with a non-generic email and a human owner visible in the evidence; role inboxes, unknown-owner emails, blocked emails, unsupported emails, and unnamed person-like emails fail validation. Summaries expose `goodLeadCount`, which only counts those high-quality named human email records.

package/docs/PRIMARY_PLATFORM.md

@@ -0,0 +1,35 @@
+# Primary Platform Enrichment
+
+`public-leads enrich:platform` adds a refreshable channel recommendation to a
+validated lead artifact without paid APIs.
+
+```bash
+public-leads enrich:platform \
+  --input data/leads.json \
+  --out data/leads-primary-platform.json \
+  --report data/leads-primary-platform-report.json \
+  --checkpoint data/leads-primary-platform.checkpoint.json \
+  --activity-window-days 90 \
+  --refresh-days 7 \
+  --concurrency 4
+```
+
+Run the same command weekly with the same checkpoint. Fresh profile
+measurements are reused. `GITHUB_TOKEN` is optional and only raises GitHub's
+public REST rate limit.
+
+## Selection Methods
+
+- `observed_public_activity` means a supported public endpoint returned dated
+  actions inside the configured activity window.
+- `fallback_presence_priority` means no comparable dated signal was available;
+  the configured B2B platform order selected the best known public profile.
+
+The worker uses GitHub public events, Bluesky's public author feed, and YouTube
+channel Atom feeds. It does not request LinkedIn, X, Facebook, or Instagram
+profile pages. It stores aggregate counts and timestamps, not post content.
+
+Page-level social links are accepted only when the profile username matches the
+named contact. Explicit person-profile fields such as `linkedinUrl` are trusted
+inputs. This prevents company footer accounts from being assigned to an
+individual lead.

package/lib/leadharness-crawler.mjs

@@ -961,6 +961,8 @@ function isPublicProfileUrl(value) {
     const host = url.hostname.toLowerCase().replace(/^www\./, '');
     const path = url.pathname.toLowerCase();
     if (host === 'linkedin.com') return /^\/(in|company)\//.test(path);
+    if (host === 'github.com') return /^\/[a-z0-9](?:[a-z0-9-]{0,37}[a-z0-9])?\/?$/i.test(path);
+    if (host === 'bsky.app') return /^\/profile\/[^/]+\/?$/i.test(path);
     if (host === 'x.com' || host === 'twitter.com') return path.length > 1 && !/^\/(share|intent|search|hashtag)\b/.test(path);
     if (host === 'facebook.com' || host === 'instagram.com' || host === 'youtube.com') return path.length > 1;
     return false;

package/lib/leadharness-leads.mjs

@@ -8,6 +8,7 @@ import {
   writeFileSync,
 } from 'fs';
 import { basename, dirname, extname, isAbsolute, join, relative, resolve } from 'path';
+import { normalizeSocialProfiles } from './leadharness-primary-platform.mjs';
 
 export const PROJECT_DIR = process.env.PUBLIC_LEADS_PROJECT || process.env.LEAD_HARNESS_PROJECT || process.cwd();
 export const HARNESS_ROOT = process.env.PUBLIC_LEADS_ROOT || process.env.LEAD_HARNESS_ROOT || resolve(dirname(new URL(import.meta.url).pathname), '..');
@@ -162,9 +163,18 @@ export function normalizeLead(input, { now = new Date().toISOString() } = {}) {
   const verificationStatus = normalizeVerificationStatus(input.verificationStatus, emailType);
   const confidence = clampInteger(input.confidence, 0, 100, 0);
   const foundAt = normalizeDateTime(input.foundAt, now);
+  const linkedinUrl = normalizeLinkedInUrl(input.linkedinUrl);
   const phone = stringValue(input.phone);
+  const address = compactWhitespace(input.address);
+  const streetAddress = compactWhitespace(input.streetAddress);
+  const location = compactWhitespace(input.location);
+  const city = compactWhitespace(input.city);
+  const region = compactWhitespace(input.region);
+  const postalCode = compactWhitespace(input.postalCode);
+  const country = compactWhitespace(input.country);
   const socialUrls = normalizeUrlList(input.socialUrls);
   const contactUrls = normalizeUrlList(input.contactUrls);
+  const socialProfiles = normalizeSocialProfiles(input.socialProfiles);
 
   const lead = {
     id: stringValue(input.id),
@@ -187,9 +197,25 @@ export function normalizeLead(input, { now = new Date().toISOString() } = {}) {
     verificationStatus,
     confidence,
     warnings: normalizeWarnings(input.warnings),
+    linkedinUrl,
     phone,
+    address,
+    streetAddress,
+    location,
+    city,
+    region,
+    postalCode,
+    country,
     socialUrls,
     contactUrls,
+    socialProfiles,
+    primaryPlatform: stringValue(input.primaryPlatform).toLowerCase(),
+    primaryPlatformUrl: normalizeHttpUrl(input.primaryPlatformUrl),
+    primaryPlatformConfidence: clampInteger(input.primaryPlatformConfidence, 0, 100, 0),
+    primaryPlatformSelectionMethod: stringValue(input.primaryPlatformSelectionMethod),
+    primaryPlatformEvidence: compactWhitespace(input.primaryPlatformEvidence),
+    primaryPlatformCheckedAt: normalizeOptionalDateTime(input.primaryPlatformCheckedAt),
+    primaryPlatformNextRefreshAt: normalizeOptionalDateTime(input.primaryPlatformNextRefreshAt),
     foundAt,
   };
 
@@ -343,6 +369,20 @@ export function validateLead(lead, path, issues) {
       if (!isHttpUrl(url)) issues.push(issue('warning', `${path}.contactUrls[${index}]`, 'invalid_contact_url', 'contactUrls entries should be http(s) URLs'));
     });
   }
+  if (!Array.isArray(lead.socialProfiles)) {
+    issues.push(issue('error', `${path}.socialProfiles`, 'invalid_social_profiles', 'socialProfiles must be an array'));
+  } else {
+    lead.socialProfiles.forEach((profile, index) => {
+      if (!profile?.platform) issues.push(issue('warning', `${path}.socialProfiles[${index}].platform`, 'missing_platform', 'social profile platform should be present'));
+      if (!isHttpUrl(profile?.url)) issues.push(issue('warning', `${path}.socialProfiles[${index}].url`, 'invalid_profile_url', 'social profile URL should be http(s)'));
+    });
+  }
+  if (lead.primaryPlatformUrl && !isHttpUrl(lead.primaryPlatformUrl)) {
+    issues.push(issue('warning', `${path}.primaryPlatformUrl`, 'invalid_primary_platform_url', 'primaryPlatformUrl should be an http(s) URL'));
+  }
+  if (!Number.isInteger(lead.primaryPlatformConfidence) || lead.primaryPlatformConfidence < 0 || lead.primaryPlatformConfidence > 100) {
+    issues.push(issue('error', `${path}.primaryPlatformConfidence`, 'invalid_primary_platform_confidence', 'primaryPlatformConfidence must be an integer from 0 to 100'));
+  }
   if (!Array.isArray(lead.warnings)) {
     issues.push(issue('error', `${path}.warnings`, 'invalid_warnings', 'warnings must be an array'));
   }
@@ -547,8 +587,25 @@ function normalizeLeadRecord(lead) {
     sources,
     evidence: sources[0]?.evidence || compactWhitespace(lead?.evidence),
     warnings: normalizeWarnings(lead?.warnings),
+    linkedinUrl: normalizeLinkedInUrl(lead?.linkedinUrl),
+    phone: stringValue(lead?.phone),
+    address: compactWhitespace(lead?.address),
+    streetAddress: compactWhitespace(lead?.streetAddress),
+    location: compactWhitespace(lead?.location),
+    city: compactWhitespace(lead?.city),
+    region: compactWhitespace(lead?.region),
+    postalCode: compactWhitespace(lead?.postalCode),
+    country: compactWhitespace(lead?.country),
     socialUrls: normalizeUrlList(lead?.socialUrls),
     contactUrls: normalizeUrlList(lead?.contactUrls),
+    socialProfiles: normalizeSocialProfiles(lead?.socialProfiles),
+    primaryPlatform: stringValue(lead?.primaryPlatform).toLowerCase(),
+    primaryPlatformUrl: normalizeHttpUrl(lead?.primaryPlatformUrl),
+    primaryPlatformConfidence: clampInteger(lead?.primaryPlatformConfidence, 0, 100, 0),
+    primaryPlatformSelectionMethod: stringValue(lead?.primaryPlatformSelectionMethod),
+    primaryPlatformEvidence: compactWhitespace(lead?.primaryPlatformEvidence),
+    primaryPlatformCheckedAt: normalizeOptionalDateTime(lead?.primaryPlatformCheckedAt),
+    primaryPlatformNextRefreshAt: normalizeOptionalDateTime(lead?.primaryPlatformNextRefreshAt),
   };
   normalized.id = stableLeadID(normalized);
   return normalized;
@@ -574,9 +631,25 @@ export function mergeLeadRecords(current, candidate) {
       ? secondary.verificationStatus
       : primary.verificationStatus,
     confidence: Math.max(primary.confidence || 0, secondary.confidence || 0),
+    linkedinUrl: primary.linkedinUrl || secondary.linkedinUrl,
     phone: primary.phone || secondary.phone,
+    address: longerString(primary.address, secondary.address),
+    streetAddress: primary.streetAddress || secondary.streetAddress,
+    location: longerString(primary.location, secondary.location),
+    city: primary.city || secondary.city,
+    region: primary.region || secondary.region,
+    postalCode: primary.postalCode || secondary.postalCode,
+    country: primary.country || secondary.country,
     socialUrls: normalizeUrlList([...(primary.socialUrls || []), ...(secondary.socialUrls || [])]),
     contactUrls: normalizeUrlList([...(primary.contactUrls || []), ...(secondary.contactUrls || [])]),
+    socialProfiles: normalizeSocialProfiles([...(primary.socialProfiles || []), ...(secondary.socialProfiles || [])]),
+    primaryPlatform: primary.primaryPlatform || secondary.primaryPlatform,
+    primaryPlatformUrl: primary.primaryPlatformUrl || secondary.primaryPlatformUrl,
+    primaryPlatformConfidence: Math.max(primary.primaryPlatformConfidence || 0, secondary.primaryPlatformConfidence || 0),
+    primaryPlatformSelectionMethod: primary.primaryPlatformSelectionMethod || secondary.primaryPlatformSelectionMethod,
+    primaryPlatformEvidence: longerString(primary.primaryPlatformEvidence, secondary.primaryPlatformEvidence),
+    primaryPlatformCheckedAt: latestDateTime(primary.primaryPlatformCheckedAt, secondary.primaryPlatformCheckedAt),
+    primaryPlatformNextRefreshAt: latestDateTime(primary.primaryPlatformNextRefreshAt, secondary.primaryPlatformNextRefreshAt),
     warnings: normalizeWarnings([...(primary.warnings || []), ...(secondary.warnings || [])]),
   };
 
@@ -842,6 +915,51 @@ function normalizeUrlList(value) {
   return urls;
 }
 
+function normalizeLinkedInUrl(value) {
+  let raw = stringValue(value);
+  if (!raw) return '';
+  if (!raw.includes('://')) raw = `https://${raw}`;
+
+  try {
+    const url = new URL(raw);
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') return '';
+    const host = url.hostname.toLowerCase();
+    if (host !== 'linkedin.com' && !host.endsWith('.linkedin.com')) return '';
+
+    const path = url.pathname.replace(/\/+$/, '');
+    if (!/^\/(in|pub|company|school|showcase)\//i.test(path)) return '';
+    return `https://www.linkedin.com${path}`;
+  } catch {
+    return '';
+  }
+}
+
+function normalizeHttpUrl(value) {
+  const raw = stringValue(value);
+  if (!raw) return '';
+  try {
+    const url = new URL(raw);
+    return ['http:', 'https:'].includes(url.protocol) ? url.toString() : '';
+  } catch {
+    return '';
+  }
+}
+
+function normalizeOptionalDateTime(value) {
+  const raw = stringValue(value);
+  if (!raw) return '';
+  const date = new Date(raw);
+  return Number.isNaN(date.getTime()) ? '' : date.toISOString();
+}
+
+function latestDateTime(...values) {
+  const dates = values
+    .map(normalizeOptionalDateTime)
+    .filter(Boolean)
+    .sort();
+  return dates.at(-1) || '';
+}
+
 function normalizeDateTime(value, fallback) {
   const raw = stringValue(value);
   if (!raw) return fallback;
@@ -876,6 +994,12 @@ function compactWhitespace(value) {
   return stringValue(value).replace(/\s+/g, ' ');
 }
 
+function longerString(left, right) {
+  const first = stringValue(left);
+  const second = stringValue(right);
+  return second.length > first.length ? second : first;
+}
+
 function displayCompany(domain) {
   const clean = normalizeDomain(domain);
   if (!clean) return '';

package/lib/leadharness-primary-platform.mjs

@@ -0,0 +1,512 @@
+const DEFAULT_PLATFORM_ORDER = ['linkedin', 'github', 'x', 'bluesky', 'youtube', 'instagram', 'facebook'];
+const ACTIVITY_PLATFORMS = new Set(['github', 'bluesky', 'youtube']);
+const BLOCKED_GITHUB_PATHS = new Set([
+  'about', 'apps', 'collections', 'customer-stories', 'enterprise', 'events',
+  'features', 'issues', 'marketplace', 'new', 'notifications', 'orgs', 'pricing',
+  'pulls', 'search', 'security', 'settings', 'sponsors', 'topics', 'trending',
+]);
+
+export async function enrichPrimaryPlatforms(payload, options = {}) {
+  const opts = normalizeOptions(options);
+  const leads = Array.isArray(payload?.leads) ? payload.leads : [];
+  const selected = opts.limit > 0 ? leads.slice(opts.offset, opts.offset + opts.limit) : leads.slice(opts.offset);
+  const selectedKeys = new Set(selected.map(leadKey));
+  const profilesByLead = new Map();
+  const uniqueProfiles = new Map();
+
+  for (const lead of selected) {
+    const profiles = discoverLeadProfiles(lead, opts.now);
+    profilesByLead.set(leadKey(lead), profiles);
+    for (const profile of profiles) uniqueProfiles.set(profileKey(profile), profile);
+  }
+
+  const measurements = new Map();
+  const pending = [...uniqueProfiles.values()].slice(0, opts.maxProfiles);
+  await mapLimit(pending, opts.concurrency, async (profile) => {
+    const key = profileKey(profile);
+    const cached = normalizeActivityProfile(opts.cache?.profiles?.[key]);
+    if (!opts.refresh && isFresh(cached, opts.now)) {
+	  opts.cacheHits += 1;
+      measurements.set(key, cached);
+      return;
+    }
+
+    const measured = await measureProfile(profile, opts);
+    if (measured.activityStatus === 'error' && hasUsableMeasurement(cached)) {
+      measurements.set(key, {
+        ...cached,
+        stale: true,
+        lastError: measured.lastError,
+      });
+      return;
+    }
+    measurements.set(key, measured);
+  });
+
+  const enrichedByKey = new Map();
+  for (const lead of selected) {
+    const profiles = (profilesByLead.get(leadKey(lead)) || []).map((profile) => {
+      const measured = measurements.get(profileKey(profile));
+      return measured || presenceOnlyProfile(profile, opts);
+    });
+    enrichedByKey.set(leadKey(lead), applyPrimaryPlatform(lead, profiles, opts));
+  }
+
+  const enrichLead = (lead) => selectedKeys.has(leadKey(lead))
+    ? enrichedByKey.get(leadKey(lead)) || lead
+    : lead;
+  const output = {
+    ...payload,
+    leads: leads.map(enrichLead),
+    results: Array.isArray(payload?.results)
+      ? payload.results.map((result) => ({
+        ...result,
+        leads: Array.isArray(result?.leads) ? result.leads.map(enrichLead) : [],
+      }))
+      : [],
+  };
+
+  const enriched = [...enrichedByKey.values()];
+  const report = {
+    generatedAt: opts.now,
+    inputLeads: leads.length,
+    selectedLeads: selected.length,
+    leadsWithProfiles: enriched.filter((lead) => lead.socialProfiles.length > 0).length,
+    leadsWithPrimaryPlatform: enriched.filter((lead) => lead.primaryPlatform).length,
+    observedActivitySelections: enriched.filter((lead) => lead.primaryPlatformSelectionMethod === 'observed_public_activity').length,
+    fallbackSelections: enriched.filter((lead) => lead.primaryPlatformSelectionMethod === 'fallback_presence_priority').length,
+    uniqueProfiles: uniqueProfiles.size,
+    measuredProfiles: [...measurements.values()].filter((profile) => ['observed', 'observed_inactive'].includes(profile.activityStatus)).length,
+	publicActivityRequests: opts.publicActivityRequests,
+	cacheHits: opts.cacheHits,
+    byPrimaryPlatform: countBy(enriched, (lead) => lead.primaryPlatform || 'none'),
+    bySelectionMethod: countBy(enriched, (lead) => lead.primaryPlatformSelectionMethod || 'none'),
+    directThirdPartyApiCostUsd: 0,
+    paidApiRequests: 0,
+    refreshDays: opts.refreshDays,
+    activityWindowDays: opts.activityWindowDays,
+  };
+  const cache = {
+    version: 1,
+    updatedAt: opts.now,
+    profiles: Object.fromEntries([...measurements.entries()]),
+  };
+  return { payload: output, report, cache };
+}
+
+export function discoverLeadProfiles(lead, now = new Date().toISOString()) {
+  const candidates = [];
+  const add = (value, trusted = false) => {
+    const profile = normalizeProfileUrl(value);
+    if (!profile) return;
+    if (!trusted && !profileMatchesContact(profile, lead?.contactName)) return;
+    candidates.push({
+      ...profile,
+      activityStatus: 'presence_only',
+      checkedAt: '',
+      nextRefreshAt: '',
+      discoveredAt: validDateTime(lead?.foundAt) || now,
+    });
+  };
+
+  add(lead?.linkedinUrl, true);
+  add(lead?.githubUrl, true);
+  add(lead?.twitterUrl, true);
+  add(lead?.youtubeUrl, true);
+  add(lead?.blueskyUrl, true);
+  for (const profile of Array.isArray(lead?.socialProfiles) ? lead.socialProfiles : []) {
+    const normalized = normalizeActivityProfile(profile);
+    if (normalized) candidates.push(normalized);
+  }
+  for (const value of Array.isArray(lead?.socialUrls) ? lead.socialUrls : []) add(value, false);
+
+  const byKey = new Map();
+  for (const profile of candidates) {
+    const key = profileKey(profile);
+    const current = byKey.get(key);
+    if (!current || profileRichness(profile) > profileRichness(current)) byKey.set(key, profile);
+  }
+  return [...byKey.values()].sort((left, right) => platformRank(left.platform) - platformRank(right.platform));
+}
+
+export function normalizeSocialProfiles(value) {
+  if (!Array.isArray(value)) return [];
+  const byKey = new Map();
+  for (const item of value) {
+    const normalized = normalizeActivityProfile(item);
+    if (!normalized) continue;
+    const key = profileKey(normalized);
+    const current = byKey.get(key);
+    if (!current || profileRichness(normalized) > profileRichness(current)) byKey.set(key, normalized);
+  }
+  return [...byKey.values()].sort((left, right) => platformRank(left.platform) - platformRank(right.platform));
+}
+
+export function normalizeProfileUrl(value) {
+  let url;
+  try {
+    url = new URL(String(value || '').trim().match(/^https?:\/\//i) ? String(value).trim() : `https://${String(value || '').trim()}`);
+  } catch {
+    return null;
+  }
+  if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password) return null;
+  const host = url.hostname.toLowerCase().replace(/^www\./, '');
+  const parts = url.pathname.split('/').filter(Boolean).map(decodeURIComponentSafe);
+  url.search = '';
+  url.hash = '';
+
+  if ((host === 'linkedin.com' || host.endsWith('.linkedin.com')) && parts[0]?.toLowerCase() === 'in' && parts[1]) {
+    return profile('linkedin', `https://www.linkedin.com/in/${encodeURIComponent(parts[1])}`, parts[1]);
+  }
+  if (host === 'github.com' && parts.length === 1 && !BLOCKED_GITHUB_PATHS.has(parts[0].toLowerCase())) {
+    return profile('github', `https://github.com/${encodeURIComponent(parts[0])}`, parts[0]);
+  }
+  if ((host === 'x.com' || host === 'twitter.com') && parts.length === 1 && !['home', 'search', 'share', 'intent', 'hashtag'].includes(parts[0].toLowerCase())) {
+    return profile('x', `https://x.com/${encodeURIComponent(parts[0])}`, parts[0]);
+  }
+  if (host === 'bsky.app' && parts[0]?.toLowerCase() === 'profile' && parts[1]) {
+    return profile('bluesky', `https://bsky.app/profile/${encodeURIComponent(parts[1])}`, parts[1]);
+  }
+  if ((host === 'youtube.com' || host === 'm.youtube.com') && parts[0]) {
+    if (parts[0].toLowerCase() === 'channel' && parts[1]) {
+      return { ...profile('youtube', `https://www.youtube.com/channel/${encodeURIComponent(parts[1])}`, parts[1]), channelId: parts[1] };
+    }
+    if (parts[0].startsWith('@')) return profile('youtube', `https://www.youtube.com/${encodeURIComponent(parts[0])}`, parts[0].slice(1));
+  }
+  if (host === 'instagram.com' && parts.length === 1) {
+    return profile('instagram', `https://www.instagram.com/${encodeURIComponent(parts[0])}`, parts[0]);
+  }
+  if (host === 'facebook.com' && parts.length === 1 && !['share', 'sharer', 'groups', 'pages'].includes(parts[0].toLowerCase())) {
+    return profile('facebook', `https://www.facebook.com/${encodeURIComponent(parts[0])}`, parts[0]);
+  }
+  return null;
+}
+
+export function selectPrimaryPlatform(profiles, options = {}) {
+  const order = normalizePlatformOrder(options.platformOrder);
+  const active = profiles
+    .filter((profile) => profile.activityStatus === 'observed' && profile.publicActivityCount > 0)
+    .sort((left, right) => activityScore(right, options.now) - activityScore(left, options.now));
+  if (active.length > 0) {
+    const winner = active[0];
+    const measuredCount = profiles.filter((profile) => ['observed', 'observed_inactive'].includes(profile.activityStatus)).length;
+    const gap = active.length > 1 ? activityScore(active[0], options.now) - activityScore(active[1], options.now) : 0;
+    const confidence = clamp(60 + (measuredCount > 1 ? 15 : 0) + (gap >= 25 ? 10 : 0), 0, 90);
+    return {
+      platform: winner.platform,
+      url: winner.url,
+      confidence,
+      selectionMethod: 'observed_public_activity',
+      evidence: winner.evidence,
+    };
+  }
+
+  const fallback = [...profiles].sort((left, right) => order.indexOf(left.platform) - order.indexOf(right.platform))[0];
+  if (!fallback) return { platform: '', url: '', confidence: 0, selectionMethod: '', evidence: '' };
+  return {
+    platform: fallback.platform,
+    url: fallback.url,
+    confidence: profiles.length === 1 ? 40 : 30,
+    selectionMethod: 'fallback_presence_priority',
+    evidence: `No comparable dated public activity was available; selected ${displayPlatform(fallback.platform)} using the configured presence fallback order.`,
+  };
+}
+
+async function measureProfile(profile, opts) {
+  if (!ACTIVITY_PLATFORMS.has(profile.platform)) return presenceOnlyProfile(profile, opts);
+  try {
+    if (profile.platform === 'github') return await measureGitHub(profile, opts);
+    if (profile.platform === 'bluesky') return await measureBluesky(profile, opts);
+    if (profile.platform === 'youtube') return await measureYouTube(profile, opts);
+  } catch (error) {
+    return {
+      ...presenceOnlyProfile(profile, opts),
+      activityStatus: 'error',
+      lastError: error instanceof Error ? error.message : String(error),
+    };
+  }
+  return presenceOnlyProfile(profile, opts);
+}
+
+async function measureGitHub(profile, opts) {
+  const endpoint = `https://api.github.com/users/${encodeURIComponent(profile.username)}/events/public?per_page=100`;
+  const headers = {
+    accept: 'application/vnd.github+json',
+    'user-agent': opts.userAgent,
+    'x-github-api-version': '2022-11-28',
+  };
+  if (opts.githubToken) headers.authorization = `Bearer ${opts.githubToken}`;
+	opts.publicActivityRequests += 1;
+  const events = await fetchJSON(endpoint, { ...opts, headers });
+  if (!Array.isArray(events)) throw new Error('GitHub returned an invalid public-events payload');
+  return observedProfile(profile, events.map((event) => event?.created_at), endpoint, opts, 'GitHub public events');
+}
+
+async function measureBluesky(profile, opts) {
+  const endpoint = new URL('https://public.api.bsky.app/xrpc/app.bsky.feed.getAuthorFeed');
+  endpoint.searchParams.set('actor', profile.username);
+  endpoint.searchParams.set('filter', 'posts_no_replies');
+  endpoint.searchParams.set('limit', '100');
+	opts.publicActivityRequests += 1;
+  const body = await fetchJSON(endpoint, {
+    ...opts,
+    headers: { accept: 'application/json', 'user-agent': opts.userAgent },
+  });
+  if (!Array.isArray(body?.feed)) throw new Error('Bluesky returned an invalid author-feed payload');
+  const dates = body.feed.map((item) => item?.post?.record?.createdAt || item?.post?.indexedAt);
+  return observedProfile(profile, dates, endpoint.toString(), opts, 'Bluesky public author posts');
+}
+
+async function measureYouTube(profile, opts) {
+  if (!profile.channelId) return presenceOnlyProfile(profile, opts);
+  const endpoint = `https://www.youtube.com/feeds/videos.xml?channel_id=${encodeURIComponent(profile.channelId)}`;
+	opts.publicActivityRequests += 1;
+  const xml = await fetchText(endpoint, {
+    ...opts,
+    headers: { accept: 'application/atom+xml,application/xml,text/xml', 'user-agent': opts.userAgent },
+  });
+  const dates = [...xml.matchAll(/<published>([^<]+)<\/published>/gi)].map((match) => match[1]);
+  return observedProfile(profile, dates, endpoint, opts, 'YouTube public channel uploads');
+}
+
+function observedProfile(profile, rawDates, sourceUrl, opts, label) {
+  const cutoff = new Date(new Date(opts.now).getTime() - opts.activityWindowDays * 86_400_000);
+  const dates = rawDates.map(validDate).filter((date) => date && date >= cutoff).sort((left, right) => right - left);
+  const count = dates.length;
+  const status = count > 0 ? 'observed' : 'observed_inactive';
+  const last = dates[0]?.toISOString() || '';
+  return {
+    ...profile,
+    activityStatus: status,
+    activityWindowDays: opts.activityWindowDays,
+    publicActivityCount: count,
+    lastPublicActivityAt: last,
+    checkedAt: opts.now,
+    nextRefreshAt: addDays(opts.now, opts.refreshDays),
+    activitySourceUrl: sourceUrl,
+    evidence: count > 0
+      ? `${label} show ${count} dated public activities in the last ${opts.activityWindowDays} days; the most recent was ${last}.`
+      : `${label} showed no dated public activity in the last ${opts.activityWindowDays} days.`,
+    stale: false,
+    lastError: '',
+  };
+}
+
+function presenceOnlyProfile(profile, opts) {
+  return {
+    ...profile,
+    activityStatus: 'presence_only',
+    activityWindowDays: opts.activityWindowDays,
+    publicActivityCount: 0,
+    lastPublicActivityAt: '',
+    checkedAt: opts.now,
+    nextRefreshAt: addDays(opts.now, opts.refreshDays),
+    activitySourceUrl: '',
+    evidence: `${displayPlatform(profile.platform)} profile presence is public, but no permitted comparable activity measurement was available.`,
+    stale: false,
+    lastError: '',
+  };
+}
+
+function applyPrimaryPlatform(lead, profiles, opts) {
+  const primary = selectPrimaryPlatform(profiles, opts);
+  return {
+    ...lead,
+    socialProfiles: profiles,
+    primaryPlatform: primary.platform,
+    primaryPlatformUrl: primary.url,
+    primaryPlatformConfidence: primary.confidence,
+    primaryPlatformSelectionMethod: primary.selectionMethod,
+    primaryPlatformEvidence: primary.evidence,
+    primaryPlatformCheckedAt: primary.platform ? opts.now : '',
+    primaryPlatformNextRefreshAt: primary.platform ? addDays(opts.now, opts.refreshDays) : '',
+  };
+}
+
+function normalizeActivityProfile(value) {
+  const base = normalizeProfileUrl(value?.url);
+  if (!base) return null;
+  return {
+    ...base,
+    ...(value?.channelId ? { channelId: String(value.channelId) } : {}),
+    activityStatus: String(value?.activityStatus || 'presence_only'),
+    activityWindowDays: clampInteger(value?.activityWindowDays, 0, 3650, 0),
+    publicActivityCount: clampInteger(value?.publicActivityCount, 0, 1_000_000, 0),
+    lastPublicActivityAt: validDateTime(value?.lastPublicActivityAt),
+    checkedAt: validDateTime(value?.checkedAt),
+    nextRefreshAt: validDateTime(value?.nextRefreshAt),
+    activitySourceUrl: httpUrl(value?.activitySourceUrl),
+    evidence: compact(value?.evidence),
+    discoveredAt: validDateTime(value?.discoveredAt),
+    stale: Boolean(value?.stale),
+    lastError: compact(value?.lastError),
+  };
+}
+
+async function fetchJSON(url, opts) {
+  const response = await fetchResponse(url, opts);
+  return response.json();
+}
+
+async function fetchText(url, opts) {
+  const response = await fetchResponse(url, opts);
+  return response.text();
+}
+
+async function fetchResponse(url, opts) {
+  const response = await opts.fetchImpl(url, {
+    headers: opts.headers,
+    signal: AbortSignal.timeout(opts.timeoutMs),
+  });
+  if (!response.ok) throw new Error(`${new URL(url).hostname} returned HTTP ${response.status}`);
+  return response;
+}
+
+function normalizeOptions(options) {
+  const now = validDateTime(options.now) || new Date().toISOString();
+  return {
+    now,
+    activityWindowDays: clampInteger(options.activityWindowDays, 7, 365, 90),
+    refreshDays: clampInteger(options.refreshDays, 1, 30, 7),
+    concurrency: clampInteger(options.concurrency, 1, 16, 4),
+    timeoutMs: clampInteger(options.timeoutMs, 1_000, 60_000, 8_000),
+    limit: clampInteger(options.limit, 0, 1_000_000, 0),
+    offset: clampInteger(options.offset, 0, 1_000_000, 0),
+    maxProfiles: clampInteger(options.maxProfiles, 1, 1_000_000, 100_000),
+    platformOrder: normalizePlatformOrder(options.platformOrder),
+    githubToken: String(options.githubToken || process.env.GITHUB_TOKEN || '').trim(),
+    userAgent: String(options.userAgent || 'PublicLeadsPrimaryPlatform/0.1 (+https://github.com/Agent-Pattern-Labs/leads-rig)'),
+    fetchImpl: options.fetchImpl || globalThis.fetch,
+    cache: options.cache && typeof options.cache === 'object' ? options.cache : {},
+    refresh: Boolean(options.refresh),
+	publicActivityRequests: 0,
+	cacheHits: 0,
+  };
+}
+
+function profile(platform, url, username) {
+  return { platform, url, username: String(username || '').replace(/^@/, '') };
+}
+
+function profileMatchesContact(profile, contactName) {
+  const words = comparable(contactName).split(' ').filter((word) => word.length >= 2);
+  if (words.length < 2) return false;
+  const first = words[0];
+  const last = words.at(-1);
+  const username = comparable(profile.username).replaceAll(' ', '');
+  return username.includes(`${first}${last}`)
+    || username.includes(`${last}${first}`)
+    || username.includes(`${first[0]}${last}`)
+    || username.includes(`${first}${last[0]}`);
+}
+
+function activityScore(profile, now) {
+  const countScore = Math.min(50, Math.log2(1 + profile.publicActivityCount) * 10);
+  const ageDays = profile.lastPublicActivityAt
+    ? Math.max(0, (new Date(now).getTime() - new Date(profile.lastPublicActivityAt).getTime()) / 86_400_000)
+    : 365;
+  return countScore + Math.max(0, 60 - ageDays);
+}
+
+function normalizePlatformOrder(value) {
+  const values = Array.isArray(value) ? value : String(value || '').split(',');
+  const clean = values.map((item) => String(item || '').trim().toLowerCase()).filter(Boolean);
+  return [...new Set([...clean, ...DEFAULT_PLATFORM_ORDER])];
+}
+
+function platformRank(value) {
+  const index = DEFAULT_PLATFORM_ORDER.indexOf(value);
+  return index === -1 ? DEFAULT_PLATFORM_ORDER.length : index;
+}
+
+function profileKey(profile) {
+  return `${profile.platform}|${profile.url}`;
+}
+
+function leadKey(lead) {
+  return String(lead?.id || `${lead?.domain || ''}|${lead?.email || ''}|${lead?.contactName || ''}`).toLowerCase();
+}
+
+function profileRichness(profile) {
+  return Number(Boolean(profile.lastPublicActivityAt)) * 10 + Number(profile.publicActivityCount || 0) + Number(Boolean(profile.evidence));
+}
+
+function hasUsableMeasurement(profile) {
+  return profile && ['observed', 'observed_inactive'].includes(profile.activityStatus);
+}
+
+function isFresh(profile, now) {
+  if (!profile?.nextRefreshAt) return false;
+  return new Date(profile.nextRefreshAt) > new Date(now);
+}
+
+function validDate(value) {
+  const date = new Date(String(value || ''));
+  return Number.isNaN(date.getTime()) ? null : date;
+}
+
+function validDateTime(value) {
+  return validDate(value)?.toISOString() || '';
+}
+
+function addDays(value, days) {
+  return new Date(new Date(value).getTime() + days * 86_400_000).toISOString();
+}
+
+function httpUrl(value) {
+  try {
+    const url = new URL(String(value || ''));
+    return ['http:', 'https:'].includes(url.protocol) ? url.toString() : '';
+  } catch {
+    return '';
+  }
+}
+
+function compact(value) {
+  return String(value || '').replace(/\s+/g, ' ').trim();
+}
+
+function comparable(value) {
+  return compact(value).normalize('NFKD').replace(/[\u0300-\u036f]/g, '').toLowerCase().replace(/[^a-z0-9]+/g, ' ').trim();
+}
+
+function displayPlatform(value) {
+  return value === 'x' ? 'X' : String(value || '').replace(/^./, (char) => char.toUpperCase());
+}
+
+function countBy(values, keyFn) {
+  const counts = {};
+  for (const value of values) {
+    const key = keyFn(value);
+    counts[key] = (counts[key] || 0) + 1;
+  }
+  return Object.fromEntries(Object.entries(counts).sort((left, right) => right[1] - left[1] || left[0].localeCompare(right[0])));
+}
+
+function clamp(value, min, max) {
+  return Math.max(min, Math.min(max, value));
+}
+
+function clampInteger(value, min, max, fallback) {
+  const number = Number(value);
+  return Number.isFinite(number) ? Math.round(clamp(number, min, max)) : fallback;
+}
+
+function decodeURIComponentSafe(value) {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+}
+
+async function mapLimit(items, limit, worker) {
+  let next = 0;
+  async function run() {
+    while (next < items.length) {
+      const index = next++;
+      await worker(items[index], index);
+    }
+  }
+  await Promise.all(Array.from({ length: Math.min(limit, items.length) }, run));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-pattern-labs/leads-rig",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "Agentic public-web lead discovery harness with portable ingest artifacts",
   "type": "module",
   "author": "Razroo",
@@ -30,6 +30,7 @@
     "lead:validate": "node bin/lead-harness.mjs validate",
     "lead:manifest": "node bin/lead-harness.mjs manifest",
     "lead:ingest": "node bin/lead-harness.mjs ingest",
+    "lead:enrich-platform": "node bin/lead-harness.mjs enrich:platform",
     "batch": "batch/batch-runner.sh",
     "trace:list": "node bin/lead-harness.mjs trace:list",
     "trace:stats": "node bin/lead-harness.mjs trace:stats",

package/scripts/enrich-platform.mjs

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+
+import { existsSync, readFileSync } from 'node:fs';
+import {
+  parseArgs,
+  readLeadArtifact,
+  validatePayload,
+  writeJson,
+} from '../lib/leadharness-leads.mjs';
+import { enrichPrimaryPlatforms } from '../lib/leadharness-primary-platform.mjs';
+
+const USAGE = `public-leads enrich:platform -- measure public platform activity and select a primary profile
+
+Usage:
+  public-leads enrich:platform --input data/leads.json
+      [--out data/leads-primary-platform.json]
+      [--report data/leads-primary-platform-report.json]
+      [--checkpoint data/leads-primary-platform.checkpoint.json]
+      [--activity-window-days 90] [--refresh-days 7]
+      [--platform-order linkedin,github,x,bluesky,youtube,instagram,facebook]
+      [--limit 0] [--offset 0] [--concurrency 4] [--timeout-ms 8000]
+      [--github-token <token>] [--refresh]
+
+Only permitted public activity endpoints are requested. LinkedIn, X, Instagram,
+and Facebook are presence-only fallbacks and are never crawled by this command.
+GitHub tokens are optional and only increase the public REST API rate limit.
+`;
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.stack || error.message : String(error));
+  process.exit(1);
+});
+
+async function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  if (opts.help) {
+    console.log(USAGE);
+    return;
+  }
+
+  const input = String(opts.input || opts._?.[0] || '').trim();
+  if (!input) throw new Error('--input is required');
+  if (!existsSync(input)) throw new Error(`input not found: ${input}`);
+  const stem = input.replace(/\.json$/i, '');
+  const out = String(opts.out || `${stem}-primary-platform.json`);
+  const reportOut = String(opts.report || `${stem}-primary-platform-report.json`);
+  const checkpoint = String(opts.checkpoint || `${stem}-primary-platform.checkpoint.json`);
+  const cache = loadCache(checkpoint);
+  const payload = readLeadArtifact(input);
+
+  const enriched = await enrichPrimaryPlatforms(payload, {
+    cache,
+    activityWindowDays: opts.activityWindowDays,
+    refreshDays: opts.refreshDays,
+    platformOrder: opts.platformOrder,
+    limit: opts.limit,
+    offset: opts.offset,
+    concurrency: opts.concurrency,
+    timeoutMs: opts.timeoutMs,
+    maxProfiles: opts.maxProfiles,
+    githubToken: opts.githubToken,
+    refresh: Boolean(opts.refresh),
+  });
+  const validation = validatePayload(enriched.payload, { allowEmpty: true });
+  enriched.report.validation = validation.summary;
+
+  writeJson(out, enriched.payload);
+  writeJson(reportOut, enriched.report);
+  writeJson(checkpoint, enriched.cache);
+  if (!validation.ok) {
+    const errors = validation.issues.filter((issue) => issue.severity === 'error');
+    throw new Error(errors.map((issue) => `${issue.path}: ${issue.message}`).join('\n'));
+  }
+
+  console.log(JSON.stringify({
+    status: 'COMPLETED',
+    ...enriched.report,
+    out,
+    report: reportOut,
+    checkpoint,
+  }, null, 2));
+}
+
+function loadCache(path) {
+  if (!existsSync(path)) return {};
+  try {
+    const value = JSON.parse(readFileSync(path, 'utf8'));
+    return value && typeof value === 'object' ? value : {};
+  } catch {
+    return {};
+  }
+}

package/templates/contracts.json

@@ -30,8 +30,24 @@
         },
         { "name": "confidence", "type": "integer", "required": true, "min": 0, "max": 100 },
         { "name": "warnings", "type": "json" },
+        { "name": "linkedinUrl", "type": "url" },
         { "name": "phone", "type": "string" },
+        { "name": "address", "type": "string" },
+        { "name": "streetAddress", "type": "string" },
+        { "name": "location", "type": "string" },
+        { "name": "city", "type": "string" },
+        { "name": "region", "type": "string" },
+        { "name": "postalCode", "type": "string" },
+        { "name": "country", "type": "string" },
         { "name": "socialUrls", "type": "json" },
+        { "name": "socialProfiles", "type": "json" },
+        { "name": "primaryPlatform", "type": "string" },
+        { "name": "primaryPlatformUrl", "type": "url" },
+        { "name": "primaryPlatformConfidence", "type": "integer", "min": 0, "max": 100 },
+        { "name": "primaryPlatformSelectionMethod", "type": "string" },
+        { "name": "primaryPlatformEvidence", "type": "string" },
+        { "name": "primaryPlatformCheckedAt", "type": "datetime" },
+        { "name": "primaryPlatformNextRefreshAt", "type": "datetime" },
         { "name": "contactUrls", "type": "json" },
         { "name": "foundAt", "type": "datetime" }
       ],

package/templates/lead-schema.json

@@ -74,16 +74,52 @@
           "items": { "type": "string" },
           "default": []
         },
+        "linkedinUrl": {
+          "type": "string",
+          "description": "Optional canonical public LinkedIn profile or organization URL."
+        },
         "phone": {
           "type": "string",
           "description": "Optional normalized phone number found near the public contact evidence."
         },
+        "address": {
+          "type": "string",
+          "description": "Optional complete public business address."
+        },
+        "streetAddress": {
+          "type": "string",
+          "description": "Optional street-address component."
+        },
+        "location": {
+          "type": "string",
+          "description": "Optional display location for the lead."
+        },
+        "city": { "type": "string" },
+        "region": { "type": "string" },
+        "postalCode": { "type": "string" },
+        "country": { "type": "string" },
         "socialUrls": {
           "type": "array",
           "items": { "type": "string" },
           "default": [],
           "description": "Optional public social/profile URLs found on the same source page."
         },
+        "socialProfiles": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/socialProfile" },
+          "default": [],
+          "description": "Public person-matched profiles with refreshable activity measurements."
+        },
+        "primaryPlatform": { "type": "string" },
+        "primaryPlatformUrl": { "type": "string" },
+        "primaryPlatformConfidence": { "type": "integer", "minimum": 0, "maximum": 100 },
+        "primaryPlatformSelectionMethod": {
+          "type": "string",
+          "enum": ["", "observed_public_activity", "fallback_presence_priority"]
+        },
+        "primaryPlatformEvidence": { "type": "string" },
+        "primaryPlatformCheckedAt": { "type": "string" },
+        "primaryPlatformNextRefreshAt": { "type": "string" },
         "contactUrls": {
           "type": "array",
           "items": { "type": "string" },
@@ -96,6 +132,28 @@
         }
       }
     },
+    "socialProfile": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["platform", "url", "activityStatus"],
+      "properties": {
+        "platform": { "type": "string" },
+        "url": { "type": "string" },
+        "username": { "type": "string" },
+        "activityStatus": {
+          "type": "string",
+          "enum": ["presence_only", "observed", "observed_inactive", "unavailable", "error"]
+        },
+        "activityWindowDays": { "type": "integer", "minimum": 0 },
+        "publicActivityCount": { "type": "integer", "minimum": 0 },
+        "lastPublicActivityAt": { "type": "string" },
+        "checkedAt": { "type": "string" },
+        "nextRefreshAt": { "type": "string" },
+        "activitySourceUrl": { "type": "string" },
+        "evidence": { "type": "string" },
+        "stale": { "type": "boolean" }
+      }
+    },
     "result": {
       "type": "object",
       "additionalProperties": true,