@slicedearth/whoisleuth-cli 2.4.0 → 2.5.1

package/cli/case-command.mjs

@@ -1,5 +1,5 @@
 import { createHash } from 'node:crypto';
-import { boundedJsonLimitsForBytes, parseBoundedJsonObject } from "../lib/bounded-json.mjs";
+import { boundedJsonLimitsForBytes, parseBoundedJsonObject } from "../packages/analysis/bounded-json.mjs";
 import { canonicalArtifactJsonV2 } from "../packages/evidence/artifact-integrity.mjs";
 import { normalizeExplicitIsoTimestamp } from "../packages/evidence/observation.mjs";
 import { MAX_CASE_CHECKPOINT_FACTS, MAX_CASE_OBJECTIVE_LENGTH, MAX_CASE_STORE_BYTES, MAX_EDITABLE_CASE_INPUT_BYTES, MAX_NOTE_LENGTH, MAX_RESPONSE_RATIONALE_LENGTH, MAX_RESPONSE_VALUE_LENGTH } from "../packages/contracts/case-portability.mjs";
@@ -8,6 +8,7 @@ import { createCaseIncident, openOrCreateCase, recordCaseConclusion, recordCaseR
 import { buildCaseExport, serializeCaseStore } from "../packages/cases/case-storage-model.mjs";
 import { appendCaseEvidencePin } from "../packages/cases/case-response-model.mjs";
 import { readCaseRecheckAnswerContext } from "../packages/cases/case-recheck-model.mjs";
+import { caseEvidenceLinkIssues, mergeCaseEvidenceLinks } from "../packages/cases/case-evidence-links.mjs";
 import { dispositionLabel, statusLabel } from "../packages/cases/case-record-decisions.mjs";
 import { normalizeDomain } from "../packages/cases/case-record-core.mjs";
 import { safeTerminalValue } from "./formatters/terminal.mjs";
@@ -52,6 +53,10 @@ function pin(input, now) {
     return raw;
 }
 function retainExistingEntries(before, after) {
+    if (canonicalArtifactJsonV2(mergeCaseEvidenceLinks(before.evidenceLinks, after.evidenceLinks) ?? [])
+        !== canonicalArtifactJsonV2(mergeCaseEvidenceLinks(undefined, after.evidenceLinks) ?? [])) {
+        throw new CliUsageError('The operation would remove retained evidence relationships. Nothing was written.');
+    }
     const pairs = [
         [before.notes, after.notes], [before.evidenceHistory, after.evidenceHistory], [before.evidencePins, after.evidencePins],
         [before.decisions, after.decisions], [before.actions, after.actions], [before.assertions, after.assertions],
@@ -66,7 +71,7 @@ function retainExistingEntries(before, after) {
         }
     }
 }
-function mutate(cases, args, input, note, now) {
+export function applyCliCaseOperation(cases, args, input, note, now) {
     if (args.operation === 'open') {
         const title = args.title === null ? undefined : prose(args.title, MAX_CASE_OBJECTIVE_LENGTH, 'Incident title');
         const result = args.newIncident
@@ -84,6 +89,9 @@ function mutate(cases, args, input, note, now) {
     else if (args.operation === 'pin') {
         result = updateCase(cases, current.id, { evidencePin: pin(input, now) }, now);
     }
+    else if (args.operation === 'link' || args.operation === 'withdraw-link') {
+        result = updateCase(cases, current.id, args.operation === 'link' ? { evidenceLink: input } : { evidenceLinkWithdrawal: input }, now);
+    }
     else if (args.operation === 'assess') {
         if (!input)
             throw new CliUsageError('An assessment requires JSON input.');
@@ -149,6 +157,15 @@ function formatCases(cases, digest) {
             lines.push(`Pin ${safeTerminalValue(pin.id)} · ${safeTerminalValue(pin.label)}`, safeTerminalValue(pin.value, '—', MAX_RESPONSE_VALUE_LENGTH), `  Source ${safeTerminalValue(pin.source)} · ${safeTerminalValue(pin.observedAt, 'time unavailable')} · ${pin.completeness}`);
         for (const decision of record.decisions)
             lines.push(`Assessment ${decision.createdAt}`, safeTerminalValue(decision.summary, '—', MAX_RESPONSE_VALUE_LENGTH), safeTerminalValue(decision.rationale, '—', MAX_RESPONSE_RATIONALE_LENGTH));
+        for (const { link, missingPinIds, cyclic } of caseEvidenceLinkIssues(record.evidenceLinks ?? [], record.evidencePins)) {
+            lines.push(`Evidence relationship ${safeTerminalValue(link.id)} · analyst declaration`, `  ${safeTerminalValue(link.fromPinId)} ${link.kind.replaceAll('_', ' ')} ${safeTerminalValue(link.toPinId)}`, `  ${safeTerminalValue(link.basis, '—', MAX_RESPONSE_RATIONALE_LENGTH)}`);
+            if (link.withdrawal)
+                lines.push(`  Withdrawn ${link.withdrawal.at}: ${safeTerminalValue(link.withdrawal.reason, '—', MAX_RESPONSE_RATIONALE_LENGTH)}`);
+            if (missingPinIds.length)
+                lines.push(`  Referenced pins not retained: ${missingPinIds.map(id => safeTerminalValue(id)).join(', ')}`);
+            if (cyclic)
+                lines.push('  Conflicting imported derivation cycle; no order is inferred.');
+        }
         for (const review of record.observedEffects.reviews)
             lines.push(`Recheck ${safeTerminalValue(review.observedAt, 'time unavailable')} · ${review.state} · ${review.completeness} · ${safeTerminalValue(review.source)}`);
         lines.push(`Other retained records: ${record.evidenceHistory.length} snapshots, ${record.actions.length} actions, ${record.assertions.length} assertions, ${record.attachments?.length ?? 0} file references.`, '');
@@ -176,7 +193,7 @@ export async function runCaseCommand(args, dependencies, context) {
             maximumBytes: MAX_EDITABLE_CASE_INPUT_BYTES, limits: boundedJsonLimitsForBytes(MAX_CASE_STORE_BYTES), label: 'Case operation input',
         }) : null;
         const note = args.noteSource ? await context.readInput(args.noteSource, MAX_NOTE_LENGTH * 4 + 4, 'Case note') : args.text;
-        const next = mutate(cases, args, input, note, now);
+        const next = applyCliCaseOperation(cases, args, input, note, now);
         if (Buffer.byteLength(serializeCaseStore(next)) > MAX_CASE_STORE_BYTES)
             throw new CliUsageError('The updated Case store exceeds its byte budget. No evidence was pruned and nothing was written.');
         const output = `${JSON.stringify(buildCaseExport(next, now))}\n`;

package/cli/case-pack.mjs

@@ -3,8 +3,12 @@ import { Buffer } from 'node:buffer';
 import { canonicalArtifactJson, canonicalArtifactJsonV2, SORTED_JSON_V2, } from "../packages/evidence/artifact-integrity.mjs";
 import { buildCaseReport, buildCaseReportVerificationProjection } from "../packages/cases/case-report.mjs";
 import { WHOISLEUTH_APPLICATION_VERSION } from "../lib/application-version.mjs";
-import { assertBoundedJsonStructure, scanBoundedJson } from "../lib/bounded-json.mjs";
-import { assertCaseBrandProfileIds, CASE_AUDIENCE_SENSITIVE_FIELD_NAMES, caseAudienceExclusions, normalizeDomain, normalizeCaseStore, projectCaseForAudience, safeId, } from "../packages/cases/case-model.mjs";
+import { assertBoundedJsonStructure, scanBoundedJson } from "../packages/analysis/bounded-json.mjs";
+import { assertCaseBrandProfileIds } from "../packages/cases/case-brand-profile-references.mjs";
+import { CASE_AUDIENCE_SENSITIVE_FIELD_NAMES, caseAudienceExclusions, projectCaseForAudience, } from "../packages/cases/case-record-projection.mjs";
+import { normalizeDomain } from "../packages/evidence/domain-name.mjs";
+import { normalizeCaseStore } from "../packages/cases/case-migration-model.mjs";
+import { safeId } from "../packages/cases/case-record-core.mjs";
 import { CASE_REPORT_SCHEMA, CASE_IMPORT_VERSIONS, CASE_SCHEMA_VERSION, INCIDENT_CASE_SCHEMA_VERSION, CLI_CASE_PACK_SCHEMA, CLI_CASE_PACK_VERSION, CLI_CASE_PACK_INPUT_CASE_VERSIONS, CLI_CASE_PACK_CURRENT_REDACTION_KEYS, CLI_CASE_PACK_PUBLIC_REPORT_KEYS, CLI_CASE_PACK_INTEGRITY_KEYS as INTEGRITY_KEYS, CLI_CASE_PACK_LIMITATIONS as PACKET_LIMITATIONS, CLI_CASE_PACK_PACKET_KEYS as PACKET_KEYS, CLI_CASE_PACK_REPORT_KEYS as REPORT_KEYS, CLI_CASE_PACK_ROOT_KEYS as ROOT_KEYS, MAX_CASE_IMPORT_BYTES, MAX_CASE_PACK_CASES, MAX_CASE_PACK_INPUT_BYTES, PUBLIC_CASE_SCHEMA_VERSION, PUBLISHED_V2_3_CASE_SCHEMA_VERSION, caseReportVersionMatchesCase, } from "../packages/contracts/case-portability.mjs";
 import { CliUsageError } from "./errors.mjs";
 import { canonicalCaseExportProjection as canonicalPackProjection } from "../packages/cases/case-export-input.mjs";
@@ -62,6 +66,11 @@ function allowedSensitiveFieldPath(key, path) {
         return topCasePath(path) || reportCasePath(path);
     if (key === 'notes')
         return topCasePath(path) || reportCasePath(path);
+    if (key === 'workflowMetadata')
+        return topCasePath(path) || analystResponsePath(path);
+    if (key === 'incidentTargets' || key === 'investigationContext') {
+        return path.at(-1) === 'workflowMetadata' && (topCasePath(path.slice(0, -1)) || analystResponsePath(path.slice(0, -1)));
+    }
     if (key === 'actions' || key === 'assertions' || key === 'manualTrail' || key === 'observedEffects' || key === 'closures' || key === 'branches') {
         return topCasePath(path) || analystResponsePath(path);
     }
@@ -473,6 +482,7 @@ export function formatCliCasePack(document) {
         `Cases      ${document.cases.length}`,
         `Reports    ${document.packet.reports.length}`,
         `Digest     ${document.integrity.digestSha256}`,
+        'Included for every audience: domain evidence, Case, pin and decision identifiers, tags, decision summaries and rationale. Review these before sharing.',
         '',
         ...document.packet.redactionManifest.excluded.map((item) => `Excluded: ${item}`),
         '',

package/cli/ci-report.mjs

@@ -1,4 +1,4 @@
-import { WHOISLEUTH_REQUEST_POLICY_URL } from "../lib/project-metadata.mjs";
+import { WHOISLEUTH_REQUEST_POLICY_URL } from "../packages/analysis/project-metadata.mjs";
 import { CLI_DOMAIN_CONTROL_MONITOR_SCHEMA } from "../packages/contracts/domain-control-monitor.mjs";
 function record(value) {
     return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
@@ -45,9 +45,12 @@ function junitCases(document) {
     return [{ name: 'WHOISleuth result', failure: 'Unsupported document for JUnit conversion.' }];
 }
 export function formatCliJunit(document) {
-    const cases = junitCases(record(document));
+    const root = record(document);
+    const cases = junitCases(root);
     const failures = cases.filter((item) => item.failure).length;
-    return `<?xml version="1.0" encoding="UTF-8"?>\n<testsuite name="WHOISleuth" tests="${cases.length}" failures="${failures}">\n${cases.map((item) => `  <testcase classname="whoisleuth" name="${xml(item.name)}">${item.failure ? `<failure message="${xml(item.failure)}" />` : ''}</testcase>`).join('\n')}\n</testsuite>\n`;
+    const reminders = root.schema === CLI_DOMAIN_CONTROL_MONITOR_SCHEMA
+        ? `\n  <system-out>${xml(`Renewal reviews due: ${Number(record(record(root.review).counts).due ?? 0)}`)}</system-out>` : '';
+    return `<?xml version="1.0" encoding="UTF-8"?>\n<testsuite name="WHOISleuth" tests="${cases.length}" failures="${failures}">\n${cases.map((item) => `  <testcase classname="whoisleuth" name="${xml(item.name)}">${item.failure ? `<failure message="${xml(item.failure)}" />` : ''}</testcase>`).join('\n')}${reminders}\n</testsuite>\n`;
 }
 export function buildPostureSarif(document) {
     const root = record(document);

package/cli/collection-arguments.mjs

@@ -0,0 +1,123 @@
+import {} from "./command-argument-grammar.mjs";
+import {} from "./fail-policy.mjs";
+import { commandDefaultNumber, commandDefaultText } from "./command-reference.mjs";
+import { COLLECTION_COMMAND_DEFINITIONS } from "./collection-command-definitions.mjs";
+import { terminalOptions, normalizedLabel, failPolicies, parseOutput, } from "./argument-values.mjs";
+function parseLookupArguments(parsed) {
+    const output = parseOutput(parsed, COLLECTION_COMMAND_DEFINITIONS.lookup);
+    const selectedFailPolicies = failPolicies(parsed, 'lookup');
+    return {
+        action: 'lookup',
+        query: parsed.positionalValue('target'),
+        output,
+        deep: parsed.hasOption('--deep'),
+        detail: parsed.hasOption('--summary')
+            ? 'summary'
+            : parsed.hasOption('--verbose')
+                ? 'verbose'
+                : 'standard',
+        strictExit: parsed.hasOption('--strict-exit'),
+        events: parsed.hasOption('--events'),
+        plan: parsed.hasOption('--plan'),
+        includeAttribution: !parsed.hasOption('--no-attribution'),
+        observerLabel: normalizedLabel(parsed, '--observer', 80),
+        vantageLabel: normalizedLabel(parsed, '--vantage', 80),
+        ...terminalOptions(parsed),
+        ...(parsed.hasOption('--browse') ? { browse: true } : {}),
+        ...(parsed.hasOption('--exact-url') ? { exactUrl: true } : {}),
+        ...(parsed.optionValue('--save-lookup')
+            ? { saveLookup: parsed.optionValue('--save-lookup') }
+            : {}),
+        ...(selectedFailPolicies ? { failOn: selectedFailPolicies } : {}),
+    };
+}
+function parseBulkArguments(parsed) {
+    const deep = parsed.hasOption('--deep');
+    const selectedFailPolicies = failPolicies(parsed, 'bulk');
+    const output = parseOutput(parsed, COLLECTION_COMMAND_DEFINITIONS.bulk);
+    const filter = parsed.hasOption('--registered-only')
+        ? 'registered'
+        : parsed.hasOption('--inconclusive-only')
+            ? 'inconclusive'
+            : parsed.hasOption('--errors-only')
+                ? 'errors'
+                : 'all';
+    return {
+        action: 'bulk',
+        source: parsed.positionalValue('source'),
+        output,
+        deep,
+        concurrency: parsed.integerOption('--concurrency') ?? commandDefaultNumber('bulk', '--concurrency', deep),
+        checkpoint: parsed.optionValue('--checkpoint'),
+        resume: parsed.hasOption('--resume'),
+        events: parsed.hasOption('--events'),
+        plan: parsed.hasOption('--plan'),
+        filter,
+        ...terminalOptions(parsed),
+        ...(selectedFailPolicies ? { failOn: selectedFailPolicies } : {}),
+    };
+}
+function parseDiscoverArguments(parsed) {
+    return {
+        action: 'discover',
+        seed: parsed.positionalValue('subject'),
+        output: parseOutput(parsed, COLLECTION_COMMAND_DEFINITIONS.discover),
+        ...discoveryValues(parsed),
+        snapshotSource: parsed.optionValue('--snapshot'),
+        ...terminalOptions(parsed),
+    };
+}
+function discoveryValues(parsed) {
+    const familyText = parsed.optionValue('--families');
+    return {
+        preset: (familyText
+            ? 'custom'
+            : (parsed.optionValue('--preset') ?? commandDefaultText('discover', '--preset'))),
+        keyboardLayout: (parsed.optionValue('--keyboard') ??
+            commandDefaultText('discover', '--keyboard')),
+        tldText: parsed.optionValue('--tlds'),
+        dictionarySource: parsed.optionValue('--dictionary'),
+        familyText,
+    };
+}
+function parseDiscoverScanArguments(parsed) {
+    const deep = parsed.hasOption('--deep');
+    const selectedFailPolicies = failPolicies(parsed, 'discover-scan');
+    const filter = parsed.hasOption('--registered-only')
+        ? 'registered'
+        : parsed.hasOption('--inconclusive-only')
+            ? 'inconclusive'
+            : parsed.hasOption('--acquisition-only')
+                ? 'acquisition'
+                : parsed.hasOption('--suppressed-only')
+                    ? 'suppressed'
+                    : 'all';
+    return {
+        action: 'discover-scan',
+        seed: parsed.positionalValue('subject'),
+        output: parseOutput(parsed, COLLECTION_COMMAND_DEFINITIONS['discover-scan']),
+        ...discoveryValues(parsed),
+        deep,
+        scanLimit: parsed.integerOption('--scan-limit') ??
+            commandDefaultNumber('discover-scan', '--scan-limit', deep),
+        chunkSize: parsed.integerOption('--chunk-size') ?? commandDefaultNumber('discover-scan', '--chunk-size'),
+        concurrency: parsed.integerOption('--concurrency') ??
+            commandDefaultNumber('discover-scan', '--concurrency', deep),
+        checkpoint: parsed.optionValue('--checkpoint'),
+        resume: parsed.hasOption('--resume'),
+        resolverText: parsed.optionValue('--resolver'),
+        observationSnapshot: parsed.optionValue('--observation-snapshot'),
+        allowlistSource: parsed.optionValue('--allowlist'),
+        filter,
+        events: parsed.hasOption('--events'),
+        plan: parsed.hasOption('--plan'),
+        ...terminalOptions(parsed),
+        ...(selectedFailPolicies ? { failOn: selectedFailPolicies } : {}),
+    };
+}
+export const COLLECTION_ARGUMENT_PARSERS = Object.freeze({
+    lookup: parseLookupArguments,
+    bulk: parseBulkArguments,
+    discover: parseDiscoverArguments,
+    'discover-scan': parseDiscoverScanArguments,
+});

package/cli/collection-command-definitions.mjs

@@ -0,0 +1,330 @@
+import { positional, OPTIONAL_FILE_POSITIONAL, OPTIONAL_TEXT_POSITIONAL, constraint, commandSeed, } from "./command-definition.mjs";
+import { bulkQueryLimit, bulkConcurrencyLimit } from "../lib/bulk-limits.mjs";
+const COLLECTION_CEILINGS = `${bulkQueryLimit('fast')} fast or ${bulkQueryLimit('deep')} deep`;
+const CONCURRENCY_CEILINGS = `${bulkConcurrencyLimit('fast')} fast or ${bulkConcurrencyLimit('deep')} deep`;
+export const COLLECTION_COMMAND_DEFINITIONS = Object.freeze({
+    lookup: commandSeed({
+        reference: {
+            description: 'Collect registration evidence for one domain, IP, or ASN.',
+            example: 'whoisleuth lookup example.test --deep --browse',
+            boundary: 'Fast is the default. An ICANN-recognised public domain, reserved documentation domain, IP, or ASN may occupy command position as shorthand; it delegates to this same parser and URL-like input requires the explicit lookup command. Deep mode adds bounded WHOIS, DNS, HTTP, TLS, technology, posture, and network context where applicable. --deep --exact-url explicitly sends the input URL path and query to the website, without its fragment; ordinary URL input sends only the hostname. --plan remains offline and omits the selected URL. Retained paths and page-derived text require review before sharing. A full Deep homepage observation can derive fixed publication and delivery/cache summaries from the same response without retaining raw metadata values or making another request. --browse opens before collection, shows aggregate Fast progress or independently settled planned Deep sources, and then navigates allowlisted retained fields in the completed document. Press ? for help and / to search rendered panel text only. Closing during collection cancels without a partial document. --save-lookup writes the exact completed private JSON only after a normal browser close; it can contain normalised evidence omitted from panels and refuses an existing path.',
+        },
+        collection: {
+            scope: 'Accepts one target. Fast is the default; deep collection must be selected explicitly.',
+        },
+        summary: 'Collect one domain, IP, or ASN',
+        options: [
+            '--json',
+            '--junit',
+            '--markdown',
+            '--html',
+            '--no-attribution',
+            '--fast',
+            '--deep',
+            '--exact-url',
+            '--observer',
+            '--vantage',
+            '--plan',
+            '--summary',
+            '--verbose',
+            '--browse',
+            '--save-lookup',
+            '--strict-exit',
+            '--fail-on',
+            '--events',
+            '--quiet',
+            '--no-color',
+        ],
+        positionals: Object.freeze([
+            positional('target', 'text', 0, 1, [], 'argv_or_stdin', ['--browse']),
+        ]),
+        constraints: Object.freeze([
+            constraint({
+                kind: 'mutually_exclusive',
+                options: ['--json', '--junit', '--markdown', '--html'],
+            }),
+            constraint({ kind: 'mutually_exclusive', options: ['--fast', '--deep'] }),
+            constraint({ kind: 'mutually_exclusive', options: ['--summary', '--verbose'] }),
+            constraint({ kind: 'requires_all', option: '--save-lookup', requiredOptions: ['--browse'] }),
+            constraint({ kind: 'requires_all', option: '--exact-url', requiredOptions: ['--deep'] }),
+            constraint({
+                kind: 'excludes_all',
+                option: '--summary',
+                excludedOptions: ['--json', '--junit', '--markdown', '--html'],
+            }),
+            constraint({
+                kind: 'excludes_all',
+                option: '--verbose',
+                excludedOptions: ['--json', '--junit', '--markdown', '--html'],
+            }),
+            constraint({
+                kind: 'excludes_all',
+                option: '--browse',
+                excludedOptions: [
+                    '--json',
+                    '--junit',
+                    '--markdown',
+                    '--html',
+                    '--summary',
+                    '--verbose',
+                    '--events',
+                    '--plan',
+                    '--quiet',
+                ],
+            }),
+            constraint({
+                kind: 'requires_any',
+                option: '--no-attribution',
+                requiredOptions: ['--markdown', '--html'],
+            }),
+            constraint({
+                kind: 'excludes_all',
+                option: '--plan',
+                excludedOptions: [
+                    '--junit',
+                    '--markdown',
+                    '--html',
+                    '--summary',
+                    '--verbose',
+                    '--strict-exit',
+                    '--events',
+                    '--quiet',
+                    '--fail-on',
+                ],
+            }),
+        ]),
+        handlerOwner: 'lookup',
+        networkEffect: 'conditional_network',
+        common: true,
+        schemaIdentifiers: Object.freeze(['whoisleuth.cli.lookup', 'whoisleuth.cli.lookup-plan']),
+        primaryArtefacts: Object.freeze(['Source-qualified Lookup', 'Lookup request plan']),
+        planSupport: true,
+        additionalOutputFormats: Object.freeze([]),
+        bootstrapProfile: 'allowed',
+    }),
+    bulk: commandSeed({
+        reference: {
+            description: 'Triage newline-delimited domains, IPs, or ASNs with bounded concurrency.',
+            example: 'cat domains.txt | whoisleuth bulk --jsonl',
+            boundary: 'Fast and deep jobs use separate concurrency ceilings. Filters affect output only; collection failures and inconclusive authority states remain explicit in JSON, JSONL, and CSV. --csv-with-metadata adds source versions, separate observation and report times, collection origin and diagnostic states; --csv retains the compact columns.',
+        },
+        collection: {
+            scope: `Accepts at most ${COLLECTION_CEILINGS} targets, with concurrency capped at ${CONCURRENCY_CEILINGS}.`,
+        },
+        summary: 'Run bounded multi-target collection',
+        options: [
+            '--json',
+            '--jsonl',
+            '--junit',
+            '--csv',
+            '--csv-with-metadata',
+            '--domains',
+            '--queries',
+            '--registered-only',
+            '--inconclusive-only',
+            '--errors-only',
+            '--fast',
+            '--deep',
+            '--concurrency',
+            '--checkpoint',
+            '--resume',
+            '--events',
+            '--plan',
+            '--fail-on',
+            '--quiet',
+            '--no-color',
+        ],
+        positionals: OPTIONAL_FILE_POSITIONAL,
+        constraints: Object.freeze([
+            constraint({
+                kind: 'mutually_exclusive',
+                options: [
+                    '--json',
+                    '--jsonl',
+                    '--junit',
+                    '--csv',
+                    '--csv-with-metadata',
+                    '--domains',
+                    '--queries',
+                ],
+            }),
+            constraint({
+                kind: 'mutually_exclusive',
+                options: ['--registered-only', '--inconclusive-only', '--errors-only'],
+            }),
+            constraint({ kind: 'mutually_exclusive', options: ['--fast', '--deep'] }),
+            constraint({ kind: 'requires_all', option: '--resume', requiredOptions: ['--checkpoint'] }),
+            constraint({
+                kind: 'excludes_all',
+                option: '--plan',
+                excludedOptions: [
+                    '--jsonl',
+                    '--junit',
+                    '--csv',
+                    '--csv-with-metadata',
+                    '--domains',
+                    '--queries',
+                    '--events',
+                    '--checkpoint',
+                    '--resume',
+                    '--quiet',
+                    '--fail-on',
+                ],
+            }),
+        ]),
+        handlerOwner: 'bulk',
+        networkEffect: 'conditional_network',
+        common: true,
+        schemaIdentifiers: Object.freeze([
+            'whoisleuth.cli.bulk',
+            'whoisleuth.cli.bulk.item',
+            'whoisleuth.cli.bulk-checkpoint',
+        ]),
+        primaryArtefacts: Object.freeze(['Bulk result', 'Bulk checkpoint']),
+        planSupport: true,
+        additionalOutputFormats: Object.freeze([]),
+        bootstrapProfile: 'allowed',
+    }),
+    discover: commandSeed({
+        reference: {
+            description: 'Generate bounded lookalike-domain candidates from a brand or registrable domain, including multi-part public suffixes.',
+            example: 'whoisleuth discover example.test --preset common --jsonl',
+            boundary: 'Generation and optional local snapshot comparison are offline. Candidates are leads only and are not resolved, registered, or classified as malicious.',
+        },
+        collection: {
+            scope: 'Generates a bounded candidate set from local rules, dictionaries, and optional saved snapshots.',
+        },
+        summary: 'Generate lookalike candidates offline',
+        options: [
+            '--tlds',
+            '--preset',
+            '--families',
+            '--keyboard',
+            '--dictionary',
+            '--snapshot',
+            '--json',
+            '--jsonl',
+            '--domains',
+            '--quiet',
+            '--no-color',
+        ],
+        positionals: OPTIONAL_TEXT_POSITIONAL,
+        constraints: Object.freeze([
+            constraint({ kind: 'mutually_exclusive', options: ['--json', '--jsonl', '--domains'] }),
+            constraint({ kind: 'mutually_exclusive', options: ['--preset', '--families'] }),
+            constraint({
+                kind: 'value_excludes',
+                option: '--preset',
+                value: 'common',
+                excludedOptions: ['--dictionary'],
+            }),
+        ]),
+        handlerOwner: 'discovery',
+        networkEffect: 'offline',
+        common: true,
+        schemaIdentifiers: Object.freeze([
+            'whoisleuth.cli.discover',
+            'whoisleuth.cli.discover.item',
+            'whoisleuth.cli.discovery-snapshot',
+        ]),
+        primaryArtefacts: Object.freeze(['Candidate set', 'Discovery snapshot']),
+        planSupport: false,
+        additionalOutputFormats: Object.freeze([]),
+        bootstrapProfile: 'allowed',
+    }),
+    'discover-scan': commandSeed({
+        reference: {
+            description: 'Generate a bounded candidate set, collect a selected subset, and produce a supervised review queue.',
+            example: 'whoisleuth discover-scan example.test --scan-limit 50 --checkpoint scan.json --json',
+            boundary: `This command performs network collection. Fast compact lookup is the default; deep mode is capped at ${bulkQueryLimit('deep')} candidates. Allowlisting changes review priority only and shared infrastructure remains a lead, not attribution. --csv-with-metadata adds source versions, separate observation and report times, collection origin and diagnostic states; --csv retains the compact columns.`,
+        },
+        collection: {
+            scope: `Scans at most ${COLLECTION_CEILINGS} candidates, with concurrency capped at ${CONCURRENCY_CEILINGS}.`,
+        },
+        summary: 'Collect a supervised candidate review queue',
+        options: [
+            '--tlds',
+            '--preset',
+            '--families',
+            '--keyboard',
+            '--dictionary',
+            '--fast',
+            '--deep',
+            '--scan-limit',
+            '--chunk-size',
+            '--concurrency',
+            '--resolver',
+            '--allowlist',
+            '--checkpoint',
+            '--resume',
+            '--observation-snapshot',
+            '--registered-only',
+            '--inconclusive-only',
+            '--acquisition-only',
+            '--suppressed-only',
+            '--events',
+            '--plan',
+            '--fail-on',
+            '--json',
+            '--jsonl',
+            '--csv',
+            '--csv-with-metadata',
+            '--domains',
+            '--quiet',
+            '--no-color',
+        ],
+        positionals: OPTIONAL_TEXT_POSITIONAL,
+        constraints: Object.freeze([
+            constraint({
+                kind: 'mutually_exclusive',
+                options: ['--json', '--jsonl', '--csv', '--csv-with-metadata', '--domains'],
+            }),
+            constraint({ kind: 'mutually_exclusive', options: ['--preset', '--families'] }),
+            constraint({ kind: 'mutually_exclusive', options: ['--fast', '--deep'] }),
+            constraint({
+                kind: 'mutually_exclusive',
+                options: [
+                    '--registered-only',
+                    '--inconclusive-only',
+                    '--acquisition-only',
+                    '--suppressed-only',
+                ],
+            }),
+            constraint({ kind: 'requires_all', option: '--resume', requiredOptions: ['--checkpoint'] }),
+            constraint({
+                kind: 'value_excludes',
+                option: '--preset',
+                value: 'common',
+                excludedOptions: ['--dictionary'],
+            }),
+            constraint({
+                kind: 'excludes_all',
+                option: '--plan',
+                excludedOptions: [
+                    '--jsonl',
+                    '--csv',
+                    '--csv-with-metadata',
+                    '--domains',
+                    '--events',
+                    '--checkpoint',
+                    '--resume',
+                    '--observation-snapshot',
+                    '--quiet',
+                    '--fail-on',
+                ],
+            }),
+        ]),
+        handlerOwner: 'discovery_scan',
+        networkEffect: 'conditional_network',
+        common: true,
+        schemaIdentifiers: Object.freeze([
+            'whoisleuth.cli.discovery-scan',
+            'whoisleuth.cli.discovery-scan.item',
+            'whoisleuth.cli.discovery-observation-snapshot',
+        ]),
+        primaryArtefacts: Object.freeze(['Reviewed candidate queue', 'Observation snapshot']),
+        planSupport: true,
+        additionalOutputFormats: Object.freeze([]),
+        bootstrapProfile: 'allowed',
+    }),
+});

package/cli/collection-preflight.mjs

@@ -1,3 +1,4 @@
+import { bulkQueryLimit } from "../lib/bulk-limits.mjs";
 export const CLI_COLLECTION_PREFLIGHT_SCHEMA = 'whoisleuth.cli.collection-preflight';
 export const CLI_COLLECTION_PREFLIGHT_VERSION = 1;
 export function buildCollectionPreflight(options) {
@@ -12,7 +13,7 @@ export function buildCollectionPreflight(options) {
         networkRequestsMade: false,
         scope: Object.freeze({
             selectedTargets: options.targetCount,
-            commandTargetLimit: options.targetLimit,
+            commandTargetLimit: bulkQueryLimit(options.deep ? 'deep' : 'fast'),
             concurrency: options.concurrency,
             sourceFamilies: Object.freeze(sourceFamilies),
             exactRequestCountKnown: false,
@@ -53,6 +54,12 @@ export function formatCollectionPreflight(document) {
         ...document.scope.sourceFamilies.map((source) => `  ${source}`),
         '',
         ...document.disclosure.map((item) => `Disclosure: ${item}`),
+        '',
+        `Output format: ${document.persistence.output}`,
+        `Checkpoint: ${document.persistence.checkpoint ? 'enabled' : 'not written'}. ${document.persistence.note}`,
+        ...(document.review.allowlistAffectsPriorityOnly ? ['Allowlist: affects review priority only; it does not exclude targets from collection.'] : []),
+        'Enforcement: none. This plan does not report, block or remove a target.',
+        '',
         ...document.limitations.map((item) => `Limitation: ${item}`),
         '',
     ].join('\n');