fix(explore): shrink a later cluster into the remainder instead of dropping it (CG-36)

A file's ranked clusters were all-or-nothing past the first one: the top-ranked
cluster was taken (shrunk to fit when it had to be) and every cluster below it
was rendered whole, then either fit the remainder or was dropped entirely. On a
file whose top-ranked cluster is TRIVIAL that discards the answer — django's
`db/models/sql/query.py` kept a 22-line glue cluster and dropped the 624-line
`Query` body, spending 1,923 of a 7,947 reservation; okhttp's
`RealInterceptorChain.kt` did the same behind its import header.

The response stayed full, which is why this was invisible: the unspent
reservation carried forward exactly as designed and a file scoring a fifth as
much took the bytes.

Two sites, the same rule — hold the remainder while it is still worth a section
(CG-26's between-FILES lesson, applied between CLUSTERS):

- selection now shrinks a later cluster into what is left of the file's budget,
  by the same whole-member rule the first cluster already used;
- the ceiling trim re-renders the weakest cluster into the room that remains
  before dropping it. On excalidraw's `typeChecks.ts` the section-cost estimate
  missed by 13 chars and a 1,512-char cluster — the file's highest-SCORING one —
  was thrown away to pay for it.

Cluster RANKING is untouched: measured, both real cases lost on `maxImportance`,
not on the density tiebreak the issue suspected, and density-first is what keeps
Alamofire's `Session.swift` from burying its methods under the property list.

Suite (6 repos, clean-rebuilt indexes): all 8 starvation flags cleared,
+1,012 source chars net. django's `sql/query.py` 1,923 -> 10,082 of 7,947,
okhttp's `RealInterceptorChain.kt` 1,474 -> 6,038 of 6,058, gin's
`routergroup.go` 3,273 -> 5,632. okhttp trades its rank-6 file (score 21) for
+7,196 chars in the two files that answer the question.

Ships two fixtures pulling in opposite directions (`starved-cluster-ts` and
`dense-header-ts`), a `spendShareAtLeast` gate in probe-allocation, and
probe-file-spend.mjs — a standing per-file reservation-vs-delivered sweep.

__tests__/fixtures/dense-header-ts/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "dense-header-fixture",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module"
+}

__tests__/fixtures/dense-header-ts/src/core/queue.ts

@@ -0,0 +1,23 @@
+import type { URLSessionTask } from './types';
+
+export class RequestQueue {
+  private readonly waiting: URLSessionTask[] = [];
+  private running = 0;
+
+  enqueue(task: URLSessionTask, limit: number): void {
+    if (this.running < limit) {
+      this.running += 1;
+      return;
+    }
+    this.waiting.push(task);
+  }
+
+  release(): URLSessionTask | undefined {
+    this.running = Math.max(0, this.running - 1);
+    return this.waiting.shift();
+  }
+
+  get depth(): number {
+    return this.waiting.length;
+  }
+}

__tests__/fixtures/dense-header-ts/src/core/request-builder.ts

@@ -0,0 +1,27 @@
+import type { CachePolicy, URLRequest } from './types';
+
+export function buildURLRequest(options: {
+  url: string;
+  method: string;
+  body?: Uint8Array;
+  headers: Record<string, string>;
+  timeout: number;
+  cachePolicy: CachePolicy;
+}): URLRequest {
+  const headers = { ...options.headers };
+  if (options.body && !headers['content-length']) {
+    headers['content-length'] = String(options.body.length);
+  }
+  return {
+    url: normalize(options.url),
+    method: options.method.toUpperCase(),
+    headers,
+    body: options.body,
+    timeout: options.timeout,
+    cachePolicy: options.cachePolicy,
+  };
+}
+
+function normalize(url: string): string {
+  return url.endsWith('/') && url.split('/').length > 4 ? url.slice(0, -1) : url;
+}

__tests__/fixtures/dense-header-ts/src/core/task-factory.ts

@@ -0,0 +1,23 @@
+import type { RequestDelegate, TaskResponse, URLRequest, URLSessionTask } from './types';
+
+export function makeTask(options: {
+  identifier: number;
+  request: URLRequest;
+  delegate: RequestDelegate;
+  allowsCellularAccess: boolean;
+  waitsForConnectivity: boolean;
+  resourceTimeout: number;
+}): URLSessionTask {
+  const handlers: Array<(response: TaskResponse) => void> = [];
+  return {
+    identifier: options.identifier,
+    request: options.request,
+    state: 'initialized',
+    cancel() { this.state = 'cancelled'; },
+    onComplete(handler) { handlers.push(handler); },
+  };
+}
+
+export function resumeTask(task: URLSessionTask): void {
+  task.state = 'resumed';
+}

__tests__/fixtures/dense-header-ts/src/core/types.ts

@@ -0,0 +1,42 @@
+export type CachePolicy = 'useProtocolCachePolicy' | 'reloadIgnoringLocalCacheData' | 'returnCacheDataElseLoad';
+export type RequestState = 'initialized' | 'resumed' | 'suspended' | 'cancelled' | 'finished';
+
+export interface URLRequest {
+  url: string;
+  method: string;
+  headers: Record<string, string>;
+  body?: Uint8Array;
+  timeout: number;
+  cachePolicy: CachePolicy;
+}
+
+export interface TaskResponse {
+  status: number;
+  headers: Record<string, string>;
+  body: Uint8Array;
+}
+
+export interface URLSessionTask {
+  identifier: number;
+  request: URLRequest;
+  state: RequestState;
+  cancel(): void;
+  onComplete(handler: (response: TaskResponse) => void): void;
+}
+
+export interface Adapter { adapt(request: URLRequest): URLRequest; }
+export interface Serializer { serialize(value: unknown): Uint8Array; }
+export interface Validator { validate(response: TaskResponse): { ok: boolean; reason?: string }; }
+export interface Retrier { shouldRetry(response: TaskResponse, verdict: { ok: boolean }): boolean; }
+export interface RedirectHandler { resolve(location: string, original: URLRequest): { url: string; method: string; body?: Uint8Array } | null; }
+export interface TrustEvaluator { evaluate(host: string): boolean; }
+export interface Credential { apply(request: URLRequest): URLRequest; }
+export interface Interceptor { name: string; adapt(request: URLRequest, session: unknown): Promise<URLRequest>; }
+export interface RequestDelegate { willSend(request: URLRequest): void; }
+export interface EventMonitor {
+  didAdaptRequest(request: URLRequest, interceptor: string): void;
+  didCreateTask(task: URLSessionTask, request: URLRequest): void;
+  didResumeTask(task: URLSessionTask): void;
+  didRetryTask(task: URLSessionTask, previousIdentifier: number): void;
+  didCompleteTask(task: URLSessionTask, response: TaskResponse): void;
+}

__tests__/fixtures/dense-header-ts/src/index.ts

@@ -0,0 +1,3 @@
+export { Session } from './net/session';
+export { RequestQueue } from './core/queue';
+export { buildURLRequest } from './core/request-builder';

__tests__/fixtures/dense-header-ts/src/net/session.ts

@@ -0,0 +1,285 @@
+import type {
+  Adapter,
+  CachePolicy,
+  Credential,
+  EventMonitor,
+  Interceptor,
+  RedirectHandler,
+  RequestDelegate,
+  RequestState,
+  Retrier,
+  Serializer,
+  TrustEvaluator,
+  URLRequest,
+  URLSessionTask,
+  Validator,
+} from '../core/types';
+import { buildURLRequest } from '../core/request-builder';
+import { makeTask, resumeTask } from '../core/task-factory';
+import { RequestQueue } from '../core/queue';
+
+/**
+ * The shape density-first ranking exists for: a class whose top-of-file header
+ * is a long, tightly-packed property list — dozens of adjacent declarations,
+ * each individually trivial — while the methods a flow question actually asks
+ * about live hundreds of lines below it.
+ *
+ * Ranked by density alone the header wins the file's whole budget and the
+ * methods are buried. The ranking puts importance first for exactly this
+ * reason, and density only breaks ties inside one importance tier.
+ */
+export class Session {
+  readonly identifier: string;
+  readonly adapter: Adapter;
+  readonly serializer: Serializer;
+  readonly validator: Validator;
+  readonly retrier: Retrier;
+  readonly redirectHandler: RedirectHandler;
+  readonly trustEvaluator: TrustEvaluator;
+  readonly eventMonitor: EventMonitor;
+  readonly cachePolicy: CachePolicy;
+  readonly credential: Credential | null;
+  readonly interceptors: Interceptor[];
+  readonly delegate: RequestDelegate;
+  readonly queue: RequestQueue;
+  readonly startRequestsImmediately: boolean;
+  readonly maximumConnectionsPerHost: number;
+  readonly timeoutIntervalForRequest: number;
+  readonly timeoutIntervalForResource: number;
+  readonly allowsCellularAccess: boolean;
+  readonly waitsForConnectivity: boolean;
+  readonly httpShouldUsePipelining: boolean;
+  readonly httpShouldSetCookies: boolean;
+  readonly httpMaximumConnectionsPerHost: number;
+  readonly sessionConfigurationName: string;
+  readonly requestState: RequestState;
+  readonly defaultHeaders: Record<string, string>;
+  readonly userAgent: string;
+  readonly acceptEncoding: string;
+  readonly acceptLanguage: string;
+  private taskCounter = 0;
+  private active = new Map<number, URLSessionTask>();
+
+  constructor(options: Partial<Session> & { identifier: string }) {
+    this.identifier = options.identifier;
+    this.adapter = options.adapter!;
+    this.serializer = options.serializer!;
+    this.validator = options.validator!;
+    this.retrier = options.retrier!;
+    this.redirectHandler = options.redirectHandler!;
+    this.trustEvaluator = options.trustEvaluator!;
+    this.eventMonitor = options.eventMonitor!;
+    this.cachePolicy = options.cachePolicy ?? 'useProtocolCachePolicy';
+    this.credential = options.credential ?? null;
+    this.interceptors = options.interceptors ?? [];
+    this.delegate = options.delegate!;
+    this.queue = options.queue ?? new RequestQueue();
+    this.startRequestsImmediately = options.startRequestsImmediately ?? true;
+    this.maximumConnectionsPerHost = options.maximumConnectionsPerHost ?? 6;
+    this.timeoutIntervalForRequest = options.timeoutIntervalForRequest ?? 60;
+    this.timeoutIntervalForResource = options.timeoutIntervalForResource ?? 604800;
+    this.allowsCellularAccess = options.allowsCellularAccess ?? true;
+    this.waitsForConnectivity = options.waitsForConnectivity ?? false;
+    this.httpShouldUsePipelining = options.httpShouldUsePipelining ?? false;
+    this.httpShouldSetCookies = options.httpShouldSetCookies ?? true;
+    this.httpMaximumConnectionsPerHost = options.httpMaximumConnectionsPerHost ?? 6;
+    this.sessionConfigurationName = options.sessionConfigurationName ?? 'default';
+    this.requestState = options.requestState ?? 'initialized';
+    this.defaultHeaders = options.defaultHeaders ?? {};
+    this.userAgent = options.userAgent ?? 'session/1.0';
+    this.acceptEncoding = options.acceptEncoding ?? 'br;q=1.0, gzip;q=0.9';
+    this.acceptLanguage = options.acceptLanguage ?? 'en;q=1.0';
+  }
+
+  // -- configuration accessors ----------------------------------------------
+  // Individually trivial, adjacent, and dense. On the density tiebreak alone
+  // this block outranks anything with a body worth reading.
+
+  get isBackground(): boolean {
+    return this.sessionConfigurationName === 'background';
+  }
+
+  get connectionLimit(): number {
+    return Math.min(this.maximumConnectionsPerHost, this.httpMaximumConnectionsPerHost);
+  }
+
+  get headerDefaults(): Record<string, string> {
+    return { ...this.defaultHeaders, 'user-agent': this.userAgent };
+  }
+
+  get acceptHeaders(): Record<string, string> {
+    return { 'accept-encoding': this.acceptEncoding, 'accept-language': this.acceptLanguage };
+  }
+
+  get activeCount(): number {
+    return this.active.size;
+  }
+
+  get isIdle(): boolean {
+    return this.active.size === 0;
+  }
+
+  get nextIdentifier(): number {
+    return this.taskCounter + 1;
+  }
+
+  get description(): string {
+    return `Session(${this.identifier}, ${this.sessionConfigurationName})`;
+  }
+
+  cancelAll(): void {
+    for (const task of this.active.values()) task.cancel();
+    this.active.clear();
+  }
+
+  taskFor(identifier: number): URLSessionTask | undefined {
+    return this.active.get(identifier);
+  }
+
+  headers(): Record<string, string> {
+    return { ...this.headerDefaults, ...this.acceptHeaders };
+  }
+
+  withUserAgent(userAgent: string): Session {
+    return new Session({ ...this, identifier: this.identifier, userAgent });
+  }
+
+  withTimeout(seconds: number): Session {
+    return new Session({ ...this, identifier: this.identifier, timeoutIntervalForRequest: seconds });
+  }
+
+  withInterceptor(interceptor: Interceptor): Session {
+    return new Session({
+      ...this,
+      identifier: this.identifier,
+      interceptors: [...this.interceptors, interceptor],
+    });
+  }
+
+  withCredential(credential: Credential): Session {
+    return new Session({ ...this, identifier: this.identifier, credential });
+  }
+
+  withCachePolicy(cachePolicy: CachePolicy): Session {
+    return new Session({ ...this, identifier: this.identifier, cachePolicy });
+  }
+
+  withQueue(queue: RequestQueue): Session {
+    return new Session({ ...this, identifier: this.identifier, queue });
+  }
+
+  withAdapter(adapter: Adapter): Session {
+    return new Session({ ...this, identifier: this.identifier, adapter });
+  }
+
+  withValidator(validator: Validator): Session {
+    return new Session({ ...this, identifier: this.identifier, validator });
+  }
+
+  withRetrier(retrier: Retrier): Session {
+    return new Session({ ...this, identifier: this.identifier, retrier });
+  }
+
+  withMonitor(eventMonitor: EventMonitor): Session {
+    return new Session({ ...this, identifier: this.identifier, eventMonitor });
+  }
+
+  // -- the flow ---------------------------------------------------------------
+  //
+  // The methods below are what a "how does a request get built and sent" question
+  // is about, and they sit hundreds of lines under the header block.
+
+  /**
+   * Turn a convenience call into a URLRequest, hand it to the adapter chain and
+   * start the resulting task. The entry point of the whole flow.
+   */
+  async perform(url: string, method: string, body?: Uint8Array): Promise<URLSessionTask> {
+    const initial = buildURLRequest({
+      url,
+      method,
+      body,
+      headers: this.headers(),
+      timeout: this.timeoutIntervalForRequest,
+      cachePolicy: this.cachePolicy,
+    });
+    const adapted = await this.adapt(initial);
+    return this.didCreateURLRequest(adapted);
+  }
+
+  /**
+   * Every interceptor gets a chance to rewrite the request before it becomes a
+   * task. Runs in registration order, and a thrown error aborts the whole call.
+   */
+  private async adapt(request: URLRequest): Promise<URLRequest> {
+    let current = request;
+    for (const interceptor of this.interceptors) {
+      current = await interceptor.adapt(current, this);
+      this.eventMonitor.didAdaptRequest(current, interceptor.name);
+    }
+    if (this.credential) current = this.credential.apply(current);
+    return current;
+  }
+
+  /**
+   * The adapted request is final: build the task around it, register it and —
+   * unless the session was told to wait — resume it immediately.
+   */
+  didCreateURLRequest(request: URLRequest): URLSessionTask {
+    this.taskCounter += 1;
+    const identifier = this.taskCounter;
+    const created = this.task(request, identifier);
+    this.active.set(identifier, created);
+    this.eventMonitor.didCreateTask(created, request);
+    if (this.startRequestsImmediately) this.resume(created);
+    return created;
+  }
+
+  /**
+   * Build the URLSessionTask for a request. Split out from
+   * `didCreateURLRequest` because retries rebuild the task without going back
+   * through the adapter chain.
+   */
+  task(request: URLRequest, identifier: number): URLSessionTask {
+    const created = makeTask({
+      identifier,
+      request,
+      delegate: this.delegate,
+      allowsCellularAccess: this.allowsCellularAccess,
+      waitsForConnectivity: this.waitsForConnectivity,
+      resourceTimeout: this.timeoutIntervalForResource,
+    });
+    created.onComplete((response) => {
+      this.active.delete(identifier);
+      const verdict = this.validator.validate(response);
+      if (!verdict.ok && this.retrier.shouldRetry(response, verdict)) {
+        this.retry(request, identifier);
+        return;
+      }
+      this.eventMonitor.didCompleteTask(created, response);
+    });
+    return created;
+  }
+
+  /** Put a built task on the queue and start it. */
+  resume(task: URLSessionTask): void {
+    this.queue.enqueue(task, this.connectionLimit);
+    resumeTask(task);
+    this.eventMonitor.didResumeTask(task);
+  }
+
+  /** Rebuild and restart a task the retrier asked for. */
+  private retry(request: URLRequest, previousIdentifier: number): void {
+    this.taskCounter += 1;
+    const retried = this.task(request, this.taskCounter);
+    this.active.set(this.taskCounter, retried);
+    this.eventMonitor.didRetryTask(retried, previousIdentifier);
+    this.resume(retried);
+  }
+
+  /** Follow a redirect by adapting and re-performing the new location. */
+  async follow(response: { location: string }, original: URLRequest): Promise<URLSessionTask> {
+    const target = this.redirectHandler.resolve(response.location, original);
+    if (!target) throw new Error(`redirect to ${response.location} refused`);
+    return this.perform(target.url, target.method, target.body);
+  }
+}