@bastani/atomic 0.9.11-alpha.5 → 0.9.11-alpha.7

package/dist/core/compaction/index.d.ts

@@ -6,6 +6,9 @@ export * from "./compaction.ts";
 export * from "./compaction-types.js";
 export * from "./compaction-parameters.js";
 export * from "./compaction-boundary.js";
+export * from "./planner-outcome.js";
+export * from "./fallback-planner.js";
+export * from "./region-trimming.js";
 export * from "./range-planner.js";
 export * from "./range-planner-diagnostics.js";
 export * from "./compaction-runner.js";

package/dist/core/compaction/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/compaction/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,2BAA2B,CAAC;AAC1C,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,0BAA0B,CAAC;AACzC,cAAc,oBAAoB,CAAC;AACnC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,wBAAwB,CAAC;AACvC,cAAc,qBAAqB,CAAC;AACpC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/compaction/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,2BAA2B,CAAC;AAC1C,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,0BAA0B,CAAC;AACzC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC;AACnC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,wBAAwB,CAAC;AACvC,cAAc,qBAAqB,CAAC;AACpC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,YAAY,CAAC"}

package/dist/core/compaction/index.js

@@ -6,6 +6,9 @@ export * from "./compaction.js";
 export * from "./compaction-types.js";
 export * from "./compaction-parameters.js";
 export * from "./compaction-boundary.js";
+export * from "./planner-outcome.js";
+export * from "./fallback-planner.js";
+export * from "./region-trimming.js";
 export * from "./range-planner.js";
 export * from "./range-planner-diagnostics.js";
 export * from "./compaction-runner.js";

package/dist/core/compaction/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/compaction/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,2BAA2B,CAAC;AAC1C,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,0BAA0B,CAAC;AACzC,cAAc,oBAAoB,CAAC;AACnC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,wBAAwB,CAAC;AACvC,cAAc,qBAAqB,CAAC;AACpC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,YAAY,CAAC","sourcesContent":["/**\n * Compaction support utilities.\n */\n\nexport * from \"./branch-summarization.ts\";\nexport * from \"./compaction.ts\";\nexport * from \"./compaction-types.js\";\nexport * from \"./compaction-parameters.js\";\nexport * from \"./compaction-boundary.js\";\nexport * from \"./range-planner.js\";\nexport * from \"./range-planner-diagnostics.js\";\nexport * from \"./compaction-runner.js\";\nexport * from \"./deleted-ranges.js\";\nexport * from \"./transcript-serialization.js\";\nexport * from \"./utils.ts\";\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/compaction/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,2BAA2B,CAAC;AAC1C,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,0BAA0B,CAAC;AACzC,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC;AACnC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,wBAAwB,CAAC;AACvC,cAAc,qBAAqB,CAAC;AACpC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,YAAY,CAAC","sourcesContent":["/**\n * Compaction support utilities.\n */\n\nexport * from \"./branch-summarization.ts\";\nexport * from \"./compaction.ts\";\nexport * from \"./compaction-types.js\";\nexport * from \"./compaction-parameters.js\";\nexport * from \"./compaction-boundary.js\";\nexport * from \"./planner-outcome.js\";\nexport * from \"./fallback-planner.js\";\nexport * from \"./region-trimming.js\";\nexport * from \"./range-planner.js\";\nexport * from \"./range-planner-diagnostics.js\";\nexport * from \"./compaction-runner.js\";\nexport * from \"./deleted-ranges.js\";\nexport * from \"./transcript-serialization.js\";\nexport * from \"./utils.ts\";\n"]}

package/dist/core/compaction/planner-outcome.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Typed outcomes for one compaction planner attempt.
+ *
+ * `planDeletedLineRanges` used to collapse ranked success, silent partial
+ * recovery, reasoning starvation, rate limiting, malformed output, and context
+ * overflow into "ranges or throw". Callers could not tell a throttle from
+ * garbage without string-matching an error message. This module makes each
+ * outcome a distinct value so the rung ladder, the `0600` diagnostic sidecar,
+ * and the UI can separate them.
+ *
+ * Cancellation is deliberately NOT a variant: an abort still throws.
+ */
+import type { Api, AssistantMessage } from "@earendil-works/pi-ai/compat";
+import type { RawLineRange } from "./compaction-types.js";
+import type { DiagnosticFailureCategory } from "./range-planner-diagnostics.js";
+/** Which limit a `rateLimited` outcome represents. */
+export type PlannerLimitClass = "quota" | "rate_limited";
+/** Every way one planner attempt can end. */
+export type PlannerOutcome = {
+    kind: "ranked";
+    ranges: RawLineRange[];
+} | {
+    kind: "recovered";
+    ranges: RawLineRange[];
+    recoveredCount: number;
+} | {
+    kind: "rateLimited";
+    /**
+     * Which limit this was, independent of retry activity. Quota/billing
+     * exhaustion and transient throttling are different facts and must stay
+     * separable in code and diagnostics; `exhausted` records only whether a
+     * retry was actually scheduled, which cannot tell them apart when retry
+     * is disabled.
+     */
+    category: PlannerLimitClass;
+    exhausted: boolean;
+    message: string;
+    diagnosticPath?: string;
+} | {
+    kind: "unusable";
+    category: DiagnosticFailureCategory;
+    excerpt: string;
+    diagnosticPath?: string;
+} | {
+    kind: "overflowed";
+    diagnosticPath?: string;
+} | {
+    kind: "providerError";
+    message: string;
+    diagnosticPath?: string;
+};
+/** A planner outcome that cannot produce a boundary and must advance the ladder. */
+export type TerminalPlannerOutcome = Extract<PlannerOutcome, {
+    kind: "rateLimited" | "unusable" | "overflowed" | "providerError";
+}>;
+/** Whether this outcome produced validated deletion ranges. */
+export declare function isPlannerSuccess(outcome: PlannerOutcome): outcome is Extract<PlannerOutcome, {
+    kind: "ranked" | "recovered";
+}>;
+/** How a failed planner response is classified before an outcome is built. */
+export type PlannerFailureClass = "overflow" | "quota" | "rate_limited" | "provider_error";
+/**
+ * Classify one failed planner response.
+ *
+ * Context overflow wins first because pi-ai's `isContextOverflow` already
+ * excludes rate/throttle text, and overflow is recoverable by trimming.
+ * Quota/billing exhaustion then wins over transient throttling, matching pi-ai's
+ * own precedence.
+ */
+export declare function classifyPlannerFailure(response: AssistantMessage, contextWindow: number): PlannerFailureClass;
+/** Build a synthetic error response so a thrown transport failure classifies identically. */
+export declare function syntheticErrorResponse(model: {
+    api: Api;
+    provider: string;
+    id: string;
+}, errorMessage: string): AssistantMessage;
+/**
+ * Reasoning starvation fingerprint: the response stopped at the output limit,
+ * produced no usable deletion record, and billed reasoning tokens.
+ *
+ * This is a diagnostic category only. Codex has no starvation concept and never
+ * retries one; neither does Atomic. A starved outcome advances the ladder
+ * exactly like any other `unusable` output.
+ */
+export declare function isReasoningStarved(response: AssistantMessage, hasUsableRanges: boolean): boolean;
+//# sourceMappingURL=planner-outcome.d.ts.map

package/dist/core/compaction/planner-outcome.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"planner-outcome.d.ts","sourceRoot":"","sources":["../../../src/core/compaction/planner-outcome.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAE1E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,gCAAgC,CAAC;AAEhF,sDAAsD;AACtD,MAAM,MAAM,iBAAiB,GAAG,OAAO,GAAG,cAAc,CAAC;AAEzD,6CAA6C;AAC7C,MAAM,MAAM,cAAc,GACvB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,YAAY,EAAE,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,MAAM,EAAE,YAAY,EAAE,CAAC;IAAC,cAAc,EAAE,MAAM,CAAA;CAAE,GACrE;IACA,IAAI,EAAE,aAAa,CAAC;IACpB;;;;;;OAMG;IACH,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,CAAC;CACvB,GACD;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,EAAE,yBAAyB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CAAE,GACnG;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CAAE,GAC/C;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvE,oFAAoF;AACpF,MAAM,MAAM,sBAAsB,GAAG,OAAO,CAC3C,cAAc,EACd;IAAE,IAAI,EAAE,aAAa,GAAG,UAAU,GAAG,YAAY,GAAG,eAAe,CAAA;CAAE,CACrE,CAAC;AAEF,+DAA+D;AAC/D,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,IAAI,OAAO,CAAC,cAAc,EAAE;IAAE,IAAI,EAAE,QAAQ,GAAG,WAAW,CAAA;CAAE,CAAC,CAE9H;AA6DD,8EAA8E;AAC9E,MAAM,MAAM,mBAAmB,GAAG,UAAU,GAAG,OAAO,GAAG,cAAc,GAAG,gBAAgB,CAAC;AAE3F;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,GAAG,mBAAmB,CAM7G;AAED,6FAA6F;AAC7F,wBAAgB,sBAAsB,CACrC,KAAK,EAAE;IAAE,GAAG,EAAE,GAAG,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,EACjD,YAAY,EAAE,MAAM,GAClB,gBAAgB,CAmBlB;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,gBAAgB,EAAE,eAAe,EAAE,OAAO,GAAG,OAAO,CAEhG"}

package/dist/core/compaction/planner-outcome.js

@@ -0,0 +1,122 @@
+/**
+ * Typed outcomes for one compaction planner attempt.
+ *
+ * `planDeletedLineRanges` used to collapse ranked success, silent partial
+ * recovery, reasoning starvation, rate limiting, malformed output, and context
+ * overflow into "ranges or throw". Callers could not tell a throttle from
+ * garbage without string-matching an error message. This module makes each
+ * outcome a distinct value so the rung ladder, the `0600` diagnostic sidecar,
+ * and the UI can separate them.
+ *
+ * Cancellation is deliberately NOT a variant: an abort still throws.
+ */
+import { isContextOverflow } from "@earendil-works/pi-ai/compat";
+/** Whether this outcome produced validated deletion ranges. */
+export function isPlannerSuccess(outcome) {
+    return outcome.kind === "ranked" || outcome.kind === "recovered";
+}
+function buildProviderErrorPattern(patterns) {
+    return new RegExp(patterns.join("|"), "i");
+}
+/**
+ * Quota/billing exhaustion. Mirrors pi-ai's
+ * `NON_RETRYABLE_PROVIDER_LIMIT_ERROR_PATTERN` (`utils/retry.js`), which takes
+ * precedence over the transient patterns and never spends backoff.
+ */
+const QUOTA_EXHAUSTED_PATTERN = buildProviderErrorPattern([
+    "GoUsageLimitError",
+    "FreeUsageLimitError",
+    "Monthly usage limit reached",
+    "available balance",
+    "insufficient_quota",
+    "out of budget",
+    "quota exceeded",
+    "billing",
+]);
+/**
+ * Generic usage-limit wording, e.g. Codex's "The usage limit has been reached".
+ *
+ * This is a deliberate **local addition**, not a mirror: pi-ai lists it in
+ * neither its non-retryable nor its retryable pattern, so `retryAssistantCall`
+ * never schedules a backoff for it. Classifying it as transient throttling would
+ * report `exhausted: true` for a retry budget that was never spent, so Atomic
+ * treats it as quota exhaustion (`exhausted: false`). pi-ai's own
+ * `Monthly usage limit reached` entry above already covers the specific form.
+ */
+const LOCAL_USAGE_LIMIT_PATTERN = /usage.?limit/i;
+/**
+ * Transient throttling and provider-load failures. This is the rate-limit
+ * subset of pi-ai's `RETRYABLE_PROVIDER_ERROR_PATTERN`, minus the individual
+ * status codes, which `HTTP_5XX_PATTERN` generalizes below.
+ */
+const RATE_LIMITED_PATTERN = buildProviderErrorPattern([
+    "overloaded",
+    "rate.?limit",
+    "too many requests",
+    "429",
+    "service.?unavailable",
+    "server.?error",
+    "internal.?error",
+    "ResourceExhausted",
+]);
+/**
+ * The whole HTTP 5xx class, bounded so it cannot match inside a longer number.
+ *
+ * A deliberate local broadening: the RFC and the acceptance contract enumerate
+ * `5xx`, while pi-ai lists only 500/502/503/504/524, so a `501` would otherwise
+ * fall through to `providerError`. The consequence is that pi-ai may schedule no
+ * backoff for a status Atomic types as rate limiting — which is exactly why
+ * `exhausted` reports *observed* retry activity rather than assuming it.
+ */
+const HTTP_5XX_PATTERN = /(?<![\d.])5\d\d(?![\d.])/;
+/**
+ * Classify one failed planner response.
+ *
+ * Context overflow wins first because pi-ai's `isContextOverflow` already
+ * excludes rate/throttle text, and overflow is recoverable by trimming.
+ * Quota/billing exhaustion then wins over transient throttling, matching pi-ai's
+ * own precedence.
+ */
+export function classifyPlannerFailure(response, contextWindow) {
+    if (isContextOverflow(response, contextWindow))
+        return "overflow";
+    const message = response.errorMessage ?? "";
+    if (QUOTA_EXHAUSTED_PATTERN.test(message) || LOCAL_USAGE_LIMIT_PATTERN.test(message))
+        return "quota";
+    if (RATE_LIMITED_PATTERN.test(message) || HTTP_5XX_PATTERN.test(message))
+        return "rate_limited";
+    return "provider_error";
+}
+/** Build a synthetic error response so a thrown transport failure classifies identically. */
+export function syntheticErrorResponse(model, errorMessage) {
+    return {
+        role: "assistant",
+        content: [],
+        api: model.api,
+        provider: model.provider,
+        model: model.id,
+        usage: {
+            input: 0,
+            output: 0,
+            cacheRead: 0,
+            cacheWrite: 0,
+            totalTokens: 0,
+            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+        },
+        stopReason: "error",
+        errorMessage,
+        timestamp: Date.now(),
+    };
+}
+/**
+ * Reasoning starvation fingerprint: the response stopped at the output limit,
+ * produced no usable deletion record, and billed reasoning tokens.
+ *
+ * This is a diagnostic category only. Codex has no starvation concept and never
+ * retries one; neither does Atomic. A starved outcome advances the ladder
+ * exactly like any other `unusable` output.
+ */
+export function isReasoningStarved(response, hasUsableRanges) {
+    return response.stopReason === "length" && !hasUsableRanges && (response.usage?.reasoning ?? 0) > 0;
+}
+//# sourceMappingURL=planner-outcome.js.map

package/dist/core/compaction/planner-outcome.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"planner-outcome.js","sourceRoot":"","sources":["../../../src/core/compaction/planner-outcome.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AAmCjE,+DAA+D;AAC/D,MAAM,UAAU,gBAAgB,CAAC,OAAuB;IACvD,OAAO,OAAO,CAAC,IAAI,KAAK,QAAQ,IAAI,OAAO,CAAC,IAAI,KAAK,WAAW,CAAC;AAClE,CAAC;AAED,SAAS,yBAAyB,CAAC,QAA2B;IAC7D,OAAO,IAAI,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC,CAAC;AAC5C,CAAC;AAED;;;;GAIG;AACH,MAAM,uBAAuB,GAAG,yBAAyB,CAAC;IACzD,mBAAmB;IACnB,qBAAqB;IACrB,6BAA6B;IAC7B,mBAAmB;IACnB,oBAAoB;IACpB,eAAe;IACf,gBAAgB;IAChB,SAAS;CACT,CAAC,CAAC;AAEH;;;;;;;;;GASG;AACH,MAAM,yBAAyB,GAAG,eAAe,CAAC;AAElD;;;;GAIG;AACH,MAAM,oBAAoB,GAAG,yBAAyB,CAAC;IACtD,YAAY;IACZ,aAAa;IACb,mBAAmB;IACnB,KAAK;IACL,sBAAsB;IACtB,eAAe;IACf,iBAAiB;IACjB,mBAAmB;CACnB,CAAC,CAAC;AAEH;;;;;;;;GAQG;AACH,MAAM,gBAAgB,GAAG,0BAA0B,CAAC;AAKpD;;;;;;;GAOG;AACH,MAAM,UAAU,sBAAsB,CAAC,QAA0B,EAAE,aAAqB;IACvF,IAAI,iBAAiB,CAAC,QAAQ,EAAE,aAAa,CAAC;QAAE,OAAO,UAAU,CAAC;IAClE,MAAM,OAAO,GAAG,QAAQ,CAAC,YAAY,IAAI,EAAE,CAAC;IAC5C,IAAI,uBAAuB,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,yBAAyB,CAAC,IAAI,CAAC,OAAO,CAAC;QAAE,OAAO,OAAO,CAAC;IACrG,IAAI,oBAAoB,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,gBAAgB,CAAC,IAAI,CAAC,OAAO,CAAC;QAAE,OAAO,cAAc,CAAC;IAChG,OAAO,gBAAgB,CAAC;AACzB,CAAC;AAED,6FAA6F;AAC7F,MAAM,UAAU,sBAAsB,CACrC,KAAiD,EACjD,YAAoB;IAEpB,OAAO;QACN,IAAI,EAAE,WAAW;QACjB,OAAO,EAAE,EAAE;QACX,GAAG,EAAE,KAAK,CAAC,GAAG;QACd,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,KAAK,EAAE,KAAK,CAAC,EAAE;QACf,KAAK,EAAE;YACN,KAAK,EAAE,CAAC;YACR,MAAM,EAAE,CAAC;YACT,SAAS,EAAE,CAAC;YACZ,UAAU,EAAE,CAAC;YACb,WAAW,EAAE,CAAC;YACd,IAAI,EAAE,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,UAAU,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE;SACpE;QACD,UAAU,EAAE,OAAO;QACnB,YAAY;QACZ,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;KACD,CAAC;AACvB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAAC,QAA0B,EAAE,eAAwB;IACtF,OAAO,QAAQ,CAAC,UAAU,KAAK,QAAQ,IAAI,CAAC,eAAe,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;AACrG,CAAC","sourcesContent":["/**\n * Typed outcomes for one compaction planner attempt.\n *\n * `planDeletedLineRanges` used to collapse ranked success, silent partial\n * recovery, reasoning starvation, rate limiting, malformed output, and context\n * overflow into \"ranges or throw\". Callers could not tell a throttle from\n * garbage without string-matching an error message. This module makes each\n * outcome a distinct value so the rung ladder, the `0600` diagnostic sidecar,\n * and the UI can separate them.\n *\n * Cancellation is deliberately NOT a variant: an abort still throws.\n */\n\nimport type { Api, AssistantMessage } from \"@earendil-works/pi-ai/compat\";\nimport { isContextOverflow } from \"@earendil-works/pi-ai/compat\";\nimport type { RawLineRange } from \"./compaction-types.js\";\nimport type { DiagnosticFailureCategory } from \"./range-planner-diagnostics.js\";\n\n/** Which limit a `rateLimited` outcome represents. */\nexport type PlannerLimitClass = \"quota\" | \"rate_limited\";\n\n/** Every way one planner attempt can end. */\nexport type PlannerOutcome =\n\t| { kind: \"ranked\"; ranges: RawLineRange[] }\n\t| { kind: \"recovered\"; ranges: RawLineRange[]; recoveredCount: number }\n\t| {\n\t\t\tkind: \"rateLimited\";\n\t\t\t/**\n\t\t\t * Which limit this was, independent of retry activity. Quota/billing\n\t\t\t * exhaustion and transient throttling are different facts and must stay\n\t\t\t * separable in code and diagnostics; `exhausted` records only whether a\n\t\t\t * retry was actually scheduled, which cannot tell them apart when retry\n\t\t\t * is disabled.\n\t\t\t */\n\t\t\tcategory: PlannerLimitClass;\n\t\t\texhausted: boolean;\n\t\t\tmessage: string;\n\t\t\tdiagnosticPath?: string;\n\t  }\n\t| { kind: \"unusable\"; category: DiagnosticFailureCategory; excerpt: string; diagnosticPath?: string }\n\t| { kind: \"overflowed\"; diagnosticPath?: string }\n\t| { kind: \"providerError\"; message: string; diagnosticPath?: string };\n\n/** A planner outcome that cannot produce a boundary and must advance the ladder. */\nexport type TerminalPlannerOutcome = Extract<\n\tPlannerOutcome,\n\t{ kind: \"rateLimited\" | \"unusable\" | \"overflowed\" | \"providerError\" }\n>;\n\n/** Whether this outcome produced validated deletion ranges. */\nexport function isPlannerSuccess(outcome: PlannerOutcome): outcome is Extract<PlannerOutcome, { kind: \"ranked\" | \"recovered\" }> {\n\treturn outcome.kind === \"ranked\" || outcome.kind === \"recovered\";\n}\n\nfunction buildProviderErrorPattern(patterns: readonly string[]): RegExp {\n\treturn new RegExp(patterns.join(\"|\"), \"i\");\n}\n\n/**\n * Quota/billing exhaustion. Mirrors pi-ai's\n * `NON_RETRYABLE_PROVIDER_LIMIT_ERROR_PATTERN` (`utils/retry.js`), which takes\n * precedence over the transient patterns and never spends backoff.\n */\nconst QUOTA_EXHAUSTED_PATTERN = buildProviderErrorPattern([\n\t\"GoUsageLimitError\",\n\t\"FreeUsageLimitError\",\n\t\"Monthly usage limit reached\",\n\t\"available balance\",\n\t\"insufficient_quota\",\n\t\"out of budget\",\n\t\"quota exceeded\",\n\t\"billing\",\n]);\n\n/**\n * Generic usage-limit wording, e.g. Codex's \"The usage limit has been reached\".\n *\n * This is a deliberate **local addition**, not a mirror: pi-ai lists it in\n * neither its non-retryable nor its retryable pattern, so `retryAssistantCall`\n * never schedules a backoff for it. Classifying it as transient throttling would\n * report `exhausted: true` for a retry budget that was never spent, so Atomic\n * treats it as quota exhaustion (`exhausted: false`). pi-ai's own\n * `Monthly usage limit reached` entry above already covers the specific form.\n */\nconst LOCAL_USAGE_LIMIT_PATTERN = /usage.?limit/i;\n\n/**\n * Transient throttling and provider-load failures. This is the rate-limit\n * subset of pi-ai's `RETRYABLE_PROVIDER_ERROR_PATTERN`, minus the individual\n * status codes, which `HTTP_5XX_PATTERN` generalizes below.\n */\nconst RATE_LIMITED_PATTERN = buildProviderErrorPattern([\n\t\"overloaded\",\n\t\"rate.?limit\",\n\t\"too many requests\",\n\t\"429\",\n\t\"service.?unavailable\",\n\t\"server.?error\",\n\t\"internal.?error\",\n\t\"ResourceExhausted\",\n]);\n\n/**\n * The whole HTTP 5xx class, bounded so it cannot match inside a longer number.\n *\n * A deliberate local broadening: the RFC and the acceptance contract enumerate\n * `5xx`, while pi-ai lists only 500/502/503/504/524, so a `501` would otherwise\n * fall through to `providerError`. The consequence is that pi-ai may schedule no\n * backoff for a status Atomic types as rate limiting — which is exactly why\n * `exhausted` reports *observed* retry activity rather than assuming it.\n */\nconst HTTP_5XX_PATTERN = /(?<![\\d.])5\\d\\d(?![\\d.])/;\n\n/** How a failed planner response is classified before an outcome is built. */\nexport type PlannerFailureClass = \"overflow\" | \"quota\" | \"rate_limited\" | \"provider_error\";\n\n/**\n * Classify one failed planner response.\n *\n * Context overflow wins first because pi-ai's `isContextOverflow` already\n * excludes rate/throttle text, and overflow is recoverable by trimming.\n * Quota/billing exhaustion then wins over transient throttling, matching pi-ai's\n * own precedence.\n */\nexport function classifyPlannerFailure(response: AssistantMessage, contextWindow: number): PlannerFailureClass {\n\tif (isContextOverflow(response, contextWindow)) return \"overflow\";\n\tconst message = response.errorMessage ?? \"\";\n\tif (QUOTA_EXHAUSTED_PATTERN.test(message) || LOCAL_USAGE_LIMIT_PATTERN.test(message)) return \"quota\";\n\tif (RATE_LIMITED_PATTERN.test(message) || HTTP_5XX_PATTERN.test(message)) return \"rate_limited\";\n\treturn \"provider_error\";\n}\n\n/** Build a synthetic error response so a thrown transport failure classifies identically. */\nexport function syntheticErrorResponse(\n\tmodel: { api: Api; provider: string; id: string },\n\terrorMessage: string,\n): AssistantMessage {\n\treturn {\n\t\trole: \"assistant\",\n\t\tcontent: [],\n\t\tapi: model.api,\n\t\tprovider: model.provider,\n\t\tmodel: model.id,\n\t\tusage: {\n\t\t\tinput: 0,\n\t\t\toutput: 0,\n\t\t\tcacheRead: 0,\n\t\t\tcacheWrite: 0,\n\t\t\ttotalTokens: 0,\n\t\t\tcost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },\n\t\t},\n\t\tstopReason: \"error\",\n\t\terrorMessage,\n\t\ttimestamp: Date.now(),\n\t} as AssistantMessage;\n}\n\n/**\n * Reasoning starvation fingerprint: the response stopped at the output limit,\n * produced no usable deletion record, and billed reasoning tokens.\n *\n * This is a diagnostic category only. Codex has no starvation concept and never\n * retries one; neither does Atomic. A starved outcome advances the ladder\n * exactly like any other `unusable` output.\n */\nexport function isReasoningStarved(response: AssistantMessage, hasUsableRanges: boolean): boolean {\n\treturn response.stopReason === \"length\" && !hasUsableRanges && (response.usage?.reasoning ?? 0) > 0;\n}\n"]}

package/dist/core/compaction/range-planner-diagnostics.d.ts

@@ -10,7 +10,15 @@
  */
 import type { Api, AssistantMessage, Model, Usage } from "@earendil-works/pi-ai/compat";
 /** Failure categories emitted in diagnostic sidecars. */
-export type DiagnosticFailureCategory = "malformed_output" | "no_usable_ranges" | "provider_error" | "stream_error";
+export type DiagnosticFailureCategory = "malformed_output" | "no_usable_ranges" | "provider_error" | "stream_error"
+/** Length stop, no usable record, and billed reasoning tokens. */
+ | "starved"
+/** Transient throttling, whether or not a retry was actually scheduled. */
+ | "rate_limited"
+/** Quota, billing, or usage-limit exhaustion; never spends backoff. */
+ | "quota"
+/** The planner request itself exceeded the model's context window. */
+ | "context_overflow";
 /** Recovery categories emitted in recovery diagnostic sidecars. */
 export type DiagnosticRecoveryCategory = "partial_length_recovery";
 /** Safe model metadata subset (no credentials, no headers). */
@@ -31,7 +39,14 @@ export interface CompactionDiagnostic {
     stopReason: string | undefined;
     providerError: string | undefined;
     usage: Usage | undefined;
-    requestMaxTokens: number;
+    /** Undefined since the planner sends no output cap. */
+    requestMaxTokens: number | undefined;
+    /**
+     * Whether a retry was actually scheduled before the final failure. It records
+     * retry activity, not the failure identity: a `rate_limited` record with retry
+     * disabled is `false`, and `quota` is always `false`.
+     */
+    rateLimitExhausted?: boolean;
     model: DiagnosticModelMeta;
 }
 /** Recovery diagnostic payload written on successful partial recovery. */
@@ -42,7 +57,7 @@ export interface RecoveryDiagnostic {
     rawResponse: string;
     stopReason: string | undefined;
     usage: Usage | undefined;
-    requestMaxTokens: number;
+    requestMaxTokens: number | undefined;
     model: DiagnosticModelMeta;
     recoveredRangeCount: number;
 }
@@ -51,8 +66,8 @@ export interface DiagnosticContext {
     sessionFilePath: string | undefined;
     /** The model used for the planner request. */
     model: Model<Api>;
-    /** The maxTokens value sent in the planner request. */
-    requestMaxTokens: number;
+    /** The maxTokens value sent in the planner request; undefined when no cap is sent. */
+    requestMaxTokens: number | undefined;
     /** The full assistant response message, if one was received. */
     response: AssistantMessage | undefined;
     /** The full raw text extracted from the response. */
@@ -61,6 +76,8 @@ export interface DiagnosticContext {
     failureCategory: DiagnosticFailureCategory;
     /** The user-facing failure message. */
     failureMessage: string;
+    /** Retry activity for a limit failure; see CompactionDiagnostic. */
+    rateLimitExhausted?: boolean;
 }
 declare function buildDiagnosticPayload(ctx: DiagnosticContext): CompactionDiagnostic;
 /**
@@ -84,7 +101,7 @@ export { buildDiagnosticPayload };
 export interface RecoveryDiagnosticContext {
     sessionFilePath: string | undefined;
     model: Model<Api>;
-    requestMaxTokens: number;
+    requestMaxTokens: number | undefined;
     response: AssistantMessage;
     rawResponseText: string;
     recoveryCategory: DiagnosticRecoveryCategory;
@@ -98,4 +115,39 @@ declare function buildRecoveryPayload(ctx: RecoveryDiagnosticContext): RecoveryD
  */
 export declare function writeRecoveryDiagnosticSidecar(ctx: RecoveryDiagnosticContext): string | undefined;
 export { buildRecoveryPayload };
+/** Success categories emitted in success diagnostic sidecars. */
+export type DiagnosticSuccessCategory = "borrowed_planner";
+/**
+ * Success diagnostic payload written when a *borrowed* fallback model ranked
+ * the lines. The RFC requires the borrowed identity to appear in diagnostics but
+ * defines no payload; this is the chosen shape, and it carries only safe data —
+ * no key, headers, auth, prompt, or transcript.
+ */
+export interface SuccessDiagnostic {
+    version: 1;
+    timestamp: string;
+    successCategory: DiagnosticSuccessCategory;
+    /** Effective reasoning level of the successful planner request, when it had one. */
+    thinkingLevel?: string;
+    /** Undefined since the planner sends no output cap. */
+    requestMaxTokens: number | undefined;
+    model: DiagnosticModelMeta;
+}
+export interface SuccessDiagnosticContext {
+    sessionFilePath: string | undefined;
+    /** The model that actually produced the accepted ranking. */
+    model: Model<Api>;
+    successCategory: DiagnosticSuccessCategory;
+    thinkingLevel?: string;
+}
+declare function buildSuccessPayload(ctx: SuccessDiagnosticContext): SuccessDiagnostic;
+/**
+ * Write a success sidecar naming the borrowed model that ranked the lines.
+ *
+ * Best-effort: an in-memory session or a write failure never changes compaction
+ * success. The filename uses a distinct `-compaction-success-<ts>.json` suffix so
+ * it cannot collide with the primary model's failure sidecar.
+ */
+export declare function writeSuccessDiagnosticSidecar(ctx: SuccessDiagnosticContext): string | undefined;
+export { buildSuccessPayload };
 //# sourceMappingURL=range-planner-diagnostics.d.ts.map

package/dist/core/compaction/range-planner-diagnostics.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"range-planner-diagnostics.d.ts","sourceRoot":"","sources":["../../../src/core/compaction/range-planner-diagnostics.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"range-planner-diagnostics.d.ts","sourceRoot":"","sources":["../../../src/core/compaction/range-planner-diagnostics.ts"],"names":[],"mappings":"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"}

package/dist/core/compaction/range-planner-diagnostics.js

@@ -10,6 +10,40 @@
  */
 import { chmodSync, writeFileSync } from "fs";
 import { basename, dirname, join } from "path";
+import { uuidv7 } from "@earendil-works/pi-ai";
+/**
+ * Write one private sidecar, never replacing an existing record.
+ *
+ * Names were previously millisecond-only, so two attempts inside the same
+ * millisecond — easy to hit across overflow trims or a fast fallback walk —
+ * selected the same path and the second write silently replaced the first.
+ * A `uuidv7()` discriminator plus exclusive creation (`flag: "wx"`) keeps one
+ * durable record per attempt. Retry on collision; every other failure stays
+ * best-effort and never changes the planner outcome.
+ */
+function writeSidecar(sessionFilePath, kind, payload) {
+    const dir = dirname(sessionFilePath);
+    const base = basename(sessionFilePath, ".jsonl");
+    const timestamp = Date.now();
+    const body = JSON.stringify(payload, null, 2);
+    for (let attempt = 0; attempt < 4; attempt++) {
+        const filePath = join(dir, `${base}-compaction-${kind}-${timestamp}-${uuidv7()}.json`);
+        try {
+            writeFileSync(filePath, body, { encoding: "utf-8", mode: 0o600, flag: "wx" });
+            try {
+                chmodSync(filePath, 0o600);
+            }
+            catch { /* best-effort on non-POSIX */ }
+            return filePath;
+        }
+        catch (error) {
+            if (error?.code === "EEXIST")
+                continue;
+            return undefined;
+        }
+    }
+    return undefined;
+}
 function buildDiagnosticPayload(ctx) {
     return {
         version: 1,
@@ -21,6 +55,7 @@ function buildDiagnosticPayload(ctx) {
         providerError: ctx.response?.errorMessage,
         usage: ctx.response?.usage,
         requestMaxTokens: ctx.requestMaxTokens,
+        ...(ctx.rateLimitExhausted === undefined ? {} : { rateLimitExhausted: ctx.rateLimitExhausted }),
         model: {
             provider: ctx.model.provider,
             id: ctx.model.id,
@@ -37,8 +72,9 @@ function buildDiagnosticPayload(ctx) {
 export function diagnosticSidecarPath(sessionFilePath) {
     const dir = dirname(sessionFilePath);
     const base = basename(sessionFilePath, ".jsonl");
-    const ts = Date.now();
-    return join(dir, `${base}-compaction-diagnostic-${ts}.json`);
+    // Includes a per-attempt discriminator so two attempts inside one millisecond
+    // cannot select the same path; see `writeSidecar`.
+    return join(dir, `${base}-compaction-diagnostic-${Date.now()}-${uuidv7()}.json`);
 }
 /**
  * Attempt to write a diagnostic sidecar file. Returns the written path on
@@ -50,19 +86,7 @@ export function diagnosticSidecarPath(sessionFilePath) {
 export function writeDiagnosticSidecar(ctx) {
     if (!ctx.sessionFilePath)
         return undefined;
-    const payload = buildDiagnosticPayload(ctx);
-    const filePath = diagnosticSidecarPath(ctx.sessionFilePath);
-    try {
-        writeFileSync(filePath, JSON.stringify(payload, null, 2), { encoding: "utf-8", mode: 0o600 });
-        try {
-            chmodSync(filePath, 0o600);
-        }
-        catch { /* best-effort on non-POSIX */ }
-        return filePath;
-    }
-    catch {
-        return undefined;
-    }
+    return writeSidecar(ctx.sessionFilePath, "diagnostic", buildDiagnosticPayload(ctx));
 }
 /**
  * Build the diagnostic payload without writing. Exported for testing.
@@ -95,22 +119,36 @@ function buildRecoveryPayload(ctx) {
 export function writeRecoveryDiagnosticSidecar(ctx) {
     if (!ctx.sessionFilePath)
         return undefined;
-    const payload = buildRecoveryPayload(ctx);
-    const dir = dirname(ctx.sessionFilePath);
-    const base = basename(ctx.sessionFilePath, ".jsonl");
-    const ts = Date.now();
-    const filePath = join(dir, `${base}-compaction-recovery-${ts}.json`);
-    try {
-        writeFileSync(filePath, JSON.stringify(payload, null, 2), { encoding: "utf-8", mode: 0o600 });
-        try {
-            chmodSync(filePath, 0o600);
-        }
-        catch { /* best-effort on non-POSIX */ }
-        return filePath;
-    }
-    catch {
-        return undefined;
-    }
+    return writeSidecar(ctx.sessionFilePath, "recovery", buildRecoveryPayload(ctx));
 }
 export { buildRecoveryPayload };
+function buildSuccessPayload(ctx) {
+    return {
+        version: 1,
+        timestamp: new Date().toISOString(),
+        successCategory: ctx.successCategory,
+        ...(ctx.thinkingLevel === undefined ? {} : { thinkingLevel: ctx.thinkingLevel }),
+        requestMaxTokens: undefined,
+        model: {
+            provider: ctx.model.provider,
+            id: ctx.model.id,
+            api: ctx.model.api,
+            contextWindow: ctx.model.contextWindow,
+            maxTokens: ctx.model.maxTokens,
+        },
+    };
+}
+/**
+ * Write a success sidecar naming the borrowed model that ranked the lines.
+ *
+ * Best-effort: an in-memory session or a write failure never changes compaction
+ * success. The filename uses a distinct `-compaction-success-<ts>.json` suffix so
+ * it cannot collide with the primary model's failure sidecar.
+ */
+export function writeSuccessDiagnosticSidecar(ctx) {
+    if (!ctx.sessionFilePath)
+        return undefined;
+    return writeSidecar(ctx.sessionFilePath, "success", buildSuccessPayload(ctx));
+}
+export { buildSuccessPayload };
 //# sourceMappingURL=range-planner-diagnostics.js.map

package/dist/core/compaction/range-planner-diagnostics.js.map

@@ -1 +1 @@
-{"version":3,"file":"range-planner-diagnostics.js","sourceRoot":"","sources":["../../../src/core/compaction/range-planner-diagnostics.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Diagnostic sidecar writer for compaction planner output.\n *\n * When the one-pass range planner returns malformed output or no usable ranges,\n * this module writes a private diagnostic file next to the persisted session\n * file. The sidecar is never written for in-memory sessions.\n *\n * Additionally, successful partial recovery from length-truncated responses\n * writes a private recovery diagnostic sidecar for operational observability.\n */\n\nimport { chmodSync, writeFileSync } from \"fs\";\nimport { basename, dirname, join } from \"path\";\nimport type { Api, AssistantMessage, Model, Usage } from \"@earendil-works/pi-ai/compat\";\n\n/** Failure categories emitted in diagnostic sidecars. */\nexport type DiagnosticFailureCategory =\n\t| \"malformed_output\"\n\t| \"no_usable_ranges\"\n\t| \"provider_error\"\n\t| \"stream_error\";\n\n/** Recovery categories emitted in recovery diagnostic sidecars. */\nexport type DiagnosticRecoveryCategory = \"partial_length_recovery\";\n\n/** Safe model metadata subset (no credentials, no headers). */\nexport interface DiagnosticModelMeta {\n\tprovider: string;\n\tid: string;\n\tapi: string;\n\tcontextWindow: number;\n\tmaxTokens: number;\n}\n\n/** Full diagnostic payload written as the sidecar JSON file. */\nexport interface CompactionDiagnostic {\n\tversion: 1;\n\ttimestamp: string;\n\tfailureCategory: DiagnosticFailureCategory;\n\tfailureMessage: string;\n\trawResponse: string;\n\tstopReason: string | undefined;\n\tproviderError: string | undefined;\n\tusage: Usage | undefined;\n\trequestMaxTokens: number;\n\tmodel: DiagnosticModelMeta;\n}\n\n/** Recovery diagnostic payload written on successful partial recovery. */\nexport interface RecoveryDiagnostic {\n\tversion: 1;\n\ttimestamp: string;\n\trecoveryCategory: DiagnosticRecoveryCategory;\n\trawResponse: string;\n\tstopReason: string | undefined;\n\tusage: Usage | undefined;\n\trequestMaxTokens: number;\n\tmodel: DiagnosticModelMeta;\n\trecoveredRangeCount: number;\n}\n\nexport interface DiagnosticContext {\n\t/** Absolute path to the persisted session file, or undefined for in-memory sessions. */\n\tsessionFilePath: string | undefined;\n\t/** The model used for the planner request. */\n\tmodel: Model<Api>;\n\t/** The maxTokens value sent in the planner request. */\n\trequestMaxTokens: number;\n\t/** The full assistant response message, if one was received. */\n\tresponse: AssistantMessage | undefined;\n\t/** The full raw text extracted from the response. */\n\trawResponseText: string;\n\t/** The failure category. */\n\tfailureCategory: DiagnosticFailureCategory;\n\t/** The user-facing failure message. */\n\tfailureMessage: string;\n}\n\nfunction buildDiagnosticPayload(ctx: DiagnosticContext): CompactionDiagnostic {\n\treturn {\n\t\tversion: 1,\n\t\ttimestamp: new Date().toISOString(),\n\t\tfailureCategory: ctx.failureCategory,\n\t\tfailureMessage: ctx.failureMessage,\n\t\trawResponse: ctx.rawResponseText,\n\t\tstopReason: ctx.response?.stopReason,\n\t\tproviderError: ctx.response?.errorMessage,\n\t\tusage: ctx.response?.usage,\n\t\trequestMaxTokens: ctx.requestMaxTokens,\n\t\tmodel: {\n\t\t\tprovider: ctx.model.provider,\n\t\t\tid: ctx.model.id,\n\t\t\tapi: ctx.model.api,\n\t\t\tcontextWindow: ctx.model.contextWindow,\n\t\t\tmaxTokens: ctx.model.maxTokens,\n\t\t},\n\t};\n}\n\n/**\n * Derive the sidecar file path from a session file path and current timestamp.\n * The sidecar sits alongside the session file with a `-compaction-diagnostic-<ts>.json` suffix.\n */\nexport function diagnosticSidecarPath(sessionFilePath: string): string {\n\tconst dir = dirname(sessionFilePath);\n\tconst base = basename(sessionFilePath, \".jsonl\");\n\tconst ts = Date.now();\n\treturn join(dir, `${base}-compaction-diagnostic-${ts}.json`);\n}\n\n/**\n * Attempt to write a diagnostic sidecar file. Returns the written path on\n * success, or undefined if the session is in-memory or writing fails.\n *\n * The file is written with mode 0o600 (owner-only read/write) on platforms\n * that support POSIX permissions.\n */\nexport function writeDiagnosticSidecar(ctx: DiagnosticContext): string | undefined {\n\tif (!ctx.sessionFilePath) return undefined;\n\n\tconst payload = buildDiagnosticPayload(ctx);\n\tconst filePath = diagnosticSidecarPath(ctx.sessionFilePath);\n\n\ttry {\n\t\twriteFileSync(filePath, JSON.stringify(payload, null, 2), { encoding: \"utf-8\", mode: 0o600 });\n\t\ttry { chmodSync(filePath, 0o600); } catch { /* best-effort on non-POSIX */ }\n\t\treturn filePath;\n\t} catch {\n\t\treturn undefined;\n\t}\n}\n\n/**\n * Build the diagnostic payload without writing. Exported for testing.\n */\nexport { buildDiagnosticPayload };\n\n/** Context for writing a recovery diagnostic sidecar. */\nexport interface RecoveryDiagnosticContext {\n\tsessionFilePath: string | undefined;\n\tmodel: Model<Api>;\n\trequestMaxTokens: number;\n\tresponse: AssistantMessage;\n\trawResponseText: string;\n\trecoveryCategory: DiagnosticRecoveryCategory;\n\trecoveredRangeCount: number;\n}\n\nfunction buildRecoveryPayload(ctx: RecoveryDiagnosticContext): RecoveryDiagnostic {\n\treturn {\n\t\tversion: 1,\n\t\ttimestamp: new Date().toISOString(),\n\t\trecoveryCategory: ctx.recoveryCategory,\n\t\trawResponse: ctx.rawResponseText,\n\t\tstopReason: ctx.response.stopReason,\n\t\tusage: ctx.response.usage,\n\t\trequestMaxTokens: ctx.requestMaxTokens,\n\t\tmodel: {\n\t\t\tprovider: ctx.model.provider,\n\t\t\tid: ctx.model.id,\n\t\t\tapi: ctx.model.api,\n\t\t\tcontextWindow: ctx.model.contextWindow,\n\t\t\tmaxTokens: ctx.model.maxTokens,\n\t\t},\n\t\trecoveredRangeCount: ctx.recoveredRangeCount,\n\t};\n}\n\n/**\n * Write a recovery diagnostic sidecar on successful partial recovery.\n * Returns the written path on success, or undefined if write fails or session is in-memory.\n * Write failures are silently swallowed — recovery success is never affected.\n */\nexport function writeRecoveryDiagnosticSidecar(ctx: RecoveryDiagnosticContext): string | undefined {\n\tif (!ctx.sessionFilePath) return undefined;\n\n\tconst payload = buildRecoveryPayload(ctx);\n\tconst dir = dirname(ctx.sessionFilePath);\n\tconst base = basename(ctx.sessionFilePath, \".jsonl\");\n\tconst ts = Date.now();\n\tconst filePath = join(dir, `${base}-compaction-recovery-${ts}.json`);\n\n\ttry {\n\t\twriteFileSync(filePath, JSON.stringify(payload, null, 2), { encoding: \"utf-8\", mode: 0o600 });\n\t\ttry { chmodSync(filePath, 0o600); } catch { /* best-effort on non-POSIX */ }\n\t\treturn filePath;\n\t} catch {\n\t\treturn undefined;\n\t}\n}\n\nexport { buildRecoveryPayload };\n"]}
+{"version":3,"file":"range-planner-diagnostics.js","sourceRoot":"","sources":["../../../src/core/compaction/range-planner-diagnostics.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Diagnostic sidecar writer for compaction planner output.\n *\n * When the one-pass range planner returns malformed output or no usable ranges,\n * this module writes a private diagnostic file next to the persisted session\n * file. The sidecar is never written for in-memory sessions.\n *\n * Additionally, successful partial recovery from length-truncated responses\n * writes a private recovery diagnostic sidecar for operational observability.\n */\n\nimport { chmodSync, writeFileSync } from \"fs\";\nimport { basename, dirname, join } from \"path\";\nimport { uuidv7 } from \"@earendil-works/pi-ai\";\nimport type { Api, AssistantMessage, Model, Usage } from \"@earendil-works/pi-ai/compat\";\n\n/**\n * Write one private sidecar, never replacing an existing record.\n *\n * Names were previously millisecond-only, so two attempts inside the same\n * millisecond — easy to hit across overflow trims or a fast fallback walk —\n * selected the same path and the second write silently replaced the first.\n * A `uuidv7()` discriminator plus exclusive creation (`flag: \"wx\"`) keeps one\n * durable record per attempt. Retry on collision; every other failure stays\n * best-effort and never changes the planner outcome.\n */\nfunction writeSidecar(sessionFilePath: string, kind: string, payload: unknown): string | undefined {\n\tconst dir = dirname(sessionFilePath);\n\tconst base = basename(sessionFilePath, \".jsonl\");\n\tconst timestamp = Date.now();\n\tconst body = JSON.stringify(payload, null, 2);\n\tfor (let attempt = 0; attempt < 4; attempt++) {\n\t\tconst filePath = join(dir, `${base}-compaction-${kind}-${timestamp}-${uuidv7()}.json`);\n\t\ttry {\n\t\t\twriteFileSync(filePath, body, { encoding: \"utf-8\", mode: 0o600, flag: \"wx\" });\n\t\t\ttry { chmodSync(filePath, 0o600); } catch { /* best-effort on non-POSIX */ }\n\t\t\treturn filePath;\n\t\t} catch (error) {\n\t\t\tif ((error as NodeJS.ErrnoException)?.code === \"EEXIST\") continue;\n\t\t\treturn undefined;\n\t\t}\n\t}\n\treturn undefined;\n}\n\n/** Failure categories emitted in diagnostic sidecars. */\nexport type DiagnosticFailureCategory =\n\t| \"malformed_output\"\n\t| \"no_usable_ranges\"\n\t| \"provider_error\"\n\t| \"stream_error\"\n\t/** Length stop, no usable record, and billed reasoning tokens. */\n\t| \"starved\"\n\t/** Transient throttling, whether or not a retry was actually scheduled. */\n\t| \"rate_limited\"\n\t/** Quota, billing, or usage-limit exhaustion; never spends backoff. */\n\t| \"quota\"\n\t/** The planner request itself exceeded the model's context window. */\n\t| \"context_overflow\";\n\n/** Recovery categories emitted in recovery diagnostic sidecars. */\nexport type DiagnosticRecoveryCategory = \"partial_length_recovery\";\n\n/** Safe model metadata subset (no credentials, no headers). */\nexport interface DiagnosticModelMeta {\n\tprovider: string;\n\tid: string;\n\tapi: string;\n\tcontextWindow: number;\n\tmaxTokens: number;\n}\n\n/** Full diagnostic payload written as the sidecar JSON file. */\nexport interface CompactionDiagnostic {\n\tversion: 1;\n\ttimestamp: string;\n\tfailureCategory: DiagnosticFailureCategory;\n\tfailureMessage: string;\n\trawResponse: string;\n\tstopReason: string | undefined;\n\tproviderError: string | undefined;\n\tusage: Usage | undefined;\n\t/** Undefined since the planner sends no output cap. */\n\trequestMaxTokens: number | undefined;\n\t/**\n\t * Whether a retry was actually scheduled before the final failure. It records\n\t * retry activity, not the failure identity: a `rate_limited` record with retry\n\t * disabled is `false`, and `quota` is always `false`.\n\t */\n\trateLimitExhausted?: boolean;\n\tmodel: DiagnosticModelMeta;\n}\n\n/** Recovery diagnostic payload written on successful partial recovery. */\nexport interface RecoveryDiagnostic {\n\tversion: 1;\n\ttimestamp: string;\n\trecoveryCategory: DiagnosticRecoveryCategory;\n\trawResponse: string;\n\tstopReason: string | undefined;\n\tusage: Usage | undefined;\n\trequestMaxTokens: number | undefined;\n\tmodel: DiagnosticModelMeta;\n\trecoveredRangeCount: number;\n}\n\nexport interface DiagnosticContext {\n\t/** Absolute path to the persisted session file, or undefined for in-memory sessions. */\n\tsessionFilePath: string | undefined;\n\t/** The model used for the planner request. */\n\tmodel: Model<Api>;\n\t/** The maxTokens value sent in the planner request; undefined when no cap is sent. */\n\trequestMaxTokens: number | undefined;\n\t/** The full assistant response message, if one was received. */\n\tresponse: AssistantMessage | undefined;\n\t/** The full raw text extracted from the response. */\n\trawResponseText: string;\n\t/** The failure category. */\n\tfailureCategory: DiagnosticFailureCategory;\n\t/** The user-facing failure message. */\n\tfailureMessage: string;\n\t/** Retry activity for a limit failure; see CompactionDiagnostic. */\n\trateLimitExhausted?: boolean;\n}\n\nfunction buildDiagnosticPayload(ctx: DiagnosticContext): CompactionDiagnostic {\n\treturn {\n\t\tversion: 1,\n\t\ttimestamp: new Date().toISOString(),\n\t\tfailureCategory: ctx.failureCategory,\n\t\tfailureMessage: ctx.failureMessage,\n\t\trawResponse: ctx.rawResponseText,\n\t\tstopReason: ctx.response?.stopReason,\n\t\tproviderError: ctx.response?.errorMessage,\n\t\tusage: ctx.response?.usage,\n\t\trequestMaxTokens: ctx.requestMaxTokens,\n\t\t...(ctx.rateLimitExhausted === undefined ? {} : { rateLimitExhausted: ctx.rateLimitExhausted }),\n\t\tmodel: {\n\t\t\tprovider: ctx.model.provider,\n\t\t\tid: ctx.model.id,\n\t\t\tapi: ctx.model.api,\n\t\t\tcontextWindow: ctx.model.contextWindow,\n\t\t\tmaxTokens: ctx.model.maxTokens,\n\t\t},\n\t};\n}\n\n/**\n * Derive the sidecar file path from a session file path and current timestamp.\n * The sidecar sits alongside the session file with a `-compaction-diagnostic-<ts>.json` suffix.\n */\nexport function diagnosticSidecarPath(sessionFilePath: string): string {\n\tconst dir = dirname(sessionFilePath);\n\tconst base = basename(sessionFilePath, \".jsonl\");\n\t// Includes a per-attempt discriminator so two attempts inside one millisecond\n\t// cannot select the same path; see `writeSidecar`.\n\treturn join(dir, `${base}-compaction-diagnostic-${Date.now()}-${uuidv7()}.json`);\n}\n\n/**\n * Attempt to write a diagnostic sidecar file. Returns the written path on\n * success, or undefined if the session is in-memory or writing fails.\n *\n * The file is written with mode 0o600 (owner-only read/write) on platforms\n * that support POSIX permissions.\n */\nexport function writeDiagnosticSidecar(ctx: DiagnosticContext): string | undefined {\n\tif (!ctx.sessionFilePath) return undefined;\n\n\treturn writeSidecar(ctx.sessionFilePath, \"diagnostic\", buildDiagnosticPayload(ctx));\n}\n\n/**\n * Build the diagnostic payload without writing. Exported for testing.\n */\nexport { buildDiagnosticPayload };\n\n/** Context for writing a recovery diagnostic sidecar. */\nexport interface RecoveryDiagnosticContext {\n\tsessionFilePath: string | undefined;\n\tmodel: Model<Api>;\n\trequestMaxTokens: number | undefined;\n\tresponse: AssistantMessage;\n\trawResponseText: string;\n\trecoveryCategory: DiagnosticRecoveryCategory;\n\trecoveredRangeCount: number;\n}\n\nfunction buildRecoveryPayload(ctx: RecoveryDiagnosticContext): RecoveryDiagnostic {\n\treturn {\n\t\tversion: 1,\n\t\ttimestamp: new Date().toISOString(),\n\t\trecoveryCategory: ctx.recoveryCategory,\n\t\trawResponse: ctx.rawResponseText,\n\t\tstopReason: ctx.response.stopReason,\n\t\tusage: ctx.response.usage,\n\t\trequestMaxTokens: ctx.requestMaxTokens,\n\t\tmodel: {\n\t\t\tprovider: ctx.model.provider,\n\t\t\tid: ctx.model.id,\n\t\t\tapi: ctx.model.api,\n\t\t\tcontextWindow: ctx.model.contextWindow,\n\t\t\tmaxTokens: ctx.model.maxTokens,\n\t\t},\n\t\trecoveredRangeCount: ctx.recoveredRangeCount,\n\t};\n}\n\n/**\n * Write a recovery diagnostic sidecar on successful partial recovery.\n * Returns the written path on success, or undefined if write fails or session is in-memory.\n * Write failures are silently swallowed — recovery success is never affected.\n */\nexport function writeRecoveryDiagnosticSidecar(ctx: RecoveryDiagnosticContext): string | undefined {\n\tif (!ctx.sessionFilePath) return undefined;\n\n\treturn writeSidecar(ctx.sessionFilePath, \"recovery\", buildRecoveryPayload(ctx));\n}\n\nexport { buildRecoveryPayload };\n\n/** Success categories emitted in success diagnostic sidecars. */\nexport type DiagnosticSuccessCategory = \"borrowed_planner\";\n\n/**\n * Success diagnostic payload written when a *borrowed* fallback model ranked\n * the lines. The RFC requires the borrowed identity to appear in diagnostics but\n * defines no payload; this is the chosen shape, and it carries only safe data —\n * no key, headers, auth, prompt, or transcript.\n */\nexport interface SuccessDiagnostic {\n\tversion: 1;\n\ttimestamp: string;\n\tsuccessCategory: DiagnosticSuccessCategory;\n\t/** Effective reasoning level of the successful planner request, when it had one. */\n\tthinkingLevel?: string;\n\t/** Undefined since the planner sends no output cap. */\n\trequestMaxTokens: number | undefined;\n\tmodel: DiagnosticModelMeta;\n}\n\nexport interface SuccessDiagnosticContext {\n\tsessionFilePath: string | undefined;\n\t/** The model that actually produced the accepted ranking. */\n\tmodel: Model<Api>;\n\tsuccessCategory: DiagnosticSuccessCategory;\n\tthinkingLevel?: string;\n}\n\nfunction buildSuccessPayload(ctx: SuccessDiagnosticContext): SuccessDiagnostic {\n\treturn {\n\t\tversion: 1,\n\t\ttimestamp: new Date().toISOString(),\n\t\tsuccessCategory: ctx.successCategory,\n\t\t...(ctx.thinkingLevel === undefined ? {} : { thinkingLevel: ctx.thinkingLevel }),\n\t\trequestMaxTokens: undefined,\n\t\tmodel: {\n\t\t\tprovider: ctx.model.provider,\n\t\t\tid: ctx.model.id,\n\t\t\tapi: ctx.model.api,\n\t\t\tcontextWindow: ctx.model.contextWindow,\n\t\t\tmaxTokens: ctx.model.maxTokens,\n\t\t},\n\t};\n}\n\n/**\n * Write a success sidecar naming the borrowed model that ranked the lines.\n *\n * Best-effort: an in-memory session or a write failure never changes compaction\n * success. The filename uses a distinct `-compaction-success-<ts>.json` suffix so\n * it cannot collide with the primary model's failure sidecar.\n */\nexport function writeSuccessDiagnosticSidecar(ctx: SuccessDiagnosticContext): string | undefined {\n\tif (!ctx.sessionFilePath) return undefined;\n\n\treturn writeSidecar(ctx.sessionFilePath, \"success\", buildSuccessPayload(ctx));\n}\n\nexport { buildSuccessPayload };\n"]}