@tryvitris/website-harness 0.0.0-stage → 0.1.0-beta.5

package/bin/types/src/agent/jev/packets.d.ts

@@ -0,0 +1,124 @@
+import type { SkillGraph, AgentState, GraphNode } from "../graph.ts";
+import { type RankedEvidenceItem } from "./ranking.ts";
+import type { JevConfig } from "./types.ts";
+export declare const SUPPORTED_COMPACT_NODES: readonly ["business-review", "narrative-review", "direction-review", "copy-review"];
+export type SupportedCompactNode = (typeof SUPPORTED_COMPACT_NODES)[number];
+export declare function isCompactSupportedNode(nodeId: string): boolean;
+export interface NodePacketBudget {
+    maxChars: number;
+    maxEvidenceChars: number;
+}
+export declare const DEFAULT_PACKET_BUDGETS: Record<string, NodePacketBudget>;
+export interface ManifestItem {
+    path: string;
+    bytes?: number;
+    reason: string;
+    section?: string;
+}
+export interface ExpandableItem {
+    id: string;
+    path: string;
+    description: string;
+    bytes: number;
+    hash?: string;
+}
+export interface DiverseEvidenceSelectionResult<T> {
+    selected: T[];
+    overflow: T[];
+}
+/**
+ * Selects evidence candidates with guaranteed diversity across sources.
+ * Prevents a single document or URL from monopolizing the packet budget.
+ */
+export declare function selectDiverseEvidence<T extends {
+    id: string;
+    source: string;
+    score?: number;
+    excerpt?: string;
+}>(items: T[], maxChars: number, lengthFn?: (item: T) => number, maxPerSource?: number): DiverseEvidenceSelectionResult<T>;
+export interface ObligationPartitionResult<T> {
+    included: T[];
+    partitioned: T[];
+    partitionedObligations: string[];
+}
+/**
+ * Partitions items by obligation boundary when required items exceed budget.
+ * Keeps entire obligations intact rather than arbitrarily truncating text mid-sentence or mid-claim.
+ */
+export declare function partitionByObligation<T extends {
+    obligationId?: string;
+    bytes?: number;
+    content?: string;
+}>(items: T[], maxBudget: number, sizeFn?: (item: T) => number): ObligationPartitionResult<T>;
+export interface PacketItem {
+    id: string;
+    kind: "instruction" | "contract" | "subject" | "evidence" | "preflight" | "constraint" | "obligation" | "repair";
+    required: boolean;
+    obligationId?: string;
+    content: string;
+    sourceHash: string;
+    bytes: number;
+}
+export interface CoverageManifest {
+    schemaVersion: 1;
+    nodeId: string;
+    generatedAt: string;
+    manifestHash?: string;
+    requiredPartitions?: string[];
+    included: ManifestItem[];
+    excluded: ManifestItem[];
+    expandable: ExpandableItem[];
+    items?: PacketItem[];
+}
+export interface CompactPacketResult {
+    packetText: string;
+    manifest: CoverageManifest;
+    oversize: boolean;
+    warnings: string[];
+}
+export interface RankedExcerpt {
+    id: string;
+    source: string;
+    excerpt: string;
+    score: number;
+    reason: string;
+}
+/**
+ * Computes per-excerpt relevance scores against node task keywords, change requests, or defect targets.
+ * Code ranks candidates deterministically; mandatory evidence is preserved independently.
+ */
+export declare function rankEvidenceRelevance(excerpts: Array<{
+    id: string;
+    source: string;
+    excerpt: string;
+}>, contextTerms: string[]): RankedExcerpt[];
+/** Slices only the relevant sections of contracts.md for a given review node. */
+export declare function extractContractSlice(kernelRoot: string, nodeId: string): string;
+/** Computes the canonical SHA256 content hash of coverage manifest items. */
+export declare function computeManifestHash(manifest: {
+    nodeId: string;
+    included: ManifestItem[];
+    excluded?: ManifestItem[];
+    expandable: ExpandableItem[];
+    requiredPartitions?: string[];
+}): string;
+export declare function logPacketExpansion(root: string, nodeId: string, expansionId: string): void;
+export declare function expandPacketItem(root: string, nodeId: string, expansionId: string, manifestHash?: string): string;
+/**
+ * Builds a bounded, compact context packet for a node.
+ * Slices mandatory contracts, embeds essential verbatim evidence excerpts,
+ * generates a coverage manifest, and defines explicit expansion paths.
+ */
+export declare function buildCompactContextPacket(opts: {
+    root: string;
+    kernel: string;
+    graph: SkillGraph;
+    state: AgentState;
+    node: GraphNode;
+    preflightSummary?: string;
+    budget?: NodePacketBudget;
+    jevConfig?: JevConfig;
+    /** Jev Score ranks for optional evidence. Shadow must omit this so packets match off. */
+    jevRankedEvidence?: RankedEvidenceItem[];
+    mandatoryEvidenceIds?: string[];
+}): CompactPacketResult;

package/bin/types/src/agent/jev/policy.d.ts

@@ -0,0 +1,83 @@
+import type { ChangeScope } from "../refine.ts";
+import type { GroundingVerdict, JevTaskApplicability } from "./types.ts";
+export declare const POLICY_VERSION = "2026-09-17.2";
+export interface TaskApplicabilityResult {
+    /** Whether this task should run at all given the site context. */
+    applicable: boolean;
+    /** Reason the task was skipped (empty when applicable). */
+    skipReason?: string;
+}
+/**
+ * Evaluates whether a Jev task should run for a given site context.
+ * A task is inapplicable when its subject matter does not exist on the site.
+ * Example: skip booking-price questions for a site with no booking functionality.
+ *
+ * When no applicability descriptor is registered for a task, it defaults to applicable.
+ * Confidence is distribution concentration, not correctness; do not use blanket thresholds.
+ */
+export declare function evaluateTaskApplicability(taskId: string, applicabilityDescriptors: JevTaskApplicability[] | undefined, siteContext?: {
+    subjectExists?: boolean;
+}): TaskApplicabilityResult;
+export interface CodeQuoteCheck {
+    sourceExists: boolean;
+    quoteFound: boolean;
+    normalizedMatch: boolean;
+    sourceFile?: string;
+    excerptLength: number;
+}
+export declare function evaluateGroundingVerdict(opts: {
+    codeCheck: CodeQuoteCheck;
+    relationChoice?: "supports" | "contradicts" | "says_nothing";
+    confidence?: number;
+    threshold?: number;
+}): {
+    verdict: GroundingVerdict;
+    autoAccepted: boolean;
+    notes: string;
+};
+export interface RoutingPolicyResult {
+    scope: ChangeScope;
+    isMixed: boolean;
+    isAmbiguous: boolean;
+    confidence: number;
+    autoAccepted: boolean;
+    rationale: string;
+}
+export declare function evaluateRoutingDecision(opts: {
+    choice: "business" | "copy" | "pages" | "direction" | "ambiguous" | "mixed";
+    confidence: number;
+    overrideScope?: ChangeScope;
+    fallbackScope: ChangeScope;
+    threshold?: number;
+}): RoutingPolicyResult;
+export interface MultiScopeDecisionResult {
+    scope: ChangeScope;
+    scopes: ChangeScope[];
+    isMixed: boolean;
+    isAmbiguous: boolean;
+    confidence: number;
+    autoAccepted: boolean;
+    rationale: string;
+    affectedNodes: string[];
+}
+export declare function requestNodesForScope(scope: ChangeScope): string[];
+export declare function unionNodesForScopes(scopes: ChangeScope[]): string[];
+export declare function evaluateMultiScopeDecision(opts: {
+    answers: {
+        business?: {
+            noul: number;
+        };
+        copy?: {
+            noul: number;
+        };
+        pages?: {
+            noul: number;
+        };
+        direction?: {
+            noul: number;
+        };
+    };
+    overrideScope?: ChangeScope;
+    fallbackScope: ChangeScope;
+    threshold?: number;
+}): MultiScopeDecisionResult;

package/bin/types/src/agent/jev/questions.d.ts

@@ -0,0 +1,244 @@
+import { type ChoiceQuestion, type NoulQuestion, type Questions, type ScoreCriteria, type ScoreQuestion } from "@typesafe-ai/sdk";
+export declare const QUESTION_VERSION = "2026-09-17.2";
+/**
+ * Recursively serializes any value to canonical JSON.
+ * - Object keys are recursively sorted lexicographically at every depth.
+ * - Array order is strictly preserved.
+ * - Undefined properties on objects are omitted (matching standard JSON.stringify).
+ * - Primitives are serialized deterministically.
+ */
+export declare function canonicalJsonStringify(val: unknown): string;
+/**
+ * Computes a SHA-256 hash of fully serialized question instructions and criteria.
+ * This is the cache-bust key: changing question wording or criteria busts the cache even if
+ * QUESTION_VERSION was not bumped.
+ */
+export declare function questionSemanticsHash(q: Record<string, unknown> | unknown): string;
+export declare const GROUNDING_RELATION_CRITERIA: {
+    readonly supports: "The cited evidence excerpt directly proves, confirms, or states the claim to be true.";
+    readonly contradicts: "The cited evidence excerpt directly contradicts the claim or asserts an opposite fact.";
+    readonly says_nothing: "The cited evidence excerpt does not address, mention, or verify what the claim asserts.";
+};
+export declare const PATH_REFERENCED_GROUNDING_INSTRUCTION_TEMPLATE = "Evaluate how the evidence excerpt at state.{evidencePath} relates to the claim at state.{claimPath}.\nDetermine whether the cited evidence supports, contradicts, or says nothing about the claim.";
+export declare const EMBEDDED_GROUNDING_INSTRUCTION_TEMPLATE = "Evaluate how the evidence excerpt relates to the claim.\n\nClaim:\n{claim}\n\nEvidence Excerpt:\n{excerpt}";
+export declare const GROUNDING_TASK_INSTRUCTIONS = "Evaluate how the evidence excerpt at state.{evidencePath} relates to the claim at state.{claimPath}.\nDetermine whether the cited evidence supports, contradicts, or says nothing about the claim.";
+/** Complete versioned semantic task definition, hashing instructions and criteria together. */
+export declare const GROUNDING_TASK_SEMANTICS: {
+    readonly task: "grounding";
+    readonly version: "2026-09-17.2";
+    readonly pathReferencedTemplate: "Evaluate how the evidence excerpt at state.{evidencePath} relates to the claim at state.{claimPath}.\nDetermine whether the cited evidence supports, contradicts, or says nothing about the claim.";
+    readonly embeddedTemplate: "Evaluate how the evidence excerpt relates to the claim.\n\nClaim:\n{claim}\n\nEvidence Excerpt:\n{excerpt}";
+    readonly criteria: {
+        readonly supports: "The cited evidence excerpt directly proves, confirms, or states the claim to be true.";
+        readonly contradicts: "The cited evidence excerpt directly contradicts the claim or asserts an opposite fact.";
+        readonly says_nothing: "The cited evidence excerpt does not address, mention, or verify what the claim asserts.";
+    };
+};
+export declare const GROUNDING_SEMANTICS_HASH: string;
+export declare function makeGroundingQuestion(claim: string, excerpt: string): ChoiceQuestion<typeof GROUNDING_RELATION_CRITERIA>;
+/** Path-referenced grounding question referencing explicit state paths without prompt duplication. */
+export declare function makePathReferencedGroundingQuestion(claimPath: string, evidencePath: string): ChoiceQuestion<typeof GROUNDING_RELATION_CRITERIA>;
+export declare const ROUTING_SCOPE_CRITERIA: {
+    readonly business: "Adds, removes, or modifies core business facts, services, offerings, pricing tiers, hours, or locations.";
+    readonly copy: "Edits wording, headlines, captions, subheads, or text without introducing ungrounded facts or changing visual design.";
+    readonly pages: "Changes component layout, spacing, buttons, navigation structure, or presentation without altering business facts.";
+    readonly direction: "Changes overall visual theme, brand styling, typography, color palette, or aesthetic look-and-feel.";
+    readonly ambiguous: "The request is vague, unclear, or lacks sufficient detail to determine a single engineering change scope.";
+    readonly mixed: "The request clearly combines multiple independent changes across different scopes (e.g., both copy wording and UI layout, or both business facts and visual theme).";
+};
+export declare function makeRoutingQuestion(instruction: string, context?: string): ChoiceQuestion<typeof ROUTING_SCOPE_CRITERIA>;
+export interface MultiScopeQuestions extends Questions {
+    business: NoulQuestion;
+    copy: NoulQuestion;
+    pages: NoulQuestion;
+    direction: NoulQuestion;
+}
+export declare function makeMultiScopeRoutingQuestions(instruction: string, context?: string): MultiScopeQuestions;
+export declare const CTA_CONSISTENCY_CRITERIA: {
+    readonly consistent: "The planned call-to-action wording, destination route, and intended interaction directly align with storyboard actions.";
+    readonly contradictory: "The planned call-to-action promises an action (e.g., direct scheduling, instant booking, checkout) that is not supported or conflicts with storyboard action definitions.";
+    readonly unaddressed: "The planned call-to-action is not addressed or present in the storyboard actions.";
+};
+export declare function makeCtaConsistencyQuestion(plannedCta: string, storyboardAction: string): ChoiceQuestion<typeof CTA_CONSISTENCY_CRITERIA>;
+export declare const EVIDENCE_RELEVANCE_RUBRIC: ScoreCriteria;
+export declare function makeEvidenceRelevanceScoreQuestion(claim: string, excerpt: string): ScoreQuestion<typeof EVIDENCE_RELEVANCE_RUBRIC>;
+export declare const DIRECTION_SCORE_RUBRICS: {
+    readonly business_fit: readonly [{
+        readonly score: 0;
+        readonly description: "Mismatch: aesthetic completely conflicts with the business domain and target audience.";
+    }, {
+        readonly score: 1;
+        readonly description: "Generic: generic modern layout without domain personality.";
+    }, {
+        readonly score: 2;
+        readonly description: "Adequate: acceptable styling that does not detract from credibility.";
+    }, {
+        readonly score: 3;
+        readonly description: "Strong: well-tuned aesthetic that builds immediate credibility and industry fit.";
+    }, {
+        readonly score: 4;
+        readonly description: "Exemplary: bespoke vernacular craft perfectly tailored to the business.";
+    }];
+    readonly typography: readonly [{
+        readonly score: 0;
+        readonly description: "Poor: illegible, chaotic, or inappropriate type choices.";
+    }, {
+        readonly score: 1;
+        readonly description: "Bland: default system fonts with weak hierarchy.";
+    }, {
+        readonly score: 2;
+        readonly description: "Functional: clear contrast and readable hierarchy.";
+    }, {
+        readonly score: 3;
+        readonly description: "Refined: intentional font pairing with elegant rhythm and scale.";
+    }, {
+        readonly score: 4;
+        readonly description: "Editorial: publication-grade typographic pacing and bespoke details.";
+    }];
+    readonly composition: readonly [{
+        readonly score: 0;
+        readonly description: "Cluttered: disorganized elements with poor rhythm.";
+    }, {
+        readonly score: 1;
+        readonly description: "Rigid: repetitive card grid without breathing room.";
+    }, {
+        readonly score: 2;
+        readonly description: "Balanced: clean spatial structure and adequate whitespace.";
+    }, {
+        readonly score: 3;
+        readonly description: "Dynamic: intentional pacing, focal points, and visual interest.";
+    }, {
+        readonly score: 4;
+        readonly description: "Harmonious: masterfully balanced visual density and narrative cadence.";
+    }];
+    readonly authenticity: readonly [{
+        readonly score: 0;
+        readonly description: "Stock/AI: feels unmistakably like an automated stock template.";
+    }, {
+        readonly score: 1;
+        readonly description: "Imitative: borrows standard SaaS patterns inappropriately.";
+    }, {
+        readonly score: 2;
+        readonly description: "Honest: straightforward presentation without pretension.";
+    }, {
+        readonly score: 3;
+        readonly description: "Distinctive: distinctive personality grounded in actual customer work.";
+    }, {
+        readonly score: 4;
+        readonly description: "Singular: unforgettable signature identity that could belong to no other business.";
+    }];
+};
+export type DirectionDimension = keyof typeof DIRECTION_SCORE_RUBRICS;
+export declare function makeDirectionScoreQuestion(dimension: DirectionDimension, businessSummary: string, directionSpec: string): ScoreQuestion<any>;
+export declare const MEDIA_RELEVANCE_RUBRIC: ScoreCriteria;
+export declare const FIELD_SELECTION_NO_MATCH = "no_match";
+export declare const FIELD_SELECTION_INSTRUCTION_TEMPLATE = "Select which supplied source span is the value of field `{field}` for this business. Copy a candidate verbatim; do not invent a value. Choose no_match if none of the spans belong to this business or the correct value is absent.";
+export declare const FIELD_CANDIDATE_NOUL_TEMPLATE = "Is the source span at state.{valuePath} a valid `{field}` value that belongs to this business (not a third-party, unrelated, or stale mention)?";
+export declare function makeFieldSelectionQuestion(field: string, candidates: Array<{
+    id: string;
+    value: string;
+    excerpt: string;
+    source: string;
+}>): ChoiceQuestion<Record<string, string>>;
+export declare function makeFieldCandidateNoulQuestion(field: string, candidate: {
+    id: string;
+    value: string;
+    excerpt: string;
+    source: string;
+}): NoulQuestion;
+export declare const FIELD_SELECTION_TASK_SEMANTICS: {
+    readonly task: "field_selection";
+    readonly version: "2026-09-17.2";
+    readonly template: "Select which supplied source span is the value of field `{field}` for this business. Copy a candidate verbatim; do not invent a value. Choose no_match if none of the spans belong to this business or the correct value is absent.";
+    readonly noulTemplate: "Is the source span at state.{valuePath} a valid `{field}` value that belongs to this business (not a third-party, unrelated, or stale mention)?";
+    readonly noMatch: "no_match";
+};
+export declare const FIELD_SELECTION_SEMANTICS_HASH: string;
+export declare function makeMediaRelevanceQuestion(sectionText: string, imageDescription: string): ScoreQuestion<typeof MEDIA_RELEVANCE_RUBRIC>;
+export declare const CLAIM_ERROR_NOUL_TRUE = "This error is present in the supplied assertion relative to the evidence.";
+export declare const CLAIM_ERROR_NOUL_FALSE = "This error is not present.";
+export declare function makeClaimErrorNoulQuestion(errorKind: "unsupported" | "contradiction" | "dropped_qualification" | "exaggerated_strength" | "off_target_evidence", assertion: string, evidence: string): NoulQuestion;
+export declare const CLAIM_ERROR_TASK_SEMANTICS: {
+    version: string;
+    primitive: string;
+    true: string;
+    false: string;
+};
+export declare const CLAIM_ERROR_SEMANTICS_HASH: string;
+export declare function makeIntentCoverageNoulQuestion(question: string, pageText: string): NoulQuestion;
+export declare const INTENT_COVERAGE_TASK_SEMANTICS: {
+    version: string;
+    primitive: string;
+    true: string;
+    false: string;
+};
+export declare const INTENT_COVERAGE_SEMANTICS_HASH: string;
+export declare const CTA_FIDELITY_CRITERIA: {
+    readonly consistent: "The CTA label/promise matches the recorded textual behavior contract.";
+    readonly mismatch: "The CTA label/promise does not match the recorded destination or action (e.g. Schedule pointing at a generic contact form).";
+};
+export declare function makeCtaFidelityQuestion(label: string, behavior: string): ChoiceQuestion<typeof CTA_FIDELITY_CRITERIA>;
+export declare const CTA_FIDELITY_TASK_SEMANTICS: {
+    version: string;
+    primitive: string;
+    criteria: {
+        readonly consistent: "The CTA label/promise matches the recorded textual behavior contract.";
+        readonly mismatch: "The CTA label/promise does not match the recorded destination or action (e.g. Schedule pointing at a generic contact form).";
+    };
+};
+export declare const CTA_FIDELITY_SEMANTICS_HASH: string;
+export declare const CONTINUITY_CRITERIA: {
+    readonly preserved: "The later stage preserves the earlier meaning.";
+    readonly narrowed: "The later stage narrows the earlier meaning without contradicting it.";
+    readonly broadened: "The later stage broadens the earlier meaning.";
+    readonly contradicted: "The later stage contradicts the earlier meaning.";
+    readonly omitted: "The later stage omits the earlier meaning.";
+};
+export declare function makeContinuityQuestion(earlier: string, later: string, edge: string): ChoiceQuestion<typeof CONTINUITY_CRITERIA>;
+export declare const CONTINUITY_TASK_SEMANTICS: {
+    version: string;
+    primitive: string;
+    criteria: {
+        readonly preserved: "The later stage preserves the earlier meaning.";
+        readonly narrowed: "The later stage narrows the earlier meaning without contradicting it.";
+        readonly broadened: "The later stage broadens the earlier meaning.";
+        readonly contradicted: "The later stage contradicts the earlier meaning.";
+        readonly omitted: "The later stage omits the earlier meaning.";
+    };
+};
+export declare const CONTINUITY_SEMANTICS_HASH: string;
+export declare function makeRedundancyNoulQuestion(first: string, second: string): NoulQuestion;
+export declare const CREATIVE_SCORE_RUBRICS: ScoreCriteria;
+export type CreativeDimension = "audience_fit" | "offer_clarity" | "evidence_use" | "visitor_job_coverage" | "distinctive_relevance" | "feasibility";
+export declare function makeCreativeDimensionQuestion(dimension: CreativeDimension, proposal: string, context: string): ScoreQuestion<typeof CREATIVE_SCORE_RUBRICS>;
+export declare const COMPONENT_FIT_RUBRICS: ScoreCriteria;
+export type ComponentFitDimension = "visitor_job" | "slot_fit" | "media_fit" | "composition_fit";
+export declare function makeComponentFitQuestion(dimension: ComponentFitDimension, candidate: string, state: string): ScoreQuestion<typeof COMPONENT_FIT_RUBRICS>;
+export declare function makeRhythmRepetitionQuestion(pageRhythm: string, candidate: string): NoulQuestion;
+export declare const COMPONENT_FIT_TASK_SEMANTICS: {
+    version: string;
+    primitive: string;
+    rubrics: ScoreCriteria;
+};
+export declare const COMPONENT_FIT_SEMANTICS_HASH: string;
+export declare const DIRECTION_DECISION_CRITERIA: {
+    readonly supports: "The textual proposal supports this check.";
+    readonly contradicts: "The textual proposal conflicts with this check.";
+    readonly says_nothing: "The proposal does not contain enough text to decide.";
+};
+export declare const DIRECTION_DECISION_CHECKS: readonly ["hierarchy_serves_goal", "uses_distinctive_evidence", "requires_unavailable_imagery", "alternatives_differ_in_experience", "contradicts_user_constraint"];
+export declare function makeDirectionDecisionQuestion(check: (typeof DIRECTION_DECISION_CHECKS)[number], proposal: string, context: string): ChoiceQuestion<{
+    readonly supports: "The textual proposal supports this check.";
+    readonly contradicts: "The textual proposal conflicts with this check.";
+    readonly says_nothing: "The proposal does not contain enough text to decide.";
+}>;
+export declare const COMPOSITION_REPETITION_CRITERIA: {
+    readonly serves_narrative: "The repeated treatment serves one visitor job or one deliberate list.";
+    readonly unrelated_repetition: "Equal treatment repeats sections that answer different jobs without a rationale.";
+    readonly insufficient_evidence: "The section notes do not say enough to judge repetition.";
+};
+export declare function makeCompositionRepetitionQuestion(pagePath: string, sectionContext: string): ChoiceQuestion<{
+    readonly serves_narrative: "The repeated treatment serves one visitor job or one deliberate list.";
+    readonly unrelated_repetition: "Equal treatment repeats sections that answer different jobs without a rationale.";
+    readonly insufficient_evidence: "The section notes do not say enough to judge repetition.";
+}>;

package/bin/types/src/agent/jev/ranking.d.ts

@@ -0,0 +1,129 @@
+import type { JevClient } from "./client.ts";
+/**
+ * Local lexical / character n-gram cosine similarity retrieval utility.
+ *
+ * NOTE: This is a local algorithmic / lexical helper for evidence slicing and relevance sorting.
+ * It is NOT an evaluated TypeSafe/Jev neural model ranker or Choice/Score model inference endpoint.
+ * Reported token metrics reflect budget formatting bounds rather than demonstrated model-driven token savings.
+ * Cross-stage consistency, focused critic context, typed coverage partitions, and preference scoring remain pending.
+ */
+export interface RankedEvidenceItem {
+    id: string;
+    source: string;
+    excerpt: string;
+    lexicalScore: number;
+    semanticScore: number;
+    combinedScore: number;
+    reason: string;
+    retrievalMethod?: string;
+    jevScore?: number;
+    jevConfidence?: number;
+    probabilities?: Record<string, number>;
+    mandatory?: boolean;
+}
+export interface QueryEmbeddingEntry {
+    query: string;
+    hash: string;
+    vector: Record<string, number>;
+    createdAt: string;
+}
+export declare class QueryEmbeddingCache {
+    private cache;
+    private diskPath?;
+    constructor(diskPath?: string);
+    get(query: string): Record<string, number> | undefined;
+    set(query: string, vector: Record<string, number>): void;
+    size(): number;
+}
+/** Computes character 3-gram and token frequency vector for dense semantic similarity. */
+export declare function computeDenseVector(text: string): Record<string, number>;
+/** Computes cosine similarity between two normalized dense vectors in [0, 1]. */
+export declare function cosineSimilarity(vecA: Record<string, number>, vecB: Record<string, number>): number;
+/** Stage 1: Lexical retrieval using token matching and query term frequency. */
+export declare function lexicalRetrieve<T extends {
+    id: string;
+    source: string;
+    text?: string;
+    excerpt?: string;
+}>(candidates: T[], query: string, limit?: number): T[];
+/** Stage 2: Dense semantic re-ranking with query embedding cache. */
+export declare function semanticRerank<T extends {
+    id: string;
+    source: string;
+    text?: string;
+    excerpt?: string;
+}>(candidates: T[], query: string, options?: {
+    cache?: QueryEmbeddingCache;
+}): RankedEvidenceItem[];
+/**
+ * End-to-end two-stage retrieval and slicing:
+ * 1. Lexical retrieval collects top candidates.
+ * 2. Dense semantic similarity re-ranks candidates against active query.
+ * 3. Compact slicing fits top evidence within token/character budget for critics.
+ */
+export declare function rankAndSliceEvidence<T extends {
+    id: string;
+    source: string;
+    text?: string;
+    excerpt?: string;
+}>(candidates: T[], query: string, options?: {
+    lexicalLimit?: number;
+    maxItems?: number;
+    tokenBudget?: number;
+    cache?: QueryEmbeddingCache;
+    minScore?: number;
+}): {
+    ranked: RankedEvidenceItem[];
+    slicedItems: RankedEvidenceItem[];
+    slicedText: string;
+    totalCandidates: number;
+    droppedCount: number;
+};
+export interface ShortlistRecallResult {
+    recall: number;
+    totalGold: number;
+    coveredGold: number;
+    missedGoldIds: string[];
+}
+/**
+ * Measures whether the shortlisted items cover all claims or evidence items
+ * that have gold-standard relevance in the full candidate set.
+ */
+export declare function measureShortlistRecall<T extends {
+    id: string;
+}>(shortlist: T[], fullCandidates: T[], goldItemIds: string[]): ShortlistRecallResult;
+export declare function identifyMandatoryEvidenceIds(opts: {
+    citedIds?: string[];
+    contradictoryIds?: string[];
+    mandatoryIds?: string[];
+}): string[];
+export interface JevRankedEvidenceResult {
+    ranked: RankedEvidenceItem[];
+    mandatoryIds: string[];
+    contradictoryIds: string[];
+    retrievalMethod: string;
+    judgedCount: number;
+    shortlistCount: number;
+}
+export declare function rankOptionalEvidenceWithJev<T extends {
+    id: string;
+    source: string;
+    text?: string;
+    excerpt?: string;
+}>(opts: {
+    client: JevClient;
+    evidence: T[];
+    claims: Array<{
+        id: string;
+        claim: string;
+        evidenceIds?: string[];
+    }>;
+    query?: string;
+    citedIds?: string[];
+    contradictoryIds?: string[];
+    mandatoryIds?: string[];
+    lexicalLimit?: number;
+    perClaimLimit?: number;
+    nodeId?: string;
+    signal?: AbortSignal;
+}): Promise<JevRankedEvidenceResult>;

package/bin/types/src/agent/jev/repair.d.ts

@@ -0,0 +1,73 @@
+import { type Finding } from "../artifacts.ts";
+import type { AgentState, GraphNode, SkillGraph } from "../graph.ts";
+export interface RepairPacket {
+    nodeId: string;
+    repairTarget: string;
+    failedFindings: Finding[];
+    allowedWrites: string[];
+    preservationInvariants: string[];
+    verificationCommand: string;
+    contextSlice: string;
+    obligationId?: string;
+    findingId?: string;
+}
+/** Determines whether a review finding targets the author node or its writable files. */
+export declare function isFindingApplicable(f: Finding, node: GraphNode, repairTarget: string, graph?: SkillGraph): boolean;
+/**
+ * Builds a focused repair packet containing only active, fresh, applicable failed findings,
+ * allowed writes, and preservation invariants, avoiding full re-read overhead.
+ */
+export interface BuildRepairPacketOptions {
+    root: string;
+    kernel: string;
+    node: GraphNode;
+    state: AgentState;
+    graph?: SkillGraph;
+    obligationId?: string;
+    findingId?: string;
+}
+export declare function buildRepairPacket(opts: BuildRepairPacketOptions): RepairPacket;
+export interface RepairResolutionVerification {
+    resolved: boolean;
+    findingId?: string;
+    obligationId?: string;
+    reason: string;
+    remainingViolations?: string[];
+}
+/**
+ * Verifies whether a repair attempt actually resolved the targeted defect finding.
+ * Catches no-op edits, persistent problem strings, and unmet verification criteria.
+ */
+export declare function verifyRepairResolution(opts: {
+    root: string;
+    finding?: Finding;
+    obligationId?: string;
+    previousArtifactContent?: string;
+    currentArtifactContent?: string;
+    semanticResolved?: boolean;
+    criticDisposition?: boolean;
+}): RepairResolutionVerification;
+export interface DecisionArtifactContext {
+    questionVersion?: string;
+    policyVersion?: string;
+    model?: string;
+    stateHash?: string;
+    evidenceHash?: string;
+}
+/** Determines whether a raw atomic decision can be reused. Policy version is not part of inference identity. */
+export declare function canReuseDecision(cached: DecisionArtifactContext | string | undefined, currentOrEvidenceHash?: DecisionArtifactContext | string, _cachedPolicyVersion?: string): boolean;
+export declare const MAX_IDENTICAL_UNCERTAIN_REPEATS = 1;
+export declare function shouldEscalateRepeatedUncertainty(priorUncertainCount: number): boolean;
+export declare function formatTargetedRepairBlock(opts: {
+    findingId: string;
+    location: string;
+    before: string;
+    sourceSpan: string;
+    verification: string;
+    constraints: string[];
+}): string;
+/** A composition finding is resolved only when the storyboard no longer produces that finding id. */
+export declare function recheckCompositionFinding(root: string, findingId: string): {
+    resolved: boolean;
+    reason: string;
+};