@slicedearth/whoisleuth-cli 1.34.0 → 1.39.1

package/frontend/src/lib/analysis/lookup-decision-support.js

@@ -0,0 +1,480 @@
+const CONTROL_CHARACTERS = /[\u0000-\u001f\u007f]/gu;
+const MAX_TEXT = 320;
+const MAX_ENTRIES = 24;
+const MAX_ACTIONS = 6;
+const TASK_GUIDANCE = Object.freeze({
+    general: Object.freeze({
+        label: 'General investigation',
+        summary: 'Establish what was observed, which sources agree, and what remains unknown before drawing a conclusion.',
+        questions: Object.freeze([
+            'Which source observations are complete enough to rely on?',
+            'Do registration, infrastructure, certificate, and page identity evidence agree?',
+            'What manual pivot would reduce the most important uncertainty?',
+        ]),
+        prioritySections: Object.freeze(['overview', 'web-evidence', 'registry', 'case-response']),
+    }),
+    acquisition: Object.freeze({
+        label: 'Acquisition review',
+        summary: 'Prioritise registration lifecycle, authority, transfer dependencies, mail, DNS, and services that would need a controlled transition.',
+        questions: Object.freeze([
+            'Is the registration conclusion authoritative and internally consistent?',
+            'Which DNS, mail, certificate, and website dependencies require transition planning?',
+            'Which lifecycle dates are observations rather than guaranteed transfer or deletion dates?',
+        ]),
+        prioritySections: Object.freeze(['overview', 'registry', 'web-evidence', 'case-response']),
+    }),
+    brand: Object.freeze({
+        label: 'Brand review',
+        summary: 'Prioritise declared identity, page similarity, credential surfaces, external destinations, and infrastructure relationships.',
+        questions: Object.freeze([
+            'Does the page claim or resemble a reviewed identity?',
+            'Where do redirects, forms, resources, and trackers cross trust boundaries?',
+            'Which similarities are verified facts and which are only review leads?',
+        ]),
+        prioritySections: Object.freeze(['overview', 'web-evidence', 'external-intelligence', 'case-response']),
+    }),
+    incident: Object.freeze({
+        label: 'Incident response',
+        summary: 'Prioritise current reachability, redirects, certificate state, credential surfaces, warning data, and evidence that can support a reviewed response.',
+        questions: Object.freeze([
+            'What behaviour was observed at the recorded time?',
+            'Which source limitations could change the response decision?',
+            'What evidence and recipient route are ready for a reviewed handoff?',
+        ]),
+        prioritySections: Object.freeze(['overview', 'external-intelligence', 'web-evidence', 'case-response']),
+    }),
+    owned: Object.freeze({
+        label: 'Owned-domain posture',
+        summary: 'Prioritise delegation, mail, certificate, security-policy, lifecycle, and change evidence for a domain under review.',
+        questions: Object.freeze([
+            'Do registry publication and directly observed delegation agree?',
+            'Are mail, certificate, and website controls in the expected state?',
+            'Which incomplete or stale source should be reviewed before recording posture?',
+        ]),
+        prioritySections: Object.freeze(['overview', 'registry', 'web-evidence', 'case-response']),
+    }),
+});
+const TIMING_TO_EVIDENCE = Object.freeze({
+    rdap: Object.freeze(['rdap']),
+    whois: Object.freeze(['whois']),
+    domain_evidence: Object.freeze([
+        'availability',
+        'client-behavior',
+        'dns',
+        'http',
+        'page-identity',
+        'page-role',
+        'security-posture',
+        'sslbl',
+        'technology',
+        'tls',
+    ]),
+    reverse_dns: Object.freeze(['reverse-dns']),
+    registrar_rdap: Object.freeze(['registrar-rdap']),
+    network_context: Object.freeze(['network-context']),
+    security_txt: Object.freeze(['security-txt']),
+    external_intelligence: Object.freeze(['external-intelligence']),
+    malware_host_intelligence: Object.freeze(['malware-host-intelligence']),
+    malware_ioc_intelligence: Object.freeze(['malware-ioc-intelligence']),
+});
+const SUPPORTS = Object.freeze({
+    rdap: Object.freeze(['Registration summary', 'Lifecycle', 'Availability']),
+    whois: Object.freeze(['Registration comparison', 'Contacts', 'Lifecycle']),
+    'registrar-rdap': Object.freeze(['Registration publication comparison']),
+    availability: Object.freeze(['Availability decision', 'Lookup assessment']),
+    dns: Object.freeze(['Delegation', 'Mail posture', 'Service dependencies']),
+    'reverse-dns': Object.freeze(['Observed endpoint context']),
+    'network-context': Object.freeze(['Delivery and routing context']),
+    http: Object.freeze(['Redirects', 'Page collection', 'Website state']),
+    tls: Object.freeze(['Hostname authorisation', 'Certificate scope']),
+    'page-identity': Object.freeze(['Declared page identity', 'Form and resource review']),
+    technology: Object.freeze(['Technology profile']),
+    'security-posture': Object.freeze(['Passive security posture']),
+    'security-txt': Object.freeze(['Security contact route']),
+    sslbl: Object.freeze(['Certificate warning-data comparison']),
+    'external-intelligence': Object.freeze(['Optional external context']),
+});
+const ENDPOINT_CLASS = Object.freeze({
+    rdap: 'Authoritative registry endpoint',
+    whois: 'WHOIS transport',
+    'registrar-rdap': 'Registrar publication endpoint',
+    availability: 'Authority-aware analysis',
+    dns: 'DNS resolver and authorities',
+    'reverse-dns': 'Reverse DNS resolver',
+    'network-context': 'IP RDAP and routing',
+    http: 'Bounded HTTP collection',
+    tls: 'TLS endpoint',
+    'page-identity': 'Static page analysis',
+    technology: 'Derived analysis',
+    'security-posture': 'Derived analysis',
+    'security-txt': 'Selected well-known resource',
+    sslbl: 'Local warning-data snapshot',
+    'external-intelligence': 'Optional external provider',
+});
+const SOURCE_DESCRIPTION = Object.freeze({
+    rdap: 'Structured registration data selected through the registry bootstrap.',
+    whois: 'Referral-aware text registration data collected through the WHOIS service path.',
+    'registrar-rdap': 'A separately attributed registrar publication discovered from registry RDAP.',
+    availability: 'An authority-aware conclusion derived from the enabled registration sources.',
+    dns: 'Point-in-time delegation, address, mail, and service records from bounded DNS collection.',
+    'reverse-dns': 'Operator-published PTR context for an observed public address.',
+    'network-context': 'Point-in-time IP registration and routing context for an observed endpoint.',
+    http: 'A bounded homepage request covering redirects, response metadata, and a capped body prefix.',
+    tls: 'A point-in-time TLS handshake to one validated public address for the requested hostname.',
+    'page-identity': 'Static identity, form, resource, and page-component signals from retained HTML.',
+    technology: 'Curated technology signatures evaluated against already observed page evidence.',
+    'security-posture': 'Passive security controls derived from collected DNS, HTTP, TLS, and page evidence.',
+    'security-txt': 'A bounded request for the selected well-known security contact resource.',
+    sslbl: 'A local comparison against a versioned certificate warning-data snapshot.',
+    'external-intelligence': 'Optional provider context retained with its own source state and limitations.',
+});
+function record(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : {};
+}
+function text(value, maximum = MAX_TEXT) {
+    return String(value ?? '')
+        .replace(CONTROL_CHARACTERS, ' ')
+        .replace(/\s+/gu, ' ')
+        .trim()
+        .slice(0, maximum);
+}
+function idPart(value) {
+    return text(value, 80).toLowerCase().replace(/[^a-z0-9]+/gu, '-').replace(/^-|-$/gu, '');
+}
+function display(value) {
+    const normalized = text(value, 180);
+    return normalized || 'not published';
+}
+function isoDate(value) {
+    if (typeof value !== 'string')
+        return null;
+    const timestamp = Date.parse(value);
+    return Number.isFinite(timestamp) ? new Date(timestamp).toISOString() : null;
+}
+function ageDays(value, now) {
+    const current = isoDate(now);
+    if (!value || !current)
+        return null;
+    return Math.max(0, Math.floor((Date.parse(current) - Date.parse(value)) / 86_400_000));
+}
+function taskGuidance(task) {
+    return { task, ...TASK_GUIDANCE[task] };
+}
+function comparisonEntries(comparison, kind) {
+    const output = [];
+    const source = record(comparison);
+    const sourceHealth = record(source.sourceHealth);
+    const fields = Array.isArray(source.fields) ? source.fields.slice(0, 24) : [];
+    for (const item of fields) {
+        const field = record(item);
+        const status = text(field.status, 64);
+        const label = text(field.label, 120) || 'Registration field';
+        const suffix = idPart(label);
+        if (status === 'conflict') {
+            const left = kind === 'registry-whois' ? field.rdapDisplay : field.registryDisplay;
+            const right = kind === 'registry-whois' ? field.whoisDisplay : field.registrarDisplay;
+            output.push({
+                id: `${kind}-${suffix || output.length}`,
+                state: 'conflict',
+                importance: ['Domain', 'Registrar', 'Name servers', 'Statuses'].includes(label) ? 'high' : 'medium',
+                title: `${label} differs between registration sources`,
+                detail: `${display(left)} compared with ${display(right)}.`,
+                sources: kind === 'registry-whois'
+                    ? ['Registry RDAP', 'WHOIS']
+                    : ['Registry RDAP', 'Registrar RDAP'],
+                href: '#registry',
+            });
+            continue;
+        }
+        const unavailableSource = status.startsWith('rdap_')
+            ? 'rdap'
+            : status.startsWith('whois_')
+                ? 'whois'
+                : status.startsWith('registry_')
+                    ? 'registry'
+                    : status.startsWith('registrar_')
+                        ? 'registrar'
+                        : null;
+        const unavailableSourceStatus = unavailableSource
+            ? text(record(sourceHealth[unavailableSource]).status, 64)
+            : null;
+        if ((status.includes('unavailable') || status.includes('incomplete'))
+            && unavailableSourceStatus !== 'unsupported') {
+            output.push({
+                id: `${kind}-${suffix || output.length}-${status}`,
+                state: 'uncertain',
+                importance: 'low',
+                title: `${label} comparison is incomplete`,
+                detail: 'At least one registration source did not provide complete evidence, so no disagreement or equivalence conclusion is available.',
+                sources: kind === 'registry-whois'
+                    ? ['Registry RDAP', 'WHOIS']
+                    : ['Registry RDAP', 'Registrar RDAP'],
+                href: '#registry',
+            });
+        }
+    }
+    return output;
+}
+function hostname(value) {
+    const candidate = typeof value === 'string' ? value : text(record(value).url, 2_048);
+    if (!candidate)
+        return null;
+    try {
+        const url = new URL(/^[a-z][a-z\d+.-]*:\/\//iu.test(candidate) ? candidate : `https://${candidate}`);
+        return url.hostname.toLowerCase().replace(/\.$/u, '');
+    }
+    catch {
+        return null;
+    }
+}
+function sameRegistrableScope(left, right, registrableDomain) {
+    if (left === right)
+        return true;
+    if (!registrableDomain)
+        return false;
+    const belongsToDomain = (value) => (value === registrableDomain || value.endsWith(`.${registrableDomain}`));
+    return belongsToDomain(left) && belongsToDomain(right);
+}
+function identityEntries(input) {
+    const output = [];
+    const requestedHost = hostname(input.requestedHost);
+    const registrableDomain = hostname(input.registrableDomain);
+    const finalHost = hostname(input.finalUrl);
+    const canonicalHost = hostname(input.canonicalUrl);
+    const openGraphHost = hostname(input.openGraphUrl);
+    const tlsAuthorization = record(input.tlsAuthorization);
+    if (tlsAuthorization.authorized === false) {
+        output.push({
+            id: 'tls-hostname-authorization',
+            state: 'conflict',
+            importance: 'high',
+            title: 'The observed certificate did not authorise the requested hostname',
+            detail: text(tlsAuthorization.error, 240) || 'TLS hostname authorisation failed for the requested host.',
+            sources: ['TLS'],
+            href: '#evidence-tls',
+        });
+    }
+    if (requestedHost && finalHost && !sameRegistrableScope(requestedHost, finalHost, registrableDomain)) {
+        output.push({
+            id: 'http-cross-site-final-origin',
+            state: 'conflict',
+            importance: 'medium',
+            title: 'The final website origin is outside the requested domain',
+            detail: `${requestedHost} redirected to ${finalHost}. Review the redirect chain before interpreting identity or control.`,
+            sources: ['HTTP'],
+            href: '#evidence-http',
+        });
+    }
+    if (finalHost && canonicalHost && !sameRegistrableScope(finalHost, canonicalHost, registrableDomain)) {
+        output.push({
+            id: 'page-canonical-origin',
+            state: 'conflict',
+            importance: 'medium',
+            title: 'The declared canonical origin differs from the observed final origin',
+            detail: `${finalHost} served the page while the document declared ${canonicalHost} as canonical.`,
+            sources: ['HTTP', 'HTML'],
+            href: '#evidence-page-identity',
+        });
+    }
+    if (finalHost && openGraphHost && !sameRegistrableScope(finalHost, openGraphHost, registrableDomain)) {
+        output.push({
+            id: 'page-open-graph-origin',
+            state: 'conflict',
+            importance: 'low',
+            title: 'The Open Graph URL points outside the observed final origin',
+            detail: `${finalHost} served the page while Open Graph metadata declared ${openGraphHost}. Publisher metadata is a claim, not identity proof.`,
+            sources: ['HTTP', 'HTML'],
+            href: '#evidence-page-identity',
+        });
+    }
+    return output;
+}
+function certificatePolicyEntries(value) {
+    const review = record(value);
+    const findings = Array.isArray(review.findings) ? review.findings.slice(0, 8) : [];
+    const output = [];
+    for (const item of findings) {
+        const finding = record(item);
+        const id = text(finding.id, 80);
+        const state = text(finding.state, 80);
+        const label = text(finding.label, 120) || 'Certificate policy';
+        if (state === 'apparently_outside_current_policy' || state === 'changed') {
+            output.push({
+                id: `certificate-policy-${id || state}`,
+                state: 'conflict',
+                importance: id === 'expected_spki' ? 'high' : 'medium',
+                title: label,
+                detail: text(finding.detail, 300) || 'Observed certificate context differs from the current reviewed policy context.',
+                sources: Array.isArray(finding.sources) ? finding.sources.map((source) => text(source, 80)).filter(Boolean) : ['DNS', 'TLS'],
+                href: '#evidence-certificate-policy',
+            });
+            continue;
+        }
+        if (state === 'indeterminate' || state === 'no_target_policy_observed') {
+            output.push({
+                id: `certificate-policy-${id || state}`,
+                state: 'uncertain',
+                importance: 'low',
+                title: `${label} is indeterminate`,
+                detail: text(finding.detail, 300) || 'Current evidence does not support a policy comparison.',
+                sources: Array.isArray(finding.sources) ? finding.sources.map((source) => text(source, 80)).filter(Boolean) : ['DNS', 'TLS'],
+                href: '#evidence-certificate-policy',
+            });
+        }
+    }
+    return output;
+}
+function prioritizeEntries(entries, task) {
+    const taskBoost = {
+        general: [],
+        acquisition: ['registry'],
+        brand: ['page', 'http', 'tls'],
+        incident: ['http', 'tls', 'page'],
+        owned: ['registry', 'tls'],
+    };
+    const importance = { high: 0, medium: 1, low: 2 };
+    return [...entries].sort((left, right) => {
+        const leftBoost = taskBoost[task].some((prefix) => left.id.startsWith(prefix)) ? -1 : 0;
+        const rightBoost = taskBoost[task].some((prefix) => right.id.startsWith(prefix)) ? -1 : 0;
+        return leftBoost - rightBoost
+            || importance[left.importance] - importance[right.importance]
+            || left.title.localeCompare(right.title);
+    }).slice(0, 16);
+}
+export function buildLookupDecisionSupport(input) {
+    const entries = prioritizeEntries([
+        ...comparisonEntries(input.registryComparison, 'registry-whois'),
+        ...comparisonEntries(input.registrarPublicationComparison, 'registry-registrar'),
+        ...identityEntries(input),
+        ...certificatePolicyEntries(input.certificatePolicyReview),
+    ], input.task);
+    const actions = [];
+    const firstConflict = entries.find((entry) => entry.state === 'conflict');
+    if (firstConflict) {
+        actions.push({
+            id: 'review-priority-conflict',
+            label: 'Review the highest-priority disagreement',
+            reason: firstConflict.title,
+            href: firstConflict.href,
+            priority: 'high',
+        });
+    }
+    if (input.refreshPlan.items.length) {
+        actions.push({
+            id: 'review-refresh-options',
+            label: 'Review limited or stale sources',
+            reason: `${input.refreshPlan.items.length} deliberate source refresh option${input.refreshPlan.items.length === 1 ? ' is' : 's are'} available.`,
+            href: '#evidence-quality',
+            priority: 'medium',
+        });
+    }
+    const firstLimited = input.coverage.entries.find((entry) => entry.manualReviewSuggested);
+    if (firstLimited && !input.refreshPlan.items.some((item) => item.evidenceIds.includes(firstLimited.id))) {
+        actions.push({
+            id: 'inspect-limited-source',
+            label: `Inspect ${firstLimited.label}`,
+            reason: `${firstLimited.statusLabel} evidence may limit downstream conclusions.`,
+            href: '#evidence-quality',
+            priority: 'medium',
+        });
+    }
+    if (input.task === 'brand') {
+        actions.push({
+            id: 'review-page-identity',
+            label: 'Review identity and credential evidence',
+            reason: 'Compare declared identity, forms, redirects, and external destinations before making a brand assessment.',
+            href: '#web-evidence',
+            priority: 'medium',
+        });
+    }
+    else if (input.task === 'acquisition') {
+        actions.push({
+            id: 'review-acquisition-dependencies',
+            label: 'Review transfer dependencies',
+            reason: 'Registration dates alone do not describe the DNS, mail, certificate, and website services that require transition.',
+            href: '#web-evidence',
+            priority: 'medium',
+        });
+    }
+    else if (input.task === 'owned') {
+        actions.push({
+            id: 'review-owned-posture',
+            label: 'Review delegation and posture evidence',
+            reason: 'Confirm registry publication, authoritative responses, mail, and certificate state together.',
+            href: '#web-evidence',
+            priority: 'medium',
+        });
+    }
+    if (input.hasCaseSection) {
+        actions.push({
+            id: 'review-case-handoff',
+            label: 'Record or hand off reviewed evidence',
+            reason: 'Keep observed facts, hypotheses, unknowns, and analyst decisions separate in the case workflow.',
+            href: '#case-response',
+            priority: 'low',
+        });
+    }
+    const uniqueActions = [...new Map(actions.map((action) => [action.id, action])).values()].slice(0, MAX_ACTIONS);
+    return {
+        version: 1,
+        guidance: taskGuidance(input.task),
+        entries,
+        actions: uniqueActions,
+        counts: {
+            conflicts: entries.filter((entry) => entry.state === 'conflict').length,
+            uncertainties: entries.filter((entry) => entry.state === 'uncertain').length,
+        },
+    };
+}
+function timingByEvidence(timing) {
+    const output = new Map();
+    if (!timing)
+        return output;
+    for (const source of timing.sources) {
+        for (const evidenceId of TIMING_TO_EVIDENCE[source.source]) {
+            output.set(evidenceId, source);
+        }
+    }
+    return output;
+}
+export function buildLookupEvidenceQualityMatrix(input) {
+    const observedAt = isoDate(input.observedAt);
+    const currentAgeDays = ageDays(observedAt, input.now ?? new Date().toISOString());
+    const timings = timingByEvidence(input.timing);
+    const refreshIds = new Set(input.refreshPlan.items.flatMap((item) => item.evidenceIds));
+    const entries = input.coverage.entries.slice(0, MAX_ENTRIES).map((entry) => {
+        const timing = timings.get(entry.id);
+        const entryObservedAt = isoDate(input.observedAtByEvidence?.[entry.id]) ?? observedAt;
+        return {
+            id: entry.id,
+            label: entry.label,
+            category: entry.category,
+            endpointClass: ENDPOINT_CLASS[entry.id] ?? 'Source-specific collection',
+            description: SOURCE_DESCRIPTION[entry.id]
+                ?? 'Source-specific evidence retained with its original state and limitations.',
+            state: entry.state,
+            statusLabel: entry.statusLabel,
+            truncated: entry.truncated,
+            observedAt: entryObservedAt,
+            ageDays: ageDays(entryObservedAt, input.now ?? new Date().toISOString()),
+            durationMs: timing?.durationMs ?? null,
+            timingOutcome: timing?.outcome ?? null,
+            refreshAvailable: refreshIds.has(entry.id),
+            limitations: entry.limitations,
+            supports: SUPPORTS[entry.id] ?? Object.freeze([]),
+        };
+    });
+    return {
+        version: 1,
+        observedAt,
+        totalMs: input.timing?.totalMs ?? null,
+        entries,
+        completeCount: input.coverage.completeCount,
+        limitedCount: input.coverage.limitedCount,
+        stale: input.refreshPlan.stale,
+        ageDays: currentAgeDays,
+        freshnessPolicy: input.refreshPlan.freshnessPolicy,
+    };
+}

package/frontend/src/lib/analysis/lookup-investigation-brief.js

@@ -0,0 +1,153 @@
+export const LOOKUP_INVESTIGATION_BRIEF_SCHEMA = 'whoisleuth.investigation-brief';
+export const LOOKUP_INVESTIGATION_BRIEF_VERSION = 1;
+const CONTROL_CHARACTERS = /[\u0000-\u001f\u007f]/gu;
+const MAX_FACTS = 12;
+const MAX_LIMITATIONS = 20;
+function text(value, maximum = 320) {
+    return String(value ?? '')
+        .replace(CONTROL_CHARACTERS, ' ')
+        .replace(/\s+/gu, ' ')
+        .trim()
+        .slice(0, maximum);
+}
+function timestamp(value) {
+    if (typeof value !== 'string')
+        return null;
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) ? new Date(parsed).toISOString() : null;
+}
+function uniqueText(values, maximum = MAX_LIMITATIONS) {
+    const output = [];
+    const seen = new Set();
+    for (const value of values) {
+        const normalized = text(value);
+        if (!normalized || seen.has(normalized))
+            continue;
+        output.push(normalized);
+        seen.add(normalized);
+        if (output.length >= maximum)
+            break;
+    }
+    return output;
+}
+function taskQuestion(support) {
+    return support.guidance.questions[0]
+        ?? 'What does the collected evidence establish, and what remains uncertain?';
+}
+export function buildLookupInvestigationBrief(input) {
+    const generatedAt = timestamp(input.generatedAt) ?? new Date().toISOString();
+    const verifiedFacts = input.summary.facts
+        .filter((fact) => fact.value !== '—')
+        .slice(0, MAX_FACTS);
+    const contradictions = input.decisionSupport.entries
+        .filter((entry) => entry.state === 'conflict');
+    const unknowns = input.decisionSupport.entries
+        .filter((entry) => entry.state === 'uncertain');
+    const limitedSources = input.quality.entries
+        .filter((entry) => entry.state !== 'complete')
+        .map((entry) => `${entry.label}: ${entry.statusLabel}`);
+    const graphKinds = uniqueText(input.graph.edges.map((edge) => edge.label), 12);
+    return {
+        schema: LOOKUP_INVESTIGATION_BRIEF_SCHEMA,
+        schemaVersion: LOOKUP_INVESTIGATION_BRIEF_VERSION,
+        generatedAt,
+        target: text(input.target, 253) || 'Unknown target',
+        targetType: text(input.targetType, 40) || 'unknown',
+        task: input.task,
+        taskLabel: input.decisionSupport.guidance.label,
+        question: taskQuestion(input.decisionSupport),
+        summary: input.decisionSupport.guidance.summary,
+        observation: {
+            observedAt: input.quality.observedAt,
+            evidenceAgeDays: input.quality.ageDays,
+            completeSources: input.quality.completeCount,
+            limitedSources: input.quality.limitedCount,
+            freshnessPolicy: input.quality.freshnessPolicy,
+        },
+        verifiedFacts,
+        contradictions,
+        unknowns,
+        nextActions: input.decisionSupport.actions,
+        relationships: {
+            nodes: input.graph.nodes.length,
+            edges: input.graph.edges.length,
+            truncated: input.graph.truncated,
+            kinds: graphKinds,
+        },
+        limitations: uniqueText([
+            ...limitedSources,
+            ...input.graph.limitations,
+            'This brief is a deterministic organisation of collected and derived evidence, not an attribution, ownership, safety, availability, or maliciousness conclusion.',
+            'Analyst assertions, hypotheses, and decisions must remain separate from observed evidence.',
+        ]),
+    };
+}
+function markdown(value) {
+    return text(value, 2_000)
+        .replace(/&/gu, '&')
+        .replace(/</gu, '&lt;')
+        .replace(/>/gu, '&gt;')
+        .replace(/([\\`*_{}[\]()#+\-.!|=~])/gu, '\\$1');
+}
+function factLine(fact) {
+    const sources = fact.provenance.sources.length
+        ? ` Sources: ${fact.provenance.sources.map(markdown).join(', ')}.`
+        : '';
+    return `- **${markdown(fact.label)}:** ${markdown(fact.value)}.${sources}`;
+}
+function decisionLine(entry) {
+    return `- **${markdown(entry.title)}:** ${markdown(entry.detail)} Sources: ${entry.sources.map(markdown).join(', ') || 'not reported'}.`;
+}
+export function formatLookupInvestigationBriefMarkdown(brief) {
+    const lines = [
+        `# Investigation brief: ${markdown(brief.target)}`,
+        '',
+        `Generated ${markdown(brief.generatedAt)} from a ${markdown(brief.targetType)} Lookup.`,
+        '',
+        '## Decision context',
+        '',
+        `- **Task:** ${markdown(brief.taskLabel)}`,
+        `- **Question:** ${markdown(brief.question)}`,
+        `- **Summary:** ${markdown(brief.summary)}`,
+        `- **Evidence observed:** ${markdown(brief.observation.observedAt ?? 'not reported')}`,
+        `- **Source quality:** ${brief.observation.completeSources} complete; ${brief.observation.limitedSources} limited`,
+        `- **Freshness policy:** v${brief.observation.freshnessPolicy.version} ${markdown(brief.observation.freshnessPolicy.id)} for ${markdown(brief.observation.freshnessPolicy.task)}; registration ${brief.observation.freshnessPolicy.thresholdsDays.registration}d, network ${brief.observation.freshnessPolicy.thresholdsDays.network}d, web ${brief.observation.freshnessPolicy.thresholdsDays.web}d`,
+        '',
+        '## Verified normalised facts',
+        '',
+        ...(brief.verifiedFacts.length ? brief.verifiedFacts.map(factLine) : ['- No normalised fact was available for this brief.']),
+        '',
+        '## Contradictory evidence',
+        '',
+        ...(brief.contradictions.length ? brief.contradictions.map(decisionLine) : ['- No explicit contradiction was derived from the supported comparisons.']),
+        '',
+        '## Unknowns and incomplete comparisons',
+        '',
+        ...(brief.unknowns.length ? brief.unknowns.map(decisionLine) : ['- No explicit uncertainty entry was derived. Review source quality before treating this as complete.']),
+        '',
+        '## Recommended next manual steps',
+        '',
+        ...(brief.nextActions.length
+            ? brief.nextActions.map((action) => `- **${markdown(action.label)}:** ${markdown(action.reason)}`)
+            : ['- Review the underlying source evidence and its limitations.']),
+        '',
+        '## Observed relationship map',
+        '',
+        `- ${brief.relationships.nodes} nodes and ${brief.relationships.edges} edges${brief.relationships.truncated ? '; bounded output was truncated' : ''}.`,
+        `- Relationship types: ${brief.relationships.kinds.map(markdown).join(', ') || 'none observed'}.`,
+        '',
+        '## Limitations',
+        '',
+        ...brief.limitations.map((limitation) => `- ${markdown(limitation)}`),
+        '',
+    ];
+    return lines.join('\n');
+}
+export function lookupInvestigationBriefFilename(brief) {
+    const target = brief.target
+        .toLowerCase()
+        .replace(/[^a-z0-9.-]+/gu, '-')
+        .replace(/^-+|-+$/gu, '')
+        .slice(0, 80) || 'lookup';
+    return `whoisleuth-investigation-brief-${target}-${brief.generatedAt.slice(0, 10)}.md`;
+}