@bbigbang/core 0.1.0

package/dist/services/nativeMissionReportGenerator.js

@@ -0,0 +1,227 @@
+import { writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+export const NATIVE_MISSION_REPORT_FILE_NAME = 'mission-report.md';
+/**
+ * Generates a Markdown mission report from native mission data and writes it
+ * to the mission directory. The report is intended to be human-readable and
+ * includes a mission summary, feature list, validation results, handoffs, and
+ * a timeline of key events.
+ */
+export function generateNativeMissionReport(missionDir, input) {
+    if (!existsSync(missionDir)) {
+        mkdirSync(missionDir, { recursive: true });
+    }
+    const reportText = renderNativeMissionReport(input);
+    const reportPath = join(missionDir, NATIVE_MISSION_REPORT_FILE_NAME);
+    writeFileSync(reportPath, reportText, 'utf8');
+    return { reportPath, sizeBytes: Buffer.byteLength(reportText, 'utf8') };
+}
+function renderNativeMissionReport(input) {
+    const { mission, features, assertions, events } = input;
+    const featureStatusCounts = countBy(features.map((f) => f.status));
+    const assertionStatusCounts = countBy(assertions.map((a) => a.status));
+    const handoffFeatures = features.filter((f) => f.handoff != null);
+    const lines = [];
+    lines.push(`# Mission Report: ${mission.title}`);
+    lines.push('');
+    lines.push(`- **Mission ID:** \`${mission.missionId}\``);
+    lines.push(`- **State:** ${mission.state}`);
+    lines.push(`- **Runtime Provider:** ${mission.runtimeProvider}`);
+    lines.push(`- **Workspace:** \`${mission.workspacePath}\``);
+    lines.push(`- **Model Mode:** ${mission.modelMode}`);
+    if (mission.startedAt) {
+        lines.push(`- **Started At:** ${formatTimestamp(mission.startedAt)}`);
+    }
+    if (mission.completedAt) {
+        lines.push(`- **Completed At:** ${formatTimestamp(mission.completedAt)}`);
+    }
+    lines.push('');
+    lines.push('## Summary');
+    lines.push('');
+    lines.push(`- **Features:** ${features.length} total`);
+    lines.push(`  - Completed: ${featureStatusCounts.completed ?? 0}`);
+    lines.push(`  - Failed: ${featureStatusCounts.failed ?? 0}`);
+    lines.push(`  - Skipped: ${featureStatusCounts.skipped ?? 0}`);
+    lines.push(`  - Cancelled: ${featureStatusCounts.cancelled ?? 0}`);
+    lines.push(`  - Pending: ${featureStatusCounts.pending ?? 0}`);
+    lines.push(`- **Validation Assertions:** ${assertions.length} total`);
+    lines.push(`  - Passed: ${assertionStatusCounts.passed ?? 0}`);
+    lines.push(`  - Failed: ${assertionStatusCounts.failed ?? 0}`);
+    lines.push(`  - Blocked: ${assertionStatusCounts.blocked ?? 0}`);
+    lines.push(`  - Pending: ${assertionStatusCounts.pending ?? 0}`);
+    lines.push(`- **Handoffs:** ${handoffFeatures.length}`);
+    lines.push('');
+    if (mission.description) {
+        lines.push('## Mission Brief');
+        lines.push('');
+        lines.push(mission.description);
+        lines.push('');
+    }
+    lines.push('## Features');
+    lines.push('');
+    if (features.length === 0) {
+        lines.push('*No features were parsed from the mission brief.*');
+        lines.push('');
+    }
+    else {
+        const featuresByMilestone = groupBy(features, (f) => f.milestone);
+        for (const [milestone, milestoneFeatures] of featuresByMilestone) {
+            lines.push(`### ${milestone}`);
+            lines.push('');
+            for (const feature of milestoneFeatures.sort((a, b) => a.ordering - b.ordering)) {
+                lines.push(`#### ${feature.description.split(/\r?\n/)[0] ?? feature.description}`);
+                lines.push('');
+                lines.push(`- **Status:** ${feature.status}`);
+                lines.push(`- **Feature ID:** \`${feature.featureId}\``);
+                if (feature.skillName) {
+                    lines.push(`- **Skill:** ${feature.skillName}`);
+                }
+                if (feature.preconditions.length > 0) {
+                    lines.push(`- **Preconditions:**`);
+                    for (const precondition of feature.preconditions) {
+                        lines.push(`  - ${precondition}`);
+                    }
+                }
+                if (feature.expectedBehavior.length > 0) {
+                    lines.push(`- **Expected Behavior:**`);
+                    for (const expected of feature.expectedBehavior) {
+                        lines.push(`  - ${expected}`);
+                    }
+                }
+                lines.push('');
+            }
+        }
+    }
+    lines.push('## Validation Results');
+    lines.push('');
+    if (assertions.length === 0) {
+        lines.push('*No validation assertions were generated.*');
+        lines.push('');
+    }
+    else {
+        const assertionsByFeature = groupBy(assertions, (a) => a.featureId ?? 'unknown');
+        for (const [featureId, featureAssertions] of assertionsByFeature) {
+            const feature = features.find((f) => f.featureId === featureId);
+            if (feature) {
+                lines.push(`### ${feature.description.split(/\r?\n/)[0] ?? feature.description}`);
+            }
+            else {
+                lines.push(`### Feature ID: \`${featureId}\``);
+            }
+            lines.push('');
+            for (const assertion of featureAssertions) {
+                lines.push(`- **${assertion.status.toUpperCase()}:** ${assertion.assertionText}`);
+                if (assertion.note) {
+                    lines.push(`  - *Note:* ${assertion.note}`);
+                }
+                if (assertion.evidence) {
+                    lines.push(`  - *Evidence:* ${assertion.evidence}`);
+                }
+            }
+            lines.push('');
+        }
+    }
+    lines.push('## Handoffs');
+    lines.push('');
+    if (handoffFeatures.length === 0) {
+        lines.push('*No worker handoffs were recorded.*');
+        lines.push('');
+    }
+    else {
+        for (const feature of handoffFeatures) {
+            const handoff = feature.handoff ?? {};
+            lines.push(`### ${feature.description.split(/\r?\n/)[0] ?? feature.description}`);
+            lines.push('');
+            const summary = typeof handoff.salientSummary === 'string' ? handoff.salientSummary : null;
+            if (summary) {
+                lines.push(summary);
+                lines.push('');
+            }
+            if (handoff.verification && typeof handoff.verification === 'object') {
+                lines.push(`- **Verification:** \`${JSON.stringify(handoff.verification)}\``);
+            }
+            if (Array.isArray(handoff.discoveredIssues) && handoff.discoveredIssues.length > 0) {
+                lines.push('- **Discovered Issues:**');
+                for (const issue of handoff.discoveredIssues) {
+                    lines.push(`  - ${String(issue)}`);
+                }
+            }
+            lines.push('');
+        }
+    }
+    lines.push('## Timeline');
+    lines.push('');
+    const lifecycleEvents = events.filter((e) => isLifecycleEventType(e.eventType));
+    if (lifecycleEvents.length === 0) {
+        lines.push('*No lifecycle events recorded.*');
+        lines.push('');
+    }
+    else {
+        for (const event of lifecycleEvents) {
+            const time = formatTimestamp(event.eventTime);
+            lines.push(`- **${time}** \`${event.eventType}\` (${event.source})`);
+            const payloadSummary = summarizePayload(event.payload);
+            if (payloadSummary) {
+                lines.push(`  - ${payloadSummary}`);
+            }
+        }
+        lines.push('');
+    }
+    lines.push('---');
+    lines.push('');
+    lines.push(`*Report generated by Bigbang Native Mission Runtime.*`);
+    lines.push('');
+    return lines.join('\n');
+}
+function isLifecycleEventType(eventType) {
+    return (eventType.startsWith('mission_') ||
+        eventType.startsWith('feature_') ||
+        eventType === 'validation_started' ||
+        eventType === 'validation_completed');
+}
+function summarizePayload(payload) {
+    const parts = [];
+    if (typeof payload.featureId === 'string') {
+        parts.push(`featureId=${payload.featureId}`);
+    }
+    if (typeof payload.milestone === 'string') {
+        parts.push(`milestone=${payload.milestone}`);
+    }
+    if (typeof payload.exitCode === 'number') {
+        parts.push(`exitCode=${payload.exitCode}`);
+    }
+    if (typeof payload.error === 'string') {
+        parts.push(`error=${payload.error}`);
+    }
+    if (typeof payload.reason === 'string') {
+        parts.push(`reason=${payload.reason}`);
+    }
+    if (parts.length === 0)
+        return null;
+    return parts.join(', ');
+}
+function formatTimestamp(timestamp) {
+    try {
+        return new Date(timestamp).toISOString();
+    }
+    catch {
+        return String(timestamp);
+    }
+}
+function countBy(items) {
+    const counts = {};
+    for (const item of items) {
+        counts[item] = (counts[item] ?? 0) + 1;
+    }
+    return counts;
+}
+function groupBy(items, keyFn) {
+    const groups = new Map();
+    for (const item of items) {
+        const key = keyFn(item);
+        const list = groups.get(key) ?? [];
+        list.push(item);
+        groups.set(key, list);
+    }
+    return groups;
+}

package/dist/services/nativeMissionValidationRunner.js

@@ -0,0 +1,452 @@
+const DEFAULT_TIMEOUT_MS = 60_000;
+const DEFAULT_POLICY = 'continueOnWarning';
+export class NativeMissionValidationRunner {
+    missionService;
+    defaultTimeoutMs;
+    defaultPolicy;
+    evaluator;
+    constructor(params) {
+        this.missionService = params.missionService;
+        this.defaultTimeoutMs = params.defaultTimeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.defaultPolicy = params.defaultPolicy ?? DEFAULT_POLICY;
+        this.evaluator = params.evaluator ?? defaultAssertionEvaluator;
+    }
+    async runValidation(input) {
+        const { missionId, milestone } = input;
+        const policy = input.policy ?? this.defaultPolicy;
+        const timeoutMs = input.timeoutMs ?? this.defaultTimeoutMs;
+        const forceInferredConfidence = input.forceInferredConfidence ?? false;
+        const features = this.missionService.listMissionFeatures({
+            missionId,
+            userId: '',
+            isAdmin: true,
+        });
+        const milestoneFeatureIds = new Set(features.filter((feature) => feature.milestone === milestone).map((feature) => feature.featureId));
+        const allAssertions = this.missionService.listMissionValidationAssertions({
+            missionId,
+            userId: '',
+            isAdmin: true,
+        });
+        const assertions = allAssertions.filter((assertion) => assertion.featureId && milestoneFeatureIds.has(assertion.featureId));
+        this.missionService.recordMissionRuntimeEvent({
+            missionId,
+            eventType: 'validation_started',
+            source: 'platform',
+            eventTime: Date.now(),
+            payload: {
+                milestone,
+                assertionCount: assertions.length,
+                assertionIds: assertions.map((assertion) => assertion.assertionId),
+                policy,
+            },
+        });
+        const featureById = new Map(features.map((feature) => [feature.featureId, feature]));
+        const runWithTimeout = async () => {
+            const result = {
+                milestone,
+                assertionCount: assertions.length,
+                passed: 0,
+                failed: 0,
+                blocked: 0,
+                failedAssertionIds: [],
+                shouldHalt: false,
+                timedOut: false,
+            };
+            for (const assertion of assertions) {
+                const feature = assertion.featureId ? featureById.get(assertion.featureId) ?? null : null;
+                const workerOutput = feature?.workerOutput ?? null;
+                const evaluation = await this.evaluator({ assertion, feature, workerOutput });
+                const confidence = forceInferredConfidence && evaluation.confidence !== 'unknown'
+                    ? 'inferred'
+                    : evaluation.confidence;
+                this.missionService.updateMissionValidationAssertion({
+                    missionId,
+                    assertionId: assertion.assertionId,
+                    status: evaluation.status,
+                    note: evaluation.note,
+                    evidence: evaluation.evidence,
+                    confidence,
+                });
+                if (evaluation.status === 'passed') {
+                    result.passed += 1;
+                }
+                else if (evaluation.status === 'failed') {
+                    result.failed += 1;
+                    result.failedAssertionIds.push(assertion.assertionId);
+                }
+                else {
+                    result.blocked += 1;
+                }
+            }
+            result.shouldHalt = policy === 'failOnFirst' && result.failed > 0;
+            return result;
+        };
+        let result;
+        let timedOut = false;
+        try {
+            result = await runWithTimeoutBound(runWithTimeout, timeoutMs, () => {
+                timedOut = true;
+            });
+        }
+        catch (error) {
+            const message = String(error?.message ?? error);
+            result = {
+                milestone,
+                assertionCount: assertions.length,
+                passed: 0,
+                failed: 0,
+                blocked: 0,
+                failedAssertionIds: [],
+                shouldHalt: policy === 'failOnFirst',
+                timedOut,
+                error: message,
+            };
+        }
+        result.timedOut = timedOut || result.timedOut;
+        this.missionService.recordMissionRuntimeEvent({
+            missionId,
+            eventType: 'validation_completed',
+            source: 'platform',
+            eventTime: Date.now(),
+            payload: {
+                milestone,
+                assertionCount: result.assertionCount,
+                assertionIds: assertions.map((assertion) => assertion.assertionId),
+                failedAssertionIds: result.failedAssertionIds,
+                passed: result.passed,
+                failed: result.failed,
+                blocked: result.blocked,
+                policy,
+                shouldHalt: result.shouldHalt,
+                timedOut: result.timedOut,
+                error: result.error ?? null,
+            },
+        });
+        return result;
+    }
+    async evaluateAssertion(input) {
+        const { missionId, assertionId, forceInferredConfidence } = input;
+        const assertion = this.missionService
+            .listMissionValidationAssertions({ missionId, userId: '', isAdmin: true })
+            .find((a) => a.assertionId === assertionId);
+        if (!assertion) {
+            throw new Error(`Assertion ${assertionId} not found`);
+        }
+        const features = this.missionService.listMissionFeatures({ missionId, userId: '', isAdmin: true });
+        const feature = assertion.featureId
+            ? features.find((f) => f.featureId === assertion.featureId) ?? null
+            : null;
+        const workerOutput = feature?.workerOutput ?? null;
+        const evaluation = await this.evaluator({ assertion, feature, workerOutput });
+        const confidence = forceInferredConfidence && evaluation.confidence !== 'unknown'
+            ? 'inferred'
+            : evaluation.confidence;
+        this.missionService.updateMissionValidationAssertion({
+            missionId,
+            assertionId,
+            status: evaluation.status,
+            note: evaluation.note,
+            evidence: evaluation.evidence,
+            confidence,
+        });
+        return { ...evaluation, confidence };
+    }
+    resolvePolicy(config) {
+        const value = config?.validationPolicy;
+        if (value === 'failOnFirst' || value === 'continueOnWarning')
+            return value;
+        return this.defaultPolicy;
+    }
+    resolveTimeoutMs(config) {
+        const value = config?.validationTimeoutMs;
+        if (typeof value === 'number' && Number.isFinite(value) && value > 0)
+            return Math.floor(value);
+        return this.defaultTimeoutMs;
+    }
+}
+function runWithTimeoutBound(fn, timeoutMs, onTimeout) {
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0)
+        return fn();
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            onTimeout();
+            reject(new Error(`Validation timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+        fn()
+            .then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        })
+            .catch((error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+    });
+}
+export function defaultAssertionEvaluator(input) {
+    const { assertion, feature, workerOutput } = input;
+    if (!feature) {
+        return {
+            status: 'blocked',
+            note: 'Source feature not found for assertion.',
+            evidence: `assertionId=${assertion.assertionId}`,
+            confidence: 'unknown',
+        };
+    }
+    const status = feature.status;
+    if (status === 'completed') {
+        return evaluateCompletedFeature(assertion, feature, workerOutput);
+    }
+    if (status === 'failed') {
+        return evaluateFailedFeature(assertion, feature, workerOutput);
+    }
+    if (status === 'skipped') {
+        return {
+            status: 'blocked',
+            note: 'Source feature was skipped.',
+            evidence: buildFeatureStatusEvidence(feature),
+            confidence: 'inferred',
+        };
+    }
+    if (status === 'cancelled') {
+        return {
+            status: 'blocked',
+            note: 'Source feature was cancelled.',
+            evidence: buildFeatureStatusEvidence(feature),
+            confidence: 'inferred',
+        };
+    }
+    return {
+        status: 'blocked',
+        note: `Source feature has unresolved status: ${status}.`,
+        evidence: buildFeatureStatusEvidence(feature),
+        confidence: 'unknown',
+    };
+}
+function evaluateCompletedFeature(assertion, feature, workerOutput) {
+    const commandsRun = extractCommandsRun(workerOutput);
+    if (commandsRun.length > 0) {
+        const failed = commandsRun.find((entry) => entry.exitCode !== 0);
+        if (failed) {
+            return {
+                status: 'failed',
+                note: `Verification command failed: ${failed.command}`,
+                evidence: `exitCode=${failed.exitCode}; observation=${truncateCitation(failed.observation)}`,
+                confidence: 'observed',
+            };
+        }
+        return {
+            status: 'passed',
+            note: 'Feature completed and verification commands ran successfully.',
+            evidence: commandsRun
+                .map((entry) => `${entry.command} (exitCode=${entry.exitCode})`)
+                .join('; '),
+            confidence: 'observed',
+        };
+    }
+    const evidence = buildEvidenceCorpus(workerOutput);
+    if (!evidence.hasAnyEvidence) {
+        return {
+            status: 'passed',
+            note: 'Feature completed; no worker output evidence was captured.',
+            evidence: buildFeatureStatusEvidence(feature),
+            confidence: 'inferred',
+        };
+    }
+    const match = findAssertionEvidenceMatch(assertion.assertionText, evidence);
+    if (match) {
+        return {
+            status: 'passed',
+            note: `Feature completed and worker output supports this assertion via ${match.source}.`,
+            evidence: match.citation,
+            confidence: 'observed',
+        };
+    }
+    return {
+        status: 'passed',
+        note: 'Feature completed with worker output; no direct assertion keyword match, so result is derived from feature success.',
+        evidence: buildEvidenceSummary(evidence),
+        confidence: 'derived',
+    };
+}
+function extractCommandsRun(workerOutput) {
+    const handoff = isPlainObject(workerOutput?.handoff) ? workerOutput.handoff : {};
+    const verification = isPlainObject(handoff.verification) ? handoff.verification : {};
+    const commandsRun = Array.isArray(verification.commandsRun) ? verification.commandsRun : [];
+    return commandsRun.filter((entry) => isPlainObject(entry) &&
+        typeof entry.command === 'string' &&
+        typeof entry.exitCode === 'number' &&
+        typeof entry.observation === 'string');
+}
+function evaluateFailedFeature(assertion, feature, workerOutput) {
+    const errorEvidence = buildErrorEvidence(workerOutput);
+    if (errorEvidence) {
+        return {
+            status: 'failed',
+            note: `Source feature ${feature.featureId} failed with worker-reported error.`,
+            evidence: errorEvidence,
+            confidence: 'observed',
+        };
+    }
+    return {
+        status: 'failed',
+        note: `Source feature ${feature.featureId} failed.`,
+        evidence: buildFeatureStatusEvidence(feature),
+        confidence: 'derived',
+    };
+}
+function buildEvidenceCorpus(workerOutput) {
+    const handoff = isPlainObject(workerOutput?.handoff) ? workerOutput.handoff : {};
+    const stdout = typeof workerOutput?.stdout === 'string' ? workerOutput.stdout : '';
+    const stderr = typeof workerOutput?.stderr === 'string' ? workerOutput.stderr : '';
+    const implementedFiles = Array.isArray(workerOutput?.implementedFiles)
+        ? workerOutput.implementedFiles.filter((item) => typeof item === 'string')
+        : [];
+    return {
+        hasAnyEvidence: Boolean(stdout
+            || stderr
+            || implementedFiles.length > 0
+            || handoff.salientSummary
+            || handoff.verification
+            || handoff.llmResponsePreview
+            || (Array.isArray(handoff.discoveredIssues) && handoff.discoveredIssues.length > 0)),
+        handoffSummary: typeof handoff.salientSummary === 'string' ? handoff.salientSummary : '',
+        handoffVerification: isPlainObject(handoff.verification)
+            ? JSON.stringify(handoff.verification)
+            : typeof handoff.verification === 'string'
+                ? handoff.verification
+                : '',
+        handoffLlmPreview: typeof handoff.llmResponsePreview === 'string' ? handoff.llmResponsePreview : '',
+        discoveredIssues: Array.isArray(handoff.discoveredIssues)
+            ? handoff.discoveredIssues
+                .map((item) => {
+                if (typeof item === 'string')
+                    return item;
+                if (isPlainObject(item) && typeof item.description === 'string')
+                    return item.description;
+                return JSON.stringify(item);
+            })
+                .join('\n')
+            : '',
+        stdout,
+        stderr,
+        implementedFiles,
+    };
+}
+function findAssertionEvidenceMatch(assertionText, evidence) {
+    const keywords = extractAssertionKeywords(assertionText);
+    if (keywords.length === 0)
+        return null;
+    // Prefer concrete file evidence first when a keyword names a changed file.
+    for (const filePath of evidence.implementedFiles) {
+        const normalizedPath = normalizeEvidenceText(filePath);
+        if (keywords.some((keyword) => normalizedPath.includes(keyword))) {
+            return {
+                source: 'implementedFiles',
+                citation: `implementedFiles: ${evidence.implementedFiles.join(', ')}`,
+            };
+        }
+    }
+    const searchableFields = [
+        { key: 'handoff.salientSummary', text: evidence.handoffSummary },
+        { key: 'handoff.verification', text: evidence.handoffVerification },
+        { key: 'handoff.llmResponsePreview', text: evidence.handoffLlmPreview },
+        { key: 'handoff.discoveredIssues', text: evidence.discoveredIssues },
+        { key: 'stdout', text: evidence.stdout },
+    ];
+    for (const field of searchableFields) {
+        const normalized = normalizeEvidenceText(field.text);
+        if (keywords.some((keyword) => normalized.includes(keyword))) {
+            return {
+                source: field.key,
+                citation: `${field.key}: ${truncateCitation(field.text)}`,
+            };
+        }
+    }
+    return null;
+}
+function buildErrorEvidence(workerOutput) {
+    const parts = [];
+    if (typeof workerOutput?.error === 'string' && workerOutput.error) {
+        parts.push(`error: ${truncateCitation(workerOutput.error)}`);
+    }
+    if (typeof workerOutput?.stderr === 'string' && workerOutput.stderr) {
+        parts.push(`stderr: ${truncateCitation(workerOutput.stderr)}`);
+    }
+    const handoff = isPlainObject(workerOutput?.handoff) ? workerOutput.handoff : {};
+    if (Array.isArray(handoff.discoveredIssues) && handoff.discoveredIssues.length > 0) {
+        const issues = handoff.discoveredIssues
+            .map((item) => {
+            if (typeof item === 'string')
+                return item;
+            if (isPlainObject(item) && typeof item.description === 'string')
+                return item.description;
+            return JSON.stringify(item);
+        })
+            .join('; ');
+        parts.push(`discoveredIssues: ${truncateCitation(issues)}`);
+    }
+    return parts.length > 0 ? parts.join('; ') : null;
+}
+function buildEvidenceSummary(evidence) {
+    const parts = [];
+    if (evidence.handoffSummary)
+        parts.push(`handoff.salientSummary: ${truncateCitation(evidence.handoffSummary)}`);
+    if (evidence.implementedFiles.length > 0) {
+        parts.push(`implementedFiles: ${evidence.implementedFiles.join(', ')}`);
+    }
+    if (evidence.stdout)
+        parts.push(`stdout: ${truncateCitation(evidence.stdout)}`);
+    if (evidence.stderr)
+        parts.push(`stderr: ${truncateCitation(evidence.stderr)}`);
+    return parts.length > 0 ? parts.join('; ') : 'Worker output present but no summary fields were extracted.';
+}
+function buildFeatureStatusEvidence(feature) {
+    const parts = [`featureId=${feature.featureId}`, `status=${feature.status}`];
+    if (feature.description) {
+        parts.push(`description=${feature.description.slice(0, 200)}`);
+    }
+    return parts.join('; ');
+}
+function extractAssertionKeywords(assertionText) {
+    const normalized = normalizeEvidenceText(assertionText);
+    const stopWords = new Set([
+        // Generic modals and auxiliaries
+        'should', 'must', 'will', 'would', 'could', 'shall', 'need', 'needs', 'have', 'having',
+        'with', 'without', 'from', 'into', 'through', 'during', 'before', 'after', 'above',
+        'below', 'between', 'among', 'within', 'across', 'around', 'under', 'over', 'again',
+        'further', 'then', 'once', 'here', 'there', 'when', 'where', 'what', 'which', 'while',
+        'because', 'until', 'although', 'whether', 'unless', 'since', 'than', 'that', 'this',
+        'these', 'those', 'they', 'them', 'their', 'such', 'only', 'also', 'just', 'about',
+        'above', 'according', 'accordingly', 'across', 'actually', 'afterwards', 'able',
+        // Native mission domain generics that appear in boilerplate
+        'worker', 'workers', 'feature', 'features', 'mission', 'missions', 'native', 'natives',
+        'complete', 'completed', 'completes', 'completion', 'run', 'runs', 'running', 'execute',
+        'executes', 'executed', 'perform', 'performs', 'performed', 'generate', 'generates',
+        'generated', 'create', 'creates', 'created', 'write', 'writes', 'written', 'make',
+        'makes', 'made', 'implement', 'implements', 'implemented', 'build', 'builds', 'built',
+    ]);
+    const tokens = normalized
+        .split(/\s+/)
+        .filter((token) => token.length >= 5 && !stopWords.has(token));
+    return [...new Set(tokens)];
+}
+function normalizeEvidenceText(value) {
+    return value
+        .toLowerCase()
+        .replace(/[^a-z0-9\/._-]+/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+function truncateCitation(value, limit = 300) {
+    const trimmed = value.trim();
+    if (trimmed.length <= limit)
+        return trimmed;
+    return `${trimmed.slice(0, limit)}...`;
+}
+function isPlainObject(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}