@orion-agents/orion-code 0.1.2 → 0.1.4

package/dist/runtime/subagents/research-citation.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Citation, conflict, and evidence-candidate resolution (v0.1.4, P0-R3).
+ *
+ * Turns a `ResearchPacket` (with its claims + sources) into:
+ *  - resolved claim->source bindings (reference-integrity validated),
+ *  - same-URL multi-version dedupe (older revisions marked `stale` on hash drift),
+ *  - conflict records for contradictory sources (never auto-picked),
+ *  - a verification classification per claim,
+ *  - evidence candidates (only rule-compliant claims; research vs execution kept
+ *    distinct so a web summary can never stand in for test/build/file facts),
+ *  - a completion audit that stays `partial`/`unmet` for claims that have sources
+ *    but no independent verification.
+ *
+ * This module is pure (no IO) so it is fully testable without network or disk.
+ */
+import type { ResearchPacket } from './research-types';
+/** Normalize a URL for dedupe: drop fragment + trailing slash, lowercase host. */
+export declare function urlKey(url: string | undefined): string;
+export type BindingStatus = 'bound' | 'dangling' | 'stale_only' | 'conflicted';
+export interface ClaimBinding {
+    claimId: string;
+    /** Resolved, non-stale source ids actually backing the claim. */
+    sourceIds: string[];
+    /** All source ids referenced by the claim (including stale/blocked). */
+    referencedSourceIds: string[];
+    status: BindingStatus;
+}
+export interface ConflictRecord {
+    claimId: string;
+    sourceIds: string[];
+    reason: string;
+}
+export interface EvidenceCandidate {
+    claimId: string;
+    /** 'research' = external/web source; 'execution' = file/verification fact. */
+    kind: 'research' | 'execution';
+    basis: 'file' | 'external';
+    summary: string;
+}
+export interface CompletionAudit {
+    status: 'met' | 'partial' | 'unmet';
+    /** Claims that have sources but no independent verification. */
+    unverifiedClaimIds: string[];
+    notes: string[];
+}
+export interface CitationResolution {
+    packetId: string;
+    bindings: ClaimBinding[];
+    conflicts: ConflictRecord[];
+    staleSourceIds: string[];
+    evidenceCandidates: EvidenceCandidate[];
+    audit: CompletionAudit;
+}
+/**
+ * Resolve citations for a packet.
+ *
+ * Reference integrity: a claim binding to an unknown source id is flagged
+ * `dangling` (and downgraded to `unverified`). Dedupe: sources sharing a
+ * canonical URL key are collapsed; the newest by `retrievedAt` wins and older
+ * revisions with a different content hash are marked `stale`. Conflict: a claim
+ * backed by both a `retrieved` source and a `failed`/`blocked` source (or two
+ * sources explicitly flagged contradictory) yields a conflict record and is
+ * never silently resolved in the model-favorable direction.
+ */
+export declare function resolveCitations(packet: ResearchPacket): CitationResolution;
+//# sourceMappingURL=research-citation.d.ts.map

package/dist/runtime/subagents/research-citation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"research-citation.d.ts","sourceRoot":"","sources":["../../../src/runtime/subagents/research-citation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAiB,cAAc,EAAgC,MAAM,kBAAkB,CAAC;AAEpG,kFAAkF;AAClF,wBAAgB,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAYtD;AAED,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,UAAU,GAAG,YAAY,GAAG,YAAY,CAAC;AAE/E,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,wEAAwE;IACxE,mBAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,MAAM,EAAE,aAAa,CAAC;CACvB;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,8EAA8E;IAC9E,IAAI,EAAE,UAAU,GAAG,WAAW,CAAC;IAC/B,KAAK,EAAE,MAAM,GAAG,UAAU,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,KAAK,GAAG,SAAS,GAAG,OAAO,CAAC;IACpC,gEAAgE;IAChE,kBAAkB,EAAE,MAAM,EAAE,CAAC;IAC7B,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,SAAS,EAAE,cAAc,EAAE,CAAC;IAC5B,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,kBAAkB,EAAE,iBAAiB,EAAE,CAAC;IACxC,KAAK,EAAE,eAAe,CAAC;CACxB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,cAAc,GAAG,kBAAkB,CAsG3E"}

package/dist/runtime/subagents/research-citation.js

@@ -0,0 +1,185 @@
+"use strict";
+/**
+ * Citation, conflict, and evidence-candidate resolution (v0.1.4, P0-R3).
+ *
+ * Turns a `ResearchPacket` (with its claims + sources) into:
+ *  - resolved claim->source bindings (reference-integrity validated),
+ *  - same-URL multi-version dedupe (older revisions marked `stale` on hash drift),
+ *  - conflict records for contradictory sources (never auto-picked),
+ *  - a verification classification per claim,
+ *  - evidence candidates (only rule-compliant claims; research vs execution kept
+ *    distinct so a web summary can never stand in for test/build/file facts),
+ *  - a completion audit that stays `partial`/`unmet` for claims that have sources
+ *    but no independent verification.
+ *
+ * This module is pure (no IO) so it is fully testable without network or disk.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.urlKey = urlKey;
+exports.resolveCitations = resolveCitations;
+/** Normalize a URL for dedupe: drop fragment + trailing slash, lowercase host. */
+function urlKey(url) {
+    if (!url)
+        return '';
+    try {
+        const u = new URL(url);
+        const host = u.host.toLowerCase();
+        let path = u.pathname;
+        if (path.length > 1 && path.endsWith('/'))
+            path = path.slice(0, -1);
+        const query = u.search;
+        return `${u.protocol}//${host}${path}${query}`;
+    }
+    catch {
+        return url;
+    }
+}
+/**
+ * Resolve citations for a packet.
+ *
+ * Reference integrity: a claim binding to an unknown source id is flagged
+ * `dangling` (and downgraded to `unverified`). Dedupe: sources sharing a
+ * canonical URL key are collapsed; the newest by `retrievedAt` wins and older
+ * revisions with a different content hash are marked `stale`. Conflict: a claim
+ * backed by both a `retrieved` source and a `failed`/`blocked` source (or two
+ * sources explicitly flagged contradictory) yields a conflict record and is
+ * never silently resolved in the model-favorable direction.
+ */
+function resolveCitations(packet) {
+    const sourceIds = new Set(packet.sources.map(s => s.id));
+    const byId = new Map(packet.sources.map(s => [s.id, s]));
+    // --- dedupe same-URL multi-version -> stale ---
+    const staleSourceIds = [];
+    const groups = new Map();
+    for (const s of packet.sources) {
+        const key = urlKey(s.canonicalUrl);
+        if (!key)
+            continue;
+        const arr = groups.get(key) ?? [];
+        arr.push(s);
+        groups.set(key, arr);
+    }
+    for (const [, group] of groups) {
+        if (group.length < 2)
+            continue;
+        // newest by retrievedAt wins; older ones with a different hash become stale.
+        const sorted = [...group].sort((a, b) => b.retrievedAt.localeCompare(a.retrievedAt));
+        const winner = sorted[0];
+        for (let i = 1; i < sorted.length; i++) {
+            const s = sorted[i];
+            if (s.contentHash && winner.contentHash && s.contentHash !== winner.contentHash) {
+                staleSourceIds.push(s.id);
+                s.status = 'stale';
+            }
+        }
+    }
+    const staleSet = new Set(staleSourceIds);
+    const bindings = [];
+    const conflicts = [];
+    const evidenceCandidates = [];
+    for (const claim of packet.claims) {
+        const referenced = claim.sourceIds.filter(id => sourceIds.has(id));
+        const danglingRefs = claim.sourceIds.filter(id => !sourceIds.has(id));
+        const active = referenced.filter(id => !staleSet.has(id));
+        const activeSources = active.map(id => byId.get(id)).filter(Boolean);
+        const hasRetrieved = activeSources.some(s => s.status === 'retrieved');
+        const hasFailed = activeSources.some(s => s.status === 'failed' || s.status === 'blocked');
+        let status;
+        if (danglingRefs.length > 0 && referenced.length === 0) {
+            status = 'dangling';
+        }
+        else if (hasRetrieved && hasFailed) {
+            status = 'conflicted';
+        }
+        else if (active.length === 0 && referenced.length > 0) {
+            status = 'stale_only';
+        }
+        else {
+            status = 'bound';
+        }
+        if (status === 'conflicted') {
+            conflicts.push({
+                claimId: claim.id,
+                sourceIds: active,
+                reason: 'claim backed by both a retrieved source and a failed/blocked source',
+            });
+        }
+        bindings.push({
+            claimId: claim.id,
+            sourceIds: active,
+            referencedSourceIds: referenced,
+            status,
+        });
+        // Verification classification: conflicted -> contradicted.
+        const verification = status === 'conflicted'
+            ? 'contradicted'
+            : classifyVerification(claim, hasRetrieved, activeSources);
+        claim.verification = verification;
+        // Evidence candidate: only rule-compliant claims.
+        if ((verification === 'observed' || verification === 'partially_observed') &&
+            claim.evidenceKind !== 'inference' &&
+            status !== 'conflicted') {
+            const primary = activeSources.find(s => s.status === 'retrieved');
+            const isFile = primary?.kind === 'file';
+            evidenceCandidates.push({
+                claimId: claim.id,
+                kind: isFile ? 'execution' : 'research',
+                basis: isFile ? 'file' : 'external',
+                summary: claim.text,
+            });
+        }
+    }
+    const audit = auditCompletion(packet, bindings);
+    return {
+        packetId: packet.packetId,
+        bindings,
+        conflicts,
+        staleSourceIds,
+        evidenceCandidates,
+        audit,
+    };
+}
+function classifyVerification(claim, hasRetrieved, activeSources) {
+    if (claim.evidenceKind === 'inference')
+        return 'unverified';
+    if (!hasRetrieved)
+        return 'unverified';
+    const onlyExcerpt = activeSources.every(s => !!s.excerpt && s.excerpt.length < 4000 && !s.contentHash);
+    return onlyExcerpt ? 'partially_observed' : 'observed';
+}
+/**
+ * Completion audit. The key invariant (plan exit condition): a claim that HAS
+ * sources but no independent verification must keep the audit `partial`/`unmet`
+ * - never `met`. We therefore treat any claim with referenced sources whose
+ * verification is not `observed` as unverified for audit purposes.
+ */
+function auditCompletion(packet, bindings) {
+    const notes = [];
+    const unverifiedClaimIds = [];
+    for (const claim of packet.claims) {
+        const binding = bindings.find(b => b.claimId === claim.id);
+        const hasSources = (binding?.referencedSourceIds.length ?? 0) > 0;
+        const independentlyVerified = claim.verification === 'observed';
+        if (!independentlyVerified) {
+            if (hasSources) {
+                unverifiedClaimIds.push(claim.id);
+                notes.push(`claim ${claim.id} has sources but no independent verification (stays partial)`);
+            }
+            else {
+                unverifiedClaimIds.push(claim.id);
+            }
+        }
+    }
+    let status;
+    if (unverifiedClaimIds.length === 0) {
+        status = 'met';
+    }
+    else if (packet.claims.some(c => (bindings.find(b => b.claimId === c.id)?.referencedSourceIds.length ?? 0) > 0)) {
+        status = 'partial';
+    }
+    else {
+        status = 'unmet';
+    }
+    return { status, unverifiedClaimIds, notes };
+}
+//# sourceMappingURL=research-citation.js.map

package/dist/runtime/subagents/research-citation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"research-citation.js","sourceRoot":"","sources":["../../../src/runtime/subagents/research-citation.ts"],"names":[],"mappings":"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"}

package/dist/runtime/subagents/research-contract.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Research contract and normalizer (v0.1.4, P0-R1).
+ *
+ * Responsibilities:
+ *  - Validate a `ResearchRequest` before any work happens.
+ *  - Map a legacy `SubtaskResult` (existing `research` role output) into a
+ *    versioned `ResearchPacket` without rewriting the runtime.
+ *  - Fail closed: missing summary, over-limit sources, or an `observed` claim
+ *    without a source binding are rejected. Non-completed results never yield
+ *    `observed` claims (no "looks researched" masquerading as verified).
+ *  - Provide a deterministic serialization + content hash contract so packets
+ *    are replayable and de-duplicable.
+ */
+import type { SubtaskResult } from './types';
+import { type ResearchPacket, type ResearchRequest } from './research-types';
+/** Hard caps independent of per-request budget, to bound abuse. */
+export declare const RESEARCH_HARD_LIMITS: {
+    readonly maxSources: {
+        readonly min: 1;
+        readonly max: 200;
+    };
+    readonly maxFetchBytes: {
+        readonly min: 0;
+        readonly max: number;
+    };
+    readonly maxDurationMs: {
+        readonly min: 1000;
+        readonly max: 600000;
+    };
+    readonly maxClaims: 500;
+    readonly maxSummaryLen: 20000;
+};
+export interface ValidationResult {
+    ok: boolean;
+    errors: string[];
+}
+export interface PacketContext {
+    sessionId: string;
+    projectPath: string;
+    goalId?: string;
+    objectiveRevision?: number;
+}
+/** Validate a research request before scheduling any work. */
+export declare function validateResearchRequest(req: Partial<ResearchRequest>): ValidationResult;
+/** Convenience builder for a local-only research request (POC-1 default). */
+export declare function createLocalResearchRequest(objective: string, projectRoot: string, overrides?: Partial<ResearchRequest>): ResearchRequest;
+/**
+ * Map a legacy `SubtaskResult` into a versioned `ResearchPacket`.
+ *
+ * File findings become `observed` file claims bound to a `file` source. Findings
+ * without a file become `inference`/`unverified` claims. Failed/cancelled/timed
+ * out results downgrade every claim to `unverified` so a partial run can never
+ * report a verified conclusion.
+ */
+export declare function subtaskResultToPacket(result: SubtaskResult, request: ResearchRequest, ctx: PacketContext): ResearchPacket;
+/**
+ * Fail-closed packet validation. An `observed`/`partially_observed` claim must
+ * bind to at least one existing source; an inference claim must not be marked
+ * `observed`; source counts must respect the request budget.
+ */
+export declare function validatePacket(packet: ResearchPacket): ValidationResult;
+/** Deterministic JSON (sorted keys) for a value. */
+export declare function stableStringify(value: unknown): string;
+/**
+ * Content hash over the canonical packet body (timestamps excluded). Proves what
+ * was read, NOT that the content is true; used for dedupe and drift detection.
+ */
+export declare function hashPacket(packet: ResearchPacket): string;
+//# sourceMappingURL=research-contract.d.ts.map

package/dist/runtime/subagents/research-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"research-contract.d.ts","sourceRoot":"","sources":["../../../src/runtime/subagents/research-contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAgB,MAAM,SAAS,CAAC;AAC3D,OAAO,EAIL,KAAK,cAAc,EACnB,KAAK,eAAe,EAGrB,MAAM,kBAAkB,CAAC;AAE1B,mEAAmE;AACnE,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;CAMvB,CAAC;AAEX,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAMD,8DAA8D;AAC9D,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,OAAO,CAAC,eAAe,CAAC,GAAG,gBAAgB,CA2BvF;AAED,6EAA6E;AAC7E,wBAAgB,0BAA0B,CACxC,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,SAAS,GAAE,OAAO,CAAC,eAAe,CAAM,GACvC,eAAe,CAWjB;AAQD;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,eAAe,EACxB,GAAG,EAAE,aAAa,GACjB,cAAc,CAgEhB;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,cAAc,GAAG,gBAAgB,CAoCvE;AAaD,oDAAoD;AACpD,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEtD;AAWD;;;GAGG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAEzD"}

package/dist/runtime/subagents/research-contract.js

@@ -0,0 +1,232 @@
+"use strict";
+/**
+ * Research contract and normalizer (v0.1.4, P0-R1).
+ *
+ * Responsibilities:
+ *  - Validate a `ResearchRequest` before any work happens.
+ *  - Map a legacy `SubtaskResult` (existing `research` role output) into a
+ *    versioned `ResearchPacket` without rewriting the runtime.
+ *  - Fail closed: missing summary, over-limit sources, or an `observed` claim
+ *    without a source binding are rejected. Non-completed results never yield
+ *    `observed` claims (no "looks researched" masquerading as verified).
+ *  - Provide a deterministic serialization + content hash contract so packets
+ *    are replayable and de-duplicable.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RESEARCH_HARD_LIMITS = void 0;
+exports.validateResearchRequest = validateResearchRequest;
+exports.createLocalResearchRequest = createLocalResearchRequest;
+exports.subtaskResultToPacket = subtaskResultToPacket;
+exports.validatePacket = validatePacket;
+exports.stableStringify = stableStringify;
+exports.hashPacket = hashPacket;
+const crypto_1 = require("crypto");
+const research_types_1 = require("./research-types");
+/** Hard caps independent of per-request budget, to bound abuse. */
+exports.RESEARCH_HARD_LIMITS = {
+    maxSources: { min: 1, max: 200 },
+    maxFetchBytes: { min: 0, max: 32 * 1024 * 1024 },
+    maxDurationMs: { min: 1000, max: 600000 },
+    maxClaims: 500,
+    maxSummaryLen: 20000,
+};
+function nowIso() {
+    return new Date().toISOString();
+}
+/** Validate a research request before scheduling any work. */
+function validateResearchRequest(req) {
+    const errors = [];
+    if (typeof req.schemaVersion !== 'number')
+        errors.push('schemaVersion is required');
+    if (req.schemaVersion !== undefined && req.schemaVersion !== research_types_1.RESEARCH_SCHEMA_VERSION) {
+        errors.push(`unsupported schemaVersion ${req.schemaVersion}`);
+    }
+    if (typeof req.objective !== 'string' || !req.objective.trim())
+        errors.push('objective is required');
+    if (!req.scope || typeof req.scope.projectRoot !== 'string')
+        errors.push('scope.projectRoot is required');
+    if (req.mode !== 'local' && req.mode !== 'web' && req.mode !== 'mixed') {
+        errors.push('mode must be local | web | mixed');
+    }
+    if (typeof req.maxSources !== 'number' || req.maxSources < exports.RESEARCH_HARD_LIMITS.maxSources.min) {
+        errors.push(`maxSources must be >= ${exports.RESEARCH_HARD_LIMITS.maxSources.min}`);
+    }
+    if (typeof req.maxFetchBytes !== 'number' || req.maxFetchBytes < 0) {
+        errors.push('maxFetchBytes must be >= 0');
+    }
+    if (typeof req.maxDurationMs !== 'number' || req.maxDurationMs <= 0) {
+        errors.push('maxDurationMs must be > 0');
+    }
+    if (req.goalBinding) {
+        if (typeof req.goalBinding.goalId !== 'string')
+            errors.push('goalBinding.goalId is required');
+        if (typeof req.goalBinding.objectiveRevision !== 'number') {
+            errors.push('goalBinding.objectiveRevision is required');
+        }
+    }
+    return { ok: errors.length === 0, errors };
+}
+/** Convenience builder for a local-only research request (POC-1 default). */
+function createLocalResearchRequest(objective, projectRoot, overrides = {}) {
+    return {
+        schemaVersion: research_types_1.RESEARCH_SCHEMA_VERSION,
+        objective,
+        scope: { projectRoot, ...(overrides.scope ?? {}) },
+        mode: overrides.mode ?? 'local',
+        maxSources: overrides.maxSources ?? 50,
+        maxFetchBytes: overrides.maxFetchBytes ?? 0,
+        maxDurationMs: overrides.maxDurationMs ?? 120000,
+        ...overrides,
+    };
+}
+function deriveVerification(status, hasFile) {
+    // Fail closed: a non-completed result can never produce an `observed` claim.
+    if (status !== 'completed')
+        return 'unverified';
+    return hasFile ? 'observed' : 'unverified';
+}
+/**
+ * Map a legacy `SubtaskResult` into a versioned `ResearchPacket`.
+ *
+ * File findings become `observed` file claims bound to a `file` source. Findings
+ * without a file become `inference`/`unverified` claims. Failed/cancelled/timed
+ * out results downgrade every claim to `unverified` so a partial run can never
+ * report a verified conclusion.
+ */
+function subtaskResultToPacket(result, request, ctx) {
+    const sources = [];
+    const sourceByPath = new Map();
+    const ensureFileSource = (projectPath) => {
+        const existing = sourceByPath.get(projectPath);
+        if (existing)
+            return existing;
+        const source = {
+            id: `src-${sources.length + 1}`,
+            kind: 'file',
+            projectPath,
+            provider: 'local',
+            retrievedAt: nowIso(),
+            status: 'retrieved',
+        };
+        sourceByPath.set(projectPath, source);
+        sources.push(source);
+        return source;
+    };
+    for (const filePath of result.files)
+        ensureFileSource(filePath);
+    const claims = result.findings.map((finding, i) => {
+        const hasFile = typeof finding.file === 'string' && finding.file.length > 0;
+        const bound = hasFile ? ensureFileSource(finding.file) : undefined;
+        const evidenceKind = hasFile ? 'file' : 'inference';
+        const verification = deriveVerification(result.status, hasFile);
+        const text = finding.evidence ? `${finding.title}: ${finding.evidence}` : finding.title;
+        const claim = {
+            id: `clm-${i + 1}`,
+            text,
+            sourceIds: bound ? [bound.id] : [],
+            evidenceKind,
+            verification,
+        };
+        if (finding.severity) {
+            const confidence = finding.severity === 'critical' || finding.severity === 'high'
+                ? 'high'
+                : finding.severity === 'medium'
+                    ? 'medium'
+                    : 'low';
+            claim.confidence = confidence;
+        }
+        return claim;
+    });
+    const packet = {
+        schemaVersion: research_types_1.RESEARCH_SCHEMA_VERSION,
+        packetId: `pkt-${result.id}`,
+        projectPath: ctx.projectPath,
+        sessionId: ctx.sessionId,
+        ...(ctx.goalId ? { goalId: ctx.goalId } : {}),
+        ...(ctx.objectiveRevision !== undefined ? { objectiveRevision: ctx.objectiveRevision } : {}),
+        request,
+        summary: result.summary,
+        claims,
+        sources,
+        gaps: [],
+        risks: result.risks,
+        usage: result.usage,
+        createdAt: nowIso(),
+    };
+    return packet;
+}
+/**
+ * Fail-closed packet validation. An `observed`/`partially_observed` claim must
+ * bind to at least one existing source; an inference claim must not be marked
+ * `observed`; source counts must respect the request budget.
+ */
+function validatePacket(packet) {
+    const errors = [];
+    if (!packet.summary || !packet.summary.trim())
+        errors.push('packet.summary is required');
+    if (packet.schemaVersion !== research_types_1.RESEARCH_SCHEMA_VERSION) {
+        errors.push(`unsupported schemaVersion ${packet.schemaVersion}`);
+    }
+    if (packet.summary.length > exports.RESEARCH_HARD_LIMITS.maxSummaryLen) {
+        errors.push('packet.summary exceeds max length');
+    }
+    if (packet.claims.length > exports.RESEARCH_HARD_LIMITS.maxClaims) {
+        errors.push(`claims ${packet.claims.length} exceed max ${exports.RESEARCH_HARD_LIMITS.maxClaims}`);
+    }
+    const sourceIds = new Set(packet.sources.map(s => s.id));
+    for (const source of packet.sources) {
+        if (!source.provider)
+            errors.push(`source ${source.id} missing provider`);
+        if (!source.status)
+            errors.push(`source ${source.id} missing status`);
+    }
+    if (packet.sources.length > packet.request.maxSources) {
+        errors.push(`sources ${packet.sources.length} exceed request.maxSources ${packet.request.maxSources}`);
+    }
+    for (const claim of packet.claims) {
+        for (const sid of claim.sourceIds) {
+            if (!sourceIds.has(sid))
+                errors.push(`claim ${claim.id} references unknown source ${sid}`);
+        }
+        const verified = claim.verification === 'observed' || claim.verification === 'partially_observed';
+        if (verified && claim.sourceIds.length === 0) {
+            errors.push(`claim ${claim.id} marked ${claim.verification} but has no source binding`);
+        }
+        if (claim.verification === 'observed' && claim.evidenceKind === 'inference') {
+            errors.push(`claim ${claim.id} is inference but marked observed`);
+        }
+    }
+    return { ok: errors.length === 0, errors };
+}
+function sortDeep(value) {
+    if (Array.isArray(value))
+        return value.map(sortDeep);
+    if (value && typeof value === 'object') {
+        const obj = value;
+        const sorted = {};
+        for (const key of Object.keys(obj).sort())
+            sorted[key] = sortDeep(obj[key]);
+        return sorted;
+    }
+    return value;
+}
+/** Deterministic JSON (sorted keys) for a value. */
+function stableStringify(value) {
+    return JSON.stringify(sortDeep(value));
+}
+/** Strip volatile timestamps so the content hash is reproducible across runs. */
+function packetContentForHash(packet) {
+    return sortDeep({
+        ...packet,
+        createdAt: undefined,
+        sources: packet.sources.map(s => ({ ...s, retrievedAt: undefined })),
+    });
+}
+/**
+ * Content hash over the canonical packet body (timestamps excluded). Proves what
+ * was read, NOT that the content is true; used for dedupe and drift detection.
+ */
+function hashPacket(packet) {
+    return (0, crypto_1.createHash)('sha256').update(stableStringify(packetContentForHash(packet))).digest('hex');
+}
+//# sourceMappingURL=research-contract.js.map

package/dist/runtime/subagents/research-contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"research-contract.js","sourceRoot":"","sources":["../../../src/runtime/subagents/research-contract.ts"],"names":[],"mappings":"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"}

package/dist/runtime/subagents/research-quality.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Research quality, cost, and recovery hardening (v0.1.4, P1-R6).
+ *
+ * - Source ranking is EXPLAINABLE ONLY: it returns an ordering plus a list of
+ *   human-readable reasons (freshness / provider / scope match / dedup). It is
+ *   never a verdict on truth - a higher rank does not mean a source is correct.
+ * - Cost diagnostics summarize model/tool/time/source usage for `npm run cost`
+ *   reconciliation.
+ * - Recovery hints turn a structured failure reason into an actionable suggestion,
+ *   without ever suggesting a generic MCP or a write path.
+ */
+import type { ResearchPacket, ResearchScope, ResearchSource } from './research-types';
+export interface RankedSource {
+    sourceId: string;
+    rank: number;
+    score: number;
+    reasons: string[];
+}
+export interface RankOptions {
+    /** Preferred providers in priority order (higher index = lower preference). */
+    preferredProviders?: string[];
+    scope?: ResearchScope;
+    now?: Date;
+}
+/**
+ * Rank sources by explainable signals. Stale revisions are demoted. The returned
+ * `reasons` explain every contribution; the score is advisory, not truth.
+ */
+export declare function rankSources(sources: ResearchSource[], opts?: RankOptions): RankedSource[];
+export interface ResearchCostSummary {
+    modelRequests: number;
+    toolCalls: number;
+    durationMs: number;
+    sourceCount: number;
+    retrievedCount: number;
+    notes: string[];
+}
+/** Summarize research cost from the packet usage + source counts. */
+export declare function researchCostSummary(packet: ResearchPacket, opts?: {
+    fetchedBytes?: number;
+}): ResearchCostSummary;
+/**
+ * Turn a structured failure reason into an actionable recovery hint. Never
+ * suggests a generic MCP or a write/exec path.
+ */
+export declare function recoveryHint(reason: string | undefined): string;
+//# sourceMappingURL=research-quality.d.ts.map

package/dist/runtime/subagents/research-quality.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"research-quality.d.ts","sourceRoot":"","sources":["../../../src/runtime/subagents/research-quality.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEtF,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAuBD,MAAM,WAAW,WAAW;IAC1B,+EAA+E;IAC/E,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC9B,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,cAAc,EAAE,EAAE,IAAI,GAAE,WAAgB,GAAG,YAAY,EAAE,CAwC7F;AAED,MAAM,WAAW,mBAAmB;IAClC,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED,qEAAqE;AACrE,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,cAAc,EACtB,IAAI,GAAE;IAAE,YAAY,CAAC,EAAE,MAAM,CAAA;CAAO,GACnC,mBAAmB,CAiBrB;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAkB/D"}