@aiwg/cli 2026.9.4 → 2026.9.5

package/dist/src/network-analysis/probe.js

@@ -0,0 +1,405 @@
+import { execFile as execFileCallback } from 'node:child_process';
+import { access, constants, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { promisify } from 'node:util';
+const execFile = promisify(execFileCallback);
+export const NETWORK_ANALYSIS_PROBE_SCHEMA = 'aiwg.network-analysis.probe.v1';
+const TOOL_SPECS = {
+    tshark: {
+        name: 'tshark',
+        required: true,
+        versionArgs: ['-v'],
+        capabilityCommands: [['-h'], ['-G', 'fields'], ['-z', 'help'], ['-F']],
+    },
+    capinfos: {
+        name: 'capinfos',
+        required: true,
+        versionArgs: ['-v'],
+        capabilityCommands: [['-h']],
+    },
+    termshark: {
+        name: 'termshark',
+        required: false,
+        versionArgs: ['--version'],
+        capabilityCommands: [['--help']],
+    },
+};
+export const CURRENT_NETWORK_ANALYSIS_VERSION_POLICY = {
+    verifiedAt: '2026-09-05',
+    wiresharkStable: '4.6.8',
+    wiresharkOldStable: '4.4.18',
+    maintainedBranches: ['4.6', '4.4'],
+    minimumSupportedTshark: '4.4.0',
+    termsharkLatest: '2.4.0',
+    termsharkOptionalRisk: 'aged-release-managed',
+    sources: [
+        'https://www.wireshark.org/download.html',
+        'https://www.wireshark.org/docs/wsug_html_chunked/ChIntroReleaseLifeCycle.html',
+        'https://github.com/gcla/termshark/releases',
+    ],
+};
+export function createDefaultProbeHost() {
+    return {
+        async isExecutable(file) {
+            try {
+                await access(file, constants.X_OK);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+        async run(file, args, limits) {
+            const configRoot = await mkdtemp(path.join(tmpdir(), 'aiwg-network-probe-'));
+            try {
+                const result = await execFile(file, [...args], {
+                    timeout: limits.timeoutMs,
+                    maxBuffer: limits.maxBufferBytes,
+                    killSignal: 'SIGKILL',
+                    shell: false,
+                    env: isolatedProbeEnv(configRoot),
+                });
+                return { exitCode: 0, stdout: result.stdout, stderr: result.stderr };
+            }
+            catch (error) {
+                return {
+                    exitCode: typeof error?.code === 'number' ? error.code : null,
+                    stdout: typeof error?.stdout === 'string' ? error.stdout : '',
+                    stderr: typeof error?.stderr === 'string' ? error.stderr : String(error?.message ?? ''),
+                    timedOut: error?.code !== 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER' && error?.killed === true,
+                    outputLimited: error?.code === 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER',
+                };
+            }
+            finally {
+                await rm(configRoot, { recursive: true, force: true });
+            }
+        },
+    };
+}
+export async function probeNetworkAnalysisTools(options = {}, host = createDefaultProbeHost()) {
+    const tools = {
+        tshark: await probeTool(TOOL_SPECS.tshark, options, host),
+        capinfos: await probeTool(TOOL_SPECS.capinfos, options, host),
+        termshark: await probeTool(TOOL_SPECS.termshark, options, host),
+    };
+    return {
+        schema: NETWORK_ANALYSIS_PROBE_SCHEMA,
+        generatedAt: (options.now ?? (() => new Date()))().toISOString(),
+        status: overallStatus(tools),
+        tools,
+        provenance: {
+            configuredPaths: { ...(options.configuredPaths ?? {}) },
+            trustedSearchPaths: normalizeTrustedSearchPaths(options.trustedSearchPaths ?? []),
+            declaredProfilePaths: explicitAbsoluteList(options.declaredProfilePaths ?? []),
+            declaredConfigPaths: explicitAbsoluteList(options.declaredConfigPaths ?? []),
+            pathPolicy: 'explicit absolute configured paths take precedence; invalid explicit paths fail closed; ambient cwd and user PATH are never searched implicitly',
+            executionPolicy: 'bounded execFile execution only; isolated clean environment; no shell, installs, privilege changes, ambient profiles, user configs, or packet capture',
+            versionPolicy: CURRENT_NETWORK_ANALYSIS_VERSION_POLICY,
+        },
+    };
+}
+async function probeTool(spec, options, host) {
+    const diagnostics = [];
+    const resolved = await resolveExecutable(spec.name, options, host, diagnostics);
+    if (!resolved)
+        return emptyTool(spec, diagnostics);
+    const versionLimits = limitsFor(spec.name, spec.versionArgs);
+    const versionResult = await host.run(resolved.path, spec.versionArgs, versionLimits);
+    const commands = [commandRecord(spec.versionArgs, versionResult, versionLimits)];
+    recordCommandFailure(spec.name, spec.versionArgs, versionResult, diagnostics);
+    const versionOutput = `${versionResult.stdout}\n${versionResult.stderr}`;
+    const version = commandSucceeded(versionResult) ? parseToolVersion(spec.name, versionOutput) : null;
+    if (!version)
+        diagnostics.push(`Could not parse ${spec.name} version output.`);
+    const capabilityOutputs = [];
+    for (const args of spec.capabilityCommands) {
+        const limits = limitsFor(spec.name, args);
+        const result = await host.run(resolved.path, args, limits);
+        commands.push(commandRecord(args, result, limits));
+        capabilityOutputs.push({ args: [...args], output: `${result.stdout}\n${result.stderr}` });
+        recordCommandFailure(spec.name, args, result, diagnostics);
+    }
+    const buildCapabilities = detectBuildCapabilities(versionOutput);
+    const featureDetection = detectFeatures(spec.name, capabilityOutputs);
+    featureDetection.captureFormats = await detectReadCaptureFormats(spec.name, resolved.path, host, commands, diagnostics);
+    const status = classifyTool(spec, version, featureDetection, diagnostics);
+    return {
+        name: spec.name,
+        status,
+        required: spec.required,
+        path: resolved.path,
+        trust: resolved.trust,
+        version,
+        buildCapabilities,
+        featureDetection,
+        commands,
+        diagnostics,
+    };
+}
+async function resolveExecutable(name, options, host, diagnostics) {
+    const explicit = options.configuredPaths?.[name];
+    if (explicit !== undefined) {
+        if (!path.isAbsolute(explicit)) {
+            diagnostics.push(`Configured ${name} path is not absolute: ${explicit}`);
+            return null;
+        }
+        if (!await host.isExecutable(explicit)) {
+            diagnostics.push(`Configured ${name} path is not executable or does not exist: ${explicit}`);
+            return null;
+        }
+        return { path: explicit, trust: 'explicit-config' };
+    }
+    for (const directory of normalizeTrustedSearchPaths(options.trustedSearchPaths ?? [])) {
+        const candidate = path.join(directory, name);
+        if (await host.isExecutable(candidate))
+            return { path: candidate, trust: 'trusted-search-path' };
+    }
+    diagnostics.push(`No trusted executable found for ${name}.`);
+    return null;
+}
+function normalizeTrustedSearchPaths(paths) {
+    return paths.filter(path.isAbsolute);
+}
+function explicitAbsoluteList(paths) {
+    return paths.filter(path.isAbsolute);
+}
+function emptyTool(spec, diagnostics) {
+    return {
+        name: spec.name,
+        status: 'missing',
+        required: spec.required,
+        path: null,
+        trust: null,
+        version: null,
+        buildCapabilities: [],
+        featureDetection: {
+            outputFormats: [],
+            statistics: [],
+            fields: [],
+            captureFormats: [],
+            writeFormats: [],
+        },
+        commands: [],
+        diagnostics,
+    };
+}
+function commandRecord(args, result, limits) {
+    return {
+        args: [...args],
+        exitCode: result.exitCode,
+        timedOut: result.timedOut === true,
+        outputLimited: result.outputLimited === true,
+        maxBufferBytes: limits.maxBufferBytes,
+    };
+}
+function limitsFor(name, args) {
+    if (name === 'tshark' && args.join(' ') === '-G fields') {
+        return { timeoutMs: 10000, maxBufferBytes: 32 * 1024 * 1024 };
+    }
+    if (name === 'tshark' && args.join(' ') === '-z help') {
+        return { timeoutMs: 5000, maxBufferBytes: 4 * 1024 * 1024 };
+    }
+    return { timeoutMs: 3000, maxBufferBytes: 2 * 1024 * 1024 };
+}
+function isolatedProbeEnv(configRoot) {
+    return {
+        XDG_CONFIG_HOME: configRoot,
+        WIRESHARK_CONFIG_DIR: configRoot,
+        TERM: 'dumb',
+        LANG: 'C',
+        LC_ALL: 'C',
+        PATH: '',
+    };
+}
+async function detectReadCaptureFormats(name, executable, host, commands, diagnostics) {
+    if (name === 'termshark')
+        return [];
+    const smokeRoot = await mkdtemp(path.join(tmpdir(), 'aiwg-network-capture-smoke-'));
+    try {
+        const captures = [
+            { format: 'pcap', file: path.join(smokeRoot, 'empty.pcap'), content: emptyPcap() },
+            { format: 'pcapng', file: path.join(smokeRoot, 'empty.pcapng'), content: emptyPcapng() },
+        ];
+        await Promise.all(captures.map(capture => writeFile(capture.file, capture.content)));
+        const supported = [];
+        for (const capture of captures) {
+            const args = name === 'tshark' ? ['-r', capture.file, '-q'] : [capture.file];
+            const limits = limitsFor(name, ['read-smoke']);
+            const result = await host.run(executable, args, limits);
+            commands.push(commandRecord(args, result, limits));
+            recordCommandFailure(name, args, result, diagnostics);
+            if (commandSucceeded(result))
+                supported.push(capture.format);
+        }
+        return supported;
+    }
+    finally {
+        await rm(smokeRoot, { recursive: true, force: true });
+    }
+}
+function emptyPcap() {
+    return Buffer.from([
+        0xd4, 0xc3, 0xb2, 0xa1,
+        0x02, 0x00,
+        0x04, 0x00,
+        0x00, 0x00, 0x00, 0x00,
+        0x00, 0x00, 0x00, 0x00,
+        0xff, 0xff, 0x00, 0x00,
+        0x01, 0x00, 0x00, 0x00,
+    ]);
+}
+function emptyPcapng() {
+    return Buffer.from([
+        0x0a, 0x0d, 0x0d, 0x0a,
+        0x1c, 0x00, 0x00, 0x00,
+        0x4d, 0x3c, 0x2b, 0x1a,
+        0x01, 0x00,
+        0x00, 0x00,
+        0xff, 0xff, 0xff, 0xff,
+        0xff, 0xff, 0xff, 0xff,
+        0x1c, 0x00, 0x00, 0x00,
+    ]);
+}
+function parseToolVersion(name, output) {
+    const patterns = {
+        tshark: [/\bTShark \(Wireshark\) ([0-9]+(?:\.[0-9]+){1,2})\b/i, /\bTShark ([0-9]+(?:\.[0-9]+){1,2})\b/i],
+        capinfos: [/\bCapinfos \(Wireshark\) ([0-9]+(?:\.[0-9]+){1,2})\b/i, /\bCapinfos ([0-9]+(?:\.[0-9]+){1,2})\b/i],
+        termshark: [/\btermshark v?([0-9]+(?:\.[0-9]+){1,2})\b/i],
+    };
+    for (const pattern of patterns[name]) {
+        const match = output.match(pattern);
+        if (match?.[1])
+            return match[1];
+    }
+    return null;
+}
+function detectBuildCapabilities(output) {
+    const capabilities = new Set();
+    const checks = [
+        ['libpcap', /\bwith libpcap\b/i],
+        ['nghttp2', /\bwith nghttp2\b/i],
+        ['brotli', /\bwith brotli\b/i],
+        ['zstd', /\bwith zstd\b/i],
+        ['lua', /\bwith Lua\b/],
+        ['gnutls', /\bwith GnuTLS\b/],
+        ['maxminddb', /\bwith MaxMind DB\b/i],
+    ];
+    for (const [capability, pattern] of checks) {
+        if (pattern.test(output))
+            capabilities.add(capability);
+    }
+    return [...capabilities].sort();
+}
+function detectFeatures(name, outputs) {
+    const outputFor = (args) => outputs
+        .filter(item => item.args.join(' ') === args.join(' '))
+        .map(item => item.output)
+        .join('\n');
+    return {
+        outputFormats: name === 'tshark' ? detectOutputFormats(outputFor(['-h'])) : [],
+        statistics: name === 'tshark' ? detectStatistics(outputFor(['-z', 'help'])) : [],
+        fields: name === 'tshark' ? detectFields(outputFor(['-G', 'fields'])) : [],
+        captureFormats: [],
+        writeFormats: name === 'tshark' ? detectFormats(outputFor(['-F'])) : [],
+    };
+}
+function detectOutputFormats(output) {
+    return uniqueMatches(output, /\b(?:ek|fields|json|jsonraw|pdml|ps|psml|tabs|text)\b/g);
+}
+function detectStatistics(output) {
+    return uniqueMatches(output, /\b(?:conv|endpoints|io,stat|protocols|expert|flow|http|http2|dns|icmp|udp|tcp)\b/g);
+}
+function detectFields(output) {
+    const fields = new Set();
+    for (const line of output.split(/\r?\n/)) {
+        const columns = line.split('\t');
+        if (columns[0] === 'F' && columns[2])
+            fields.add(columns[2]);
+    }
+    return [...fields].sort();
+}
+function detectFormats(output) {
+    const formats = new Set();
+    for (const token of uniqueMatches(output, /\b(?:pcapng|pcap|erf|snoop|ngsniffer|netmon|libpcap|modpcap)\b/gi)) {
+        formats.add(token.toLowerCase());
+    }
+    return [...formats].sort();
+}
+function commandSucceeded(result) {
+    return result.exitCode === 0 && result.timedOut !== true && result.outputLimited !== true;
+}
+function recordCommandFailure(name, args, result, diagnostics) {
+    const command = `${name} ${args.map(arg => path.basename(arg) === arg ? arg : '<temp>').join(' ')}`;
+    if (result.timedOut)
+        diagnostics.push(`${command} timed out.`);
+    if (result.outputLimited)
+        diagnostics.push(`${command} exceeded the output limit.`);
+    if (result.exitCode !== 0 && !isExpectedNonZeroCommand(name, args)) {
+        diagnostics.push(`${command} exited with code ${result.exitCode ?? 'unknown'}.`);
+    }
+}
+function isExpectedNonZeroCommand(name, args) {
+    return name === 'tshark' && args.join(' ') === '-F';
+}
+function uniqueMatches(output, pattern) {
+    return [...new Set([...output.matchAll(pattern)].map(match => match[0]))].sort();
+}
+function classifyTool(spec, version, features, diagnostics) {
+    if (!version)
+        return 'unsupported';
+    if (diagnostics.some(diagnostic => /exited with code|timed out|exceeded the output limit/.test(diagnostic))) {
+        return 'partially_capable';
+    }
+    if (spec.name === 'termshark')
+        return version === CURRENT_NETWORK_ANALYSIS_VERSION_POLICY.termsharkLatest
+            ? 'supported'
+            : 'partially_capable';
+    if (!CURRENT_NETWORK_ANALYSIS_VERSION_POLICY.maintainedBranches.some(branch => version.startsWith(`${branch}.`))) {
+        diagnostics.push(`${spec.name} ${version} is outside the maintained Wireshark branches.`);
+        return 'unsupported';
+    }
+    const missingRequiredFeatures = spec.name === 'tshark'
+        ? requiredTsharkFeaturesMissing(features)
+        : requiredCapinfosFeaturesMissing(features);
+    if (missingRequiredFeatures.length > 0) {
+        diagnostics.push(`Missing feature detections: ${missingRequiredFeatures.join(', ')}.`);
+        return 'partially_capable';
+    }
+    return 'supported';
+}
+function requiredTsharkFeaturesMissing(features) {
+    const missing = [];
+    for (const format of ['json', 'fields']) {
+        if (!features.outputFormats.includes(format))
+            missing.push(`output:${format}`);
+    }
+    if (!features.statistics.includes('conv'))
+        missing.push('statistics:conv');
+    if (!features.fields.includes('frame.time_epoch'))
+        missing.push('field:frame.time_epoch');
+    for (const format of ['pcap', 'pcapng']) {
+        if (!features.captureFormats.includes(format))
+            missing.push(`capture-read:${format}`);
+    }
+    return missing;
+}
+function requiredCapinfosFeaturesMissing(features) {
+    const missing = [];
+    for (const format of ['pcap', 'pcapng']) {
+        if (!features.captureFormats.includes(format))
+            missing.push(`capture-read:${format}`);
+    }
+    return missing;
+}
+function overallStatus(tools) {
+    const required = [tools.tshark, tools.capinfos];
+    if (required.some(tool => tool.status === 'missing'))
+        return 'missing';
+    if (required.some(tool => tool.status === 'unsupported'))
+        return 'unsupported';
+    if (required.some(tool => tool.status === 'partially_capable'))
+        return 'partially_capable';
+    return 'supported';
+}
+//# sourceMappingURL=probe.js.map

package/dist/src/network-analysis/recipes.js

@@ -0,0 +1,88 @@
+import semver from 'semver';
+export const ANALYSIS_RECIPE_SCHEMA_VERSION = 'network-analysis.analysis-recipe/v1';
+export class RecipeCompatibilityError extends Error {
+    diagnostics;
+    constructor(message, diagnostics) {
+        super(message);
+        this.name = 'RecipeCompatibilityError';
+        this.diagnostics = diagnostics;
+    }
+}
+export function compileAnalysisRecipe(document, capability) {
+    assertRecipeIdentity(document);
+    const diagnostics = [];
+    const tshark = document.compatibility.minimum_tools.find(tool => tool.name === 'tshark');
+    if (!tshark?.required)
+        throw new RecipeCompatibilityError('Recipe must require TShark.', ['Missing required TShark compatibility entry.']);
+    if (!semver.valid(capability.tsharkVersion) || !semver.satisfies(capability.tsharkVersion, tshark.version_range, { includePrerelease: true })) {
+        throw new RecipeCompatibilityError(`TShark ${capability.tsharkVersion} is incompatible with ${document.recipe_id}.`, [`Install a maintained TShark matching ${tshark.version_range}; unsupported major versions fail closed.`]);
+    }
+    if (document.filters.capture_filters.length > 0) {
+        throw new RecipeCompatibilityError('Offline recipes cannot apply capture filters after collection.', [
+            'Select a saved capture and use only Wireshark display filters during analysis.',
+        ]);
+    }
+    const available = new Set(capability.availableFields);
+    const fallbackByField = new Map((document.compatibility.field_fallbacks ?? []).map(fallback => [fallback.field, fallback]));
+    const selectedFields = [];
+    const usedFallbacks = [];
+    for (const request of document.requested_output.fields) {
+        if (available.has(request.name)) {
+            selectedFields.push(request.name);
+            continue;
+        }
+        const fallback = fallbackByField.get(request.name);
+        if (fallback?.behavior === 'use-fallback' && fallback.fallback_field && available.has(fallback.fallback_field)) {
+            selectedFields.push(fallback.fallback_field);
+            diagnostics.push(`${fallback.diagnostic} Selected ${fallback.fallback_field}.`);
+            usedFallbacks.push({ field: request.name, replacement: fallback.fallback_field });
+            continue;
+        }
+        if (!request.required && fallback?.behavior !== 'fail-required') {
+            diagnostics.push(fallback?.diagnostic ?? `Optional field ${request.name} is unavailable and was omitted.`);
+            usedFallbacks.push({ field: request.name });
+            continue;
+        }
+        throw new RecipeCompatibilityError(`Required field ${request.name} is unavailable for ${document.recipe_id}.`, [
+            fallback?.diagnostic ?? `Probe TShark fields and select a compatible recipe version; ${request.name} has no declared fallback.`,
+        ]);
+    }
+    const displayFilter = document.filters.display_filters.map(filter => `(${filter.expression})`).join(' && ');
+    return {
+        recipe: {
+            id: document.recipe_id.replace(/^analysis-recipe:/, ''),
+            version: document.version,
+            ...(displayFilter ? { displayFilter } : {}),
+            fields: [...new Set(selectedFields)],
+        },
+        limits: {
+            inputBytes: document.limits.max_capture_bytes,
+            packets: document.limits.max_frames,
+            outputBytes: document.limits.max_output_bytes,
+            timeoutMs: document.limits.max_duration_seconds * 1000,
+        },
+        sensitivity: document.sensitivity,
+        statistics: document.requested_output.statistics,
+        interpretation: document.interpretation,
+        diagnostics,
+        provenance: {
+            recipeId: document.recipe_id,
+            recipeVersion: document.version,
+            toolVersion: capability.tsharkVersion,
+            selectedFields: [...new Set(selectedFields)],
+            displayFilter,
+            fallbacks: usedFallbacks,
+        },
+    };
+}
+function assertRecipeIdentity(document) {
+    if (document.schema_version !== ANALYSIS_RECIPE_SCHEMA_VERSION || document.kind !== 'AnalysisRecipe'
+        || document.compatibility.contract !== ANALYSIS_RECIPE_SCHEMA_VERSION
+        || document.compatibility.unsupported_major_policy !== 'fail-closed') {
+        throw new RecipeCompatibilityError('Unsupported analysis recipe contract.', ['Use network-analysis.analysis-recipe/v1; unsupported major versions fail closed.']);
+    }
+    if (!/^analysis-recipe:[A-Za-z0-9][A-Za-z0-9._-]*$/.test(document.recipe_id) || !semver.valid(document.version)) {
+        throw new RecipeCompatibilityError('Recipe identity or version is invalid.', ['Use a scoped recipe_id and semantic version.']);
+    }
+}
+//# sourceMappingURL=recipes.js.map

package/dist/src/network-analysis/research.js

@@ -0,0 +1,181 @@
+import { formatEvidenceCitation, validateEvidenceReferences } from './citations.js';
+import { assertLocalOutputAllowed } from './governance.js';
+export const RESEARCH_PACKET_SOURCE_SCHEMA = 'aiwg.research.packet-evidence-source.v1';
+export function inductPacketEvidenceSource(input) {
+    validateResearchInput(input);
+    validateEvidenceReferences(input.evidence);
+    const captureDigest = String(input.evidence.capture.capture_digest);
+    const rawCapture = rawCaptureDecision(input.evidence, input.rawCaptureApproval);
+    const timestamps = frameTimestampIndex(input.evidence);
+    const analysisContexts = (input.evidence.capture.analysis_contexts ?? []).map(context => ({
+        contextDigest: requiredString(context.context_digest, 'Analysis context digest'),
+        tool: {
+            name: requiredString(context.tool?.name, 'Analysis tool name'),
+            version: requiredString(context.tool?.version, 'Analysis tool version'),
+            executablePath: requiredString(context.tool?.executable_path, 'Analysis tool path'),
+        },
+        profile: requiredString(context.profile, 'Analysis profile'),
+        displayFilterDigest: requiredString(context.display_filter_digest, 'Display-filter digest'),
+        captureFilterDigest: requiredString(context.capture_filter_digest, 'Capture-filter digest'),
+        configDigests: stringArray(context.config_digests, 'Config digests'),
+        commandArgv: stringArray(context.command_argv, 'Analysis argv'),
+    }));
+    const claims = input.evidence.evidence_items.map((item, index) => researchClaim(item, index, timestamps));
+    const provenance = input.evidence.provenance;
+    const limitations = [
+        `Capture analysis status: ${input.evidence.status}`,
+        `Representativeness: ${input.collection.representativeness}`,
+        `Clock source: ${input.collection.clockSource}; source timezone: ${input.collection.timezone}`,
+        `Missing traffic: ${input.collection.missingTraffic}`,
+        `Encryption visibility: ${input.collection.encryptionVisibility}`,
+        ...input.collection.analystLimitations.map(value => `Analyst limitation: ${value}`),
+    ];
+    return {
+        schema: RESEARCH_PACKET_SOURCE_SCHEMA,
+        refId: input.refId,
+        title: input.title.trim(),
+        sourceType: 'packet-evidence',
+        scholarlyClassification: 'non-scholarly-observational-evidence',
+        quality: {
+            grade: 'not-applicable',
+            framework: 'packet-evidence-limitations',
+            reason: 'GRADE study ratings do not apply to a collected network trace; assess authority, integrity, scope, and limitations instead.',
+        },
+        evidenceBundle: {
+            bundleId: input.evidence.bundle_id,
+            status: input.evidence.status,
+            captureDigest,
+            createdAt: input.evidence.created_at,
+        },
+        collection: structuredClone(input.collection),
+        analysisContexts,
+        derivedArtifacts: input.evidence.artifacts.map(sanitizeDerivedArtifact),
+        rawCapture,
+        claims,
+        provenance: {
+            actor: requiredString(provenance.actor, 'Provenance actor'),
+            activity: requiredString(provenance.activity, 'Provenance activity'),
+            startedAt: requiredString(provenance.started_at, 'Provenance start'),
+            endedAt: requiredString(provenance.ended_at, 'Provenance end'),
+            recipeId: requiredString(provenance.recipe_id, 'Provenance recipe'),
+            authorizationRefs: stringArray(provenance.authorization_refs, 'Authorization references'),
+        },
+        limitations,
+    };
+}
+function sanitizeDerivedArtifact(artifact) {
+    const handling = artifact.data_handling;
+    return {
+        artifactId: requiredString(artifact.artifact_id, 'Derived artifact ID'),
+        mediaType: requiredString(artifact.media_type, 'Derived artifact media type'),
+        uri: requiredString(artifact.uri, 'Derived artifact URI'),
+        digest: {
+            algorithm: requiredString(artifact.digest?.algorithm, 'Derived artifact digest algorithm'),
+            value: requiredString(artifact.digest?.value, 'Derived artifact digest value'),
+        },
+        dataHandling: {
+            sensitivity: requiredString(handling?.sensitivity, 'Derived artifact sensitivity'),
+            payloadContent: requiredString(handling?.payload_content, 'Derived artifact payload declaration'),
+            redaction: {
+                state: requiredString(handling?.redaction?.state, 'Derived artifact redaction state'),
+                method: requiredString(handling?.redaction?.method, 'Derived artifact redaction method'),
+                redactedFields: stringArray(handling?.redaction?.redacted_fields, 'Derived artifact redacted fields'),
+            },
+            retentionClass: requiredString(handling?.retention?.class, 'Derived artifact retention class'),
+            disclosureState: requiredString(handling?.disclosure?.state, 'Derived artifact disclosure state'),
+            allowedAudiences: stringArray(handling?.disclosure?.allowed_audiences, 'Derived artifact allowed audiences'),
+        },
+    };
+}
+function researchClaim(item, index, timestamps) {
+    const basis = requiredString(item.basis, `Evidence item ${index + 1} basis`);
+    if (basis !== 'observation' && basis !== 'inference')
+        throw new Error(`Evidence item ${index + 1} must distinguish observation from inference`);
+    const citations = item.citations.map(citation => {
+        const frame = citation.locator.type === 'frame' ? citation.locator.frame_number : frameForStream(item.citations);
+        const observedAt = frame === null ? null : timestamps.get(frame) ?? null;
+        return {
+            citation: formatEvidenceCitation(citation),
+            captureDigest: citation.capture_digest,
+            locator: structuredClone(citation.locator),
+            observedAt,
+            timeBasis: observedAt === null ? 'not-recorded' : 'capture-frame-time-utc',
+        };
+    });
+    return {
+        claimId: requiredString(item.evidence_id, `Evidence item ${index + 1} ID`),
+        kind: basis,
+        statement: requiredString(item.statement, `Evidence item ${index + 1} statement`),
+        confidence: requiredString(item.confidence, `Evidence item ${index + 1} confidence`),
+        citations,
+        inferenceInputs: basis === 'inference' ? stringArray(item.inference?.inputs, 'Inference inputs') : [],
+    };
+}
+function rawCaptureDecision(evidence, approval) {
+    if (!approval)
+        return { included: false };
+    const captureDigest = String(evidence.capture.capture_digest);
+    if (!approval.approvalRef.trim() || !approval.approvedBy.trim() || !approval.basis.trim() || approval.captureDigest !== captureDigest) {
+        throw new Error('Raw capture research inclusion requires an exact, complete approval record');
+    }
+    assertLocalOutputAllowed(approval.policy, { content: ['metadata', 'raw-packets'], payloadOptIn: approval.payloadOptIn });
+    return {
+        included: true,
+        digest: captureDigest,
+        sourceUri: requiredString(evidence.capture.source_uri, 'Capture source URI'),
+        approvalRef: approval.approvalRef,
+        approvedBy: approval.approvedBy,
+        basis: approval.basis,
+    };
+}
+function frameTimestampIndex(evidence) {
+    const result = new Map();
+    for (const item of evidence.evidence_items) {
+        const fields = Array.isArray(item.observed_fields) ? item.observed_fields : [];
+        const frame = Number(fields.find(field => field.name === 'frame.number')?.value);
+        const epoch = Number(fields.find(field => field.name === 'frame.time_epoch')?.value);
+        if (Number.isSafeInteger(frame) && frame > 0 && Number.isFinite(epoch) && epoch >= 0) {
+            result.set(frame, new Date(epoch * 1000).toISOString());
+        }
+    }
+    return result;
+}
+function frameForStream(citations) {
+    const frame = citations.find(citation => citation.locator.type === 'frame');
+    return frame?.locator.type === 'frame' ? frame.locator.frame_number : null;
+}
+function validateResearchInput(input) {
+    if (!/^REF-[0-9]{3,}$/.test(input.refId))
+        throw new Error('Packet evidence research source requires a REF-NNN identifier');
+    requiredString(input.title, 'Research source title');
+    if (input.evidence.kind !== 'PacketEvidenceBundle' || input.evidence.status === 'error') {
+        throw new Error('Research induction requires a usable PacketEvidenceBundle');
+    }
+    for (const [label, value] of Object.entries({
+        owner: input.collection.owner,
+        authority: input.collection.authorityRef,
+        purpose: input.collection.purpose,
+        representativeness: input.collection.representativeness,
+        clock: input.collection.clockSource,
+        timezone: input.collection.timezone,
+        missingTraffic: input.collection.missingTraffic,
+        encryption: input.collection.encryptionVisibility,
+    }))
+        requiredString(value, `Collection ${label}`);
+    if (!Array.isArray(input.collection.analystLimitations) || input.collection.analystLimitations.length === 0) {
+        throw new Error('At least one analyst limitation is required');
+    }
+    stringArray(input.collection.analystLimitations, 'Analyst limitations');
+}
+function requiredString(value, label) {
+    if (typeof value !== 'string' || !value.trim() || value.includes('\0'))
+        throw new Error(`${label} is required`);
+    return value;
+}
+function stringArray(value, label) {
+    if (!Array.isArray(value) || value.some(item => typeof item !== 'string' || !item.trim() || item.includes('\0'))) {
+        throw new Error(`${label} must contain non-empty strings`);
+    }
+    return [...value];
+}
+//# sourceMappingURL=research.js.map