Function loadIdentities

src/compute-engine/fungrim/loader.ts:672–805

(
  ce: IComputeEngine,
  options: FungrimLoadOptions = {}
)

 * selection skips the already-loaded rule ids. Shell declarations go into
 * the **current** scope — call `loadIdentities` before declaring user
 * symbols that could shadow shell heads.
 */
export function loadIdentities(
  ce: IComputeEngine,
  options: FungrimLoadOptions = {}
): FungrimLoadReport {
  const data = options.data ?? FUNGRIM_CORE;
  const topics = options.topics !== undefined ? new Set(options.topics) : null;
  const classes =
    options.classes !== undefined ? new Set<string>(options.classes) : null;
  const purposes =
    options.purposes !== undefined ? new Set<string>(options.purposes) : null;
  const solve = options.solve === true;

  let alreadyLoaded = loadedIdsByEngine.get(ce);
  if (alreadyLoaded === undefined) {
    alreadyLoaded = new Set();
    loadedIdsByEngine.set(ce, alreadyLoaded);
    // A checkpoint restore can roll back the declarations this loader
    // installed. The marker below would then still claim those ids are
    // present, so a replayed `loadIdentities()` would skip re-declaring rules
    // the engine no longer has. Clearing it is registered as a hook ON the
    // engine rather than being called from the checkpoint code, so the core
    // checkpoint path does not import — and therefore does not bundle — the
    // Fungrim payload. Registered once, on the first load for this engine.
    (ce._checkpointResetHooks ??= []).push(() => loadedIdsByEngine.delete(ce));
  }

  const report: FungrimLoadReport = {
    loaded: 0,
    byTarget: { simplify: 0, solve: 0, harmonization: 0 },
    byPurpose: { simplify: 0, transform: 0, expand: 0 },
    declared: [],
    skipped: [],
    compileLedger: { ...data.manifest.ledger },
  };

  // -- 1. Selection (each rule gets exactly one disposition)
  //
  //    `referenced` accumulates the shell heads of EVERY rule that passes the
  //    class/topic/purpose/solve filters — including rules already loaded on
  //    this engine. Shell declarations are scope-local (`ce.declare`), so a
  //    rule loaded inside a since-popped scope leaves its rule object alive in
  //    the engine-global rule store while its shell heads have gone out of
  //    scope. Re-running the shell pass over the already-loaded rules too
  //    (idempotent: `declare` skips names still defined) makes those heads
  //    usable again on reload after a `popScope` (SYM P3-8).
  const selected: CompiledFungrimRule[] = [];
  const referenced = new Set<string>();
  const collectReferenced = (r: CompiledFungrimRule): void => {
    collectSymbols(r.match, referenced);
    collectSymbols(r.replace, referenced);
    for (const g of r.guards) collectSymbols(guardJson(g), referenced);
  };
  for (const r of data.rules) {
    if (classes !== null && !classes.has(r.class)) {
      report.skipped.push({ id: r.id, reason: 'filtered-class' });
      continue;