@suss/adapter-python 0.21.1 → 0.22.1

package/dist/index.js

@@ -765,19 +765,399 @@ import {
   mapReading,
   unreadableReading,
   valueToReadFurtherFrom,
-  walkDescendants,
+  walkDescendants as walkDescendants2,
   writtenReading
 } from "@suss/extractor";
 
+// src/envReads.ts
+import { runtimeConfigBinding } from "@suss/behavioral-ir";
+import { SKIP_CHILDREN, walkDescendants } from "@suss/extractor";
+var PYTHON_ENV_RECOGNITION = "python-env";
+var DEFERRED_BODY_TYPES = /* @__PURE__ */ new Set(["function_definition", "lambda"]);
+function envReadEffects(root, module) {
+  const effects = [];
+  const startScope = module.scopeFor.get(root.id) ?? module.moduleScope;
+  walkDescendants(root, startScope, {
+    at: (node, scope) => {
+      const read = envReadAt(node, scope);
+      if (read !== null) {
+        effects.push(configReadEffect(read));
+      }
+    },
+    into: (node, scope) => {
+      if (DEFERRED_BODY_TYPES.has(node.type)) {
+        return SKIP_CHILDREN;
+      }
+      return module.scopeFor.get(node.id) ?? scope;
+    }
+  });
+  return effects;
+}
+function configReadEffect(read) {
+  return {
+    type: "interaction",
+    binding: runtimeConfigBinding({
+      recognition: PYTHON_ENV_RECOGNITION,
+      deploymentTarget: "lambda",
+      instanceName: "<unknown>"
+    }),
+    callee: `os.environ["${read.name}"]`,
+    interaction: {
+      class: "config-read",
+      name: read.name,
+      defaulted: read.defaulted
+    }
+  };
+}
+function envReadAt(node, scope) {
+  if (node.type === "subscript") {
+    return subscriptRead(node, scope);
+  }
+  if (node.type === "call") {
+    return callRead(node, scope);
+  }
+  return null;
+}
+function subscriptRead(node, scope) {
+  const value = field(node, "value");
+  const index = field(node, "subscript");
+  if (value === null || index === null || !isEnviron(value, scope)) {
+    return null;
+  }
+  const name = stringLiteralValue(index);
+  if (name === null || isAssignedTo(node)) {
+    return null;
+  }
+  return { name, defaulted: isDefaultedAt(node) };
+}
+function isAssignedTo(node) {
+  const parent = node.parent;
+  if (parent === null) {
+    return false;
+  }
+  if (parent.type === "delete_statement") {
+    return true;
+  }
+  return (parent.type === "assignment" || parent.type === "augmented_assignment") && field(parent, "left")?.id === node.id;
+}
+function callRead(node, scope) {
+  const callee = field(node, "function");
+  const args = field(node, "arguments");
+  if (callee === null || args === null || !isEnvGetter(callee, scope)) {
+    return null;
+  }
+  const positional = args.namedChildren.filter(
+    (arg) => arg !== null && arg.type !== "keyword_argument"
+  );
+  const name = positional[0] === void 0 ? null : stringLiteralValue(positional[0]);
+  if (name === null) {
+    return null;
+  }
+  const keywords = args.namedChildren.filter(
+    (arg) => arg !== null && arg.type === "keyword_argument"
+  );
+  const hasDefault = positional.length > 1 || keywords.some((arg) => field(arg, "name")?.text === "default");
+  return { name, defaulted: hasDefault || isDefaultedAt(node) };
+}
+function isEnvGetter(callee, scope) {
+  if (callee.type === "attribute") {
+    const object2 = field(callee, "object");
+    const attribute = field(callee, "attribute")?.text;
+    if (object2 === null) {
+      return false;
+    }
+    if (attribute === "get") {
+      return isEnviron(object2, scope);
+    }
+    return attribute === "getenv" && isOsModule(object2, scope);
+  }
+  return isImportedFromOs(callee, scope, "getenv");
+}
+function isEnviron(node, scope) {
+  if (node.type === "attribute") {
+    const object2 = field(node, "object");
+    return object2 !== null && field(node, "attribute")?.text === "environ" && isOsModule(object2, scope);
+  }
+  return isImportedFromOs(node, scope, "environ");
+}
+function isOsModule(node, scope) {
+  if (node.type !== "identifier") {
+    return false;
+  }
+  const binding = resolveName(scope, node.text);
+  return binding?.kind === "import" && binding.module === "os" && binding.relativeLevel === 0;
+}
+function isImportedFromOs(node, scope, name) {
+  if (node.type !== "identifier") {
+    return false;
+  }
+  const binding = resolveName(scope, node.text);
+  return binding?.kind === "importFrom" && binding.module === "os" && binding.relativeLevel === 0 && binding.importedName === name;
+}
+function isDefaultedAt(node) {
+  let child = node;
+  let parent = node.parent;
+  while (parent !== null) {
+    if (parent.type === "parenthesized_expression") {
+      child = parent;
+      parent = parent.parent;
+      continue;
+    }
+    if (parent.type !== "boolean_operator" || field(parent, "operator")?.text !== "or") {
+      return false;
+    }
+    if (field(parent, "left")?.id === child.id) {
+      return true;
+    }
+    child = parent;
+    parent = parent.parent;
+  }
+  return false;
+}
+
 // src/facts/resolve.ts
-import { deriveOnDemand, evaluate } from "@suss/datalog";
+import { deriveOnDemand, evaluate as evaluate2 } from "@suss/datalog";
 
 // ../../resolution/dist/index.js
 import { ruleLabel } from "@suss/datalog";
+import { Database, evaluate, proofOf, witnesses } from "@suss/datalog";
 import { constant, lit, rule, variable as v } from "@suss/datalog";
-function joinMountedPath(prefix, path4) {
+function exportTrail(proof, describe3) {
+  if (proof.kind !== "derived") {
+    return [];
+  }
+  const name = ruleLabel(proof.rule);
+  if (name === "re-export") {
+    const [m, n, m2, n2] = proof.premises[0].tuple;
+    return [
+      `${describe3(m)} takes ${String(n)} from ${describe3(m2)}, where it is called ${String(n2)}`,
+      ...exportTrail(proof.premises[1], describe3)
+    ];
+  }
+  if (name === "re-export all") {
+    const [m, m2] = proof.premises[0].tuple;
+    return [
+      `${describe3(m)} forwards everything ${describe3(m2)} exports`,
+      ...exportTrail(proof.premises[1], describe3)
+    ];
+  }
+  return [];
+}
+function argumentReason(proof, describe3) {
+  const [, p, a] = proof.tuple;
+  if (proof.kind !== "derived") {
+    return `${describe3(p)} is a parameter, and a call passes it ${describe3(a)}`;
+  }
+  const f = proof.premises[0].tuple[0];
+  return `${describe3(p)} is a parameter of ${describe3(f)}, and a call passes it ${describe3(a)}`;
+}
+var DEFAULT_PHRASES = {
+  alias: ({ tuple: tuple2, describe: describe3 }) => ({
+    reason: `${describe3(tuple2[0])} is declared as ${describe3(tuple2[1])}`
+  }),
+  "last write": ({ tuple: tuple2, describe: describe3 }) => ({
+    reason: `${describe3(tuple2[0])} is written more than once, and the last write leaves it as ${describe3(tuple2[1])}`
+  }),
+  fallback: ({ tuple: tuple2, describe: describe3 }) => ({
+    reason: `${describe3(tuple2[0])} is a fallback expression, and ${describe3(tuple2[1])} is the branch that resolves`
+  }),
+  import: ({ tuple: tuple2, premises, describe: describe3 }) => {
+    const [, module, name] = premises[0].tuple;
+    return {
+      reason: `${describe3(tuple2[0])} is imported from ${describe3(module)} under the name ${String(name)}`,
+      notes: exportTrail(premises[1], describe3)
+    };
+  },
+  argument: ({ premises, describe: describe3 }) => ({
+    reason: argumentReason(premises[0], describe3)
+  }),
+  "property read": ({ tuple: tuple2, premises, describe: describe3 }) => {
+    const [, object2, name] = premises[0].tuple;
+    const contains = premises[2];
+    const inherited = contains.kind === "derived" && contains.premises.length > 1;
+    return {
+      reason: `${describe3(tuple2[0])} reads ${String(name)} off ${describe3(object2)}, which contains ${describe3(tuple2[1])}`,
+      notes: inherited ? [`${String(name)} comes from a base class`] : []
+    };
+  },
+  "class instance": ({ tuple: tuple2, premises, describe: describe3, inline }) => ({
+    reason: `${describe3(tuple2[0])} makes an instance of ${describe3(tuple2[1])}`,
+    notes: inline(premises[1])
+  }),
+  "factory unwrap": ({ tuple: tuple2, premises, describe: describe3, inline }) => {
+    const factory = premises[1].tuple[1];
+    return {
+      reason: `${describe3(tuple2[0])} calls ${describe3(factory)}, a factory that passes its argument through, so it comes down to ${describe3(tuple2[1])}`,
+      notes: inline(premises[1])
+    };
+  },
+  "declared wrapper": ({ tuple: tuple2, premises, describe: describe3 }) => {
+    const callee = String(premises[0].tuple[1]);
+    const module = String(premises[2].tuple[1]);
+    const argument = String(premises[1].tuple[1]);
+    return {
+      reason: `${describe3(tuple2[0])} calls ${callee} from ${module}, which passes argument ${argument} through, so it comes down to ${describe3(tuple2[1])}`,
+      assumptions: [
+        `a pack declares that ${callee} from ${module} passes argument ${argument} through to its result`
+      ]
+    };
+  },
+  "call result": ({ tuple: tuple2, premises, describe: describe3, inline }) => {
+    const invokes = premises[0];
+    const invoked = invokes.tuple[1];
+    const calleeWalks = invokes.kind === "derived" ? invokes.premises.filter(
+      (premise) => premise.kind === "derived" && (premise.relation === "comesTo" || premise.relation === "givesBack")
+    ) : [];
+    return {
+      reason: `${describe3(tuple2[0])} runs ${describe3(invoked)}, which returns ${describe3(tuple2[1])}`,
+      notes: calleeWalks.flatMap((premise) => inline(premise))
+    };
+  }
+};
+var CHAIN_RELATIONS = /* @__PURE__ */ new Set([
+  "resolves",
+  "comesTo",
+  "givesBack",
+  "isWrittenAs",
+  "comesFrom",
+  "reaches",
+  "stepsTo"
+]);
+function inlineChain(proof, state) {
+  const explained = explainResolutionProof(proof, {
+    describe: state.describe,
+    phrases: state.phrases
+  });
+  if (explained === null || explained.steps.length === 0) {
+    return [];
+  }
+  if (explained.truncated) {
+    state.truncated = true;
+  }
+  return explained.steps.map((step) => step.reason);
+}
+function stepFrom(proof, state) {
+  const name = ruleLabel(proof.rule);
+  const phrase = state.phrases[name];
+  const from = proof.tuple[0];
+  const to = proof.tuple[1];
+  if (phrase === void 0) {
+    return {
+      from,
+      to,
+      rule: name,
+      reason: `${state.describe(from)} steps to ${state.describe(to)} (${name})`,
+      notes: [],
+      assumptions: []
+    };
+  }
+  const said = phrase({
+    tuple: proof.tuple,
+    premises: proof.premises,
+    describe: state.describe,
+    inline: (nested) => inlineChain(nested, state)
+  });
+  return {
+    from,
+    to,
+    rule: name,
+    reason: said.reason,
+    notes: said.notes ?? [],
+    assumptions: said.assumptions ?? []
+  };
+}
+function importStep(proof, state) {
+  const [x, module, name] = proof.tuple;
+  return {
+    from: x,
+    to: module,
+    rule: "import",
+    reason: `${state.describe(x)} is imported from ${state.describe(module)} under the name ${String(name)}`,
+    notes: [],
+    assumptions: []
+  };
+}
+var flattenInto = (proof, state) => {
+  if (proof.kind === "truncated") {
+    state.truncated = true;
+    return;
+  }
+  if (proof.kind !== "derived") {
+    return;
+  }
+  const relation = proof.relation;
+  if (relation === "stepsTo") {
+    state.steps.push(stepFrom(proof, state));
+    return;
+  }
+  if (relation === "reaches") {
+    for (const p of proof.premises) {
+      flattenInto(p, state);
+    }
+    return;
+  }
+  if (relation === "comesFrom") {
+    if (proof.premises.length === 2) {
+      flattenInto(proof.premises[0], state);
+      state.steps.push(importStep(proof.premises[1], state));
+    } else {
+      state.steps.push(importStep(proof.premises[0], state));
+    }
+    return;
+  }
+  for (const p of proof.premises) {
+    if (p.kind === "derived" && (p.relation === "reaches" || p.relation === "comesTo")) {
+      flattenInto(p, state);
+    }
+    if (p.kind === "truncated") {
+      state.truncated = true;
+    }
+  }
+};
+function explainResolutionProof(proof, options) {
+  if (proof.kind === "absence") {
+    return null;
+  }
+  if (proof.kind === "derived" && !CHAIN_RELATIONS.has(proof.relation)) {
+    return null;
+  }
+  const state = {
+    steps: [],
+    truncated: proof.kind === "truncated",
+    describe: options.describe,
+    phrases: { ...DEFAULT_PHRASES, ...options.phrases }
+  };
+  flattenInto(proof, state);
+  const atoms = proof.kind === "fact" || proof.kind === "truncated" ? [proof.tuple[0]] : [proof.tuple[0], ...state.steps.map((step) => step.to)];
+  return {
+    atoms,
+    steps: state.steps,
+    assumptions: state.steps.flatMap((step) => step.assumptions),
+    truncated: state.truncated
+  };
+}
+function renderExplanation(explanation, describe3) {
+  const lines = [];
+  if (explanation.steps.length > 0) {
+    lines.push(explanation.atoms.map((atom) => describe3(atom)).join(" -> "));
+  }
+  for (const step of explanation.steps) {
+    lines.push(`  ${step.reason}`);
+    for (const note of step.notes) {
+      lines.push(`    ${note}`);
+    }
+  }
+  for (const assumption of explanation.assumptions) {
+    lines.push(`  assuming ${assumption}`);
+  }
+  if (explanation.truncated) {
+    lines.push("  the chain goes on past the proof depth cap");
+  }
+  return lines;
+}
+function joinMountedPath(prefix, path6) {
   const trimmed = prefix.endsWith("/") ? prefix.slice(0, -1) : prefix;
-  return trimmed === "" ? path4 : trimmed + path4;
+  return trimmed === "" ? path6 : trimmed + path6;
 }
 function mountPathsOf(edges, childId) {
   return pathsOf(edges, /* @__PURE__ */ new Map(), childId, /* @__PURE__ */ new Set());
@@ -814,6 +1194,88 @@ function pathsOf(edges, memo, childId, visiting) {
   memo.set(childId, result);
   return result;
 }
+function explainResolvedKey(options) {
+  const { db, rules, key, locate, displayPath } = options;
+  const proofDb = new Database();
+  let baseFacts = 0;
+  for (const relation of db.relationNames()) {
+    for (const tuple2 of db.facts(relation)) {
+      proofDb.add(relation, tuple2);
+      baseFacts++;
+    }
+  }
+  const started = performance.now();
+  evaluate(proofDb, rules, witnesses);
+  const evaluateMs = performance.now() - started;
+  const derivedFacts = proofDb.relationNames().reduce((count, relation) => count + proofDb.size(relation), 0) - baseFacts;
+  const targets = new Set(
+    proofDb.lookup("resolves", 0, key).map((tuple2) => String(tuple2[1]))
+  );
+  if (targets.size !== 1) {
+    return null;
+  }
+  const target = [...targets][0];
+  const proof = proofOf(
+    proofDb,
+    "resolves",
+    [key, target],
+    options.maxDepth === void 0 ? {} : { maxDepth: options.maxDepth }
+  );
+  const describe3 = (atom) => {
+    const location = locate(String(atom));
+    return location === null ? displayPath(String(atom)) : `${location.name} (${location.file}:${location.line})`;
+  };
+  const explanation = explainResolutionProof(proof, {
+    describe: describe3,
+    ...options.phrases === void 0 ? {} : { phrases: options.phrases }
+  });
+  if (explanation === null) {
+    return null;
+  }
+  const targetLocation = locate(target);
+  if (targetLocation === null) {
+    return null;
+  }
+  return {
+    explanation,
+    chain: explanation.atoms.map(describe3),
+    lines: renderExplanation(explanation, describe3),
+    target: targetLocation,
+    stats: { baseFacts, derivedFacts, evaluateMs }
+  };
+}
+var NO_PLACEHOLDERS = /* @__PURE__ */ new Set();
+function singleAnswers(rows, placeholders = NO_PLACEHOLDERS) {
+  const candidates = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    const key = String(row[0]);
+    const answer = String(row[1]);
+    if (answer === key) {
+      continue;
+    }
+    const set2 = candidates.get(key) ?? /* @__PURE__ */ new Set();
+    set2.add(answer);
+    candidates.set(key, set2);
+  }
+  const settled = /* @__PURE__ */ new Map();
+  for (const [key, set2] of candidates) {
+    const answers = withoutPlaceholders(set2, placeholders);
+    if (answers.length === 1) {
+      settled.set(key, answers[0]);
+    }
+  }
+  return settled;
+}
+function placeholderValues(db) {
+  return new Set(db.facts("placeholderValue").map((row) => String(row[0])));
+}
+function withoutPlaceholders(answers, placeholders) {
+  const kept = [...answers].filter((answer) => !placeholders.has(answer));
+  if (kept.length === 0) {
+    return [...answers];
+  }
+  return kept;
+}
 var VALUE_STEP = constant("value");
 var NAMESPACE_IMPORT_NAME = "*";
 var NAMESPACE_IMPORT = constant(NAMESPACE_IMPORT_NAME);
@@ -1005,6 +1467,18 @@ var RESOLUTION_RULES = [
     [v("x"), v("z")],
     [lit("reaches", v("x"), v("z"), VALUE_STEP), lit("objectValue", v("z"))]
   ),
+  // A call is written as whatever its callee's return value is written
+  // as. Unlike `comesTo`, this has nothing to protect: which expression
+  // a value was written as does not compete with unwrapping it.
+  rule(
+    "isWrittenAs",
+    [v("x"), v("z")],
+    [
+      lit("invokes", v("x"), v("f")),
+      lit("returnsValue", v("f"), v("ret")),
+      lit("isWrittenAs", v("ret"), v("z"))
+    ]
+  ),
   // What one call site put in a parameter, told apart from what the
   // other callers passed.
   rule(
@@ -1552,23 +2026,33 @@ function resolveCalls(db, callKeys) {
   for (const callKey of callKeys) {
     db.add("wanted", [callKey]);
   }
-  evaluate(db, RESOLUTION_PROGRAM.rules);
+  evaluate2(db, RESOLUTION_PROGRAM.rules);
 }
 function subjectConstructions(db, valueKeys) {
   const found = /* @__PURE__ */ new Map();
   if (valueKeys.length === 0) {
     return found;
   }
-  for (const valueKey2 of valueKeys) {
-    db.add("wantedSubject", [valueKey2]);
-  }
-  evaluate(db, RESOLUTION_PROGRAM.rules);
-  const writtenAs = /* @__PURE__ */ new Map();
-  for (const row of db.facts("wantedSubjectWritten")) {
-    const written = writtenAs.get(String(row[0])) ?? /* @__PURE__ */ new Set();
-    written.add(String(row[1]));
-    writtenAs.set(String(row[0]), written);
+  const askSubjects = (keys) => {
+    for (const key of keys) {
+      db.add("wantedSubject", [key]);
+    }
+    evaluate2(db, RESOLUTION_PROGRAM.rules);
+  };
+  askSubjects(valueKeys);
+  const placeholders = placeholderValues(db);
+  const written = singleAnswers(db.facts("wantedSubjectWritten"), placeholders);
+  const calls = new Set(db.facts("call").map((row) => String(row[0])));
+  const throughCalls = new Set(
+    [...written.values()].filter((candidate) => calls.has(candidate))
+  );
+  if (throughCalls.size > 0) {
+    askSubjects(throughCalls);
   }
+  const writtenThroughCall = singleAnswers(
+    db.facts("wantedSubjectWritten"),
+    placeholders
+  );
   const origins = /* @__PURE__ */ new Map();
   for (const row of db.facts("wantedSubjectConstruction")) {
     const key = `${String(row[0])}|${String(row[1])}`;
@@ -1577,12 +2061,14 @@ function subjectConstructions(db, valueKeys) {
     origins.set(key, listed);
   }
   for (const valueKey2 of valueKeys) {
-    const written = writtenAs.get(valueKey2);
-    if (written === void 0 || written.size !== 1) {
+    const direct = written.get(valueKey2);
+    if (direct === void 0) {
       continue;
     }
-    const constructionKey = [...written][0];
-    const from = origins.get(`${valueKey2}|${constructionKey}`);
+    const deeper = calls.has(direct) ? writtenThroughCall.get(direct) : void 0;
+    const constructionKey = deeper ?? direct;
+    const originOf = deeper === void 0 ? valueKey2 : direct;
+    const from = origins.get(`${originOf}|${constructionKey}`);
     if (from !== void 0) {
       found.set(valueKey2, { constructionKey, origins: from });
     }
@@ -1778,6 +2264,9 @@ function emitExpressionFact(emitter, child) {
   if (WRITTEN_VALUE_TYPES.has(child.type)) {
     add(emitter, "writtenValue", nodeId(emitter.filePath, child));
   }
+  if (child.type === "none") {
+    add(emitter, "placeholderValue", nodeId(emitter.filePath, child));
+  }
 }
 function emitExpressionFacts(emitter, node) {
   walkExpressions(emitter, node, (child) => {
@@ -2236,7 +2725,7 @@ function predicateOf(node) {
 }
 
 // src/paths/effects.ts
-var NESTED_FUNCTION_TYPES2 = /* @__PURE__ */ new Set(["function_definition", "lambda"]);
+var NESTED_DEFINITION_TYPES = /* @__PURE__ */ new Set(["function_definition"]);
 var LITERAL_ARGS = {
   string: (node) => ({ kind: "string", value: node.text.slice(1, -1) }),
   integer: (node) => {
@@ -2252,7 +2741,7 @@ var LITERAL_ARGS = {
 };
 function bodyCalls(node, found = []) {
   for (const child of node.namedChildren) {
-    if (child === null || NESTED_FUNCTION_TYPES2.has(child.type)) {
+    if (child === null || NESTED_DEFINITION_TYPES.has(child.type)) {
       continue;
     }
     if (child.type === "call") {
@@ -2294,26 +2783,12 @@ function argsOf(call) {
 function calleeText(call) {
   return field(call, "function")?.text ?? call.text;
 }
-function withoutChainLinks(calls) {
-  const isLink = /* @__PURE__ */ new Set();
-  for (const call of calls) {
-    const callee = field(call, "function");
-    if (callee === null || callee.type !== "attribute") {
-      continue;
-    }
-    const object2 = field(callee, "object");
-    if (object2 !== null && object2.type === "call") {
-      isLink.add(object2.id);
-    }
-  }
-  return calls.filter((call) => !isLink.has(call.id));
-}
 function invocationEffects(definitionNode) {
   const body = field(definitionNode, "body");
   if (body === null) {
     return [];
   }
-  const calls = withoutChainLinks(bodyCalls(body));
+  const calls = bodyCalls(body).sort((a, b) => a.endIndex - b.endIndex);
   if (calls.length === 0) {
     return [];
   }
@@ -3191,10 +3666,10 @@ function mergeDefs(...defs) {
 function cloneDef(schema) {
   return mergeDefs(schema._zod.def);
 }
-function getElementAtPath(obj, path4) {
-  if (!path4)
+function getElementAtPath(obj, path6) {
+  if (!path6)
     return obj;
-  return path4.reduce((acc, key) => acc?.[key], obj);
+  return path6.reduce((acc, key) => acc?.[key], obj);
 }
 function promiseAllObject(promisesObj) {
   const keys = Object.keys(promisesObj);
@@ -3603,11 +4078,11 @@ function explicitlyAborted(x, startIndex = 0) {
   }
   return false;
 }
-function prefixIssues(path4, issues) {
+function prefixIssues(path6, issues) {
   return issues.map((iss) => {
     var _a3;
     (_a3 = iss).path ?? (_a3.path = []);
-    iss.path.unshift(path4);
+    iss.path.unshift(path6);
     return iss;
   });
 }
@@ -3754,16 +4229,16 @@ function flattenError(error51, mapper = (issue2) => issue2.message) {
 }
 function formatError(error51, mapper = (issue2) => issue2.message) {
   const fieldErrors = { _errors: [] };
-  const processError = (error52, path4 = []) => {
+  const processError = (error52, path6 = []) => {
     for (const issue2 of error52.issues) {
       if (issue2.code === "invalid_union" && issue2.errors.length) {
-        issue2.errors.map((issues) => processError({ issues }, [...path4, ...issue2.path]));
+        issue2.errors.map((issues) => processError({ issues }, [...path6, ...issue2.path]));
       } else if (issue2.code === "invalid_key") {
-        processError({ issues: issue2.issues }, [...path4, ...issue2.path]);
+        processError({ issues: issue2.issues }, [...path6, ...issue2.path]);
       } else if (issue2.code === "invalid_element") {
-        processError({ issues: issue2.issues }, [...path4, ...issue2.path]);
+        processError({ issues: issue2.issues }, [...path6, ...issue2.path]);
       } else {
-        const fullpath = [...path4, ...issue2.path];
+        const fullpath = [...path6, ...issue2.path];
         if (fullpath.length === 0) {
           fieldErrors._errors.push(mapper(issue2));
         } else {
@@ -3790,17 +4265,17 @@ function formatError(error51, mapper = (issue2) => issue2.message) {
 }
 function treeifyError(error51, mapper = (issue2) => issue2.message) {
   const result = { errors: [] };
-  const processError = (error52, path4 = []) => {
+  const processError = (error52, path6 = []) => {
     var _a3, _b;
     for (const issue2 of error52.issues) {
       if (issue2.code === "invalid_union" && issue2.errors.length) {
-        issue2.errors.map((issues) => processError({ issues }, [...path4, ...issue2.path]));
+        issue2.errors.map((issues) => processError({ issues }, [...path6, ...issue2.path]));
       } else if (issue2.code === "invalid_key") {
-        processError({ issues: issue2.issues }, [...path4, ...issue2.path]);
+        processError({ issues: issue2.issues }, [...path6, ...issue2.path]);
       } else if (issue2.code === "invalid_element") {
-        processError({ issues: issue2.issues }, [...path4, ...issue2.path]);
+        processError({ issues: issue2.issues }, [...path6, ...issue2.path]);
       } else {
-        const fullpath = [...path4, ...issue2.path];
+        const fullpath = [...path6, ...issue2.path];
         if (fullpath.length === 0) {
           result.errors.push(mapper(issue2));
           continue;
@@ -3832,8 +4307,8 @@ function treeifyError(error51, mapper = (issue2) => issue2.message) {
 }
 function toDotPath(_path) {
   const segs = [];
-  const path4 = _path.map((seg) => typeof seg === "object" ? seg.key : seg);
-  for (const seg of path4) {
+  const path6 = _path.map((seg) => typeof seg === "object" ? seg.key : seg);
+  for (const seg of path6) {
     if (typeof seg === "number")
       segs.push(`[${seg}]`);
     else if (typeof seg === "symbol")
@@ -16525,13 +17000,13 @@ function resolveRef(ref, ctx) {
   if (!ref.startsWith("#")) {
     throw new Error("External $ref is not supported, only local refs (#/...) are allowed");
   }
-  const path4 = ref.slice(1).split("/").filter(Boolean);
-  if (path4.length === 0) {
+  const path6 = ref.slice(1).split("/").filter(Boolean);
+  if (path6.length === 0) {
     return ctx.rootSchema;
   }
   const defsKey = ctx.version === "draft-2020-12" ? "$defs" : "definitions";
-  if (path4[0] === defsKey) {
-    const key = path4[1];
+  if (path6[0] === defsKey) {
+    const key = path6[1];
     if (!key || !ctx.defs[key]) {
       throw new Error(`Reference not found: ${ref}`);
     }
@@ -17291,8 +17766,8 @@ function baseUrlReference(semantics) {
   const label = OPENING_HOLE.exec(semantics.path ?? "")?.[1];
   return label === void 0 ? null : referenceFromName(patternHole(label));
 }
-function normalizePath(path4) {
-  let normalized = path4.replace(/:([a-zA-Z_]\w*)/g, "{$1}");
+function normalizePath(path6) {
+  let normalized = path6.replace(/:([a-zA-Z_]\w*)/g, "{$1}");
   if (normalized.length > 1 && normalized.endsWith("/")) {
     normalized = normalized.slice(0, -1);
   }
@@ -17302,8 +17777,8 @@ function normalizePath(path4) {
   );
   return normalized;
 }
-function pathShape(path4) {
-  return normalizePath(path4).replace(/\{[^}]*\}/g, "{}");
+function pathShape(path6) {
+  return normalizePath(path6).replace(/\{[^}]*\}/g, "{}");
 }
 function methodsAgree(a, b) {
   if (a === null || b === null) {
@@ -17381,8 +17856,8 @@ var restSemantics = defineBoundarySemantics({
         return null;
       }
       const method = semantics.method === null ? "ANY" : semantics.method.toUpperCase();
-      const path4 = semantics.path === null ? "?" : normalizePath(semantics.path);
-      return `${method} ${path4}`;
+      const path6 = semantics.path === null ? "?" : normalizePath(semantics.path);
+      return `${method} ${path6}`;
     },
     /**
      * A route with both halves stated decides for itself: the method
@@ -17391,14 +17866,14 @@ var restSemantics = defineBoundarySemantics({
      * half might still be the one that handles the request, and nothing
      * here can settle that, so it abstains instead of refusing.
      */
-    servesRequest(semantics, method, path4) {
+    servesRequest(semantics, method, path6) {
       if (semantics.method === null || semantics.path === null) {
         return "unknown";
       }
       if (!methodsAgree(semantics.method, method.toUpperCase())) {
         return "nomatch";
       }
-      return routePathAdmits(semantics.path, path4) ? "match" : "nomatch";
+      return routePathAdmits(semantics.path, path6) ? "match" : "nomatch";
     },
     /**
      * A route the registration pattern admits is inside it. A route
@@ -18035,71 +18510,10 @@ function returnTypeName(node) {
   }
   return annotation.type === "subscript" ? field(annotation, "value")?.text ?? null : annotation.text;
 }
-function callsIn(node, found = []) {
-  for (const child of node.namedChildren) {
-    if (child === null) {
-      continue;
-    }
-    if (child.type === "call") {
-      found.push(child);
-    }
-    callsIn(child, found);
-  }
-  return found;
-}
-function storageEffects(calls, options) {
-  const seen = /* @__PURE__ */ new Set();
-  const asked = new Set(
-    options.facts.facts("wanted").map((row) => String(row[0]))
-  );
-  const gather = (inCalls, filePath) => {
-    const found = [...directStorageEffects(inCalls, { ...options, filePath })];
-    resolveCalls(
-      options.facts,
-      inCalls.filter((call) => options.leadsToStorage.has(methodName(call))).map((call) => field(call, "function")).filter((callee) => callee !== null).map((callee) => calleeKeyOf(filePath, callee)).filter((key) => {
-        const fresh = !asked.has(key);
-        asked.add(key);
-        return fresh;
-      })
-    );
-    for (const call of inCalls) {
-      const callee = field(call, "function");
-      if (callee === null || !options.leadsToStorage.has(methodName(call))) {
-        continue;
-      }
-      const key = resolvedOnce(options, calleeKeyOf(filePath, callee));
-      const body = key === void 0 ? void 0 : options.definitionAt(key);
-      if (key === void 0 || body === void 0 || seen.has(key)) {
-        continue;
-      }
-      seen.add(key);
-      const name = field(body, "name")?.text;
-      const origin = {
-        file: fileOf(key),
-        line: body.startPosition.row + 1,
-        ...name === void 0 ? {} : { function: name }
-      };
-      found.push(
-        ...gather(callsIn(body), fileOf(key)).map(
-          (effect) => effect.type === "interaction" && effect.origin === void 0 ? { ...effect, origin } : effect
-        )
-      );
-    }
-    return found;
-  };
-  return gather(calls, options.filePath);
-}
-function calleeKeyOf(filePath, callee) {
-  return callee.type === "identifier" ? `${filePath}#${callee.text}` : nodeId(filePath, callee);
-}
-function resolvedOnce(options, calleeKey) {
-  const resolved = options.facts.facts("wantedResolves").filter((row) => String(row[0]) === calleeKey).map((row) => String(row[1]));
-  return resolved.length === 1 ? resolved[0] : void 0;
-}
 function storageCallees(calls, filePath, couldMatch) {
   return chainsIn(calls).filter((chain) => couldMatch.has(methodName(chain.root))).map((chain) => field(chain.root, "function")).filter((callee) => callee !== null).map((callee) => nodeId(filePath, callee));
 }
-function directStorageEffects(calls, options) {
+function storageEffects(calls, options) {
   if (options.patterns.length === 0) {
     return [];
   }
@@ -18157,7 +18571,7 @@ function directStorageEffects(calls, options) {
 // src/discovery.ts
 function decoratedStatements(root, module) {
   const found = [];
-  walkDescendants(
+  walkDescendants2(
     root,
     { scope: module.moduleScope, enclosingFunction: null },
     {
@@ -18196,21 +18610,21 @@ function builtSubjects(decorated, options) {
   }
   const factsPath = options.absoluteFile ?? options.filePath;
   const asked = /* @__PURE__ */ new Set();
-  for (const { enclosingFunction, decorators } of decorated) {
+  for (const { enclosingFunction: enclosingFunction2, decorators } of decorated) {
     for (const { node, direct } of decorators) {
       if (direct.module !== null && acceptedByAnyPattern(direct.module, options)) {
         continue;
       }
       const written = decoratorReceiver(node);
       if (written !== null) {
-        asked.add(readKey(factsPath, written.object, enclosingFunction));
+        asked.add(readKey(factsPath, written.object, enclosingFunction2));
       }
     }
   }
   return subjectConstructions(facts, [...asked]);
 }
 function decoratedUnits(decoratedStatement, module, options, subjects) {
-  const { stmt, scope, enclosingFunction, decorators } = decoratedStatement;
+  const { stmt, scope, enclosingFunction: enclosingFunction2, decorators } = decoratedStatement;
   const units = [];
   const { definition } = stripDecorators(stmt);
   for (const { node: decoratorNode, direct } of decorators) {
@@ -18226,7 +18640,7 @@ function decoratedUnits(decoratedStatement, module, options, subjects) {
         ) ?? null
       ) ?? builtSubjectClassification(
         decoratorNode,
-        enclosingFunction,
+        enclosingFunction2,
         subjects,
         options
       )
@@ -18262,14 +18676,14 @@ function acceptedByAnyPattern(module, options) {
     (pack) => pack.discovery.some((pattern) => pattern.importModule.includes(module))
   );
 }
-function builtSubjectClassification(decoratorNode, enclosingFunction, subjects, options) {
+function builtSubjectClassification(decoratorNode, enclosingFunction2, subjects, options) {
   const written = decoratorReceiver(decoratorNode);
   if (written === null) {
     return null;
   }
   const factsPath = options.absoluteFile ?? options.filePath;
   const built = subjects.get(
-    readKey(factsPath, written.object, enclosingFunction)
+    readKey(factsPath, written.object, enclosingFunction2)
   );
   const origin = built?.origins.find(
     (candidate) => acceptedByAnyPattern(candidate.module, options)
@@ -18342,9 +18756,9 @@ function readPathArgument(classification) {
 }
 var NO_PATH_PARAMS = /* @__PURE__ */ new Set();
 function templateReader(template) {
-  return (path4) => {
+  return (path6) => {
     const names = [];
-    const canonical = path4.replace(template, (_match, name) => {
+    const canonical = path6.replace(template, (_match, name) => {
       names.push(name);
       return `{${name}}`;
     });
@@ -18357,10 +18771,10 @@ var PATH_TEMPLATE_READERS = {
     /<(?:[A-Za-z_]\w*(?:\(.*?\))?:)?([A-Za-z_]\w*)>/g
   )
 };
-function readPathTemplate(pattern, path4, range) {
+function readPathTemplate(pattern, path6, range) {
   const syntax = pattern.pathParamSyntax;
   if (syntax === void 0) {
-    return writtenReading({ path: path4, paramNames: NO_PATH_PARAMS }, range);
+    return writtenReading({ path: path6, paramNames: NO_PATH_PARAMS }, range);
   }
   const reader = PATH_TEMPLATE_READERS[syntax];
   if (reader === void 0) {
@@ -18369,7 +18783,7 @@ function readPathTemplate(pattern, path4, range) {
       range
     );
   }
-  return writtenReading(reader(path4), range);
+  return writtenReading(reader(path6), range);
 }
 function classRouteUnits(pattern, pack, classification, classNode, module, options) {
   const pathArgument = readPathArgument(classification);
@@ -18439,7 +18853,7 @@ function readRoutePath(pattern, pathArgument, classification, module, options) {
   );
   return andThenReading(
     composed,
-    (path4, range) => readPathTemplate(pattern, path4, range)
+    (path6, range) => readPathTemplate(pattern, path6, range)
   );
 }
 function readRoutePaths(pattern, pathArgument, classification, module, options) {
@@ -18468,7 +18882,7 @@ function readRoutePaths(pattern, pathArgument, classification, module, options)
         pathArgument,
         (literal2, range) => writtenReading(servedSpelling(pattern, prefix + literal2), range)
       ),
-      (path4, range) => readPathTemplate(pattern, path4, range)
+      (path6, range) => readPathTemplate(pattern, path6, range)
     ),
     mount: { siblings: resolution.values.length, prefix }
   }));
@@ -18510,11 +18924,11 @@ function composeRoutePath(pattern, classification, module, options, literal2, ra
   );
 }
 var REPEATED_SLASH_READERS = {
-  kept: (path4) => path4,
-  merged: (path4) => path4.replace(/\/{2,}/g, "/")
+  kept: (path6) => path6,
+  merged: (path6) => path6.replace(/\/{2,}/g, "/")
 };
-function servedSpelling(pattern, path4) {
-  return REPEATED_SLASH_READERS[pattern.pathRepeatedSlashes ?? "kept"](path4);
+function servedSpelling(pattern, path6) {
+  return REPEATED_SLASH_READERS[pattern.pathRepeatedSlashes ?? "kept"](path6);
 }
 function readRouterPrefix(pattern, classification, module, options, range) {
   const resolution = routerResolutionOf(
@@ -18626,8 +19040,8 @@ function branchesFromReturns(readsReturnedStatus, definitionNode, effects, respo
       "This return gives a status this reading cannot resolve to a number, so this outcome claims none",
       range
     );
-    for (const path4 of paths) {
-      const conditions = path4.map((condition) => ({
+    for (const path6 of paths) {
+      const conditions = path6.map((condition) => ({
         sourceText: condition.sourceText,
         structured: condition.expression === null ? null : predicateOf(condition.expression),
         polarity: condition.polarity,
@@ -18656,7 +19070,7 @@ function branchesFromReturns(readsReturnedStatus, definitionNode, effects, respo
         },
         effects: effectsReaching(effects, conditions),
         location: range,
-        isDefault: path4.length === 0
+        isDefault: path6.length === 0
       });
     }
   }
@@ -18867,17 +19281,7 @@ function buildRouteUnit(options) {
     () => readReturnAnnotation(definitionNode, enclosingScope, ctx)
   );
   const effects = invocationEffects(definitionNode);
-  const storage = storageLookup === void 0 ? [] : [
-    ...storageEffects(bodyCalls(definitionNode), {
-      ...storageLookup,
-      filePath: storageLookup.factsPath
-    }),
-    ...rawSqlEffects(bodyCalls(definitionNode), {
-      facts: storageLookup.facts,
-      filePath: storageLookup.factsPath,
-      patterns: storageLookup.rawSql ?? []
-    })
-  ];
+  const extra = recognizedBodyEffects(definitionNode, module, storageLookup);
   const perReturn = branchesFromReturns(
     readsReturnedStatus,
     definitionNode,
@@ -18886,9 +19290,9 @@ function buildRouteUnit(options) {
     statusCode
   );
   const branches = (perReturn ?? []).map(
-    (branch) => storage.length === 0 ? branch : { ...branch, extraEffects: storage }
+    (branch) => extra.length === 0 ? branch : { ...branch, extraEffects: extra }
   );
-  if (perReturn === null && (responseShape.reading.kind !== "absent" || statusCode.reading.kind !== "absent" || storage.length > 0 || effects.length > 0)) {
+  if (perReturn === null && (responseShape.reading.kind !== "absent" || statusCode.reading.kind !== "absent" || extra.length > 0 || effects.length > 0)) {
     branches.push({
       conditions: [],
       terminal: {
@@ -18908,7 +19312,7 @@ function buildRouteUnit(options) {
       statusCodeReading: statusCode,
       bodyShapeReading: { reading: responseShape.reading },
       effects,
-      ...storage.length === 0 ? {} : { extraEffects: storage },
+      ...extra.length === 0 ? {} : { extraEffects: extra },
       location: rangeOf(definitionNode),
       isDefault: true
     });
@@ -18956,6 +19360,20 @@ function unreadRoleReadings(parameters, range) {
     )
   ];
 }
+function recognizedBodyEffects(definitionNode, module, storageLookup) {
+  const storage = storageLookup === void 0 ? [] : [
+    ...storageEffects(bodyCalls(definitionNode), {
+      ...storageLookup,
+      filePath: storageLookup.factsPath
+    }),
+    ...rawSqlEffects(bodyCalls(definitionNode), {
+      facts: storageLookup.facts,
+      filePath: storageLookup.factsPath,
+      patterns: storageLookup.rawSql ?? []
+    })
+  ];
+  return [...envReadEffects(definitionNode, module), ...storage];
+}
 function bodyContentOf(bodyNode) {
   for (const stmt of bodyStatements(bodyNode)) {
     if (stmt.type === "pass_statement") {
@@ -19091,6 +19509,11 @@ function parameterNameAndType(param) {
   return null;
 }
 
+// src/facts/why.ts
+import fs4 from "fs";
+import path4 from "path";
+import { Database as Database4 } from "@suss/datalog";
+
 // src/moduleResolver.ts
 import fs from "fs";
 import path from "path";
@@ -19183,43 +19606,38 @@ function importedModuleText(module, relativeLevel) {
   return relativeLevel > 0 ? `${".".repeat(relativeLevel)}${module}` : module;
 }
 function emitModuleImportFacts(db, filePath, module, resolverOptions) {
-  const everyBinding = [...module.scopeFor.values()].flatMap((scope) => [
-    ...scope.bindings
-  ]);
-  for (const [localName, binding] of everyBinding) {
-    if (binding.kind !== "import" && binding.kind !== "importFrom") {
-      continue;
-    }
-    const moduleText = importedModuleText(
-      binding.module,
-      binding.relativeLevel
-    );
-    const resolution = resolveModule(
-      filePath,
-      { module: binding.module, relativeLevel: binding.relativeLevel },
-      resolverOptions
-    );
-    db.add("pyImport", [
-      filePath,
-      moduleText,
-      resolution.status === "resolved" ? "resolved" : resolution.reason
-    ]);
-    const importedName = binding.kind === "import" ? binding.localName : binding.importedName;
-    db.add("pyImportedName", [
-      `${filePath}#${localName}`,
-      moduleText,
-      importedName
-    ]);
-    if (resolution.status === "resolved") {
-      db.add("pyImportResolved", [filePath, moduleText, resolution.file]);
-      db.add("imports", [
-        `${filePath}#${localName}`,
-        resolution.file,
-        importedName
+  for (const scope of module.scopeFor.values()) {
+    for (const [localName, binding] of scope.bindings) {
+      if (binding.kind !== "import" && binding.kind !== "importFrom") {
+        continue;
+      }
+      const nameKey = `${filePath}#${localName}`;
+      const moduleText = importedModuleText(
+        binding.module,
+        binding.relativeLevel
+      );
+      const resolution = resolveModule(
+        filePath,
+        { module: binding.module, relativeLevel: binding.relativeLevel },
+        resolverOptions
+      );
+      db.add("pyImport", [
+        filePath,
+        moduleText,
+        resolution.status === "resolved" ? "resolved" : resolution.reason
       ]);
-      continue;
-    }
-    db.add("imports", [`${filePath}#${localName}`, moduleText, importedName]);
+      const importedName = binding.kind === "import" ? binding.localName : binding.importedName;
+      db.add("pyImportedName", [nameKey, moduleText, importedName]);
+      if (scope.kind === "module") {
+        db.add("exportsAs", [filePath, localName, nameKey]);
+      }
+      if (resolution.status === "resolved") {
+        db.add("pyImportResolved", [filePath, moduleText, resolution.file]);
+        db.add("imports", [nameKey, resolution.file, importedName]);
+        continue;
+      }
+      db.add("imports", [nameKey, moduleText, importedName]);
+    }
   }
   for (const openModule of module.openImports) {
     db.add("pyOpenImport", [filePath, openModule]);
@@ -19238,6 +19656,7 @@ var GRAMMAR_PATH = path2.join(
   "tree-sitter-python.wasm"
 );
 var languagePromise = null;
+var loadedLanguage = null;
 function loadLanguage() {
   languagePromise ??= (async () => {
     if (!fs2.existsSync(GRAMMAR_PATH)) {
@@ -19246,12 +19665,28 @@ function loadLanguage() {
       );
     }
     await Parser.init();
-    return Language.load(GRAMMAR_PATH);
+    const language = await Language.load(GRAMMAR_PATH);
+    loadedLanguage = language;
+    return language;
   })();
   return languagePromise;
 }
 async function parsePython(source) {
   const language = await loadLanguage();
+  return parseWith(language, source);
+}
+async function preloadPythonGrammar() {
+  await loadLanguage();
+}
+function parsePythonSync(source) {
+  if (loadedLanguage === null) {
+    throw new Error(
+      "the Python grammar has not been loaded yet; call preloadPythonGrammar first"
+    );
+  }
+  return parseWith(loadedLanguage, source);
+}
+function parseWith(language, source) {
   const parser = new Parser();
   parser.setLanguage(language);
   try {
@@ -19268,8 +19703,705 @@ async function parsePython(source) {
 // src/project.ts
 import fs3 from "fs";
 import path3 from "path";
-import { Database, evaluate as evaluate2, lit as lit2, rule as rule2, variable as v2 } from "@suss/datalog";
-import { assembleSummary } from "@suss/extractor";
+import {
+  disambiguateSummaryIds,
+  linkCallsToSummaries,
+  placeArgTargets as placeArgTargets2,
+  placeCalleeParameters as placeCalleeParameters2,
+  placeCalls as placeCalls2,
+  recordParameterGaps as recordParameterGaps2,
+  summaryIdFromParts,
+  unfollowedCallGap as unfollowedCallGap2
+} from "@suss/behavioral-ir";
+import { Database as Database3 } from "@suss/datalog";
+import {
+  assembleSummary as assembleSummary2,
+  createCacheLayer,
+  createTimer,
+  moduleInitStructure,
+  noopTimer,
+  runDigest,
+  stampModuleImports
+} from "@suss/extractor";
+
+// src/diagnostics.ts
+import {
+  buildUngatedExtractionReport,
+  createPackTallies,
+  tallyUnit
+} from "@suss/extractor";
+function buildPythonExtractionReport(args) {
+  return buildUngatedExtractionReport({
+    packs: args.packs.map((pack) => ({
+      name: pack.name,
+      version: pack.version ?? null,
+      discovers: pack.discovery.length > 0
+    })),
+    tallies: args.tallies,
+    filesWalked: args.filesWalked,
+    summaries: args.summaries
+  });
+}
+
+// src/reach/closure.ts
+import {
+  functionCallBinding,
+  placeArgTargets,
+  placeCalleeParameters,
+  placeCalls,
+  recordParameterGaps,
+  TargetPlacements,
+  unfollowedCallGap,
+  worthRecording
+} from "@suss/behavioral-ir";
+import { Database as Database2, evaluate as evaluate3, lit as lit2, rule as rule2, variable as v2 } from "@suss/datalog";
+import {
+  assembleSummary,
+  SKIP_CHILDREN as SKIP_CHILDREN2,
+  walkDescendants as walkDescendants3
+} from "@suss/extractor";
+
+// src/reach/resolveCallee.ts
+var stop = (reason) => ({ kind: "stop", reason });
+var MODULE_STOP = {
+  ambiguous: "multipleSources",
+  outsideRoots: "outsideRun"
+};
+function resolveCallee2(call, site, ctx) {
+  const callee = field(call, "function");
+  if (callee === null) {
+    return { kind: "stopped", reason: "noDeclaration" };
+  }
+  return asCallee(resolveExpression(callee, site, ctx), ctx);
+}
+function resolveNamedFunctionArgument(name, site, ctx) {
+  if (site.rebound.has(name)) {
+    return null;
+  }
+  const binding = resolveName(site.scope, name);
+  if (binding !== null && binding.kind === "assignment") {
+    return null;
+  }
+  const resolved = binding === null ? throughOpenImports(site.file, name, ctx, /* @__PURE__ */ new Set()) : resolveBinding(binding, site.file, site.scope, ctx, /* @__PURE__ */ new Set());
+  return resolved.kind === "function" ? resolved.target : null;
+}
+function asCallee(resolved, ctx) {
+  if (resolved.kind === "function") {
+    return { kind: "followed", target: resolved.target };
+  }
+  if (resolved.kind === "class") {
+    return asCallee(
+      memberOfClass(resolved.file, resolved.node, "__init__", ctx),
+      ctx
+    );
+  }
+  if (resolved.kind === "stop") {
+    return { kind: "stopped", reason: resolved.reason };
+  }
+  if (resolved.kind === "package") {
+    return { kind: "stopped", reason: "outsideRun" };
+  }
+  return { kind: "stopped", reason: "noDeclaration" };
+}
+var EXPRESSION_RESOLVERS = {
+  identifier: (node, site, ctx) => resolveIdentifier(node.text, site, ctx),
+  attribute: (node, site, ctx) => {
+    const object2 = field(node, "object");
+    const attribute = field(node, "attribute");
+    if (object2 === null || attribute === null) {
+      return stop("noDeclaration");
+    }
+    return memberOf(resolveExpression(object2, site, ctx), attribute.text, ctx);
+  },
+  // `Service().run()` runs a method on whatever the constructor built.
+  call: (node, site, ctx) => {
+    const callee = field(node, "function");
+    if (callee === null) {
+      return stop("noDeclaration");
+    }
+    const built = resolveExpression(callee, site, ctx);
+    return built.kind === "class" ? built : stop("noDeclaration");
+  },
+  parenthesized_expression: (node, site, ctx) => {
+    const inner = node.namedChildren[0];
+    return inner === null || inner === void 0 ? stop("noDeclaration") : resolveExpression(inner, site, ctx);
+  }
+};
+function resolveExpression(node, site, ctx) {
+  const resolver = EXPRESSION_RESOLVERS[node.type];
+  return resolver === void 0 ? stop("noDeclaration") : resolver(node, site, ctx);
+}
+function resolveIdentifier(name, site, ctx) {
+  if (site.rebound.has(name)) {
+    return stop("unsettledValue");
+  }
+  if (isReceiver(name, site.scope)) {
+    return receiverClass(site);
+  }
+  const binding = resolveName(site.scope, name);
+  if (binding === null) {
+    return throughOpenImports(site.file, name, ctx, /* @__PURE__ */ new Set());
+  }
+  return resolveBinding(binding, site.file, site.scope, ctx, /* @__PURE__ */ new Set());
+}
+function isReceiver(name, scope) {
+  return (name === "self" || name === "cls") && scope.kind === "function" && scope.parent?.kind === "class";
+}
+function receiverClass(site) {
+  const classScope = site.scope.parent;
+  if (classScope === null || classScope === void 0) {
+    return stop("noDeclaration");
+  }
+  return { kind: "class", file: site.file, node: classScope.node };
+}
+var BINDING_RESOLVERS = {
+  functionDef: (binding, file2) => ({
+    kind: "function",
+    target: reachedFunction(file2, binding.node)
+  }),
+  classDef: (binding, file2) => ({ kind: "class", file: file2, node: binding.node }),
+  parameter: () => stop("callerSupplied"),
+  // `import a.b.c` binds `a`, and `import a.b.c as m` binds `m` to `a.b.c`.
+  import: (binding, file2, _scope, ctx) => moduleNamed(
+    file2,
+    binding.localName === binding.module.split(".")[0] ? binding.localName : binding.module,
+    0,
+    ctx
+  ),
+  importFrom: (binding, file2, _scope, ctx, visited) => memberOf(
+    moduleNamed(file2, binding.module, binding.relativeLevel, ctx),
+    binding.importedName,
+    ctx,
+    visited
+  ),
+  // `run = load` is an alias worth one hop; anything else is a value.
+  assignment: (binding, file2, scope, ctx, visited) => aliasedValue(binding.value, file2, scope, ctx, visited),
+  global: () => stop("unsettledValue"),
+  nonlocal: () => stop("unsettledValue")
+};
+function resolveBinding(binding, file2, scope, ctx, visited) {
+  const resolver = BINDING_RESOLVERS[binding.kind];
+  return resolver(binding, file2, scope, ctx, visited);
+}
+function aliasedValue(value, file2, scope, ctx, visited) {
+  if (value === null) {
+    return stop("unsettledValue");
+  }
+  if (value.type === "identifier") {
+    const binding = resolveName(scope, value.text);
+    if (binding === null || binding.kind === "assignment") {
+      return stop("unsettledValue");
+    }
+    return resolveBinding(binding, file2, scope, ctx, visited);
+  }
+  if (value.type === "call") {
+    const callee = field(value, "function");
+    const built = callee === null ? stop("unsettledValue") : aliasedValue(callee, file2, scope, ctx, visited);
+    return built.kind === "class" ? built : stop("unsettledValue");
+  }
+  if (value.type === "attribute") {
+    const object2 = field(value, "object");
+    const attribute = field(value, "attribute");
+    if (object2 === null || attribute === null) {
+      return stop("unsettledValue");
+    }
+    return memberOf(
+      aliasedValue(object2, file2, scope, ctx, visited),
+      attribute.text,
+      ctx
+    );
+  }
+  return stop("unsettledValue");
+}
+function reachedFunction(file2, node, owner) {
+  const name = field(node, "name")?.text ?? "<anon>";
+  const ownerName = owner === void 0 ? null : field(owner, "name")?.text;
+  return {
+    file: file2,
+    node,
+    name,
+    exportPath: ownerName === null || ownerName === void 0 ? [name] : [ownerName, name]
+  };
+}
+function moduleNamed(from, module, relativeLevel, ctx) {
+  const resolution = resolveModule(
+    from.file,
+    { module, relativeLevel },
+    { roots: ctx.roots }
+  );
+  if (resolution.status !== "resolved") {
+    return resolution.reason === "external" ? { kind: "package", dotted: module, relativeLevel, from } : stop(MODULE_STOP[resolution.reason]);
+  }
+  const file2 = ctx.filesByPath.get(resolution.file);
+  return file2 === void 0 ? stop("outsideRun") : { kind: "module", file: file2 };
+}
+function memberOf(base, name, ctx, visited = /* @__PURE__ */ new Set()) {
+  if (base.kind === "module") {
+    return memberOfModule(base.file, name, ctx, visited);
+  }
+  if (base.kind === "package") {
+    return moduleNamed(
+      base.from,
+      base.dotted === "" ? name : `${base.dotted}.${name}`,
+      base.relativeLevel,
+      ctx
+    );
+  }
+  if (base.kind === "class") {
+    return memberOfClass(base.file, base.node, name, ctx);
+  }
+  if (base.kind === "stop") {
+    return base;
+  }
+  return stop("noDeclaration");
+}
+function memberOfClass(file2, classNode, name, ctx) {
+  const classScope = file2.module.scopeFor.get(classNode.id);
+  const binding = classScope?.bindings.get(name);
+  if (binding === void 0) {
+    return stop("noDeclaration");
+  }
+  if (binding.kind === "functionDef") {
+    return {
+      kind: "function",
+      target: reachedFunction(file2, binding.node, classNode)
+    };
+  }
+  return resolveBinding(binding, file2, classScope, ctx, /* @__PURE__ */ new Set());
+}
+function memberOfModule(file2, name, ctx, visited) {
+  const key = `${file2.file}#${name}`;
+  if (visited.has(key)) {
+    return stop("unsettledValue");
+  }
+  visited.add(key);
+  const binding = file2.module.moduleScope.bindings.get(name);
+  if (binding !== void 0) {
+    return resolveBinding(binding, file2, file2.module.moduleScope, ctx, visited);
+  }
+  if (file2.file.endsWith("__init__.py")) {
+    const submodule = moduleNamed(file2, name, 1, ctx);
+    if (submodule.kind === "module") {
+      return submodule;
+    }
+  }
+  return throughOpenImports(file2, name, ctx, visited);
+}
+function throughOpenImports(file2, name, ctx, visited) {
+  const found = [];
+  for (const spec of file2.module.openImports) {
+    const dots = spec.length - spec.replace(/^\.+/, "").length;
+    const opened = moduleNamed(file2, spec.slice(dots), dots, ctx);
+    if (opened.kind !== "module") {
+      continue;
+    }
+    const member = memberOfModule(opened.file, name, ctx, visited);
+    if (member.kind !== "stop") {
+      found.push(member);
+    }
+  }
+  if (found.length > 1) {
+    return stop("multipleSources");
+  }
+  return found[0] ?? stop("noDeclaration");
+}
+
+// src/reach/closure.ts
+var REACHABLE_RULES = [
+  rule2("reachable", [v2("f")], [lit2("entry", v2("f"))]),
+  rule2(
+    "reachable",
+    [v2("g")],
+    [lit2("reachable", v2("f")), lit2("calls", v2("f"), v2("g"))]
+  )
+];
+function reachedFunctions(seeds, options) {
+  const ctx = {
+    filesByPath: new Map(options.files.map((file2) => [file2.file, file2])),
+    roots: options.roots
+  };
+  const db = new Database2();
+  const functionByKey = /* @__PURE__ */ new Map();
+  const seedKeys = /* @__PURE__ */ new Set();
+  const scanned = /* @__PURE__ */ new Set();
+  const targetsByKey = /* @__PURE__ */ new Map();
+  const stopsByKey = /* @__PURE__ */ new Map();
+  const argTargetsByKey = /* @__PURE__ */ new Map();
+  const parameterCallsByKey = /* @__PURE__ */ new Map();
+  const passedPositions = /* @__PURE__ */ new Set();
+  for (const seed of seeds) {
+    seedKeys.add(seed.key);
+    functionByKey.set(seed.key, {
+      file: seed.file,
+      node: seed.node,
+      name: field(seed.node, "name")?.text ?? "<anon>",
+      exportPath: []
+    });
+    db.add("entry", [seed.key]);
+  }
+  for (; ; ) {
+    evaluate3(db, REACHABLE_RULES);
+    const frontier = db.facts("reachable").map(([key]) => String(key)).filter((key) => !scanned.has(key));
+    if (frontier.length === 0) {
+      break;
+    }
+    for (const key of frontier) {
+      scanned.add(key);
+      const source = functionByKey.get(key);
+      if (source === void 0) {
+        continue;
+      }
+      const scan = scanBody(source, ctx);
+      if (scan.stops.length > 0) {
+        stopsByKey.set(key, scan.stops);
+      }
+      targetsByKey.set(key, scan.targets);
+      argTargetsByKey.set(key, scan.argTargets);
+      if (scan.parameterCalls.length > 0) {
+        parameterCallsByKey.set(key, scan.parameterCalls);
+      }
+      for (const position of scan.passedPositions) {
+        passedPositions.add(position);
+      }
+      for (const target of scan.followed) {
+        const calleeKey = keyOf(target);
+        if (!functionByKey.has(calleeKey)) {
+          functionByKey.set(calleeKey, target);
+        }
+        db.add("calls", [key, calleeKey]);
+      }
+    }
+  }
+  const summaries = [];
+  const summariesByKey = /* @__PURE__ */ new Map();
+  for (const [keyAtom] of db.facts("reachable")) {
+    const key = String(keyAtom);
+    const target = functionByKey.get(key);
+    if (seedKeys.has(key) || target === void 0) {
+      continue;
+    }
+    const summary = assembleSummary(libraryUnit(target, options), {
+      gapHandling: options.gapHandling
+    });
+    summary.confidence = { source: "inferred_static", level: "low" };
+    if (options.gapHandling !== "silent") {
+      summary.gaps.push(...(stopsByKey.get(key) ?? []).map(unfollowedCallGap));
+    }
+    placeCalls(summary, targetsByKey.get(key));
+    placeArgTargets(summary, argTargetsByKey.get(key));
+    placeCalleeParameters(summary, parameterCallsByKey.get(key));
+    summariesByKey.set(key, [summary]);
+    summaries.push(summary);
+  }
+  if (options.gapHandling !== "silent") {
+    recordParameterGaps(parameterCallsByKey, summariesByKey, passedPositions);
+  }
+  return {
+    summaries,
+    targetsByKey,
+    stopsByKey,
+    argTargetsByKey,
+    parameterCallsByKey,
+    passedPositions
+  };
+}
+function keyOf(target) {
+  return nodeId(target.file.file, target.node);
+}
+var EMPTY_SCAN = {
+  followed: [],
+  stops: [],
+  targets: /* @__PURE__ */ new Map(),
+  argTargets: /* @__PURE__ */ new Map(),
+  parameterCalls: [],
+  passedPositions: /* @__PURE__ */ new Set()
+};
+function scanBody(source, ctx) {
+  const followed = [];
+  const stops = [];
+  const placements = new TargetPlacements();
+  const parameterCalls = [];
+  const passedPositions = /* @__PURE__ */ new Set();
+  const seen = /* @__PURE__ */ new Set();
+  const parameterCallsSeen = /* @__PURE__ */ new Set();
+  const { file: file2, node } = source;
+  const body = field(node, "body");
+  if (body === null) {
+    return EMPTY_SCAN;
+  }
+  const ownParameters = callParameterNames(node, source.exportPath.length > 1);
+  const recordPassedArgs = (call, callee, calleeKey, where) => {
+    const args = field(call, "arguments");
+    if (args === null) {
+      return;
+    }
+    args.namedChildren.forEach((arg, position) => {
+      if (arg === null || arg.type !== "identifier") {
+        return;
+      }
+      const resolved = resolveNamedFunctionArgument(
+        arg.text,
+        { file: file2, scope: where.scope, rebound: where.rebound },
+        ctx
+      );
+      if (resolved === null) {
+        return;
+      }
+      const key = keyOf(resolved);
+      if (!seen.has(key)) {
+        seen.add(key);
+        followed.push(resolved);
+      }
+      placements.placeArg(callee, position, {
+        file: resolved.file.displayPath,
+        span: spanOf(resolved.node)
+      });
+      if (calleeKey !== null) {
+        passedPositions.add(`${calleeKey}#${position}`);
+      }
+    });
+  };
+  const record2 = (call, where) => {
+    const callee = calleeText(call);
+    const outcome = resolveCallee2(
+      call,
+      { file: file2, scope: where.scope, rebound: where.rebound },
+      ctx
+    );
+    const placed = outcome.kind === "followed" ? {
+      file: outcome.target.file.displayPath,
+      span: spanOf(outcome.target.node)
+    } : outcome.reason === "noDeclaration" ? null : { file: file2.displayPath, span: spanOf(call) };
+    placements.place(callee, placed);
+    recordPassedArgs(
+      call,
+      callee,
+      outcome.kind === "followed" ? keyOf(outcome.target) : null,
+      where
+    );
+    if (outcome.kind === "stopped") {
+      const stopKey = `${outcome.reason}:${callee}`;
+      if (!seen.has(stopKey) && worthRecording(outcome.reason)) {
+        seen.add(stopKey);
+        stops.push({ callee, reason: outcome.reason });
+      }
+      if (outcome.reason === "callerSupplied" && !parameterCallsSeen.has(callee)) {
+        const parameterIndex = ownParameters.indexOf(callee);
+        if (parameterIndex !== -1) {
+          parameterCallsSeen.add(callee);
+          parameterCalls.push({ callee, parameterIndex });
+        }
+      }
+      return;
+    }
+    const key = keyOf(outcome.target);
+    if (!seen.has(key)) {
+      seen.add(key);
+      followed.push(outcome.target);
+    }
+  };
+  walkDescendants3(
+    body,
+    { scope: scopeAt(file2, node), rebound: reboundNames(body) },
+    {
+      at: (child, where) => {
+        if (child.type === "call") {
+          record2(child, where);
+        }
+      },
+      into: (child, where) => {
+        if (child.type === "function_definition") {
+          return SKIP_CHILDREN2;
+        }
+        if (child.type === "lambda") {
+          return {
+            scope: where.scope,
+            rebound: /* @__PURE__ */ new Set([...where.rebound, ...lambdaParameters(child)])
+          };
+        }
+        return {
+          scope: file2.module.scopeFor.get(child.id) ?? where.scope,
+          rebound: where.rebound
+        };
+      }
+    }
+  );
+  return {
+    followed,
+    stops,
+    targets: placements.targets,
+    argTargets: placements.argTargets,
+    parameterCalls,
+    passedPositions
+  };
+}
+function scopeAt(file2, node) {
+  let current = node;
+  while (current !== null) {
+    const scope = file2.module.scopeFor.get(current.id);
+    if (scope !== void 0) {
+      return scope;
+    }
+    current = current.parent;
+  }
+  return file2.module.moduleScope;
+}
+var REBINDING_FIELDS = {
+  assignment: "left",
+  augmented_assignment: "left",
+  named_expression: "name",
+  for_statement: "left",
+  for_in_clause: "left",
+  as_pattern: "alias"
+};
+function reboundNames(body) {
+  const names = /* @__PURE__ */ new Set();
+  walkDescendants3(body, null, {
+    at: (node) => {
+      const target = REBINDING_FIELDS[node.type];
+      if (target === void 0 || boundByBinder(node, body)) {
+        return;
+      }
+      const written = field(node, target);
+      if (written !== null) {
+        for (const name of identifiersUnder(written)) {
+          names.add(name);
+        }
+      }
+    },
+    into: (node) => node.type === "function_definition" ? SKIP_CHILDREN2 : null
+  });
+  return names;
+}
+function boundByBinder(node, body) {
+  if (node.type !== "assignment") {
+    return false;
+  }
+  const statement = node.parent;
+  return field(node, "left")?.type === "identifier" && statement?.type === "expression_statement" && statement.parent?.id === body.id;
+}
+function identifiersUnder(node, found = []) {
+  if (node.type === "identifier") {
+    found.push(node.text);
+    return found;
+  }
+  for (const child of node.namedChildren) {
+    if (child !== null && child.type !== "attribute" && child.type !== "subscript") {
+      identifiersUnder(child, found);
+    }
+  }
+  return found;
+}
+function lambdaParameters(lambda) {
+  const parameters = field(lambda, "parameters");
+  return parameters === null ? [] : identifiersUnder(parameters);
+}
+function libraryUnit(target, options) {
+  const { file: file2, node, name, exportPath } = target;
+  const body = field(node, "body");
+  const extra = recognizedBodyEffects(
+    node,
+    file2.module,
+    options.storageFor(file2)
+  );
+  const range = rangeOf(node);
+  return {
+    identity: {
+      name,
+      nameKind: "binding",
+      kind: "library",
+      file: file2.displayPath,
+      range,
+      span: spanOf(node),
+      exportName: exportPath[0] ?? name,
+      exportPath
+    },
+    boundaryBinding: functionCallBinding({
+      transport: "in-process",
+      recognition: "reachable"
+    }),
+    parameters: positionalParameters(node, exportPath.length > 1),
+    branches: [
+      {
+        conditions: [],
+        terminal: {
+          kind: "return",
+          statusCode: null,
+          body: null,
+          exceptionType: null,
+          message: null,
+          component: null,
+          renderTree: null,
+          delegateTarget: null,
+          emitEvent: null,
+          location: range
+        },
+        effects: invocationEffects(node),
+        ...extra.length === 0 ? {} : { extraEffects: extra },
+        location: range,
+        isDefault: true
+      }
+    ],
+    bodyContent: body === null ? "absent" : bodyContentOf(body),
+    dependencyCalls: [],
+    declaredContract: null
+  };
+}
+function positionalParameters(node, isMethod) {
+  const parameters = field(node, "parameters");
+  if (parameters === null) {
+    return [];
+  }
+  const out = [];
+  let position = 0;
+  for (const param of parameters.namedChildren) {
+    if (param === null) {
+      continue;
+    }
+    const name = parameterName3(param);
+    if (name === null) {
+      continue;
+    }
+    if (isMethod && position === 0 && (name === "self" || name === "cls")) {
+      position += 1;
+      continue;
+    }
+    out.push({ name, position, role: name, typeText: null });
+    position += 1;
+  }
+  return out;
+}
+function callParameterNames(node, isMethod) {
+  const parameters = field(node, "parameters");
+  if (parameters === null) {
+    return [];
+  }
+  const names = [];
+  for (const param of parameters.namedChildren) {
+    if (param === null) {
+      continue;
+    }
+    const name = parameterName3(param);
+    if (name === null) {
+      continue;
+    }
+    if (isMethod && names.length === 0 && (name === "self" || name === "cls")) {
+      continue;
+    }
+    names.push(name);
+  }
+  return names;
+}
+function parameterName3(param) {
+  if (param.type === "identifier") {
+    return param.text;
+  }
+  const named = field(param, "name");
+  if (named !== null && named.type === "identifier") {
+    return named.text;
+  }
+  return identifiersUnder(param)[0] ?? null;
+}
 
 // src/routers.ts
 var UNSTATED_PREFIX = { kind: "unstated" };
@@ -19544,6 +20676,9 @@ function buildPatternIndex(files, importModule, composition, resolverOptions) {
   for (const bound of files) {
     collectConstructions(bound, importModule, composition, index);
   }
+  for (const bound of files) {
+    collectReturnedConstructions(bound, importModule, composition, index);
+  }
   if (objectPrefix?.carrier !== void 0) {
     const carrier = objectPrefix.carrier;
     for (const bound of files) {
@@ -19719,6 +20854,37 @@ function collectConstructions(bound, importModule, composition, index) {
     );
   }
 }
+function collectReturnedConstructions(bound, importModule, composition, index) {
+  for (const stmt of bodyStatements(bound.root)) {
+    const definition = stripDecorators(stmt).definition;
+    if (definition.type !== "function_definition") {
+      continue;
+    }
+    const scope = bound.module.scopeFor.get(definition.id);
+    for (const inner of nestedStatements(definition)) {
+      if (inner.type !== "return_statement" || scope === void 0) {
+        continue;
+      }
+      const returned = inner.namedChildren[0];
+      if (returned?.type !== "call") {
+        continue;
+      }
+      const callee = field(returned, "function");
+      const constructorName = callee === null ? null : importedConstructorName(callee, scope, importModule);
+      if (constructorName !== composition.routerConstructorName) {
+        continue;
+      }
+      const { keywordArgs } = readCallArguments(field(returned, "arguments"));
+      const valueKey2 = nodeId(bound.file, returned);
+      index.byValueKey.set(valueKey2, {
+        constructorName,
+        valueKey: valueKey2,
+        prefix: constructorPrefix(keywordArgs, composition, scope),
+        reassigned: false
+      });
+    }
+  }
+}
 function collectCarrierConstructions(carrier, composition, scan) {
   walkStatements(
     bodyStatements(scan.bound.root),
@@ -19777,6 +20943,21 @@ function constructionNamed(name, scope, scan, constructions = scan.index.constru
   };
   return resolvers[binding.kind]?.() ?? null;
 }
+function constructionThroughFacts(name, scope, scan) {
+  const facts = scan.index.facts;
+  const binding = resolveName(scope, name);
+  if (facts === void 0 || binding === null) {
+    return null;
+  }
+  if (binding.kind !== "assignment" && binding.kind !== "importFrom") {
+    return null;
+  }
+  const nameKey = `${scan.bound.file}#${name}`;
+  const constructionKey = subjectConstructions(facts, [nameKey]).get(
+    nameKey
+  )?.constructionKey;
+  return constructionKey === void 0 ? null : scan.index.byValueKey.get(constructionKey) ?? null;
+}
 var MOUNT_STATE_BY_EFFECT = {
   prefixes: (statedPrefix, site) => ({
     kind: "mounted",
@@ -19946,10 +21127,10 @@ function constructionsReturnedBy(target, index) {
     return { kind: "unread" };
   }
   const contained = containedValues(facts, returned);
-  resolveCalls(facts, contained);
+  const settled = subjectConstructions(facts, contained);
   const found = [];
   for (const value of contained) {
-    const resolved = resolvedValueKey(facts, value);
+    const resolved = settled.get(value)?.constructionKey ?? value;
     const construction = index.byValueKey.get(resolved);
     if (construction === void 0) {
       return {
@@ -19964,10 +21145,6 @@ function constructionsReturnedBy(target, index) {
   }
   return { kind: "settled", found };
 }
-function resolvedValueKey(facts, value) {
-  const row = facts.facts("wantedIsWrittenAs").find((entry) => String(entry[0]) === value);
-  return row === void 0 ? value : String(row[1]);
-}
 function mountedConstructions(arg, position, scan) {
   if (arg?.kind === "attribute") {
     const construction = constructionThroughModule(arg, position.scope, scan);
@@ -19977,7 +21154,7 @@ function mountedConstructions(arg, position, scan) {
     return [];
   }
   const named = (name) => {
-    const construction = constructionNamed(name, position.scope, scan);
+    const construction = constructionNamed(name, position.scope, scan) ?? constructionThroughFacts(name, position.scope, scan);
     return construction === null ? [] : [construction];
   };
   const target = position.loopBindings.get(arg.name);
@@ -20364,36 +21541,69 @@ function carrierPrefix(carrier, constructorArg, objectName, scope, scan) {
   return readings[construction.prefix.kind]();
 }
 
+// src/version.ts
+import { createAdapterStamp } from "@suss/extractor";
+var ADAPTER_VERSION = "0.1.0";
+var adapterStamp = createAdapterStamp({
+  moduleUrl: import.meta.url,
+  version: ADAPTER_VERSION
+});
+
 // src/project.ts
-function reportUnresolvedProjectModules(options) {
+function reportUnresolvedProjectModules(options, db) {
+  const imported = new Set(db.facts("pyImport").map((row) => String(row[1])));
   for (const pack of options.packs) {
     for (const module of pack.projectModules ?? []) {
-      const resolved = resolveAbsoluteModule(module, { roots: options.roots });
-      if (resolved.status === "resolved") {
+      if (imported.has(module)) {
         continue;
       }
       process.stderr.write(
-        `[suss] ${pack.name}: the configured module ${module} does not resolve under ${options.roots.join(", ")}, so nothing it wraps will be discovered.
+        `[suss] ${pack.name}: no file under ${options.roots.join(", ")} imports ${module}, so the stub for it changes nothing.
 `
       );
     }
   }
 }
 async function extractPythonProject(options) {
-  const db = new Database();
+  const timer = options.onTiming !== void 0 ? createTimer() : noopTimer();
+  const cacheDir = adapterStamp.declineWhenRunFromSource(
+    options.cacheDir === null ? null : options.cacheDir ?? (options.projectRoot !== void 0 ? path3.join(options.projectRoot, ".suss", "cache") : null)
+  );
+  const cache = createCacheLayer(cacheDir);
+  const packsDigest = adapterStamp.packsDigest(
+    options.packs.map(
+      (pack) => pack.version !== void 0 ? { name: pack.name, version: pack.version } : { name: pack.name }
+    )
+  );
+  const cacheInput = {
+    files: cacheDir === null ? [] : options.files,
+    adapterPacksDigest: cacheDir === null ? packsDigest : runDigest(packsDigest, options.packs, options.files)
+  };
+  const lookup = await timer.timeAsync(
+    "cache.lookup",
+    () => cache.lookup(cacheInput)
+  );
+  options.onCacheDiagnostic?.(lookup.diagnostic);
+  if (lookup.kind === "hit") {
+    options.onTiming?.(timer.report());
+    return { summaries: lookup.summaries, facts: new Database3() };
+  }
+  const db = new Database3();
   const summaries = [];
   const gapHandling = options.gapHandling ?? "permissive";
+  const tallies = createPackTallies(options.packs);
   const displayPathOf = (file2) => options.workspaceRoot !== void 0 ? path3.relative(options.workspaceRoot, file2) : file2;
-  reportUnresolvedProjectModules(options);
   const bound = [];
   for (const file2 of options.files) {
-    const source = fs3.readFileSync(file2, "utf8");
-    const tree = await parsePython(source);
-    bound.push({
-      file: file2,
-      displayPath: displayPathOf(file2),
-      root: tree.rootNode,
-      module: bindModule(tree.rootNode)
+    await timer.timeAsync("parse", async () => {
+      const source = fs3.readFileSync(file2, "utf8");
+      const tree = await parsePython(source);
+      bound.push({
+        file: file2,
+        displayPath: displayPathOf(file2),
+        root: tree.rootNode,
+        module: bindModule(tree.rootNode)
+      });
     });
   }
   const mountsRouters = options.packs.some(
@@ -20404,81 +21614,172 @@ async function extractPythonProject(options) {
   const discovers = options.packs.some((pack) => pack.discovery.length > 0);
   const needsValues = discovers || mountsRouters || storagePatterns.length > 0;
   const definitions = /* @__PURE__ */ new Map();
-  for (const { file: file2, root, module: moduleBinding } of bound) {
-    emitModuleImportFacts(db, file2, moduleBinding, { roots: options.roots });
-    if (needsValues) {
-      emitValueFacts(db, file2, root);
-    }
-    if (storagePatterns.length > 0) {
+  timer.time("discover", () => {
+    for (const { file: file2, root, module: moduleBinding } of bound) {
+      emitModuleImportFacts(db, file2, moduleBinding, { roots: options.roots });
+      if (needsValues) {
+        emitValueFacts(db, file2, root);
+      }
       indexDefinitions(definitions, file2, root);
     }
-  }
-  const couldMatch = methodsDeclaredNear(db, storagePatterns, definitions);
-  const startsAQuery = /* @__PURE__ */ new Set([
-    ...couldMatch,
-    ...storagePatterns.flatMap((pattern) => pattern.queryFunctions ?? [])
-  ]);
-  const leadsToStorage = functionsReachingStorage(
-    db,
-    definitions,
-    startsAQuery
-  );
-  const routerIndex = buildRouterIndex(bound, options.packs, {
-    roots: options.roots,
-    ...mountsRouters ? { facts: db } : {}
   });
-  for (const { file: file2, root, module: moduleBinding } of bound) {
+  reportUnresolvedProjectModules(options, db);
+  const couldMatch = timer.time(
+    "discover",
+    () => methodsDeclaredNear(db, storagePatterns, definitions)
+  );
+  const routerIndex = timer.time(
+    "discover",
+    () => buildRouterIndex(bound, options.packs, {
+      roots: options.roots,
+      ...mountsRouters ? { facts: db } : {}
+    })
+  );
+  const storageFor = (file2) => storagePatterns.length > 0 || rawSqlPatterns.length > 0 ? {
+    facts: db,
+    factsPath: file2.file,
+    patterns: storagePatterns,
+    definitionAt: (key) => definitions.get(key),
+    couldMatch,
+    rawSql: rawSqlPatterns
+  } : void 0;
+  const seeds = [];
+  const summariesBySeed = /* @__PURE__ */ new Map();
+  for (const boundFile of bound) {
+    const { file: file2, root, module: moduleBinding } = boundFile;
     const displayPath = displayPathOf(file2);
-    const rawUnits = discoverUnits(root, moduleBinding, {
-      packs: options.packs,
-      filePath: displayPath,
-      absoluteFile: file2,
-      routerIndex,
-      gapHandling,
-      ...needsValues ? { facts: db } : {},
-      ...storagePatterns.length > 0 || rawSqlPatterns.length > 0 ? {
-        storage: {
-          facts: db,
-          factsPath: file2,
-          patterns: storagePatterns,
-          definitionAt: (key) => definitions.get(key),
-          couldMatch,
-          leadsToStorage,
-          rawSql: rawSqlPatterns
-        }
-      } : {}
-    });
+    const storage = storageFor(boundFile);
+    const rawUnits = timer.time(
+      "discover",
+      () => discoverUnits(root, moduleBinding, {
+        packs: options.packs,
+        filePath: displayPath,
+        absoluteFile: file2,
+        routerIndex,
+        gapHandling,
+        ...needsValues ? { facts: db } : {},
+        ...storage === void 0 ? {} : { storage }
+      })
+    );
     for (const raw of rawUnits) {
-      const summary = assembleSummary(raw, { gapHandling });
+      const summary = timer.time(
+        "summarize",
+        () => assembleSummary2(raw, { gapHandling })
+      );
       summary.confidence = { source: "inferred_static", level: "low" };
       summaries.push(summary);
       emitEntryFact(db, file2, raw.identity.range, raw.identity.name);
+      tallyUnit(tallies, raw.boundaryBinding?.recognition);
+      const span = raw.identity.span;
+      const key = span === void 0 ? null : `${file2}:${span.start}-${span.end}`;
+      const node = key === null ? void 0 : definitions.get(key);
+      if (key === null || node === void 0) {
+        continue;
+      }
+      const sharing = summariesBySeed.get(key);
+      if (sharing === void 0) {
+        seeds.push({ key, file: boundFile, node });
+        summariesBySeed.set(key, [summary]);
+      } else {
+        sharing.push(summary);
+      }
     }
+    const loadTimeReads = timer.time(
+      "discover",
+      () => envReadEffects(root, moduleBinding)
+    );
+    if (loadTimeReads.length > 0) {
+      const summary = timer.time(
+        "summarize",
+        () => assembleSummary2(
+          moduleInitStructure({
+            name: path3.basename(displayPath),
+            file: displayPath,
+            range: rangeOf(root),
+            effects: loadTimeReads
+          }),
+          { gapHandling }
+        )
+      );
+      summary.confidence = { source: "inferred_static", level: "low" };
+      summaries.push(summary);
+    }
+  }
+  const reached = timer.time(
+    "summarize",
+    () => reachedFunctions(seeds, {
+      files: bound,
+      roots: options.roots,
+      gapHandling,
+      storageFor
+    })
+  );
+  for (const [key, owners] of summariesBySeed) {
+    for (const summary of owners) {
+      if (gapHandling !== "silent") {
+        summary.gaps.push(
+          ...(reached.stopsByKey.get(key) ?? []).map(unfollowedCallGap2)
+        );
+      }
+      placeCalls2(summary, reached.targetsByKey.get(key));
+      placeArgTargets2(summary, reached.argTargetsByKey.get(key));
+      placeCalleeParameters2(summary, reached.parameterCallsByKey.get(key));
+    }
+  }
+  if (gapHandling !== "silent") {
+    recordParameterGaps2(
+      reached.parameterCallsByKey,
+      summariesBySeed,
+      reached.passedPositions
+    );
+  }
+  summaries.push(...reached.summaries);
+  const resolvedImports = resolvedImportsOf(db, displayPathOf);
+  stampModuleImports(summaries, (file2) => resolvedImports.get(file2) ?? []);
+  const idRoot = options.projectRoot ?? options.workspaceRoot;
+  for (const summary of summaries) {
+    const absoluteFile = options.workspaceRoot === void 0 ? summary.location.file : path3.resolve(options.workspaceRoot, summary.location.file);
+    summary.identity.id = summaryIdFromParts({
+      workspace: void 0,
+      file: idRoot === void 0 ? absoluteFile : path3.relative(idRoot, absoluteFile),
+      name: summary.identity.name,
+      exportPath: summary.identity.exportPath
+    });
   }
-  stampModuleImports(summaries, db, displayPathOf);
+  disambiguateSummaryIds(summaries);
+  linkCallsToSummaries(summaries);
+  await timer.timeAsync("cache.write", async () => {
+    if (cacheDir === null || summaries.length === 0) {
+      return;
+    }
+    try {
+      await cache.write(cacheInput, summaries);
+    } catch {
+    }
+  });
+  options.onExtractionReport?.(
+    buildPythonExtractionReport({
+      packs: options.packs,
+      tallies,
+      filesWalked: options.files.length,
+      summaries
+    })
+  );
+  options.onTiming?.(timer.report());
   return { summaries, facts: db };
 }
-function stampModuleImports(summaries, db, displayPathOf) {
+function resolvedImportsOf(db, displayPathOf) {
   const importsByFile = /* @__PURE__ */ new Map();
   for (const [from, , to] of db.facts("pyImportResolved")) {
     if (typeof from !== "string" || typeof to !== "string") {
       continue;
     }
     const key = displayPathOf(from);
-    const seen = importsByFile.get(key) ?? /* @__PURE__ */ new Set();
-    seen.add(displayPathOf(to));
+    const seen = importsByFile.get(key) ?? [];
+    seen.push(displayPathOf(to));
     importsByFile.set(key, seen);
   }
-  for (const summary of summaries) {
-    const imports = importsByFile.get(summary.location.file);
-    if (imports === void 0 || imports.size === 0) {
-      continue;
-    }
-    summary.metadata = {
-      ...summary.metadata ?? {},
-      moduleImports: [...imports].sort()
-    };
-  }
+  return importsByFile;
 }
 var SKIPPED_DIRECTORIES = /* @__PURE__ */ new Set([
   "__pycache__",
@@ -20533,54 +21834,271 @@ function methodsDeclaredNear(db, patterns, definitions) {
   }
   return found;
 }
-function calledName(call) {
-  const callee = field(call, "function");
-  if (callee === null) {
-    return "";
+
+// src/facts/why.ts
+var FUNCTION_TYPES2 = /* @__PURE__ */ new Set(["function_definition", "lambda"]);
+var IMPORT_TYPES = /* @__PURE__ */ new Set(["import_statement", "import_from_statement"]);
+function namedChildrenOf(node) {
+  return node.namedChildren.filter((child) => child !== null);
+}
+function indexImportNames(file2, stmt, locations) {
+  for (const nameNode of fields(stmt, "name")) {
+    if (nameNode.type === "aliased_import") {
+      const alias = field(nameNode, "alias");
+      if (alias !== null) {
+        locations.set(`${file2}#${alias.text}`, { file: file2, node: alias });
+      }
+      continue;
+    }
+    const local = nameNode.type === "dotted_name" ? nameNode.namedChild(0) : nameNode;
+    if (local !== null) {
+      locations.set(`${file2}#${local.text}`, { file: file2, node: local });
+    }
   }
-  return callee.type === "attribute" ? field(callee, "attribute")?.text ?? "" : callee.text;
 }
-function callsUnder(node, found = []) {
-  for (const child of node.namedChildren) {
-    if (child === null) {
+function enclosingFunction(node) {
+  let current = node.parent;
+  while (current !== null) {
+    if (FUNCTION_TYPES2.has(current.type)) {
+      return current;
+    }
+    current = current.parent;
+  }
+  return null;
+}
+function indexFile(file2, root, locations) {
+  const walk = (node) => {
+    locations.set(nodeId(file2, node), { file: file2, node });
+    if (IMPORT_TYPES.has(node.type)) {
+      indexImportNames(file2, node, locations);
+    }
+    if (FUNCTION_TYPES2.has(node.type) || node.type === "class_definition") {
+      const name = field(node, "name");
+      if (name !== null) {
+        locations.set(`${file2}#${name.text}`, { file: file2, node: name });
+      }
+    }
+    if (node.type === "assignment") {
+      const left = field(node, "left");
+      if (left !== null && left.type === "identifier") {
+        locations.set(`${file2}#${left.text}`, { file: file2, node: left });
+      }
+    }
+    for (const child of namedChildrenOf(node)) {
+      walk(child);
+    }
+  };
+  walk(root);
+}
+function displayNameOf(node) {
+  if (node.type === "identifier") {
+    return node.text;
+  }
+  if (node.type === "call") {
+    const callee = field(node, "function");
+    return `${callee?.text ?? "call"}(...)`;
+  }
+  if (node.type === "function_definition" || node.type === "class_definition") {
+    return field(node, "name")?.text ?? node.text;
+  }
+  const text = node.text.split("\n")[0].trim();
+  return text.length > 40 ? `${text.slice(0, 40)}...` : text;
+}
+function width(node) {
+  return node.endIndex - node.startIndex;
+}
+var PythonWhySession = class {
+  root;
+  db = new Database4();
+  locations = /* @__PURE__ */ new Map();
+  trees = /* @__PURE__ */ new Map();
+  constructor(options) {
+    this.root = path4.resolve(options.dir);
+    const roots = [this.root];
+    for (const file2 of findPythonFiles(this.root)) {
+      const source = fs4.readFileSync(file2, "utf8");
+      const root = parsePythonSync(source).rootNode;
+      this.trees.set(file2, root);
+      emitModuleImportFacts(this.db, file2, bindModule(root), { roots });
+      emitValueFacts(this.db, file2, root);
+      indexFile(file2, root, this.locations);
+    }
+  }
+  /**
+   * The smallest expression on `line` of `file` whose text is exactly
+   * `text`, or null.
+   */
+  findExpression(file2, line, text) {
+    const root = this.rootOf(file2);
+    if (root === null) {
+      return null;
+    }
+    let found = null;
+    const visit = (node) => {
+      if (node.startPosition.row + 1 === line && node.text === text) {
+        if (found === null || width(node) <= width(found)) {
+          found = node;
+        }
+      }
+      for (const child of namedChildrenOf(node)) {
+        visit(child);
+      }
+    };
+    visit(root);
+    return found === null ? null : { file: this.pathOf(file2), node: found };
+  }
+  /**
+   * The callee of the call written as `calleeText` between `startLine`
+   * and `endLine` of `file`, or null.
+   */
+  findCallee(file2, startLine, endLine, calleeText2) {
+    const root = this.rootOf(file2);
+    if (root === null) {
+      return null;
+    }
+    let found = null;
+    const visit = (node) => {
+      if (node.type === "call") {
+        const line = node.startPosition.row + 1;
+        const callee = field(node, "function");
+        if (line >= startLine && line <= endLine && callee !== null && callee.text === calleeText2) {
+          found = callee;
+        }
+      }
+      for (const child of namedChildrenOf(node)) {
+        visit(child);
+      }
+    };
+    visit(root);
+    return found === null ? null : { file: this.pathOf(file2), node: found };
+  }
+  /**
+   * Why `value` resolves to what it does: the witness proof, flattened
+   * to the chain and rendered. Null when the value does not resolve,
+   * which the caller says in its own words.
+   */
+  explain(value, options = {}) {
+    return explainResolvedKey({
+      db: this.db,
+      rules: RESOLUTION_RULES,
+      key: readKey(value.file, value.node, enclosingFunction(value.node)),
+      locate: (key) => this.locate(key),
+      displayPath: (key) => this.displayPath(key),
+      ...options
+    });
+  }
+  locate(key) {
+    const located = this.locations.get(key);
+    if (located === void 0) {
+      return null;
+    }
+    return {
+      name: displayNameOf(located.node),
+      file: this.displayPath(located.file),
+      line: located.node.startPosition.row + 1
+    };
+  }
+  rootOf(file2) {
+    return this.trees.get(this.pathOf(file2)) ?? null;
+  }
+  pathOf(file2) {
+    return path4.isAbsolute(file2) ? file2 : path4.resolve(this.root, file2);
+  }
+  /** A file path said relative to the root, or as given when it is outside the root. */
+  displayPath(key) {
+    if (key.startsWith(this.root)) {
+      return path4.relative(this.root, key);
+    }
+    return key;
+  }
+};
+
+// src/stubEvidence.ts
+import fs5 from "fs";
+import path5 from "path";
+function importsSubmoduleOf(module, packageName) {
+  return module === packageName || module.startsWith(`${packageName}.`);
+}
+function importStatementModules(stmt) {
+  const modules = [];
+  for (const nameNode of fields(stmt, "name")) {
+    if (nameNode.type === "aliased_import") {
+      const dotted = field(nameNode, "name");
+      if (dotted !== null) {
+        modules.push(dotted.text);
+      }
       continue;
     }
-    if (child.type === "call") {
-      found.push(child);
+    if (nameNode.type === "dotted_name") {
+      modules.push(nameNode.text);
     }
-    callsUnder(child, found);
   }
-  return found;
+  return modules;
 }
-var REACHES_STORAGE_RULES = [
-  rule2(
-    "reachesStorage",
-    [v2("f")],
-    [lit2("defCallsName", v2("f"), v2("m")), lit2("queryStart", v2("m"))]
-  ),
-  rule2(
-    "reachesStorage",
-    [v2("f")],
-    [lit2("defCallsName", v2("f"), v2("m")), lit2("reachesStorage", v2("m"))]
-  )
-];
-function functionsReachingStorage(db, definitions, couldMatch) {
-  for (const node of definitions.values()) {
-    const name = field(node, "name");
-    if (name === null) {
+function importFromStatementEntries(stmt) {
+  const moduleNode = field(stmt, "module_name");
+  if (moduleNode === null || moduleNode.type === "relative_import") {
+    return [];
+  }
+  const module = moduleNode.text;
+  const entries = [];
+  for (const nameNode of fields(stmt, "name")) {
+    if (nameNode.type === "aliased_import") {
+      const original = field(nameNode, "name");
+      if (original !== null) {
+        entries.push({ module, name: original.text });
+      }
       continue;
     }
-    for (const called of callsUnder(node).map(calledName)) {
-      db.add("defCallsName", [name.text, called]);
+    if (nameNode.type === "dotted_name") {
+      entries.push({ module, name: nameNode.text });
     }
   }
-  for (const name of couldMatch) {
-    db.add("queryStart", [name]);
+  return entries;
+}
+function importSitesIn(root) {
+  const found = [];
+  const visit = (node) => {
+    if (node.type === "import_statement") {
+      const line = rangeOf(node).start;
+      for (const module of importStatementModules(node)) {
+        found.push({ module, name: null, line });
+      }
+    } else if (node.type === "import_from_statement") {
+      const line = rangeOf(node).start;
+      for (const entry of importFromStatementEntries(node)) {
+        found.push({ module: entry.module, name: entry.name, line });
+      }
+    }
+    for (const child of node.namedChildren) {
+      if (child !== null) {
+        visit(child);
+      }
+    }
+  };
+  visit(root);
+  return found;
+}
+async function pythonImportEvidence(options) {
+  const byModule = /* @__PURE__ */ new Map();
+  for (const file2 of findPythonFiles(options.directory)) {
+    const source = fs5.readFileSync(file2, "utf8");
+    const tree = await parsePython(source);
+    const displayPath = path5.relative(options.directory, file2);
+    for (const site of importSitesIn(tree.rootNode)) {
+      if (!importsSubmoduleOf(site.module, options.packageName)) {
+        continue;
+      }
+      const sites = byModule.get(site.module) ?? [];
+      sites.push({ name: site.name, file: displayPath, line: site.line });
+      byModule.set(site.module, sites);
+    }
   }
-  evaluate2(db, REACHES_STORAGE_RULES);
-  return new Set(db.facts("reachesStorage").map((row) => String(row[0])));
+  return [...byModule.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([module, sites]) => ({ module, sites }));
 }
 export {
+  ADAPTER_VERSION,
+  PythonWhySession,
   annotationToShape,
   bindModule,
   buildRouterIndex,
@@ -20595,6 +22113,10 @@ export {
   nodeId,
   objectReturnedBy,
   parsePython,
+  parsePythonSync,
+  preloadPythonGrammar,
+  pythonImportEvidence,
+  readKey,
   resolveAbsoluteModule,
   resolveCalls,
   resolveModule,