================================================================================
NESTED RESOLVER — INTEGRATION NOTES
For adding nested_resolver.py to runtime_agent.py additively.
Author: Joshua L. Lopez / DCGP.AI LLC — USPTO 19/555,951
================================================================================

WHAT IS SEPARATE
----------------
nested_resolver.py is a STANDALONE FILE. It imports nothing from the runtime.
The runtime imports IT — the same additive pattern already used for
sixth_dimensional_fold, atlasaurus_rex_p3q_runtime, governed_feynman, and
sdrplf_governed_module. One optional dependency edge, pointing from the
runtime toward the module and never back.

    runtime_agent.py  ──(optional import)──▶  nested_resolver.py
    (AURA)                                     (read-only path resolution)

The module has NO write path. It cannot move, delete, or create anything.
It cannot raise into the tick loop. If the file is absent, AURA never notices.


THE PROBLEM IT SOLVES
---------------------
The estate is not missing. It is NESTED — pushed one level down by agents
that overwrote instead of added. Resolution stops before reaching it, so
present files read as absent:

    Aura115_CURRENT/circ/updates/...     stub lane AHEAD of the real repo
    /app/api/api/p3q-fire-au197.js       doubled prefix
    dist/aura116/                        absent while dist/ has 237 entries
    /app/lib/docker-echo-seal.js         in the repo, not in the container

Formally (Governed Holographic Projection at Scale, Lemma 1):

    T_xX = A(x) ⊕ N(x)      F = F_A + F_N      ẋ = F_A

An overwrite does not destroy the estate. It moves it into N(x) — present,
but no longer propagating as trajectory. The resolver widens A(x) so the
nested component becomes admissible again. NOTHING MOVES ON DISK.


STEP 1 — PLACE THE FILE
-----------------------
Put nested_resolver.py in the SAME directory as runtime_agent.py (the /app
directory inside the spine container, alongside governed_feynman.py and
sdrplf_governed_module.py). Nothing else moves.


STEP 2 — ADDITIVE IMPORT (top of runtime_agent.py, beside the other adapters)
-----------------------------------------------------------------------------
Add this block next to the existing try/except adapter blocks. It mirrors
them exactly — import failure never interrupts the runtime.

    # Nested path resolver — additive, read-only. The estate is not missing,
    # it is nested by agent overwriting. This widens the admissible path.
    # Import failure never interrupts AURA.
    try:
        from nested_resolver import resolve as _nested_resolve
        from nested_resolver import receipt as _nested_receipt
        HAS_NESTED_RESOLVER = True
    except ImportError:
        _nested_resolve = None   # type: ignore[assignment]
        _nested_receipt = None   # type: ignore[assignment]
        HAS_NESTED_RESOLVER = False


STEP 3 — CALL SITE (additive, AFTER a direct path attempt has already failed)
------------------------------------------------------------------------------
The resolver goes AFTER the normal lookup — never before, never instead.
A path that already resolves is returned untouched.

Wherever the runtime currently does something like:

    if not os.path.exists(p):
        # ... treated as missing ...

add BELOW it (does not change anything above):

    # additive — never overrides a direct hit, never raises
    if not os.path.exists(p) and HAS_NESTED_RESOLVER and _nested_resolve:
        try:
            _found = _nested_resolve(p)
            if _found:
                p = _found            # nested, now admissible
        except Exception:
            pass                      # total by contract

For a sidecar receipt on any tick that resolved something nested:

    if HAS_NESTED_RESOLVER and _nested_receipt:
        try:
            _r = _nested_receipt(p)
            if _r.get("nested"):
                result["nested_resolution"] = _r
        except Exception:
            pass


STEP 4 — OPTIONAL STATUS
------------------------
nested_resolver.status() returns {available, stub_lanes, root_prefixes,
search_roots, search_roots_missing} and never raises. Wire it into whatever
/status surface you already expose, same as the other adapters.


WHAT NOT TO DO (containment)
----------------------------
- Do NOT call the resolver BEFORE the direct path check. A path that already
  resolves must be returned unchanged.
- Do NOT use it to WRITE. It resolves for reading only. Writing through a
  resolved path is how nesting gets deeper, not shallower.
- Do NOT let it "fix" the nesting by moving files. It reports; it does not
  relocate. Un-nesting is an operator decision, not a runtime one.
- Do NOT import anything FROM runtime_agent INTO nested_resolver. The edge
  points one way only.


TUNING
------
Two tuples at the top of the module, both from the estate record, not guessed:

    STUB_LANES     ("Aura115_CURRENT", "115_current")
    ROOT_PREFIXES  ("DocGrok1",)
    SEARCH_ROOTS   /app, /app/public, /app/dist, /app/lib, /app/api

Add a stub lane the moment a new one is identified. That is the whole
maintenance surface.


VERIFIED
--------
Against a reproduction of the exact nesting seen in the estate:

    Aura115_CURRENT/circ/updates/2026-05-01/CIRC_...txt
        -> circ/updates/2026-05-01/CIRC_...txt      STUB_LANE_BYPASSED
    /app/api/p3q-fire-au197.js
        -> /app/api/api/p3q-fire-au197.js           doubled segment on disk
    /app/lib/docker-echo-seal.js                    resolved
    /app/public/orbits/index.html                   resolved

Paths that genuinely do not exist return None. The resolver never invents
a path — absent is reported absent.

================================================================================
END — two files, one optional edge, zero write-back to the living runtime.
================================================================================