ambitgraph 0.2.0__tar.gz → 0.3.0__tar.gz

{ambitgraph-0.2.0/ambitgraph.egg-info → ambitgraph-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ambitgraph
-Version: 0.2.0
+Version: 0.3.0
 Summary: Read-only codebase scan: reusable units, families, roles, ownership candidates, duplication.
 Author: AmbitGraph
 License: Proprietary

{ambitgraph-0.2.0 → ambitgraph-0.3.0}/ambit_map/graph.py

@@ -49,6 +49,19 @@ from . import matched as mtc
 # 3.1 Constants
 # ---------------------------------------------------------------------------
 
+# R4.5: precomputed once, a set UNION that tolerates reg.PY_LANGS/
+# reg.JS_LANGS being either tuples (today's committed type) or frozensets
+# (JUDGES-DIGEST.txt LENS 1, C1's named "declared future shape" -- the
+# adversarial finding that KIND_READER_LANGS is already frozenset-valued,
+# so the natural next step for these two groupings is the same). The
+# branch below used to read `reg.PY_LANGS + reg.JS_LANGS`, tuple
+# CONCATENATION: the instant either grouping becomes a frozenset that
+# expression TypeErrors ("can only concatenate tuple (not frozenset) to
+# tuple") in this exact no-edges unit-view render branch -- one the
+# codelib byte-golden (an engine-side export) can never reach. `in a | b`
+# never cares which collection type either operand is.
+_PY_OR_JS_LANGS = frozenset(reg.PY_LANGS) | frozenset(reg.JS_LANGS)
+
 N_CAP_DEFAULT = 28
 N_CAP_MIN = 8
 N_CAP_MAX = 80
@@ -1504,11 +1517,23 @@ def _quarantine_note(drawn):
         # read") is false for a cross-root HELD disclosure -- the scan
         # read the candidate, under a root this file does not sit in.
         # Branch on the ref's own reason, never on a guess.
-        if r.reason == "cross_root_import_held":
-            out += ob.note(reg.cross_root_import_held_sentence(
-                A=drawn["id"], raw=r.raw))
-        else:
-            out += ob.note(reg.sentence("unresolved", A=drawn["id"], raw=r.raw))
+        #
+        # Java W1 (2026-09-02, DESIGN.md D3): two more machine-token
+        # branches, same law -- "wildcard_import" and "importer_root_
+        # underivable" are both false under the generic "never read"
+        # sentence too (see registry.py's own comment on the two
+        # sentences below for why). cross_root_import_held's own sentence
+        # is reused byte-identical for a java-sourced cross-root hold --
+        # its text names no language ("a matching file exists, but only
+        # under a root this file does not sit in"), so it needs no java
+        # variant. The token-to-sentence dispatch itself lives in
+        # reg.unresolved_reason_sentence, shared with unitpage.py's
+        # connections block -- one origin, so a token can never render
+        # here and fall through to the generic caption there.
+        sent = reg.unresolved_reason_sentence(r.reason, A=drawn["id"], raw=r.raw)
+        if not sent:
+            sent = reg.sentence("unresolved", A=drawn["id"], raw=r.raw)
+        out += ob.note(sent)
     cut_phrase = reg.count_phrase(len(shown), total, reg.NOUN_UNRESOLVED)
     if cut_phrase:
         out += ob.note(reg.esc(cut_phrase))
@@ -1717,7 +1742,7 @@ def _canvas_block(model, drawn, n_cap, pinned, dialects):
     if not merged:
         body = ob.note(_library_view_link(drawn))
         body += ob.note(reg.esc(reg.GRAPH_NO_EDGES.format(seed=_seed_display(drawn))))
-        if drawn["state"] == "unit" and drawn["unit"].lang in (reg.PY_LANGS + reg.JS_LANGS):
+        if drawn["state"] == "unit" and drawn["unit"].lang in _PY_OR_JS_LANGS:
             blind = lib._combined_blind(model.coverage)
             found = lib._find_blind(blind, reg.CALL_BLIND_MATCH)
             text = found if found else reg.CALL_BLIND_NO_REASON

ambitgraph-0.3.0/ambit_map/langmirror.py

@@ -0,0 +1,243 @@
+"""ambit_map/langmirror.py -- the product-side ASSERTED MIRROR of
+ambitgraph/langs.py's declared language vocabulary (R4-DESIGN.md, v2;
+CENSUS.md).
+
+ONE file replacing five scatterings: ambit_map/orchestrate.py's admission
+copy + MAPLLM_EXTRA_INCLUDE_EXT, ambit_map/registry.py's JS_LANGS/PY_LANGS/
+ROUTEDNESS_LANGS, ambit_map/paths.py's KIND_READER_LANGS/_GRAMMAR_EXTS, and
+ambit_map/library.py's inline blind-filter regex vocabulary. Every value
+below is UNCHANGED from what its scattered original held -- this module
+only gives them one address; see each field's own comment for its prior
+location, and the module-docstring note below for R4's "no member
+deletion" ruling.
+
+THE WALL (tests/test_import_boundaries.py's violations helper, the
+ambit_map stdlib-only rule inside rule_message, and that file's own
+test_self_test_map_importing_contracts_is_caught test): ambit_map may
+NEVER import ambitgraph, not even ambit_contracts, the house's own
+shared-stdlib-only package -- there was never a choice of a third shared
+package; the wall forecloses it outright (R4-DESIGN.md v2, "The
+architecture ruling"). So this module cannot import ambitgraph/
+langs.py and DERIVE its values the way ambitgraph/symbols.py, edges.py,
+config.py and codelib.py now derive theirs from langs.py -- it is instead
+an ASSERTED COPY: every value below is retyped by hand, checked against
+langs.py's own values ONLY by a TEST (tests/test_langs_mirror_diff.py),
+NEVER by any import at runtime. This is not a new exception -- the
+identical both-sides-import shape is already live at
+tests/test_map_serve.py's own
+test_engine_include_ext_is_duplicated_by_value_and_never_drifts test
+(ENGINE_DEFAULT_INCLUDE_EXT vs ScanConfig().include_ext), which this
+module's own admission field below continues rather than replaces.
+
+Unlike ambitgraph/langs.py (which imports `re` and `dataclasses` for its
+own LangSpec declarations), this module is a pure, dependency-free LEAF:
+no imports at all, not even stdlib (every value below is a literal). Every
+consumer inside this package (orchestrate.py, paths.py, registry.py,
+library.py) imports IT; it imports NONE of them, so no existing consumer
+of registry.py/paths.py/library.py/orchestrate.py risks a cycle by their
+now also depending, transitively, on this module.
+
+NO MEMBER DELETION (R4-DESIGN.md v2, ruling 1, refuting the v1 draft's
+"delete the dead members" plan twice over -- JUDGES-DIGEST.txt LENS 3,
+finding on ruling 1): tests/test_map_registry.py's own
+test_kind_key_maps_import_by_source_language_not_by_kind test already
+pins kind_key("include", "import", "ts") == "include/import.js" --
+deleting "ts" from JS_LANGS reds that live pin. And ambit_map/load.py's
+load_run reads a unit's `lang` value VERBATIM off of symbols.json with NO
+vocabulary gate at all, under this product's own shipped producer-
+portability contract (ambit-mapllm-contract.md, pyproject.toml) -- an
+older or foreign producer's artifact can carry a `lang` this engine's OWN
+current writer (ambitgraph/symbols.py's build_file_plane) never emits
+today. So every grouping below keeps its READER-TOLERANCE members: they
+document what a FILE may say, not only what this engine currently
+writes.
+"""
+
+# ===========================================================================
+# Admission -- CENSUS fact 1. Byte-duplicated from ambitgraph/langs.py's
+# ENGINE_DEFAULT_INCLUDE_EXT, IN ORDER: the order is byte-load-bearing
+# through ambitgraph/symbols.py's config_hash and through the cross-import
+# equality pin at tests/test_map_serve.py's own
+# test_engine_include_ext_is_duplicated_by_value_and_never_drifts test
+# (see that engine module's own docstring for the full argument). Formerly
+# hand-duplicated separately inside ambit_map/orchestrate.py;
+# orchestrate.py now aliases this tuple instead of carrying its own
+# literal.
+# ===========================================================================
+ENGINE_DEFAULT_INCLUDE_EXT = (
+    ".py", ".js", ".ts", ".tsx", ".jsx", ".java", ".jsp", ".jspf",
+    ".css", ".html", ".go", ".rb", ".php", ".cs", ".sql", ".sh",
+)
+
+# The extra extensions a mapllm run admits beyond the shared engine default
+# above -- world-popularity order per the founder's list, the C/C++
+# foundation first (formerly ambit_map/orchestrate.py's own
+# MAPLLM_EXTRA_INCLUDE_EXT literal; this constant is not part of
+# ambitgraph/langs.py at all -- it is this product's OWN scope extension,
+# mirrored here only so orchestrate.py can source every admission fact
+# from this one file).
+MAPLLM_EXTRA_INCLUDE_EXT = (".c", ".h", ".cpp", ".hpp", ".rs")
+
+
+# ===========================================================================
+# Naming's product-side grouping (CENSUS fact 2's third spelling) --
+# formerly ambit_map/registry.py's own JS_LANGS/PY_LANGS literals, the pair
+# kind_key's src_lang branch reads. READER-TOLERANCE VOCABULARY (see module
+# docstring): today ambitgraph/symbols.py's build_file_plane (the only
+# writer of a file row's `lang` field) folds .jsx/.mjs/.cjs/.ts/.tsx all
+# into the single tag "js" -- so "jsx"/"mjs"/"cjs"/"ts"/"tsx" can never
+# appear as a REAL `lang` value THIS engine emits today. They stay in
+# JS_LANGS anyway: an older or foreign producer's symbols.json is free to
+# spell it differently under this product's own producer-portability
+# contract, and ambit_map/load.py's load_run reads `lang` with no
+# vocabulary gate at all. PY_LANGS carries no such extra member -- "py" is
+# the only tag ambitgraph/langs.py's "py" LangSpec ever declares.
+#
+# JAVA_LANGS (Java W1, 2026-09-02, additive): the identical one-tag
+# grouping shape as PY_LANGS -- "java" is the only tag ambitgraph/langs.py's
+# "java" LangSpec ever declares, so this carries no reader-tolerance member
+# either. Exists as its own named grouping (never folded into JS_LANGS or
+# PY_LANGS) because kind_key's import branch needs a THIRD disjoint
+# src_lang bucket once include/import.java joins include/import.py and
+# include/import.js.
+# ===========================================================================
+JS_LANGS = ("js", "jsx", "mjs", "cjs", "ts", "tsx")
+PY_LANGS = ("py",)
+JAVA_LANGS = ("java",)
+
+# TYPE_SYMBOL_KINDS (Java W1 repair -- the wall-legal PRODUCT-side
+# mirror of ambitgraph/codelib.py's own _TYPE_SYMBOL_KINDS): the literal
+# kind strings symbols.py's own class alternation emits for a Java type
+# declaration ("class"/"interface"/"enum"/"record") -- "constructor" is
+# DELIBERATELY not a member, the same exclusion codelib.py's own set
+# states (a constructor is a member OF a type, never itself a type
+# declaration). Consumed by ambit_map/unitpage.py's own class-count
+# bucket so a Java interface/enum/record renders in the class(es) count
+# on the unit story, not silently in "other named symbol(s)". Diffed
+# against ambitgraph.codelib._TYPE_SYMBOL_KINDS by
+# tests/test_langs_mirror_diff.py (DIFFED_FACT_NAMES entry
+# "type_symbol_kinds") -- one origin (symbols.py's own kind literals), two
+# independently-declared copies, never a cross-wall import.
+TYPE_SYMBOL_KINDS = ("class", "interface", "enum", "record")
+
+# NAMESPACE_LANGS (Java W1 repair -- the wall-legal PRODUCT-side mirror of
+# ambitgraph/langs.py's own NAMESPACE_LANGS): the `lang` tags whose units
+# get the java-namespace treatment (the languages whose LangSpec declares
+# namespace=True). Consumed by ambit_map/unitpage.py's class-count bucket
+# as the language gate on TYPE_SYMBOL_KINDS above -- symbols.py emits the
+# SAME literal kinds ("interface"/"enum") for TypeScript declarations,
+# which must keep rendering as "other named symbol(s)", exactly the
+# boundary ambitgraph/codelib.py draws with its own is_java_namespace
+# check at export. Diffed against ambitgraph.langs.NAMESPACE_LANGS by
+# tests/test_langs_mirror_diff.py (DIFFED_FACT_NAMES entry
+# "namespace_langs") -- one origin (the LangSpec namespace flags), two
+# independently-declared copies, never a cross-wall import.
+NAMESPACE_LANGS = frozenset({"java", "jsp"})
+
+
+# ===========================================================================
+# CENSUS fact 8 -- formerly ambit_map/registry.py's own ROUTEDNESS_LANGS
+# literal. READER-TOLERANCE VOCABULARY, same law as JS_LANGS above: "jspf"
+# can never appear as a real `lang` value today (ambitgraph/symbols.py's
+# build_file_plane folds .jspf into the tag "jsp", never into "jspf"
+# itself) but stays for the identical producer-portability reason.
+# Consumed DIRECTLY by ambit_map/library.py's routedness gates
+# (_routedness_is_silent, _blind_for_run) via `langm.ROUTEDNESS_LANGS` --
+# no production call site reads it through registry.py anymore.
+# ambit_map/registry.py still re-exports the name (`ROUTEDNESS_LANGS =
+# langm.ROUTEDNESS_LANGS`), kept alive for backward compatibility and
+# because tests/test_langs_value_pins.py's own R4.0 locked oracle pin
+# still asserts `reg.ROUTEDNESS_LANGS` by value.
+# ===========================================================================
+ROUTEDNESS_LANGS = ("jsp", "jspf", "java")
+
+
+# ===========================================================================
+# CENSUS fact 4's product-side mirror -- formerly ambit_map/paths.py's own
+# KIND_READER_LANGS literal (the full reader-coverage matrix: 19
+# ALLOWED_KINDS rows -> the Unit.lang frozenset each kind's reader covers).
+# Java W1 (2026-09-02): the 19th row, include/import.java, is additive --
+# every pre-existing row's value is UNCHANGED. Values UNCHANGED otherwise;
+# the "why" narrative for each individual row (which real reader function
+# backs it, what its own language gate looks like) stays in
+# ambit_map/paths.py's own module comment beside its KIND_READER_LANGS
+# alias -- this module only carries the literal.
+#
+# _kind_applicable's THREE NAMED DIVERGENCES (ambit_map/paths.py, unmoved
+# -- these are about HOW paths.py USES this table, not part of the table's
+# own values, so the overriding logic and its own inputs (TERMINAL_KINDS,
+# MOUNT_CAPABLE_PACKS) stay declared in paths.py, not here):
+#   1. TERMINAL_KINDS (table/read|write|ddl) -- LANGUAGE-AGNOSTIC by the
+#      real reader's own construction (ambitgraph/tables.py's build_tables
+#      carries no language gate at all): applicable whenever the model
+#      holds any unit at all -- this table's own three TERMINAL rows are
+#      never actually consulted for that decision.
+#   2. "reference/script" -- unconditionally False: CONFIG-gated on
+#      ScanConfig.asset_roots, never language-gated, and this product's own
+#      scan config never sets asset_roots -- so this row's frozenset below
+#      is never actually consulted either; kept only so this dict's key set
+#      still equals paths.ALLOWED_KINDS.
+#   3. "route/mount" -- language overlap against this row IS consulted, but
+#      is NECESSARY, not SUFFICIENT: applicability additionally requires at
+#      least one of MOUNT_CAPABLE_PACKS (express_pack/fastapi_pack/
+#      flask_pack) to have DETECTED this run.
+# ===========================================================================
+KIND_READER_LANGS = {
+    "include/static": frozenset({"jsp"}),
+    "include/import.py": frozenset({"py"}),
+    "include/import.js": frozenset({"js"}),
+    # Java W1 (2026-09-02), additive: langs.py's java LangSpec gains
+    # include_lane=True this wave -- the row sits beside its import.py/
+    # import.js siblings, same shape, one reader language.
+    "include/import.java": frozenset({"java"}),
+    "include/require": frozenset({"js"}),
+    "include/dynamic": frozenset({"jsp"}),
+    "include/reexport": frozenset({"js"}),
+    "include/dynamic-import": frozenset({"js"}),
+    "include/member-resolved": frozenset({"js"}),
+    "calls": frozenset({"jsp", "java", "py", "js"}),
+    "reference/script": frozenset({"jsp"}),
+    "route/mount": frozenset({"py", "js"}),
+    "ui/component-use": frozenset({"js"}),
+    "net/fetch-route": frozenset({"js", "py"}),
+    "ui/component-use-matched": frozenset({"js"}),
+    "event/emit": frozenset({"js"}),
+    "table/read": frozenset({"sql", "js", "py", "jsp"}),
+    "table/write": frozenset({"sql", "js", "py", "jsp"}),
+    "table/ddl": frozenset({"sql", "js", "py", "jsp"}),
+}
+
+
+# ===========================================================================
+# CENSUS fact 2's product-side mirror -- formerly ambit_map/paths.py's own
+# _GRAMMAR_EXTS literal, a hand-kept copy of ambitgraph/symbols.py's
+# _LANG_FOR_EXT key set (exactly the extensions with a real comment-
+# blanking grammar). Unlike JS_LANGS/PY_LANGS/ROUTEDNESS_LANGS above, this
+# set carries NO reader-tolerance members: it is a copy of the ENGINE's own
+# key set (every ambitgraph/langs.py LangSpec's naming_exts, unioned), not
+# a copy of a possibly-foreign `lang` value's vocabulary.
+# ===========================================================================
+_GRAMMAR_EXTS = frozenset({
+    ".jsp", ".jspf", ".java", ".js", ".mjs", ".cjs", ".jsx", ".ts", ".tsx",
+    ".py", ".sh", ".sql",
+})
+
+
+# ===========================================================================
+# CENSUS fact 8's disclosure-gate vocabulary -- formerly
+# ambit_map/library.py's own inline regex literal, r"\bjsp\b|\bjava\b".
+# Declared as its OWN field, NEVER derived from a lang-tag grouping above
+# (R4-DESIGN.md v2's explicit ruling, JUDGES-DIGEST.txt LENS 1/2 finding on
+# the blind filter): this is a vocabulary of ENGLISH WORDS a disclosure
+# SENTENCE spells, not a vocabulary of `lang` tag values, and the two
+# differ on purpose. Joining it from ROUTEDNESS_LANGS above would either
+# resurrect "jspf" into the regex (no disclosure sentence anywhere spells
+# the standalone word "jspf" -- ROUTEDNESS_LANGS keeps it only for
+# producer-portability tolerance, never because prose says it) or, joined
+# from JS_LANGS, mint useless/dangerous words no disclosure sentence uses
+# standalone this way ("ts", "cjs") or that collide with ordinary English
+# ("js" inside other tokens). ambit_map/library.py's own _BLIND_LANG_FILTER
+# compiles its regex from exactly these two words, `\b<word>\b` each,
+# joined with `|` -- byte-identical to the pattern it replaces.
+# ===========================================================================
+BLIND_LANG_PROSE_WORDS = ("jsp", "java")

{ambitgraph-0.2.0 → ambitgraph-0.3.0}/ambit_map/library.py

@@ -2,8 +2,9 @@
 screens (U1 rewrite, wave/u1-library-home): the COMPOSITION is now built on
 ambit_map/objects.py's object kit and ambit_map/families.py's human family
 taxonomy. No file I/O, no clock, no server. Imports: registry, objects,
-families (same package) + collections, threading (stdlib -- W7, the
-_resolved_mounts cache below; see that cache's own module comment).
+families, and (R4) langmirror (same package) + collections, threading
+(stdlib -- W7, the _resolved_mounts cache below; see that cache's own
+module comment).
 
 U3 (wave/u3-graph, U3-A): the transitional chrome fence that kept the old
 `_hero`/`_block`/`_note`/... renderers alive for graph.py's own sake is
@@ -27,6 +28,7 @@ import threading
 from . import registry as reg
 from . import objects as ob
 from . import families as fam
+from . import langmirror as langm
 
 # ---------------------------------------------------------------------------
 # Cap constants
@@ -66,7 +68,12 @@ JUDGED_HOME_ROWS_CAP = 24
 JUDGED_FOLD_ROWS_CAP = 8
 JUDGED_UNJOINED_CAP = 24
 
-_COUNTED_SYMBOL_KINDS = ("function", "method", "class")
+# R4.4-product: _COUNTED_SYMBOL_KINDS deleted here (was `("function",
+# "method", "class")`) -- grep-verified ZERO references tree-wide before
+# deletion (JUDGES-DIGEST.txt LENS 3 finding: dead code, not a shared
+# vocabulary with this module's own _fn_count or unitpage.py's own
+# per-unit symbol partition -- see those two sites' own comments, both
+# left untouched).
 _SLUG_OK = set("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789")
 
 
@@ -528,7 +535,7 @@ def _routedness_is_silent(model):
     servlet container's web.xml is not a thing that could exist)."""
     units = model.units.values()
     for u in units:
-        if u.lang in reg.ROUTEDNESS_LANGS:
+        if u.lang in langm.ROUTEDNESS_LANGS:
             return False
     for u in units:
         r = u.routedness
@@ -889,16 +896,25 @@ def _method_note1(dialects):
 # neither is the language name this filter exists to drop. `\bjava\b`
 # never matches "javascript" (no boundary follows "java" there) or
 # "javadoc" (same reason), so only the standalone word is caught.
-_BLIND_LANG_FILTER = re.compile(r"\bjsp\b|\bjava\b", re.IGNORECASE)
+#
+# R4: the two words themselves now live at ambit_map/langmirror.py's own
+# BLIND_LANG_PROSE_WORDS, declared as their OWN field rather than derived
+# from ROUTEDNESS_LANGS/JS_LANGS above (that module's own comment states
+# why: a vocabulary of English disclosure words, not of `lang` tags). The
+# compiled pattern is byte-identical to the literal it replaces,
+# r"\bjsp\b|\bjava\b".
+_BLIND_LANG_FILTER = re.compile(
+    "|".join(r"\b%s\b" % re.escape(w) for w in langm.BLIND_LANG_PROSE_WORDS),
+    re.IGNORECASE)
 
 
 def _blind_for_run(cov, model):
     """`_combined_blind` (DATA/LOGIC, kept verbatim -- other call sites in
     this module still want the RAW list) always carries the engine's
     static, always-present disclosures, including the JSP/Java-scriptlet
-    and JSP/Java-namespace sentences -- ambitgraph/symbols.py:43-46 says so
-    explicitly ("always present, regardless of what the scanned tree
-    happens to contain"). Review fix (major): on a run with zero jsp/jspf/
+    and JSP/Java-namespace sentences -- the comment above
+    ambitgraph.symbols.BLIND_SENTENCES says so explicitly ("always
+    present, regardless of what the scanned tree happens to contain"). Review fix (major): on a run with zero jsp/jspf/
     java units those two sentences named a language the page never scanned
     (chatbot-ui, flask), so THIS caller -- the only live caller of
     `_combined_blind` in the new render_library flow -- drops any sentence
@@ -907,7 +923,7 @@ def _blind_for_run(cov, model):
     callers unfiltered, since ZERO_DDL_MATCH/CALL_BLIND_MATCH need the
     full list regardless of language mix."""
     blind = _combined_blind(cov)
-    if any(u.lang in reg.ROUTEDNESS_LANGS for u in model.units.values()):
+    if any(u.lang in langm.ROUTEDNESS_LANGS for u in model.units.values()):
         return blind
     return [s for s in blind if not _BLIND_LANG_FILTER.search(s)]
 

{ambitgraph-0.2.0 → ambitgraph-0.3.0}/ambit_map/load.py

@@ -295,12 +295,35 @@ def load_run(run_dir):
                 line = row.get("line") if isinstance(row.get("line"), int) else 0
                 if not row.get("resolved"):
                     if src in unresolved_acc:
-                        # R3/R9 (W7a, additive): "unresolved_reason" is a
-                        # NEW, optional key ambitgraph/edges.py sets only
-                        # on a Python absolute import HELD on the
-                        # cross-root tier (R9) -- absent (the row.get
-                        # default) on every ordinary unresolved row,
-                        # exactly as before this wave.
+                        # R3/R9 (W7a, additive) + Java W1 (D3, "machine
+                        # tokens are interfaces" law; load.py repair):
+                        # "unresolved_reason" is an OPTIONAL
+                        # key ambitgraph/edges.py sets on an unresolved
+                        # row it can name a SPECIFIC held/refused reason
+                        # for -- absent (the row.get default) on every
+                        # ORDINARY unresolved row (a target this scan
+                        # genuinely never read at all), exactly as
+                        # before R9. THE THREE TOKENS this key actually
+                        # carries today, this being the one place any of
+                        # them is parsed off the wire: "cross_root_
+                        # import_held" (a Python absolute import R9-held
+                        # on the cross-root tier, OR a Java import
+                        # HELD the same way -- java's tier reuses this
+                        # SAME token, never a java-named twin, per D3);
+                        # "wildcard_import" (a Java plain wildcard import
+                        # -- `import com.foo.*;` names a package, never a
+                        # single file, so it is never even tried against
+                        # the resolver); "importer_root_underivable" (a
+                        # Java file whose OWN package root could not be
+                        # derived -- a default-package file, or one whose
+                        # directory does not match its `package`
+                        # declaration's suffix -- so none of its imports
+                        # is tried against either resolution tier at
+                        # all). registry.py's unresolved_reason_sentence
+                        # is the dispatch that maps these three literals
+                        # to their sentences, for every caption site
+                        # (graph.py's _quarantine_note, unitpage.py's
+                        # connections block).
                         reason = row.get("unresolved_reason")
                         unresolved_acc[src].append(
                             model.UnresolvedRef(

{ambitgraph-0.2.0 → ambitgraph-0.3.0}/ambit_map/matched.py

@@ -24,6 +24,12 @@ from . import library as lib
 from . import model as model_mod
 
 _DEFINER_KINDS = ("function", "class")
+# Java W1 repair (2026-09-02): DELIBERATELY unwidened this wave --
+# symbols.py's D2 closure now also emits "interface"/"enum"/"record", but
+# whether any of those should ever be a call-binding DEFINER is roadmap
+# material (JAVA-W1-DESIGN.md v2's own "out of W1": "call-binding via
+# imports"), not decided here. Left exactly as it was pre-wave; not an
+# oversight.
 
 
 def _collapse_matched_edges(edges):

{ambitgraph-0.2.0 → ambitgraph-0.3.0}/ambit_map/model.py

@@ -47,17 +47,40 @@ class UnresolvedRef:
     # ruling on the verify pass's finding [2], additive): "" (the
     # default) is byte-identical to every pre-W7a UnresolvedRef -- every
     # existing keyword-only construction site stays valid unchanged.
-    # "cross_root_import_held" marks a Python absolute import HELD on
-    # the cross-root tier (ambitgraph/edges.py's R9 evidence ladder --
-    # neither '' nor the importer's own derived root resolved it, but
-    # some OTHER one did; carried on the edges row as "unresolved_
-    # reason"), distinct from an ordinary external/never-read import --
-    # ambit_map/load.py sets it, ambit_map/graph.py's _quarantine_note
-    # reads it to pick the correct sentence (never the false "this scan
-    # never read" one for a target the scan genuinely read). (Was
-    # "ambiguous_import_roots" pre-R9 -- renamed along with the ladder
-    # change; see edges.py's own R9 docstring for why the old name no
-    # longer names a distinct state.)
+    # "cross_root_import_held" marks an import HELD on the cross-root
+    # tier of its language's own evidence ladder (ambitgraph/edges.py's
+    # R9 ladder for Python -- neither '' nor the importer's own derived
+    # root resolved it, but some OTHER one did; carried on the edges row
+    # as "unresolved_reason"), distinct from an ordinary external/
+    # never-read import -- ambit_map/load.py sets it, and the caption
+    # sites (graph.py's _quarantine_note, unitpage.py's connections
+    # block) read it through registry.py's unresolved_reason_sentence to
+    # pick the correct sentence (never the false "this scan never read"
+    # one for a target the scan genuinely read). Java W1 repair (2026-09-02): this token is NOT
+    # Python-only -- D3's java ladder tier (ii) REUSES this exact same
+    # token, byte-identically, for a java-sourced cross-root hold, rather
+    # than minting a java-named twin (the sentence text itself already
+    # names no language, by deliberate choice -- see registry.py's
+    # CROSS_ROOT_IMPORT_HELD_SENTENCE); this comment used to describe the
+    # token as if only a Python import could ever carry it, which stopped
+    # being true the moment D3 landed. (Was "ambiguous_import_roots"
+    # pre-R9 -- renamed along with the ladder change; see edges.py's own
+    # R9 docstring for why the old name no longer names a distinct
+    # state.) Java W1 (2026-09-02, DESIGN.md D3,
+    # "machine tokens are interfaces" law), additive, same posture as
+    # cross_root_import_held -- each ships WITH its own graph.py branch
+    # and registry.py sentence, never a free-text reason (a free-text
+    # reason falls through to the generic "never read" sentence, which is
+    # false for a target this scan genuinely did read):
+    # "wildcard_import" marks a Java wildcard import (`import com.foo.*;`)
+    # -- a wildcard names a PACKAGE, never a single file, so it is refused
+    # and counted rather than guessed at one target.
+    # "importer_root_underivable" marks an import whose OWN importer file
+    # has no derivable package root (a default-package file, or one whose
+    # directory does not match its `package` declaration's suffix) -- its
+    # imports are never tested against another file's derived root at
+    # all, for a reason that has nothing to do with whether some target
+    # file was ever read.
     reason: str = ""
 
 

{ambitgraph-0.2.0 → ambitgraph-0.3.0}/ambit_map/objects.py

@@ -797,12 +797,16 @@ def sub_head(text):
 
 def sym_table(headers, rows):
     """headers = iterable of column header strings. rows = iterable of
-    (anchor_id, href, name, kind, line, signature, doc[, clipped]) --
-    `href` falsy renders the name as plain text, never an anchor; a
+    (anchor_id, href, name, kind, line, signature, doc[, clipped[, vis]])
+    -- `href` falsy renders the name as plain text, never an anchor; a
     trailing 8th `clipped` element (bool) appends the CLIPPED_LABEL chip
-    inside the signature cell. EVERY cell is escaped inside this emitter --
-    there is no RAW slot at all. Stamped `data-amg-object="sym-table"` on
-    the `.cl-scroll` root -- it IS a container root."""
+    inside the signature cell; a trailing `vis` element after it (a
+    display word the caller already chose, e.g. reg.sym_visibility_label's)
+    appends a scope chip stating the symbol's captured visibility in the
+    same cell, omitted entirely when falsy. EVERY cell is escaped inside this
+    emitter -- there is no RAW slot at all. Stamped
+    `data-amg-object="sym-table"` on the `.cl-scroll` root -- it IS a
+    container root."""
     parts = ['<div class="cl-scroll" data-amg-object="sym-table"><table class="cl-table"><thead><tr>']
     for h in headers:
         parts.append('<th>' + esc(h) + '</th>')
@@ -810,11 +814,14 @@ def sym_table(headers, rows):
     for row in rows:
         anchor_id, href, name, kind, line, signature, doc = row[:7]
         clipped = row[7] if len(row) > 7 else False
+        vis = row[8] if len(row) > 8 else ""
         name_html = ('<a href="' + esc(_safe_href(href)) + '">' + esc(name) + '</a>'
                      if href else esc(name))
         sig_html = esc(signature)
         if clipped:
             sig_html += dchip("scope", CLIPPED_LABEL)
+        if vis:
+            sig_html += dchip("scope", vis)
         parts.append(
             '<tr><td class="cl-fn" id="' + esc(anchor_id) + '">' + name_html + '</td>'
             '<td>' + esc(kind) + '</td><td>' + esc(line) + '</td>'

{ambitgraph-0.2.0 → ambitgraph-0.3.0}/ambit_map/orchestrate.py

@@ -2,9 +2,10 @@
 rotate its runs, and speak the greeting. NEW for K4.
 
 Imports: stdlib only (`hashlib, json, os, re, shutil, subprocess, sys, time,
-webbrowser`, `datetime`, `pathlib`) plus `from . import registry as reg` and
-`from . import load` -- never `ambitgraph`, never any dynamic import, never
-eval/exec (the absolute wall, tests/test_import_boundaries.py:83-102).
+webbrowser`, `datetime`, `pathlib`) plus `from . import registry as reg`,
+`from . import load` and (R4) `from . import langmirror as langm` -- never
+`ambitgraph`, never any dynamic import, never eval/exec (the absolute
+wall, test_import_boundaries.py's own rule_message wall rule).
 
 `serve` is imported LAZILY, inside run_scan() only: serve.py imports this
 module (`orchestrate as orch`) at its own top level, so a module-level
@@ -33,6 +34,7 @@ from . import load
 from . import paths
 from . import graph
 from . import islands
+from . import langmirror as langm
 from .dialects import contract as dcontract
 
 # ---------------------------------------------------------------------------
@@ -90,14 +92,18 @@ PATIENCE_BUDGET_SECONDS = 3600
 ENVELOPE_FILES = 750
 MEASURED_SECONDS_PER_FILE = 0.080
 
-# duplicated BY VALUE from ambitgraph/config.py:32-35 -- ambit_map imports no
-# engine code, the same posture ENGINE_DEFAULT_EXCLUDE_DIRS already takes.
-# tests/test_map_serve.py asserts this still equals ScanConfig().include_ext,
-# so the two can never silently drift.
-ENGINE_DEFAULT_INCLUDE_EXT = (
-    ".py", ".js", ".ts", ".tsx", ".jsx", ".java", ".jsp", ".jspf",
-    ".css", ".html", ".go", ".rb", ".php", ".cs", ".sql", ".sh",
-)
+# R4: sourced from ambit_map/langmirror.py, the product-side mirror of
+# ambitgraph/langs.py -- the engine truth this tuple duplicates by value
+# now lives at ambitgraph/langs.py's own ENGINE_DEFAULT_INCLUDE_EXT
+# (citation-rot fix, R4-DESIGN.md v2 ruling 3: this comment used to point
+# at config.py:32-35 while ScanConfig's real default had drifted to
+# different lines -- a one-line pointer, never a line number, so the
+# comment cannot rot the same way again). ambit_map still imports no
+# engine code -- langmirror.py is an ASSERTED COPY, the same posture
+# ENGINE_DEFAULT_EXCLUDE_DIRS already takes. tests/test_map_serve.py
+# asserts this still equals ScanConfig().include_ext, so the two can never
+# silently drift.
+ENGINE_DEFAULT_INCLUDE_EXT = langm.ENGINE_DEFAULT_INCLUDE_EXT
 # C2 (mapllm wave): the extra extensions a mapllm run admits beyond the
 # shared engine default above -- world-popularity order per the founder's
 # list, the C/C++ foundation first. `map`'s and `scan`'s own defaults stay
@@ -105,8 +111,9 @@ ENGINE_DEFAULT_INCLUDE_EXT = (
 # stays green, unchanged): this list only ever widens a mapllm run's OWN
 # generated product config (product_config()/write_product_config()/
 # plan()'s own extra_include_ext argument, below), never
-# ENGINE_DEFAULT_INCLUDE_EXT itself.
-MAPLLM_EXTRA_INCLUDE_EXT = (".c", ".h", ".cpp", ".hpp", ".rs")
+# ENGINE_DEFAULT_INCLUDE_EXT itself. R4: sourced from langmirror.py, same
+# posture as the admission tuple above.
+MAPLLM_EXTRA_INCLUDE_EXT = langm.MAPLLM_EXTRA_INCLUDE_EXT
 FAIL_TAIL_CHARS = 1200
 DIALECT_FILENAME = "product-dialect.json"
 # W5 D-W5-D -- the per-run path-plane data artifact, written beside