clinkx 0.3.0 → 1.1.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-finalizer-effective.d.ts

@@ -0,0 +1,33 @@
+import { type ContextBuilderIntentProfile } from "./schema.js";
+/**
+ * Effective finalizer enablement, matching the workflow preflight rule:
+ * `finalizer.enabled` if defined, else the intent profile's `finalizer_enabled`
+ * default, else true when no profile is set.
+ *
+ * Does not consider outer `delegate.enabled` — callers short-circuit that.
+ */
+export declare function resolveContextBuilderFinalizerEffectiveEnabled(finalizerEnabled: boolean | undefined, profile: ContextBuilderIntentProfile | undefined): boolean;
+/**
+ * Admission-time E5: a model/effort override, or an explicitly requested
+ * min_score, on an effectively disabled finalizer is -32602, before run state,
+ * artifacts, or spawn.
+ */
+export declare function assertNoDisabledFinalizerInvocationOverrides(finalizerEnabled: boolean | undefined, profile: ContextBuilderIntentProfile | undefined, model: string | undefined, effort: string | undefined, minScore?: number): void;
+/**
+ * E5 rejection text. Byte-identical to the workflow admission twin in
+ * `clinkx-workflows/src/delegate-finalizer-policy.ts`.
+ *
+ * Requested knobs render in fixed model → effort → min_score order: the first
+ * leads and the rest are parenthesized, so model/effort-only text is unchanged
+ * from before `min_score` participated.
+ */
+export declare function formatDisabledFinalizerOverrideRejectionMessage(model: string | undefined, effort: string | undefined, explicitEnabledFalse: boolean, profile: ContextBuilderIntentProfile | undefined, minScore?: number): string;
+/**
+ * Whether the raw (pre-parse) context_builder arguments carry an explicit
+ * `delegate.finalizer.min_score`. Raw presence is required because both
+ * packages default `min_score` at parse time, erasing caller intent. Any
+ * unexpected shape is not explicit; schema parsing owns reporting it. The
+ * engine twin is `delegateFinalizerMinScoreExplicit` in
+ * `clinkx-workflows/src/delegate-validate.ts` (it reads a raw `cb_delegate`).
+ */
+export declare function finalizerMinScoreExplicit(rawArgs: unknown): boolean;

package/dist/context-builder/delegate-finalizer-effective.js

@@ -0,0 +1,82 @@
+import { InvalidParamsError } from "../errors.js";
+import { CONTEXT_BUILDER_INTENT_PROFILE_DEFAULTS, } from "./schema.js";
+/**
+ * Effective finalizer enablement, matching the workflow preflight rule:
+ * `finalizer.enabled` if defined, else the intent profile's `finalizer_enabled`
+ * default, else true when no profile is set.
+ *
+ * Does not consider outer `delegate.enabled` — callers short-circuit that.
+ */
+export function resolveContextBuilderFinalizerEffectiveEnabled(finalizerEnabled, profile) {
+    if (finalizerEnabled !== undefined) {
+        return finalizerEnabled;
+    }
+    if (profile === undefined) {
+        return true;
+    }
+    return CONTEXT_BUILDER_INTENT_PROFILE_DEFAULTS[profile].finalizer_enabled;
+}
+/**
+ * Admission-time E5: a model/effort override, or an explicitly requested
+ * min_score, on an effectively disabled finalizer is -32602, before run state,
+ * artifacts, or spawn.
+ */
+export function assertNoDisabledFinalizerInvocationOverrides(finalizerEnabled, profile, model, effort, minScore) {
+    // `minScore` carries an explicitly requested finalizer.min_score only
+    // (raw-input presence, see `finalizerMinScoreExplicit`); a parse-time
+    // default must never be passed here.
+    if (model === undefined && effort === undefined && minScore === undefined) {
+        return;
+    }
+    if (resolveContextBuilderFinalizerEffectiveEnabled(finalizerEnabled, profile)) {
+        return;
+    }
+    throw new InvalidParamsError(formatDisabledFinalizerOverrideRejectionMessage(model, effort, finalizerEnabled === false, profile, minScore));
+}
+/**
+ * E5 rejection text. Byte-identical to the workflow admission twin in
+ * `clinkx-workflows/src/delegate-finalizer-policy.ts`.
+ *
+ * Requested knobs render in fixed model → effort → min_score order: the first
+ * leads and the rest are parenthesized, so model/effort-only text is unchanged
+ * from before `min_score` participated.
+ */
+export function formatDisabledFinalizerOverrideRejectionMessage(model, effort, explicitEnabledFalse, profile, minScore) {
+    const reason = explicitEnabledFalse
+        ? "(finalizer.enabled:false)"
+        : `(finalizer.enabled omitted; profile "${profile}" default is finalizer_enabled:false)`;
+    const knobs = [];
+    if (model !== undefined)
+        knobs.push(`model "${model}"`);
+    if (effort !== undefined)
+        knobs.push(`effort "${effort}"`);
+    if (minScore !== undefined)
+        knobs.push(`min_score ${minScore}`);
+    const [lead = `effort "${effort}"`, ...rest] = knobs;
+    const named = rest.length === 0
+        ? `finalizer ${lead}`
+        : `finalizer ${lead} (${rest.join(", ")})`;
+    return `${named} was requested but the finalizer is effectively disabled ${reason}; set finalizer.enabled:true or remove the override`;
+}
+/**
+ * Whether the raw (pre-parse) context_builder arguments carry an explicit
+ * `delegate.finalizer.min_score`. Raw presence is required because both
+ * packages default `min_score` at parse time, erasing caller intent. Any
+ * unexpected shape is not explicit; schema parsing owns reporting it. The
+ * engine twin is `delegateFinalizerMinScoreExplicit` in
+ * `clinkx-workflows/src/delegate-validate.ts` (it reads a raw `cb_delegate`).
+ */
+export function finalizerMinScoreExplicit(rawArgs) {
+    const delegate = ownPlainProperty(rawArgs, "delegate");
+    const finalizer = ownPlainProperty(delegate, "finalizer");
+    return ownPlainProperty(finalizer, "min_score") !== undefined;
+}
+function ownPlainProperty(value, key) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        return undefined;
+    }
+    return Object.hasOwn(value, key)
+        ? value[key]
+        : undefined;
+}
+//# sourceMappingURL=delegate-finalizer-effective.js.map

package/dist/context-builder/delegate-finalizer-effective.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"delegate-finalizer-effective.js","sourceRoot":"","sources":["../../src/context-builder/delegate-finalizer-effective.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,8 @@ export type ContextBuilderDelegatePacketMetrics = {
     evidence_byte_cap_hit: boolean;
     packet_estimated_tokens: number;
     packet_token_cap_hit: boolean;
+    packet_json_byte_cap_hit: boolean;
+    compaction: ContextBuilderDelegatePacketCompactionMetrics;
 };
 export type ContextBuilderDelegatePacket = {
     version: "context-builder.delegate-packet.v1";
@@ -145,6 +171,7 @@ export type ContextBuilderDelegatePacket = {
         raw_full_content_included: false;
     };
     budget: ContextBuilderPublicBudget;
+    coverage_policy: ContextBuilderDelegatePacketCoveragePolicy;
     candidates: ContextBuilderDelegatePacketCandidate[];
     deterministic_selection: {
         metrics: ContextBuilderSelectionMetrics;
@@ -152,6 +179,7 @@ export type ContextBuilderDelegatePacket = {
     };
     omissions: ContextBuilderOmission[];
     metrics: ContextBuilderDelegatePacketMetrics;
+    evidence_warning?: ContextBuilderDelegatePacketEvidenceWarning;
     curator_proposal?: ContextBuilderCuratorProposal;
     local_selection_summary?: {
         selected: ContextBuilderDelegatePacketSelection[];
@@ -164,13 +192,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 & {
@@ -180,3 +218,20 @@ export declare function buildContextBuilderCuratorPacket(input: ContextBuilderDe
 export declare function buildContextBuilderFinalizerPacket(input: ContextBuilderFinalizerPacketInput): ContextBuilderDelegatePacket;
 export declare function contextBuilderCandidateId(rootIndex: number, path: string): string;
 export declare function contextBuilderRangeId(candidateId: string, startLine: number, endLine: number): string;
+export type ContextBuilderDelegatePacketObligationTruncation = {
+    targets_total: number;
+    targets_included: number;
+    ranges_total: number;
+    ranges_included: number;
+    regression_links_total: number;
+    regression_links_included: number;
+};
+/**
+ * Observability-only count of what normalizeCoveragePolicy sliced off the
+ * review obligations it serializes into the packet. Terminal coverage
+ * evaluation (review-coverage.ts) always uses the FULL discovery obligation
+ * set, so a delegate can satisfy every packet obligation and the run can still
+ * report degraded coverage. Returns undefined when nothing was sliced.
+ * "ranges" counts target ranges plus regression-link ranges.
+ */
+export declare function countDelegatePacketObligationTruncation(fullObligations: ContextReviewObligationModel | undefined, packetPolicy: ContextBuilderDelegatePacketCoveragePolicy): ContextBuilderDelegatePacketObligationTruncation | undefined;