clinkx 0.3.0 → 1.0.0

package/dist/context-builder/context-run-catalog.js

@@ -0,0 +1,99 @@
+import { mkdir, open, readdir, rm, } from "node:fs/promises";
+import { join } from "node:path";
+import { isContextBuilderOperationId } from "./lifecycle-contract.js";
+export const CONTEXT_RUN_CATALOG_DIRECTORY = ".catalog";
+export const CONTEXT_RUN_CATALOG_LEGACY_CUTOFF_FILENAME = ".legacy-before";
+export const DEFAULT_CONTEXT_RUN_CATALOG_MAX_MARKERS = 1_000;
+const ARTIFACT_ID_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
+const MARKER_NAME_PATTERN = /^(\d{13})-([oa])-(.+)$/;
+export async function recordContextRunCatalogMarker(input) {
+    validateMarkerIdentity(input.kind, input.id);
+    const createdAtMs = Date.parse(input.createdAt);
+    if (!Number.isSafeInteger(createdAtMs) || createdAtMs < 0) {
+        throw new TypeError("context run catalog createdAt must be a valid timestamp");
+    }
+    const contextRunsDir = join(input.runsDir, ".context-runs");
+    const catalogDir = join(contextRunsDir, CONTEXT_RUN_CATALOG_DIRECTORY);
+    await mkdir(catalogDir, { recursive: true, mode: 0o700 });
+    await writeLegacyCutoffOnce(contextRunsDir, createdAtMs);
+    const markerPath = join(catalogDir, `${String(createdAtMs).padStart(13, "0")}-${input.kind === "operation" ? "o" : "a"}-${input.id}`);
+    try {
+        const handle = await open(markerPath, "wx", 0o600);
+        try {
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    catch (error) {
+        if (!isAlreadyExistsError(error))
+            throw error;
+    }
+    await pruneContextRunCatalogMarkers(catalogDir, input.maxMarkers ?? DEFAULT_CONTEXT_RUN_CATALOG_MAX_MARKERS);
+    return markerPath;
+}
+async function writeLegacyCutoffOnce(contextRunsDir, createdAtMs) {
+    try {
+        const handle = await open(join(contextRunsDir, CONTEXT_RUN_CATALOG_LEGACY_CUTOFF_FILENAME), "wx", 0o600);
+        try {
+            await handle.writeFile(`${String(createdAtMs)}\n`, "utf8");
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    catch (error) {
+        if (!isAlreadyExistsError(error))
+            throw error;
+    }
+}
+export function parseContextRunCatalogMarkerName(name) {
+    const match = MARKER_NAME_PATTERN.exec(name);
+    if (match === null)
+        return undefined;
+    const createdAtMs = Number(match[1]);
+    const kind = match[2] === "o" ? "operation" : "artifact";
+    const id = match[3];
+    try {
+        validateMarkerIdentity(kind, id);
+    }
+    catch {
+        return undefined;
+    }
+    const createdAt = new Date(createdAtMs).toISOString();
+    return { createdAt, kind, id };
+}
+function validateMarkerIdentity(kind, id) {
+    if (kind === "operation") {
+        if (!isContextBuilderOperationId(id)) {
+            throw new TypeError("context run catalog operation ID is invalid");
+        }
+        return;
+    }
+    if (!ARTIFACT_ID_PATTERN.test(id) ||
+        id.startsWith("wfctx") ||
+        id.startsWith("wfpre")) {
+        throw new TypeError("context run catalog artifact ID is invalid");
+    }
+}
+async function pruneContextRunCatalogMarkers(catalogDir, maxMarkers) {
+    if (!Number.isSafeInteger(maxMarkers) || maxMarkers < 1 ||
+        maxMarkers > DEFAULT_CONTEXT_RUN_CATALOG_MAX_MARKERS) {
+        throw new TypeError(`context run catalog maxMarkers must be an integer from 1 through ${String(DEFAULT_CONTEXT_RUN_CATALOG_MAX_MARKERS)}`);
+    }
+    const markerNames = (await readdir(catalogDir, { withFileTypes: true }))
+        .filter((entry) => entry.isFile() && parseContextRunCatalogMarkerName(entry.name) !== undefined)
+        .map((entry) => entry.name)
+        .sort();
+    const excess = markerNames.length - maxMarkers;
+    if (excess <= 0)
+        return;
+    await Promise.all(markerNames.slice(0, excess).map((name) => rm(join(catalogDir, name), { force: true })));
+}
+function isAlreadyExistsError(error) {
+    return typeof error === "object" && error !== null &&
+        "code" in error && error.code === "EEXIST";
+}
+//# sourceMappingURL=context-run-catalog.js.map

package/dist/context-builder/context-run-catalog.js.map

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

package/dist/context-builder/delegate-packet.d.ts

@@ -2,6 +2,7 @@ import { type ContextBuilderOmission } from "./diagnostics.js";
 import { type ContextBuilderContentCandidate, type ContextBuilderDiscoveryMetrics, type ContextBuilderSearchRecord, type ContextBuilderSliceRecord, type ContextBuilderTreeFile } from "./discovery.js";
 import { type ContextBuilderResolvedFocusPath } from "./paths.js";
 import { type ContextBuilderPublicBudget } from "./schema.js";
+import { ContextCoveragePolicy, ContextEvidenceClass, type ContextReviewObligationModel } from "./review-coverage.js";
 import { type ContextBuilderSelectionMetrics, type ContextBuilderSelectionResult } from "./selection.js";
 export type ContextBuilderDelegatePacketPurpose = "curator" | "finalizer";
 export type ContextBuilderDelegatePacketCaps = {
@@ -65,6 +66,7 @@ export type ContextBuilderDelegatePacketCandidate = {
     size_bytes: number;
     estimated_tokens: number;
     discovery_reason: "focus_path" | "search_hit" | "eligible_candidate";
+    evidence_classes: ContextEvidenceClass[];
     focus_requested?: boolean;
     required_focus_ranges?: ContextBuilderDelegatePacketSelectedRange[];
     deterministic_selected: boolean;
@@ -74,6 +76,11 @@ export type ContextBuilderDelegatePacketCandidate = {
     ranges: ContextBuilderDelegatePacketRange[];
     search_hits: ContextBuilderDelegatePacketSearchHit[];
 };
+export type ContextBuilderDelegatePacketCoveragePolicy = {
+    policy_id: "review_deep_v1" | null;
+    required_when_available: ContextEvidenceClass[];
+    obligations?: ContextReviewObligationModel;
+};
 export type ContextBuilderDelegatePacketRange = {
     id: string;
     start_line: number;
@@ -119,6 +126,23 @@ export type ContextBuilderCuratorProposal = {
     warnings: string[];
     open_questions: string[];
 };
+export type ContextBuilderDelegatePacketCompactionMetrics = {
+    candidates_before_compaction: number;
+    candidates_after_compaction: number;
+    candidates_evicted_by_compaction: number;
+    evidence_bytes_before_compaction: number;
+    evidence_bytes_after_compaction: number;
+    search_records_before_compaction: number;
+    search_records_after_compaction: number;
+    slice_records_before_compaction: number;
+    slice_records_after_compaction: number;
+    all_non_focus_candidates_evidence_free: boolean;
+};
+export type ContextBuilderDelegatePacketEvidenceWarning = {
+    code: "all_non_focus_candidates_evidence_free";
+    message: string;
+    non_focus_candidate_count: number;
+};
 export type ContextBuilderDelegatePacketMetrics = {
     discovery: ContextBuilderDiscoveryMetrics;
     selection: ContextBuilderSelectionMetrics;
@@ -132,6 +156,7 @@ export type ContextBuilderDelegatePacketMetrics = {
     evidence_byte_cap_hit: boolean;
     packet_estimated_tokens: number;
     packet_token_cap_hit: boolean;
+    compaction: ContextBuilderDelegatePacketCompactionMetrics;
 };
 export type ContextBuilderDelegatePacket = {
     version: "context-builder.delegate-packet.v1";
@@ -145,6 +170,7 @@ export type ContextBuilderDelegatePacket = {
         raw_full_content_included: false;
     };
     budget: ContextBuilderPublicBudget;
+    coverage_policy: ContextBuilderDelegatePacketCoveragePolicy;
     candidates: ContextBuilderDelegatePacketCandidate[];
     deterministic_selection: {
         metrics: ContextBuilderSelectionMetrics;
@@ -152,6 +178,7 @@ export type ContextBuilderDelegatePacket = {
     };
     omissions: ContextBuilderOmission[];
     metrics: ContextBuilderDelegatePacketMetrics;
+    evidence_warning?: ContextBuilderDelegatePacketEvidenceWarning;
     curator_proposal?: ContextBuilderCuratorProposal;
     local_selection_summary?: {
         selected: ContextBuilderDelegatePacketSelection[];
@@ -164,13 +191,23 @@ export type ContextBuilderDelegatePacketDiscoveryInput = {
     slices: readonly ContextBuilderSliceRecord[];
     omissions: readonly ContextBuilderOmission[];
     metrics: ContextBuilderDiscoveryMetrics;
+    review_obligations?: ContextReviewObligationModel;
 };
 export type ContextBuilderDelegatePacketInput = {
     task: string;
+    allowSecrets?: boolean;
     discovery: ContextBuilderDelegatePacketDiscoveryInput;
     selection: ContextBuilderSelectionResult;
     budget: ContextBuilderPublicBudget;
     focus_paths?: readonly ContextBuilderResolvedFocusPath[];
+    /**
+     * Caller-supplied `search_terms` from the public request. Optional and
+     * additive: when absent, exact-caller-hit compaction protection is simply
+     * not applied (legacy behavior). Used only to classify candidates whose
+     * search records match a caller term verbatim.
+     */
+    caller_search_terms?: readonly string[];
+    coveragePolicy?: ContextCoveragePolicy;
     caps?: Partial<ContextBuilderDelegatePacketCaps>;
 };
 export type ContextBuilderFinalizerPacketInput = ContextBuilderDelegatePacketInput & {