@oscharko-dev/keiko-workflows 0.2.6 → 0.2.8

package/dist/context-budget/allocator.d.ts

@@ -0,0 +1,29 @@
+import { type ContextAssemblyDiagnostics, type ContextBudget, type ContextLaneDiagnostics, type ContextLaneId, type ContextProfile } from "@oscharko-dev/keiko-contracts";
+export interface ContextLaneItemInput {
+    readonly id: string;
+    readonly text: string;
+    readonly score: number;
+}
+export interface ContextLaneInput {
+    readonly laneId: ContextLaneId;
+    readonly items: readonly ContextLaneItemInput[];
+}
+export interface AllocateContextInput {
+    readonly profile: ContextProfile;
+    readonly budget: ContextBudget;
+    readonly lanes: readonly ContextLaneInput[];
+}
+export interface AllocatedContextLane {
+    readonly laneId: ContextLaneId;
+    readonly includedItemIds: readonly string[];
+    readonly excludedItemIds: readonly string[];
+    readonly estimatedTokens: number;
+    readonly diagnostics: ContextLaneDiagnostics;
+}
+export interface AllocateContextResult {
+    readonly lanes: readonly AllocatedContextLane[];
+    readonly diagnostics: ContextAssemblyDiagnostics;
+    readonly totalEstimatedTokens: number;
+}
+export declare function allocateContext(input: AllocateContextInput): AllocateContextResult;
+//# sourceMappingURL=allocator.d.ts.map

package/dist/context-budget/allocator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"allocator.d.ts","sourceRoot":"","sources":["../../src/context-budget/allocator.ts"],"names":[],"mappings":"AAKA,OAAO,EAIL,KAAK,0BAA0B,EAC/B,KAAK,aAAa,EAGlB,KAAK,sBAAsB,EAC3B,KAAK,aAAa,EAClB,KAAK,cAAc,EACpB,MAAM,+BAA+B,CAAC;AAEvC,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,SAAS,oBAAoB,EAAE,CAAC;CACjD;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,SAAS,gBAAgB,EAAE,CAAC;CAC7C;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,WAAW,EAAE,sBAAsB,CAAC;CAC9C;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,KAAK,EAAE,SAAS,oBAAoB,EAAE,CAAC;IAChD,QAAQ,CAAC,WAAW,EAAE,0BAA0B,CAAC;IACjD,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;CACvC;AAkND,wBAAgB,eAAe,CAAC,KAAK,EAAE,oBAAoB,GAAG,qBAAqB,CAoBlF"}

package/dist/context-budget/allocator.js

@@ -0,0 +1,185 @@
+// Pure, deterministic, no-IO lane budget allocator (ADR-0052 D3/D6). Mirrors the immutable
+// state pattern of planner/governor.ts: never mutates inputs, returns fresh objects, no clock,
+// no randomness, no network. estimateTokens from keiko-contracts is the SINGLE token currency
+// (ADR-0052 gate 3) — no other ratio appears in this module.
+import { CONTEXT_ENGINEERING_SCHEMA_VERSION, CONTEXT_LANE_IDS, estimateTokens, } from "@oscharko-dev/keiko-contracts";
+const CANONICAL_INDEX = new Map(CONTEXT_LANE_IDS.map((id, index) => [id, index]));
+function canonicalIndex(laneId) {
+    return CANONICAL_INDEX.get(laneId) ?? CONTEXT_LANE_IDS.length;
+}
+// Deterministic score-greedy fill by TOKEN budget. Mirrors the proven ordering of
+// selectScoredTextByByteBudget (packages/keiko-workspace/src/contextPack.ts:53): score DESC,
+// then id ASC (localeCompare) for stable ties, greedy-fill until the cap is reached. Byte-reuse
+// was rejected here because that primitive measures utf8 BYTES, which would corrupt the single
+// token currency the allocator must use (estimateTokens) for every lane.
+function selectScoredByTokenBudget(items, tokenBudget) {
+    const ordered = [...items].sort((a, b) => {
+        const byScore = b.score - a.score;
+        return byScore !== 0 ? byScore : a.id.localeCompare(b.id);
+    });
+    const includedIds = [];
+    const excludedIds = [];
+    let tokens = 0;
+    for (const item of ordered) {
+        const cost = estimateTokens(item.text);
+        if (tokens + cost > tokenBudget) {
+            excludedIds.push(item.id);
+            continue;
+        }
+        includedIds.push(item.id);
+        tokens += cost;
+    }
+    return { includedIds, excludedIds, tokens, droppedForBudget: excludedIds.length > 0 };
+}
+// Non-evictable lanes include EVERY item (reserved off the top, never dropped) even if their
+// total exceeds the budget — that overflow is the only permitted exception (forces "exceeded").
+function includeAll(items) {
+    const includedIds = items.map((item) => item.id);
+    let tokens = 0;
+    for (const item of items) {
+        tokens += estimateTokens(item.text);
+    }
+    return { includedIds, excludedIds: [], tokens, droppedForBudget: false };
+}
+function pressureFor(tokens, cap) {
+    if (cap <= 0) {
+        return tokens > 0 ? "exceeded" : "low";
+    }
+    const ratio = tokens / cap;
+    if (ratio >= 1) {
+        return "exceeded";
+    }
+    if (ratio >= 0.85) {
+        return "high";
+    }
+    if (ratio >= 0.6) {
+        return "moderate";
+    }
+    return "low";
+}
+function laneDiagnostics(laneId, fill, cap) {
+    const base = {
+        laneId,
+        estimatedTokens: fill.tokens,
+        includedItems: fill.includedIds.length,
+        excludedItems: fill.excludedIds.length,
+        budgetPressure: pressureFor(fill.tokens, cap),
+        provenanceCounts: {
+            included: fill.includedIds.length,
+            excluded: fill.excludedIds.length,
+        },
+    };
+    return fill.droppedForBudget ? { ...base, compactionReason: "budget" } : base;
+}
+function toAllocatedLane(laneId, fill, cap) {
+    return {
+        laneId,
+        includedItemIds: fill.includedIds,
+        excludedItemIds: fill.excludedIds,
+        estimatedTokens: fill.tokens,
+        diagnostics: laneDiagnostics(laneId, fill, cap),
+    };
+}
+// Joins each present input lane to its budget row. Lanes absent from input.lanes contribute
+// nothing; an input lane with no matching budget row is ignored gracefully (no throw).
+function planLanes(input) {
+    const itemsByLane = new Map();
+    for (const lane of input.lanes) {
+        itemsByLane.set(lane.laneId, lane.items);
+    }
+    const planned = [];
+    for (const row of input.budget.lanes) {
+        const items = itemsByLane.get(row.laneId);
+        if (items !== undefined) {
+            planned.push({ row, items });
+        }
+    }
+    return planned;
+}
+function isNonEvictable(row) {
+    return row.eviction === "none";
+}
+// Evictable lanes are filled in priority order (lower priority first; canonical lane order
+// breaks ties) so eviction is deterministic and matches the ADR allocation order.
+function byEvictionOrder(a, b) {
+    const byPriority = a.row.priority - b.row.priority;
+    return byPriority !== 0
+        ? byPriority
+        : canonicalIndex(a.row.laneId) - canonicalIndex(b.row.laneId);
+}
+function fillEvictableLanes(lanes, budgetAfterReserved) {
+    const ordered = [...lanes].sort(byEvictionOrder);
+    const fills = new Map();
+    let remaining = Math.max(0, budgetAfterReserved);
+    for (const lane of ordered) {
+        const cap = Math.min(lane.row.maxTokens, remaining);
+        const fill = selectScoredByTokenBudget(lane.items, cap);
+        fills.set(lane.row.laneId, fill);
+        remaining -= fill.tokens;
+    }
+    return fills;
+}
+function buildLaneFills(planned, effectiveBudget) {
+    const fills = new Map();
+    let reservedTokens = 0;
+    let nonEvictableOverflow = false;
+    const evictable = [];
+    for (const lane of planned) {
+        if (isNonEvictable(lane.row)) {
+            const fill = includeAll(lane.items);
+            fills.set(lane.row.laneId, fill);
+            reservedTokens += fill.tokens;
+            if (fill.tokens > lane.row.maxTokens) {
+                nonEvictableOverflow = true;
+            }
+        }
+        else {
+            evictable.push(lane);
+        }
+    }
+    const evictableFills = fillEvictableLanes(evictable, effectiveBudget - reservedTokens);
+    for (const [laneId, fill] of evictableFills) {
+        fills.set(laneId, fill);
+    }
+    return { fills, reservedTokens, nonEvictableOverflow };
+}
+function capForLane(budget, laneId) {
+    for (const row of budget.lanes) {
+        if (row.laneId === laneId) {
+            return row.maxTokens;
+        }
+    }
+    return 0;
+}
+// Emits the allocated lanes in the canonical CONTEXT_LANE_IDS order so a later prompt assembler
+// can place them START -> END deterministically (lost-in-the-middle layout obligation).
+function orderResults(budget, fills) {
+    const out = [];
+    for (const laneId of CONTEXT_LANE_IDS) {
+        const fill = fills.get(laneId);
+        if (fill !== undefined) {
+            out.push(toAllocatedLane(laneId, fill, capForLane(budget, laneId)));
+        }
+    }
+    return out;
+}
+export function allocateContext(input) {
+    const effectiveBudget = input.profile.effectiveInputBudget;
+    const planned = planLanes(input);
+    const { fills, reservedTokens, nonEvictableOverflow } = buildLaneFills(planned, effectiveBudget);
+    const lanes = orderResults(input.budget, fills);
+    const totalEstimatedTokens = lanes.reduce((sum, lane) => sum + lane.estimatedTokens, 0);
+    const overflow = nonEvictableOverflow || reservedTokens > effectiveBudget;
+    const budgetPressure = overflow
+        ? "exceeded"
+        : pressureFor(totalEstimatedTokens, effectiveBudget);
+    const diagnostics = {
+        schemaVersion: CONTEXT_ENGINEERING_SCHEMA_VERSION,
+        profile: input.profile,
+        totalEstimatedTokens,
+        budgetPressure,
+        lanes: lanes.map((lane) => lane.diagnostics),
+        orderedForRecency: true,
+    };
+    return { lanes, diagnostics, totalEstimatedTokens };
+}

package/dist/context-budget/compaction-helpers.d.ts

@@ -0,0 +1,44 @@
+import { type ContextAssumption, type ContextCommandOutcome, type ContextInvalidationKey, type ContextLaneId, type ContextPreservedFact, type ContextProvenanceRef, type ContextRehydrationHandle, type ContextUserConstraint } from "@oscharko-dev/keiko-contracts";
+import type { ContextLaneInput, ContextLaneItemInput } from "./allocator.js";
+export interface CompactionDigest {
+    readonly preservedFacts?: readonly ContextPreservedFact[] | undefined;
+    readonly assumptions?: readonly ContextAssumption[] | undefined;
+    readonly userConstraints?: readonly ContextUserConstraint[] | undefined;
+    readonly decisions?: readonly string[] | undefined;
+    readonly openQuestions?: readonly string[] | undefined;
+    readonly filesInspected?: readonly string[] | undefined;
+    readonly filesChanged?: readonly string[] | undefined;
+    readonly commandOutcomes?: readonly ContextCommandOutcome[] | undefined;
+    readonly failingTests?: readonly string[] | undefined;
+    readonly droppedCategories?: readonly string[] | undefined;
+}
+export interface DigestProjection {
+    readonly preservedFacts?: readonly ContextPreservedFact[] | undefined;
+    readonly assumptions?: readonly ContextAssumption[] | undefined;
+    readonly userConstraints?: readonly ContextUserConstraint[] | undefined;
+    readonly decisions?: readonly string[] | undefined;
+    readonly openQuestions?: readonly string[] | undefined;
+    readonly filesInspected?: readonly string[] | undefined;
+    readonly filesChanged?: readonly string[] | undefined;
+    readonly commandOutcomes?: readonly ContextCommandOutcome[] | undefined;
+    readonly failingTests?: readonly string[] | undefined;
+    readonly droppedCategories?: readonly string[] | undefined;
+}
+export declare function projectFacts(facts: readonly ContextPreservedFact[]): {
+    readonly kept: readonly ContextPreservedFact[];
+    readonly dropped: number;
+};
+export declare function projectDigest(digest: CompactionDigest): DigestProjection;
+export declare function tokensForItems(items: readonly ContextLaneItemInput[]): number;
+export declare function laneItems(lanes: readonly ContextLaneInput[], laneId: ContextLaneId): readonly ContextLaneItemInput[];
+export declare function itemsByIds(items: readonly ContextLaneItemInput[], ids: readonly string[]): readonly ContextLaneItemInput[];
+export declare function buildSourceSpans(excluded: readonly ContextLaneItemInput[], provenance: ReadonlyMap<string, ContextProvenanceRef>): readonly ContextProvenanceRef[];
+export declare function buildInvalidationKeys(spans: readonly ContextProvenanceRef[], fileHashes: ReadonlyMap<string, string> | undefined): readonly ContextInvalidationKey[];
+export declare function buildRehydrationHandle(input: {
+    readonly laneId: ContextLaneId;
+    readonly excludedIds: readonly string[];
+    readonly spans: readonly ContextProvenanceRef[];
+    readonly approxTokens: number;
+}): ContextRehydrationHandle;
+export declare function summaryHashOf(excluded: readonly ContextLaneItemInput[]): string;
+//# sourceMappingURL=compaction-helpers.d.ts.map

package/dist/context-budget/compaction-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compaction-helpers.d.ts","sourceRoot":"","sources":["../../src/context-budget/compaction-helpers.ts"],"names":[],"mappings":"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"}

package/dist/context-budget/compaction-helpers.js

@@ -0,0 +1,203 @@
+// Pure helpers for the compaction builder (ADR-0053 D4). No IO, no clock, no randomness. Every
+// free-text string that enters a record is scrubbed via redact() from keiko-security BEFORE
+// inclusion (the PR2 in-memory defense-in-depth; the CRITICAL BOUNDARY CORRECTION over ADR-0053
+// keeps keiko-workflows free of any keiko-memory-capture edge). Split from compaction.ts to hold
+// both files under the 400-LOC budget.
+import { CONTEXT_ENGINEERING_SCHEMA_VERSION, estimateTokens, validateContextPreservedFact, } from "@oscharko-dev/keiko-contracts";
+import { hashExcerptContent } from "@oscharko-dev/keiko-workspace";
+import { redact } from "@oscharko-dev/keiko-security";
+function redactStrings(values) {
+    return values === undefined ? undefined : values.map((value) => redact(value));
+}
+function redactRef(ref) {
+    return ref.notPersistedReason === undefined
+        ? ref
+        : { ...ref, notPersistedReason: redact(ref.notPersistedReason) };
+}
+// A redacted fact is kept ONLY when it still satisfies the sourceRef-or-inferred invariant. An
+// unsourced, non-inferred "fact" is DROPPED (and counted by the caller) — never silently coerced.
+function projectFact(fact) {
+    const redacted = {
+        ...fact,
+        statement: redact(fact.statement),
+        ...(fact.sourceRef !== undefined ? { sourceRef: redactRef(fact.sourceRef) } : {}),
+        ...(fact.corroborating !== undefined
+            ? { corroborating: fact.corroborating.map(redactRef) }
+            : {}),
+    };
+    return validateContextPreservedFact(redacted).ok ? redacted : undefined;
+}
+export function projectFacts(facts) {
+    const kept = [];
+    let dropped = 0;
+    for (const fact of facts) {
+        const projected = projectFact(fact);
+        if (projected === undefined) {
+            dropped += 1;
+        }
+        else {
+            kept.push(projected);
+        }
+    }
+    return { kept, dropped };
+}
+function projectAssumption(assumption) {
+    return {
+        ...assumption,
+        statement: redact(assumption.statement),
+        rationale: redact(assumption.rationale),
+    };
+}
+function projectConstraint(constraint) {
+    return {
+        ...constraint,
+        statement: redact(constraint.statement),
+        ...(constraint.sourceRef !== undefined ? { sourceRef: redactRef(constraint.sourceRef) } : {}),
+    };
+}
+function projectOutcome(outcome) {
+    return {
+        ...outcome,
+        command: redact(outcome.command),
+        summary: redact(outcome.summary),
+    };
+}
+// The structured (typed) digest members: facts validated + redacted, assumptions/constraints/
+// outcomes redacted in their free-text members. Facts stay strictly separate from assumptions.
+function projectStructured(digest) {
+    return {
+        ...(digest.preservedFacts !== undefined
+            ? { preservedFacts: projectFacts(digest.preservedFacts).kept }
+            : {}),
+        ...(digest.assumptions !== undefined
+            ? { assumptions: digest.assumptions.map(projectAssumption) }
+            : {}),
+        ...(digest.userConstraints !== undefined
+            ? { userConstraints: digest.userConstraints.map(projectConstraint) }
+            : {}),
+        ...(digest.commandOutcomes !== undefined
+            ? { commandOutcomes: digest.commandOutcomes.map(projectOutcome) }
+            : {}),
+    };
+}
+// The free-text / path-list digest members. decisions/openQuestions/failingTests are redacted;
+// file-path lists are kept verbatim (paths are not free text and never reach the browser; PR5
+// applies the persistence-time redaction posture).
+function projectPlain(digest) {
+    return {
+        ...(digest.decisions !== undefined ? { decisions: redactStrings(digest.decisions) } : {}),
+        ...(digest.openQuestions !== undefined
+            ? { openQuestions: redactStrings(digest.openQuestions) }
+            : {}),
+        ...(digest.filesInspected !== undefined ? { filesInspected: digest.filesInspected } : {}),
+        ...(digest.filesChanged !== undefined ? { filesChanged: digest.filesChanged } : {}),
+        ...(digest.failingTests !== undefined
+            ? { failingTests: redactStrings(digest.failingTests) }
+            : {}),
+        ...(digest.droppedCategories !== undefined
+            ? { droppedCategories: digest.droppedCategories }
+            : {}),
+    };
+}
+// Projects the digest into the additive record fields: every free-text member is redacted, facts
+// are validated (unsourced facts dropped), assumptions stay strictly separate from facts.
+export function projectDigest(digest) {
+    return { ...projectStructured(digest), ...projectPlain(digest) };
+}
+export function tokensForItems(items) {
+    let total = 0;
+    for (const item of items) {
+        total += estimateTokens(item.text);
+    }
+    return total;
+}
+export function laneItems(lanes, laneId) {
+    for (const lane of lanes) {
+        if (lane.laneId === laneId) {
+            return lane.items;
+        }
+    }
+    return [];
+}
+export function itemsByIds(items, ids) {
+    const byId = new Map(items.map((item) => [item.id, item]));
+    const out = [];
+    for (const id of ids) {
+        const found = byId.get(id);
+        if (found !== undefined) {
+            out.push(found);
+        }
+    }
+    return out;
+}
+// Enriches a repo-file ref with the per-excerpt content hash of the EXACT excluded text (the finer
+// invalidation signal, ADR-0053 REFINEMENT 2). Non-repo-file refs are returned unchanged.
+function enrichRef(ref, text) {
+    if (ref.kind !== "repo-file" || text === undefined) {
+        return ref;
+    }
+    return { ...ref, contentHash: hashExcerptContent(text) };
+}
+export function buildSourceSpans(excluded, provenance) {
+    const spans = [];
+    for (const item of excluded) {
+        const ref = provenance.get(item.id);
+        if (ref !== undefined) {
+            spans.push(enrichRef(ref, item.text));
+        }
+    }
+    return spans;
+}
+export function buildInvalidationKeys(spans, fileHashes) {
+    if (fileHashes === undefined) {
+        return [];
+    }
+    const keys = [];
+    const seen = new Set();
+    for (const span of spans) {
+        const scopePath = span.scopePath;
+        if (span.kind !== "repo-file" || scopePath === undefined || seen.has(scopePath)) {
+            continue;
+        }
+        const contentHash = fileHashes.get(scopePath);
+        if (contentHash !== undefined) {
+            seen.add(scopePath);
+            keys.push({ scopePath, contentHash });
+        }
+    }
+    return keys;
+}
+// Stable handle id: hashExcerptContent over the laneId plus the SORTED excluded ids, so the same
+// eviction set always yields the same opaque key regardless of allocator ordering.
+function handleId(laneId, excludedIds) {
+    const sorted = [...excludedIds].sort((a, b) => (a < b ? -1 : 1));
+    return hashExcerptContent(`${laneId}:${sorted.join(",")}`);
+}
+// Copies the kind/scopePath/lineRange/contentHash of a single repo-file excerpt onto the handle so
+// rehydrateHandle can resolve it directly. Only when EXACTLY one excluded item is a repo-file span.
+function singleRepoFileFields(spans) {
+    const repoFiles = spans.filter((span) => span.kind === "repo-file");
+    const only = repoFiles.length === 1 ? repoFiles[0] : undefined;
+    if (only === undefined) {
+        return {};
+    }
+    return {
+        kind: only.kind,
+        ...(only.scopePath !== undefined ? { scopePath: only.scopePath } : {}),
+        ...(only.lineRange !== undefined ? { lineRange: only.lineRange } : {}),
+        ...(only.contentHash !== undefined ? { contentHash: only.contentHash } : {}),
+    };
+}
+export function buildRehydrationHandle(input) {
+    return {
+        schemaVersion: CONTEXT_ENGINEERING_SCHEMA_VERSION,
+        laneId: input.laneId,
+        handleId: handleId(input.laneId, input.excludedIds),
+        itemCount: input.excludedIds.length,
+        approxTokens: input.approxTokens,
+        ...singleRepoFileFields(input.spans),
+    };
+}
+export function summaryHashOf(excluded) {
+    return hashExcerptContent(excluded.map((item) => item.text).join("\n"));
+}

package/dist/context-budget/compaction.d.ts

@@ -0,0 +1,14 @@
+import { type ContextCompactionRecord, type ContextProvenanceRef } from "@oscharko-dev/keiko-contracts";
+import type { AllocateContextResult, ContextLaneInput } from "./allocator.js";
+import { type CompactionDigest } from "./compaction-helpers.js";
+export type { CompactionDigest } from "./compaction-helpers.js";
+export interface BuildCompactionInput {
+    readonly result: AllocateContextResult;
+    readonly lanes: readonly ContextLaneInput[];
+    readonly provenance: ReadonlyMap<string, ContextProvenanceRef>;
+    readonly orderedAt: number;
+    readonly fileHashes?: ReadonlyMap<string, string> | undefined;
+    readonly digest?: CompactionDigest | undefined;
+}
+export declare function buildCompactionRecords(input: BuildCompactionInput): readonly ContextCompactionRecord[];
+//# sourceMappingURL=compaction.d.ts.map

package/dist/context-budget/compaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compaction.d.ts","sourceRoot":"","sources":["../../src/context-budget/compaction.ts"],"names":[],"mappings":"AAMA,OAAO,EAGL,KAAK,uBAAuB,EAG5B,KAAK,oBAAoB,EAE1B,MAAM,+BAA+B,CAAC;AAEvC,OAAO,KAAK,EAAE,qBAAqB,EAAwB,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACpG,OAAO,EASL,KAAK,gBAAgB,EAEtB,MAAM,yBAAyB,CAAC;AAEjC,YAAY,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAEhE,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAC;IACvC,QAAQ,CAAC,KAAK,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC5C,QAAQ,CAAC,UAAU,EAAE,WAAW,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;IAC/D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,CAAC,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC;IAC9D,QAAQ,CAAC,MAAM,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAC;CAChD;AAkHD,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,oBAAoB,GAC1B,SAAS,uBAAuB,EAAE,CAWpC"}

package/dist/context-budget/compaction.js

@@ -0,0 +1,97 @@
+// Pure, deterministic, no-IO compaction builder (ADR-0053 D4/D7). Consumes the allocator's
+// excludedItemIds and emits one ContextCompactionRecord per evicted lane. No clock, no randomness:
+// orderedAt is caller-injected, every hash is deterministic over the same bytes, so running the
+// builder twice on the same input yields a deeply-equal result. Secret scrubbing uses redact()
+// from keiko-security (NOT keiko-memory-capture — that would add a forbidden package-graph edge).
+import { CONTEXT_ENGINEERING_SCHEMA_VERSION, validateContextCompactionRecord, } from "@oscharko-dev/keiko-contracts";
+import { buildInvalidationKeys, buildRehydrationHandle, buildSourceSpans, itemsByIds, laneItems, projectDigest, summaryHashOf, tokensForItems, } from "./compaction-helpers.js";
+const HISTORY_SUMMARY_LANE = "history-summary";
+function reasonFor(lane) {
+    return lane.diagnostics.compactionReason ?? "budget";
+}
+function buildCore(input, lane, index) {
+    const allItems = laneItems(input.lanes, lane.laneId);
+    const included = itemsByIds(allItems, lane.includedItemIds);
+    const excluded = itemsByIds(allItems, lane.excludedItemIds);
+    const spans = buildSourceSpans(excluded, input.provenance);
+    const tokensBefore = tokensForItems(allItems);
+    const tokensAfter = tokensForItems(included);
+    return {
+        laneId: lane.laneId,
+        reason: reasonFor(lane),
+        itemsBefore: allItems.length,
+        itemsAfter: included.length,
+        tokensBefore,
+        tokensAfter,
+        summaryRefHash: summaryHashOf(excluded),
+        orderedAt: input.orderedAt + index,
+        sourceSpans: spans,
+        invalidationKeys: buildInvalidationKeys(spans, input.fileHashes),
+        rehydration: buildRehydrationHandle({
+            laneId: lane.laneId,
+            excludedIds: lane.excludedItemIds,
+            spans,
+            approxTokens: tokensBefore - tokensAfter,
+        }),
+    };
+}
+function withDigest(record, projection) {
+    return { ...record, ...projection };
+}
+function assembleRecord(core) {
+    const record = {
+        schemaVersion: CONTEXT_ENGINEERING_SCHEMA_VERSION,
+        laneId: core.laneId,
+        reason: core.reason,
+        itemsBefore: core.itemsBefore,
+        itemsAfter: core.itemsAfter,
+        tokensBefore: core.tokensBefore,
+        tokensAfter: core.tokensAfter,
+        summaryRefHash: core.summaryRefHash,
+        rehydration: core.rehydration,
+        orderedAt: core.orderedAt,
+        sourceSpans: core.sourceSpans,
+        ...(core.invalidationKeys.length > 0 ? { invalidationKeys: core.invalidationKeys } : {}),
+    };
+    return record;
+}
+function digestOnlyRecord(input, projection) {
+    const record = {
+        schemaVersion: CONTEXT_ENGINEERING_SCHEMA_VERSION,
+        laneId: HISTORY_SUMMARY_LANE,
+        reason: "summarize-then-drop",
+        itemsBefore: 0,
+        itemsAfter: 0,
+        tokensBefore: 0,
+        tokensAfter: 0,
+        orderedAt: input.orderedAt,
+        ...projection,
+    };
+    return record;
+}
+function evictedLanes(result) {
+    return result.lanes.filter((lane) => lane.excludedItemIds.length > 0);
+}
+function assertValid(record) {
+    const validation = validateContextCompactionRecord(record);
+    if (!validation.ok) {
+        throw new Error(`buildCompactionRecords produced an invalid record: ${validation.reasons.join(", ")}`);
+    }
+    return record;
+}
+// Builds one ContextCompactionRecord per evicted lane (in allocator order). The optional digest is
+// attached to the FIRST emitted record; if no lane evicted but a digest is supplied, a single
+// digest-only history-summary record is emitted instead. Throws if any produced record fails
+// validation (a builder bug). Pure and idempotent.
+export function buildCompactionRecords(input) {
+    const lanes = evictedLanes(input.result);
+    const projection = input.digest === undefined ? undefined : projectDigest(input.digest);
+    if (lanes.length === 0) {
+        return projection === undefined ? [] : [assertValid(digestOnlyRecord(input, projection))];
+    }
+    return lanes.map((lane, index) => {
+        const base = assembleRecord(buildCore(input, lane, index));
+        const enriched = index === 0 && projection !== undefined ? withDigest(base, projection) : base;
+        return assertValid(enriched);
+    });
+}

package/dist/context-budget/defaults.d.ts

@@ -0,0 +1,3 @@
+import { type ContextBudget } from "@oscharko-dev/keiko-contracts";
+export declare const DEFAULT_CONTEXT_BUDGET: ContextBudget;
+//# sourceMappingURL=defaults.d.ts.map

package/dist/context-budget/defaults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../../src/context-budget/defaults.ts"],"names":[],"mappings":"AAYA,OAAO,EAGL,KAAK,aAAa,EAEnB,MAAM,+BAA+B,CAAC;AA6DvC,eAAO,MAAM,sBAAsB,EAAE,aAI3B,CAAC"}

package/dist/context-budget/defaults.js

@@ -0,0 +1,75 @@
+// Default lane budget plan for the deterministic context allocator (ADR-0052 D3, "Default lane
+// budget"). One ContextLaneBudget row per the eight lanes, pinned against DEFAULT_CONTEXT_PROFILE
+// (effectiveInputBudget 116_000). The CONTRACT is the shape and the allocation order encoded by
+// `priority`; the specific integers are TUNABLE and may be re-balanced without any surface change.
+//
+// Allocation order (priority, lower = earlier): system-contract=0, user-task=1, active-plan=2,
+// working-memory=3, repo-evidence=4, tool-observations=5, history-summary=6, verification-evidence=7.
+// system-contract + user-task are non-evictable (eviction "none", minReservedTokens > 0) and are
+// reserved off the top. Per-lane maxTokens deliberately SUM ABOVE 116_000 — lanes compete and the
+// allocator enforces effectiveInputBudget at runtime. The non-evictable minReserved sums
+// (4_000 + 8_000 = 12_000) stay well under 116_000.
+import { CONTEXT_ENGINEERING_SCHEMA_VERSION, DEFAULT_CONTEXT_PROFILE, } from "@oscharko-dev/keiko-contracts";
+const DEFAULT_LANES = [
+    {
+        laneId: "system-contract",
+        priority: 0,
+        maxTokens: 6_000,
+        minReservedTokens: 4_000,
+        eviction: "none",
+    },
+    {
+        laneId: "user-task",
+        priority: 1,
+        maxTokens: 12_000,
+        minReservedTokens: 8_000,
+        eviction: "none",
+    },
+    {
+        laneId: "active-plan",
+        priority: 2,
+        maxTokens: 16_000,
+        minReservedTokens: 0,
+        eviction: "summarize-then-drop",
+    },
+    {
+        laneId: "working-memory",
+        priority: 3,
+        maxTokens: 24_000,
+        minReservedTokens: 0,
+        eviction: "summarize-then-drop",
+    },
+    {
+        laneId: "repo-evidence",
+        priority: 4,
+        maxTokens: 48_000,
+        minReservedTokens: 0,
+        eviction: "drop-lowest-score",
+    },
+    {
+        laneId: "tool-observations",
+        priority: 5,
+        maxTokens: 32_000,
+        minReservedTokens: 0,
+        eviction: "drop-oldest",
+    },
+    {
+        laneId: "history-summary",
+        priority: 6,
+        maxTokens: 16_000,
+        minReservedTokens: 0,
+        eviction: "summarize-then-drop",
+    },
+    {
+        laneId: "verification-evidence",
+        priority: 7,
+        maxTokens: 16_000,
+        minReservedTokens: 0,
+        eviction: "drop-oldest",
+    },
+];
+export const DEFAULT_CONTEXT_BUDGET = {
+    schemaVersion: CONTEXT_ENGINEERING_SCHEMA_VERSION,
+    profile: DEFAULT_CONTEXT_PROFILE,
+    lanes: DEFAULT_LANES,
+};