@kodr/aiwrangler 0.0.0-stage → 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,697 @@
+import { z } from 'zod';
+
+type SourceKind = "spec" | "rule" | "divergence" | "question" | "door" | "paper" | "doc";
+type EntryStatus = "ruled" | "open" | "answered" | "info";
+interface CorpusSection {
+    id: string;
+    kind: SourceKind;
+    title: string;
+    text: string;
+    source: string;
+    status: EntryStatus;
+    ruling?: string;
+    paperRef?: string;
+    precedence: number;
+}
+interface CorpusSource {
+    path: string;
+    hash: string;
+}
+interface Corpus {
+    sections: CorpusSection[];
+    sources: CorpusSource[];
+    hash: string;
+    paperText: string;
+}
+declare const PRECEDENCE: {
+    readonly ruling: 0;
+    readonly paper: 1;
+    readonly door: 1;
+    readonly spec: 2;
+    readonly doc: 3;
+    readonly nonRuling: 4;
+};
+type Severity = "block" | "review" | "human";
+interface DiffLine {
+    kind: "add" | "del" | "ctx";
+    text: string;
+    newLine?: number;
+    oldLine?: number;
+}
+interface DiffHunk {
+    header: string;
+    lines: DiffLine[];
+}
+interface DiffFile {
+    path: string;
+    oldPath?: string;
+    binary: boolean;
+    hunks: DiffHunk[];
+}
+interface RepoDiff {
+    repo: string;
+    repoDir: string;
+    files: DiffFile[];
+}
+interface Finding {
+    rule: string;
+    severity: Severity;
+    repo: string;
+    file: string;
+    line: number | null;
+    evidence: string;
+    note: string;
+    kind?: "deterministic" | "semantic";
+    confidence?: number;
+    noul?: number;
+    acknowledged?: boolean;
+}
+
+declare const RuntimeOverridesSchema: z.ZodObject<{
+    activePolicy: z.ZodOptional<z.ZodString>;
+    egressSemantic: z.ZodOptional<z.ZodBoolean>;
+    actionThreshold: z.ZodOptional<z.ZodNumber>;
+    reviewThreshold: z.ZodOptional<z.ZodNumber>;
+    gates: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodBoolean>>;
+}, "strip", z.ZodTypeAny, {
+    activePolicy?: string | undefined;
+    egressSemantic?: boolean | undefined;
+    actionThreshold?: number | undefined;
+    reviewThreshold?: number | undefined;
+    gates?: Record<string, boolean> | undefined;
+}, {
+    activePolicy?: string | undefined;
+    egressSemantic?: boolean | undefined;
+    actionThreshold?: number | undefined;
+    reviewThreshold?: number | undefined;
+    gates?: Record<string, boolean> | undefined;
+}>;
+type RuntimeOverrides = z.infer<typeof RuntimeOverridesSchema>;
+
+declare const ConfigSchema: z.ZodObject<{
+    model: z.ZodDefault<z.ZodString>;
+    activePolicy: z.ZodDefault<z.ZodString>;
+    egress: z.ZodDefault<z.ZodObject<{
+        semantic: z.ZodDefault<z.ZodBoolean>;
+        warnOncePerSession: z.ZodDefault<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        semantic: boolean;
+        warnOncePerSession: boolean;
+    }, {
+        semantic?: boolean | undefined;
+        warnOncePerSession?: boolean | undefined;
+    }>>;
+    corpus: z.ZodDefault<z.ZodObject<{
+        spec: z.ZodDefault<z.ZodString>;
+        rules: z.ZodDefault<z.ZodString>;
+        divergences: z.ZodDefault<z.ZodString>;
+        questions: z.ZodDefault<z.ZodString>;
+        plan: z.ZodDefault<z.ZodString>;
+        docs: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        whitepaper: z.ZodDefault<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        spec: string;
+        rules: string;
+        divergences: string;
+        questions: string;
+        plan: string;
+        docs: string[];
+        whitepaper: string;
+    }, {
+        spec?: string | undefined;
+        rules?: string | undefined;
+        divergences?: string | undefined;
+        questions?: string | undefined;
+        plan?: string | undefined;
+        docs?: string[] | undefined;
+        whitepaper?: string | undefined;
+    }>>;
+    gates: z.ZodDefault<z.ZodObject<{
+        plan: z.ZodDefault<z.ZodObject<{
+            inSpec: z.ZodDefault<z.ZodBoolean>;
+            ambiguity: z.ZodDefault<z.ZodBoolean>;
+            openQuestions: z.ZodDefault<z.ZodBoolean>;
+            oneWayDoors: z.ZodDefault<z.ZodBoolean>;
+        }, "strip", z.ZodTypeAny, {
+            inSpec: boolean;
+            ambiguity: boolean;
+            openQuestions: boolean;
+            oneWayDoors: boolean;
+        }, {
+            inSpec?: boolean | undefined;
+            ambiguity?: boolean | undefined;
+            openQuestions?: boolean | undefined;
+            oneWayDoors?: boolean | undefined;
+        }>>;
+        retrieval: z.ZodDefault<z.ZodObject<{
+            rerank: z.ZodDefault<z.ZodBoolean>;
+            topK: z.ZodDefault<z.ZodNumber>;
+        }, "strip", z.ZodTypeAny, {
+            rerank: boolean;
+            topK: number;
+        }, {
+            rerank?: boolean | undefined;
+            topK?: number | undefined;
+        }>>;
+        check: z.ZodDefault<z.ZodObject<{
+            deterministic: z.ZodDefault<z.ZodBoolean>;
+            battery: z.ZodDefault<z.ZodBoolean>;
+            selfReport: z.ZodDefault<z.ZodBoolean>;
+            testQuality: z.ZodDefault<z.ZodBoolean>;
+            docDrift: z.ZodDefault<z.ZodBoolean>;
+            injectionDefense: z.ZodDefault<z.ZodBoolean>;
+        }, "strip", z.ZodTypeAny, {
+            deterministic: boolean;
+            battery: boolean;
+            selfReport: boolean;
+            testQuality: boolean;
+            docDrift: boolean;
+            injectionDefense: boolean;
+        }, {
+            deterministic?: boolean | undefined;
+            battery?: boolean | undefined;
+            selfReport?: boolean | undefined;
+            testQuality?: boolean | undefined;
+            docDrift?: boolean | undefined;
+            injectionDefense?: boolean | undefined;
+        }>>;
+        security: z.ZodDefault<z.ZodObject<{
+            trustBoundary: z.ZodDefault<z.ZodBoolean>;
+            severity: z.ZodDefault<z.ZodBoolean>;
+            alwaysHuman: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        }, "strip", z.ZodTypeAny, {
+            trustBoundary: boolean;
+            severity: boolean;
+            alwaysHuman: string[];
+        }, {
+            trustBoundary?: boolean | undefined;
+            severity?: boolean | undefined;
+            alwaysHuman?: string[] | undefined;
+        }>>;
+        loop: z.ZodDefault<z.ZodObject<{
+            retryProgress: z.ZodDefault<z.ZodBoolean>;
+            errorSalience: z.ZodDefault<z.ZodBoolean>;
+            maxCycles: z.ZodDefault<z.ZodNumber>;
+        }, "strip", z.ZodTypeAny, {
+            retryProgress: boolean;
+            errorSalience: boolean;
+            maxCycles: number;
+        }, {
+            retryProgress?: boolean | undefined;
+            errorSalience?: boolean | undefined;
+            maxCycles?: number | undefined;
+        }>>;
+        session: z.ZodDefault<z.ZodObject<{
+            endAudit: z.ZodDefault<z.ZodBoolean>;
+            nudge: z.ZodDefault<z.ZodBoolean>;
+            maxNudges: z.ZodDefault<z.ZodNumber>;
+        }, "strip", z.ZodTypeAny, {
+            endAudit: boolean;
+            nudge: boolean;
+            maxNudges: number;
+        }, {
+            endAudit?: boolean | undefined;
+            nudge?: boolean | undefined;
+            maxNudges?: number | undefined;
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        plan: {
+            inSpec: boolean;
+            ambiguity: boolean;
+            openQuestions: boolean;
+            oneWayDoors: boolean;
+        };
+        retrieval: {
+            rerank: boolean;
+            topK: number;
+        };
+        check: {
+            deterministic: boolean;
+            battery: boolean;
+            selfReport: boolean;
+            testQuality: boolean;
+            docDrift: boolean;
+            injectionDefense: boolean;
+        };
+        security: {
+            trustBoundary: boolean;
+            severity: boolean;
+            alwaysHuman: string[];
+        };
+        loop: {
+            retryProgress: boolean;
+            errorSalience: boolean;
+            maxCycles: number;
+        };
+        session: {
+            endAudit: boolean;
+            nudge: boolean;
+            maxNudges: number;
+        };
+    }, {
+        plan?: {
+            inSpec?: boolean | undefined;
+            ambiguity?: boolean | undefined;
+            openQuestions?: boolean | undefined;
+            oneWayDoors?: boolean | undefined;
+        } | undefined;
+        retrieval?: {
+            rerank?: boolean | undefined;
+            topK?: number | undefined;
+        } | undefined;
+        check?: {
+            deterministic?: boolean | undefined;
+            battery?: boolean | undefined;
+            selfReport?: boolean | undefined;
+            testQuality?: boolean | undefined;
+            docDrift?: boolean | undefined;
+            injectionDefense?: boolean | undefined;
+        } | undefined;
+        security?: {
+            trustBoundary?: boolean | undefined;
+            severity?: boolean | undefined;
+            alwaysHuman?: string[] | undefined;
+        } | undefined;
+        loop?: {
+            retryProgress?: boolean | undefined;
+            errorSalience?: boolean | undefined;
+            maxCycles?: number | undefined;
+        } | undefined;
+        session?: {
+            endAudit?: boolean | undefined;
+            nudge?: boolean | undefined;
+            maxNudges?: number | undefined;
+        } | undefined;
+    }>>;
+    policies: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
+        actionThreshold: z.ZodDefault<z.ZodNumber>;
+        reviewThreshold: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        actionThreshold: number;
+        reviewThreshold: number;
+    }, {
+        actionThreshold?: number | undefined;
+        reviewThreshold?: number | undefined;
+    }>>>;
+    cache: z.ZodDefault<z.ZodObject<{
+        dir: z.ZodDefault<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        dir: string;
+    }, {
+        dir?: string | undefined;
+    }>>;
+    ledger: z.ZodDefault<z.ZodObject<{
+        path: z.ZodDefault<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        path: string;
+    }, {
+        path?: string | undefined;
+    }>>;
+    repos: z.ZodDefault<z.ZodObject<{
+        super: z.ZodDefault<z.ZodString>;
+        members: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        reviewed: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        super: string;
+        members: string[];
+        reviewed: string[];
+    }, {
+        super?: string | undefined;
+        members?: string[] | undefined;
+        reviewed?: string[] | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    activePolicy: string;
+    gates: {
+        plan: {
+            inSpec: boolean;
+            ambiguity: boolean;
+            openQuestions: boolean;
+            oneWayDoors: boolean;
+        };
+        retrieval: {
+            rerank: boolean;
+            topK: number;
+        };
+        check: {
+            deterministic: boolean;
+            battery: boolean;
+            selfReport: boolean;
+            testQuality: boolean;
+            docDrift: boolean;
+            injectionDefense: boolean;
+        };
+        security: {
+            trustBoundary: boolean;
+            severity: boolean;
+            alwaysHuman: string[];
+        };
+        loop: {
+            retryProgress: boolean;
+            errorSalience: boolean;
+            maxCycles: number;
+        };
+        session: {
+            endAudit: boolean;
+            nudge: boolean;
+            maxNudges: number;
+        };
+    };
+    model: string;
+    egress: {
+        semantic: boolean;
+        warnOncePerSession: boolean;
+    };
+    corpus: {
+        spec: string;
+        rules: string;
+        divergences: string;
+        questions: string;
+        plan: string;
+        docs: string[];
+        whitepaper: string;
+    };
+    policies: Record<string, {
+        actionThreshold: number;
+        reviewThreshold: number;
+    }>;
+    cache: {
+        dir: string;
+    };
+    ledger: {
+        path: string;
+    };
+    repos: {
+        super: string;
+        members: string[];
+        reviewed: string[];
+    };
+}, {
+    activePolicy?: string | undefined;
+    gates?: {
+        plan?: {
+            inSpec?: boolean | undefined;
+            ambiguity?: boolean | undefined;
+            openQuestions?: boolean | undefined;
+            oneWayDoors?: boolean | undefined;
+        } | undefined;
+        retrieval?: {
+            rerank?: boolean | undefined;
+            topK?: number | undefined;
+        } | undefined;
+        check?: {
+            deterministic?: boolean | undefined;
+            battery?: boolean | undefined;
+            selfReport?: boolean | undefined;
+            testQuality?: boolean | undefined;
+            docDrift?: boolean | undefined;
+            injectionDefense?: boolean | undefined;
+        } | undefined;
+        security?: {
+            trustBoundary?: boolean | undefined;
+            severity?: boolean | undefined;
+            alwaysHuman?: string[] | undefined;
+        } | undefined;
+        loop?: {
+            retryProgress?: boolean | undefined;
+            errorSalience?: boolean | undefined;
+            maxCycles?: number | undefined;
+        } | undefined;
+        session?: {
+            endAudit?: boolean | undefined;
+            nudge?: boolean | undefined;
+            maxNudges?: number | undefined;
+        } | undefined;
+    } | undefined;
+    model?: string | undefined;
+    egress?: {
+        semantic?: boolean | undefined;
+        warnOncePerSession?: boolean | undefined;
+    } | undefined;
+    corpus?: {
+        spec?: string | undefined;
+        rules?: string | undefined;
+        divergences?: string | undefined;
+        questions?: string | undefined;
+        plan?: string | undefined;
+        docs?: string[] | undefined;
+        whitepaper?: string | undefined;
+    } | undefined;
+    policies?: Record<string, {
+        actionThreshold?: number | undefined;
+        reviewThreshold?: number | undefined;
+    }> | undefined;
+    cache?: {
+        dir?: string | undefined;
+    } | undefined;
+    ledger?: {
+        path?: string | undefined;
+    } | undefined;
+    repos?: {
+        super?: string | undefined;
+        members?: string[] | undefined;
+        reviewed?: string[] | undefined;
+    } | undefined;
+}>;
+type Config = z.infer<typeof ConfigSchema>;
+type GatePath = string;
+interface LoadedConfig {
+    config: Config;
+    root: string;
+    source: "explicit" | "discovered" | "user" | "defaults";
+    path: string | null;
+    overrides: RuntimeOverrides | null;
+}
+declare function expandPath(p: string, root: string): string;
+declare function findConfigFile(startDir: string): {
+    path: string;
+    source: "discovered" | "user";
+} | null;
+declare function flattenGates(config: Config): Map<GatePath, boolean>;
+declare function applyGateFlag(config: Config, name: string, value: boolean): string[];
+declare function applyEnvOverrides(config: Config, env?: Record<string, string | undefined>): Config;
+declare function loadConfig(startDir: string, env?: Record<string, string | undefined>): LoadedConfig;
+declare function activeThresholds(config: Config): {
+    actionThreshold: number;
+    reviewThreshold: number;
+};
+
+declare function stripJsonc(text: string): string;
+declare function parseJsonc(text: string): unknown;
+
+declare function sha256Hex(text: string): string;
+declare function shortHash(text: string): string;
+
+interface MdSection {
+    level: number;
+    title: string;
+    text: string;
+    line: number;
+}
+declare function splitMarkdown(md: string): MdSection[];
+declare function slug(title: string): string;
+
+declare function parseSpec(md: string, source: string): CorpusSection[];
+declare function parseRules(md: string, source: string): CorpusSection[];
+declare function parseDivergences(md: string, source: string): CorpusSection[];
+declare function parseQuestions(md: string, source: string): CorpusSection[];
+declare function parsePlan(md: string, source: string): CorpusSection[];
+declare function parseDoc(md: string, source: string, label: string): CorpusSection[];
+declare function parsePaper(text: string, source: string): CorpusSection[];
+
+declare function ensurePaperText(config: Config, root: string): {
+    text: string | null;
+    extracted: boolean;
+};
+
+declare function loadCorpus(config: Config, root: string): Corpus;
+declare function loadCorpusFrom(startDir: string): {
+    loaded: LoadedConfig;
+    corpus: Corpus;
+};
+
+type JevValue = {
+    kind: "noul";
+    noul: number;
+} | {
+    kind: "choice";
+    choice: string;
+    confidence: number;
+    probabilities: Record<string, number>;
+} | {
+    kind: "score";
+    score: number;
+    confidence: number;
+    probabilities: Record<string, number>;
+};
+interface JevResult {
+    model: string;
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+    answers: Record<string, JevValue>;
+    cached?: boolean;
+}
+interface JevUnavailable {
+    ok: false;
+    reason: "egress-off" | "no-key";
+}
+declare class Jev {
+    private client;
+    readonly model: string;
+    private readonly semantic;
+    private readonly warnOnce;
+    private readonly keyPresent;
+    private readonly cache;
+    constructor(config: Config, opts?: {
+        cacheDir?: string;
+        cacheEnabled?: boolean;
+    });
+    unavailable(): JevUnavailable | null;
+    private ensure;
+    ask(state: unknown, questions: Record<string, unknown>, opts?: {
+        signal?: AbortSignal;
+        timeoutMs?: number;
+    }): Promise<JevResult>;
+}
+
+interface PlanInput {
+    task: string;
+    plan?: string;
+}
+interface PlanVerdict {
+    question: string;
+    label: string;
+    noul: number;
+    interpretation: "definite" | "possible" | "clear" | "unlikely";
+    subject?: string;
+}
+type PlanAction = "pass" | "clarify" | "human";
+interface PlanReport {
+    action: PlanAction;
+    degraded: boolean;
+    degradedReason?: string;
+    contextPack: {
+        sections: CorpusSection[];
+        rulings: CorpusSection[];
+        openItems: CorpusSection[];
+        doors: CorpusSection[];
+    };
+    verdicts: PlanVerdict[];
+    reasons: string[];
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+}
+declare function runPlanGate(config: Config, jev: Jev, corpus: Corpus, input: PlanInput, opts?: {
+    signal?: AbortSignal;
+}): Promise<PlanReport>;
+
+interface CargoStep {
+    label: string;
+    ok: boolean;
+    summary: string;
+    errors: string[];
+    output: string;
+}
+interface Diagnostic {
+    file: string;
+    line: number | null;
+    col: number | null;
+    severity: string;
+    message: string;
+    code: string | null;
+    isRootCauseCandidate: boolean;
+}
+
+interface DeterministicReport {
+    repoDiffs: RepoDiff[];
+    findings: Finding[];
+    cargo: {
+        repo: string;
+        steps: CargoStep[];
+    }[];
+}
+
+interface CheckInput {
+    diffs: RepoDiff[];
+    task?: string;
+    claims?: string[];
+    agentSummary?: string;
+    toolOutput?: string;
+    previousReasons?: string[];
+}
+interface SemanticVerdict {
+    question: string;
+    label: string;
+    value: number;
+    confidence?: number;
+    subject?: string;
+}
+interface SemanticReport {
+    findings: Finding[];
+    verdicts: SemanticVerdict[];
+    sections: CorpusSection[];
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+    examinedFiles: number;
+}
+
+interface RootCauseResult {
+    root: Diagnostic | null;
+    cascade: Diagnostic[];
+    usedJev: boolean;
+}
+
+interface CheckOptions extends Omit<CheckInput, "diffs"> {
+    cargo?: boolean;
+    tests?: boolean;
+    diffs?: RepoDiff[];
+    sessionID?: string;
+}
+type CheckAction = "pass" | "fix" | "human" | "degraded";
+interface CheckReport {
+    action: CheckAction;
+    degraded: boolean;
+    degradedReason?: string;
+    deterministic: DeterministicReport;
+    semantic: SemanticReport | null;
+    rootCause: RootCauseResult | null;
+    diagnostics: Diagnostic[];
+    loop: {
+        cycle: number;
+        escalated: boolean;
+        reason?: string;
+    };
+    reasons: string[];
+    exitCode: number;
+    corpusHash: string;
+    sessionID?: string;
+    diffHash?: string;
+    files: {
+        repo: string;
+        path: string;
+        added: number;
+        removed: number;
+    }[];
+    examinedFiles: number | null;
+    overridesActive: boolean;
+    acknowledged: number;
+}
+declare function runCheck(config: Config, root: string, corpus: Corpus, jev: Jev, opts: CheckOptions): Promise<CheckReport>;
+declare function formatReport(report: CheckReport): string;
+
+declare function checkRepoDiff(diff: RepoDiff, config: Config): Finding[];
+declare function checkCommitMessage(message: string, repo: string): Finding[];
+
+declare function sectionById(corpus: Corpus, id: string): CorpusSection | undefined;
+declare function sectionsOfKind(corpus: Corpus, kind: CorpusSection["kind"]): CorpusSection[];
+declare function effectiveTruth(corpus: Corpus): CorpusSection[];
+declare function paperSectionForSpec(corpus: Corpus, spec: CorpusSection): CorpusSection | undefined;
+declare function authoritativeFor(conflicting: CorpusSection, corpus: Corpus): CorpusSection | null;
+
+export { type Config, ConfigSchema, type Corpus, type CorpusSection, type CorpusSource, type DiffFile, type DiffHunk, type DiffLine, type EntryStatus, type Finding, type GatePath, type LoadedConfig, PRECEDENCE, type RepoDiff, type Severity, type SourceKind, activeThresholds, applyEnvOverrides, applyGateFlag, authoritativeFor, checkCommitMessage, checkRepoDiff, effectiveTruth, ensurePaperText, expandPath, findConfigFile, flattenGates, formatReport, loadConfig, loadCorpus, loadCorpusFrom, paperSectionForSpec, parseDivergences, parseDoc, parseJsonc, parsePaper, parsePlan, parseQuestions, parseRules, parseSpec, runCheck, runPlanGate, sectionById, sectionsOfKind, sha256Hex, shortHash, slug, splitMarkdown, stripJsonc };