@oscharko-dev/keiko-contracts 0.2.0

package/dist/connected-context.js

@@ -0,0 +1,636 @@
+// Public type contracts for the connected repository context surface (Epic #177, Issue #178).
+// All string content carried by these types is already redacted upstream (keiko-security policy);
+// nothing here performs redaction, IO, hashing, clock reads, or randomness. Pure data + pure
+// validators only. The schemaVersion discriminant follows the same evolution rule as
+// EVIDENCE_SCHEMA_VERSION (ADR-0010 D2): a breaking change introduces a NEW literal member
+// rather than mutating "1". Leaf-package rule (ADR-0019 direction 1) means no
+// `@oscharko-dev/keiko-*` imports may appear in this module.
+// ─── Schema version ───────────────────────────────────────────────────────────
+export const CONNECTED_CONTEXT_SCHEMA_VERSION = "1";
+export const SELECTED_SCOPE_KINDS = [
+    "workspace-root",
+    "directory",
+    "files",
+];
+export const EVIDENCE_ATOM_PROVENANCE_KINDS = [
+    "lexical-search",
+    "file-listing",
+    "excerpt-read",
+    "structural",
+    "git-history",
+    "model-rerank",
+    "document-extract",
+];
+export const EVIDENCE_ATOM_REDACTION_STATES = [
+    "redacted",
+    "raw-internal",
+];
+export const DEFAULT_EXPLORATION_BUDGET = {
+    searchCallsMax: 16,
+    filesReadMax: 32,
+    excerptBytesMax: 131_072,
+    modelInputTokensMax: 32_000,
+    modelOutputTokensMax: 4_096,
+    elapsedMsMax: 30_000,
+    rerankCallsMax: 0,
+};
+export const RETRIEVAL_QUERY_KINDS = [
+    "natural-language",
+    "exact-symbol",
+    "file-pattern",
+    "regex",
+];
+export const CANDIDATE_OMISSION_REASONS = [
+    "outside-scope",
+    "binary",
+    "generated",
+    "ignored",
+    "size-exceeded",
+    "near-duplicate",
+    "low-relevance",
+    "redacted-only",
+    "budget-exhausted",
+    "tool-unavailable",
+    "unsupported-format",
+    "no-text-layer",
+    "malformed-document",
+    "encrypted-document",
+];
+export const CONNECTED_FILE_ROLES = [
+    "read-only",
+    "editable",
+];
+export const UNCERTAINTY_MARKER_KINDS = [
+    "no-evidence",
+    "stale-evidence",
+    "scope-incomplete",
+    "budget-clipped",
+    "tool-unavailable",
+    "low-confidence",
+];
+// Module-scope regex (avoid per-call allocation; safe — no backtracking risk).
+const WINDOWS_DRIVE_RE = /^[A-Za-z]:/;
+const WINDOWS_DRIVE_ABSOLUTE_RE = /^[A-Za-z]:[\\/]/;
+const WINDOWS_DEVICE_PREFIX_RE = /^[\\/]{2}[?.][\\/]/;
+const WINDOWS_UNC_PREFIX_RE = /^[\\/]{2}[^\\/?.]/;
+const REMOTE_URL_PREFIX_RE = /^[a-zA-Z][a-zA-Z0-9+\-.]*:\/\//;
+const TRAVERSAL_SEGMENT_RE = /(^|[\\/])(?:\.{1,2})(?:[\\/]|$)/;
+// The schema discriminant comparisons below are statically true at the type level (the
+// constant equals the literal field type), so we widen to `string` before comparing. This
+// keeps the validator honest against runtime inputs that bypass the type system — e.g.,
+// objects materialized from JSON.parse or cross-version manifests.
+function schemaMismatch(actual, expected) {
+    return actual !== expected;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function isFiniteNonNegativeInteger(value) {
+    return typeof value === "number" && Number.isInteger(value) && value >= 0;
+}
+function isFinitePositiveInteger(value) {
+    return typeof value === "number" && Number.isInteger(value) && value > 0;
+}
+function isNonEmptyTrimmed(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+function hasInvalidPathPrefix(path) {
+    if (path.startsWith("/")) {
+        return true;
+    }
+    if (path.startsWith("\\\\")) {
+        return true;
+    }
+    return WINDOWS_DRIVE_RE.test(path);
+}
+function hasInvalidSegments(path) {
+    const segments = path.split("/");
+    for (const segment of segments) {
+        if (segment.length === 0) {
+            return true;
+        }
+        if (segment === "." || segment === "..") {
+            return true;
+        }
+    }
+    return false;
+}
+export function isValidScopePath(path, options) {
+    if (typeof path !== "string") {
+        return false;
+    }
+    if (!options.mustBeRelative) {
+        return false;
+    }
+    if (path.length === 0) {
+        return false;
+    }
+    if (path.includes("\0")) {
+        return false;
+    }
+    // Backslashes are not valid path separators in POSIX workspace-relative paths; reject
+    // them before segment analysis so Windows-style traversals cannot slip through.
+    if (path.includes("\\")) {
+        return false;
+    }
+    if (hasInvalidPathPrefix(path)) {
+        return false;
+    }
+    return !hasInvalidSegments(path);
+}
+function isValidWorkspaceRootPath(path) {
+    if (typeof path !== "string") {
+        return false;
+    }
+    if (!isNonEmptyTrimmed(path)) {
+        return false;
+    }
+    if (path.includes("\0")) {
+        return false;
+    }
+    if (WINDOWS_DEVICE_PREFIX_RE.test(path) || WINDOWS_UNC_PREFIX_RE.test(path)) {
+        return false;
+    }
+    if (!WINDOWS_DRIVE_ABSOLUTE_RE.test(path) && REMOTE_URL_PREFIX_RE.test(path)) {
+        return false;
+    }
+    if (!path.startsWith("/") && !WINDOWS_DRIVE_ABSOLUTE_RE.test(path)) {
+        return false;
+    }
+    return !TRAVERSAL_SEGMENT_RE.test(path);
+}
+export function isValidLineRange(range) {
+    if (!isRecord(range)) {
+        return false;
+    }
+    if (!Number.isInteger(range.startLine) || !Number.isInteger(range.endLine)) {
+        return false;
+    }
+    if (range.startLine < 1) {
+        return false;
+    }
+    return range.endLine >= range.startLine;
+}
+export function isWithinBudget(usage, budget) {
+    if (!isRecord(usage) || !isRecord(budget)) {
+        return false;
+    }
+    const dims = [
+        [usage.searchCalls, budget.searchCallsMax],
+        [usage.filesRead, budget.filesReadMax],
+        [usage.excerptBytes, budget.excerptBytesMax],
+        [usage.modelInputTokens, budget.modelInputTokensMax],
+        [usage.modelOutputTokens, budget.modelOutputTokensMax],
+        [usage.elapsedMs, budget.elapsedMsMax],
+        [usage.rerankCalls, budget.rerankCallsMax],
+    ];
+    for (const dim of dims) {
+        const used = dim[0];
+        const cap = dim[1];
+        if (!Number.isFinite(used) || used < 0) {
+            return false;
+        }
+        if (used > cap) {
+            return false;
+        }
+    }
+    return true;
+}
+function pushIf(reasons, condition, reason) {
+    if (condition) {
+        reasons.push(reason);
+    }
+}
+function buildResult(reasons) {
+    return reasons.length === 0 ? { ok: true } : { ok: false, reasons };
+}
+function hasStringArray(value) {
+    return Array.isArray(value) && value.every((entry) => typeof entry === "string");
+}
+function appendPrefixedReasons(result, prefix, reasons) {
+    if (result.ok) {
+        return;
+    }
+    for (const reason of result.reasons) {
+        reasons.push(`${prefix}${reason}`);
+    }
+}
+function isRuntimeSelectedScope(value) {
+    if (!isRecord(value)) {
+        return false;
+    }
+    if (!SELECTED_SCOPE_KINDS.includes(value.kind)) {
+        return false;
+    }
+    return hasStringArray(value.relativePaths);
+}
+function isCandidateOmissionReason(value) {
+    return (typeof value === "string" &&
+        CANDIDATE_OMISSION_REASONS.includes(value));
+}
+function isConnectedFileRole(value) {
+    return typeof value === "string" && CONNECTED_FILE_ROLES.includes(value);
+}
+function isUncertaintyMarkerKind(value) {
+    return (typeof value === "string" && UNCERTAINTY_MARKER_KINDS.includes(value));
+}
+function validateScopeKindPaths(scope, reasons) {
+    const paths = scope.relativePaths;
+    if (scope.kind === "workspace-root" && paths.length !== 0) {
+        reasons.push("scope.relativePaths must be empty for workspace-root");
+    }
+    if (scope.kind === "directory" && paths.length !== 1) {
+        reasons.push("scope.relativePaths must have exactly one entry for directory");
+    }
+    if (scope.kind === "files" && paths.length < 1) {
+        reasons.push("scope.relativePaths must be non-empty for files");
+    }
+    for (const candidate of paths) {
+        if (!isValidScopePath(candidate, { mustBeRelative: true })) {
+            reasons.push("scope.relativePaths contains an invalid path");
+            return;
+        }
+    }
+}
+function isPathWithinSelectedScope(scope, candidatePath) {
+    if (typeof candidatePath !== "string") {
+        return false;
+    }
+    if (scope.kind === "workspace-root") {
+        return true;
+    }
+    return scope.relativePaths.some((scopePath) => candidatePath === scopePath || candidatePath.startsWith(`${scopePath}/`));
+}
+function pathsOverlap(a, b) {
+    return a === b || a.startsWith(`${b}/`) || b.startsWith(`${a}/`);
+}
+function setHasOverlappingPath(paths, candidatePath) {
+    for (const path of paths) {
+        if (pathsOverlap(path, candidatePath)) {
+            return true;
+        }
+    }
+    return false;
+}
+export function validateSelectedScope(scope) {
+    const reasons = [];
+    if (!isRecord(scope)) {
+        return buildResult(["scope invalid"]);
+    }
+    pushIf(reasons, schemaMismatch(scope.schemaVersion, CONNECTED_CONTEXT_SCHEMA_VERSION), "scope.schemaVersion mismatch");
+    pushIf(reasons, !isNonEmptyTrimmed(scope.scopeId), "scope.scopeId empty");
+    pushIf(reasons, !isNonEmptyTrimmed(scope.workspaceRoot), "scope.workspaceRoot empty");
+    if (isNonEmptyTrimmed(scope.workspaceRoot)) {
+        pushIf(reasons, !isValidWorkspaceRootPath(scope.workspaceRoot), "scope.workspaceRoot invalid");
+    }
+    pushIf(reasons, !SELECTED_SCOPE_KINDS.includes(scope.kind), "scope.kind invalid");
+    if (!Array.isArray(scope.relativePaths)) {
+        reasons.push("scope.relativePaths invalid");
+    }
+    else if (!hasStringArray(scope.relativePaths)) {
+        reasons.push("scope.relativePaths contains an invalid path");
+    }
+    else if (SELECTED_SCOPE_KINDS.includes(scope.kind)) {
+        validateScopeKindPaths(scope, reasons);
+    }
+    pushIf(reasons, !isFiniteNonNegativeInteger(scope.connectedAtMs), "scope.connectedAtMs invalid");
+    if (scope.conversationId !== undefined) {
+        pushIf(reasons, !isNonEmptyTrimmed(scope.conversationId), "scope.conversationId empty");
+    }
+    return buildResult(reasons);
+}
+function validateLedgerRef(ref, reasons, prefix) {
+    if (!isRecord(ref)) {
+        reasons.push(`${prefix}.ledgerRef invalid`);
+        return;
+    }
+    if (schemaMismatch(ref.evidenceSchemaVersion, "1")) {
+        reasons.push(`${prefix}.ledgerRef.evidenceSchemaVersion mismatch`);
+    }
+    if (!isNonEmptyTrimmed(ref.runId)) {
+        reasons.push(`${prefix}.ledgerRef.runId empty`);
+    }
+    if (ref.atomId !== undefined && !isNonEmptyTrimmed(ref.atomId)) {
+        reasons.push(`${prefix}.ledgerRef.atomId empty`);
+    }
+}
+function isScoreInUnitInterval(score) {
+    return typeof score === "number" && Number.isFinite(score) && score >= 0 && score <= 1;
+}
+export function validateEvidenceAtom(atom) {
+    const reasons = [];
+    if (!isRecord(atom)) {
+        return buildResult(["atom invalid"]);
+    }
+    pushIf(reasons, schemaMismatch(atom.schemaVersion, CONNECTED_CONTEXT_SCHEMA_VERSION), "atom.schemaVersion mismatch");
+    pushIf(reasons, !isNonEmptyTrimmed(atom.stableId), "atom.stableId empty");
+    pushIf(reasons, !isValidScopePath(atom.scopePath, { mustBeRelative: true }), "atom.scopePath invalid");
+    if (atom.lineRange !== undefined) {
+        pushIf(reasons, !isValidLineRange(atom.lineRange), "atom.lineRange invalid");
+    }
+    pushIf(reasons, !isScoreInUnitInterval(atom.score), "atom.score out of range");
+    const provenance = atom.provenance;
+    if (typeof provenance !== "object" || provenance === null) {
+        reasons.push("atom.provenance missing");
+    }
+    else {
+        pushIf(reasons, !EVIDENCE_ATOM_PROVENANCE_KINDS.includes(atom.provenance.kind), "atom.provenance.kind invalid");
+        pushIf(reasons, !isNonEmptyTrimmed(atom.provenance.tool), "atom.provenance.tool empty");
+        pushIf(reasons, !isNonEmptyTrimmed(atom.provenance.queryFingerprint), "atom.provenance.queryFingerprint empty");
+    }
+    pushIf(reasons, !EVIDENCE_ATOM_REDACTION_STATES.includes(atom.redactionState), "atom.redactionState invalid");
+    pushIf(reasons, !isFiniteNonNegativeInteger(atom.emittedAtMs), "atom.emittedAtMs invalid");
+    if (atom.ledgerRef !== undefined) {
+        validateLedgerRef(atom.ledgerRef, reasons, "atom");
+    }
+    return buildResult(reasons);
+}
+export function validateRetrievalQuery(query) {
+    const reasons = [];
+    if (!isRecord(query)) {
+        return buildResult(["query invalid"]);
+    }
+    pushIf(reasons, !RETRIEVAL_QUERY_KINDS.includes(query.kind), "query.kind invalid");
+    pushIf(reasons, !isNonEmptyTrimmed(query.text), "query.text empty");
+    pushIf(reasons, !isFinitePositiveInteger(query.maxResults), "query.maxResults invalid");
+    pushIf(reasons, !isFiniteNonNegativeInteger(query.emittedAtMs), "query.emittedAtMs invalid");
+    return buildResult(reasons);
+}
+// UTF-8 byte length via WHATWG TextEncoder (Web standard; available on globalThis in Node 22).
+// Using this instead of Buffer keeps the contracts package free of Node-only APIs.
+const TEXT_ENCODER = new TextEncoder();
+function utf8ByteLength(value) {
+    return TEXT_ENCODER.encode(value).length;
+}
+function validatePackFileEntry(entry, scope, selectedPaths, reasons) {
+    if (!isRecord(entry)) {
+        reasons.push("pack.files entry invalid");
+        return;
+    }
+    const scopePath = entry.scopePath;
+    if (typeof scopePath === "string" && isValidScopePath(scopePath, { mustBeRelative: true })) {
+        if (selectedPaths.has(scopePath)) {
+            reasons.push("pack.files contains duplicate scopePath");
+        }
+        else if (setHasOverlappingPath(selectedPaths, scopePath)) {
+            reasons.push("pack.files contains overlapping scopePath");
+        }
+        selectedPaths.add(scopePath);
+    }
+    if (!isConnectedFileRole(entry.role)) {
+        reasons.push("pack.files entry has invalid role");
+    }
+    if (!isValidScopePath(scopePath, { mustBeRelative: true })) {
+        reasons.push("pack.files entry has invalid scopePath");
+    }
+    if (!isPathWithinSelectedScope(scope, scopePath)) {
+        reasons.push("pack.files entry falls outside selected scope");
+    }
+    if (!isNonEmptyTrimmed(entry.selectionReason)) {
+        reasons.push("pack.files entry has empty selectionReason");
+    }
+}
+function validatePackExcerptAtom(atom, entryScopePath, scope, reasons) {
+    const atomScopePath = isRecord(atom) ? atom.scopePath : undefined;
+    if (atomScopePath !== entryScopePath) {
+        reasons.push("pack.files excerpt atom.scopePath does not match parent scopePath");
+    }
+    appendPrefixedReasons(validateEvidenceAtom(atom), "pack.files excerpt ", reasons);
+    if (typeof atomScopePath === "string" && !isPathWithinSelectedScope(scope, atomScopePath)) {
+        reasons.push("pack.files excerpt atom.scopePath falls outside selected scope");
+    }
+    if (isRecord(atom) && atom.redactionState === "raw-internal") {
+        reasons.push("pack.files excerpt atom.redactionState raw-internal");
+    }
+}
+function validatePackExcerptContent(excerpt, reasons) {
+    if (typeof excerpt.content !== "string") {
+        reasons.push("pack.files excerpt content invalid");
+    }
+    if (!isFiniteNonNegativeInteger(excerpt.contentBytes)) {
+        reasons.push("pack.files excerpt contentBytes invalid");
+        return 0;
+    }
+    if (typeof excerpt.content === "string" &&
+        excerpt.contentBytes !== utf8ByteLength(excerpt.content)) {
+        reasons.push("pack.files excerpt contentBytes mismatch");
+    }
+    return excerpt.contentBytes;
+}
+function validatePackExcerpt(excerpt, entryScopePath, scope, reasons) {
+    if (!isRecord(excerpt)) {
+        reasons.push("pack.files excerpt invalid");
+        return 0;
+    }
+    validatePackExcerptAtom(excerpt.atom, entryScopePath, scope, reasons);
+    return validatePackExcerptContent(excerpt, reasons);
+}
+function collectPackAtomIds(files) {
+    const atomIds = new Set();
+    if (!Array.isArray(files)) {
+        return atomIds;
+    }
+    for (const entry of files) {
+        if (!isRecord(entry) || !Array.isArray(entry.excerpts)) {
+            continue;
+        }
+        for (const excerpt of entry.excerpts) {
+            if (!isRecord(excerpt) || !isRecord(excerpt.atom)) {
+                continue;
+            }
+            const stableId = excerpt.atom.stableId;
+            if (typeof stableId === "string") {
+                atomIds.add(stableId);
+            }
+        }
+    }
+    return atomIds;
+}
+function validatePackFiles(files, scope, reasons) {
+    const selectedPaths = new Set();
+    let actualExcerptBytes = 0;
+    if (!Array.isArray(files)) {
+        reasons.push("pack.files invalid");
+        return { actualExcerptBytes, selectedPaths };
+    }
+    for (const entry of files) {
+        validatePackFileEntry(entry, scope, selectedPaths, reasons);
+        if (!isRecord(entry)) {
+            continue;
+        }
+        if (!Array.isArray(entry.excerpts)) {
+            reasons.push("pack.files entry excerpts invalid");
+            continue;
+        }
+        const parentScopePath = typeof entry.scopePath === "string" ? entry.scopePath : "";
+        for (const excerpt of entry.excerpts) {
+            actualExcerptBytes += validatePackExcerpt(excerpt, parentScopePath, scope, reasons);
+        }
+    }
+    return { actualExcerptBytes, selectedPaths };
+}
+function validateOmittedPathState(entry, entryIndex, reasons, selectedPaths, omittedPaths) {
+    const scopePath = entry.scopePath;
+    const validScopePath = isValidScopePath(scopePath, { mustBeRelative: true });
+    if (typeof scopePath === "string" && setHasOverlappingPath(selectedPaths, scopePath)) {
+        reasons.push("pack.omitted overlaps selected scopePath");
+    }
+    if (typeof scopePath === "string" && validScopePath) {
+        if (omittedPaths.has(scopePath)) {
+            reasons.push("pack.omitted contains duplicate scopePath");
+        }
+        else if (setHasOverlappingPath(omittedPaths, scopePath)) {
+            reasons.push("pack.omitted contains overlapping scopePath");
+        }
+        omittedPaths.add(scopePath);
+    }
+    if (!validScopePath) {
+        reasons.push(`omitted[${entryIndex.toString()}].scopePath invalid`);
+    }
+}
+function validatePackOmitted(entries, scope, reasons, selectedPaths) {
+    if (!Array.isArray(entries)) {
+        reasons.push("pack.omitted invalid");
+        return;
+    }
+    const omittedPaths = new Set();
+    for (const [i, entry] of entries.entries()) {
+        if (!isRecord(entry)) {
+            reasons.push("pack.omitted entry invalid");
+            continue;
+        }
+        validateOmittedPathState(entry, i, reasons, selectedPaths, omittedPaths);
+        if (!isCandidateOmissionReason(entry.reason)) {
+            reasons.push("pack.omitted has invalid reason");
+        }
+        if (!isPathWithinSelectedScope(scope, entry.scopePath)) {
+            reasons.push("pack.omitted entry falls outside selected scope");
+        }
+        if (!isFiniteNonNegativeInteger(entry.omittedAtMs)) {
+            reasons.push("pack.omitted has invalid omittedAtMs");
+        }
+    }
+}
+function validateImpactedAtomIds(impactedAtomIds, entryIndex, validAtomIds, reasons) {
+    if (!Array.isArray(impactedAtomIds)) {
+        reasons.push(`uncertainty[${entryIndex.toString()}].impactedAtomIds invalid`);
+        return;
+    }
+    const impactedIds = new Set();
+    for (const atomId of impactedAtomIds) {
+        if (!isNonEmptyTrimmed(atomId)) {
+            reasons.push(`uncertainty[${entryIndex.toString()}].impactedAtomIds invalid`);
+            continue;
+        }
+        if (impactedIds.has(atomId)) {
+            reasons.push(`uncertainty[${entryIndex.toString()}].impactedAtomIds duplicate`);
+            continue;
+        }
+        if (!validAtomIds.has(atomId)) {
+            reasons.push(`uncertainty[${entryIndex.toString()}].impactedAtomIds unknown`);
+            continue;
+        }
+        impactedIds.add(atomId);
+    }
+}
+function validateUncertaintyEntry(entry, entryIndex, validAtomIds, reasons) {
+    if (!isUncertaintyMarkerKind(entry.kind)) {
+        reasons.push("pack.uncertainty has invalid kind");
+    }
+    if (!isNonEmptyTrimmed(entry.claim)) {
+        reasons.push(`uncertainty[${entryIndex.toString()}].claim empty`);
+    }
+    if (!isFiniteNonNegativeInteger(entry.emittedAtMs)) {
+        reasons.push("pack.uncertainty has invalid emittedAtMs");
+    }
+    validateImpactedAtomIds(entry.impactedAtomIds, entryIndex, validAtomIds, reasons);
+}
+function validatePackUncertainty(entries, validAtomIds, reasons) {
+    if (!Array.isArray(entries)) {
+        reasons.push("pack.uncertainty invalid");
+        return;
+    }
+    for (const [i, entry] of entries.entries()) {
+        if (!isRecord(entry)) {
+            reasons.push("pack.uncertainty entry invalid");
+            continue;
+        }
+        validateUncertaintyEntry(entry, i, validAtomIds, reasons);
+    }
+}
+function checkBudgetDimension(used, cap, dimension, reasons) {
+    if (!isFiniteNonNegativeInteger(cap)) {
+        reasons.push(`budget.${dimension}Max not a finite non-negative integer`);
+        return;
+    }
+    if (!Number.isFinite(used) || used < 0) {
+        reasons.push(`pack.usage.${dimension} invalid`);
+        return;
+    }
+    if (used > cap) {
+        reasons.push(`pack.usage.${dimension} exceeds budget`);
+    }
+}
+function validatePackBudget(pack, actualExcerptBytes, reasons) {
+    if (!isRecord(pack.usage)) {
+        reasons.push("pack.usage invalid");
+        return;
+    }
+    if (!isRecord(pack.budget)) {
+        reasons.push("pack.budget invalid");
+        return;
+    }
+    checkBudgetDimension(pack.usage.searchCalls, pack.budget.searchCallsMax, "searchCalls", reasons);
+    checkBudgetDimension(pack.usage.filesRead, pack.budget.filesReadMax, "filesRead", reasons);
+    checkBudgetDimension(pack.usage.excerptBytes, pack.budget.excerptBytesMax, "excerptBytes", reasons);
+    checkBudgetDimension(pack.usage.modelInputTokens, pack.budget.modelInputTokensMax, "modelInputTokens", reasons);
+    checkBudgetDimension(pack.usage.modelOutputTokens, pack.budget.modelOutputTokensMax, "modelOutputTokens", reasons);
+    checkBudgetDimension(pack.usage.elapsedMs, pack.budget.elapsedMsMax, "elapsedMs", reasons);
+    checkBudgetDimension(pack.usage.rerankCalls, pack.budget.rerankCallsMax, "rerankCalls", reasons);
+    if (actualExcerptBytes > pack.usage.excerptBytes) {
+        reasons.push("pack.files excerpts exceed pack.usage.excerptBytes");
+    }
+    if (actualExcerptBytes > pack.budget.excerptBytesMax) {
+        reasons.push("pack.files excerpts exceed budget.excerptBytesMax");
+    }
+}
+function validatePackScopeAndQuery(pack, reasons) {
+    appendPrefixedReasons(validateSelectedScope(pack.scope), "pack.", reasons);
+    appendPrefixedReasons(validateRetrievalQuery(pack.query), "pack.", reasons);
+}
+function validatePackFileCollection(pack, reasons) {
+    if (isRuntimeSelectedScope(pack.scope)) {
+        return validatePackFiles(pack.files, pack.scope, reasons);
+    }
+    if (!Array.isArray(pack.files)) {
+        reasons.push("pack.files invalid");
+    }
+    return { actualExcerptBytes: 0, selectedPaths: new Set() };
+}
+function validatePackOmittedCollection(pack, fileSummary, reasons) {
+    if (isRuntimeSelectedScope(pack.scope)) {
+        validatePackOmitted(pack.omitted, pack.scope, reasons, fileSummary.selectedPaths);
+        return;
+    }
+    if (!Array.isArray(pack.omitted)) {
+        reasons.push("pack.omitted invalid");
+    }
+}
+export function validateConnectedContextPack(pack) {
+    const reasons = [];
+    if (!isRecord(pack)) {
+        return buildResult(["pack invalid"]);
+    }
+    pushIf(reasons, schemaMismatch(pack.schemaVersion, CONNECTED_CONTEXT_SCHEMA_VERSION), "pack.schemaVersion mismatch");
+    pushIf(reasons, !isNonEmptyTrimmed(pack.stableId), "pack.stableId empty");
+    validatePackScopeAndQuery(pack, reasons);
+    const fileSummary = validatePackFileCollection(pack, reasons);
+    validatePackBudget(pack, fileSummary.actualExcerptBytes, reasons);
+    validatePackOmittedCollection(pack, fileSummary, reasons);
+    validatePackUncertainty(pack.uncertainty, collectPackAtomIds(pack.files), reasons);
+    pushIf(reasons, !isFiniteNonNegativeInteger(pack.emittedAtMs), "pack.emittedAtMs invalid");
+    if (pack.ledgerRef !== undefined) {
+        validateLedgerRef(pack.ledgerRef, reasons, "pack");
+    }
+    return buildResult(reasons);
+}

package/dist/conversation-budget.d.ts

@@ -0,0 +1,37 @@
+export interface ConversationBudgetMessage {
+    readonly role: string;
+    readonly content: string;
+}
+export interface ConversationBudgetDocumentContext {
+    readonly extractedBytes: number;
+}
+export interface ConversationBudgetInputs {
+    readonly modelContextWindow: number;
+    readonly modelMaxOutputTokens: number;
+    readonly userDraftText: string;
+    readonly conversationHistory: readonly ConversationBudgetMessage[];
+    readonly documentContext?: readonly ConversationBudgetDocumentContext[] | undefined;
+    readonly repoContextPackBytes?: number | undefined;
+    readonly knowledgeCapsuleBytes?: number | undefined;
+    readonly memoryContextBytes?: number | undefined;
+}
+export type ConversationBudgetPressure = "low" | "moderate" | "high" | "exceeded";
+export interface ConversationBudgetBreakdown {
+    readonly draftBytes: number;
+    readonly historyBytes: number;
+    readonly documentBytes: number;
+    readonly repoContextBytes: number;
+    readonly knowledgeBytes: number;
+    readonly memoryBytes: number;
+}
+export interface ConversationBudgetEstimate {
+    readonly approximateBytes: number;
+    readonly approximateTokens: number;
+    readonly contextWindowTokens: number;
+    readonly reservedOutputTokens: number;
+    readonly availableInputTokens: number;
+    readonly pressure: ConversationBudgetPressure;
+    readonly breakdown: ConversationBudgetBreakdown;
+}
+export declare function estimateConversationBudget(input: ConversationBudgetInputs): ConversationBudgetEstimate;
+//# sourceMappingURL=conversation-budget.d.ts.map

package/dist/conversation-budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversation-budget.d.ts","sourceRoot":"","sources":["../src/conversation-budget.ts"],"names":[],"mappings":"AAYA,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,iCAAiC;IAChD,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,mBAAmB,EAAE,SAAS,yBAAyB,EAAE,CAAC;IACnE,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,iCAAiC,EAAE,GAAG,SAAS,CAAC;IACpF,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnD,QAAQ,CAAC,qBAAqB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpD,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAClD;AAED,MAAM,MAAM,0BAA0B,GAAG,KAAK,GAAG,UAAU,GAAG,MAAM,GAAG,UAAU,CAAC;AAElF,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;IACrC,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,QAAQ,EAAE,0BAA0B,CAAC;IAC9C,QAAQ,CAAC,SAAS,EAAE,2BAA2B,CAAC;CACjD;AA6DD,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,wBAAwB,GAC9B,0BAA0B,CAmC5B"}