@oscharko-dev/keiko-contracts 0.2.0

package/dist/connected-context.d.ts

@@ -0,0 +1,174 @@
+export declare const CONNECTED_CONTEXT_SCHEMA_VERSION: "1";
+export type SelectedScopeKind = "workspace-root" | "directory" | "files";
+export declare const SELECTED_SCOPE_KINDS: readonly SelectedScopeKind[];
+export interface SelectedScope {
+    readonly schemaVersion: typeof CONNECTED_CONTEXT_SCHEMA_VERSION;
+    readonly scopeId: string;
+    readonly workspaceRoot: string;
+    readonly kind: SelectedScopeKind;
+    readonly relativePaths: readonly string[];
+    readonly conversationId: string | undefined;
+    readonly connectedAtMs: number;
+    readonly explicitConnection?: boolean;
+}
+export interface EvidenceLedgerRef {
+    readonly evidenceSchemaVersion: "1";
+    readonly runId: string;
+    readonly atomId: string | undefined;
+}
+export type EvidenceAtomProvenanceKind = "lexical-search" | "file-listing" | "excerpt-read" | "structural" | "git-history" | "model-rerank" | "document-extract";
+export declare const EVIDENCE_ATOM_PROVENANCE_KINDS: readonly EvidenceAtomProvenanceKind[];
+export interface EvidenceAtomProvenance {
+    readonly kind: EvidenceAtomProvenanceKind;
+    readonly tool: string;
+    readonly queryFingerprint: string;
+}
+export type EvidenceAtomRedactionState = "redacted" | "raw-internal";
+export declare const EVIDENCE_ATOM_REDACTION_STATES: readonly EvidenceAtomRedactionState[];
+export interface LineRange {
+    readonly startLine: number;
+    readonly endLine: number;
+}
+export interface EvidenceAtom {
+    readonly schemaVersion: typeof CONNECTED_CONTEXT_SCHEMA_VERSION;
+    readonly stableId: string;
+    readonly scopePath: string;
+    readonly lineRange: LineRange | undefined;
+    readonly score: number;
+    readonly provenance: EvidenceAtomProvenance;
+    readonly redactionState: EvidenceAtomRedactionState;
+    readonly emittedAtMs: number;
+    readonly ledgerRef: EvidenceLedgerRef | undefined;
+}
+export interface ExplorationBudget {
+    readonly searchCallsMax: number;
+    readonly filesReadMax: number;
+    readonly excerptBytesMax: number;
+    readonly modelInputTokensMax: number;
+    readonly modelOutputTokensMax: number;
+    readonly elapsedMsMax: number;
+    readonly rerankCallsMax: number;
+}
+export declare const DEFAULT_EXPLORATION_BUDGET: ExplorationBudget;
+export interface ExplorationUsage {
+    readonly searchCalls: number;
+    readonly filesRead: number;
+    readonly excerptBytes: number;
+    readonly modelInputTokens: number;
+    readonly modelOutputTokens: number;
+    readonly elapsedMs: number;
+    readonly rerankCalls: number;
+}
+export type RetrievalQueryKind = "natural-language" | "exact-symbol" | "file-pattern" | "regex";
+export declare const RETRIEVAL_QUERY_KINDS: readonly RetrievalQueryKind[];
+export interface RetrievalQuery {
+    readonly kind: RetrievalQueryKind;
+    readonly text: string;
+    readonly caseSensitive: boolean;
+    readonly maxResults: number;
+    readonly emittedAtMs: number;
+}
+export type CandidateOmissionReason = "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 declare const CANDIDATE_OMISSION_REASONS: readonly CandidateOmissionReason[];
+export interface CandidateSignal {
+    readonly name: string;
+    readonly value: number;
+}
+export interface CandidateFile {
+    readonly scopePath: string;
+    readonly score: number;
+    readonly signals: readonly CandidateSignal[];
+    readonly omitted: CandidateOmissionReason | undefined;
+}
+export interface ContextExcerpt {
+    readonly atom: EvidenceAtom;
+    readonly content: string;
+    readonly contentBytes: number;
+}
+export type ConnectedFileRole = "read-only" | "editable";
+export declare const CONNECTED_FILE_ROLES: readonly ConnectedFileRole[];
+export interface ConnectedFileEntry {
+    readonly scopePath: string;
+    readonly role: ConnectedFileRole;
+    readonly selectionReason: string;
+    readonly excerpts: readonly ContextExcerpt[];
+}
+export type UncertaintyMarkerKind = "no-evidence" | "stale-evidence" | "scope-incomplete" | "budget-clipped" | "tool-unavailable" | "low-confidence";
+export declare const UNCERTAINTY_MARKER_KINDS: readonly UncertaintyMarkerKind[];
+export interface UncertaintyMarker {
+    readonly kind: UncertaintyMarkerKind;
+    readonly claim: string;
+    readonly impactedAtomIds: readonly string[];
+    readonly emittedAtMs: number;
+}
+export interface OmittedContextEntry {
+    readonly scopePath: string;
+    readonly reason: CandidateOmissionReason;
+    readonly omittedAtMs: number;
+}
+export interface ConnectedContextPack {
+    readonly schemaVersion: typeof CONNECTED_CONTEXT_SCHEMA_VERSION;
+    readonly stableId: string;
+    readonly scope: SelectedScope;
+    readonly query: RetrievalQuery;
+    readonly budget: ExplorationBudget;
+    readonly usage: ExplorationUsage;
+    readonly files: readonly ConnectedFileEntry[];
+    readonly omitted: readonly OmittedContextEntry[];
+    readonly uncertainty: readonly UncertaintyMarker[];
+    readonly emittedAtMs: number;
+    readonly ledgerRef: EvidenceLedgerRef | undefined;
+}
+export interface ConnectedContextPackSummary {
+    readonly schemaVersion: typeof CONNECTED_CONTEXT_SCHEMA_VERSION;
+    readonly stableId: string;
+    readonly scopeId: string;
+    readonly scopeKind: SelectedScopeKind;
+    readonly conversationId: string | undefined;
+    readonly queryKind: RetrievalQueryKind;
+    readonly fileCount: number;
+    readonly readOnlyFileCount: number;
+    readonly editableFileCount: number;
+    readonly omittedCount: number;
+    readonly uncertaintyCount: number;
+    readonly usage: ExplorationUsage;
+    readonly budget: ExplorationBudget;
+    readonly emittedAtMs: number;
+}
+export interface ConversationAttachmentContextLink {
+    readonly attachmentId: string;
+    readonly contextPackStableId: string;
+    readonly scopeId: string;
+    readonly linkedAtMs: number;
+}
+export interface EvidenceAtomStableIdInput {
+    readonly scopeId: string;
+    readonly scopePath: string;
+    readonly lineRange: LineRange | undefined;
+    readonly provenanceKind: EvidenceAtomProvenanceKind;
+    readonly provenanceTool: string;
+    readonly queryFingerprint: string;
+}
+export interface ConnectedContextPackStableIdInput {
+    readonly scopeId: string;
+    readonly queryKind: RetrievalQueryKind;
+    readonly queryText: string;
+    readonly atomStableIds: readonly string[];
+}
+export type ValidationResult = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly reasons: readonly string[];
+};
+export interface IsValidScopePathOptions {
+    readonly mustBeRelative: boolean;
+}
+export declare function isValidScopePath(path: unknown, options: IsValidScopePathOptions): boolean;
+export declare function isValidLineRange(range: LineRange): boolean;
+export declare function isWithinBudget(usage: ExplorationUsage, budget: ExplorationBudget): boolean;
+export declare function validateSelectedScope(scope: SelectedScope): ValidationResult;
+export declare function validateEvidenceAtom(atom: EvidenceAtom): ValidationResult;
+export declare function validateRetrievalQuery(query: RetrievalQuery): ValidationResult;
+export declare function validateConnectedContextPack(pack: ConnectedContextPack): ValidationResult;
+//# sourceMappingURL=connected-context.d.ts.map

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

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