@slicedearth/whoisleuth-cli 2.4.0 → 2.6.0

package/cli/investigation-plan.mjs

@@ -1,156 +1,20 @@
 import { domainToASCII } from 'node:url';
 import { normalizeExplicitIsoTimestamp } from "../packages/evidence/observation.mjs";
-import { CLI_DOMAIN_CONTROL_MONITOR_SCHEMA } from "../packages/contracts/domain-control-monitor.mjs";
-import { DOMAIN_CONTROL_REVIEW_SCHEMA } from "../packages/contracts/domain-control-review.mjs";
-import { EXTERNAL_FINDINGS_SCHEMA } from "../packages/interchange/external-findings-import.mjs";
-import { CLI_LOOKUP_BRIEF_SCHEMA } from "./lookup-brief.mjs";
-import { INVESTIGATION_PLAN_RECIPES, RUNNABLE_INVESTIGATION_PLAN_RECIPES, cliInvocationNetworkEffect, } from "./command-reference.mjs";
+import { cliInvocationNetworkEffect } from "./command-reference.mjs";
+import { INVESTIGATION_RECIPE_DEFINITIONS, INVESTIGATION_PLAN_RECIPES, RUNNABLE_INVESTIGATION_PLAN_RECIPES, } from "./investigation-recipes.mjs";
 export const CLI_INVESTIGATION_PLAN_SCHEMA = 'whoisleuth.cli.investigation-plan';
 export const CLI_INVESTIGATION_PLAN_VERSION = 1;
 export const CLI_WORKFLOW_RECIPE_CATALOGUE_SCHEMA = 'whoisleuth.cli.workflow-recipe-catalogue';
 export const CLI_WORKFLOW_RECIPE_CATALOGUE_VERSION = 1;
 export { INVESTIGATION_PLAN_RECIPES, RUNNABLE_INVESTIGATION_PLAN_RECIPES };
-const RECIPES = Object.freeze({
-    'domain-triage': Object.freeze({
-        id: 'domain-triage',
-        label: 'New domain triage',
-        standardInputs: Object.freeze([
-            { stepId: 'export', input: 1, sourceStepId: 'collect' },
-            { stepId: 'verify', input: 1, sourceStepId: 'export' },
-        ]),
-        subjectRequirement: 'domain',
-        objective: 'Collect and preserve separately attributed registration, DNS, HTTP, TLS, page, and network-context evidence.',
-        limitations: Object.freeze([
-            'Collection remains analyst-triggered and source limitations remain explicit.',
-            'Disposition, reviewed response actions, monitoring, and closure continue in the saved Case workspace; this CLI recipe does not submit reports.',
-        ]),
-        steps: (domain) => Object.freeze([
-            step('collect', 'Collect a Deep lookup', 'lookup', [domain, '--deep', '--json'], 'network', 'network_disclosure', 'whoisleuth.cli.lookup', 'Review source health and limitations before using missing fields.'),
-            step('export', 'Create a portable evidence report', 'export', ['<saved-lookup.json>'], 'offline', 'analyst_selection', 'whoisleuth.lookup-evidence', 'Reuse the collected Lookup by default, or select a different reviewed Lookup file.'),
-            step('verify', 'Verify the exported artefact', 'verify-artifact', ['<evidence.json>', '--json'], 'offline', 'analyst_selection', 'whoisleuth.offline-artifact-verification', 'Keep verification distinct from a claim that the observations are correct or current.'),
-        ]),
-    }),
-    'lookalike-review': Object.freeze({
-        id: 'lookalike-review',
-        label: 'Lookalike candidate review',
-        subjectRequirement: 'brand_or_domain',
-        objective: 'Generate a bounded candidate queue, collect only the selected scope, and retain a reviewed candidate lookup.',
-        limitations: Object.freeze([
-            'Candidate generation does not establish registration, control, intent, or maliciousness.',
-            'Official-reference collection and page comparison require analyst-selected saved evidence; use page-compare after retaining the reference and candidate observations.',
-        ]),
-        steps: (subject) => Object.freeze([
-            step('generate', 'Generate candidates offline', 'discover', [subject, '--preset', 'all', '--json'], 'offline', 'none', 'whoisleuth.cli.discover', 'Review mutation families and suppressions before collection.'),
-            step('scan', 'Collect a bounded candidate queue', 'discover-scan', [subject, '--fast', '--scan-limit', '50', '--json'], 'network', 'network_disclosure', 'whoisleuth.cli.discovery-scan', 'Fast collection is a triage boundary; partial or inconclusive authority evidence remains explicit.'),
-            step('inspect', 'Deep-review one selected candidate', 'lookup', ['<selected-domain>', '--deep', '--json'], 'network', 'analyst_selection', 'whoisleuth.cli.lookup', 'Select a candidate deliberately; generation does not prove registration, control, intent, or maliciousness.'),
-        ]),
-    }),
-    'owned-domain-review': Object.freeze({
-        id: 'owned-domain-review',
-        label: 'Owned domain posture review',
-        subjectRequirement: 'domain',
-        objective: 'Review current passive posture and compare supplied observations with an analyst-authored control manifest.',
-        limitations: Object.freeze(['Use only for a domain the analyst owns or is authorised to review.']),
-        steps: (domain) => Object.freeze([
-            step('posture', 'Collect bounded DNS posture', 'posture', [domain, '--json'], 'network', 'network_disclosure', 'whoisleuth.cli.posture', 'Review mail profile and delegation evidence before interpreting missing records.'),
-            step('lookup', 'Collect supporting Deep evidence', 'lookup', [domain, '--deep', '--json'], 'network', 'network_disclosure', 'whoisleuth.cli.lookup', 'Retain separately attributed registration, DNS, TLS, and page observations.'),
-            step('manifest', 'Review the domain control manifest', 'domain-control', ['<review-input.json>', '--json'], 'offline', 'analyst_selection', DOMAIN_CONTROL_REVIEW_SCHEMA, 'Only complete supplied observations may produce drift.'),
-        ]),
-    }),
-    'historical-comparison': Object.freeze({
-        id: 'historical-comparison',
-        label: 'Historical observation comparison',
-        standardInputs: Object.freeze([
-            { stepId: 'diff', input: 2, sourceStepId: 'current' },
-            { stepId: 'timeline', input: 3, sourceStepId: 'current' },
-        ]),
-        subjectRequirement: 'domain',
-        objective: 'Collect a current observation and compare it with analyst-selected saved observations without merging source states.',
-        limitations: Object.freeze(['A later observation does not retroactively refresh retained evidence.']),
-        steps: (domain) => Object.freeze([
-            step('current', 'Collect the current lookup', 'lookup', [domain, '--deep', '--json'], 'network', 'network_disclosure', 'whoisleuth.cli.lookup', 'A current request does not refresh or validate older provider-reported history.'),
-            step('diff', 'Compare two selected observations', 'diff', ['<previous.json>', '<current.json>', '--json'], 'offline', 'analyst_selection', 'whoisleuth.cli.lookup-diff', 'Equal, different, conflicting, and unavailable evidence remain separate.'),
-            step('timeline', 'Build a bounded local timeline', 'timeline', ['<oldest.json>', '<newer.json>', '<current.json>', '--json'], 'offline', 'analyst_selection', 'whoisleuth.cli.lookup-timeline', 'Choose two to twenty same-domain files in chronological scope.'),
-        ]),
-    }),
-    'campaign-review': Object.freeze({
-        id: 'campaign-review',
-        label: 'Campaign candidate review',
-        subjectRequirement: 'brand_or_domain',
-        objective: 'Prepare a bounded candidate set, collect a deliberately selected queue, and review retained evidence without asserting campaign attribution.',
-        limitations: Object.freeze(['Grouping candidates is analyst triage and does not prove common ownership, control, infrastructure, or intent.']),
-        steps: (subject) => Object.freeze([
-            step('prepare', 'Prepare candidates offline', 'discover', [subject, '--preset', 'all', '--json'], 'offline', 'none', 'whoisleuth.cli.discover', 'Review mutation families and bounded omissions before selecting a collection scope.'),
-            step('collect', 'Collect the selected candidate queue', 'discover-scan', [subject, '--fast', '--scan-limit', '50', '--json'], 'network', 'network_disclosure', 'whoisleuth.cli.discovery-scan', 'Treat partial and inconclusive authority results as explicit outcomes.'),
-            step('review', 'Prepare a selected candidate brief', 'brief', ['<saved-lookup.json>', '--json'], 'offline', 'analyst_selection', CLI_LOOKUP_BRIEF_SCHEMA, 'Select a saved candidate Lookup; keep any campaign grouping analyst-authored.'),
-        ]),
-    }),
-    'certificate-anomaly': Object.freeze({
-        id: 'certificate-anomaly',
-        label: 'Certificate anomaly review',
-        subjectRequirement: 'domain',
-        objective: 'Review bounded certificate observations alongside current source-qualified domain evidence without treating issuance as proof of control or intent.',
-        limitations: Object.freeze(['Certificate observations are separately attributed and do not establish current service control.']),
-        steps: (domain) => Object.freeze([
-            step('search', 'Collect bounded certificate observations', 'ct-search', [domain, '--json'], 'network', 'network_disclosure', 'whoisleuth.cli.ct-search', 'Review source availability, truncation, and observation timing.'),
-            step('intake', 'Normalise the selected observations', 'ct-intake', ['<certificate-events.json>', '--json'], 'offline', 'analyst_selection', EXTERNAL_FINDINGS_SCHEMA, 'Select a certificate-event batch; a certificate-search report is not interchangeable with that input.'),
-            step('corroborate', 'Collect supporting domain evidence', 'lookup', [domain, '--deep', '--json'], 'network', 'network_disclosure', 'whoisleuth.cli.lookup', 'Compare evidence families without collapsing certificate and registration identities.'),
-        ]),
-    }),
-    'registry-disagreement': Object.freeze({
-        id: 'registry-disagreement',
-        label: 'Registry disagreement review',
-        standardInputs: Object.freeze([
-            { stepId: 'compare', input: 1, sourceStepId: 'collect' },
-            { stepId: 'report', input: 1, sourceStepId: 'collect' },
-        ]),
-        subjectRequirement: 'domain',
-        objective: 'Collect separately attributed registration evidence and review conflicting publications without selecting an arbitrary source as truth.',
-        limitations: Object.freeze(['Only authority-aware registration evidence may decide availability; disagreement remains explicit.']),
-        steps: (domain) => Object.freeze([
-            step('collect', 'Collect source-qualified registration evidence', 'lookup', [domain, '--deep', '--json'], 'network', 'network_disclosure', 'whoisleuth.cli.lookup', 'Retain RDAP, registrar RDAP, WHOIS, and authority states separately.'),
-            step('compare', 'Compare registry publications offline', 'compare', ['<saved-lookup.json>', '--json'], 'offline', 'analyst_selection', 'whoisleuth.cli.compare', 'Do not convert conflicting or unavailable publications into equivalence.'),
-            step('report', 'Prepare a target-free source report', 'source-report', ['<saved-lookup.json>', '--json'], 'offline', 'analyst_selection', 'whoisleuth.source-reliability-report', 'The report describes source behaviour, not ownership, safety, or legal status.'),
-        ]),
-    }),
-    'evidence-handoff': Object.freeze({
-        id: 'evidence-handoff',
-        label: 'Reviewed evidence handoff',
-        standardInputs: Object.freeze([{ stepId: 'lint', input: 1, sourceStepId: 'package' }]),
-        subjectRequirement: 'review_label',
-        objective: 'Verify, minimise, and package analyst-selected evidence for a deliberate handoff without transmitting or submitting it.',
-        limitations: Object.freeze(['The recipe prepares local material only; sharing remains a separate deliberate action.']),
-        steps: () => Object.freeze([
-            step('verify', 'Verify the selected artefact', 'verify-artifact', ['<evidence.json>', '--json', '--strict-exit'], 'offline', 'analyst_selection', 'whoisleuth.offline-artifact-verification', 'Verification checks structure and integrity, not the truth or currency of observations.'),
-            step('package', 'Build a reviewed public Case-pack', 'case-pack', ['<cases.json>', '--audience', 'public', '--reviewed', '--json'], 'offline', 'analyst_selection', 'whoisleuth.cli.case-pack', 'Review minimisation and audience projection before retaining the separate package.'),
-            step('lint', 'Review deliberate-sharing metadata', 'sharing-review', ['<package.json>', '--marking', 'clear', '--recipient-scope', 'public', '--purpose', 'reviewed evidence handoff', '--human-reviewed', '--personal-data-reviewed', '--redactions-confirmed', '--json'], 'offline', 'analyst_selection', 'whoisleuth.cli.sharing-review', 'A clear lint result does not send, upload, publish, or authorise the artefact.'),
-        ]),
-    }),
-    'planned-domain-change': Object.freeze({
-        id: 'planned-domain-change',
-        label: 'Planned domain change',
-        subjectRequirement: 'domain',
-        objective: 'Review an analyst-authored desired state and prepare bounded change material without changing DNS, registry, mail, or hosted configuration.',
-        limitations: Object.freeze(['Planning and packaging never apply, submit, schedule, or enforce a change.']),
-        steps: () => Object.freeze([
-            step('control', 'Review the desired-state manifest', 'domain-control', ['<review-input.json>', '--json'], 'offline', 'analyst_selection', DOMAIN_CONTROL_REVIEW_SCHEMA, 'Only supplied complete observations may produce drift.'),
-            step('assure', 'Review change and recovery assumptions', 'assurance', ['<assurance-input.json>', '--json'], 'offline', 'analyst_selection', 'whoisleuth.domain-assurance', 'Record uncertainty, rollback dependencies, and unavailable evidence explicitly.'),
-            step('package', 'Build a reviewed change packet', 'change-packet', ['<change-packet-input.json>', '--json'], 'offline', 'analyst_selection', 'whoisleuth.domain-change-packet', 'The packet is local reviewed material and performs no submission or enforcement.'),
-        ]),
-    }),
-    'post-change-verification': Object.freeze({
-        id: 'post-change-verification',
-        label: 'Post-change verification',
-        subjectRequirement: 'domain',
-        objective: 'Perform one explicit later observation and compare it with analyst-selected retained evidence after an authorised change.',
-        limitations: Object.freeze(['This is a one-time recheck, not monitoring setup or proof that every resolver or service has converged.']),
-        steps: () => Object.freeze([
-            step('recheck', 'Run one bounded retained-manifest review', 'monitor-once', ['<manifest.json>', '--limit', '1', '--json'], 'network', 'network_disclosure', CLI_DOMAIN_CONTROL_MONITOR_SCHEMA, 'One later observation may remain partial, unavailable, stale, or conflicting.'),
-            step('compare', 'Compare selected before and after evidence', 'diff', ['<before.json>', '<after.json>', '--json'], 'offline', 'analyst_selection', 'whoisleuth.cli.lookup-diff', 'Materiality is derived from compatible retained evidence and does not infer intent.'),
-            step('record', 'Record reviewed completion material', 'change-packet', ['<post-change-input.json>', '--json'], 'offline', 'analyst_selection', 'whoisleuth.domain-change-packet', 'Recording reviewed material does not submit it or start automatic monitoring.'),
-        ]),
+const RECIPES = Object.freeze(Object.fromEntries(INVESTIGATION_PLAN_RECIPES.map((id) => [
+    id,
+    Object.freeze({
+        ...INVESTIGATION_RECIPE_DEFINITIONS[id],
+        id,
+        steps: (subject) => validatedSteps(INVESTIGATION_RECIPE_DEFINITIONS[id].steps(subject)),
     }),
-});
+])));
 export const INVESTIGATION_RECIPE_REGISTRY = RECIPES;
 export function workflowStandardInputs(recipe) {
     return RECIPES[recipe].standardInputs ?? [];
@@ -160,7 +24,12 @@ export function isRunnableInvestigationRecipe(value) {
     return RUNNABLE_INVESTIGATION_PLAN_RECIPES.includes(value);
 }
 export function workflowReviewDeclarations(step) {
-    return step.arguments.filter(argument => ['--reviewed', '--human-reviewed', '--personal-data-reviewed', '--redactions-confirmed'].includes(argument));
+    return step.arguments.filter((argument) => [
+        '--reviewed',
+        '--human-reviewed',
+        '--personal-data-reviewed',
+        '--redactions-confirmed',
+    ].includes(argument));
 }
 function recipeCatalogueEntry(recipe) {
     const exampleSubject = recipe.subjectRequirement === 'domain' ? 'example.test' : 'Example Organisation';
@@ -215,15 +84,20 @@ export function formatWorkflowRecipeCatalogue(catalogue) {
         '',
     ].join('\n');
 }
-function step(id, label, command, args, mode, approval, produces, completion) {
-    const invocationEffect = cliInvocationNetworkEffect(command, args);
-    if ((mode === 'network') !== (invocationEffect === 'network')) {
-        throw new Error(`Investigation step ${id} does not match the registered network effect for ${command}.`);
+function validatedSteps(steps) {
+    for (const step of steps) {
+        const invocationEffect = cliInvocationNetworkEffect(step.command, step.arguments);
+        if ((step.mode === 'network') !== (invocationEffect === 'network')) {
+            throw new Error(`Investigation step ${step.id} does not match the registered network effect for ${step.command}.`);
+        }
     }
-    return Object.freeze({ id, label, command, arguments: Object.freeze([...args]), mode, approval, produces, completion });
+    return steps;
 }
 function boundedSubject(value) {
-    if (typeof value !== 'string' || !value.trim() || value.length > 253 || /[\u0000-\u001f\u007f]/u.test(value)) {
+    if (typeof value !== 'string' ||
+        !value.trim() ||
+        value.length > 253 ||
+        /[\u0000-\u001f\u007f]/u.test(value)) {
         throw new TypeError('Investigation-plan subject must be bounded text without control characters.');
     }
     return value.replace(/\s+/gu, ' ').trim();
@@ -232,7 +106,9 @@ function normalizedDomain(value) {
     const candidate = domainToASCII(value.toLowerCase().replace(/\.$/u, ''));
     if (!candidate || candidate.length > 253 || !candidate.includes('.'))
         return null;
-    return candidate.split('.').every((label) => /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/u.test(label))
+    return candidate
+        .split('.')
+        .every((label) => /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/u.test(label))
         ? candidate
         : null;
 }
@@ -241,7 +117,9 @@ export function buildInvestigationPlan(recipeId, subjectValue, generatedAtValue
     if (!recipe)
         throw new TypeError('Investigation-plan recipe is unsupported.');
     const suppliedSubject = boundedSubject(subjectValue);
-    const subject = recipe.subjectRequirement === 'domain' ? normalizedDomain(suppliedSubject) : suppliedSubject.toLowerCase();
+    const subject = recipe.subjectRequirement === 'domain'
+        ? normalizedDomain(suppliedSubject)
+        : suppliedSubject.toLowerCase();
     if (!subject)
         throw new TypeError('This investigation-plan recipe requires one valid domain.');
     const generatedAt = normalizeExplicitIsoTimestamp(generatedAtValue);

package/cli/investigation-recipes.mjs

@@ -0,0 +1,177 @@
+import { CLI_DOMAIN_CONTROL_MONITOR_SCHEMA } from "../packages/contracts/domain-control-monitor.mjs";
+import { DOMAIN_CONTROL_REVIEW_SCHEMA } from "../packages/contracts/domain-control-review.mjs";
+import { EXTERNAL_FINDINGS_SCHEMA } from "../packages/contracts/external-observation-interchange.mjs";
+import { CLI_LOOKUP_BRIEF_SCHEMA } from "../packages/contracts/cli-lookup-brief.mjs";
+export const INVESTIGATION_RECIPE_DEFINITIONS = Object.freeze({
+    'domain-triage': Object.freeze({
+        label: 'New domain triage',
+        standardInputs: Object.freeze([
+            { stepId: 'export', input: 1, sourceStepId: 'collect' },
+            { stepId: 'verify', input: 1, sourceStepId: 'export' },
+        ]),
+        subjectRequirement: 'domain',
+        objective: 'Collect and preserve separately attributed registration, DNS, HTTP, TLS, page, and network-context evidence.',
+        limitations: Object.freeze([
+            'Collection remains analyst-triggered and source limitations remain explicit.',
+            'Disposition, reviewed response actions, monitoring, and closure continue in the saved Case workspace; this CLI recipe does not submit reports.',
+        ]),
+        steps: (domain) => Object.freeze([
+            step('collect', 'Collect a Deep lookup', 'lookup', [domain, '--deep', '--json'], 'network', 'network_disclosure', 'whoisleuth.cli.lookup', 'Review source health and limitations before using missing fields.'),
+            step('export', 'Create a portable evidence report', 'export', ['<saved-lookup.json>'], 'offline', 'analyst_selection', 'whoisleuth.lookup-evidence', 'Reuse the collected Lookup by default, or select a different reviewed Lookup file.'),
+            step('verify', 'Verify the exported artefact', 'verify-artifact', ['<evidence.json>', '--json'], 'offline', 'analyst_selection', 'whoisleuth.offline-artifact-verification', 'Keep verification distinct from a claim that the observations are correct or current.'),
+        ]),
+    }),
+    'lookalike-review': Object.freeze({
+        label: 'Lookalike candidate review',
+        subjectRequirement: 'brand_or_domain',
+        objective: 'Generate a bounded candidate queue, collect only the selected scope, and retain a reviewed candidate lookup.',
+        limitations: Object.freeze([
+            'Candidate generation does not establish registration, control, intent, or maliciousness.',
+            'Official-reference collection and page comparison require analyst-selected saved evidence; use page-compare after retaining the reference and candidate observations.',
+        ]),
+        steps: (subject) => Object.freeze([
+            step('generate', 'Generate candidates offline', 'discover', [subject, '--preset', 'all', '--json'], 'offline', 'none', 'whoisleuth.cli.discover', 'Review mutation families and suppressions before collection.'),
+            step('scan', 'Collect a bounded candidate queue', 'discover-scan', [subject, '--fast', '--scan-limit', '50', '--json'], 'network', 'network_disclosure', 'whoisleuth.cli.discovery-scan', 'Fast collection is a triage boundary; partial or inconclusive authority evidence remains explicit.'),
+            step('inspect', 'Deep-review one selected candidate', 'lookup', ['<selected-domain>', '--deep', '--json'], 'network', 'analyst_selection', 'whoisleuth.cli.lookup', 'Select a candidate deliberately; generation does not prove registration, control, intent, or maliciousness.'),
+        ]),
+    }),
+    'owned-domain-review': Object.freeze({
+        label: 'Owned domain posture review',
+        subjectRequirement: 'domain',
+        objective: 'Review current passive posture and compare supplied observations with an analyst-authored control manifest.',
+        limitations: Object.freeze([
+            'Use only for a domain the analyst owns or is authorised to review.',
+        ]),
+        steps: (domain) => Object.freeze([
+            step('posture', 'Collect bounded DNS posture', 'posture', [domain, '--json'], 'network', 'network_disclosure', 'whoisleuth.cli.posture', 'Review mail profile and delegation evidence before interpreting missing records.'),
+            step('lookup', 'Collect supporting Deep evidence', 'lookup', [domain, '--deep', '--json'], 'network', 'network_disclosure', 'whoisleuth.cli.lookup', 'Retain separately attributed registration, DNS, TLS, and page observations.'),
+            step('manifest', 'Review the domain control manifest', 'domain-control', ['<review-input.json>', '--json'], 'offline', 'analyst_selection', DOMAIN_CONTROL_REVIEW_SCHEMA, 'Only complete supplied observations may produce drift.'),
+        ]),
+    }),
+    'historical-comparison': Object.freeze({
+        label: 'Historical observation comparison',
+        standardInputs: Object.freeze([
+            { stepId: 'diff', input: 2, sourceStepId: 'current' },
+            { stepId: 'timeline', input: 3, sourceStepId: 'current' },
+        ]),
+        subjectRequirement: 'domain',
+        objective: 'Collect a current observation and compare it with analyst-selected saved observations without merging source states.',
+        limitations: Object.freeze([
+            'A later observation does not retroactively refresh retained evidence.',
+        ]),
+        steps: (domain) => Object.freeze([
+            step('current', 'Collect the current lookup', 'lookup', [domain, '--deep', '--json'], 'network', 'network_disclosure', 'whoisleuth.cli.lookup', 'A current request does not refresh or validate older provider-reported history.'),
+            step('diff', 'Compare two selected observations', 'diff', ['<previous.json>', '<current.json>', '--json'], 'offline', 'analyst_selection', 'whoisleuth.cli.lookup-diff', 'Equal, different, conflicting, and unavailable evidence remain separate.'),
+            step('timeline', 'Build a bounded local timeline', 'timeline', ['<oldest.json>', '<newer.json>', '<current.json>', '--json'], 'offline', 'analyst_selection', 'whoisleuth.cli.lookup-timeline', 'Choose two to twenty same-domain files in chronological scope.'),
+        ]),
+    }),
+    'campaign-review': Object.freeze({
+        label: 'Campaign candidate review',
+        subjectRequirement: 'brand_or_domain',
+        objective: 'Prepare a bounded candidate set, collect a deliberately selected queue, and review retained evidence without asserting campaign attribution.',
+        limitations: Object.freeze([
+            'Grouping candidates is analyst triage and does not prove common ownership, control, infrastructure, or intent.',
+        ]),
+        steps: (subject) => Object.freeze([
+            step('prepare', 'Prepare candidates offline', 'discover', [subject, '--preset', 'all', '--json'], 'offline', 'none', 'whoisleuth.cli.discover', 'Review mutation families and bounded omissions before selecting a collection scope.'),
+            step('collect', 'Collect the selected candidate queue', 'discover-scan', [subject, '--fast', '--scan-limit', '50', '--json'], 'network', 'network_disclosure', 'whoisleuth.cli.discovery-scan', 'Treat partial and inconclusive authority results as explicit outcomes.'),
+            step('review', 'Prepare a selected candidate brief', 'brief', ['<saved-lookup.json>', '--json'], 'offline', 'analyst_selection', CLI_LOOKUP_BRIEF_SCHEMA, 'Select a saved candidate Lookup; keep any campaign grouping analyst-authored.'),
+        ]),
+    }),
+    'certificate-anomaly': Object.freeze({
+        label: 'Certificate anomaly review',
+        subjectRequirement: 'domain',
+        objective: 'Review bounded certificate observations alongside current source-qualified domain evidence without treating issuance as proof of control or intent.',
+        limitations: Object.freeze([
+            'Certificate observations are separately attributed and do not establish current service control.',
+        ]),
+        steps: (domain) => Object.freeze([
+            step('search', 'Collect bounded certificate observations', 'ct-search', [domain, '--json'], 'network', 'network_disclosure', 'whoisleuth.cli.ct-search', 'Review source availability, truncation, and observation timing.'),
+            step('intake', 'Normalise the selected observations', 'ct-intake', ['<certificate-events.json>', '--json'], 'offline', 'analyst_selection', EXTERNAL_FINDINGS_SCHEMA, 'Select a certificate-event batch; a certificate-search report is not interchangeable with that input.'),
+            step('corroborate', 'Collect supporting domain evidence', 'lookup', [domain, '--deep', '--json'], 'network', 'network_disclosure', 'whoisleuth.cli.lookup', 'Compare evidence families without collapsing certificate and registration identities.'),
+        ]),
+    }),
+    'registry-disagreement': Object.freeze({
+        label: 'Registry disagreement review',
+        standardInputs: Object.freeze([
+            { stepId: 'compare', input: 1, sourceStepId: 'collect' },
+            { stepId: 'report', input: 1, sourceStepId: 'collect' },
+        ]),
+        subjectRequirement: 'domain',
+        objective: 'Collect separately attributed registration evidence and review conflicting publications without selecting an arbitrary source as truth.',
+        limitations: Object.freeze([
+            'Only authority-aware registration evidence may decide availability; disagreement remains explicit.',
+        ]),
+        steps: (domain) => Object.freeze([
+            step('collect', 'Collect source-qualified registration evidence', 'lookup', [domain, '--deep', '--json'], 'network', 'network_disclosure', 'whoisleuth.cli.lookup', 'Retain RDAP, registrar RDAP, WHOIS, and authority states separately.'),
+            step('compare', 'Compare registry publications offline', 'compare', ['<saved-lookup.json>', '--json'], 'offline', 'analyst_selection', 'whoisleuth.cli.compare', 'Do not convert conflicting or unavailable publications into equivalence.'),
+            step('report', 'Prepare a target-free source report', 'source-report', ['<saved-lookup.json>', '--json'], 'offline', 'analyst_selection', 'whoisleuth.source-reliability-report', 'The report describes source behaviour, not ownership, safety, or legal status.'),
+        ]),
+    }),
+    'evidence-handoff': Object.freeze({
+        label: 'Reviewed evidence handoff',
+        standardInputs: Object.freeze([{ stepId: 'lint', input: 1, sourceStepId: 'package' }]),
+        subjectRequirement: 'review_label',
+        objective: 'Verify, minimise, and package analyst-selected evidence for a deliberate handoff without transmitting or submitting it.',
+        limitations: Object.freeze([
+            'The recipe prepares local material only; sharing remains a separate deliberate action.',
+        ]),
+        steps: () => Object.freeze([
+            step('verify', 'Verify the selected artefact', 'verify-artifact', ['<evidence.json>', '--json', '--strict-exit'], 'offline', 'analyst_selection', 'whoisleuth.offline-artifact-verification', 'Verification checks structure and integrity, not the truth or currency of observations.'),
+            step('package', 'Build a reviewed public Case-pack', 'case-pack', ['<cases.json>', '--audience', 'public', '--reviewed', '--json'], 'offline', 'analyst_selection', 'whoisleuth.cli.case-pack', 'Review minimisation and audience projection before retaining the separate package.'),
+            step('lint', 'Review deliberate-sharing metadata', 'sharing-review', [
+                '<package.json>',
+                '--marking',
+                'clear',
+                '--recipient-scope',
+                'public',
+                '--purpose',
+                'reviewed evidence handoff',
+                '--human-reviewed',
+                '--personal-data-reviewed',
+                '--redactions-confirmed',
+                '--json',
+            ], 'offline', 'analyst_selection', 'whoisleuth.cli.sharing-review', 'A clear lint result does not send, upload, publish, or authorise the artefact.'),
+        ]),
+    }),
+    'planned-domain-change': Object.freeze({
+        label: 'Planned domain change',
+        subjectRequirement: 'domain',
+        objective: 'Review an analyst-authored desired state and prepare bounded change material without changing DNS, registry, mail, or hosted configuration.',
+        limitations: Object.freeze([
+            'Planning and packaging never apply, submit, schedule, or enforce a change.',
+        ]),
+        steps: () => Object.freeze([
+            step('control', 'Review the desired-state manifest', 'domain-control', ['<review-input.json>', '--json'], 'offline', 'analyst_selection', DOMAIN_CONTROL_REVIEW_SCHEMA, 'Only supplied complete observations may produce drift.'),
+            step('assure', 'Review change and recovery assumptions', 'assurance', ['<assurance-input.json>', '--json'], 'offline', 'analyst_selection', 'whoisleuth.domain-assurance', 'Record uncertainty, rollback dependencies, and unavailable evidence explicitly.'),
+            step('package', 'Build a reviewed change packet', 'change-packet', ['<change-packet-input.json>', '--json'], 'offline', 'analyst_selection', 'whoisleuth.domain-change-packet', 'The packet is local reviewed material and performs no submission or enforcement.'),
+        ]),
+    }),
+    'post-change-verification': Object.freeze({
+        label: 'Post-change verification',
+        subjectRequirement: 'domain',
+        objective: 'Perform one explicit later observation and compare it with analyst-selected retained evidence after an authorised change.',
+        limitations: Object.freeze([
+            'This is a one-time recheck, not monitoring setup or proof that every resolver or service has converged.',
+        ]),
+        steps: () => Object.freeze([
+            step('recheck', 'Run one bounded retained-manifest review', 'monitor-once', ['<manifest.json>', '--limit', '1', '--json'], 'network', 'network_disclosure', CLI_DOMAIN_CONTROL_MONITOR_SCHEMA, 'One later observation may remain partial, unavailable, stale, or conflicting.'),
+            step('compare', 'Compare selected before and after evidence', 'diff', ['<before.json>', '<after.json>', '--json'], 'offline', 'analyst_selection', 'whoisleuth.cli.lookup-diff', 'Materiality is derived from compatible retained evidence and does not infer intent.'),
+            step('record', 'Record reviewed completion material', 'change-packet', ['<post-change-input.json>', '--json'], 'offline', 'analyst_selection', 'whoisleuth.domain-change-packet', 'Recording reviewed material does not submit it or start automatic monitoring.'),
+        ]),
+    }),
+});
+export const INVESTIGATION_PLAN_RECIPES = Object.freeze(Object.keys(INVESTIGATION_RECIPE_DEFINITIONS));
+export const RUNNABLE_INVESTIGATION_PLAN_RECIPES = INVESTIGATION_PLAN_RECIPES;
+function step(id, label, command, args, mode, approval, produces, completion) {
+    return Object.freeze({
+        id,
+        label,
+        command,
+        arguments: Object.freeze([...args]),
+        mode,
+        approval,
+        produces,
+        completion,
+    });
+}

package/cli/investigation-run.mjs

@@ -4,8 +4,8 @@ import { buildInvestigationPlan, isRunnableInvestigationRecipe, workflowReviewDe
 import { CliUsageError } from "./errors.mjs";
 import { hasUnsafeCliText } from "./errors.mjs";
 import EXIT_CODES from "./exit-codes.mjs";
-import { scanBoundedJson } from "../lib/bounded-json.mjs";
-import { CLI_INVESTIGATION_RUN_SCHEMA, CLI_INVESTIGATION_RUN_VERSION, SUPPORTED_CLI_INVESTIGATION_RUN_VERSIONS, MAX_INVESTIGATION_RUN_BYTES, MAX_INVESTIGATION_RUN_SELECTIONS, MAX_INVESTIGATION_RUN_SELECTION_LENGTH, } from "../packages/contracts/investigation-run.mjs";
+import { scanBoundedJson } from "../packages/analysis/bounded-json.mjs";
+import { CLI_INVESTIGATION_RUN_SCHEMA, CLI_INVESTIGATION_PREVIEW_SCHEMA, CLI_INVESTIGATION_PREVIEW_VERSION, CLI_INVESTIGATION_RUN_VERSION, SUPPORTED_CLI_INVESTIGATION_RUN_VERSIONS, MAX_INVESTIGATION_RUN_BYTES, MAX_INVESTIGATION_RUN_SELECTIONS, MAX_INVESTIGATION_RUN_SELECTION_LENGTH, } from "../packages/contracts/investigation-run.mjs";
 import { normalizeWorkflowBindings, validateWorkflowResult, workflowArtifactReference, workflowInputSchemas, } from "./investigation-artifacts.mjs";
 export { CLI_INVESTIGATION_RUN_SCHEMA, CLI_INVESTIGATION_RUN_VERSION, SUPPORTED_CLI_INVESTIGATION_RUN_VERSIONS, MAX_INVESTIGATION_RUN_BYTES, MAX_INVESTIGATION_RUN_SELECTIONS, MAX_INVESTIGATION_RUN_SELECTION_LENGTH, };
 const PLACEHOLDER_PATTERN = /^<[^>]+>$/u;
@@ -180,7 +180,7 @@ function validateSelectedInputs(plan, selections, bindings, completed) {
 }
 function parseResumeState(input, plan) {
     if (!input)
-        return Object.freeze({ completed: Object.freeze([]), selections: Object.freeze([]), bindings: Object.freeze([]) });
+        return Object.freeze({ completed: Object.freeze([]), selections: Object.freeze([]), bindings: Object.freeze([]), retryableStepId: null });
     if (Buffer.byteLength(input, 'utf8') > MAX_INVESTIGATION_RUN_BYTES)
         throw new CliUsageError('Investigation resume state exceeds the 24 MiB limit.');
     const normalizedInput = input.replace(/^\uFEFF/u, '');
@@ -222,6 +222,7 @@ function parseResumeState(input, plan) {
         throw new CliUsageError('Investigation resume state contains more steps than the installed fixed recipe.');
     }
     const completed = [];
+    let retryableStepId = null;
     for (const [index, value] of root.completedSteps.entries()) {
         const baseStep = plan.steps[index];
         const planned = baseStep ? selectedStep(baseStep, selectionsByStep.get(baseStep.id) ?? [], bindings, completed) : null;
@@ -251,6 +252,7 @@ function parseResumeState(input, plan) {
             if (index !== root.completedSteps.length - 1) {
                 throw new CliUsageError('A failed investigation step must be the final retained step.');
             }
+            retryableStepId = planned.id;
             break;
         }
         completed.push(Object.freeze({
@@ -265,19 +267,13 @@ function parseResumeState(input, plan) {
         }));
     }
     validateSelectedInputs(plan, selections, bindings, completed);
-    return Object.freeze({ completed: Object.freeze(completed), selections, bindings });
+    return Object.freeze({ completed: Object.freeze(completed), selections, bindings, retryableStepId });
 }
-export async function runInvestigationRecipe(recipe, subjectValue, options) {
+function prepareInvestigationInvocation(recipe, subjectValue, options) {
     if (!isRunnableInvestigationRecipe(recipe)) {
         throw new CliUsageError('workflow-run supports only installed recipes whose exact steps satisfy the execution contract.');
     }
     const plan = buildInvestigationPlan(recipe, subjectValue, options.generatedAt);
-    const confirmedReviews = options.confirmedReviews ?? [];
-    if (!Array.isArray(confirmedReviews) || confirmedReviews.length > plan.steps.length
-        || new Set(confirmedReviews).size !== confirmedReviews.length
-        || confirmedReviews.some(id => !plan.steps.some(step => step.id === id && workflowReviewDeclarations(step).length))) {
-        throw new CliUsageError('--confirm-review must name each selected review-declaration step at most once.');
-    }
     const prior = parseResumeState(options.resumeInput, plan);
     const suppliedSelections = normalizeInvocationSelections(plan, options.selections ?? []);
     // A complete explicit input list replaces a not-yet-run step's standard or
@@ -286,8 +282,78 @@ export async function runInvestigationRecipe(recipe, subjectValue, options) {
         && !prior.completed.some(step => step.id === selection.stepId)).map(selection => selection.stepId));
     const initialBindings = options.resumeInput === null ? workflowStandardInputs(recipe) : prior.bindings;
     const bindings = mergeBindings(plan, initialBindings.filter(binding => !explicitSteps.has(binding.stepId)), normalizeWorkflowBindings(plan, options.artifactBindings ?? []), prior.completed);
-    let selections = mergeSelections(plan, prior.selections, suppliedSelections, prior.completed, bindings);
+    const selections = mergeSelections(plan, prior.selections, suppliedSelections, prior.completed, bindings);
     validateSelectedInputs(plan, selections, bindings, prior.completed);
+    return { plan, prior, bindings, selections };
+}
+/** Validate exactly what execution would resume, without an executor or authority. */
+export function previewInvestigationRecipe(recipe, subjectValue, options) {
+    const { plan, prior, bindings, selections } = prepareInvestigationInvocation(recipe, subjectValue, options);
+    const selected = new Map(selections.map(item => [item.stepId, item.values]));
+    const steps = plan.steps.map(base => {
+        const retained = prior.completed.find(item => item.id === base.id);
+        const step = selectedStep(base, selected.get(base.id) ?? [], bindings, prior.completed);
+        let input = 0;
+        const inputs = base.arguments.flatMap((argument, index) => {
+            if (!PLACEHOLDER_PATTERN.test(argument))
+                return [];
+            input++;
+            const binding = bindings.find(item => item.stepId === base.id && item.input === input);
+            const source = binding ? prior.completed.find(item => item.id === binding.sourceStepId) : undefined;
+            return [{
+                    input, placeholder: argument,
+                    state: binding ? source?.artifact ? 'validated_output' : 'awaiting_output'
+                        : PLACEHOLDER_PATTERN.test(step.arguments[index]) ? 'unresolved' : 'selected_file_or_value',
+                    sourceStepId: binding?.sourceStepId ?? null,
+                    artifactId: source?.artifact?.id ?? null,
+                    value: binding ? null : PLACEHOLDER_PATTERN.test(step.arguments[index]) ? null : step.arguments[index],
+                }];
+        });
+        return {
+            id: step.id, label: step.label, command: step.command, mode: step.mode,
+            state: retained ? retained.exitCode === EXIT_CODES.PARTIAL_FAILURE ? 'retained_partial' : 'retained_complete'
+                : prior.retryableStepId === step.id ? 'retryable_failure' : 'remaining',
+            artifact: retained?.artifact ?? null, inputs,
+            networkApprovalRequired: !retained && step.mode === 'network',
+            reviewDeclarationsRequired: retained ? [] : workflowReviewDeclarations(step),
+            arguments: step.arguments,
+        };
+    });
+    return {
+        schema: CLI_INVESTIGATION_PREVIEW_SCHEMA, version: CLI_INVESTIGATION_PREVIEW_VERSION,
+        generatedAt: options.generatedAt, recipe, subject: plan.subject, steps,
+        requestsExecuted: 0, checkpointWritten: false,
+        limitations: [
+            'This preview validates retained results and connections but does not open selected input files, execute steps, or grant approvals.',
+            'Retained partial observations are reused as partial, not silently recollected. Failed steps remain retryable.',
+            'File paths and selected values are included in this local preview. Review them before sharing.',
+        ],
+    };
+}
+export function formatInvestigationPreview(document) {
+    return [
+        `Workflow preview: ${document.recipe}`, `Subject: ${document.subject}`,
+        'Offline inspection only; no requests or checkpoint writes.',
+        ...document.steps.flatMap(step => [
+            `${step.id}: ${step.state.replaceAll('_', ' ')} · ${step.label}`,
+            ...(step.artifact ? [`  Retained: ${step.artifact.schema} v${step.artifact.version} · ${step.artifact.id}`] : []),
+            ...step.inputs.map(input => `  Input ${input.input}: ${input.state.replaceAll('_', ' ')}${input.sourceStepId ? ` from ${input.sourceStepId}` : ''}${input.value ? ` · ${input.value}` : ''}`),
+            ...(step.networkApprovalRequired ? ['  Requires fresh network approval.'] : []),
+            ...(step.reviewDeclarationsRequired.length ? [`  Requires human review: ${step.reviewDeclarationsRequired.join(', ')}.`] : []),
+        ]),
+        ...document.limitations, '',
+    ].join('\n');
+}
+export async function runInvestigationRecipe(recipe, subjectValue, options) {
+    const prepared = prepareInvestigationInvocation(recipe, subjectValue, options);
+    const { plan, prior, bindings } = prepared;
+    let selections = prepared.selections;
+    const confirmedReviews = options.confirmedReviews ?? [];
+    if (!Array.isArray(confirmedReviews) || confirmedReviews.length > plan.steps.length
+        || new Set(confirmedReviews).size !== confirmedReviews.length
+        || confirmedReviews.some(id => !plan.steps.some(step => step.id === id && workflowReviewDeclarations(step).length))) {
+        throw new CliUsageError('--confirm-review must name each selected review-declaration step at most once.');
+    }
     const selectionsByStep = new Map(selections.map((item) => [item.stepId, item.values]));
     const completed = [...prior.completed];
     let state = completed.some((step) => step.exitCode === EXIT_CODES.PARTIAL_FAILURE) ? 'partial' : 'complete';