diffgenome 0.1.0__py3-none-any.whl

diffgenome/structure.py

@@ -0,0 +1,462 @@
+"""Observed execution structure: occurrences and a generalized skeleton (Experiment 10, v3).
+
+Call nesting and chronology are runtime facts, not semantics, so a proposer should not be
+free to invent them. This module derives them deterministically, relative to a vocabulary
+(the entity names a genome uses), from the existing event protocol: node ids are creation
+order, parents precede children, and a branch observation names its call node and a `seq`
+on the same clock. No collector change is needed.
+
+Two objects, kept apart:
+
+- **Occurrence graph** (evidence, one execution). Every observed call of a vocabulary
+  entity is an occurrence: its id is the call node id; its parent is the nearest ancestor
+  call that is also a vocabulary entity (other frames are looked through; None = no modeled
+  ancestor); its ordinal counts earlier siblings of the same entity under the same parent;
+  its events are its child occurrences and the branch evaluations made in its own call, in
+  time order; its outcome is the call's exit. The runtime records no call-site ids, so
+  repeated calls are keyed by (parent occurrence, entity, ordinal).
+
+- **Skeleton** (deterministic abstraction over the shown executions). Per entity: which
+  vocabulary entities were observed as its *ancestors* and whether it was observed with no
+  modeled ancestor (ROOT), with support. Per parent entity: pairwise precedence among the
+  event families of its occurrences (child entities, and its own decision sites as
+  `site:<id>`): `x ≺ y` when, in every occurrence where both occur, every x precedes every y;
+  families that interleave in some occurrence are recorded as interleaved (a repeated
+  region). Nothing is said about why a region repeats or how often.
+
+Checks built on these (used by `genome_state`):
+- a predicted occurrence of B under P (or at the top of a scenario) that no observed
+  occurrence of B supports is a placement problem: B was never observed during P (or B was
+  never observed without a modeled ancestor);
+- a predicted order x-then-y inside an occurrence of A, where `y ≺ x` held in every shown
+  occurrence of A with both, is an order problem.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from diffgenome.model import CallNode, Execution, SubstitutionNode
+
+ROOT = "<root>"
+
+
+def _tail(symbol: str) -> str:
+    return symbol.split(":", 1)[1] if symbol[:3] in ("go:", "py:", "js:") else symbol
+
+
+def _matches(claimed: str, symbol: str) -> bool:
+    t, c = _tail(symbol), _tail(claimed)
+    return t == c or t.endswith("." + c)
+
+
+def canonical(vocab: list[str], symbol: str) -> str | None:
+    """The vocabulary name an observed symbol belongs to; the longest match wins."""
+    hits = [v for v in vocab if _matches(v, symbol)]
+    return max(hits, key=len) if hits else None
+
+
+def _node_symbol(n: Any) -> str:
+    if isinstance(n, CallNode):
+        return n.symbol
+    if isinstance(n, SubstitutionNode):
+        return n.claimed_target or ""
+    return ""
+
+
+@dataclass
+class Occurrence:
+    id: int  # the call node id
+    entity: str  # vocabulary name
+    parent: int | None  # parent occurrence id (nearest modeled ancestor), None at the top
+    ancestors: list[str]  # vocabulary entities of every modeled ancestor, nearest first
+    ordinal: int  # earlier siblings of the same entity under the same parent
+    first: int
+    last: int  # the occurrence covers node ids / branch seqs in [first, last]
+    events: list[tuple[str, str, Any]] = field(default_factory=list)
+    # ("call", <entity>, <child occurrence id>) | ("branch", "site:<id>", <outcome>)
+    outcome: str = "unknown"
+
+
+def occurrences(ex: Execution, vocab: list[str]) -> dict[int, Occurrence]:
+    nodes = ex.nodes
+    name: dict[int, str] = {}
+    for n in nodes:
+        c = canonical(vocab, _node_symbol(n))
+        if c is not None:
+            name[n.id] = c
+    last = {n.id: n.id for n in nodes}
+    for n in reversed(nodes):  # a subtree's last id, children before parents
+        if n.parent is not None:
+            last[n.parent] = max(last[n.parent], last[n.id])
+    out: dict[int, Occurrence] = {}
+    counts: dict[tuple[int | None, str], int] = {}
+    for n in nodes:  # ids are creation order: parents come first
+        if n.id not in name:
+            continue
+        p = n.parent
+        chain: list[int] = []
+        while p is not None:
+            if p in name:
+                chain.append(p)
+            p = nodes[p].parent
+        parent = chain[0] if chain else None
+        k = (parent, name[n.id])
+        ordinal = counts.get(k, 0)
+        counts[k] = ordinal + 1
+        occ = Occurrence(
+            n.id, name[n.id], parent, [name[a] for a in chain], ordinal, n.id, last[n.id],
+            outcome=getattr(n, "outcome", "unknown"),
+        )  # fmt: skip
+        out[n.id] = occ
+    # events in time order: a child occurrence at its node id; a branch, which belongs to
+    # the occurrence of its own call node, at its seq (a branch at seq s precedes node s)
+    times: dict[int, list[tuple[int, int, tuple[str, str, Any]]]] = {o: [] for o in out}
+    for occ in out.values():
+        if occ.parent is not None:
+            times[occ.parent].append((occ.id, 1, ("call", occ.entity, occ.id)))
+    for b in ex.branches:
+        if b.node in out:
+            times[b.node].append((b.seq, 0, ("branch", f"site:{b.site}", b.outcome)))
+    for oid, evs in times.items():
+        out[oid].events = [e for _, _, e in sorted(evs, key=lambda t: (t[0], t[1]))]
+    return out
+
+
+@dataclass
+class Skeleton:
+    """Deterministic structure over several executions (see module doc)."""
+
+    executions: int = 0
+    # entity -> {ancestor entity | ROOT: number of executions where observed so}
+    ancestry: dict[str, dict[str, int]] = field(default_factory=dict)
+    # entity -> {nearest modeled parent | ROOT: executions}
+    parents: dict[str, dict[str, int]] = field(default_factory=dict)
+    # parent entity -> {(x, y): [occurrences with both, executions with both]} where x ≺ y
+    before: dict[str, dict[tuple[str, str], list[int]]] = field(default_factory=dict)
+    # parent entity -> pairs that interleave in at least one occurrence
+    interleaved: dict[str, set[frozenset[str]]] = field(default_factory=dict)
+    # parent entity -> family -> [occurrences containing it, max count in one occurrence]
+    families: dict[str, dict[str, list[int]]] = field(default_factory=dict)
+    # entity -> number of occurrences observed
+    seen: dict[str, int] = field(default_factory=dict)
+    # entity -> occurrences of it observed with each modeled ancestor (any depth)
+    inside_occ: dict[str, dict[str, int]] = field(default_factory=dict)
+    # site -> {entity | ROOT: evaluations}: the occurrence evaluating it and its ancestors
+    site_during: dict[str, dict[str, int]] = field(default_factory=dict)
+    # site -> {entity: evaluations}: the occurrence evaluating it in its own call
+    site_owner: dict[str, dict[str, int]] = field(default_factory=dict)
+    # parent entity -> repeated regions: {"members": [...], "head": family | None,
+    #   "within": {(x, y): segments} (x before y inside one repetition), "max_repeats": n}
+    regions: dict[str, list[dict[str, Any]]] = field(default_factory=dict)
+
+    def observed_inside(self, entity: str, parent: str) -> bool:
+        """Some observed occurrence of `entity` ran during an occurrence of `parent`
+        (`parent` among its modeled ancestors, any depth); ROOT: with no modeled ancestor."""
+        return self.ancestry.get(entity, {}).get(parent, 0) > 0
+
+    def always_during(self, entity: str, enclosing: str) -> bool:
+        """Every observed occurrence of `entity` ran during `enclosing` (and there is one)."""
+        n = self.seen.get(entity, 0)
+        return n > 0 and self.inside_occ.get(entity, {}).get(enclosing, 0) == n
+
+    def strictly_before(self, parent: str, x: str, y: str) -> bool:
+        """x ≺ y in every shown occurrence of `parent` containing both (and at least one)."""
+        return (x, y) in self.before.get(parent, {}) and frozenset((x, y)) not in (
+            self.interleaved.get(parent, set())
+        )
+
+
+def build_skeleton(executions: list[Execution], vocab: list[str]) -> Skeleton:
+    sk = Skeleton(executions=len(executions))
+    for ex in executions:
+        occs = occurrences(ex, vocab)
+        anc_seen: dict[str, set[str]] = {}
+        par_seen: dict[str, set[str]] = {}
+        pair_exec: dict[str, set[tuple[str, str]]] = {}
+        for o in occs.values():
+            sk.seen[o.entity] = sk.seen.get(o.entity, 0) + 1
+            io = sk.inside_occ.setdefault(o.entity, {})
+            for a in set(o.ancestors) or {ROOT}:
+                io[a] = io.get(a, 0) + 1
+            for kind, fam, _ in o.events:
+                if kind == "branch":
+                    so = sk.site_owner.setdefault(fam[5:], {})
+                    so[o.entity] = so.get(o.entity, 0) + 1
+                    sd = sk.site_during.setdefault(fam[5:], {})
+                    for a in {o.entity, *o.ancestors}:
+                        sd[a] = sd.get(a, 0) + 1
+            anc_seen.setdefault(o.entity, set()).update(o.ancestors or [ROOT])
+            par_seen.setdefault(o.entity, set()).add(
+                occs[o.parent].entity if o.parent is not None else ROOT
+            )
+            positions: dict[str, list[int]] = {}
+            for i, (_, fam, _) in enumerate(o.events):
+                positions.setdefault(fam, []).append(i)
+            fams = sk.families.setdefault(o.entity, {})
+            for fam, pos in positions.items():
+                rec = fams.setdefault(fam, [0, 0])
+                rec[0] += 1
+                rec[1] = max(rec[1], len(pos))
+            names = sorted(positions)
+            for i, x in enumerate(names):
+                for y in names[i + 1 :]:
+                    px, py = positions[x], positions[y]
+                    if max(px) < min(py):
+                        key = (x, y)
+                    elif max(py) < min(px):
+                        key = (y, x)
+                    else:
+                        sk.interleaved.setdefault(o.entity, set()).add(frozenset((x, y)))
+                        continue
+                    rec2 = sk.before.setdefault(o.entity, {}).setdefault(key, [0, 0])
+                    rec2[0] += 1
+                    pair_exec.setdefault(o.entity, set()).add(key)
+        for e, s in anc_seen.items():
+            for a in s:
+                sk.ancestry.setdefault(e, {})[a] = sk.ancestry.setdefault(e, {}).get(a, 0) + 1
+        for e, s in par_seen.items():
+            for p in s:
+                sk.parents.setdefault(e, {})[p] = sk.parents.setdefault(e, {}).get(p, 0) + 1
+        for parent, keys in pair_exec.items():
+            for key in keys:
+                sk.before[parent][key][1] += 1
+    # a pair observed in both orders (in different occurrences) is not an order
+    for parent, pairs in sk.before.items():
+        for x, y in list(pairs):
+            if (y, x) in pairs:
+                sk.interleaved.setdefault(parent, set()).add(frozenset((x, y)))
+    all_occs = [occurrences(ex, vocab) for ex in executions]
+    flat = [o for occs in all_occs for o in occs.values()]
+    for parent, pairs_i in sk.interleaved.items():
+        for members in _components(pairs_i):
+            sk.regions.setdefault(parent, []).append(_segment(parent, members, flat))
+    # a family that repeats inside one occurrence without interleaving with another is a
+    # one-member repeated region: it starts every repetition itself
+    for parent, fams in sk.families.items():
+        in_region = {m for r in sk.regions.get(parent, []) for m in r["members"]}
+        for fam, (_, max_n) in fams.items():
+            if max_n > 1 and fam not in in_region:
+                sk.regions.setdefault(parent, []).append(
+                    {"members": [fam], "head": fam, "within": {}, "max_repeats": max_n}
+                )
+    return sk
+
+
+def _components(pairs: set[frozenset[str]]) -> list[list[str]]:
+    """Families connected by interleaving: one repeated region each."""
+    adj: dict[str, set[str]] = {}
+    for pair in pairs:
+        a, b = sorted(pair)
+        adj.setdefault(a, set()).add(b)
+        adj.setdefault(b, set()).add(a)
+    seen: set[str] = set()
+    out: list[list[str]] = []
+    for start in sorted(adj):
+        if start in seen:
+            continue
+        comp, stack = [], [start]
+        while stack:
+            x = stack.pop()
+            if x in seen:
+                continue
+            seen.add(x)
+            comp.append(x)
+            stack.extend(adj[x] - seen)
+        out.append(sorted(comp))
+    return out
+
+
+def _segment(parent: str, members: list[str], occs: list[Occurrence]) -> dict[str, Any]:
+    """A repeated region's head is a member that starts every repetition: in every
+    occurrence of `parent`, the region's events begin with it and, between consecutive
+    heads, every other member appears at most once. With a head, the order of members
+    inside one repetition is recorded (x before y in every segment holding both). Without
+    one, only membership is known."""
+    mine = [o for o in occs if o.entity == parent]
+    seqs = [[f for _, f, _ in o.events if f in members] for o in mine]
+    seqs = [q for q in seqs if q]
+
+    def segments(head: str, seq: list[str]) -> list[list[str]] | None:
+        if seq[0] != head:
+            return None
+        segs: list[list[str]] = []
+        for f in seq:
+            if f == head:
+                segs.append([f])
+            elif f in segs[-1]:
+                return None
+            else:
+                segs[-1].append(f)
+        return segs
+
+    for head in members:
+        split = [segments(head, q) for q in seqs]
+        if not seqs or any(sp is None for sp in split):
+            continue
+        segs = [seg for sp in split for seg in sp or []]
+        within: dict[tuple[str, str], int] = {}
+        bad: set[tuple[str, str]] = set()
+        for seg in segs:
+            for i, x in enumerate(seg):
+                for y in seg[i + 1 :]:
+                    within[(x, y)] = within.get((x, y), 0) + 1
+                    bad.add((y, x))
+        return {
+            "members": members,
+            "head": head,
+            "within": {k: v for k, v in within.items() if k not in bad},
+            "max_repeats": max(len(sp or []) for sp in split),
+        }
+    return {"members": members, "head": None, "within": {}, "max_repeats": None}
+
+
+def _within_problems(e: str, fams: list[str], sk: Skeleton) -> list[str]:
+    out: list[str] = []
+    for region in sk.regions.get(e, []):
+        head, members = region["head"], region["members"]
+        if head is None:
+            continue
+        segs: list[list[str]] = []
+        for f in fams:
+            if f not in members:
+                continue
+            if f == head or not segs:
+                segs.append([f])
+            else:
+                segs[-1].append(f)
+        for seg in segs:
+            for i, x in enumerate(seg):
+                for y in seg[i + 1 :]:
+                    if x != y and (y, x) in region["within"]:
+                        out.append(
+                            f"inside {e}, one repetition: {x} predicted before {y}, observed after"
+                        )
+    return out
+
+
+def _executions_with(sk: Skeleton, parent: str, fam: str) -> int:
+    """Executions in which `fam` was observed inside `parent` (children: by ancestry; own
+    decision sites: by the site's owner)."""
+    if fam.startswith("site:"):
+        return sk.executions if parent in sk.site_owner.get(fam[5:], {}) else 0
+    return sk.parents.get(fam, {}).get(parent, 0)
+
+
+def placement_problems(pred_occurrences: list[dict[str, Any]], sk: Skeleton) -> list[str]:
+    """Problems of a predicted occurrence tree against the skeleton. Each predicted
+    occurrence: {"entity", "parent": index | None, "events": [(kind, family), ...]}.
+    Only entities the skeleton has observed are judged; nothing unobserved is assumed."""
+    problems: list[str] = []
+    for occ in pred_occurrences:
+        e = occ["entity"]
+        if sk.seen.get(e, 0) == 0:
+            continue
+        parent = pred_occurrences[occ["parent"]]["entity"] if occ["parent"] is not None else ROOT
+        if not sk.observed_inside(e, parent):
+            where = "outside every modeled caller" if parent == ROOT else f"during {parent}"
+            problems.append(f"{e} placed {where}, never observed so")
+        for kind, fam in occ["events"]:
+            during = sk.site_during.get(fam[5:]) if kind == "branch" else None
+            if during is not None and e not in during:
+                problems.append(f"{fam} predicted during {e}, never evaluated there")
+        fams = [f for _, f in occ["events"]]
+        # a family never observed repeating inside this entity (once at most in every
+        # occurrence, across >= 2 executions) must not be predicted repeating there; members of
+        # a repeated region are exempt (their count follows the supplied occurrences)
+        in_regions = {m for r in sk.regions.get(e, []) for m in r["members"]}
+        for fam in set(fams) - in_regions:
+            rec = sk.families.get(e, {}).get(fam)
+            if rec and rec[1] == 1 and fams.count(fam) > 1 and _executions_with(sk, e, fam) >= 2:
+                problems.append(
+                    f"{fam} predicted {fams.count(fam)} times inside one {e}, "
+                    "never observed repeating"
+                )
+        for i, x in enumerate(fams):
+            for y in fams[i + 1 :]:
+                if x != y and sk.strictly_before(e, y, x):
+                    problems.append(f"inside {e}: {x} predicted before {y}, observed after")
+        problems += _within_problems(e, fams, sk)
+    return sorted(set(problems))
+
+
+def render(sk: Skeleton, focus: list[str] | None = None) -> str:
+    """Text for a proposer: containment and phase order, with support."""
+    lines = [f"(from {sk.executions} shown execution(s))"]
+    for e in sorted(sk.parents):
+        if focus and e not in focus:
+            continue
+        par = ", ".join(f"{p} (in {n} exec)" for p, n in sorted(sk.parents[e].items()))
+        anc = ", ".join(f"{a} (in {n} exec)" for a, n in sorted(sk.ancestry.get(e, {}).items()))
+        lines.append(f"- {e}: {sk.seen.get(e, 0)} occurrence(s)")
+        lines.append(f"    nearest modeled caller: {par}")
+        lines.append(f"    runs during: {anc}")
+    for parent in sorted(sk.families):
+        if focus and parent not in focus:
+            continue
+        fams = sk.families[parent]
+        if len(fams) < 2:
+            continue
+        lines.append(f"\ninside {parent}:")
+        for fam, (n_occ, max_n) in sorted(fams.items()):
+            rep = f"repeated (up to {max_n} in one occurrence)" if max_n > 1 else "once"
+            lines.append(f"  family {fam}: in {n_occ} occurrence(s), {rep}")
+        for (x, y), (n_occ, n_ex) in sorted(sk.before.get(parent, {}).items()):
+            if sk.strictly_before(parent, x, y):
+                lines.append(f"  {x} BEFORE {y}  (all of the first before all of the second;")
+                lines.append(f"      {n_occ} occurrence(s), {n_ex} execution(s))")
+        for region in sk.regions.get(parent, []):
+            lines.append(f"  REPEATED REGION: {', '.join(region['members'])}")
+            if region["head"] is None:
+                lines.append("    (no member starts every repetition: only membership is known)")
+                continue
+            lines.append(
+                f"    each repetition starts with {region['head']} "
+                f"(up to {region['max_repeats']} repetitions in one occurrence); inside one:"
+            )
+            for (x, y), n in sorted(region["within"].items()):
+                lines.append(f"      {x} BEFORE {y}  ({n} repetition(s))")
+    return "\n".join(lines)
+
+
+def resolve(vocab: list[str], name: str) -> str:
+    """A genome/scenario entity name to the vocabulary name it denotes (itself if none)."""
+    hits = [v for v in vocab if v == name or v.endswith("." + name) or name.endswith("." + v)]
+    return max(hits, key=len) if hits else name
+
+
+def repetitions(
+    occs: dict[int, Occurrence], occ_id: int, members: list[str], head: str
+) -> list[dict[str, Any]]:
+    """The observed repetitions of a repeated region inside one occurrence: the region's
+    member events split at each `head` event. Each repetition lists its own events, the
+    occurrences it contains (child calls and all their modeled descendants), and every
+    branch evaluation inside it (the enclosing call's own, and those of the contained
+    occurrences). Its identity is its ordinal."""
+    reps: list[dict[str, Any]] = []
+    for kind, fam, ref in occs[occ_id].events:
+        if fam not in members:
+            continue
+        if fam == head or not reps:
+            reps.append({"events": [], "occurrences": [], "branches": []})
+        rep = reps[-1]
+        rep["events"].append((kind, fam, ref))
+        if kind == "branch":
+            rep["branches"].append((fam[5:], ref))
+        else:
+            rep["occurrences"].append(ref)
+    children: dict[int, list[int]] = {}
+    for o in occs.values():
+        if o.parent is not None:
+            children.setdefault(o.parent, []).append(o.id)
+    for rep in reps:
+        stack = list(rep["occurrences"])
+        seen: list[int] = []
+        while stack:
+            o = stack.pop(0)
+            seen.append(o)
+            rep["branches"] += [(f[5:], v) for k, f, v in occs[o].events if k == "branch"]
+            stack.extend(children.get(o, []))
+        rep["occurrences"] = seen
+    return reps

diffgenome-0.1.0.dist-info/METADATA

@@ -0,0 +1,139 @@
+Metadata-Version: 2.5
+Name: diffgenome
+Version: 0.1.0
+Summary: Runtime evidence for code changes: run a repository's existing tests against a change and report what actually executed.
+Author: karims
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: change impact,code review,runtime evidence,test mapping,tracing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Provides-Extra: genome
+Description-Content-Type: text/markdown
+
+# diffgenome
+
+**Runtime evidence for code changes.** diffgenome runs a repository's *existing* tests against a
+change, records what actually executes, and reports it as a small, versioned JSON contract
+(`diffgenome-runtime/1`) that a reviewer or a review tool can consume.
+
+It answers questions static analysis and models can only guess at:
+
+- Which changed functions did the existing tests actually execute, and in **exactly which tests
+  and subtests**?
+- Through which call chains did execution reach the changed code, including dynamic dispatch,
+  registries and decorators the static call graph cannot follow?
+- Which **outcomes** of each changed condition were observed (true / false / never evaluated)?
+- How did the changed code exit (returned, returned-error, raised `<type>`), and with which
+  argument type shapes?
+- Where did observation stop: mocks, fakes, eager task runners, external systems?
+- Which changed behavior did **no existing test exercise**?
+
+No model is involved. Everything reported was observed, or is a static decision site needed to
+place an observed outcome on a changed line.
+
+## Install
+
+```bash
+pip install diffgenome
+```
+
+Python 3.12+ (the Python tracer uses `sys.monitoring`). No runtime dependencies. Language
+support:
+
+| target | tests run with | needs |
+|---|---|---|
+| Python | pytest | the target's virtualenv (`--python`) |
+| Go | `go test` | a Go toolchain with the module's dependencies available offline |
+| Node / TypeScript | Jest | the target's `node_modules` (TypeScript is taken from there, or from `DIFFGENOME_NODE_PATH`) |
+
+Tests run inside a disposable copy of the repository (never the checkout itself), under a
+sandbox with no network unless `--allow-loopback` is given for local test services.
+
+## Use
+
+```bash
+# Python: the change between two revisions, the tests that cover it
+diffgenome change --runtime python --repo . --python .venv/bin/python \
+  --source-root src --test-root tests --diff main..HEAD --out .diffgenome/run
+
+# Go
+diffgenome change --runtime go --repo . --test-root api --tests ./api/ \
+  --mock-dir db/mock --diff main..HEAD --out .diffgenome/run
+
+# analyze a revision other than the checkout, without touching the checkout
+diffgenome change ... --rev <head> --diff <base>..<head>
+```
+
+The result is `.diffgenome/run/diffgenome-change.json`. Its `runtime` section is the contract:
+
+```jsonc
+{
+  "format": "diffgenome-runtime/1",
+  "universe": { "test_scope": "tests/", "executions": 55, "passed": 55, "failed": 0, "tests": [...] },
+  "changed_functions": [{
+    "symbol": "py:app.rows.handler.RowHandler.restore_row", "file": "...", "line": 3221, "origin": "repo",
+    "executed": true, "calls": 3, "tests": ["...::test_editor_can_redo_create_row", "..."],
+    "exits": { "returned": 3 }, "raised_inside": {}, "arg_shapes": [[["user", "User"], ["row_id", "int"]]],
+    "callers": [{ "symbol": "...DeleteRowActionType.undo", "calls": 2, "tests": 2 }],
+    "stand_ins": {},
+    "changed_sites": [{ "line": 3240, "predicate": "view is None", "true": 0, "false": 3 }]
+  }],
+  "edges": [{ "caller": {...}, "callee": {...}, "executions": 2, "tests": [...], "tests_total": 2 }],
+  "boundaries": [{ "kind": "external", "caller": "...", "target": "celery.canvas._chord" }],
+  "gaps": [
+    { "kind": "function_not_executed", "symbol": "...TrashHandler.restore_item" },
+    { "kind": "branch_outcome_not_observed", "line": 217, "predicate": "not fields", "outcome": "true" },
+    { "kind": "stand_in_reached", "target": "...FormulaFieldType.run_periodic_update" }
+  ],
+  "not_reported": ["values (only type shapes and opaque fingerprints are recorded)",
+                   "except-handler coverage (handlers are not decision sites)", "per-line coverage"]
+}
+```
+
+Every "not executed" is relative to `universe.test_scope`: the tests that were run. Locations
+carry `origin` (`repo`, `test`, `external`) so a consumer can tell application frames from test
+frames.
+
+The artifact's other sections (`nodes`, `edges`, `executions`, `boundaries`, `facts`) describe
+the observed behavioral neighborhood of the change; `report.md` and `behavioral-map.md` render
+it for people.
+
+## Consumers
+
+[Sydes](https://pypi.org/project/sydes/) uses the runtime contract for change verification:
+observed call edges join its call graph for reachability, the exact tests per changed function
+become supporting test evidence, the gaps become verification gaps, and AI recovery is only asked
+about what the runtime evidence cannot answer. Sydes depends on the contract alone, not on
+diffgenome internals.
+
+## Optional: the Behavioral Genome (research)
+
+`diffgenome genome` builds a semantic layer on top of the runtime evidence: a model proposes
+behavioral rules (variables, decisions, transitions), and a deterministic checker keeps only the
+rules the observed executions verify or support. It is optional research code: nothing in
+`diffgenome change` or the runtime contract uses it, and it needs no extra packages (an OpenAI
+key only for live proposals, read from `OPENAI_API_KEY` or `~/.config/diffgenome/openai_api_key`).
+Install with `pip install "diffgenome[genome]"` to state the intent. See
+`docs/research-overview.md` and `docs/runtime-evaluation.md` for what has and has not been
+shown to work.
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check src tests && uv run mypy src
+```
+
+## License
+
+Apache-2.0. See [LICENSE](LICENSE).

diffgenome-0.1.0.dist-info/RECORD

@@ -0,0 +1,53 @@
+diffgenome/__init__.py,sha256=uHLh7NN0pCqtu9aLkiP3A_0mXjWFhB64vu1QmyBGc08,253
+diffgenome/__main__.py,sha256=KKvfmaKIB1aX9Q5DxuAbczJoIHQKZtzWFLTZqdQTYQ4,9419
+diffgenome/ambiguity.py,sha256=eCameI11iaCAa9d8otPcgXwr1EY6zKZf0vSZdPLqPFc,5133
+diffgenome/api.py,sha256=y3HnwFfLRn0jfBWyvncEWTObi8WXiDaAlfE3bAIUhaU,2327
+diffgenome/change.py,sha256=ZudIM5-7HE0i9qxsV0iHNNRrqLzZI534wNWv5ifbE9g,2858
+diffgenome/change_artifact.py,sha256=LeIWGqw7g93pv8QG54WrmpyhfplKa1YdP5DWFF3vXWA,12320
+diffgenome/compose.py,sha256=r_HnkvP-Q9Uhj8mEXN8pQyBHIUckS84VWh8mxNmYwT0,20701
+diffgenome/dependence.py,sha256=26erLyayHn2_8g-PCFi4ATKzd5zw_2hIfompRARJvcY,11240
+diffgenome/evaluate.py,sha256=G3bucl2YTjJ4PSvGcTBX8Lvsw8efrbl-iypRxOYHjp0,26999
+diffgenome/genome.py,sha256=tDujpj1yNVt1vrCmbLRrt1gPEOBcHHCCuKi_LLN9XKI,41337
+diffgenome/genome_pipeline.py,sha256=IO0CJQTxqmCmhvfhPnYMJBPqpYxPzjeRuEMtNEB-mls,27392
+diffgenome/genome_prompt.py,sha256=RNMI-27Zxyd2KYkvPCORhwIkeRY46o7UrRddtOfnXJQ,12565
+diffgenome/genome_state.py,sha256=YKoDGeiRJAHiXrBOyGVWYj3IIMINt0SPFx77WznRm-M,95495
+diffgenome/graph.py,sha256=dapLj9RrC4MZVHuIX5_PSGo3m_f5E_rv5mnUR1k-4ho,17505
+diffgenome/llm.py,sha256=sEbrWQh0BU3q_MFtRznFXYC6-EJiEl-tYriQv-J-40c,7658
+diffgenome/model.py,sha256=n0SRTcJN3sVa1Xb6_5im5fXAwydY-UT7YelhAxL5rPY,16892
+diffgenome/mvp.py,sha256=w_4nIRvkVBo894IMkogzlOOQAwdVJDd4rynIUOn5a7M,18259
+diffgenome/probe.py,sha256=z8bgXLb03vY7VuP6j5nE_ohXK2IkVLCnUD1vTSwWJ4c,21632
+diffgenome/projection.py,sha256=aq3eMJDn0agMzZp0UhsKXemQi7wJwu1PKGVOrie4Q-0,13622
+diffgenome/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+diffgenome/render.py,sha256=FUrgzduqrW-l5BClD2GsqfDLaI3-gOYbYzs7Z2bDooM,4290
+diffgenome/report.py,sha256=qVdkIihAcT2f7oLapwlyvsuhOOi4XcBB7DY__HpoXAo,14511
+diffgenome/resolve.py,sha256=8Mi-t3odMfyo0gbSLBYWOoir7rkzo1-orH2PPBt8v3g,1614
+diffgenome/runtime.py,sha256=NH78fyfOQLKBTYyjYEcB4ygCzW4BajjF5Vh9lN3jMsE,2863
+diffgenome/runtime_evidence.py,sha256=yT2lmcIQFfpevMTWBY0pEv-e-Ky1wZNVYQ8Z0BPOj1E,10694
+diffgenome/sandbox.py,sha256=UcXam5kX3NHNvRsr3TkyEJw7juZMxRKidq3WBUiMFaE,5954
+diffgenome/serialize.py,sha256=r_TwAV8nG4MGouXPaukQywvk1_cCeFUprmpYCccVrN8,2891
+diffgenome/sites.py,sha256=sBIFhpXCROrIWVgnHf-h_wFG4vIZeRgYY_fjWsXoZ8Q,782
+diffgenome/static_types.py,sha256=eC7Q_QdsI6OqZr20dEJpXQw24q6LcdBrrB9hAiV9UUo,2526
+diffgenome/structure.py,sha256=KTS1F7u6ePDCmC6rcnQm6IdNEwZHwZlW2kJw5Fw-TU0,21631
+diffgenome/_collectors/go/go.mod,sha256=J6kKccdD9gBbwDUOF-PhWiHINXd0OaB3VFfvK7kI-OE,46
+diffgenome/_collectors/go/dg/dg.go,sha256=KVDTghtEcEHO7YSOLJV6y0f7bar9AKTfX9Z9YLXRrXU,15746
+diffgenome/_collectors/go/instrument/facts.go,sha256=4WMxZQ-U06JQ_wY63gjY_4w1wiLRCFRsDThfAl5TpVc,9918
+diffgenome/_collectors/go/instrument/main.go,sha256=nYXJfltYmmPPKUcRwmBm_4zSLqpT3eDCygC3WENnI5s,16160
+diffgenome/_collectors/node/instrument.js,sha256=CuY3N76_BteLS5eoBpt2MUxCZaNie96lhaGER7MnJ2E,15831
+diffgenome/_collectors/node/jest-setup.js,sha256=8UR3tTFt3pdBVoBeIvZgymkxQL0DoyjbA11lfIas4ZY,1633
+diffgenome/_collectors/node/package-lock.json,sha256=1xmoRedhHsUgusGKpO4INkAd9nzc1vzhG6D2llTZok4,1024
+diffgenome/_collectors/node/package.json,sha256=wEJ3sTIAtcMR280U0Ox7cPZyWL0i06Cx2rcb3pOwpkU,301
+diffgenome/_collectors/node/runtime.js,sha256=M3ed2lgvPxsjn6CanbgRLjZ1isEABuJ9a4fFQCL36oQ,15866
+diffgenome/collect/__init__.py,sha256=Xj42bDNrmR6XK1RWL8t1-ITtQMTecSu1GT-YhC4Od5w,174
+diffgenome/collect/go_test.py,sha256=8zhYoDNPpSqdgbVyGxCsLcC9g-VTjH-VYJoIbqCW8Ig,11387
+diffgenome/collect/node_jest.py,sha256=nWHIe6XWIRA82fnBAv-HvuYUGBkTdC0o1QfySRLozLA,13245
+diffgenome/collect/py_monitoring.py,sha256=P8f6i1OZjPEtGz6bY4pyRrYgPvCCYTQICdgfrp631Rs,43498
+diffgenome/collect/py_runtime.py,sha256=IQg5Zrtp-dZh358Edt_lv7mLGJl62l1IPZaZn39AlTw,5184
+diffgenome/collect/py_symbols.py,sha256=ta3AiA9ZKzwYZnR3CDAo6zhzdOBH4W0Uhi2vband7OY,10004
+diffgenome/collect/pytest_plugin.py,sha256=-74eLK9z53s1FaBC9k3dkG7c8jAvOynL_St6KwToHck,5329
+diffgenome/frontends/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+diffgenome/frontends/python_ir.py,sha256=E4bz9GGMQepZTlcxlSdWMu23pGzjNCBDdee8ye_jTTw,12993
+diffgenome-0.1.0.dist-info/METADATA,sha256=GW4Fx7NXe8mmMq4cH_LpXnBIXDdiXKwCo3jwIzBMSRI,6227
+diffgenome-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+diffgenome-0.1.0.dist-info/entry_points.txt,sha256=X2ICPUevqUGSr_AYBw33wpDApTEMl3hOnr6ib5PxN7Q,56
+diffgenome-0.1.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+diffgenome-0.1.0.dist-info/RECORD,,

diffgenome-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

diffgenome-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+diffgenome = diffgenome.__main__:main