ambitgraph 0.8.1__tar.gz → 0.8.2__tar.gz

{ambitgraph-0.8.1 → ambitgraph-0.8.2}/MANIFEST.in

@@ -12,6 +12,11 @@ prune dist
 prune evidence-*
 prune evidence
 
+# The repository's own responsibility record (.ambit/responsibility.jsonl):
+# it describes THIS repository's people and travels with the source tree,
+# never with the installed package.
+prune .ambit
+
 # Internal process documents.
 exclude AGENTS.md
 exclude CHANGELOG.md

{ambitgraph-0.8.1/ambitgraph.egg-info → ambitgraph-0.8.2}/PKG-INFO

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

{ambitgraph-0.8.1 → ambitgraph-0.8.2}/ambit_map/daemon.py

@@ -156,13 +156,12 @@ class DaemonTimeout(Exception):
 
 
 # ---------------------------------------------------------------------------
-# 2. reading the serve file -- fail-closed, the read_paths_index posture
+# 2. reading the serve file -- fail-closed
 # ---------------------------------------------------------------------------
 
 
 def read_serve_file(out_dir):
-    """Read <out_dir>/serve.json -> dict. FAIL-CLOSED, the exact posture
-    orchestrate.read_paths_index already takes: absent / unreadable /
+    """Read <out_dir>/serve.json -> dict. FAIL-CLOSED: absent / unreadable /
     non-JSON / not-a-dict / wrong schema version `v` -> None. Likewise,
     "pid"/"port" that are present but not ints (null, a
     string, missing) are the SAME fail-closed None -- every caller of this
@@ -1031,6 +1030,19 @@ def launch(args, out_dir, repo, idle_minutes, budget_s=None,
         lines.append(reg.DAEMON_DAMAGED.format(reason=health["damaged"]))
     if cmd is None:
         cmd = invocation_form() + " " + cmd_name
+    # The stop instruction echoes the --out the caller typed, exactly as
+    # {repo} echoes the typed repo: the state file lives under that
+    # directory, so the printed command must carry it to find the map.
+    # A typed value holding a space is double-quoted so the line survives
+    # a shell; without --out the segment is empty and the line is
+    # unchanged.
+    typed_out = getattr(args, "out", None)
+    if typed_out:
+        typed_out = str(typed_out)
+        out_segment = (' --out "{0}"'.format(typed_out) if " " in typed_out
+                       else " --out " + typed_out)
+    else:
+        out_segment = ""
     lines.append(reg.DAEMON_OPEN.format(url=url, repo=args.repo, cmd=cmd,
-                                        minutes=idle_minutes))
+                                        minutes=idle_minutes, out=out_segment))
     return 0, lines, url

{ambitgraph-0.8.1 → ambitgraph-0.8.2}/ambit_map/dialects/contract.py

@@ -592,9 +592,9 @@ def attribute_head(text):
 # module) rather than duplicated per Python pack; never resolved to a
 # real uid here (that join belongs to the renderer -- see
 # registry.resolve_py_module_spec, a BY-VALUE mirror of
-# ambitgraph/edges.py's own `_resolve_python_import`, kept in registry.py
-# rather than here because library.py's own import wall does not admit
-# this module). Never file I/O; every function here is pure over text
+# ambitgraph/edges.py's own `_resolve_python_import`, kept independently
+# in registry.py since `ambit_map` imports no `ambitgraph`). Never file
+# I/O; every function here is pure over text
 # already handed to it, matching every other helper in this module.
 # ---------------------------------------------------------------------------
 
@@ -770,14 +770,11 @@ def attribute_head_module_spec(head, module_imports, name_imports):
 
 
 # resolve_py_module_spec (the module_spec -> real-uid resolution half)
-# lives in registry.py, NOT here -- library.py's own import wall
-# (test_library_and_page_import_only_stdlib_and_ambit_map) restricts it to
-# {registry, objects, families}, and registry.py already sits BELOW this
+# lives in registry.py, NOT here -- registry.py already sits BELOW this
 # module in the dependency order (contract.py imports registry, never the
-# reverse), so hosting the pure resolver there lets the renderer use it
-# without library.py importing dialects.contract at all. See registry.py's
-# own import-resolution section for the BY-VALUE mirror of ambitgraph/edges.py's
-# `_resolve_python_import` this module's docstring above describes.
+# reverse). See registry.py's own import-resolution section for the
+# BY-VALUE mirror of ambitgraph/edges.py's `_resolve_python_import` this
+# module's docstring above describes.
 
 
 def kwarg_text(parts, name):
@@ -1153,12 +1150,10 @@ def probe_notes(probe):
 
 
 # ---------------------------------------------------------------------------
-# The entry-point glob language + resolver. Lives
-# here (where the pattern language is defined and evaluated) rather than in
-# graph.py -- library.py's own standing rule is that a renderer "imports no
-# pack, only registry"; resolving in one place yields a report field that
-# carries REAL PATHS, so graph.py never pattern-matches anything, only
-# checks set membership against `getattr(dialects, "entry_points", ())`.
+# The entry-point glob language + resolver. Lives here, where the pattern
+# language is defined and evaluated, so resolving in one place yields a
+# report field that carries REAL PATHS rather than raw patterns a
+# renderer would have to re-match itself.
 # ---------------------------------------------------------------------------
 
 ENTRY_GLOB_DOC = """A pattern is matched against the WHOLE repo-relative posix uid,

{ambitgraph-0.8.1 → ambitgraph-0.8.2}/ambit_map/families.py

@@ -12,22 +12,46 @@ value already built from a sorted walk).
 """
 
 # ---------------------------------------------------------------------------
-# 1.1 The eight families -- FIXED order, key . name . letter . pigment
+# 1.1 The nine families -- FIXED order, key . name . letter . light . dark
 # ---------------------------------------------------------------------------
-
+# TWO PIGMENT COLUMNS, ONE PER THEME, the same shape the folder palette carries.
+# A family keeps ONE identity and wears the column its surface calls for; the
+# hue is held across the pair so the green family is green in both.
+#
+# THE LIGHT COLUMN IS THE SHIPPED ONE, unchanged for the eight that existed.
+# Measured rather than assumed: all eight clear the 3:1 non-text floor on the
+# light grounds and only four clear it on the dark ones, which is what says
+# these were authored for a light surface. The dark column is derived from it,
+# hue held and lightness raised until each clears both dark grounds -- four
+# needed no change at all.
+#
+# `modules` KEEPS ITS KEY AND CHANGES ITS NAME to Logic. The key is what every
+# pin, artifact and stored ruling refers to, so renaming the display string
+# moves no file and breaks no reference; renaming the key would do both for no
+# reader-visible gain.
+#
+# `tests` is the one new family. Its hue sits in the widest unused gap -- 89
+# degrees between olive and teal, centred at 131 -- and its separation from
+# every other family was measured, not eyeballed: dE76 27.2 in the light column
+# and 23.1 in the dark, against the tightest pair already shipped at 20.9 and
+# 17.6. It is deliberately dark and unsaturated: it will be the second-largest
+# family on a typical map, and a fifth of every picture wearing a shout is a
+# picture about its tests.
 FAMILIES = (
-    ("routes", "Routes", "R", "#0e7490"),
-    ("pages", "Pages & Components", "P", "#6d28d9"),
-    ("modules", "Modules", "M", "#4d7c0f"),
-    ("helpers", "Helpers", "H", "#b45309"),
-    ("tables", "Models & Tables", "T", "#26418f"),
-    ("scripts", "Scripts", "S", "#a8324f"),
-    ("config", "Config", "C", "#475569"),
-    ("styles", "Styles", "Y", "#0f766e"),
+    ("routes", "Routes", "R", "#0e7490", "#0e7490"),
+    ("pages", "Pages & Components", "P", "#6d28d9", "#8246de"),
+    ("modules", "Logic", "L", "#4d7c0f", "#4d7c0f"),
+    ("helpers", "Helpers", "H", "#b45309", "#b45309"),
+    ("tables", "Models & Tables", "T", "#26418f", "#3e62cc"),
+    ("scripts", "Scripts", "S", "#a8324f", "#bc3858"),
+    ("config", "Config", "C", "#475569", "#5a6b84"),
+    ("styles", "Styles", "Y", "#0f766e", "#0f766e"),
+    ("tests", "Tests", "E", "#1e4825", "#31773d"),
 )
 
 KEYS = tuple(k for k, *_rest in FAMILIES)
-_BY_KEY = {k: (name, letter, pig) for k, name, letter, pig in FAMILIES}
+_BY_KEY = {k: (name, letter, light, dark)
+           for k, name, letter, light, dark in FAMILIES}
 _FALLBACK_PIG = "#475569"
 
 # ---------------------------------------------------------------------------
@@ -78,6 +102,8 @@ _PAGE_ANCHOR_EXTS = frozenset(("tsx", "jsx", "vue", "svelte", "astro", "mdx", "h
 _HELPER_SEGMENTS = frozenset(("utils", "util", "lib", "libs", "helpers", "hooks",
                                "includes", "shared", "common"))
 _HELPER_STEMS = frozenset(("utils", "util", "helpers", "helper"))
+_TEST_SEGMENTS = frozenset(("tests", "test", "__tests__", "spec", "specs"))
+_TEST_BASES = frozenset(("conftest.py",))
 
 
 def family_of(unit, routes_by_uid=None):
@@ -100,6 +126,25 @@ def family_of(unit, routes_by_uid=None):
     if routes_by_uid and uid in routes_by_uid:
         return "routes"
 
+    # 1b -- a file that exists to CHECK other files is a test, whatever its
+    # extension or its directory. This sits second on purpose. A test's
+    # identity as a test dominates both: components/Button.test.tsx is a test,
+    # not a page. Placed lower it would catch almost nothing, because the page
+    # rule takes .tsx, the helper rule takes anything under lib/, and the table
+    # rule takes anything under db/ -- each would claim the file first.
+    #
+    # It sits AFTER the route fact because that fact is a real mount read from
+    # a dialect pack, and a test file cannot hold one.
+    #
+    # The prefix is `test_` WITH its underscore rather than a bare startswith,
+    # so contest.py and latest.py are not swept in. `scripts/run-tests.sh` is
+    # likewise untouched: it RUNS tests and is not one.
+    if (any(s in _TEST_SEGMENTS for s in segs)
+            or base in _TEST_BASES
+            or stem.startswith("test_") or stem.endswith("_test")
+            or stem.endswith(".test") or stem.endswith(".spec")):
+        return "tests"
+
     # 1b -- filename convention, evaluated whether or not any pack fired.
     if stem in _ROUTE_STEMS:
         return "routes"
@@ -170,7 +215,7 @@ def families_in_use(units, routes_by_uid=None):
         key = family_of(u, routes_by_uid)
         buckets.setdefault(key, []).append(u)
     out = []
-    for key, _name, _letter, _pig in FAMILIES:
+    for key, _name, _letter, _light, _dark in FAMILIES:
         if key in buckets:
             out.append((key, tuple(sorted(buckets[key], key=lambda u: _uid_of(u)))))
     return tuple(out)
@@ -180,7 +225,19 @@ def families_in_use(units, routes_by_uid=None):
 # 1.5 wired -- the truth table
 # ---------------------------------------------------------------------------
 
-ENTRY_FAMILIES = frozenset(("routes", "pages", "scripts", "config", "styles", "tables"))
+# The families nothing needs to point AT. A unit here with no inbound edge is
+# not a loose end -- it is how that kind of file is supposed to look, so it
+# reads "live" rather than joining the unlinked review queue.
+#
+# ⚠ TESTS BELONG HERE AND THE OMISSION IS EXPENSIVE. A test runner DISCOVERS
+# test files; production code never imports them, so every test in a repository
+# has zero inbound edges by design. This list is a POSITIVE one -- anything
+# absent from it falls through to "coming" -- so leaving tests out would have
+# flagged every test file on the map as a possible loose end. On the reference
+# repository that is 55 files, a fifth of the picture, every one of them
+# accused of being unreachable code while being exactly what it should be.
+ENTRY_FAMILIES = frozenset(("routes", "pages", "scripts", "config", "styles",
+                            "tables", "tests"))
 
 
 def _inbound(model, uid):
@@ -223,9 +280,24 @@ def letter(key):
     return v[1] if v else "?"
 
 
-def pigment(key):
+def pigment(key, theme="light"):
+    """-> the family's fill for one theme, defaulting to the light column.
+
+    Two steps: look the family up, then take the column the theme asks for.
+    An unknown theme falls back to light rather than raising, because a
+    renderer asking for a theme this table has not heard of should still draw
+    something.
+
+    THE DEFAULT IS LIGHT, AND THAT IS NOT A PREFERENCE. Every existing caller
+    was written against a single-column table whose colours were authored for
+    a light surface, so defaulting to light leaves all of them correct and
+    unchanged. A default of dark would have silently repainted every current
+    page while every call site still read the same.
+    """
     v = _BY_KEY.get(key)
-    return v[2] if v else _FALLBACK_PIG
+    if not v:
+        return _FALLBACK_PIG
+    return v[3] if theme == "dark" else v[2]
 
 
 def name(key):
@@ -233,6 +305,61 @@ def name(key):
     return v[0] if v else key
 
 
+# ---------------------------------------------------------------------------
+# 1.7 DEFINITIONS -- one sentence per family, for the reader on its board
+# ---------------------------------------------------------------------------
+
+# A SEPARATE TABLE RATHER THAN A SIXTH COLUMN ON `FAMILIES`. Widening that
+# tuple would re-arity two unpackers here and two in the suite -- a
+# restructure riding inside a behaviour change. The completeness this costs
+# (a row physically cannot omit a sixth column) is bought back by the pin
+# that checks these keys against KEYS in BOTH directions.
+#
+# EVERY SENTENCE IS TRUE ONLY IN CASCADE ORDER, because `family_of` is a
+# cascade: the first rule to match wins and later rules never see the unit.
+# So a sentence must never claim a signal an EARLIER rule already took --
+# "pages are .tsx files" is false the moment a .tsx sits under a tests
+# directory. Where that carve-out is the thing a reader would otherwise get
+# wrong, the sentence names it rather than leaving a quiet exception.
+#
+# `modules` IS THE FALLBACK, and its sentence says so instead of naming a
+# purpose. Its members share nothing but having matched no earlier rule: a
+# changelog, an entry point and a data-access module land there together, so
+# any sentence claiming a subject would be false on the first board opened.
+DEFINITIONS = {
+    "routes": ("Files whose name or folder marks them as a way in — a router, "
+               "a URL table, middleware, or anything under a routes folder."),
+    "pages": ("What the app draws — components, templates and views, by file "
+              "type or by the folder holding them."),
+    "modules": ("Everything no other rule claimed. These files share only that "
+                "nothing above matched them — a remainder, not a subject."),
+    "helpers": ("Shared odds and ends, by a utils, lib or shared folder or by "
+                "name. Data models under those same folders are in Models & "
+                "Tables."),
+    "tables": ("Where the app's data shape lives — migrations, schemas, and "
+               "files named or foldered as models."),
+    "scripts": ("Things you run rather than import — shell and batch files, and "
+                "whatever sits in a scripts, bin or tools folder."),
+    "config": ("Settings and manifests rather than code — declaration files, by "
+               "extension or by well-known name."),
+    "styles": "How the app looks — stylesheets, by file type.",
+    "tests": ("Files that exist to check other files. A test's identity beats "
+              "its file type, so a test component sits here rather than in "
+              "Pages."),
+}
+
+
+def definition(key):
+    """-> the family's one-sentence definition, or "" for a key this table
+    has not heard of.
+
+    The empty string rather than a raise, and rather than a placeholder: a
+    board for an unknown family should render its counts and say nothing,
+    not interrupt the page or print a sentence nobody wrote. The same
+    fall-back-quietly posture `letter`, `pigment` and `name` already take.
+    """
+    return DEFINITIONS.get(key, "")
+
 _QUOTE_SAFE = frozenset(
     "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_.-~")
 

{ambitgraph-0.8.1 → ambitgraph-0.8.2}/ambit_map/langmirror.py

@@ -32,11 +32,9 @@ 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, and
 the single function here (`blind_langs`) reads only the table declared
-directly above it, so it needs no import either. 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.
+directly above it, so it needs no import either. Every consumer inside
+this package imports IT; it imports NONE of them, so no consumer risks
+a cycle by depending, transitively, on this module.
 
 NO MEMBER DELETION -- the dead-looking members below are kept deliberately,
 not by oversight, and deleting one is a real regression:
@@ -180,9 +178,7 @@ GO_LANGS = ("go",)
 # 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
+# declaration). 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
@@ -194,11 +190,9 @@ TYPE_SYMBOL_KINDS = ("class", "interface", "enum", "record")
 # strings symbols.py's extract_c_symbols emits for a C type declaration --
 # a tagged bodied "struct"/"union"/"enum", and "typedef". "function" is
 # deliberately not a member (it is the callable half, the same boundary
-# TYPE_SYMBOL_KINDS draws against "constructor"). Consumed by
-# ambit_map/unitpage.py's class-count bucket under the C_LANGS gate above:
-# "enum" is a member of BOTH this tuple and TYPE_SYMBOL_KINDS, and the two
-# language gates are disjoint, so a TypeScript enum still renders as
-# "other named symbol(s)" while a C enum counts as a type. Diffed against
+# TYPE_SYMBOL_KINDS draws against "constructor"). "enum" is a member of
+# BOTH this tuple and TYPE_SYMBOL_KINDS, and the two language gates are
+# disjoint, under the C_LANGS gate above. Diffed against
 # ambitgraph.codelib._C_TYPE_SYMBOL_KINDS by tests/test_langs_mirror_diff.py
 # (DIFFED_FACT_NAMES entry "c_type_symbol_kinds") -- one origin
 # (symbols.py's own kind literals), two independently-declared copies,
@@ -213,13 +207,7 @@ C_TYPE_SYMBOL_KINDS = ("struct", "union", "enum", "typedef")
 # "class" itself (Ruby genuinely has classes), so it feeds BOTH halves of
 # codelib.py's carve identically -- the same shape TYPE_SYMBOL_KINDS takes
 # for Java, never C's shape (which unions "class" in separately because C
-# never emits that literal kind at all). Consumed by
-# ambit_map/unitpage.py's class-count bucket under the RB_LANGS gate
-# above, WIDENING THE COUNT ONLY -- the word stays reg.UNIT_STORY_CLASSES
-# for Ruby (unitpage.py's own class_word ternary is not gated on RB_LANGS
-# at all): Ruby genuinely has classes, so mirroring C's word-swap here
-# would render "N type(s)" about a language whose classes are exactly what
-# the count is naming. Diffed against ambitgraph.codelib._RB_TYPE_SYMBOL_KINDS
+# never emits that literal kind at all). Diffed against ambitgraph.codelib._RB_TYPE_SYMBOL_KINDS
 # by tests/test_langs_mirror_diff.py (DIFFED_FACT_NAMES entry
 # "rb_type_symbol_kinds") -- one origin (symbols.py's own kind literals),
 # two independently-declared copies, never a cross-wall import.
@@ -228,12 +216,11 @@ RB_TYPE_SYMBOL_KINDS = ("class", "module")
 # NAMESPACE_LANGS (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
+# namespace=True) -- 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.
@@ -246,32 +233,22 @@ NAMESPACE_LANGS = frozenset({"java", "jsp"})
 # 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 locked oracle pin
-# still asserts `reg.ROUTEDNESS_LANGS` by value.
+# ambit_map/registry.py re-exports the name (`ROUTEDNESS_LANGS =
+# langm.ROUTEDNESS_LANGS`), kept alive because
+# tests/test_langs_value_pins.py's own locked oracle pin still asserts
+# `reg.ROUTEDNESS_LANGS` by value; no product call site reads it today.
 # ===========================================================================
 ROUTEDNESS_LANGS = ("jsp", "jspf", "java")
 
 
 # ===========================================================================
-# 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).
-# 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_READER_LANGS: the full reader-coverage matrix, 19 ALLOWED_KINDS
+# rows -> the Unit.lang frozenset each kind's reader covers. The 19th
+# row, include/import.java, is additive -- every pre-existing row's
+# value is UNCHANGED.
 #
-# _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):
+# Three named divergences apply this table with an override, rather than
+# a bare language-overlap lookup:
 #   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
@@ -280,8 +257,8 @@ ROUTEDNESS_LANGS = ("jsp", "jspf", "java")
 #   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.
+#      is never actually consulted either; kept only so this dict's key
+#      set still equals the full 19-kind domain.
 #   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/
@@ -395,7 +372,7 @@ _GRAMMAR_EXTS = frozenset({
 # The disclosure-gate vocabulary -- THE PER-SENTENCE LANGUAGE
 # TAG, product side. Formerly ambit_map/library.py's own
 # _BLIND_SENTENCE_LANGS/_blind_langs pair; it lives here, with every other
-# cross-wall copy, and library.py aliases the reader.
+# cross-wall copy.
 #
 # The engine declares each blind sentence's own languages AT the sentence
 # (ambitgraph.symbols.BlindSentence's `langs`, empty meaning the sentence

{ambitgraph-0.8.1 → ambitgraph-0.8.2}/ambit_map/load.py

@@ -318,9 +318,7 @@ def load_run(run_dir):
                         # 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).
+                        # to their sentences.
                         reason = row.get("unresolved_reason")
                         unresolved_acc[src].append(
                             model.UnresolvedRef(

{ambitgraph-0.8.1 → ambitgraph-0.8.2}/ambit_map/model.py

@@ -51,11 +51,10 @@ class UnresolvedRef:
     # 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). This token is NOT
+    # never-read import -- ambit_map/load.py sets it, and
+    # registry.py's unresolved_reason_sentence picks the correct
+    # sentence for it (never the false "this scan never read" one for a
+    # target the scan genuinely read). This token is NOT
     # Python-only -- the Java ladder's cross-root tier 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
@@ -64,8 +63,8 @@ class UnresolvedRef:
     # before the ladder change renamed it; see edges.py's own docstring
     # for why the old name no longer names a distinct state.) A machine
     # token is an interface, so this one keeps the 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
+    # cross_root_import_held -- each ships WITH its own 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.*;`)
@@ -124,8 +123,8 @@ class CallEdge:
 class MemberResolvedEdge:
     """A DATA-PLANE row only -- emitted as data, never painted onto the
     graph: never an IncludeEdge, never folded into `includes`/
-    `included_by`, never read by graph.py's merge_edges (the quarantine
-    precedent: present in data, never painted, on purpose). `src` is the
+    `included_by` (the quarantine precedent: present in data, never
+    painted, on purpose). `src` is the
     importing unit; `name` is the bound name it imported; `through` is the
     directly-imported module (already has its own ordinary IncludeEdge);
     `target` is the module that first DECLARES `name`, reached by tracing
@@ -160,8 +159,8 @@ class PhantomEdge:
 # ui/component-use). These mirror MemberResolvedEdge's own posture exactly:
 # DATA-PLANE-shaped value objects, never resolved or joined here -- the
 # join (composed-route table, event pairing, component-use resolution)
-# is ambit_map/matched.py's own job, over these raw facts plus the
-# already-loaded model. `src` is the file the site was read in, matching
+# is a separate step, over these raw facts plus the already-loaded
+# model. `src` is the file the site was read in, matching
 # every other per-unit dict's own key shape (`includes`, `member_resolved`,
 # ...).
 # ---------------------------------------------------------------------------
@@ -221,8 +220,8 @@ class ImportBindingTarget:
 
 
 # ---------------------------------------------------------------------------
-# The PRODUCT-side output of the four joins in ambit_map/matched.py --
-# pure value objects, never constructed by load.py (unlike every dataclass
+# The PRODUCT-side output of a matched-edge join -- pure value objects,
+# never constructed by load.py (unlike every dataclass
 # above this point, which mirrors an artifact row 1:1). `kind` is always an
 # ambit_map.registry.EDGE_KINDS key. `src`/`dst` are always real unit uids
 # (a matched edge with an unresolved endpoint is never constructed -- it is
@@ -405,8 +404,7 @@ class MapModel:
     # Additive: raw per-unit SITE FACTS, the SAME
     # uid -> tuple[...] shape `member_resolved` already uses. Defaulted so
     # every existing MapModel(...) call site (every hand-built test fixture)
-    # stays byte-unaffected. Never joined/resolved here -- see
-    # ambit_map/matched.py.
+    # stays byte-unaffected. Never joined/resolved here.
     request_sites: dict = field(default_factory=dict)
     event_sites: dict = field(default_factory=dict)
     component_use_sites: dict = field(default_factory=dict)