@oscharko-dev/keiko-contracts 0.2.6 → 0.2.8

package/dist/context-engineering-validation.js

@@ -0,0 +1,171 @@
+// Pure structural validators for the context-engineering contracts (ADR-0052). No filesystem,
+// no clock, no crypto, no randomness — every helper inspects the structure of an `unknown`
+// payload and reports which invariants failed. Follows the connected-context.ts isRecord +
+// predicate envelope. STRUCTURAL ONLY: shape, finite non-negative numbers, schemaVersion
+// literal, enum membership, the effectiveInputBudget identity. Policy (e.g. "system-contract
+// must be non-evictable") is NOT enforced here — that belongs to the allocator.
+//
+// Split from context-engineering.ts to keep both files under the 400-LOC budget (mirrors the
+// memory-validation.ts / memory-operations-validation.ts split).
+import { CONTEXT_ENGINEERING_SCHEMA_VERSION, CONTEXT_EVICTION_POLICIES, CONTEXT_LANE_IDS, } from "./context-engineering.js";
+const BUDGET_PRESSURES = ["low", "moderate", "high", "exceeded"];
+// ─── Shared primitives (local; contracts is a leaf, no shared-util import) ──────
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function isFiniteNonNegativeNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+function isNonEmptyTrimmed(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+function pushIf(reasons, condition, reason) {
+    if (condition) {
+        reasons.push(reason);
+    }
+}
+function buildResult(reasons) {
+    return reasons.length === 0 ? { ok: true } : { ok: false, reasons };
+}
+function schemaMismatch(actual) {
+    return actual !== CONTEXT_ENGINEERING_SCHEMA_VERSION;
+}
+// ─── Enum guards ────────────────────────────────────────────────────────────────
+export function isContextLaneId(value) {
+    return typeof value === "string" && CONTEXT_LANE_IDS.includes(value);
+}
+function isEvictionPolicy(value) {
+    return (typeof value === "string" && CONTEXT_EVICTION_POLICIES.includes(value));
+}
+function isBudgetPressure(value) {
+    return typeof value === "string" && BUDGET_PRESSURES.includes(value);
+}
+// ─── ContextProfile ─────────────────────────────────────────────────────────────
+function collectProfileReasons(profile, prefix) {
+    const reasons = [];
+    pushIf(reasons, schemaMismatch(profile.schemaVersion), `${prefix}.schemaVersion mismatch`);
+    pushIf(reasons, !isFiniteNonNegativeNumber(profile.maxInputTokens), `${prefix}.maxInputTokens invalid`);
+    pushIf(reasons, !isFiniteNonNegativeNumber(profile.reservedOutputTokens), `${prefix}.reservedOutputTokens invalid`);
+    pushIf(reasons, !isFiniteNonNegativeNumber(profile.safetyMarginTokens), `${prefix}.safetyMarginTokens invalid`);
+    pushIf(reasons, !isFiniteNonNegativeNumber(profile.effectiveInputBudget), `${prefix}.effectiveInputBudget invalid`);
+    pushIf(reasons, !isNonEmptyTrimmed(profile.tokenEstimatorId), `${prefix}.tokenEstimatorId empty`);
+    return reasons;
+}
+function checkBudgetIdentity(profile, prefix) {
+    const max = profile.maxInputTokens;
+    const reserved = profile.reservedOutputTokens;
+    const safety = profile.safetyMarginTokens;
+    const effective = profile.effectiveInputBudget;
+    if (typeof max !== "number" ||
+        typeof reserved !== "number" ||
+        typeof safety !== "number" ||
+        typeof effective !== "number") {
+        return [];
+    }
+    const expected = Math.max(0, max - reserved - safety);
+    return effective === expected ? [] : [`${prefix}.effectiveInputBudget mismatch`];
+}
+function validateModelMetadata(value, prefix) {
+    if (value === undefined) {
+        return [];
+    }
+    if (!isRecord(value)) {
+        return [`${prefix}.model invalid`];
+    }
+    const reasons = [];
+    for (const key of ["id", "provider", "notes"]) {
+        const field = value[key];
+        pushIf(reasons, field !== undefined && typeof field !== "string", `${prefix}.model.${key} invalid`);
+    }
+    return reasons;
+}
+function collectProfile(value, prefix) {
+    if (!isRecord(value)) {
+        return [`${prefix} invalid`];
+    }
+    const reasons = collectProfileReasons(value, prefix);
+    reasons.push(...checkBudgetIdentity(value, prefix));
+    reasons.push(...validateModelMetadata(value.model, prefix));
+    return reasons;
+}
+export function validateContextProfile(value) {
+    return buildResult(collectProfile(value, "profile"));
+}
+// ─── ContextLaneBudget ────────────────────────────────────────────────────────
+function collectLaneBudget(value, prefix) {
+    if (!isRecord(value)) {
+        return [`${prefix} invalid`];
+    }
+    const reasons = [];
+    pushIf(reasons, !isContextLaneId(value.laneId), `${prefix}.laneId invalid`);
+    pushIf(reasons, !isFiniteNonNegativeNumber(value.priority), `${prefix}.priority invalid`);
+    pushIf(reasons, !isFiniteNonNegativeNumber(value.maxTokens), `${prefix}.maxTokens invalid`);
+    pushIf(reasons, !isFiniteNonNegativeNumber(value.minReservedTokens), `${prefix}.minReservedTokens invalid`);
+    pushIf(reasons, !isEvictionPolicy(value.eviction), `${prefix}.eviction invalid`);
+    return reasons;
+}
+// ─── ContextBudget ──────────────────────────────────────────────────────────────
+export function validateContextBudget(value) {
+    if (!isRecord(value)) {
+        return buildResult(["budget invalid"]);
+    }
+    const reasons = [];
+    pushIf(reasons, schemaMismatch(value.schemaVersion), "budget.schemaVersion mismatch");
+    reasons.push(...collectProfile(value.profile, "budget.profile"));
+    if (!Array.isArray(value.lanes)) {
+        reasons.push("budget.lanes invalid");
+        return buildResult(reasons);
+    }
+    value.lanes.forEach((lane, index) => {
+        reasons.push(...collectLaneBudget(lane, `budget.lanes[${String(index)}]`));
+    });
+    return buildResult(reasons);
+}
+// ─── ContextLaneDiagnostics ──────────────────────────────────────────────────────
+function collectLaneDiagnostics(value, prefix) {
+    if (!isRecord(value)) {
+        return [`${prefix} invalid`];
+    }
+    const reasons = [];
+    pushIf(reasons, !isContextLaneId(value.laneId), `${prefix}.laneId invalid`);
+    pushIf(reasons, !isFiniteNonNegativeNumber(value.estimatedTokens), `${prefix}.estimatedTokens invalid`);
+    pushIf(reasons, !isFiniteNonNegativeNumber(value.includedItems), `${prefix}.includedItems invalid`);
+    pushIf(reasons, !isFiniteNonNegativeNumber(value.excludedItems), `${prefix}.excludedItems invalid`);
+    pushIf(reasons, !isBudgetPressure(value.budgetPressure), `${prefix}.budgetPressure invalid`);
+    pushIf(reasons, value.compactionReason !== undefined && typeof value.compactionReason !== "string", `${prefix}.compactionReason invalid`);
+    reasons.push(...collectProvenanceCounts(value.provenanceCounts, prefix));
+    return reasons;
+}
+function collectProvenanceCounts(value, prefix) {
+    if (value === undefined) {
+        return [];
+    }
+    if (!isRecord(value)) {
+        return [`${prefix}.provenanceCounts invalid`];
+    }
+    const reasons = [];
+    for (const count of Object.values(value)) {
+        pushIf(reasons, !isFiniteNonNegativeNumber(count), `${prefix}.provenanceCounts value invalid`);
+    }
+    return reasons;
+}
+// ─── ContextAssemblyDiagnostics ──────────────────────────────────────────────────
+export function validateContextAssemblyDiagnostics(value) {
+    if (!isRecord(value)) {
+        return buildResult(["assembly invalid"]);
+    }
+    const reasons = [];
+    pushIf(reasons, schemaMismatch(value.schemaVersion), "assembly.schemaVersion mismatch");
+    reasons.push(...collectProfile(value.profile, "assembly.profile"));
+    pushIf(reasons, !isFiniteNonNegativeNumber(value.totalEstimatedTokens), "assembly.totalEstimatedTokens invalid");
+    pushIf(reasons, !isBudgetPressure(value.budgetPressure), "assembly.budgetPressure invalid");
+    pushIf(reasons, typeof value.orderedForRecency !== "boolean", "assembly.orderedForRecency invalid");
+    if (!Array.isArray(value.lanes)) {
+        reasons.push("assembly.lanes invalid");
+        return buildResult(reasons);
+    }
+    value.lanes.forEach((lane, index) => {
+        reasons.push(...collectLaneDiagnostics(lane, `assembly.lanes[${String(index)}]`));
+    });
+    return buildResult(reasons);
+}

package/dist/context-engineering.d.ts

@@ -0,0 +1,148 @@
+export declare const CONTEXT_ENGINEERING_SCHEMA_VERSION: "1";
+export declare const DEFAULT_TOKEN_ESTIMATOR_ID: "keiko-conservative-utf8-v1";
+export type ContextLaneId = "system-contract" | "user-task" | "active-plan" | "repo-evidence" | "tool-observations" | "working-memory" | "history-summary" | "verification-evidence";
+export declare const CONTEXT_LANE_IDS: readonly ContextLaneId[];
+export type ContextEvictionPolicy = "none" | "summarize-then-drop" | "drop-oldest" | "drop-lowest-score";
+export declare const CONTEXT_EVICTION_POLICIES: readonly ContextEvictionPolicy[];
+export type ContextBudgetPressure = "low" | "moderate" | "high" | "exceeded";
+export interface ContextModelMetadata {
+    readonly id?: string | undefined;
+    readonly provider?: string | undefined;
+    readonly notes?: string | undefined;
+}
+export interface ContextProfile {
+    readonly schemaVersion: typeof CONTEXT_ENGINEERING_SCHEMA_VERSION;
+    readonly maxInputTokens: number;
+    readonly reservedOutputTokens: number;
+    readonly safetyMarginTokens: number;
+    readonly effectiveInputBudget: number;
+    readonly tokenEstimatorId: string;
+    readonly model?: ContextModelMetadata | undefined;
+}
+export declare const DEFAULT_CONTEXT_PROFILE: ContextProfile;
+export interface ContextLaneBudget {
+    readonly laneId: ContextLaneId;
+    readonly priority: number;
+    readonly maxTokens: number;
+    readonly minReservedTokens: number;
+    readonly eviction: ContextEvictionPolicy;
+}
+export interface ContextBudget {
+    readonly schemaVersion: typeof CONTEXT_ENGINEERING_SCHEMA_VERSION;
+    readonly profile: ContextProfile;
+    readonly lanes: readonly ContextLaneBudget[];
+}
+export interface ContextLane {
+    readonly id: ContextLaneId;
+    readonly purpose: string;
+    readonly priority: number;
+    readonly budget: ContextLaneBudget;
+    readonly diagnostics?: ContextLaneDiagnostics | undefined;
+}
+export interface ContextLaneDiagnostics {
+    readonly laneId: ContextLaneId;
+    readonly estimatedTokens: number;
+    readonly includedItems: number;
+    readonly excludedItems: number;
+    readonly budgetPressure: ContextBudgetPressure;
+    readonly compactionReason?: string | undefined;
+    readonly provenanceCounts?: Readonly<Record<string, number>> | undefined;
+}
+export interface ContextAssemblyDiagnostics {
+    readonly schemaVersion: typeof CONTEXT_ENGINEERING_SCHEMA_VERSION;
+    readonly profile: ContextProfile;
+    readonly totalEstimatedTokens: number;
+    readonly budgetPressure: ContextBudgetPressure;
+    readonly lanes: readonly ContextLaneDiagnostics[];
+    readonly orderedForRecency: boolean;
+}
+export type ContextProvenanceRefKind = "repo-file" | "tool-result" | "evidence-atom" | "message";
+export interface ContextProvenanceRef {
+    readonly kind: ContextProvenanceRefKind;
+    readonly stableId: string;
+    readonly scopePath?: string | undefined;
+    readonly lineRange?: {
+        readonly startLine: number;
+        readonly endLine: number;
+    } | undefined;
+    readonly contentHash?: string | undefined;
+    readonly evidenceAtomId?: string | undefined;
+    readonly notPersistedReason?: string | undefined;
+}
+export interface ContextPreservedFact {
+    readonly statement: string;
+    readonly sourceRef?: ContextProvenanceRef | undefined;
+    readonly inferred?: boolean | undefined;
+    readonly corroborating?: readonly ContextProvenanceRef[] | undefined;
+    readonly rationale?: never;
+    readonly confidence?: never;
+}
+export interface ContextAssumption {
+    readonly statement: string;
+    readonly rationale: string;
+    readonly confidence: "low" | "medium" | "high";
+    readonly sourceRef?: never;
+    readonly inferred?: never;
+}
+export interface ContextUserConstraint {
+    readonly statement: string;
+    readonly sourceRef?: ContextProvenanceRef | undefined;
+}
+export interface ContextCommandOutcome {
+    readonly command: string;
+    readonly exitCode: number;
+    readonly summary: string;
+}
+export interface ContextInvalidationKey {
+    readonly scopePath: string;
+    readonly contentHash: string;
+}
+export interface ContextCompactionRecord {
+    readonly schemaVersion: typeof CONTEXT_ENGINEERING_SCHEMA_VERSION;
+    readonly laneId: ContextLaneId;
+    readonly reason: string;
+    readonly itemsBefore: number;
+    readonly itemsAfter: number;
+    readonly tokensBefore: number;
+    readonly tokensAfter: number;
+    readonly summaryRefHash?: string | undefined;
+    readonly rehydration?: ContextRehydrationHandle | undefined;
+    readonly orderedAt?: number | undefined;
+    readonly sourceSpans?: readonly ContextProvenanceRef[] | undefined;
+    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;
+    readonly invalidationKeys?: readonly ContextInvalidationKey[] | undefined;
+}
+export interface ContextRehydrationHandle {
+    readonly schemaVersion: typeof CONTEXT_ENGINEERING_SCHEMA_VERSION;
+    readonly laneId: ContextLaneId;
+    readonly handleId: string;
+    readonly itemCount: number;
+    readonly approxTokens: number;
+    readonly kind?: ContextProvenanceRefKind | undefined;
+    readonly scopePath?: string | undefined;
+    readonly lineRange?: {
+        readonly startLine: number;
+        readonly endLine: number;
+    } | undefined;
+    readonly contentHash?: string | undefined;
+    readonly evidenceAtomId?: string | undefined;
+    readonly notPersistedReason?: string | undefined;
+    readonly approvedSummary?: string | undefined;
+}
+export declare function estimateTokens(text: string): number;
+export declare function estimateTokensForSegments(segments: readonly string[]): number;
+export declare function deriveContextProfile(input: {
+    readonly maxInputTokens: number;
+    readonly reservedOutputTokens: number;
+    readonly safetyMarginTokens: number;
+}): ContextProfile;
+//# sourceMappingURL=context-engineering.d.ts.map

package/dist/context-engineering.d.ts.map

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

package/dist/context-engineering.js

@@ -0,0 +1,80 @@
+// Pure readonly contracts for the deterministic context-engineering layer (ADR-0052). No IO,
+// no clock, no randomness, no sibling @oscharko-dev/keiko-* import (contracts is a strict leaf).
+// estimateTokens is the single canonical token currency; the allocator that consumes
+// ContextProfile lives in keiko-workflows. Validators follow the connected-context.ts
+// isRecord + predicate envelope and live in the sibling context-engineering-validation.ts to
+// keep both files under the 400-LOC budget (mirrors the memory-validation.ts split).
+export const CONTEXT_ENGINEERING_SCHEMA_VERSION = "1";
+// Provenance string recording which estimator produced a profile's counts. The estimator
+// function itself cannot be a JSON-serializable contract field, so the id is carried instead.
+export const DEFAULT_TOKEN_ESTIMATOR_ID = "keiko-conservative-utf8-v1";
+export const CONTEXT_LANE_IDS = [
+    "system-contract",
+    "user-task",
+    "active-plan",
+    "repo-evidence",
+    "tool-observations",
+    "working-memory",
+    "history-summary",
+    "verification-evidence",
+];
+export const CONTEXT_EVICTION_POLICIES = [
+    "none",
+    "summarize-then-drop",
+    "drop-oldest",
+    "drop-lowest-score",
+];
+// Conservative defaults. 128k window, 8k reserved for output, 4k safety margin =>
+// 116k effective input budget. Frozen. `model` is intentionally omitted (optional).
+export const DEFAULT_CONTEXT_PROFILE = {
+    schemaVersion: CONTEXT_ENGINEERING_SCHEMA_VERSION,
+    maxInputTokens: 128_000,
+    reservedOutputTokens: 8_000,
+    safetyMarginTokens: 4_000,
+    effectiveInputBudget: 116_000,
+    tokenEstimatorId: DEFAULT_TOKEN_ESTIMATOR_ID,
+};
+// ─── Canonical token estimator (the single token currency) ─────────────────── [PR1]
+// Deterministic, conservative (slightly over-estimates), total (never throws), offline.
+//
+// bytes-per-token divisor. Deliberately SMALLER than the repo's looser bytes/4 norm so the
+// estimate over-counts versus a typical provider tokenization. Over-estimation is the safe
+// direction: the allocator fits fewer tokens than the provider would, never more.
+const TOKEN_BYTES_PER_TOKEN_DIVISOR = 3.5;
+// Small fixed structural overhead per segment, modelling per-message framing. Empty input
+// returns exactly this (never 0 / NaN).
+const TOKEN_STRUCTURAL_OVERHEAD = 2;
+// Mirrors conversation-budget.ts utf8ByteLength: TextEncoder when available, char-length
+// fallback for any legacy harness without it. Never throws.
+function utf8ByteLength(text) {
+    if (typeof TextEncoder !== "undefined") {
+        return new TextEncoder().encode(text).length;
+    }
+    return text.length;
+}
+export function estimateTokens(text) {
+    const bytes = utf8ByteLength(text);
+    return TOKEN_STRUCTURAL_OVERHEAD + Math.ceil(bytes / TOKEN_BYTES_PER_TOKEN_DIVISOR);
+}
+// Sum estimateTokens over a set of segments (e.g. messages). The per-segment overhead models
+// per-message framing. Total / never throws on [] or empty segments.
+export function estimateTokensForSegments(segments) {
+    let total = 0;
+    for (const segment of segments) {
+        total += estimateTokens(segment);
+    }
+    return total;
+}
+// Derives effectiveInputBudget = maxInputTokens − reservedOutputTokens − safetyMarginTokens,
+// clamped to >= 0. Pure. Used to build a ContextProfile from a customer model window override.
+export function deriveContextProfile(input) {
+    const effective = Math.max(0, input.maxInputTokens - input.reservedOutputTokens - input.safetyMarginTokens);
+    return {
+        schemaVersion: CONTEXT_ENGINEERING_SCHEMA_VERSION,
+        maxInputTokens: input.maxInputTokens,
+        reservedOutputTokens: input.reservedOutputTokens,
+        safetyMarginTokens: input.safetyMarginTokens,
+        effectiveInputBudget: effective,
+        tokenEstimatorId: DEFAULT_TOKEN_ESTIMATOR_ID,
+    };
+}

package/dist/context-observations-validation.d.ts

@@ -0,0 +1,9 @@
+import type { ContextValidationResult } from "./context-engineering-validation.js";
+export declare function isContextToolObservationKind(value: unknown): boolean;
+export declare function validateContextToolRehydrationHandle(value: unknown): ContextValidationResult;
+export declare function validateShapedCommandObservation(value: unknown): ContextValidationResult;
+export declare function validateShapedTestObservation(value: unknown): ContextValidationResult;
+export declare function validateShapedSearchObservation(value: unknown): ContextValidationResult;
+export declare function validateShapedBrowserObservation(value: unknown): ContextValidationResult;
+export declare function validateContextToolObservation(value: unknown): ContextValidationResult;
+//# sourceMappingURL=context-observations-validation.d.ts.map

package/dist/context-observations-validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-observations-validation.d.ts","sourceRoot":"","sources":["../src/context-observations-validation.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,qCAAqC,CAAC;AA6CnF,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEpE;AA0BD,wBAAgB,oCAAoC,CAAC,KAAK,EAAE,OAAO,GAAG,uBAAuB,CAE5F;AAqED,wBAAgB,gCAAgC,CAAC,KAAK,EAAE,OAAO,GAAG,uBAAuB,CAQxF;AA4DD,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,OAAO,GAAG,uBAAuB,CAQrF;AA6CD,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,OAAO,GAAG,uBAAuB,CAQvF;AAwBD,wBAAgB,gCAAgC,CAAC,KAAK,EAAE,OAAO,GAAG,uBAAuB,CAQxF;AAGD,wBAAgB,8BAA8B,CAAC,KAAK,EAAE,OAAO,GAAG,uBAAuB,CAgBtF"}