@oscharko-dev/keiko-workflows 0.2.0

package/dist/contextpack/assemble.js

@@ -0,0 +1,431 @@
+// Public facade for the connected-context pack assembler (Epic #177, Issue #183). Bridges
+// ranked candidates (#182) + already-redacted excerpt content into a ConnectedContextPack
+// per the #178 contract. Pure orchestration: compaction + budget checkpointing + reranker
+// seam + optional micro-index. No IO. The audit ledger (#187) owns persistence and
+// `ledgerRef` is therefore always undefined here.
+import { createHash } from "node:crypto";
+import { CONNECTED_CONTEXT_SCHEMA_VERSION, } from "@oscharko-dev/keiko-contracts/connected-context";
+import { connectedContextPackStableId } from "@oscharko-dev/keiko-workspace";
+import { compactExcerpt, nextAtomFitsBudget } from "./compaction.js";
+import { makeIndexKey } from "./microIndex.js";
+import { disabledReranker } from "./reranker.js";
+// ─── Constants ────────────────────────────────────────────────────────────────
+const DEFAULT_MAX_BYTES_PER_EXCERPT = 8 * 1024;
+function resolveOptions(options) {
+    return {
+        maxBytesPerExcerpt: options?.maxBytesPerExcerpt ?? DEFAULT_MAX_BYTES_PER_EXCERPT,
+        editablePaths: options?.editablePaths ?? new Set(),
+        reranker: options?.reranker ?? disabledReranker,
+        microIndex: options?.microIndex,
+        nowMs: options?.nowMs ?? Date.now,
+    };
+}
+function zeroUsage() {
+    return {
+        searchCalls: 0,
+        filesRead: 0,
+        excerptBytes: 0,
+        modelInputTokens: 0,
+        modelOutputTokens: 0,
+        elapsedMs: 0,
+        rerankCalls: 0,
+    };
+}
+function groupAtomsByPath(atoms) {
+    const map = new Map();
+    for (const atom of atoms) {
+        const existing = map.get(atom.scopePath);
+        if (existing === undefined) {
+            map.set(atom.scopePath, [atom]);
+        }
+        else {
+            existing.push(atom);
+        }
+    }
+    return map;
+}
+function deriveSelectionReason(candidate) {
+    const first = candidate.signals[0];
+    if (first === undefined) {
+        return "ranked candidate";
+    }
+    return `ranked by ${first.name}`;
+}
+function resolveRole(scopePath, editablePaths) {
+    return editablePaths.has(scopePath) ? "editable" : "read-only";
+}
+async function applyReranker(reranker, ranked, atomsByPath, budget, usage) {
+    // The seam is only invoked when the budget actually allows rerank calls. This keeps
+    // ExplorationBudget.rerankCallsMax authoritative even when a custom reranker is supplied
+    // and avoids billing a rerank call against a run whose budget set rerankCallsMax=0.
+    if (usage.rerankCalls >= budget.rerankCallsMax) {
+        return { ordered: ranked, reranked: false };
+    }
+    const availability = await reranker.isAvailable();
+    if (!availability.available) {
+        return { ordered: ranked, reranked: false };
+    }
+    const reordered = await reranker.rerank(ranked, atomsByPath, ranked.length);
+    return { ordered: reordered, reranked: true };
+}
+function cloneUsage(usage) {
+    if (usage === undefined) {
+        return zeroUsage();
+    }
+    return { ...usage };
+}
+function emptyBuildPlan(initialUsage, initialUncertainty) {
+    return {
+        files: [],
+        usage: cloneUsage(initialUsage),
+        uncertainty: [...(initialUncertainty ?? [])],
+        extraOmitted: [],
+    };
+}
+function compactAtomsForCandidate(atomsForPath, source, maxBytesPerExcerpt) {
+    const excerpts = [];
+    let totalBytes = 0;
+    for (const atom of atomsForPath) {
+        const rawContent = contentForAtom(atom, source);
+        if (rawContent === undefined) {
+            continue;
+        }
+        const result = compactExcerpt({ atom, rawContent, maxBytes: maxBytesPerExcerpt });
+        excerpts.push(result.excerpt);
+        totalBytes += result.bytesConsumed;
+    }
+    return { excerpts, totalBytes };
+}
+function lineCount(content) {
+    if (content.length === 0) {
+        return 0;
+    }
+    return content.split("\n").length;
+}
+function isExcerptWindowArray(source) {
+    return Array.isArray(source);
+}
+function normalizeExcerptWindows(source) {
+    if (typeof source === "string") {
+        return [{ startLine: 1, endLine: lineCount(source), content: source }];
+    }
+    if (isExcerptWindowArray(source)) {
+        return source;
+    }
+    return [source];
+}
+function coversAtom(window, atom) {
+    const range = atom.lineRange;
+    return (range === undefined || (window.startLine <= range.startLine && window.endLine >= range.endLine));
+}
+function sliceWindowForAtom(window, atom) {
+    const range = atom.lineRange;
+    if (range === undefined) {
+        return window.content;
+    }
+    const lines = window.content.split("\n");
+    const startIndex = Math.max(0, range.startLine - window.startLine);
+    const endIndex = Math.min(lines.length, range.endLine - window.startLine + 1);
+    if (startIndex >= endIndex) {
+        return "";
+    }
+    return lines.slice(startIndex, endIndex).join("\n");
+}
+function contentForAtom(atom, source) {
+    const windows = normalizeExcerptWindows(source);
+    const selected = windows.find((window) => coversAtom(window, atom));
+    if (selected === undefined) {
+        return undefined;
+    }
+    return sliceWindowForAtom(selected, atom);
+}
+function appendUsage(usage, addedBytes) {
+    return {
+        ...usage,
+        filesRead: usage.filesRead + 1,
+        excerptBytes: usage.excerptBytes + addedBytes,
+    };
+}
+function recordBudgetClip(plan, candidate, atomsForPath, nowMs) {
+    plan.uncertainty.push({
+        kind: "budget-clipped",
+        claim: `context pack truncated at ${candidate.scopePath}`,
+        // The clipped candidate is omitted from pack.files, so its atoms are not valid
+        // uncertainty references under the connected-context contract.
+        impactedAtomIds: [],
+        emittedAtMs: nowMs,
+    });
+    plan.extraOmitted.push({
+        scopePath: candidate.scopePath,
+        reason: "budget-exhausted",
+        omittedAtMs: nowMs,
+    });
+}
+function recordNoEvidence(plan, claim, nowMs) {
+    plan.uncertainty.push({
+        kind: "no-evidence",
+        claim,
+        impactedAtomIds: [],
+        emittedAtMs: nowMs,
+    });
+}
+function recordPreMarkedOmission(plan, candidate, nowMs) {
+    if (candidate.omitted === undefined) {
+        return false;
+    }
+    plan.extraOmitted.push({
+        scopePath: candidate.scopePath,
+        reason: candidate.omitted,
+        omittedAtMs: nowMs,
+    });
+    return true;
+}
+function processCandidate(plan, candidate, ctx) {
+    // Respect a pre-set omission reason from the ranker (e.g. "generated", "ignored").
+    // The candidate's atoms may still exist in input.atoms (the ranker only drops them from
+    // its kept list), but they must not enter pack.files — that would contradict the
+    // omission semantics of CandidateFile.omitted.
+    if (recordPreMarkedOmission(plan, candidate, ctx.nowMs)) {
+        return "continue";
+    }
+    const excerptSource = ctx.excerpts.get(candidate.scopePath);
+    if (excerptSource === undefined) {
+        recordNoEvidence(plan, `excerpt unavailable for ${candidate.scopePath}`, ctx.nowMs);
+        return "continue";
+    }
+    const atomsForPath = ctx.atomsByPath.get(candidate.scopePath) ?? [];
+    if (atomsForPath.length === 0) {
+        return "continue";
+    }
+    const { excerpts, totalBytes } = compactAtomsForCandidate(atomsForPath, excerptSource, ctx.maxBytesPerExcerpt);
+    if (excerpts.length === 0) {
+        recordNoEvidence(plan, `excerpt unavailable for cited ranges in ${candidate.scopePath}`, ctx.nowMs);
+        return "continue";
+    }
+    const checkpoint = {
+        atoms: atomsForPath,
+        budget: ctx.budget,
+        currentUsage: plan.usage,
+    };
+    if (!nextAtomFitsBudget(checkpoint, totalBytes).fits) {
+        recordBudgetClip(plan, candidate, atomsForPath, ctx.nowMs);
+        return "budget-clipped";
+    }
+    plan.files.push({
+        scopePath: candidate.scopePath,
+        role: resolveRole(candidate.scopePath, ctx.editablePaths),
+        selectionReason: deriveSelectionReason(candidate),
+        excerpts,
+    });
+    plan.usage = appendUsage(plan.usage, totalBytes);
+    return "continue";
+}
+function buildPlan(ordered, ctx, initialUsage, initialUncertainty) {
+    const plan = emptyBuildPlan(initialUsage, initialUncertainty);
+    for (const candidate of ordered) {
+        const outcome = processCandidate(plan, candidate, ctx);
+        if (outcome === "budget-clipped") {
+            return plan;
+        }
+    }
+    return plan;
+}
+function cacheConnectedExcerpt(excerpt) {
+    return {
+        atom: cacheAtom(excerpt.atom),
+        contentHash: sha256Hex(excerpt.content),
+        contentBytes: excerpt.contentBytes,
+    };
+}
+function cacheConnectedFile(file) {
+    return {
+        scopePath: file.scopePath,
+        role: file.role,
+        selectionReason: file.selectionReason,
+        excerpts: file.excerpts.map(cacheConnectedExcerpt),
+    };
+}
+function buildStableId(input, plan) {
+    const fingerprint = sha256Hex(JSON.stringify({
+        scope: cacheScope(input.scope),
+        query: cacheQuery(input.query),
+        files: plan.files.map(cacheConnectedFile),
+        omitted: [...input.omittedFromRanking, ...plan.extraOmitted].map(cacheOmitted),
+        uncertainty: plan.uncertainty.map(cacheUncertainty),
+    }));
+    return connectedContextPackStableId({
+        scopeId: input.scope.scopeId,
+        queryKind: input.query.kind,
+        queryText: input.query.text,
+        atomStableIds: [`pack-fp-${fingerprint}`],
+    });
+}
+function buildPack(input, plan, nowMs) {
+    return {
+        schemaVersion: CONNECTED_CONTEXT_SCHEMA_VERSION,
+        stableId: buildStableId(input, plan),
+        scope: input.scope,
+        query: input.query,
+        budget: input.budget,
+        usage: plan.usage,
+        files: plan.files,
+        omitted: [...input.omittedFromRanking, ...plan.extraOmitted],
+        uncertainty: plan.uncertainty,
+        emittedAtMs: nowMs,
+        ledgerRef: undefined,
+    };
+}
+// ─── Public facade ────────────────────────────────────────────────────────────
+// Cache-key contributors that change the produced pack. Two runs with the same atoms but
+// different budgets, per-excerpt caps, editable-file sets, or reranker MUST hash to
+// different keys — otherwise we could serve a cached pack that violates the new budget or
+// carries the wrong file roles/order.
+function sha256Hex(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+function cacheLineRange(range) {
+    if (range === undefined) {
+        return undefined;
+    }
+    return { startLine: range.startLine, endLine: range.endLine };
+}
+function cacheScope(scope) {
+    return {
+        schemaVersion: scope.schemaVersion,
+        scopeId: scope.scopeId,
+        workspaceRoot: scope.workspaceRoot,
+        kind: scope.kind,
+        relativePaths: scope.relativePaths,
+        conversationId: scope.conversationId,
+        connectedAtMs: scope.connectedAtMs,
+        explicitConnection: scope.explicitConnection,
+    };
+}
+function cacheQuery(query) {
+    return {
+        kind: query.kind,
+        text: query.text,
+        caseSensitive: query.caseSensitive,
+        maxResults: query.maxResults,
+    };
+}
+function cacheAtom(atom) {
+    return {
+        stableId: atom.stableId,
+        scopePath: atom.scopePath,
+        lineRange: cacheLineRange(atom.lineRange),
+        score: atom.score,
+        provenance: atom.provenance,
+        redactionState: atom.redactionState,
+        ledgerRef: atom.ledgerRef,
+    };
+}
+function cacheUsage(usage) {
+    if (usage === undefined) {
+        return undefined;
+    }
+    return {
+        searchCalls: usage.searchCalls,
+        filesRead: usage.filesRead,
+        excerptBytes: usage.excerptBytes,
+        modelInputTokens: usage.modelInputTokens,
+        modelOutputTokens: usage.modelOutputTokens,
+        rerankCalls: usage.rerankCalls,
+    };
+}
+function cacheUncertainty(marker) {
+    return {
+        kind: marker.kind,
+        claim: marker.claim,
+        impactedAtomIds: marker.impactedAtomIds,
+    };
+}
+function cacheCandidate(candidate) {
+    return {
+        scopePath: candidate.scopePath,
+        score: candidate.score,
+        signals: candidate.signals.map((signal) => ({ name: signal.name, value: signal.value })),
+        omitted: candidate.omitted,
+    };
+}
+function cacheOmitted(entry) {
+    return {
+        scopePath: entry.scopePath,
+        reason: entry.reason,
+    };
+}
+function cacheExcerptWindow(window) {
+    return {
+        startLine: window.startLine,
+        endLine: window.endLine,
+        contentHash: sha256Hex(window.content),
+    };
+}
+function cacheExcerpts(excerpts) {
+    return [...excerpts.entries()]
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([scopePath, source]) => ({
+        scopePath,
+        windows: normalizeExcerptWindows(source).map(cacheExcerptWindow),
+    }));
+}
+function cacheExcerptIdentity(input) {
+    if (input.cacheIdentity !== undefined) {
+        return [...input.cacheIdentity].sort();
+    }
+    return cacheExcerpts(input.excerpts);
+}
+function buildCacheAtomIds(input, resolved) {
+    const fingerprintSource = JSON.stringify({
+        scope: cacheScope(input.scope),
+        query: cacheQuery(input.query),
+        atoms: input.atoms.map(cacheAtom),
+        budget: input.budget,
+        initialUsage: cacheUsage(input.initialUsage),
+        initialUncertainty: input.cacheIdentity === undefined
+            ? input.initialUncertainty?.map(cacheUncertainty)
+            : undefined,
+        ranked: input.ranked.map(cacheCandidate),
+        omittedFromRanking: input.omittedFromRanking.map(cacheOmitted),
+        excerpts: cacheExcerptIdentity(input),
+        maxBytesPerExcerpt: resolved.maxBytesPerExcerpt,
+        editablePaths: [...resolved.editablePaths].sort(),
+        rerankerName: resolved.reranker.name,
+    });
+    return [`fp-${sha256Hex(fingerprintSource)}`];
+}
+export function contextPackIndexKey(input, options) {
+    const resolved = resolveOptions(options);
+    return makeIndexKey({
+        scopeId: input.scope.scopeId,
+        queryKind: input.query.kind,
+        queryText: input.query.text,
+        atomStableIds: buildCacheAtomIds(input, resolved),
+    });
+}
+export async function assembleContextPack(input, options) {
+    const resolved = resolveOptions(options);
+    const key = contextPackIndexKey(input, options);
+    const cached = resolved.microIndex?.get(key);
+    if (cached !== undefined) {
+        return { pack: cached, fromIndex: true };
+    }
+    const atomsByPath = groupAtomsByPath(input.atoms);
+    const initialUsage = cloneUsage(input.initialUsage);
+    const rerankerOutcome = await applyReranker(resolved.reranker, input.ranked, atomsByPath, input.budget, initialUsage);
+    const now = resolved.nowMs();
+    const plan = buildPlan(rerankerOutcome.ordered, {
+        atomsByPath,
+        excerpts: input.excerpts,
+        budget: input.budget,
+        maxBytesPerExcerpt: resolved.maxBytesPerExcerpt,
+        editablePaths: resolved.editablePaths,
+        nowMs: now,
+    }, initialUsage, input.initialUncertainty);
+    if (rerankerOutcome.reranked) {
+        plan.usage = { ...plan.usage, rerankCalls: plan.usage.rerankCalls + 1 };
+    }
+    const pack = buildPack(input, plan, now);
+    resolved.microIndex?.set(key, pack);
+    return { pack, fromIndex: false };
+}

package/dist/contextpack/compaction.d.ts

@@ -0,0 +1,23 @@
+import type { ContextExcerpt, EvidenceAtom, ExplorationBudget, ExplorationUsage } from "@oscharko-dev/keiko-contracts/connected-context";
+export interface CompactionInput {
+    readonly atom: EvidenceAtom;
+    readonly rawContent: string;
+    readonly maxBytes: number;
+}
+export interface CompactionResult {
+    readonly excerpt: ContextExcerpt;
+    readonly bytesConsumed: number;
+    readonly truncated: boolean;
+}
+export interface BudgetCheckpoint {
+    readonly atoms: readonly EvidenceAtom[];
+    readonly budget: ExplorationBudget;
+    readonly currentUsage: ExplorationUsage;
+}
+export interface BudgetCheckpointResult {
+    readonly fits: boolean;
+    readonly violatedDim?: string;
+}
+export declare function compactExcerpt(input: CompactionInput): CompactionResult;
+export declare function nextAtomFitsBudget(cp: BudgetCheckpoint, candidateAtomBytes: number): BudgetCheckpointResult;
+//# sourceMappingURL=compaction.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"compaction.d.ts","sourceRoot":"","sources":["../../src/contextpack/compaction.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACV,cAAc,EACd,YAAY,EACZ,iBAAiB,EACjB,gBAAgB,EACjB,MAAM,iDAAiD,CAAC;AAIzD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IACjC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,SAAS,YAAY,EAAE,CAAC;IACxC,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IACnC,QAAQ,CAAC,YAAY,EAAE,gBAAgB,CAAC;CACzC;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAqCD,wBAAgB,cAAc,CAAC,KAAK,EAAE,eAAe,GAAG,gBAAgB,CAiBvE;AAID,wBAAgB,kBAAkB,CAChC,EAAE,EAAE,gBAAgB,EACpB,kBAAkB,EAAE,MAAM,GACzB,sBAAsB,CAaxB"}

package/dist/contextpack/compaction.js

@@ -0,0 +1,68 @@
+// Excerpt compaction and aggregate-budget checkpoint helpers for the connected-context
+// assembler (Epic #177, Issue #183). Pure functions: no IO, no clock, no randomness. The
+// input `rawContent` is already redacted by the #179 search facade boundary; this module
+// only clamps to UTF-8 byte budgets and reports whether the next atom would fit the
+// per-pack ExplorationBudget envelope.
+// ─── UTF-8 byte clamping ──────────────────────────────────────────────────────
+const TEXT_ENCODER = new TextEncoder();
+// `fatal: false` so a clamp that lands inside a multi-byte sequence emits U+FFFD instead
+// of throwing — we then strip the replacement char to keep the excerpt boundary clean.
+const TEXT_DECODER = new TextDecoder("utf-8", { fatal: false });
+const REPLACEMENT_CHAR = "�";
+function utf8ByteLength(value) {
+    return TEXT_ENCODER.encode(value).length;
+}
+function clampToBytes(value, maxBytes) {
+    if (maxBytes <= 0) {
+        return "";
+    }
+    const encoded = TEXT_ENCODER.encode(value);
+    if (encoded.length <= maxBytes) {
+        return value;
+    }
+    const sliced = encoded.subarray(0, maxBytes);
+    const decoded = TEXT_DECODER.decode(sliced);
+    if (!decoded.endsWith(REPLACEMENT_CHAR)) {
+        return decoded;
+    }
+    // Strip trailing replacement chars so the excerpt never exposes a partial code point.
+    let trimmed = decoded;
+    while (trimmed.endsWith(REPLACEMENT_CHAR)) {
+        trimmed = trimmed.slice(0, -1);
+    }
+    return trimmed;
+}
+// ─── compactExcerpt ───────────────────────────────────────────────────────────
+export function compactExcerpt(input) {
+    if (!Number.isInteger(input.maxBytes) || input.maxBytes < 0) {
+        throw new RangeError("compactExcerpt: maxBytes must be a non-negative integer");
+    }
+    const originalBytes = utf8ByteLength(input.rawContent);
+    const clamped = clampToBytes(input.rawContent, input.maxBytes);
+    const contentBytes = utf8ByteLength(clamped);
+    const excerpt = {
+        atom: input.atom,
+        content: clamped,
+        contentBytes,
+    };
+    return {
+        excerpt,
+        bytesConsumed: contentBytes,
+        truncated: contentBytes < originalBytes,
+    };
+}
+// ─── nextAtomFitsBudget ───────────────────────────────────────────────────────
+export function nextAtomFitsBudget(cp, candidateAtomBytes) {
+    if (!Number.isFinite(candidateAtomBytes) || candidateAtomBytes < 0) {
+        return { fits: false, violatedDim: "excerptBytes" };
+    }
+    const projectedBytes = cp.currentUsage.excerptBytes + candidateAtomBytes;
+    if (projectedBytes > cp.budget.excerptBytesMax) {
+        return { fits: false, violatedDim: "excerptBytes" };
+    }
+    const projectedFiles = cp.currentUsage.filesRead + 1;
+    if (projectedFiles > cp.budget.filesReadMax) {
+        return { fits: false, violatedDim: "filesRead" };
+    }
+    return { fits: true };
+}

package/dist/contextpack/index.d.ts

@@ -0,0 +1,9 @@
+export type { BudgetCheckpoint, BudgetCheckpointResult, CompactionInput, CompactionResult, } from "./compaction.js";
+export { compactExcerpt, nextAtomFitsBudget } from "./compaction.js";
+export type { RerankerAvailability, RerankerSeam } from "./reranker.js";
+export { disabledReranker } from "./reranker.js";
+export type { IndexEntry, IndexKeyInput, MicroIndex, MicroIndexOptions } from "./microIndex.js";
+export { createMicroIndex, DEFAULT_MICRO_INDEX, makeIndexKey } from "./microIndex.js";
+export type { AssembleInput, AssembleOptions, AssembleResult, ExcerptSource, ExcerptWindow, } from "./assemble.js";
+export { assembleContextPack, contextPackIndexKey } from "./assemble.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/contextpack/index.ts"],"names":[],"mappings":"AAKA,YAAY,EACV,gBAAgB,EAChB,sBAAsB,EACtB,eAAe,EACf,gBAAgB,GACjB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAErE,YAAY,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AACxE,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEjD,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,UAAU,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAChG,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAEtF,YAAY,EACV,aAAa,EACb,eAAe,EACf,cAAc,EACd,aAAa,EACb,aAAa,GACd,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC"}

package/dist/contextpack/index.js

@@ -0,0 +1,8 @@
+// Public sub-barrel for the ephemeral micro-index and connected-context pack assembler
+// (Epic #177, Issue #183). External consumers import every contextpack symbol through
+// this module; internal modules (compaction.ts, reranker.ts, microIndex.ts, assemble.ts)
+// remain implementation detail.
+export { compactExcerpt, nextAtomFitsBudget } from "./compaction.js";
+export { disabledReranker } from "./reranker.js";
+export { createMicroIndex, DEFAULT_MICRO_INDEX, makeIndexKey } from "./microIndex.js";
+export { assembleContextPack, contextPackIndexKey } from "./assemble.js";

package/dist/contextpack/microIndex.d.ts

@@ -0,0 +1,29 @@
+import type { ConnectedContextPack } from "@oscharko-dev/keiko-contracts/connected-context";
+export interface IndexEntry {
+    readonly key: string;
+    readonly pack: ConnectedContextPack;
+    readonly insertedAtMs: number;
+    readonly expiresAtMs: number;
+}
+export interface MicroIndexOptions {
+    readonly ttlMs: number;
+    readonly maxEntries: number;
+    readonly nowMs: () => number;
+}
+export declare const DEFAULT_MICRO_INDEX: Omit<MicroIndexOptions, "nowMs">;
+export interface MicroIndex {
+    get(key: string): ConnectedContextPack | undefined;
+    set(key: string, pack: ConnectedContextPack): void;
+    delete(key: string): void;
+    clear(): void;
+    size(): number;
+}
+export interface IndexKeyInput {
+    readonly scopeId: string;
+    readonly queryKind: string;
+    readonly queryText: string;
+    readonly atomStableIds: readonly string[];
+}
+export declare function makeIndexKey(input: IndexKeyInput): string;
+export declare function createMicroIndex(options: MicroIndexOptions): MicroIndex;
+//# sourceMappingURL=microIndex.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"microIndex.d.ts","sourceRoot":"","sources":["../../src/contextpack/microIndex.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,iDAAiD,CAAC;AAI5F,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;IACpC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,MAAM,CAAC;CAC9B;AAED,eAAO,MAAM,mBAAmB,EAAE,IAAI,CAAC,iBAAiB,EAAE,OAAO,CAGvD,CAAC;AAEX,MAAM,WAAW,UAAU;IACzB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,oBAAoB,GAAG,SAAS,CAAC;IACnD,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,oBAAoB,GAAG,IAAI,CAAC;IACnD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,KAAK,IAAI,IAAI,CAAC;IACd,IAAI,IAAI,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3C;AASD,wBAAgB,YAAY,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAGzD;AAqCD,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,GAAG,UAAU,CAoDvE"}

package/dist/contextpack/microIndex.js

@@ -0,0 +1,98 @@
+// Ephemeral, session-scoped micro-index for assembled ConnectedContextPacks (Epic #177,
+// Issue #183). Pure in-memory cache backed by a Map; entries are TTL-bounded and capped
+// by maxEntries (insertion order = LRU). NEVER written to disk — the audit ledger (#187)
+// owns persistence. makeIndexKey uses SHA-256 with a fixed prefix so identical inputs
+// reuse the same cached pack regardless of caller order on atomStableIds.
+import { createHash } from "node:crypto";
+export const DEFAULT_MICRO_INDEX = {
+    ttlMs: 5 * 60 * 1000,
+    maxEntries: 32,
+};
+// ─── Key derivation ───────────────────────────────────────────────────────────
+function canonicalKeyInput(input) {
+    const sorted = [...input.atomStableIds].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+    return JSON.stringify([input.scopeId, input.queryKind, input.queryText, sorted]);
+}
+export function makeIndexKey(input) {
+    const hash = createHash("sha256").update(canonicalKeyInput(input)).digest("hex");
+    return `ix-${hash.slice(0, 16)}`;
+}
+// ─── Micro-index factory ──────────────────────────────────────────────────────
+function validateOptions(options) {
+    if (!Number.isFinite(options.ttlMs) || options.ttlMs <= 0) {
+        throw new RangeError("createMicroIndex: ttlMs must be a positive finite number");
+    }
+    if (!Number.isInteger(options.maxEntries) || options.maxEntries <= 0) {
+        throw new RangeError("createMicroIndex: maxEntries must be a positive integer");
+    }
+    // Validate eagerly so the failure mode is a TypeError at construction rather than a
+    // less actionable "options.nowMs is not a function" the next time get/set is called.
+    if (typeof options.nowMs !== "function") {
+        throw new TypeError("createMicroIndex: nowMs must be a function");
+    }
+}
+function evictExpired(store, nowMs) {
+    for (const [key, entry] of store) {
+        if (entry.expiresAtMs <= nowMs) {
+            store.delete(key);
+        }
+    }
+}
+function evictOldest(store, capacity) {
+    while (store.size >= capacity) {
+        const iterator = store.keys();
+        const next = iterator.next();
+        if (next.done === true) {
+            return;
+        }
+        store.delete(next.value);
+    }
+}
+export function createMicroIndex(options) {
+    validateOptions(options);
+    // Insertion order on a Map gives natural LRU semantics: `set` re-inserts at the tail,
+    // and `evictOldest` removes from the head.
+    const store = new Map();
+    function get(key) {
+        const entry = store.get(key);
+        if (entry === undefined) {
+            return undefined;
+        }
+        const now = options.nowMs();
+        if (entry.expiresAtMs <= now) {
+            store.delete(key);
+            return undefined;
+        }
+        // Refresh insertion order without changing expiry — recent reads stay warm.
+        store.delete(key);
+        store.set(key, entry);
+        return entry.pack;
+    }
+    function set(key, pack) {
+        const now = options.nowMs();
+        evictExpired(store, now);
+        if (store.has(key)) {
+            store.delete(key);
+        }
+        else {
+            evictOldest(store, options.maxEntries);
+        }
+        const entry = {
+            key,
+            pack,
+            insertedAtMs: now,
+            expiresAtMs: now + options.ttlMs,
+        };
+        store.set(key, entry);
+    }
+    function deleteKey(key) {
+        store.delete(key);
+    }
+    function clear() {
+        store.clear();
+    }
+    function size() {
+        return store.size;
+    }
+    return { get, set, delete: deleteKey, clear, size };
+}