@oscharko-dev/keiko-workflows 0.2.0

package/dist/contextpack/reranker.d.ts

@@ -0,0 +1,15 @@
+import type { CandidateFile, EvidenceAtom } from "@oscharko-dev/keiko-contracts/connected-context";
+export type RerankerAvailability = {
+    readonly available: true;
+    readonly modelLabel: string;
+} | {
+    readonly available: false;
+    readonly reason: string;
+};
+export interface RerankerSeam {
+    readonly name: string;
+    isAvailable(): Promise<RerankerAvailability>;
+    rerank(candidates: readonly CandidateFile[], atomsByPath: ReadonlyMap<string, readonly EvidenceAtom[]>, topK: number): Promise<readonly CandidateFile[]>;
+}
+export declare const disabledReranker: RerankerSeam;
+//# sourceMappingURL=reranker.d.ts.map

package/dist/contextpack/reranker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reranker.d.ts","sourceRoot":"","sources":["../../src/contextpack/reranker.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,iDAAiD,CAAC;AAEnG,MAAM,MAAM,oBAAoB,GAC5B;IAAE,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GACzD;IAAE,QAAQ,CAAC,SAAS,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3D,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,WAAW,IAAI,OAAO,CAAC,oBAAoB,CAAC,CAAC;IAC7C,MAAM,CACJ,UAAU,EAAE,SAAS,aAAa,EAAE,EACpC,WAAW,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,CAAC,EACzD,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,SAAS,aAAa,EAAE,CAAC,CAAC;CACtC;AA2BD,eAAO,MAAM,gBAAgB,EAAE,YAI9B,CAAC"}

package/dist/contextpack/reranker.js

@@ -0,0 +1,31 @@
+// Optional semantic reranker seam for the connected-context assembler (Epic #177,
+// Issue #183). Interface ONLY — no live model calls in this PR. A future PR will add a
+// keiko-model-gateway-backed implementation behind capability + privacy + budget guards.
+// The default `disabledReranker` is always unavailable and the assembler treats that as
+// "skip reranking" rather than as an error.
+// No `await` in the body — use the resolve/reject pattern from prior PRs to avoid the
+// `@typescript-eslint/require-await` lint while preserving the async surface.
+function unavailable() {
+    try {
+        return Promise.resolve({
+            available: false,
+            reason: "reranker-not-configured",
+        });
+    }
+    catch (error) {
+        return Promise.reject(error instanceof Error ? error : new Error(String(error)));
+    }
+}
+function identity(candidates, _atomsByPath, _topK) {
+    try {
+        return Promise.resolve(candidates);
+    }
+    catch (error) {
+        return Promise.reject(error instanceof Error ? error : new Error(String(error)));
+    }
+}
+export const disabledReranker = {
+    name: "disabled-reranker",
+    isAvailable: unavailable,
+    rerank: identity,
+};

package/dist/descriptor.d.ts

@@ -0,0 +1,2 @@
+export type { WorkflowDescriptor, WorkflowInputSpec } from "@oscharko-dev/keiko-contracts";
+//# sourceMappingURL=descriptor.d.ts.map

package/dist/descriptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"descriptor.d.ts","sourceRoot":"","sources":["../src/descriptor.ts"],"names":[],"mappings":"AACA,YAAY,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC"}

package/dist/descriptor.js

@@ -0,0 +1 @@
+export {};

package/dist/governed-handoff.d.ts

@@ -0,0 +1,6 @@
+import { type ProposedPatchEntry, type WorkflowHandoffRequest } from "@oscharko-dev/keiko-contracts/workflow-handoff";
+import type { PatchValidation, WorkspaceWriter } from "@oscharko-dev/keiko-tools";
+export declare function proposedPatchEntriesFromValidation(validation: PatchValidation): readonly ProposedPatchEntry[];
+export declare function governedPatchRejectionCode(handoff: WorkflowHandoffRequest | undefined, validation: PatchValidation): string | undefined;
+export declare function createScopedWriter(baseWriter: WorkspaceWriter, workspaceRoot: string, editablePaths: readonly string[]): WorkspaceWriter;
+//# sourceMappingURL=governed-handoff.d.ts.map

package/dist/governed-handoff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"governed-handoff.d.ts","sourceRoot":"","sources":["../src/governed-handoff.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,kBAAkB,EACvB,KAAK,sBAAsB,EAC5B,MAAM,gDAAgD,CAAC;AACxD,OAAO,KAAK,EAAmB,eAAe,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAwCnG,wBAAgB,kCAAkC,CAChD,UAAU,EAAE,eAAe,GAC1B,SAAS,kBAAkB,EAAE,CAkB/B;AAED,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,sBAAsB,GAAG,SAAS,EAC3C,UAAU,EAAE,eAAe,GAC1B,MAAM,GAAG,SAAS,CASpB;AAED,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,eAAe,EAC3B,aAAa,EAAE,MAAM,EACrB,aAAa,EAAE,SAAS,MAAM,EAAE,GAC/B,eAAe,CA4BjB"}

package/dist/governed-handoff.js

@@ -0,0 +1,86 @@
+import { sep } from "node:path";
+import { checkPatchAgainstScope, } from "@oscharko-dev/keiko-contracts/workflow-handoff";
+import { resolveWithinWorkspace } from "@oscharko-dev/keiko-workspace";
+function fileHeader(file) {
+    if (file.kind === "create") {
+        return ["--- /dev/null", `+++ b/${file.path}`];
+    }
+    if (file.kind === "delete") {
+        return [`--- a/${file.path}`, "+++ /dev/null"];
+    }
+    return [`--- a/${file.path}`, `+++ b/${file.path}`];
+}
+function filePatchBytes(file) {
+    const lines = [...fileHeader(file)];
+    for (const hunk of file.hunks) {
+        lines.push(`@@ -${String(hunk.oldStart)},${String(hunk.oldLines)} +${String(hunk.newStart)},${String(hunk.newLines)} @@`);
+        lines.push(...hunk.lines);
+    }
+    return Buffer.byteLength(lines.join("\n"), "utf8");
+}
+function absoluteEditablePaths(workspaceRoot, editablePaths) {
+    return new Set(editablePaths.map((path) => resolveWithinWorkspace(workspaceRoot, path)));
+}
+function canCreateDirectory(dir, allowedFiles) {
+    for (const allowed of allowedFiles) {
+        if (allowed === dir || allowed.startsWith(`${dir}${sep}`)) {
+            return true;
+        }
+    }
+    return false;
+}
+export function proposedPatchEntriesFromValidation(validation) {
+    if (validation.files.length === 0) {
+        return [];
+    }
+    const entries = validation.files.map((file) => ({
+        path: file.path,
+        newFile: file.kind === "create",
+        patchBytes: filePatchBytes(file),
+    }));
+    const observed = entries.reduce((sum, entry) => sum + entry.patchBytes, 0);
+    const delta = Math.max(0, validation.totalBytes - observed);
+    if (delta > 0) {
+        const last = entries[entries.length - 1];
+        if (last !== undefined) {
+            last.patchBytes += delta;
+        }
+    }
+    return entries;
+}
+export function governedPatchRejectionCode(handoff, validation) {
+    if (handoff === undefined) {
+        return undefined;
+    }
+    const scopeCheck = checkPatchAgainstScope(handoff.patchScope, proposedPatchEntriesFromValidation(validation));
+    return scopeCheck.ok ? undefined : "out-of-scope";
+}
+export function createScopedWriter(baseWriter, workspaceRoot, editablePaths) {
+    const allowedFiles = absoluteEditablePaths(workspaceRoot, editablePaths);
+    const assertAllowed = (absolutePath) => {
+        if (!allowedFiles.has(absolutePath)) {
+            throw new Error(`Patch scope forbids writing ${absolutePath}`);
+        }
+    };
+    return {
+        writeFileUtf8(absolutePath, content) {
+            assertAllowed(absolutePath);
+            baseWriter.writeFileUtf8(absolutePath, content);
+        },
+        mkdirp(absoluteDir) {
+            if (!canCreateDirectory(absoluteDir, allowedFiles)) {
+                throw new Error(`Patch scope forbids creating ${absoluteDir}`);
+            }
+            baseWriter.mkdirp(absoluteDir);
+        },
+        remove(absolutePath) {
+            assertAllowed(absolutePath);
+            baseWriter.remove(absolutePath);
+        },
+        rename(fromAbsolute, toAbsolute) {
+            assertAllowed(fromAbsolute);
+            assertAllowed(toAbsolute);
+            baseWriter.rename(fromAbsolute, toAbsolute);
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export type { WorkflowDescriptor, WorkflowInputSpec } from "./descriptor.js";
+export * from "./unit-tests/index.js";
+export * from "./bug-investigation/index.js";
+export * from "./planner/index.js";
+export * from "./ranking/index.js";
+export * from "./contextpack/index.js";
+export * from "./qualityIntelligence/index.js";
+export * from "./promptEnhancer/index.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAUA,YAAY,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAE7E,cAAc,uBAAuB,CAAC;AACtC,cAAc,8BAA8B,CAAC;AAG7C,cAAc,oBAAoB,CAAC;AAGnC,cAAc,oBAAoB,CAAC;AAGnC,cAAc,wBAAwB,CAAC;AAIvC,cAAc,gCAAgC,CAAC;AAG/C,cAAc,2BAA2B,CAAC"}

package/dist/index.js

@@ -0,0 +1,13 @@
+export * from "./unit-tests/index.js";
+export * from "./bug-investigation/index.js";
+// ─── Exploration planner & budget governor (Issue #181 / Epic #177) ──────────
+export * from "./planner/index.js";
+// ─── Candidate ranking & negative context filter (Issue #182 / Epic #177) ────
+export * from "./ranking/index.js";
+// ─── Context-pack assembler & micro-index (Issue #183 / Epic #177) ──────────
+export * from "./contextpack/index.js";
+// ─── Quality Intelligence workflow execution (Epic #270, Issue #273/#279) ────
+// Scripted + model-routed run entries, descriptors, cancellation, and the run-lifecycle types.
+export * from "./qualityIntelligence/index.js";
+// ─── Prompt Enhancer workflow execution (Epic #1307, Issue #1314) ─────────────
+export * from "./promptEnhancer/index.js";

package/dist/planner/anchors.d.ts

@@ -0,0 +1,17 @@
+export type SearchAnchorKind = "literal" | "identifier" | "path" | "quoted";
+export interface SearchAnchor {
+    readonly term: string;
+    readonly weight: number;
+    readonly kind: SearchAnchorKind;
+}
+export interface AnchorExtractionInput {
+    readonly text: string;
+    readonly maxAnchors: number;
+}
+export interface AnchorExtractionResult {
+    readonly anchors: readonly SearchAnchor[];
+    readonly truncated: boolean;
+    readonly tokensConsidered: number;
+}
+export declare function extractAnchors(input: AnchorExtractionInput): AnchorExtractionResult;
+//# sourceMappingURL=anchors.d.ts.map

package/dist/planner/anchors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"anchors.d.ts","sourceRoot":"","sources":["../../src/planner/anchors.ts"],"names":[],"mappings":"AA+LA,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,YAAY,GAAG,MAAM,GAAG,QAAQ,CAAC;AAE5E,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;CACjC;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,CAAC;IAC1C,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;CACnC;AAgHD,wBAAgB,cAAc,CAAC,KAAK,EAAE,qBAAqB,GAAG,sBAAsB,CAoBnF"}

package/dist/planner/anchors.js

@@ -0,0 +1,291 @@
+// Deterministic search-anchor extraction for the exploration planner (Epic #177, Issue #181).
+// Pure JS — no IO, no clock, no randomness. Given free-form prompt text, this module produces
+// a small, stable, weight-ordered set of search anchors. The stop-word list is intentionally
+// fixed and English-only; expanding language coverage is a follow-up issue.
+const MAX_INPUT_LENGTH = 4096;
+const STOP_WORDS = new Set([
+    "the",
+    "and",
+    "for",
+    "with",
+    "from",
+    "this",
+    "that",
+    "what",
+    "where",
+    "when",
+    "which",
+    "have",
+    "has",
+    "had",
+    "are",
+    "was",
+    "were",
+    "is",
+    "be",
+    "been",
+    "being",
+    "do",
+    "does",
+    "did",
+    "doing",
+    "of",
+    "in",
+    "on",
+    "at",
+    "to",
+    "an",
+    "as",
+    "or",
+    "but",
+    "not",
+    "no",
+    "yes",
+    "if",
+    "by",
+    "it",
+    "its",
+    "you",
+    "your",
+    "we",
+    "our",
+    "they",
+    "their",
+    "them",
+    "he",
+    "she",
+    "his",
+    "her",
+    "my",
+    "me",
+    "i",
+    "us",
+    "how",
+    "why",
+    "who",
+    "whom",
+    "whose",
+    "than",
+    "then",
+    "there",
+    "can",
+    "could",
+    "would",
+    "should",
+    "may",
+    "might",
+    "must",
+    "will",
+    "so",
+    "such",
+    "any",
+    "all",
+    "some",
+    "every",
+    "each",
+    "aber",
+    "alle",
+    "als",
+    "am",
+    "an",
+    "auch",
+    "auf",
+    "aus",
+    "bei",
+    "bin",
+    "bis",
+    "bitte",
+    "da",
+    "das",
+    "dass",
+    "dein",
+    "deine",
+    "dem",
+    "den",
+    "der",
+    "des",
+    "die",
+    "dir",
+    "du",
+    "durch",
+    "ein",
+    "eine",
+    "einem",
+    "einen",
+    "einer",
+    "es",
+    "für",
+    "habe",
+    "haben",
+    "hat",
+    "ich",
+    "im",
+    "ist",
+    "kann",
+    "kannst",
+    "kein",
+    "keine",
+    "mit",
+    "mir",
+    "nach",
+    "nicht",
+    "noch",
+    "oder",
+    "sagen",
+    "sind",
+    "und",
+    "uns",
+    "von",
+    "war",
+    "was",
+    "welche",
+    "welchen",
+    "welcher",
+    "welches",
+    "wenn",
+    "wer",
+    "wie",
+    "wir",
+    "wird",
+    "wo",
+    "zu",
+    "zum",
+    "zur",
+]);
+// Module-scope regex pool. Each pattern uses character classes only (no nested quantifiers),
+// so scanning is linear in input length — ReDoS-safe.
+const QUOTED_DOUBLE_RE = /"([^"\n]+)"/g;
+const QUOTED_SINGLE_RE = /'([^'\n]+)'/g;
+const BACKTICK_RE = /`([^`\n]+)`/g;
+const PATH_RE = /(?:[\w.-]+\/)+[\w.-]+\.[A-Za-z]{1,8}/g;
+// Requires a genuine lower/digit -> upper transition so all-caps acronyms and SHOUTING words
+// (WHY, HTTP, BROKEN) are NOT mistaken for code identifiers. A spurious 0.85 identifier anchor
+// would both satisfy the clarification gate for a vague question and seed symbol-file retrieval
+// with a non-symbol — see planner/plan.ts decideClarification and grounded symbolFileAnchorTerms.
+const CAMEL_IDENTIFIER_RE = /\b([A-Za-z_$][A-Za-z0-9_$]*[a-z0-9][A-Z][A-Za-z0-9_$]*)\b/g;
+const TOKEN_SPLIT_RE = /[^A-Za-z0-9_.]+/;
+const TECHNICAL_TERM_PATTERNS = [
+    { pattern: /\btype[\s_-]?script\b/gi, term: "typescript" },
+    { pattern: /\bjava[\s_-]?script\b/gi, term: "javascript" },
+    { pattern: /\bnode(?:\.js)?\b/gi, term: "node" },
+    { pattern: /\bnext(?:\.js)?\b/gi, term: "nextjs" },
+    { pattern: /\bpackage\.json\b/gi, term: "package.json" },
+    { pattern: /\bpackage[\s_-]?manager\b/gi, term: "package-manager" },
+    { pattern: /\btsconfig(?:\.[a-z0-9]+)?\b/gi, term: "tsconfig" },
+    { pattern: /\bvitest\b/gi, term: "vitest" },
+    { pattern: /\bvite\b/gi, term: "vite" },
+    { pattern: /\bplaywright\b/gi, term: "playwright" },
+    { pattern: /\bjest\b/gi, term: "jest" },
+    { pattern: /\bcypress\b/gi, term: "cypress" },
+    { pattern: /\breact\b/gi, term: "react" },
+    { pattern: /\bnpm\b/gi, term: "npm" },
+    { pattern: /\bpnpm\b/gi, term: "pnpm" },
+    { pattern: /\byarn\b/gi, term: "yarn" },
+];
+function pushAnchor(out, raw, kind, weight) {
+    const term = raw.trim().toLowerCase();
+    if (term.length > 0) {
+        out.push({ term, weight, kind });
+    }
+}
+function collectMatches(source, pattern, kind, weight, out) {
+    const re = new RegExp(pattern.source, pattern.flags);
+    const parts = [];
+    let cursor = 0;
+    let match = re.exec(source);
+    while (match !== null) {
+        const full = match[0];
+        const captured = match[1] ?? full;
+        pushAnchor(out, captured, kind, weight);
+        parts.push(source.slice(cursor, match.index));
+        parts.push(" ".repeat(full.length));
+        cursor = match.index + full.length;
+        match = re.exec(source);
+    }
+    parts.push(source.slice(cursor));
+    return parts.join("");
+}
+function collectTechnicalTerms(source, out) {
+    let remaining = source;
+    for (const entry of TECHNICAL_TERM_PATTERNS) {
+        const re = new RegExp(entry.pattern.source, entry.pattern.flags);
+        const parts = [];
+        let cursor = 0;
+        let match = re.exec(remaining);
+        while (match !== null) {
+            const full = match[0];
+            pushAnchor(out, entry.term, "identifier", 0.85);
+            parts.push(remaining.slice(cursor, match.index));
+            parts.push(" ".repeat(full.length));
+            cursor = match.index + full.length;
+            match = re.exec(remaining);
+        }
+        parts.push(remaining.slice(cursor));
+        remaining = parts.join("");
+    }
+    return remaining;
+}
+function tokenizeRemaining(remaining, out) {
+    let considered = 0;
+    for (const raw of remaining.split(TOKEN_SPLIT_RE)) {
+        if (raw.length === 0) {
+            continue;
+        }
+        considered += 1;
+        const token = raw.toLowerCase();
+        if (token.length < 3) {
+            continue;
+        }
+        if (STOP_WORDS.has(token)) {
+            continue;
+        }
+        if (token.includes(".")) {
+            out.push({ term: token, weight: 0.8, kind: "identifier" });
+            continue;
+        }
+        out.push({ term: token, weight: 0.5, kind: "literal" });
+    }
+    return considered;
+}
+function dedup(anchors) {
+    const best = new Map();
+    for (const anchor of anchors) {
+        const existing = best.get(anchor.term);
+        if (existing === undefined || anchor.weight > existing.weight) {
+            best.set(anchor.term, { ...anchor });
+        }
+    }
+    return Array.from(best.values());
+}
+function sortAnchors(anchors) {
+    return anchors.sort((a, b) => {
+        if (a.weight !== b.weight) {
+            return b.weight - a.weight;
+        }
+        return a.term.localeCompare(b.term);
+    });
+}
+function freeze(anchors) {
+    return anchors.map((a) => ({ term: a.term, weight: a.weight, kind: a.kind }));
+}
+export function extractAnchors(input) {
+    const { text, maxAnchors } = input;
+    if (text.length === 0) {
+        return { anchors: [], truncated: false, tokensConsidered: 0 };
+    }
+    if (text.length > MAX_INPUT_LENGTH) {
+        return { anchors: [], truncated: true, tokensConsidered: 0 };
+    }
+    const collected = [];
+    let remaining = collectMatches(text, QUOTED_DOUBLE_RE, "quoted", 1, collected);
+    remaining = collectMatches(remaining, QUOTED_SINGLE_RE, "quoted", 1, collected);
+    remaining = collectMatches(remaining, BACKTICK_RE, "identifier", 0.9, collected);
+    remaining = collectMatches(remaining, PATH_RE, "path", 0.95, collected);
+    remaining = collectMatches(remaining, CAMEL_IDENTIFIER_RE, "identifier", 0.85, collected);
+    remaining = collectTechnicalTerms(remaining, collected);
+    const tokensConsidered = tokenizeRemaining(remaining, collected);
+    const merged = sortAnchors(dedup(collected));
+    const truncated = merged.length > maxAnchors;
+    const final = truncated ? merged.slice(0, maxAnchors) : merged;
+    return { anchors: freeze(final), truncated, tokensConsidered };
+}

package/dist/planner/explorationPlanner.d.ts

@@ -0,0 +1,9 @@
+import { type CreatePlanDeps, type CreatePlanInput, type ExplorationPlan } from "./plan.js";
+import { type GovernorState } from "./governor.js";
+export declare function planExploration(input: CreatePlanInput, deps?: CreatePlanDeps): ExplorationPlan;
+export interface PlanAndGovernResult {
+    readonly plan: ExplorationPlan;
+    readonly governor: GovernorState | undefined;
+}
+export declare function planAndGovern(input: CreatePlanInput, deps?: CreatePlanDeps): PlanAndGovernResult;
+//# sourceMappingURL=explorationPlanner.d.ts.map

package/dist/planner/explorationPlanner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explorationPlanner.d.ts","sourceRoot":"","sources":["../../src/planner/explorationPlanner.ts"],"names":[],"mappings":"AAIA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,eAAe,EACrB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAkB,KAAK,aAAa,EAAE,MAAM,eAAe,CAAC;AAEnE,wBAAgB,eAAe,CAAC,KAAK,EAAE,eAAe,EAAE,IAAI,CAAC,EAAE,cAAc,GAAG,eAAe,CAE9F;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,aAAa,GAAG,SAAS,CAAC;CAC9C;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,eAAe,EAAE,IAAI,CAAC,EAAE,cAAc,GAAG,mBAAmB,CAMhG"}

package/dist/planner/explorationPlanner.js

@@ -0,0 +1,15 @@
+// Public facade for the exploration planner and budget governor (Epic #177, Issue #181).
+// Thin wrapper over createExplorationPlan + createGovernor so external consumers can plan
+// and arm a governor in one call without knowing the internal file layout.
+import { createExplorationPlan, } from "./plan.js";
+import { createGovernor } from "./governor.js";
+export function planExploration(input, deps) {
+    return createExplorationPlan(input, deps);
+}
+export function planAndGovern(input, deps) {
+    const plan = createExplorationPlan(input, deps);
+    if (plan.state !== "ready") {
+        return { plan, governor: undefined };
+    }
+    return { plan, governor: createGovernor(plan) };
+}

package/dist/planner/governor.d.ts

@@ -0,0 +1,16 @@
+import { type ExplorationUsage } from "@oscharko-dev/keiko-contracts/connected-context";
+import type { ExplorationPlan } from "./plan.js";
+export type GovernorStatus = "running" | "completed" | "budget-exhausted";
+export interface GovernorState {
+    readonly plan: ExplorationPlan;
+    readonly usage: ExplorationUsage;
+    readonly currentRingIndex: number;
+    readonly status: GovernorStatus;
+    readonly stopReason: string | undefined;
+}
+export declare function createGovernor(plan: ExplorationPlan): GovernorState;
+export declare function applyUsage(state: GovernorState, delta: ExplorationUsage): GovernorState;
+export declare function canContinue(state: GovernorState): boolean;
+export declare function advanceRing(state: GovernorState): GovernorState;
+export declare function complete(state: GovernorState): GovernorState;
+//# sourceMappingURL=governor.d.ts.map

package/dist/planner/governor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"governor.d.ts","sourceRoot":"","sources":["../../src/planner/governor.ts"],"names":[],"mappings":"AAKA,OAAO,EAGL,KAAK,gBAAgB,EACtB,MAAM,iDAAiD,CAAC;AAEzD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAEjD,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,WAAW,GAAG,kBAAkB,CAAC;AAE1E,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAC;IACjC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;CACzC;AAgED,wBAAgB,cAAc,CAAC,IAAI,EAAE,eAAe,GAAG,aAAa,CAanE;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,gBAAgB,GAAG,aAAa,CAevF;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAEzD;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,aAAa,GAAG,aAAa,CAQ/D;AAED,wBAAgB,QAAQ,CAAC,KAAK,EAAE,aAAa,GAAG,aAAa,CAK5D"}

package/dist/planner/governor.js

@@ -0,0 +1,106 @@
+// Budget governor state machine (Epic #177, Issue #181).
+// Accumulates ExplorationUsage and stops execution when any dimension exceeds its budget cap.
+// Immutable state objects only — every transition returns a fresh GovernorState. No persistence;
+// callers persist via the audit ledger in #187.
+import { isWithinBudget, } from "@oscharko-dev/keiko-contracts/connected-context";
+const ZERO_USAGE = {
+    searchCalls: 0,
+    filesRead: 0,
+    excerptBytes: 0,
+    modelInputTokens: 0,
+    modelOutputTokens: 0,
+    elapsedMs: 0,
+    rerankCalls: 0,
+};
+const USAGE_KEYS = [
+    "searchCalls",
+    "filesRead",
+    "excerptBytes",
+    "modelInputTokens",
+    "modelOutputTokens",
+    "elapsedMs",
+    "rerankCalls",
+];
+const BUDGET_KEY_FOR_USAGE = {
+    searchCalls: "searchCallsMax",
+    filesRead: "filesReadMax",
+    excerptBytes: "excerptBytesMax",
+    modelInputTokens: "modelInputTokensMax",
+    modelOutputTokens: "modelOutputTokensMax",
+    elapsedMs: "elapsedMsMax",
+    rerankCalls: "rerankCallsMax",
+};
+function assertUsageDelta(delta) {
+    for (const key of USAGE_KEYS) {
+        const value = delta[key];
+        if (!Number.isInteger(value) || value < 0) {
+            throw new RangeError(`Governor usage delta has invalid ${key}: ${String(value)}`);
+        }
+    }
+}
+function addUsage(a, b) {
+    return {
+        searchCalls: a.searchCalls + b.searchCalls,
+        filesRead: a.filesRead + b.filesRead,
+        excerptBytes: a.excerptBytes + b.excerptBytes,
+        modelInputTokens: a.modelInputTokens + b.modelInputTokens,
+        modelOutputTokens: a.modelOutputTokens + b.modelOutputTokens,
+        elapsedMs: a.elapsedMs + b.elapsedMs,
+        rerankCalls: a.rerankCalls + b.rerankCalls,
+    };
+}
+function violatedDimensions(usage, budget) {
+    const out = [];
+    for (const key of USAGE_KEYS) {
+        const cap = budget[BUDGET_KEY_FOR_USAGE[key]];
+        if (usage[key] > cap) {
+            out.push(key);
+        }
+    }
+    return out;
+}
+export function createGovernor(plan) {
+    if (plan.state !== "ready") {
+        throw new RangeError(`Cannot govern a plan in state "${plan.state}"; only "ready" plans are runnable.`);
+    }
+    return {
+        plan,
+        usage: ZERO_USAGE,
+        currentRingIndex: 0,
+        status: "running",
+        stopReason: undefined,
+    };
+}
+export function applyUsage(state, delta) {
+    assertUsageDelta(delta);
+    const nextUsage = addUsage(state.usage, delta);
+    if (isWithinBudget(nextUsage, state.plan.budget)) {
+        return { ...state, usage: nextUsage };
+    }
+    const violated = violatedDimensions(nextUsage, state.plan.budget);
+    const stopReason = violated.length > 0 ? `budget-exhausted on ${violated.join(", ")}` : "budget-exhausted";
+    return {
+        ...state,
+        usage: nextUsage,
+        status: "budget-exhausted",
+        stopReason,
+    };
+}
+export function canContinue(state) {
+    return state.status === "running" && isWithinBudget(state.usage, state.plan.budget);
+}
+export function advanceRing(state) {
+    if (state.status !== "running") {
+        return state;
+    }
+    if (state.currentRingIndex >= state.plan.rings.length) {
+        return state;
+    }
+    return { ...state, currentRingIndex: state.currentRingIndex + 1 };
+}
+export function complete(state) {
+    if (state.status === "budget-exhausted") {
+        return state;
+    }
+    return { ...state, status: "completed" };
+}