indiecrm-cli 0.1.0 → 0.2.0

package/dist/company-identity-review.js

@@ -0,0 +1,78 @@
+import { companyIdentityKey } from "./company-recovery.js";
+import { createInterface } from "node:readline/promises";
+/** Cancelling a terminal question must reject it so research can release its lock. */
+export function createCompanyReviewPrompt(input = process.stdin, output = process.stderr) {
+    const rl = createInterface({ input, output, terminal: true });
+    const cancellation = new AbortController();
+    const cancel = () => cancellation.abort();
+    const signals = ["SIGINT", "SIGTERM", "SIGHUP"];
+    rl.on("SIGINT", cancel);
+    rl.once("close", cancel);
+    for (const signal of signals)
+        process.on(signal, cancel);
+    return {
+        io: {
+            write: (text) => { output.write(text); },
+            ask: async (question) => {
+                try {
+                    return await rl.question(question, { signal: cancellation.signal });
+                }
+                catch (error) {
+                    if (cancellation.signal.aborted)
+                        throw new Error("Company review cancelled. Saved work is preserved; rerun with the same --out-dir to resume.");
+                    throw error;
+                }
+            },
+        },
+        close: () => {
+            for (const signal of signals)
+                process.off(signal, cancel);
+            rl.close();
+        },
+    };
+}
+export const terminalText = (text) => text.replace(/[\x00-\x1f\x7f-\x9f\u202a-\u202e\u2066-\u2069]/g, " ").slice(0, 300);
+export async function chooseCompanyIdentity(input) {
+    const { targetName, diagnostic, details, io } = input;
+    const candidates = [...new Map(diagnostic.candidates.filter(c => /^[1-9]\d*$/.test(c.companyId) && companyIdentityKey(c.name) === companyIdentityKey(targetName)).map(c => [c.companyId, c])).values()];
+    io.write(`\nCompany review: ${terminalText(targetName)}\n`);
+    if (!candidates.length || candidates.length > 10) {
+        io.write("No bounded exact-name choice is available. Inspect recovery.json and use an evidence-backed --review-file; this company remains unresolved.\n");
+        return null;
+    }
+    const verified = [];
+    for (const candidate of candidates) {
+        const evidence = await details(candidate.companyId);
+        if (!evidence || evidence.companyId !== candidate.companyId || evidence.evidenceUrl !== `https://www.linkedin.com/sales/company/${candidate.companyId}` || companyIdentityKey(evidence.name) !== companyIdentityKey(candidate.name))
+            continue;
+        verified.push(evidence);
+        io.write(`\n${verified.length}. ${terminalText(evidence.name)}\n   Location: ${terminalText(evidence.location ?? "not provided")}\n   Website: ${terminalText(evidence.website ?? "not provided")}\n   Evidence: ${terminalText(evidence.evidenceUrl)}\n`);
+    }
+    if (!verified.length) {
+        io.write("No candidate could be verified. Nothing approved.\n");
+        return null;
+    }
+    io.write("\nMatch the location and website to your intended company. No choice is preselected.\n");
+    while (true) {
+        const answer = (await io.ask("Company number [0 = skip]: ")).trim();
+        if (!answer || answer === "0")
+            return null;
+        if (!/^[1-9]\d*$/.test(answer) || Number(answer) > verified.length) {
+            io.write("Enter a listed number, or 0 to skip.\n");
+            continue;
+        }
+        const chosen = verified[Number(answer) - 1];
+        const confirm = await io.ask(`Use ${terminalText(chosen.name)} (${terminalText(chosen.location ?? chosen.companyId)}) for ${terminalText(targetName)}? [y/N]: `);
+        return /^(y|yes)$/i.test(confirm.trim()) ? chosen : null;
+    }
+}
+export function companyResearchNextCommand(input) {
+    const quote = (text) => `'${text.replace(/'/g, "'\\''")}'`;
+    const scope = (input.companies ?? []).map(name => ` --company ${quote(name)}`).join("");
+    const base = `indiecrm leads:at-companies --brief ${quote(input.brief)} --out-dir ${quote(input.outDir)} --browser ${input.browser}${scope}`;
+    if (input.unresolved)
+        return `${base} --resolve-companies --review --all`;
+    if (input.pending)
+        return `${base} --all`;
+    return null;
+}

package/dist/company-leads.js

@@ -0,0 +1,422 @@
+import { createHash } from "node:crypto";
+import { mkdir, readFile, rename, writeFile, chmod, rmdir } from "node:fs/promises";
+import path from "node:path";
+import { z } from "zod";
+import { buildSalesNavigatorPeopleSearchUrl } from "./sales-navigator.js";
+import { CompanyReviewSchema, companyIdentityKey } from "./company-recovery.js";
+export const defaultDepartments = [
+    { name: "Digital Marketing & CRM", terms: ["marketing", "crm", "growth", "communication"], reviewTerms: ["communication"] },
+    { name: "Digital Product & UX", terms: ["product", "ux", "design"], reviewTerms: [] },
+    { name: "Software Development", terms: ["software", "engineering", "development", "cto", "operational technology"], reviewTerms: ["operational technology"] },
+    { name: "IT", terms: ["it", "information technology", "cio", "digital workplace", "chief digital officer", "cdo", "digital", "transformation"], reviewTerms: ["digital", "transformation"] },
+    { name: "Data & AI", terms: ["data", "ai", "artificial intelligence", "analytics", "business intelligence"], reviewTerms: [] },
+    { name: "HR", terms: ["hr", "human resources", "people", "personal", "chro", "talent"], reviewTerms: [] },
+];
+const companySchema = z.object({
+    name: z.string().trim().min(1),
+    companyId: z.string().regex(/^[1-9]\d*$/).optional(),
+    verifiedEmployerAliases: z.array(z.object({ name: z.string().trim().min(1), evidenceUrl: z.url() }).strict()).optional(),
+    maxContacts: z.number().int().min(1).max(100).default(20),
+}).strict();
+export const CompanyBriefSchema = z.object({
+    companies: z.array(companySchema).min(1),
+    departments: z.array(z.object({ name: z.string().trim().min(1), terms: z.array(z.string().trim().min(1)).min(1), reviewTerms: z.array(z.string().trim().min(1)).default([]) }).strict()).min(1).default(defaultDepartments),
+    regionIds: z.array(z.string().regex(/^[1-9]\d*$/)).default([]),
+    candidatesPerDepartment: z.number().int().min(1).max(100).default(50),
+}).strict().superRefine((brief, ctx) => {
+    const ids = brief.companies.flatMap(c => c.companyId ? [c.companyId] : []);
+    if (new Set(ids).size !== ids.length)
+        ctx.addIssue({ code: "custom", message: "Duplicate company IDs: merge aliases into one target company." });
+    const names = brief.departments.map(d => d.name.toLowerCase());
+    if (new Set(names).size !== names.length)
+        ctx.addIssue({ code: "custom", message: "Department names must be unique." });
+    for (const department of brief.departments) {
+        if (department.reviewTerms.some(term => !department.terms.some(t => words(t) === words(term))))
+            ctx.addIssue({ code: "custom", message: "Review terms must also be included in department search terms." });
+    }
+});
+export function planCompanySearches(brief) {
+    return brief.companies.filter(c => c.companyId).flatMap(company => brief.departments.map((department, index) => ({
+        key: `${company.companyId}:${index}`, company, department,
+        queryUrl: buildSalesNavigatorPeopleSearchUrl([
+            { type: "CURRENT_COMPANY", values: [{ id: company.companyId, text: company.name, selectionType: "INCLUDED" }] },
+            { type: "CURRENT_TITLE", values: department.terms.map(term => ({ text: term, selectionType: "INCLUDED" })) },
+            { type: "SENIORITY_LEVEL", values: [{ id: "310", text: "CXO" }, { id: "300", text: "Vice President" }, { id: "220", text: "Director" }, { id: "210", text: "Experienced Manager" }].map(v => ({ ...v, selectionType: "INCLUDED" })) },
+            ...(brief.regionIds.length ? [{ type: "REGION", values: brief.regionIds.map(id => ({ id, text: id, selectionType: "INCLUDED" })) }] : []),
+        ]),
+    })));
+}
+function words(text) {
+    return text.toLowerCase().normalize("NFKC")
+        .replace(/\b(marketing|personal|entwicklungs|it)leiter(in)?\b/g, (_, functionName, suffix) => `${functionName === "personal" ? "hr" : functionName === "entwicklungs" ? "development" : functionName} leiter${suffix ?? ""}`)
+        .replace(/[^\p{L}\p{N}]+/gu, " ").trim();
+}
+function hasTerm(title, term) { return ` ${words(title)} `.includes(` ${words(term)} `); }
+function senior(title) {
+    title = words(title);
+    return /\b(director|head|chief|ceo|cto|cio|cdo|cmo|chro|cpo|vp|vice president|vorstand|geschäftsführ\w*|(?:fachbereichs|bereichs|abteilungs|ressort|hauptabteilungs)?leiter(?:in)?|(?:fachbereichs|bereichs|abteilungs)?leitung)\b/i.test(title)
+        && !/\b(assistant|assistent\w*|assistenz|deputy|stellvertret\w*|former|ehemalig\w*)\b/i.test(title);
+}
+// A senior role in one clause must not promote an assistant/former role in another.
+export function classifyCompanyRole(title, department) {
+    const clauses = title.split(/\s*[|;\n]\s*|,\s*(?=(?:sr\.?\s+|senior\s+)?(?:director|head|chief|deputy|assistant|former|vp|vice president|leiter|fachbereichsleiter)\b)/i);
+    const relevant = clauses.filter(clause => senior(clause));
+    if (!relevant.length)
+        return "seniority_not_verified";
+    const reviewTerms = new Set(department.reviewTerms.map(words));
+    const contextMatches = (clause) => {
+        const t = words(clause);
+        if (department.name === "Software Development")
+            return /\b(software|cto|developer|developers|devops|frontend|backend|full stack)\b/.test(t);
+        if (department.name === "Digital Product & UX")
+            return /\b(ux|user experience|digital product|software product|product design|digital design|ui)\b/.test(t) && !/\b(vehicles|mechanical|industrial design|hardware design)\b/.test(t);
+        if (department.name === "Data & AI" && /\b(technical data|hydraulic|flight control)\b/.test(t))
+            return /\b(analytics|artificial intelligence|machine learning|data science|data engineering)\b/.test(t);
+        return true;
+    };
+    if (relevant.some(clause => contextMatches(clause) && department.terms.some(term => !reviewTerms.has(words(term)) && hasTerm(clause, term))))
+        return "match";
+    if (relevant.some(clause => department.terms.some(term => hasTerm(clause, term))))
+        return "review";
+    // Mixed-role headlines need a human decision, never borrow seniority across clauses.
+    if (clauses.length > 1 && department.terms.some(term => hasTerm(title, term)))
+        return "review";
+    return "function_not_verified";
+}
+function seniorRank(title) {
+    if (/\b(chief|ceo|cto|cio|cdo|cmo|chro|cpo|vorstand|geschäftsführ\w*)\b/i.test(title))
+        return 0;
+    if (/\b(vp|vice president|head|leiter\w*|leitung)\b/i.test(title))
+        return 1;
+    return 2;
+}
+export function canonicalProfile(value) {
+    try {
+        const u = new URL(value);
+        if (!/(^|\.)linkedin\.com$/i.test(u.hostname) || !/^\/(in|sales\/lead)\/[^/]+/.test(u.pathname))
+            return null;
+        return `https://www.linkedin.com${u.pathname.replace(/\/$/, "")}`;
+    }
+    catch {
+        return null;
+    }
+}
+export function shortlistCompanyLeads(brief, results) {
+    const selected = [];
+    const rejected = [];
+    const review = [];
+    const reviewSeen = new Set();
+    const coverage = [];
+    const seen = new Set();
+    for (const company of brief.companies) {
+        const jobs = planCompanySearches({ ...brief, companies: [company] });
+        const buckets = jobs.map(job => {
+            const rows = [];
+            for (const p of results[job.key]?.people ?? []) {
+                const profile = canonicalProfile(p.profileUrl);
+                // Prefer the actual current job over a free-form profile headline.
+                const raw = p.rawLocalSalesNavigatorResult;
+                const positions = raw?.currentPositions?.filter(x => String(x.companyId ?? x.companyUrn?.split(":").pop() ?? "") === company.companyId);
+                const titles = positions?.length ? positions.map(x => String(x.title ?? "")) : [String(p.title ?? "")];
+                const title = titles.find(t => classifyCompanyRole(t, job.department) === "match") ?? titles.find(t => classifyCompanyRole(t, job.department) === "review") ?? titles[0];
+                const exactCompany = raw?.currentPositions?.length ? Boolean(positions?.length) : String(p.companyId ?? "") === company.companyId;
+                const role = classifyCompanyRole(title, job.department);
+                const reason = !profile ? "invalid_profile" : !exactCompany ? "company_not_verified" : role !== "match" && role !== "review" ? role : null;
+                if (reason) {
+                    rejected.push({ companyId: company.companyId, profileUrl: p.profileUrl, reason });
+                    continue;
+                }
+                const sourceCompanyName = positions?.find(p => p.title === title)?.companyName ?? p.companyName ?? "";
+                const alias = company.verifiedEmployerAliases?.find(a => words(a.name) === words(String(sourceCompanyName)));
+                const employerNameDiffers = Boolean(sourceCompanyName) && words(String(sourceCompanyName)) !== words(company.name) && !alias;
+                const row = { profileUrl: profile, fullName: p.fullName ?? "", title, companyId: company.companyId, companyName: company.name, sourceCompanyName, employerAliasEvidence: alias?.evidenceUrl ?? "", department: job.department.name, location: p.location ?? "", sourceQueryUrl: job.queryUrl, observedAt: p.timestamp ?? "" };
+                if (role === "review" || employerNameDiffers) {
+                    const key = `${company.companyId}:${job.department.name}:${profile}`;
+                    if (!reviewSeen.has(key)) {
+                        reviewSeen.add(key);
+                        review.push({ ...row, reason: employerNameDiffers ? "employer_name_differs" : "ambiguous_role", reasons: [...(employerNameDiffers ? ["employer_name_differs"] : []), ...(role === "review" ? ["ambiguous_role"] : [])] });
+                    }
+                    continue;
+                }
+                rows.push(row);
+            }
+            return rows.sort((a, b) => seniorRank(String(a.title)) - seniorRank(String(b.title)) || String(a.profileUrl).localeCompare(String(b.profileUrl)));
+        });
+        const local = [];
+        // Round-robin selection stops one function consuming the entire company allowance.
+        while (local.length < company.maxContacts && buckets.some(b => b.length)) {
+            for (const bucket of buckets) {
+                let row;
+                while ((row = bucket.shift())) {
+                    const key = String(row.profileUrl);
+                    if (!seen.has(key)) {
+                        seen.add(key);
+                        local.push(row);
+                        break;
+                    }
+                }
+                if (local.length >= company.maxContacts)
+                    break;
+            }
+        }
+        selected.push(...local);
+        coverage.push({ companyName: company.name, companyId: company.companyId ?? null, selected: local.length, reviewRequired: review.filter(p => p.companyId === company.companyId).length, ceiling: company.maxContacts,
+            status: !company.companyId ? "unresolved_company" : jobs.some(j => !results[j.key]) ? "pending" : local.length ? "review_ready" : "no_verified_matches",
+            departments: jobs.map(j => ({ name: j.department.name, selected: local.filter(p => p.department === j.department.name).length, collected: results[j.key]?.people.length ?? null, reported: results[j.key]?.totalResults ?? null, stoppedReason: results[j.key]?.stoppedReason ?? null, searchComplete: results[j.key]?.totalResults != null ? !results[j.key].stoppedReason && results[j.key].people.length >= results[j.key].totalResults : null })) });
+    }
+    const jobs = planCompanySearches(brief);
+    const completed = jobs.filter(j => results[j.key]);
+    const incomplete = completed.filter(j => results[j.key].stoppedReason || results[j.key].totalResults != null && results[j.key].people.length < results[j.key].totalResults);
+    const unknown = completed.filter(j => results[j.key].totalResults == null);
+    const selectedIds = new Set(selected.map(p => String(p.profileUrl)));
+    const reviewIds = new Set(review.map(p => String(p.profileUrl)));
+    const unresolved = brief.companies.filter(c => !c.companyId);
+    const progress = {
+        selectedPeople: selectedIds.size, reviewRows: review.length, reviewPeople: reviewIds.size,
+        reviewOnlyPeople: [...reviewIds].filter(id => !selectedIds.has(id)).length,
+        candidateRows: completed.reduce((n, j) => n + results[j.key].people.length, 0),
+        completedSearches: completed.length, totalSearches: jobs.length, remainingSearches: jobs.length - completed.length,
+        partialSearches: incomplete.length, unknownCoverageSearches: unknown.length, unresolvedCompanies: unresolved.length,
+        collectionComplete: completed.length === jobs.length && !unresolved.length && !incomplete.length && !unknown.length,
+        geography: brief.regionIds.length ? "explicit_regions" : "unrestricted",
+    };
+    const nextActions = [
+        ...(progress.remainingSearches ? ["Resume the unchanged brief and output directory to collect pending searches."] : []),
+        ...(unresolved.length ? ["Use --review in a terminal to choose a verified exact-name identity. Inspect recovery.json for non-exact decisions or an intentional --retry-unresolved --resolve-companies retry."] : []),
+        ...(incomplete.length || unknown.length ? ["Use --continue-partial quota or exhaustive to resume eligible pages; inspect stoppedReason before claiming exhaustive coverage."] : []),
+        ...(review.length ? ["Use --verify-employers for canonical names, or evidence-backed --review-file aliases. Ambiguous roles remain review-only."] : []),
+    ];
+    const outcome = unresolved.length ? "needs_review" : !progress.collectionComplete ? "incomplete" : review.length ? "needs_review" : "complete";
+    return { outcome, selected, review, rejected, coverage, progress, nextActions, rolePolicyVersion: 2, outreachStarted: false, emailEnrichmentStarted: false };
+}
+export function companyLeadCsv(rows) {
+    const columns = ["companyName", "companyId", "fullName", "title", "department", "profileUrl", "location", "sourceQueryUrl", "observedAt", "sourceCompanyName", "reason", "reasons", "employerAliasEvidence"];
+    const escape = (value) => { let s = String(value ?? ""); if (/^[=+@\-\t\r]/.test(s))
+        s = "'" + s; return `"${s.replace(/"/g, '""')}"`; };
+    return [columns.join(","), ...rows.map(r => columns.map(c => escape(r[c])).join(","))].join("\n") + "\n";
+}
+export async function runCompanyResearch(input) {
+    await mkdir(input.outDir, { recursive: true, mode: 0o700 });
+    const lock = path.join(input.outDir, ".research-lock");
+    try {
+        await mkdir(lock, { mode: 0o700 });
+    }
+    catch (e) {
+        if (e.code === "EEXIST")
+            throw new Error("Research directory is locked by another run. If it crashed, remove only .research-lock after confirming the process stopped.");
+        throw e;
+    }
+    try {
+        return await runCompanyResearchLocked(input);
+    }
+    finally {
+        await rmdir(lock);
+    }
+}
+async function runCompanyResearchLocked(input) {
+    const { brief, outDir, scope } = input;
+    await mkdir(outDir, { recursive: true, mode: 0o700 });
+    const fingerprint = createHash("sha256").update(JSON.stringify({ brief, scope })).digest("hex");
+    const checkpoint = path.join(outDir, "checkpoint.json");
+    let state = { fingerprint, results: {} };
+    try {
+        state = JSON.parse(await readFile(checkpoint, "utf8"));
+        if (state.fingerprint !== fingerprint)
+            throw new Error("Brief or workspace changed. Use a new output directory.");
+    }
+    catch (e) {
+        if (e.code !== "ENOENT")
+            throw e;
+    }
+    const save = async (file, value) => { await writeFile(file + ".tmp", value, { mode: 0o600 }); await chmod(file + ".tmp", 0o600); await rename(file + ".tmp", file); };
+    let review = input.review ? CompanyReviewSchema.parse(input.review) : undefined;
+    if (!review) {
+        try {
+            review = CompanyReviewSchema.parse(JSON.parse(await readFile(path.join(outDir, "review-decisions.json"), "utf8")));
+        }
+        catch (e) {
+            if (e.code !== "ENOENT")
+                throw e;
+        }
+    }
+    if (review && review.fingerprint !== fingerprint)
+        throw new Error("Review decisions belong to a different brief or workspace.");
+    for (const identity of review?.identities ?? []) {
+        const index = brief.companies.findIndex(c => c.name === identity.targetName);
+        if (index < 0 || brief.companies[index].companyId || state.resolutions?.[String(index)] && state.resolutions[String(index)].companyId !== identity.companyId)
+            throw new Error("Reviewed identity must target an unresolved company in this brief.");
+        const occupied = [...brief.companies.flatMap(c => c.companyId ? [c.companyId] : []), ...Object.entries(state.resolutions ?? {}).filter(([i]) => i !== String(index)).flatMap(([, r]) => r ? [r.companyId] : [])];
+        if (occupied.includes(identity.companyId))
+            throw new Error("Reviewed identity is already assigned to another target.");
+        state.resolutions ??= {};
+        state.resolutions[String(index)] = { companyId: identity.companyId, companyName: identity.targetName, canonicalName: identity.canonicalName, evidenceUrl: identity.evidenceUrl };
+    }
+    const effectiveBrief = () => CompanyBriefSchema.parse({ ...brief, companies: brief.companies.map((company, index) => {
+            const resolution = state.resolutions?.[String(index)];
+            const resolved = !company.companyId && resolution ? { ...company, companyId: resolution.companyId } : company;
+            const evidence = resolved.companyId ? state.employerEvidence?.[resolved.companyId] : undefined;
+            const aliases = [...(resolved.verifiedEmployerAliases ?? []), ...(review?.employerAliases.filter(a => a.companyId === resolved.companyId).map(({ name, evidenceUrl }) => ({ name, evidenceUrl })) ?? [])];
+            if (resolution?.canonicalName)
+                aliases.push({ name: resolution.canonicalName, evidenceUrl: resolution.evidenceUrl });
+            if (evidence && companyIdentityKey(evidence.name) === companyIdentityKey(resolved.name))
+                aliases.push({ name: evidence.name, evidenceUrl: evidence.evidenceUrl });
+            return { ...resolved, verifiedEmployerAliases: aliases };
+        }) });
+    const allowed = (name) => !input.onlyCompanies?.length || input.onlyCompanies.includes(name);
+    for (const name of input.onlyCompanies ?? [])
+        if (!brief.companies.some(c => c.name === name))
+            throw new Error(`Unknown target company: ${name}`);
+    for (const alias of review?.employerAliases ?? [])
+        if (!effectiveBrief().companies.some(c => c.companyId === alias.companyId))
+            throw new Error("Reviewed alias targets an unknown company ID.");
+    if (input.review) {
+        await save(path.join(outDir, "review-decisions.json"), JSON.stringify(review, null, 2));
+        await save(checkpoint, JSON.stringify(state));
+    }
+    const publish = async () => {
+        const report = shortlistCompanyLeads(effectiveBrief(), state.results);
+        const aliases = new Map();
+        for (const row of report.review.filter(r => r.reason === "employer_name_differs")) {
+            const id = String(row.companyId), name = String(row.sourceCompanyName);
+            aliases.set(`${id}:${name}`, { companyId: id, targetName: String(row.companyName), name, evidenceUrl: `https://www.linkedin.com/sales/company/${id}`, status: "needs_verification" });
+        }
+        await save(path.join(outDir, "contacts.csv"), companyLeadCsv(report.selected));
+        await save(path.join(outDir, "review.csv"), companyLeadCsv(report.review));
+        await save(path.join(outDir, "coverage.json"), JSON.stringify(report, null, 2));
+        await save(path.join(outDir, "company-resolutions.json"), JSON.stringify(state.resolutions ?? {}, null, 2));
+        await save(path.join(outDir, "recovery.json"), JSON.stringify({ fingerprint, aliases: [...aliases.values()], identities: brief.companies.flatMap((c, i) => !c.companyId && !state.resolutions?.[String(i)] ? [{ targetName: c.name, diagnostic: state.diagnostics?.[String(i)] ?? { reason: "legacy_unknown" } }] : []), reviewFileTemplate: { fingerprint, employerAliases: [], identities: [] } }, null, 2));
+        return report;
+    };
+    let performed = 0;
+    try {
+        if (input.verifyEmployer)
+            for (const company of effectiveBrief().companies) {
+                if (!company.companyId || !allowed(company.name) || state.employerEvidence?.[company.companyId])
+                    continue;
+                if (!Object.values(state.results).some(result => result.people.some(p => String(p.companyId) === company.companyId)))
+                    continue;
+                const evidence = await input.verifyEmployer(company.companyId);
+                if (evidence?.companyId === company.companyId) {
+                    state.employerEvidence ??= {};
+                    state.employerEvidence[company.companyId] = evidence;
+                    await save(checkpoint, JSON.stringify(state));
+                    await publish();
+                }
+            }
+        // Known IDs run first; an unresolved identity cannot block already prepared work.
+        const collect = async () => {
+            for (const job of planCompanySearches(effectiveBrief())) {
+                if (!allowed(job.company.name))
+                    continue;
+                const previous = state.results[job.key];
+                const defaultBudgetFinished = previous && (previous.nextOffset == null || previous.nextOffset >= brief.candidatesPerDepartment);
+                if (previous && (!input.continuePartial && defaultBudgetFinished || previous.totalResults != null && previous.people.length >= previous.totalResults || previous.stoppedReason))
+                    continue;
+                if (previous && input.continuePartial === "quota" && shortlistCompanyLeads(effectiveBrief(), state.results).coverage.find(c => c.companyId === job.company.companyId).selected >= job.company.maxContacts)
+                    continue;
+                if (performed >= input.maxSearches)
+                    break;
+                performed++;
+                if (input.searchPage) {
+                    const result = previous ? { ...previous, people: [...previous.people] } : { people: [], totalResults: null, fetchedPages: 0, nextOffset: 0 };
+                    // Old checkpoints lack a reliable raw offset; replay the first page once and deduplicate.
+                    let start = result.nextOffset ?? 0;
+                    const seen = new Set(result.people.map(p => canonicalProfile(p.profileUrl)));
+                    const target = input.continuePartial ? 2500 : brief.candidatesPerDepartment;
+                    while (start < target) {
+                        const replayingLegacyFirstPage = previous != null && previous.nextOffset == null && start === 0;
+                        const count = Math.min(100, target - start);
+                        const page = await input.searchPage(job, start, count);
+                        result.fetchedPages++;
+                        if (result.totalResults != null && page.totalResults !== result.totalResults)
+                            result.stoppedReason = "reported_total_changed";
+                        result.totalResults ??= page.totalResults;
+                        let added = 0;
+                        for (const person of page.people) {
+                            const key = canonicalProfile(person.profileUrl);
+                            if (key && !seen.has(key)) {
+                                seen.add(key);
+                                result.people.push(person);
+                                added++;
+                            }
+                        }
+                        start += page.rawCount;
+                        result.nextOffset = start;
+                        if ((page.rawCount === 0 || !added && !replayingLegacyFirstPage) && (result.totalResults == null || result.people.length < result.totalResults))
+                            result.stoppedReason = "empty_or_duplicate_page";
+                        state.results[job.key] = result;
+                        await save(checkpoint, JSON.stringify(state));
+                        await publish();
+                        if (result.stoppedReason || result.totalResults != null && start >= result.totalResults)
+                            break;
+                        if (input.continuePartial === "quota" && shortlistCompanyLeads(effectiveBrief(), state.results).coverage.find(c => c.companyId === job.company.companyId).selected >= job.company.maxContacts)
+                            break;
+                    }
+                }
+                else
+                    state.results[job.key] = await input.search(job);
+                await save(checkpoint, JSON.stringify(state));
+                await publish();
+            }
+        };
+        await collect();
+        if (input.resolveCompany || input.diagnoseCompany) {
+            let resolutionsPerformed = 0;
+            for (const [index, company] of brief.companies.entries()) {
+                if (performed >= input.maxSearches || resolutionsPerformed >= input.maxSearches)
+                    break;
+                const savedResolution = state.resolutions?.[String(index)];
+                if (!allowed(company.name) || company.companyId || (Object.hasOwn(state.resolutions ?? {}, String(index)) && !(input.retryUnresolved && savedResolution === null)))
+                    continue;
+                const diagnosed = input.diagnoseCompany ? await input.diagnoseCompany(company) : undefined;
+                const resolution = diagnosed ? diagnosed.resolution : await input.resolveCompany(company);
+                if (diagnosed) {
+                    state.diagnostics ??= {};
+                    state.diagnostics[String(index)] = diagnosed.diagnostic;
+                }
+                resolutionsPerformed++;
+                if (resolution && (!/^[1-9]\d*$/.test(resolution.companyId) || words(resolution.companyName) !== words(company.name)))
+                    throw new Error("Company resolver returned a non-exact identity.");
+                const occupied = new Set(effectiveBrief().companies.map(c => c.companyId).filter(Boolean));
+                state.resolutions ??= {};
+                state.resolutions[String(index)] = resolution && !occupied.has(resolution.companyId) ? resolution : null;
+                if (resolution && occupied.has(resolution.companyId) && state.diagnostics?.[String(index)])
+                    state.diagnostics[String(index)].reason = "shared_identity";
+                await save(checkpoint, JSON.stringify(state));
+                await publish();
+                await collect();
+            }
+        }
+        if (input.reviewIdentity)
+            for (const [index, company] of brief.companies.entries()) {
+                if (!allowed(company.name) || company.companyId || state.resolutions?.[String(index)])
+                    continue;
+                const diagnostic = state.diagnostics?.[String(index)];
+                if (!diagnostic)
+                    continue;
+                const choice = await input.reviewIdentity(company, diagnostic);
+                if (!choice)
+                    continue;
+                if (!diagnostic.candidates.some(c => c.companyId === choice.companyId && companyIdentityKey(c.name) === companyIdentityKey(choice.name)))
+                    throw new Error("Reviewed identity must match a verified candidate from this research.");
+                if (effectiveBrief().companies.some(c => c.companyId === choice.companyId))
+                    throw new Error("Reviewed identity is already assigned to another target.");
+                const identity = { targetName: company.name, companyId: choice.companyId, canonicalName: choice.name, evidenceUrl: choice.evidenceUrl };
+                review = CompanyReviewSchema.parse({ fingerprint, employerAliases: review?.employerAliases ?? [], identities: [...(review?.identities ?? []), identity] });
+                // The durable review overlay is written first. A crash before the checkpoint
+                // write is recovered by the normal review-file replay on the next invocation.
+                await save(path.join(outDir, "review-decisions.json"), JSON.stringify(review, null, 2));
+                state.resolutions ??= {};
+                state.resolutions[String(index)] = { companyId: choice.companyId, companyName: company.name, canonicalName: choice.name, evidenceUrl: choice.evidenceUrl };
+                await save(checkpoint, JSON.stringify(state));
+                await publish();
+                await collect();
+            }
+    }
+    catch (e) {
+        await publish();
+        throw e;
+    }
+    const report = await publish();
+    return { status: "ok", ...report, completedSearches: Object.keys(state.results).length, totalSearches: planCompanySearches(effectiveBrief()).length, output: outDir, resumable: true };
+}

package/dist/company-recovery.js

@@ -0,0 +1,84 @@
+import { z } from "zod";
+// Only presentation annotations and legal suffixes are interchangeable. Group,
+// division, brand and subsidiary names remain different identities.
+export function companyIdentityKey(name) {
+    let key = name.replace(/\s*\((?:CH|DE|AT|UK|US|USA)\)\s*$/i, "")
+        .normalize("NFKD").replace(/[\u0300-\u036f]/g, "").replace(/ß/g, "ss").toLowerCase()
+        .replace(/&/g, " and ").replace(/[^a-z0-9]+/g, " ")
+        .replace(/\s+/g, " ").trim();
+    // Do not erase a brand token in names such as AG Insurance or SE Ranking.
+    while (/\s(?:gmbh|kgaa|ag|se|ltd|limited|inc|incorporated|llc)$/.test(key))
+        key = key.replace(/\s\S+$/, "");
+    return key;
+}
+export function companyQueryVariants(name) {
+    const plain = name.replace(/\s*\([^)]*\)\s*/g, " ").trim();
+    const primary = plain.split(/\s+\/\s+/)[0].trim();
+    return [...new Set([name, plain, primary, companyIdentityKey(primary)].filter(Boolean))].slice(0, 3);
+}
+export async function resolveCompanyIdentity(name, search, details) {
+    const diagnostic = { reason: "no_exact_match", attempts: [], candidates: [], observedAt: new Date().toISOString() };
+    const candidates = new Map();
+    const proven = new Map();
+    let incomplete = false, oversized = false;
+    for (const query of companyQueryVariants(name)) {
+        const first = await search(query, 0);
+        let count = first.rawCount;
+        const total = first.total;
+        const queryCandidates = new Map(first.candidates.map(c => [c.companyId, c]));
+        let complete = total != null && total <= 1000;
+        for (const c of first.candidates)
+            candidates.set(c.companyId, c);
+        if (complete)
+            for (let start = 25; start < total; start += 25) {
+                const page = await search(query, start);
+                if (page.total !== total || page.rawCount === 0) {
+                    complete = false;
+                    break;
+                }
+                count += page.rawCount;
+                for (const c of page.candidates) {
+                    candidates.set(c.companyId, c);
+                    queryCandidates.set(c.companyId, c);
+                }
+            }
+        complete = complete && count >= total && queryCandidates.size >= total;
+        diagnostic.attempts.push({ query, total, collected: count, complete });
+        incomplete ||= !complete;
+        oversized ||= total != null && total > 1000;
+        // A complete exact query is sufficient; avoid repeating equivalent searches.
+        if (complete)
+            for (const c of queryCandidates.values())
+                proven.set(c.companyId, c);
+        if (complete && [...queryCandidates.values()].some(c => companyIdentityKey(c.name) === companyIdentityKey(name))) {
+            incomplete = false;
+            oversized = false;
+            break;
+        }
+    }
+    diagnostic.candidates = [...candidates.values()].slice(0, 100);
+    const exact = [...proven.values()].filter(c => companyIdentityKey(c.name) === companyIdentityKey(name));
+    if (/\/|\([^)]*(?:\/|,)[^)]*\)/.test(name))
+        diagnostic.reason = "entity_decision_required";
+    else if (oversized)
+        diagnostic.reason = "oversized";
+    else if (incomplete)
+        diagnostic.reason = "incomplete";
+    else if (exact.length > 1)
+        diagnostic.reason = "ambiguous";
+    else if (exact.length === 1) {
+        const evidence = await details(exact[0].companyId);
+        if (evidence?.companyId === exact[0].companyId && companyIdentityKey(evidence.name) === companyIdentityKey(name)) {
+            diagnostic.reason = "resolved";
+            return { resolution: { companyId: evidence.companyId, companyName: name, canonicalName: evidence.name, evidenceUrl: evidence.evidenceUrl }, diagnostic };
+        }
+        diagnostic.reason = "detail_mismatch";
+    }
+    return { resolution: null, diagnostic };
+}
+const evidenceUrl = z.url().refine(value => /^https:\/\//i.test(value), "Evidence must use HTTPS");
+export const CompanyReviewSchema = z.object({
+    fingerprint: z.string().regex(/^[a-f0-9]{64}$/),
+    employerAliases: z.array(z.object({ companyId: z.string().regex(/^[1-9]\d*$/), name: z.string().trim().min(1), evidenceUrl }).strict()).default([]),
+    identities: z.array(z.object({ targetName: z.string().trim().min(1), companyId: z.string().regex(/^[1-9]\d*$/), canonicalName: z.string().trim().min(1), evidenceUrl }).strict()).default([]),
+}).strict();