ambitgraph 0.1.0__tar.gz → 0.2.0__tar.gz

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

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

ambitgraph-0.2.0/ambit_map/ambit-mapllm-contract.md

@@ -0,0 +1,246 @@
+# The mapllm ingestion contract — the shapes your assistant's files must carry
+
+ambit-map-enrich.md already states the law this document generalises: "Today's supported path
+is Claude Code; ANY capable assistant can satisfy the same contract, because your artifacts are
+plain JSON on your disk." That clause is the whole idea — this document turns it into an actual
+schema, so an assistant that is not Claude Code (or a hand-written script) can write a
+conforming file directly and be read exactly the same way.
+
+The law stated plainly, again, because it never changes: everything in this document produces
+*judgment*, not measurement. Nothing here is read, parsed, or counted by the deterministic scan.
+The map keeps the two vocabularies visibly apart — a judged note always renders inside the
+collapsed "Judged by your assistant" block, always carries the `judged` chip, and no judged
+number is ever added to a measured number. A plane built from this contract DECORATES the map;
+it never becomes authoritative over anything the scan itself measured.
+
+## Two ways to produce these files
+
+1. **The workflow-script loop** (ambit-map-enrich.md's own loop): run the script `pending/
+   <stage>.workflow.js` in your assistant session, then reduce its journal with `ambit harvest
+   <stage> --scan <run-dir> --journal <journal>`. The harvester folds one or many analysts'
+   records into the single `results/<stage>.json` file this document specifies below —
+   deduplicating, validating against the enumerations each stage declares, and degrading a
+   partial or malformed record rather than discarding the run's other work.
+2. **The direct-results door**: write `results/<stage>.json` yourself, in the exact shape this
+   document names for that stage, and skip the workflow-script loop entirely. mapllm's conductor
+   accepts a directly-written results file exactly as it accepts one `ambit harvest` produced —
+   the file on disk is the whole contract; nothing tracks how it got there.
+
+Either way, a stage advances only once its `results/<stage>.json` exists; re-running the same
+scan command against the same output directory picks up from there.
+
+## The stage results files
+
+Every stage below is optional except `extract`, `cluster`, and `roles` — `vocab` and `ownership`
+run only when the scan config declares a vocabulary or ownership areas; `suggest` runs only when
+the draft has ambiguous units queued for a human's ruling.
+
+### The `extract` stage — `results/<stage>.json`
+
+```json
+{
+  "units": [
+    {
+      "anchor": "helpers.py::shout",
+      "file": "helpers.py",
+      "hook": "shout",
+      "granularity": "component",
+      "role0": "structure_owner",
+      "hint": "a small formatting helper",
+      "ev": "imported and called by main.py",
+      "similar_to": []
+    }
+  ],
+  "uncovered": []
+}
+```
+
+`granularity` is one of `module` (whole-file scope), `component` (a cohesive unit inside a
+file), or `fragment` (a small piece that composes into larger units) — or the empty string when
+unknown. `role0` is one of `structure_owner` (this code DEFINES the shared structure), `filler`
+(this code USES a structure defined elsewhere), or `unclear`. `anchor` is `file::hook` — the
+stable pair every other stage's file joins on. `uncovered` names manifest paths no unit was
+reported for; it is informational, never a refusal.
+
+### The `cluster` stage — `results/<stage>.json`
+
+```json
+{
+  "families": [
+    {"name": "widgets", "members": ["helpers.py::shout", "main.py::run_report"]}
+  ]
+}
+```
+
+Every anchor from `extract.json` appears in exactly one family's `members`. A unit that fits no
+real family belongs in one named `singletons`, never omitted. An optional `warnings` array
+(strings) may accompany a run that had to degrade rather than discard part of the reduction.
+
+### The `roles` stage — `results/<stage>.json`
+
+```json
+{
+  "roles": {
+    "helpers.py::shout": {"role": "structure_owner", "parent": "", "confidence": "high",
+                              "family": "widgets"},
+    "main.py::run_report": {"role": "filler", "parent": "helpers.py::shout",
+                                "confidence": "high", "family": "widgets"}
+  }
+}
+```
+
+Keyed by anchor. `role` is `structure_owner` | `filler` | `unclear`. `parent` is the anchor a
+`filler` delegates to, written verbatim as anchor text (empty when there is none). `confidence`
+is `high` | `medium` | `low`.
+
+### The `vocab` and `ownership` stages — `results/<stage>.json`
+
+Written only when the scan config declares `vocabulary` (for `vocab.json`) or `areas` (for
+`ownership.json`) — each a name-to-definition mapping the config itself states.
+
+```json
+{
+  "assignments": {
+    "helpers.py::shout": {"family": "widget", "confidence": "high"}
+  },
+  "missing": [],
+  "invalid": []
+}
+```
+
+`vocab.json` uses the key `family`; `ownership.json` uses `area` in its place. The value is one
+of the config's own declared names, or `"none"` (vocab) / `"unknown"` (ownership) — any other
+value is rejected into `invalid`, never silently accepted. `missing` names anchors this file
+assigns nothing to.
+
+### The `suggest` stage — `results/<stage>.json`
+
+```json
+{
+  "suggestions": {
+    "helpers.py::shout": {"ruling": "keep", "rationale": "a tiny standalone helper, used once."}
+  },
+  "missing": [],
+  "invalid": []
+}
+```
+
+`ruling` is `keep` or `wrong` only — never `defer`; deciding later is the human reviewer's own
+authority, not a machine suggestion. A missing or empty `rationale` is rejected into `invalid`.
+
+## The draft's own version and producer record
+
+Once every required stage's results file exists, the scan assembles `map/draft_map.json` — the
+one artifact this whole contract exists to make honest. It carries two fields no prior draft
+ever had:
+
+```json
+{
+  "v": 1,
+  "producer": {
+    "recorded_at": "2026-08-30T00:00:00Z",
+    "config_hash": "sha1:0123456789ab",
+    "engine_fingerprint": "…64 hex chars…"
+  }
+}
+```
+
+`v` is the draft's schema version, checked on load — see "Fail-closed" below for exactly what
+counts as a match. `producer.tool`, when present, names in plain free text what produced the
+stage results this draft was assembled from. Nothing in this contract names a producer for you:
+a `results/<stage>.json` header carries no `producer.tool` unless something put one there — the
+workflow-script loop does not name itself automatically. Today that something is `ambit harvest`'s
+own `--producer` flag:
+
+    ambit harvest <stage> --scan "<run-dir>" --journal <journal> --producer "your assistant's name and version"
+
+`--producer` is optional and free text — name any assistant or tool, or omit it entirely. A
+direct-results-door author writing `results/<stage>.json` by hand carries the identical header
+shape without touching this flag at all: `{"producer": {"tool": "..."}}` sitting on the results
+file is all either path needs to produce. When the `extract` stage's own `results/<stage>.json`
+header never named a producer (the flag was omitted, or a legacy file predates this contract),
+`producer.tool` is **omitted entirely** from the draft, exactly as the example above shows — never
+written as a placeholder string, never guessed. A key that is present is always a real name
+someone gave; a key that is absent means no one gave one. Whitespace-only names (`"   "`) count as
+no name at all, on both the writing and the reading side, and are stripped before anything is
+stored — `ambit harvest --producer " "` prints one plain line saying so rather than silently
+writing a blank name. `producer.config_hash` is the scan's own configuration hash (the same
+value `results/symbols.json` and `results/edges.json` already carry); it binds this draft to the
+scan it was produced against, so a draft copied onto a differently-configured scan is caught
+rather than silently misjoined. `producer.engine_fingerprint` mirrors the draft's own top-level
+fingerprint field, absence-disclosed the identical way (an `engine_fingerprint_absent` flag
+stands in when no fingerprint could be computed).
+
+## Fail-closed, on every branch
+
+The reader that loads this draft never raises on anything it finds on disk, and never renders a
+guess:
+
+- No draft file at all — the normal, unremarkable state before judgment has run. Nothing is
+  shown, nothing is claimed.
+- A draft with no `"v"` key — every draft written before this contract existed. It loads exactly
+  as it always has; the absence of a version is never treated as a mismatch.
+- A draft whose `"v"` key is present but is anything other than the plain integer `1` — refused
+  by name, nothing from the draft is read further. This includes `"v": null` (declared but
+  unusable is not the same fact as absent), `"v": true` (a boolean is never accepted as an
+  integer, even where it happens to equal `1` by value), and `"v": 1.0` (a float is never accepted
+  in place of the declared integer schema version) — every one of these is a real, present value
+  that simply is not this reader's version `1`.
+- A draft whose `producer.config_hash` disagrees with the scan actually being served, when both
+  values are present — refused by name: the facts were produced against a different scan.
+- Anything else malformed (unparseable JSON, a top level that is not an object, a `units` field
+  that is not a list) — refused by name, the same as always.
+
+A refused draft never renders as an empty or zero judged plane — a plane that did not load never
+counts as a plane that loaded empty. Every other field this document does not name is tolerated
+additively: an unrecognised key is ignored, never a reason to refuse the whole file.
+
+## What the acceptance of a real repository taught
+
+The rules above are the shapes; running a real assistant against a real, unmodified public
+repository end to end found six ways a conforming file — or the run that produces it — can still
+mislead a reader even while it parses cleanly. Each is a rule for the assistant writing these
+files directly, not a change to the shapes themselves.
+
+- **`parent` is a verbatim anchor, or the empty string — never prose, and never an external
+  framework's name.** It is the exact `file::hook` text some other unit's own `anchor` field
+  carries, copied byte for byte, so a reader can follow it with a lookup, not a guess. It is
+  never a sentence describing the relationship ("extends the base template"), and never the name
+  of a class, component or framework this scan's own unit set does not contain: when a filler's
+  true parent lives OUTSIDE what this run analysed — a third-party base class, a library
+  component — the correct value is the empty string, the SAME value written when there is no
+  parent at all. The external case IS the empty-string case; it is never spelled out in its own
+  words instead.
+- **Evidence carries conclusions, never scratch reasoning or self-corrections.** The `ev` field,
+  and every free-text evidence field this contract accepts, states what you found — never the
+  thinking that got you there, and never a correction written into the record after the fact
+  ("actually, on reflection, it might instead..."). A reader who has to debug a train of thought
+  to recover the actual claim was handed reasoning, not evidence.
+- **Counts never go inside an anchor.** An anchor names WHICH unit a record is about — it is an
+  identity, never a place to carry a measurement. A number belongs in a field built to hold one,
+  or is left out; folding it into the anchor text itself (`"helpers.py::shout (12 calls)"`) turns
+  an identity into a claim, and the two must never be the same string.
+- **Never write "not in this file set," or any other claim about the file list's horizon.** A
+  large repository is read in chunks, and each analyst sees only the subset it was handed — a
+  sentence asserting what is or is not present ANYWHERE in the repository is a claim about ground
+  this one pass never covered. Worse, the harvester's own reduction keeps every evidence sentence
+  it receives VERBATIM: a horizon claim that was true of one chunk's own narrow view is carried
+  unchanged into the assembled draft, where it now reads as a claim about the WHOLE repository —
+  and is simply false there. State only what this pass itself observed inside the files it was
+  actually given.
+- **The number of stages a run produces is repository-dependent — never a fixed count to
+  expect.** `vocab` and `ownership` run only when the scan's own config declares them (see "The
+  stage results files" above); `suggest` runs only when at least one unit could not be accepted
+  in bulk (the next rule names every reason that can queue one). Watch until the conductor's own
+  exit; never assume in advance how many stages a given run will produce.
+- **The `suggest` queue is every unit the draft could not accept in bulk, and each entry's own
+  `why` field names every reason that queued it, comma-joined, in the engine's own words.** Four
+  independent checks fill the queue: `role == "unclear"` writes `"role unclear"`; otherwise a low
+  `confidence` writes `"low role confidence"`; no structural family assigned by the `cluster`
+  stage writes `"no structural family"`; low vocabulary confidence from the `vocab` stage writes
+  `"low vocabulary confidence"` — a unit can carry more than one of these at once, and none of
+  them is about duplicate code. Rule on the entry's OWN stated `why`, never a guess at what queued
+  it: for `"role unclear"`/`"low role confidence"` the question is "was my own prior uncertainty
+  justified" — but the other two reasons ask a genuinely different question, and the `why` string
+  is what tells you which one you are actually answering. Read it before ruling; do not assume it
+  is always the hedging question.

{ambitgraph-0.1.0 → ambitgraph-0.2.0}/ambit_map/daemon.py

@@ -295,7 +295,7 @@ def _http_post_stop(port, token, timeout_s, opener=None):
 # ---------------------------------------------------------------------------
 
 
-def child_argv(sys_executable, args, port, idle_minutes):
+def child_argv(sys_executable, args, port, idle_minutes, cmd_name="map"):
     """The exact argv/env of the mechanism's step 2: the child is `python
     -P -m ambitgraph map <repo> --foreground --no-open` (the "-P" and the
     env's PYTHONPATH rule are orch.python_child()'s -- see there for what
@@ -311,8 +311,18 @@ def child_argv(sys_executable, args, port, idle_minutes):
     truthy value for them -- read with getattr and a default, the K5
     seam's own rule, so `args` may be a bare six-attribute Namespace built
     by a caller that has never heard of this wave's new flags. Returns
-    (argv, env), not argv alone -- see orch.python_child()."""
-    tail = ["map", str(args.repo), "--foreground", "--no-open"]
+    (argv, env), not argv alone -- see orch.python_child().
+
+    `cmd_name`, new for the mapllm wave (THE SERVE FLAVOR, PLAN.md section
+    2 C1): the child's own subcommand word -- "map" (the default, `ambit
+    map`'s own posture, byte-unchanged) or "mapllm". Every existing caller
+    of this function never passes it, so every existing argv is
+    unaffected; ambit_map.mapllm.cmd_mapllm's own detached-launch path is
+    the one caller that passes cmd_name="mapllm", so a mapllm server's
+    detached child re-enters the SAME conductor loop that spawned it,
+    never a plain `map` child that would silently drop the auto-harvest
+    mechanism."""
+    tail = [cmd_name, str(args.repo), "--foreground", "--no-open"]
     if port is not None:
         tail += ["--port", str(port)]
     if idle_minutes:
@@ -865,7 +875,7 @@ def _status_impl(out_dir, repo, reader, prober, pid_checker):
 def launch(args, out_dir, repo, idle_minutes, budget_s=None,
            reader=None, prober=None, pid_checker=None, spawner=None,
            child_alive=None, clock=None, platform=None, sys_executable=None,
-           poll_interval_s=0.2, cmd=None):
+           poll_interval_s=0.2, cmd=None, cmd_name="map"):
     """The mechanism's steps 1-4, a pure orchestration over injectable
     side effects. `out_dir`/`repo` are ALREADY RESOLVED (the same values
     orch.plan() would compute from args.repo/args.out) -- this function
@@ -886,6 +896,14 @@ def launch(args, out_dir, repo, idle_minutes, budget_s=None,
     this parameter (an existing test, an older caller) still gets a
     real, typeable stop instruction rather than a KeyError.
 
+    `cmd_name`, new for the mapllm wave (THE SERVE FLAVOR, PLAN.md section
+    2 C1): threaded to child_argv() unchanged (see its own docstring), and
+    used to resolve `cmd` itself when the caller leaves it None -- "map"
+    (the default, byte-unchanged) or "mapllm". Every existing caller
+    either passes `cmd` explicitly (cmd_map does) or never heard of
+    `cmd_name` at all, so this default resolution changes nothing for
+    them.
+
     Returns (exit_code, lines_to_print, url_to_open_or_None). cmd_map is a
     thin caller: print each line, then orch.open_browser(url, not
     args.no_open) when url is not None."""
@@ -933,7 +951,8 @@ def launch(args, out_dir, repo, idle_minutes, budget_s=None,
     # DAEMON_PORT_TAKEN comparison below can tell "not given" apart from
     # "given, and it was DEFAULT_PORT".
     requested_port = getattr(args, "port", None)
-    argv, env = child_argv(sys_executable, args, requested_port, idle_minutes)
+    argv, env = child_argv(sys_executable, args, requested_port, idle_minutes,
+                            cmd_name=cmd_name)
     log_path = log_path_for(out_dir)
 
     spawned = {}
@@ -1005,6 +1024,6 @@ def launch(args, out_dir, repo, idle_minutes, budget_s=None,
     if health.get("damaged"):
         lines.append(reg.DAEMON_DAMAGED.format(reason=health["damaged"]))
     if cmd is None:
-        cmd = invocation_form() + " map"
+        cmd = invocation_form() + " " + cmd_name
     lines.append(reg.DAEMON_OPEN.format(url=url, repo=args.repo, cmd=cmd))
     return 0, lines, url

{ambitgraph-0.1.0 → ambitgraph-0.2.0}/ambit_map/export.py

@@ -33,6 +33,10 @@ MANIFEST_NAME = "ambitgraph-map.export.json"   # U4 review fix (blocker): the
 # fresh off disk at export time (never embedded as a literal), so a wheel
 # install and a repo checkout both ship the SAME bytes setuptools packaged.
 ENRICH_DOC_NAME = "ambit-map-enrich.md"
+# C3 (mapllm wave): the ingestion contract's published schema doc, copied
+# beside every export the SAME way as ENRICH_DOC_NAME just above -- the
+# generalisation of ambit-map-enrich.md's own producer-portability clause.
+CONTRACT_DOC_NAME = "ambit-mapllm-contract.md"
 
 Row = collections.namedtuple("Row", "rel route_path raw_query depth")
 
@@ -264,7 +268,12 @@ def write_export(state, out_dir, route, render, now_iso):
 
     rows, graph_slugs = page_rows(model, dialects)
     total_nodes = len(getattr(model, "units", {})) + len(getattr(model, "tables", {}))
-    foot = _footer_html(len(rows) + 1, len(graph_slugs), total_nodes)   # +1 for map.html
+    # `rows` names every .html page this export writes (the manifest's
+    # own "files" list, minus the two .md docs appended after it) --
+    # map.html is a real row IN `rows` (page_rows()'s own docstring
+    # above, and the manifest comment below, both say so), so the
+    # footer's own page count is exactly len(rows), no adjustment.
+    foot = _footer_html(len(rows), len(graph_slugs), total_nodes)
 
     # Stale-file rule (§2.1), scoped by manifest (U4 review fix, blocker):
     # never shutil.rmtree, never a glob wider than the paths this export
@@ -295,10 +304,18 @@ def write_export(state, out_dir, route, render, now_iso):
         (out_dir / ENRICH_DOC_NAME).write_text(
             enrich_src.read_text(encoding="utf-8"), encoding="utf-8", newline="\n")
 
+    # C3 -- the SAME copy-beside step for the ingestion contract doc.
+    contract_src = Path(__file__).with_name(CONTRACT_DOC_NAME)
+    if contract_src.exists():
+        (out_dir / CONTRACT_DOC_NAME).write_text(
+            contract_src.read_text(encoding="utf-8"), encoding="utf-8", newline="\n")
+
     # The manifest names everything THIS export wrote -- map.html included --
     # so the NEXT export's _prune_stale unlinks exactly these paths and
     # nothing a user placed alongside them (U4 review fix, blocker).
     # map.html is a ROW now, so it is already in this list -- appending it
-    # again would name it twice in the manifest.
-    _write_manifest(out_dir, [row.rel for row in rows] + [ENRICH_DOC_NAME])
+    # again would name it twice in the manifest. C3: the contract doc joins
+    # ENRICH_DOC_NAME here for the identical reason -- an un-manifested copy
+    # would be a stray file the NEXT export cannot recognise as its own.
+    _write_manifest(out_dir, [row.rel for row in rows] + [ENRICH_DOC_NAME, CONTRACT_DOC_NAME])
     return index_text

{ambitgraph-0.1.0 → ambitgraph-0.2.0}/ambit_map/judged.py

@@ -44,6 +44,12 @@ class JudgedPlane:
     unjoined: tuple = ()          # tuple[JudgedUnit], uid == "", sorted by anchor
     families: tuple = ()          # tuple[str], sorted -- legend count ONLY in v1
     rows_total: int = 0           # joined + unjoined rows kept
+    # the ingestion contract's producer record (a sibling engine module's
+    # draft writer stamps this): the free-text tool name, carried onto the
+    # plane ONLY when the draft actually named one -- "" otherwise, never
+    # guessed. A renderer may swap its generic wording for this when it is
+    # non-empty; this module renders nothing itself.
+    producer_tool: str = ""
 
 
 @dataclass(frozen=True)
@@ -52,6 +58,32 @@ class DamagedJudged:
     run_dir: str
 
 
+# the ingestion contract's version discipline -- duplicated BY VALUE from
+# the engine's own draft-writer module (the SAME number, never imported:
+# this file speaks stdlib only). Bumped only for a BREAKING shape change.
+DRAFT_SCHEMA_VERSION = 1
+
+
+class DraftVersionMismatch(ValueError):
+    """Raised only to be caught immediately below; DamagedJudged.reason
+    carries just this class's OWN NAME (never a version number, never any
+    other byte of the draft). Fires when "v" is PRESENT and != 1 -- a
+    schema this reader does not speak. A draft with no "v" key at all is
+    NOT this: every draft written before the version key existed predates
+    it entirely, and loads exactly as it always has (the absence law)."""
+
+
+class DraftProducerConfigMismatch(ValueError):
+    """Raised only to be caught immediately below; DamagedJudged.reason
+    carries just this class's own name. Fires only when BOTH the draft's
+    own producer.config_hash and the caller's run_config_hash are non-
+    empty strings AND they differ: the facts in this draft were produced
+    against a different scan configuration than the one being served now.
+    The F6 absence law, verbatim (a sibling engine-side loader keeps the
+    identical guard for its own two artifacts): either side absent never
+    fires."""
+
+
 @dataclass(frozen=True)
 class PendingScript:
     stage: str
@@ -69,13 +101,20 @@ def _s(row, key):
     return v if isinstance(v, str) else ""
 
 
-def load_judged(run_dir, known_uids=()):
+def load_judged(run_dir, known_uids=(), run_config_hash=""):
     """-> JudgedPlane | None | DamagedJudged. Fail-closed -- never raises on
     any file-system or content state; callers pass a real path.
 
     None is the normal Layer-1 state (no draft yet, or run_dir is not a
     directory at all). DamagedJudged names only the exception CLASS -- no
-    byte of the file's content is ever echoed."""
+    byte of the file's content is ever echoed.
+
+    `run_config_hash` (the ingestion contract's cross-artifact guard): the
+    CURRENT run's own config hash, computed by the caller (this module
+    imports no engine code and touches no scan config itself). Compared
+    against the draft's own producer.config_hash ONLY when both sides are
+    non-empty strings -- the F6 absence law, verbatim: omitted or ""
+    never fires a mismatch."""
     path = Path(run_dir).joinpath(*DRAFT_REL)
     try:
         text = path.read_text(encoding="utf-8")
@@ -94,6 +133,35 @@ def load_judged(run_dir, known_uids=()):
             data = json.loads(text)
             if not isinstance(data, dict):
                 raise ValueError("draft is not an object")
+            # the version gate, BACKWARD HONEST: absent "v" predates this
+            # key entirely and is never a mismatch; present and wrong is.
+            # PRESENT-BUT-NULL TRAP (adversarial finding): checking
+            # `v is not None` treats {"v": null} as absent -- but a
+            # DECLARED, unusable value is not the same fact as no value at
+            # all ("declared-but-unusable is not absent"), so membership
+            # ("v" in data) is the only honest absence test, never `is not`.
+            # TYPE TRAP (the other half of the same finding): JSON's
+            # {"v": true} and {"v": 1.0} both deserialize to Python values
+            # that compare EQUAL to 1 by value (bool is an int subclass;
+            # 1.0 == 1) -- a bare `!= DRAFT_SCHEMA_VERSION` would silently
+            # accept either as "version 1". Only a real, non-bool int
+            # equal to DRAFT_SCHEMA_VERSION passes; every other declared
+            # shape (null, bool, float, string, wrong int, ...) mismatches.
+            if "v" in data:
+                v = data["v"]
+                if isinstance(v, bool) or not isinstance(v, int) \
+                        or v != DRAFT_SCHEMA_VERSION:
+                    raise DraftVersionMismatch("v")
+            # the F6-style config_hash cross-artifact guard: only fires
+            # when the draft's own producer.config_hash AND the caller's
+            # run_config_hash are both non-empty strings that disagree.
+            producer = data.get("producer")
+            draft_config_hash = (producer.get("config_hash")
+                                 if isinstance(producer, dict) else None)
+            if (isinstance(draft_config_hash, str) and draft_config_hash
+                    and isinstance(run_config_hash, str) and run_config_hash
+                    and draft_config_hash != run_config_hash):
+                raise DraftProducerConfigMismatch("config_hash")
             rows = data.get("units")
             if not isinstance(rows, list):
                 raise ValueError("draft names no units list")
@@ -146,8 +214,23 @@ def load_judged(run_dir, known_uids=()):
                         names.add(n)
         families = tuple(sorted(names))
 
+        # the producer's tool name, carried onto the plane ONLY when the
+        # draft actually recorded one -- never guessed. `producer` was
+        # already read (and type-checked) by the config_hash gate above.
+        # Stripped and re-checked for emptiness (the SAME whitespace rule
+        # the writer applies) so a hand-authored draft's "   " reads back
+        # exactly as absent, never as a blank-looking "named" producer.
+        producer_tool = ""
+        if isinstance(producer, dict):
+            t = producer.get("tool")
+            if isinstance(t, str):
+                stripped = t.strip()
+                if stripped:
+                    producer_tool = stripped
+
         return JudgedPlane(run_dir=str(run_dir), by_uid=by_uid, unjoined=unjoined,
-                            families=families, rows_total=rows_total)
+                            families=families, rows_total=rows_total,
+                            producer_tool=producer_tool)
     except Exception as exc:
         return DamagedJudged(reason=type(exc).__name__, run_dir=str(run_dir))
 

{ambitgraph-0.1.0 → ambitgraph-0.2.0}/ambit_map/kitdemo.py

@@ -207,9 +207,9 @@ def _table_chips_block():
 
 def _symtable_block():
     """U2 (wave/u2-nodes) additive: demonstrates the three new emitters
-    (sub_head, sym_table, chip_link) the unit page's "Blocks — what it
-    holds" needs. Appended after every U0/U1 block -- no existing block's
-    bytes move."""
+    (sub_head, sym_table, chip_link) the unit page's "Blocks — what the
+    scan read" needs. Appended after every U0/U1 block -- no existing
+    block's bytes move."""
     demo = (
         ob.sub_head("Includes — what this file pulls in")
         + ob.sym_table(
@@ -219,7 +219,7 @@ def _symtable_block():
         + ob.chip_link("/graph?u=app/main.py", "See it on the Graph →"))
     body = demo + ob.code('objects.sub_head(text) / objects.sym_table(headers, rows) / '
                           'objects.chip_link(href, text)')
-    return ob.block("kd-symtable", "blocks — what it holds", body, shown=True)
+    return ob.block("kd-symtable", "blocks — what the scan read", body, shown=True)
 
 
 def _code_block():