@oscharko-dev/keiko-contracts 0.2.6 → 0.2.7

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"}

package/dist/context-observations-validation.js

@@ -0,0 +1,252 @@
+// Pure structural validators for the shaped tool-observation contracts (ADR-0054, PR3-W1). 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 and reuses ContextValidationResult. STRUCTURAL ONLY: shape, finite
+// non-negative numbers, bounded counts within the MAX_* constants, valid stream enum, valid
+// laneId/kind. Policy (e.g. which tools may be shaped) is NOT enforced here.
+//
+// Split from context-observations.ts to keep both files under the 400-LOC budget (mirrors the
+// context-engineering-validation.ts split).
+import { CONTEXT_ENGINEERING_SCHEMA_VERSION } from "./context-engineering.js";
+import { MAX_FAILING_TEST_NAMES, MAX_OBSERVATION_EXCERPT_BYTES, MAX_OBSERVATION_QUERY_BYTES, MAX_STACK_FRAME_LINES, MAX_TOP_RANGES, } from "./context-observations.js";
+import { isContextLaneId } from "./context-engineering-validation.js";
+const TOOL_OBSERVATION_KINDS = ["command", "test", "search", "browser"];
+const STREAMS = ["stdout", "stderr"];
+// ─── 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 isExitCode(value) {
+    return value === null || (typeof value === "number" && Number.isFinite(value));
+}
+function isNonEmptyTrimmed(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+function isOptionalFiniteNonNegativeNumber(value) {
+    return value === undefined || isFiniteNonNegativeNumber(value);
+}
+function isOptionalBoolean(value) {
+    return value === undefined || typeof value === "boolean";
+}
+function isOptionalNonEmptyString(value) {
+    return value === undefined || isNonEmptyTrimmed(value);
+}
+function pushIf(reasons, condition, reason) {
+    if (condition) {
+        reasons.push(reason);
+    }
+}
+function buildResult(reasons) {
+    return reasons.length === 0 ? { ok: true } : { ok: false, reasons };
+}
+// ─── Kind guard ──────────────────────────────────────────────────────────────
+export function isContextToolObservationKind(value) {
+    return typeof value === "string" && TOOL_OBSERVATION_KINDS.includes(value);
+}
+// ─── ContextToolRehydrationHandle ──────────────────────────────────────────────
+function collectRehydration(value, prefix) {
+    if (!isRecord(value)) {
+        return [`${prefix} invalid`];
+    }
+    const reasons = [];
+    pushIf(reasons, value.schemaVersion !== CONTEXT_ENGINEERING_SCHEMA_VERSION, `${prefix}.schemaVersion mismatch`);
+    pushIf(reasons, !isContextLaneId(value.laneId), `${prefix}.laneId invalid`);
+    pushIf(reasons, value.kind !== "tool-result", `${prefix}.kind invalid`);
+    pushIf(reasons, !isNonEmptyTrimmed(value.artifactId), `${prefix}.artifactId invalid`);
+    pushIf(reasons, !isFiniteNonNegativeNumber(value.itemCount), `${prefix}.itemCount invalid`);
+    pushIf(reasons, !isFiniteNonNegativeNumber(value.approxTokens), `${prefix}.approxTokens invalid`);
+    pushIf(reasons, !isOptionalNonEmptyString(value.notPersistedReason), `${prefix}.notPersistedReason invalid`);
+    return reasons;
+}
+export function validateContextToolRehydrationHandle(value) {
+    return buildResult(collectRehydration(value, "rehydration"));
+}
+function collectOptionalRehydration(value, prefix) {
+    return value === undefined ? [] : collectRehydration(value, prefix);
+}
+// ─── Shared injection-signal optionals (command/test/search/browser) ────────────
+function collectInjectionOptionals(value, prefix) {
+    const reasons = [];
+    pushIf(reasons, !isOptionalFiniteNonNegativeNumber(value.injectionSignalCount), `${prefix}.injectionSignalCount invalid`);
+    pushIf(reasons, !isOptionalBoolean(value.hasCriticalInjectionSignal), `${prefix}.hasCriticalInjectionSignal invalid`);
+    return reasons;
+}
+// ─── ShapedStreamExcerpt ────────────────────────────────────────────────────────
+function collectExcerpts(value, prefix) {
+    if (!Array.isArray(value)) {
+        return [`${prefix}.excerpts invalid`];
+    }
+    const reasons = [];
+    let totalBytes = 0;
+    value.forEach((entry, index) => {
+        const at = `${prefix}.excerpts[${String(index)}]`;
+        if (!isRecord(entry)) {
+            reasons.push(`${at} invalid`);
+            return;
+        }
+        pushIf(reasons, typeof entry.stream !== "string" || !STREAMS.includes(entry.stream), `${at}.stream invalid`);
+        pushIf(reasons, !isFiniteNonNegativeNumber(entry.bytes), `${at}.bytes invalid`);
+        pushIf(reasons, typeof entry.text !== "string", `${at}.text invalid`);
+        if (isFiniteNonNegativeNumber(entry.bytes)) {
+            totalBytes += entry.bytes;
+        }
+    });
+    pushIf(reasons, totalBytes > MAX_OBSERVATION_EXCERPT_BYTES, `${prefix}.excerpts exceed byte cap`);
+    return reasons;
+}
+// ─── ShapedCommandObservation ───────────────────────────────────────────────────
+function collectCommand(value, prefix) {
+    const reasons = [];
+    pushIf(reasons, !isNonEmptyTrimmed(value.observationId), `${prefix}.observationId invalid`);
+    pushIf(reasons, !isExitCode(value.exitCode), `${prefix}.exitCode invalid`);
+    pushIf(reasons, !isFiniteNonNegativeNumber(value.durationMs), `${prefix}.durationMs invalid`);
+    pushIf(reasons, typeof value.timedOut !== "boolean", `${prefix}.timedOut invalid`);
+    pushIf(reasons, typeof value.truncated !== "boolean", `${prefix}.truncated invalid`);
+    pushIf(reasons, !isOptionalFiniteNonNegativeNumber(value.omittedByteCount), `${prefix}.omittedByteCount invalid`);
+    reasons.push(...collectExcerpts(value.excerpts, prefix));
+    reasons.push(...collectInjectionOptionals(value, prefix));
+    reasons.push(...collectOptionalRehydration(value.rehydration, `${prefix}.rehydration`));
+    return reasons;
+}
+export function validateShapedCommandObservation(value) {
+    if (!isRecord(value)) {
+        return buildResult(["command invalid"]);
+    }
+    const reasons = [];
+    pushIf(reasons, value.kind !== "command", "command.kind invalid");
+    reasons.push(...collectCommand(value, "command"));
+    return buildResult(reasons);
+}
+// ─── ShapedTestObservation ──────────────────────────────────────────────────────
+function collectTestCounts(value, prefix) {
+    if (!isRecord(value)) {
+        return [`${prefix}.counts invalid`];
+    }
+    const reasons = [];
+    for (const key of ["passed", "failed", "skipped"]) {
+        pushIf(reasons, !isFiniteNonNegativeNumber(value[key]), `${prefix}.counts.${key} invalid`);
+    }
+    return reasons;
+}
+function collectBoundedStringArray(value, prefix, cap) {
+    if (!Array.isArray(value)) {
+        return [`${prefix} invalid`];
+    }
+    const reasons = [];
+    pushIf(reasons, value.length > cap, `${prefix} exceeds cap`);
+    value.forEach((entry, index) => {
+        pushIf(reasons, typeof entry !== "string", `${prefix}[${String(index)}] invalid`);
+    });
+    return reasons;
+}
+function collectTest(value, prefix) {
+    const reasons = [];
+    pushIf(reasons, !isNonEmptyTrimmed(value.observationId), `${prefix}.observationId invalid`);
+    pushIf(reasons, !isNonEmptyTrimmed(value.verificationKind), `${prefix}.verificationKind invalid`);
+    pushIf(reasons, !isNonEmptyTrimmed(value.status), `${prefix}.status invalid`);
+    pushIf(reasons, !isExitCode(value.exitCode), `${prefix}.exitCode invalid`);
+    pushIf(reasons, !isFiniteNonNegativeNumber(value.durationMs), `${prefix}.durationMs invalid`);
+    pushIf(reasons, typeof value.truncated !== "boolean", `${prefix}.truncated invalid`);
+    pushIf(reasons, !isOptionalFiniteNonNegativeNumber(value.omittedByteCount), `${prefix}.omittedByteCount invalid`);
+    reasons.push(...collectTestCounts(value.counts, prefix));
+    reasons.push(...collectBoundedStringArray(value.failingTestNames, `${prefix}.failingTestNames`, MAX_FAILING_TEST_NAMES));
+    reasons.push(...collectBoundedStringArray(value.stackFrameExcerpts, `${prefix}.stackFrameExcerpts`, MAX_STACK_FRAME_LINES));
+    pushIf(reasons, typeof value.outputSummary !== "string", `${prefix}.outputSummary invalid`);
+    reasons.push(...collectInjectionOptionals(value, prefix));
+    reasons.push(...collectOptionalRehydration(value.rehydration, `${prefix}.rehydration`));
+    return reasons;
+}
+export function validateShapedTestObservation(value) {
+    if (!isRecord(value)) {
+        return buildResult(["test invalid"]);
+    }
+    const reasons = [];
+    pushIf(reasons, value.kind !== "test", "test.kind invalid");
+    reasons.push(...collectTest(value, "test"));
+    return buildResult(reasons);
+}
+// ─── ShapedSearchObservation ────────────────────────────────────────────────────
+function collectTopRanges(value, prefix) {
+    if (!Array.isArray(value)) {
+        return [`${prefix}.topRanges invalid`];
+    }
+    const reasons = [];
+    pushIf(reasons, value.length > MAX_TOP_RANGES, `${prefix}.topRanges exceeds cap`);
+    value.forEach((entry, index) => {
+        const at = `${prefix}.topRanges[${String(index)}]`;
+        if (!isRecord(entry)) {
+            reasons.push(`${at} invalid`);
+            return;
+        }
+        pushIf(reasons, !isNonEmptyTrimmed(entry.scopePath), `${at}.scopePath invalid`);
+        pushIf(reasons, !isFiniteNonNegativeNumber(entry.startLine), `${at}.startLine invalid`);
+        pushIf(reasons, !isFiniteNonNegativeNumber(entry.endLine), `${at}.endLine invalid`);
+        pushIf(reasons, !isFiniteNonNegativeNumber(entry.score), `${at}.score invalid`);
+    });
+    return reasons;
+}
+function collectSearch(value, prefix) {
+    const reasons = [];
+    pushIf(reasons, !isNonEmptyTrimmed(value.observationId), `${prefix}.observationId invalid`);
+    const query = value.query;
+    pushIf(reasons, typeof query !== "string" || query.length > MAX_OBSERVATION_QUERY_BYTES, `${prefix}.query invalid`);
+    pushIf(reasons, !isNonEmptyTrimmed(value.searchKind), `${prefix}.searchKind invalid`);
+    pushIf(reasons, !isFiniteNonNegativeNumber(value.candidateCount), `${prefix}.candidateCount invalid`);
+    pushIf(reasons, !isFiniteNonNegativeNumber(value.omittedCount), `${prefix}.omittedCount invalid`);
+    pushIf(reasons, typeof value.truncated !== "boolean", `${prefix}.truncated invalid`);
+    reasons.push(...collectTopRanges(value.topRanges, prefix));
+    reasons.push(...collectInjectionOptionals(value, prefix));
+    return reasons;
+}
+export function validateShapedSearchObservation(value) {
+    if (!isRecord(value)) {
+        return buildResult(["search invalid"]);
+    }
+    const reasons = [];
+    pushIf(reasons, value.kind !== "search", "search.kind invalid");
+    reasons.push(...collectSearch(value, "search"));
+    return buildResult(reasons);
+}
+// ─── ShapedBrowserObservation (forward-defined; still validated) ─────────────────
+function collectBrowser(value, prefix) {
+    const reasons = [];
+    pushIf(reasons, !isNonEmptyTrimmed(value.observationId), `${prefix}.observationId invalid`);
+    pushIf(reasons, !isNonEmptyTrimmed(value.checkDescription), `${prefix}.checkDescription invalid`);
+    pushIf(reasons, typeof value.passed !== "boolean", `${prefix}.passed invalid`);
+    pushIf(reasons, !isFiniteNonNegativeNumber(value.durationMs), `${prefix}.durationMs invalid`);
+    pushIf(reasons, !isOptionalFiniteNonNegativeNumber(value.a11yViolationCount), `${prefix}.a11yViolationCount invalid`);
+    pushIf(reasons, !isOptionalNonEmptyString(value.screenshotScopePath), `${prefix}.screenshotScopePath invalid`);
+    reasons.push(...collectInjectionOptionals(value, prefix));
+    reasons.push(...collectOptionalRehydration(value.rehydration, `${prefix}.rehydration`));
+    return reasons;
+}
+export function validateShapedBrowserObservation(value) {
+    if (!isRecord(value)) {
+        return buildResult(["browser invalid"]);
+    }
+    const reasons = [];
+    pushIf(reasons, value.kind !== "browser", "browser.kind invalid");
+    reasons.push(...collectBrowser(value, "browser"));
+    return buildResult(reasons);
+}
+// ─── Discriminated dispatch ──────────────────────────────────────────────────────
+export function validateContextToolObservation(value) {
+    if (!isRecord(value)) {
+        return buildResult(["observation invalid"]);
+    }
+    switch (value.kind) {
+        case "command":
+            return validateShapedCommandObservation(value);
+        case "test":
+            return validateShapedTestObservation(value);
+        case "search":
+            return validateShapedSearchObservation(value);
+        case "browser":
+            return validateShapedBrowserObservation(value);
+        default:
+            return buildResult(["observation.kind invalid"]);
+    }
+}

package/dist/context-observations.d.ts

@@ -0,0 +1,88 @@
+import { CONTEXT_ENGINEERING_SCHEMA_VERSION } from "./context-engineering.js";
+import type { ContextLaneId } from "./context-engineering.js";
+export declare const MAX_OBSERVATION_EXCERPT_BYTES = 4096;
+export declare const MAX_FAILING_TEST_NAMES = 16;
+export declare const MAX_OBSERVATION_QUERY_BYTES = 512;
+export declare const MAX_TOP_RANGES = 8;
+export declare const MAX_STACK_FRAME_LINES = 30;
+export interface ShapedStreamExcerpt {
+    readonly stream: "stdout" | "stderr";
+    readonly bytes: number;
+    readonly text: string;
+}
+export interface ShapedCommandObservation {
+    readonly kind: "command";
+    readonly observationId: string;
+    readonly exitCode: number | null;
+    readonly durationMs: number;
+    readonly timedOut: boolean;
+    readonly truncated: boolean;
+    readonly omittedByteCount?: number | undefined;
+    readonly excerpts: readonly ShapedStreamExcerpt[];
+    readonly injectionSignalCount?: number | undefined;
+    readonly hasCriticalInjectionSignal?: boolean | undefined;
+    readonly rehydration?: ContextToolRehydrationHandle | undefined;
+}
+export interface ShapedTestCounts {
+    readonly passed: number;
+    readonly failed: number;
+    readonly skipped: number;
+}
+export interface ShapedTestObservation {
+    readonly kind: "test";
+    readonly observationId: string;
+    readonly verificationKind: string;
+    readonly status: string;
+    readonly exitCode: number | null;
+    readonly durationMs: number;
+    readonly truncated: boolean;
+    readonly omittedByteCount?: number | undefined;
+    readonly counts: ShapedTestCounts;
+    readonly failingTestNames: readonly string[];
+    readonly stackFrameExcerpts: readonly string[];
+    readonly outputSummary: string;
+    readonly injectionSignalCount?: number | undefined;
+    readonly hasCriticalInjectionSignal?: boolean | undefined;
+    readonly rehydration?: ContextToolRehydrationHandle | undefined;
+}
+export interface ShapedSearchRange {
+    readonly scopePath: string;
+    readonly startLine: number;
+    readonly endLine: number;
+    readonly score: number;
+}
+export interface ShapedSearchObservation {
+    readonly kind: "search";
+    readonly observationId: string;
+    readonly query: string;
+    readonly searchKind: string;
+    readonly candidateCount: number;
+    readonly topRanges: readonly ShapedSearchRange[];
+    readonly omittedCount: number;
+    readonly truncated: boolean;
+    readonly injectionSignalCount?: number | undefined;
+    readonly hasCriticalInjectionSignal?: boolean | undefined;
+}
+export interface ShapedBrowserObservation {
+    readonly kind: "browser";
+    readonly observationId: string;
+    readonly checkDescription: string;
+    readonly passed: boolean;
+    readonly durationMs: number;
+    readonly a11yViolationCount?: number | undefined;
+    readonly screenshotScopePath?: string | undefined;
+    readonly injectionSignalCount?: number | undefined;
+    readonly hasCriticalInjectionSignal?: boolean | undefined;
+    readonly rehydration?: ContextToolRehydrationHandle | undefined;
+}
+export type ContextToolObservation = ShapedCommandObservation | ShapedTestObservation | ShapedSearchObservation | ShapedBrowserObservation;
+export interface ContextToolRehydrationHandle {
+    readonly schemaVersion: typeof CONTEXT_ENGINEERING_SCHEMA_VERSION;
+    readonly laneId: ContextLaneId;
+    readonly kind: "tool-result";
+    readonly artifactId: string;
+    readonly itemCount: number;
+    readonly approxTokens: number;
+    readonly notPersistedReason?: string | undefined;
+}
+//# sourceMappingURL=context-observations.d.ts.map

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

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

package/dist/context-observations.js

@@ -0,0 +1,19 @@
+// Shaped observations for the tool-observations context lane (ADR-0054, PR3-W1). Pure readonly
+// contracts, no IO, no clock, no randomness, no sibling @oscharko-dev/keiko-* import (contracts is
+// a strict leaf). Produced by keiko-workflows/src/observations/ (PR3-W3); consumed by the lane
+// assembler (PR4). Each shape is a bounded, redaction-proven, injection-flagged view of a single
+// raw tool result — never the full raw output. The discriminated union ContextToolObservation
+// wraps the three concrete shaped types plus the forward-defined browser type.
+//
+// Validators follow the connected-context.ts isRecord + predicate envelope and live in the sibling
+// context-observations-validation.ts to keep both files under the 400-LOC budget (mirrors the
+// context-engineering-validation.ts split).
+import { CONTEXT_ENGINEERING_SCHEMA_VERSION } from "./context-engineering.js";
+// ─── Size constants (tunable; not part of the public interface shape) ─────── [PR3]
+// Frozen defaults for the shapers. They do not appear in the shaped types themselves so they can
+// be re-tuned without a contract change.
+export const MAX_OBSERVATION_EXCERPT_BYTES = 4_096; // total across all stream excerpts per observation
+export const MAX_FAILING_TEST_NAMES = 16;
+export const MAX_OBSERVATION_QUERY_BYTES = 512;
+export const MAX_TOP_RANGES = 8;
+export const MAX_STACK_FRAME_LINES = 30; // total across all stackFrameExcerpts per observation