@codedology/code-forge 0.15.4 → 0.16.0

package/src/ledger/tail.mjs

@@ -0,0 +1,89 @@
+import { open, readdir } from 'node:fs/promises';
+import path from 'node:path';
+import { ledgerPath } from './paths.mjs';
+
+/**
+ * A worker's project-wide ledger view. Concurrent callers share one serialized
+ * cursor; incomplete UTF-8/JSON bytes stay buffered until a newline arrives.
+ * @param {string} slug
+ * @returns {{read: () => Promise<Record<string, any>[]>}}
+ */
+export function createTailReader(slug) {
+  const file = ledgerPath(slug);
+  const dir = path.dirname(file);
+  const rotatedName = new RegExp(`^${slug}\\.(\\d+)\\.jsonl$`);
+  /** @type {Record<string, any>[]} */
+  let rows = [];
+  let files = '';
+  let inode = '';
+  let offset = 0;
+  /** @type {Buffer} */
+  let pending = Buffer.alloc(0);
+  let chain = Promise.resolve();
+
+  /** @param {Buffer} bytes */
+  function parse(bytes) {
+    const end = bytes.lastIndexOf(0x0a) + 1;
+    return {
+      rows: bytes.subarray(0, end).toString('utf8').split('\n').filter((line) => line.length > 0).map((line) => JSON.parse(line)),
+      pending: bytes.subarray(end),
+    };
+  }
+
+  /** @param {import('node:fs/promises').FileHandle} handle @param {number} start @param {number} size */
+  async function readBytes(handle, start, size) {
+    const bytes = Buffer.alloc(Math.max(0, size - start));
+    let n = 0;
+    while (n < bytes.length) {
+      const { bytesRead } = await handle.read(bytes, n, bytes.length - n, start + n);
+      if (bytesRead === 0) break;
+      n += bytesRead;
+    }
+    return bytes.subarray(0, n);
+  }
+
+  async function update() {
+    let names;
+    try { names = await readdir(dir); } catch (err) {
+      if (err.code !== 'ENOENT') throw err;
+      names = [];
+    }
+    const rotated = names.filter((name) => rotatedName.test(name))
+      .sort((a, b) => Number(rotatedName.exec(a)[1]) - Number(rotatedName.exec(b)[1]));
+    let handle;
+    try { handle = await open(file, 'r'); } catch (err) {
+      if (err.code !== 'ENOENT') throw err;
+    }
+    try {
+      const info = await handle?.stat();
+      const identity = info ? `${info.dev}:${info.ino}` : '';
+      const listing = JSON.stringify(rotated);
+      const reset = listing !== files || identity !== inode || (info?.size ?? 0) < offset;
+      let next = reset ? [] : rows;
+      if (reset) {
+        for (const name of rotated) {
+          const history = await open(path.join(dir, name), 'r');
+          try {
+            next = next.concat(parse(await readBytes(history, 0, (await history.stat()).size)).rows);
+          } finally { await history.close(); }
+        }
+      }
+      const start = reset ? 0 : offset;
+      const bytes = handle ? await readBytes(handle, start, info.size) : Buffer.alloc(0);
+      const parsed = parse(Buffer.concat([reset ? Buffer.alloc(0) : pending, bytes]));
+      // Commit only after every complete line parsed, so corruption cannot poison the cursor.
+      rows = next.concat(parsed.rows);
+      pending = parsed.pending;
+      offset = start + bytes.length;
+      files = listing;
+      inode = identity;
+      return rows.slice();
+    } finally { await handle?.close(); }
+  }
+
+  return { read() {
+    const result = chain.then(update);
+    chain = result.then(() => {}, () => {});
+    return result;
+  } };
+}

package/src/review/definitions.mjs

@@ -0,0 +1,170 @@
+/** Best-effort JavaScript/TypeScript definition context, with caller-supplied I/O. */
+import nodePath from 'node:path';
+import { isSecretLike } from './packet.mjs';
+
+const KEYWORDS = new Set(['if', 'for', 'while', 'switch', 'catch', 'function', 'return', 'typeof', 'new']);
+const EXTENSIONS = ['.mjs', '.js', '.ts', '.cjs', '.tsx'];
+const IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
+
+/** @typedef {{path: string, name: string, start: number, end: number, lines: string[]}} Definition */
+
+/** Comments and literals stay opaque; positions still refer to the original source.
+ * @param {string} text
+ */
+function tokensOf(text) {
+  const tokens = [];
+  let line = 1;
+  let offset = 0;
+  for (const match of text.matchAll(/\/\/[^\r\n]*|\/\*[\s\S]*?\*\/|`(?:\\[\s\S]|[^`\\])*`|'(?:\\[\s\S]|[^'\\])*'|"(?:\\[\s\S]|[^"\\])*"|\/(?:\\.|\[(?:\\.|[^\]\\])*\]|[^/\n\\])+\/[dgimsuvy]*|[A-Za-z_$][\w$]*|=>|[^\s]/g)) {
+    line += text.slice(offset, match.index).split('\n').length - 1;
+    offset = match.index;
+    if (!/^\/[/\*]/.test(match[0])) tokens.push({ value: match[0], line });
+  }
+  return tokens;
+}
+
+/** @param {string} rel */
+function safePath(rel) {
+  return !nodePath.posix.isAbsolute(rel) && !/[\\\x00-\x1f\x7f]/.test(rel) &&
+    !rel.split('/').some((part) => ['', '.', '..', '.git', '.code-forge'].includes(part)) && !isSecretLike(rel);
+}
+
+/** @param {ReturnType<typeof tokensOf>} tokens @param {number} start */
+function closing(tokens, start) {
+  const open = tokens[start]?.value;
+  const close = { '(': ')', '{': '}', '[': ']' }[open];
+  let depth = 0;
+  for (let i = start; i < tokens.length; i++) {
+    if (tokens[i].value === open) depth++;
+    if (tokens[i].value === close && --depth === 0) return i;
+  }
+  return -1;
+}
+
+/** @param {string} text @param {string} file @param {string} name @param {boolean} exported
+ * @returns {Definition | null}
+ */
+function declaration(text, file, name, exported) {
+  const tokens = tokensOf(text);
+  const lines = text.split(/\r?\n/);
+  for (let i = 0; i < tokens.length; i++) {
+    if (tokens[i].value !== name) continue;
+    const prev = tokens[i - 1]?.value;
+    const kind = ['function', 'const', 'class'].includes(prev) ? prev : null;
+    let start = i - 1;
+    while (start > 0 && ['async', 'default', 'export', 'declare'].includes(tokens[start - 1].value)) start--;
+    if (exported && !tokens.slice(start, i).some((token) => token.value === 'export')) continue;
+    if (kind === null && (exported || tokens[i + 1]?.value !== '(' || !['{', '}', ';', 'async', 'static', 'get', 'set'].includes(prev))) continue;
+    if (kind === null && tokens[closing(tokens, i + 1) + 1]?.value !== '{') continue;
+    if (kind === null) start = ['async', 'static', 'get', 'set'].includes(prev) ? i - 1 : i;
+    if (kind === 'const' && tokens[i + 1]?.value !== '=') continue;
+    let body = i + 1;
+    let end = -1;
+    for (; body < tokens.length; body++) {
+      const value = tokens[body].value;
+      if (value === '(' || value === '[') {
+        const last = closing(tokens, body);
+        if (last < 0) break;
+        body = last;
+      } else if (value === '{') {
+        end = closing(tokens, body);
+        break;
+      } else if (value === ';' || (kind === 'const' && tokens[body].line > tokens[i].line && tokens[body - 1]?.value !== '=')) {
+        end = value === ';' ? body : body - 1;
+        break;
+      }
+    }
+    if (end < 0) continue; // Malformed or incomplete declaration: keep looking.
+    const firstLine = tokens[start].line;
+    const lastLine = tokens[end].line;
+    const lastShown = Math.min(lastLine, firstLine + 39);
+    return { path: file, name, start: firstLine, end: lastShown,
+      lines: [...lines.slice(firstLine - 1, lastShown), ...(lastLine > lastShown ? ['…'] : [])] };
+  }
+  return null;
+}
+
+/** Parse local bindings, preserving aliases and namespace owners.
+ * @param {string} header
+ */
+function importsOf(header) {
+  const tokens = tokensOf(header);
+  const imports = new Map();
+  for (let i = 0; i < tokens.length; i++) {
+    if (tokens[i].value !== 'import' || ['(', '.'].includes(tokens[i + 1]?.value)) continue;
+    let end = i + 1;
+    while (end < tokens.length && !['from', ';', 'import'].includes(tokens[end].value)) end++;
+    if (tokens[end]?.value !== 'from') continue;
+    const source = tokens[end + 1]?.value;
+    if (!/^['"]\.\.?\//.test(source ?? '')) continue;
+    const specifier = source.slice(1, -1);
+    for (let j = i + 1; j < end; j++) {
+      const name = tokens[j].value;
+      if (!IDENTIFIER.test(name) || ['as', 'type'].includes(name)) continue;
+      if (tokens[j - 1]?.value === 'as') continue;
+      const alias = tokens[j + 1]?.value === 'as' ? tokens[j + 2]?.value : name;
+      imports.set(alias, { name, specifier, namespace: tokens[j - 1]?.value === '*' });
+    }
+    // `* as owner` has no ordinary imported name.
+    if (tokens[i + 1]?.value === '*' && tokens[i + 2]?.value === 'as') {
+      imports.set(tokens[i + 3]?.value, { name: '*', specifier, namespace: true });
+    }
+    i = end + 1;
+  }
+  return imports;
+}
+
+/**
+ * Calls on added unified-diff lines only. Missing or malformed source never aborts a packet.
+ * `readFile` takes an absolute path, as in relatedFiles; windows are current-file line ranges.
+ * @param {{path: string, diffLines: string[], header: string, io: {
+ *   repoRoot: string, readFile: (file: string) => string | null | Promise<string | null>,
+ *   windows?: Array<{start: number, end: number}>
+ * }}} opts
+ * @returns {Promise<Definition[]>}
+ */
+export async function findDefinitions({ path, diffLines, header, io }) {
+  const found = [];
+  if (!safePath(path) || !EXTENSIONS.includes(nodePath.posix.extname(path).toLowerCase())) return found;
+  try {
+    const cache = new Map();
+    const read = async (rel) => {
+      if (!safePath(rel)) return null;
+      if (!cache.has(rel)) {
+        try { cache.set(rel, await io.readFile(nodePath.resolve(io.repoRoot, rel))); }
+        catch { cache.set(rel, null); }
+      }
+      return cache.get(rel);
+    };
+    const text = await read(path);
+    if (typeof text !== 'string') return found;
+    const added = tokensOf(diffLines.filter((line) => line.startsWith('+') && !line.startsWith('+++')).map((line) => line.slice(1)).join('\n'));
+    const defined = new Set(added.filter((token, i) => ['function', 'const', 'class', 'let', 'var'].includes(added[i - 1]?.value) ||
+      (added[i + 1]?.value === '(' && added[closing(added, i + 1) + 1]?.value === '{')).map((token) => token.value));
+    const imports = importsOf(header);
+    const seen = new Set();
+    for (let i = 0; i < added.length; i++) {
+      const name = added[i].value;
+      if (!IDENTIFIER.test(name) || added[i + 1]?.value !== '(' || KEYWORDS.has(name) || defined.has(name)) continue;
+      const receiver = added[i - 1]?.value === '.' ? added[i - 2]?.value : null;
+      const binding = imports.get(receiver ?? name);
+      let definition = declaration(text, path, name, false);
+      if (definition && io.windows?.some((w) => w.start <= definition.start && definition.end <= w.end)) definition = null;
+      if (!definition && binding && (!receiver || binding.namespace)) {
+        const target = nodePath.posix.normalize(nodePath.posix.join(nodePath.posix.dirname(path), binding.specifier));
+        if (!safePath(target)) continue;
+        const candidates = nodePath.posix.extname(target) ? [target] : [target, ...EXTENSIONS.map((ext) => target + ext), ...EXTENSIONS.map((ext) => `${target}/index${ext}`)];
+        for (const candidate of candidates) {
+          const imported = await read(candidate);
+          if (typeof imported !== 'string') continue;
+          definition = declaration(imported, candidate, binding.namespace ? name : binding.name, true);
+          break;
+        }
+      }
+      if (!definition) continue;
+      const key = `${definition.path}:${definition.start}`;
+      if (!seen.has(key)) { seen.add(key); found.push(definition); }
+    }
+  } catch { /* Partial context is preferable to aborting review on unparseable source. */ }
+  return found;
+}

package/src/review/fixloop.mjs

@@ -19,7 +19,7 @@
  *     ≥ `escalation.warning_threshold` (2) warnings or any `critical` — climb at once (rule 2c,
  *     B34: `trigger: review_warnings`); `warn_rounds_at_level` counts them and resets on a climb.
  *  5. Cap: `review.max_rounds_per_file` (4) reached with an open finding ⇒ the L3 patch rung
- *     (rule 6; once per block — shared with rule 5's ceiling), whose `patch_check` round is
+ *     (rule 6; once per file — shared with rule 5's ceiling), whose `patch_check` round is
  *     OUTSIDE the cap. The rung is also rule 5: rule 2/2b at the running ceiling (L2 — L3 is never
  *     a coding level, R1) takes it, so for an L2 block the rung IS the +1 at round 2. After the
  *     patch the block continues at L2 (§3.6, Fable ruling A): `l3_rung_used = true`,
@@ -127,7 +127,7 @@ import { afterSchemaMiss, logSecondLevelMiss, packetHash } from './schema-fallba
  * @property {string[]} [finding_history] - claim/evidence keys from earlier rounds of this file.
  * @property {string[]} [finding_ids] - ids seen in earlier rounds, including closed findings.
  * @property {string | null} reviewed_content - the content the last counted round reviewed.
- * @property {boolean} l3_rung_used - the block's L3 rung (rule 5 or 6) was used — once per block.
+ * @property {boolean} l3_rung_used - the file's L3 rung (rule 5 or 6) was used — once per file.
  * @property {'open' | 'complete' | 'stopped'} status
  * @property {string} [stop_content_hash] - bytes reviewed by a stop (absent in legacy states).
  * @property {string} [stop_lens] - the lens whose packet stopped before a round.
@@ -146,7 +146,7 @@ import { afterSchemaMiss, logSecondLevelMiss, packetHash } from './schema-fallba
  * @property {import('./triage.mjs').JevAsk} [jev]
  * @property {import('./triage.mjs').RuleFn} [rule]
  * @property {(row: Record<string, any>) => Promise<unknown>} [writeRow]
- * @property {(req: {file: string, round: number, level: string, open: Finding[], l3_patch: boolean}) => Promise<unknown>} [fix] - a fresh coder session at `level`; `l3_patch` = the block's L3 patch is in the tree (§3.6).
+ * @property {(req: {file: string, round: number, level: string, open: Finding[], l3_patch: boolean}) => Promise<unknown>} [fix] - a fresh coder session at `level`; `l3_patch` = the file's L3 patch is in the tree (§3.6).
  * @property {(req: {file: string, level: 'L3', open: Finding[]}) => Promise<unknown>} [patch] - the L3 patch rung (≤ 80 lines, owned files only).
  * @property {string | null} [base] - the block base (`recheck_scope: file`, and the B56 moved-code diff).
  * @property {ReadonlyArray<string>} [peers] - B56: the block's other changed files (moved-code hints).
@@ -582,7 +582,7 @@ async function recheckSession(packet, deps, open) {
 function decideNext(state, openBefore, s, kind, closedIds) {
   if (state.open.length === 0) return { action: 'complete' };
   if (kind === 'patch_check') {
-    // the block's one rung is spent: a patch that closed no old finding stops FIRST — even when
+    // the file's one rung is spent: a patch that closed no old finding stops FIRST — even when
     // the rung was taken at the cap — then the cap; else (B73: ≥ 1 old id closed is progress,
     // whatever new findings its fix hunks brought) the block continues at L2: a fix, no stall
     if (closedIds === 0) return { action: 'stop', reason: 'l3_patch_exhausted', trigger: 'review_stall' };

package/src/review/gate-check.mjs

@@ -908,15 +908,31 @@ export function repoRelativePath(raw) {
 /**
  * The block's file set (§4.1): changed tracked files since `base` (deletions included, hashed
  * `DELETED_HASH`) ∪ untracked files, filtered to `owned` (`matchOwned`, default the registry's `ownsFile` with `ownedKinds`: an exact entry owns its path and the paths below it unless recorded as a regular file, B57), each with its content hash.
- * Every path goes through `repoRelativePath`.
- * @param {{repoRoot: string, base: string, owned: string[], ownedKinds?: Record<string, string>, matchOwned?: (file: string) => boolean, changed?: string[]}} opts
+ * Every path goes through `repoRelativePath`; files deleted now get a git base-existence check
+ * and, if absent at base, a history check. Omit them only when git confirms commits since base
+ * touched them in this workspace. Failed or empty history checks keep the deletion for review.
+ * Other files need no extra git call; deleted files need at most two.
+ * @param {{repoRoot: string, base: string, owned: string[], ownedKinds?: Record<string, string>, matchOwned?: (file: string) => boolean, changed?: string[], gitRun?: (argv: string[], opts: Parameters<typeof exec>[1]) => Promise<{result: 'ok' | 'failed', stdout?: string, timedOut?: boolean}>}} opts
  *   `changed`: the tree's changed files when the caller already listed them ({@link changedFiles}).
+ *   `gitRun`: the base-existence and history runner (defaults to {@link exec}).
  * @returns {Promise<Array<{file: string, content_hash: string}>>}
  */
-export async function blockFileSet({ repoRoot, base, owned, ownedKinds, matchOwned, changed }) {
+export async function blockFileSet({ repoRoot, base, owned, ownedKinds, matchOwned, changed, gitRun = exec }) {
   const all = changed ?? (await changedFiles({ repoRoot, base }));
   const isOwned = matchOwned ?? ((/** @type {string} */ f) => ownsFile(owned, f, ownedKinds));
-  return all.filter((f) => isOwned(f)).map((file) => ({ file, content_hash: currentHash(repoRoot, file) }));
+  const files = [];
+  for (const file of all.filter((f) => isOwned(f))) {
+    const content_hash = currentHash(repoRoot, file);
+    if (content_hash === DELETED_HASH) {
+      const atBase = await gitRun(['git', 'ls-tree', '--name-only', '-z', base, '--', file], { cwd: repoRoot, env: gitChildEnv(), timeoutMs: 30000 });
+      if (atBase.result === 'ok' && atBase.stdout === '') {
+        const history = await gitRun(['git', 'log', '--format=%H', `${base}..HEAD`, '--', file], { cwd: repoRoot, env: gitChildEnv(), timeoutMs: 30000 });
+        if (history.result === 'ok' && typeof history.stdout === 'string' && history.stdout.trim() !== '') continue;
+      }
+    }
+    files.push({ file, content_hash });
+  }
+  return files;
 }
 
 /** Safety check for npm locks excluded from model review; other formats are not parsed.

package/src/review/packet.mjs

@@ -11,7 +11,8 @@
  *   ## facts           the facts-sheet excerpt
  *   ## context         the current file (whole, or hunk windows — `context.mjs`)
  *   ## related files (not shown)  optional related paths only, dropped first over budget
- *   ## paired          optional paired-file names and summary (B97), dropped next over budget
+ *   ## definitions     optional called-symbol bodies, dropped last first after related paths
+ *   ## paired          optional paired-file names and summary (B97), dropped after definitions
  *   ## moved code      only when code moved to/from another file of the block (`moved.mjs`, B56)
  *   ## diff            `file:`, the `hunks:` list the reviewer must echo, then the diff
  *
@@ -22,7 +23,7 @@
  * Budget (§4.3): `review.budgets.full_in` (`quick_in` for the quick lens), in tokens estimated as
  * bytes / 4. A diff that alone exceeds it ⇒ `split_required` (a Markdown file is then reviewed
  * section by section — `sections.mjs`, B54). Otherwise over budget ⇒ the context shrinks to
- * ± `min_context_lines` (`minimal`) after dropping related files, then paired, then the digest is trimmed from the end; the diff is
+ * ± `min_context_lines` (`minimal`) after dropping related files, definitions, then paired, then the digest is trimmed from the end; the diff is
  * never cut. The `## moved code` section (B56) is part of that measure: it is counted in the diff-only
  * size (`diffOnlyTokens`, `split_required`) and never trimmed.
  *
@@ -39,6 +40,7 @@ import { fileURLToPath } from 'node:url';
 import { exec } from '../util/exec.mjs';
 import { assertInsideRoot, assertRowPath, gitChildEnv, readRegularFileNoFollow, WorkerError } from '../worker/ticket.mjs';
 import { buildContext, parseDiff, splitLines } from './context.mjs';
+import { findDefinitions } from './definitions.mjs';
 import { relatedFiles } from './related.mjs';
 
 export const LENSES = Object.freeze(['quick', 'full', 'recheck', 'A', 'B', 'judge']);
@@ -191,15 +193,19 @@ export function assertPacketPath(repoRoot, file) {
  * @property {number} plusCount
  * @property {number} minusCount
  * @property {string[]} [related] - related file names, never their content.
+ * @property {import('./definitions.mjs').Definition[]} [definitions] - called-symbol bodies.
  */
 
 /**
  * Read one file's diff against `base` (§4.1).
- * @param {{repoRoot: string, file: string, base?: string | null}} opts
+ * @param {{repoRoot: string, file: string, base?: string | null, io?: {
+ *   readFile?: (file: string) => string | null | Promise<string | null>,
+ *   listFiles?: (repoRoot: string) => string[] | Promise<string[]>
+ * }}} opts
  * @returns {Promise<FileDiff>}
  * @throws {PacketError} `bad-path`, `git`
  */
-export async function readFileDiff({ repoRoot, file, base }) {
+export async function readFileDiff({ repoRoot, file, base, io }) {
   const rel = assertPacketPath(repoRoot, file);
   if (isSecretLike(rel)) throw new PacketError('bad-path', 'secret-like path');
   const ref = base ?? 'HEAD';
@@ -224,20 +230,30 @@ export async function readFileDiff({ repoRoot, file, base }) {
       : ['git', 'diff', '--no-color', '--no-ext-diff', ref, '--', rel];
   const res = await exec(argv, { cwd: repoRoot, env, timeoutMs: GIT_TIMEOUT_MS, ...(kind === 'new' ? { okExitCodes: [0, 1] } : {}) });
   if (res.result !== 'ok') throw new PacketError('git', `git diff failed for ${rel} (exit ${res.code})`);
-  const content = onDisk ? readRepoText(repoRoot, rel) : null;
+  const content = onDisk ? await (io?.readFile ? io.readFile(full) : readRepoText(repoRoot, rel)) : null;
+  const readFile = (full) => {
+    const candidate = path.relative(repoRoot, full).split(path.sep).join('/');
+    if (isSecretLike(candidate)) return null;
+    if (candidate === rel) return content;
+    const safe = assertPacketPath(repoRoot, candidate);
+    return io?.readFile ? io.readFile(path.join(repoRoot, safe)) : readRepoText(repoRoot, safe);
+  };
   const related = res.stdout.trim().length === 0 ? [] : await relatedFiles({
     repoRoot, file: rel,
     listFiles: async () => {
+      if (io?.listFiles) return io.listFiles(repoRoot);
       const tracked = await exec(['git', 'ls-files', '-z'], { cwd: repoRoot, env, timeoutMs: GIT_TIMEOUT_MS });
       return tracked.result === 'ok' ? tracked.stdout.split('\0').filter(Boolean) : [];
     },
-    readFile: (full) => {
-      const candidate = path.relative(repoRoot, full).split(path.sep).join('/');
-      if (isSecretLike(candidate)) return null;
-      return readRepoText(repoRoot, assertPacketPath(repoRoot, candidate));
-    },
+    readFile,
+  });
+  const parsed = parseDiff(res.stdout);
+  const definitions = content === null || res.stdout.trim().length === 0 ? [] : await findDefinitions({
+    path: rel, diffLines: res.stdout.split('\n'),
+    header: splitLines(content).slice(0, importHeaderEnd(rel, content)).join('\n'),
+    io: { repoRoot, readFile, windows: parsed.hunks.map((h) => ({ start: h.newStart, end: h.newStart + h.newLines - 1 })) },
   });
-  return { file: rel, kind, diffText: res.stdout, content, related, ...parseDiff(res.stdout) };
+  return { file: rel, kind, diffText: res.stdout, content, related, definitions, ...parsed };
 }
 
 /**
@@ -274,22 +290,33 @@ export function assemblePacket({ diff, lens, rulesDigest = '', factsExcerpt = ''
   let pairedSection = boundedPaired(paired, budgetFor(cfg, 'full_in'));
   const names = ['quick', 'full'].includes(lens) ? (diff.related ?? []) : [];
   let relatedSection = names.length > 0 ? `## related files (not shown)\n${names.join('\n')}` : '';
-  let text = render(lensText, digest, factsExcerpt, ctx.text, diffSection, moved, pairedSection, relatedSection);
+  // Optional sections are dropped before context shrinks. Choose the final windows before
+  // excluding definitions already shown there, so shrinking cannot lose a called body.
+  if (estimateTokens(render(lensText, digest, factsExcerpt, ctx.text, diffSection, moved)) > limit) {
+    relatedSection = '';
+    pairedSection = '';
+    ctx = packetContext({ file: diff.file, content: diff.content, hunks: diff.hunks, cfg, mode: 'minimal' });
+  }
+  const definitions = lens === 'judge' ? [] : (diff.definitions ?? []).filter((definition) => definition.path !== diff.file ||
+    !ctx.windows.some((w) => w.start <= definition.start && definition.end <= w.end));
+  while (definitions.length > 0 && estimateTokens(definitionsSection(definitions)) > Math.floor(budgetFor(cfg, 'full_in') / 8)) definitions.pop();
+  const renderPacket = () => render(lensText, digest, factsExcerpt, ctx.text, diffSection, moved, pairedSection, relatedSection, definitionsSection(definitions));
+  let text = renderPacket();
   if (estimateTokens(text) > limit && relatedSection.length > 0) {
     relatedSection = '';
-    text = render(lensText, digest, factsExcerpt, ctx.text, diffSection, moved, pairedSection);
+    text = renderPacket();
+  }
+  while (estimateTokens(text) > limit && definitions.length > 0) {
+    definitions.pop();
+    text = renderPacket();
   }
   if (estimateTokens(text) > limit && pairedSection.length > 0) {
     pairedSection = '';
-    text = render(lensText, digest, factsExcerpt, ctx.text, diffSection, moved);
-  }
-  if (estimateTokens(text) > limit) {
-    ctx = packetContext({ file: diff.file, content: diff.content, hunks: diff.hunks, cfg, mode: 'minimal' });
-    text = render(lensText, digest, factsExcerpt, ctx.text, diffSection, moved);
+    text = renderPacket();
   }
   while (estimateTokens(text) > limit && digest.length > 0) {
     digest = digest.slice(0, -1);
-    text = render(lensText, digest, factsExcerpt, ctx.text, diffSection, moved);
+    text = renderPacket();
   }
   const tokensIn = estimateTokens(text);
   return { status: 'ok', text, hunkHeaders, contextMode: ctx.mode, contextLines: ctx.lineCount, digestLines: digest.length, tokensIn, budget: limit, overBudget: tokensIn > limit };
@@ -342,6 +369,15 @@ function boundedPaired(paired, fullIn) {
   return body.length > 0 ? heading + body.trimEnd() : '';
 }
 
+/** @param {import('./definitions.mjs').Definition[]} definitions @returns {string} */
+function definitionsSection(definitions) {
+  if (definitions.length === 0) return '';
+  return ['## definitions (called by changed lines)', ...definitions.flatMap((definition) => [
+    `### ${definition.path}:${definition.start}-${definition.end}`,
+    ...definition.lines.map((line, i) => line === '…' && i + definition.start > definition.end ? line : `${definition.start + i}| ${line}`),
+  ])].join('\n') + '\n';
+}
+
 /**
  * The tokens of the diff-only packet (lens + moved code + diff, no digest, facts or context): what
  * `assemblePacket` holds against the budget before it says `split_required`. Pass the SAME `moved`
@@ -371,8 +407,9 @@ function diffSectionOf(diff) {
  * @param {string} diffSection @param {string} [moved] - the `## moved code` section (heading included), '' for none.
  * @param {string} [paired] - the bounded `## paired` section (heading included).
  * @param {string} [related] - the names-only related files section (heading included).
+ * @param {string} [definitions] - the bounded called-symbol definitions section.
  */
-function render(lensText, digest, facts, context, diffSection, moved = '', paired = '', related = '') {
+function render(lensText, digest, facts, context, diffSection, moved = '', paired = '', related = '', definitions = '') {
   return [
     '# code-forge review packet',
     '## lens',
@@ -384,6 +421,7 @@ function render(lensText, digest, facts, context, diffSection, moved = '', paire
     '## context',
     context.length > 0 ? context : '(none)',
     ...(related.length > 0 ? [related] : []),
+    ...(definitions.length > 0 ? [definitions.trimEnd()] : []),
     ...(paired.length > 0 ? [paired] : []),
     ...(moved.length > 0 ? [moved] : []),
     '## diff',