Egonex-AI/Understand-Anything · error

Unresolved incremental symbol loss; baseline not advanced

Error message

Unresolved incremental symbol loss; baseline not advanced

What it means

Before saving the merged incremental graph, finalize-incremental.mjs runs validateIncrementalSymbols to re-verify that the graph being saved contains no lost symbols relative to the previous graph and the patch. If the symbol report is not ok, the save is aborted and the baseline is not advanced — a deliberate safety ordering so a lossy merge never silently replaces knowledge-graph.json.

Source

Thrown at understand-anything-plugin/skills/understand/finalize-incremental.mjs:477

    const graph = {
      ...previousGraph,
      version: previousGraph.version ?? '1.0.0',
      project: {
        ...projectMetadata(previousGraph.project, plan, scan),
        analyzedAt: now,
      },
      nodes: assembled.nodes,
      edges: assembled.edges,
      layers: assignLayers(rawLayers, assembled.nodes, assembled.edges),
      tour: normalizeTour(rawTour, nodeIds, pathIndex),
    };

    // Ordering is intentional: a failed graph save must never advance the
    // structural baseline and hide the failed update from the next run.
    // Recheck the actual graph being saved, never trust a prior merge report.
    const symbolReport = await validateIncrementalSymbols(projectRoot, { graph, intermediateDir });
    process.stderr.write(`${formatSymbolReport(symbolReport)}\n`);
    if (!symbolReport.ok) throw new Error('Unresolved incremental symbol loss; baseline not advanced');
    atomicWriteJson(graphPath, graph);
  }

  patchFingerprints(uaDir, plan, patch);
  advanceMeta(uaDir, plan, scan.totalFiles);
  process.stdout.write(
    `Incremental update finalized: ${plan.action}; analyzedFiles=${scan.totalFiles}\n`,
  );
}

function isCliEntry() {
  if (!process.argv[1]) return false;
  try {
    return realpathSync(fileURLToPath(import.meta.url)) === realpathSync(process.argv[1]);
  } catch {
    return false;
  }
}

View on GitHub (pinned to 07edf82a04)

Solutions

1. Inspect .ua/intermediate/incremental-symbol-report.json (and stderr report) to see which symbols/paths were lost, then re-run the analysis for the affected files so the assembled graph includes them.
2. Delete the stale .ua/intermediate/ artifacts and re-run the incremental pipeline from prepare-incremental.mjs so the merge is redone against a consistent baseline.
3. If the baseline itself is suspect, run the full /understand pipeline instead of the incremental path to rebuild knowledge-graph.json from scratch.
4. Check the fingerprint patch matches the current plan commits (finalize also validates this) and that no concurrent finalize is running against the same .ua/ directory.

// after assembling, before finalizing, check the report yourself
import { existsSync, readFileSync } from 'node:fs';
const reportPath = join(uaDir, 'intermediate', 'incremental-symbol-report.json');
if (existsSync(reportPath)) {
  const report = JSON.parse(readFileSync(reportPath, 'utf-8'));
  if (report && report.ok === false) {
    console.error('Symbol loss detected:', report.missing ?? report);
  }
}

try {
  await finalizeIncremental(projectRoot);
} catch (err) {
  if (String(err.message).includes('Unresolved incremental symbol loss')) {
    const report = JSON.parse(readFileSync(join(uaDir, 'intermediate', 'incremental-symbol-report.json'), 'utf-8'));
    console.error('Re-analyze affected files:', report);
  } else throw err;
}

When it happens

Trigger: Running finalize-incremental.mjs where the assembled graph (merged with previous nodes/edges) drops symbols: re-analyzed files lose whole-file or symbol nodes that the previous graph and fingerprint patch still reference, e.g. an agent returned partial output for a changed file, or normalization dropped nodes with missing/invalid ids.

Common situations: An LLM analysis pass returned truncated/incomplete node lists for re-analyzed files; a bug or schema change in the assembling agent's output caused nodes to be dropped during normalizeAssembled; concurrency — the baseline advanced while another process modified .ua/ files, so the patch and graph disagree.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• Architecture update requires layers.json; baseline not advan
• Architecture update requires tour.json; baseline not advance
• fingerprints.json existed and was non-empty but loaded as {}
• Benchmark stage failed: ${stage.name}
• Fingerprint patch does not match the incremental plan commit

AI-assisted analysis of Egonex-AI/Understand-Anything@07edf82a04 (2026-09-07). Data as JSON: /api/errors/5cd68862b18437bb. Report an issue: GitHub.