@suss/adapter-ruby 0.21.1 → 0.22.1

package/dist/index.js

@@ -29,6 +29,7 @@ var OWN_BODY_TYPES = /* @__PURE__ */ new Set([
   "module",
   "singleton_class"
 ]);
+var NESTING_TYPES = /* @__PURE__ */ new Set(["class", "module"]);
 var ARGUMENT_LIST_TYPE = "argument_list";
 function runStatements(body, blockConfigures = () => false) {
   const found = [];
@@ -46,6 +47,22 @@ function runStatements(body, blockConfigures = () => false) {
   });
   return found;
 }
+function stringLiteralValue(node) {
+  if (node.type !== "string") {
+    return null;
+  }
+  let content = "";
+  for (const child of bodyStatements(node)) {
+    if (child.type === "string_content") {
+      content += child.text;
+      continue;
+    }
+    if (child.type === "interpolation") {
+      return null;
+    }
+  }
+  return content;
+}
 function symbolValue(node) {
   return node.type === "simple_symbol" ? node.text.slice(1) : null;
 }
@@ -62,6 +79,71 @@ function instanceMethodsByName(body) {
   }
   return methods;
 }
+var VISIBILITY_KEYWORDS = /* @__PURE__ */ new Set([
+  "private",
+  "protected",
+  "public"
+]);
+function visibilityKeyword(text) {
+  return VISIBILITY_KEYWORDS.has(text) ? text : null;
+}
+function setVisibility(visibility, name, keyword) {
+  if (keyword === "public") {
+    visibility.delete(name);
+    return;
+  }
+  visibility.set(name, keyword);
+}
+function markCalledOutMethods(call, keyword, visibility) {
+  const argumentList = field(call, "arguments");
+  if (argumentList === null) {
+    return;
+  }
+  for (const arg of bodyStatements(argumentList)) {
+    const name = arg.type === "method" ? field(arg, "name")?.text : symbolValue(arg);
+    if (name !== void 0 && name !== null) {
+      setVisibility(visibility, name, keyword);
+    }
+  }
+}
+function instanceMethodVisibility(body) {
+  const visibility = /* @__PURE__ */ new Map();
+  let mode = "public";
+  for (const stmt of bodyStatements(body)) {
+    if (stmt.type === "method") {
+      const name = field(stmt, "name")?.text;
+      if (name !== void 0) {
+        setVisibility(visibility, name, mode);
+      }
+      continue;
+    }
+    if (stmt.type === "identifier") {
+      mode = visibilityKeyword(stmt.text) ?? mode;
+      continue;
+    }
+    if (stmt.type !== "call" || field(stmt, "receiver") !== null) {
+      continue;
+    }
+    const keyword = visibilityKeyword(field(stmt, "method")?.text ?? "");
+    if (keyword !== null) {
+      markCalledOutMethods(stmt, keyword, visibility);
+    }
+  }
+  return visibility;
+}
+function singletonMethodsByName(body) {
+  const methods = /* @__PURE__ */ new Map();
+  for (const stmt of runStatements(body)) {
+    if (stmt.type !== "singleton_method") {
+      continue;
+    }
+    const name = field(stmt, "name")?.text;
+    if (name !== void 0) {
+      methods.set(name, stmt);
+    }
+  }
+  return methods;
+}
 function bareCallArgumentGroups(body, name) {
   const groups = [];
   for (const stmt of runStatements(body)) {
@@ -249,7 +331,10 @@ async function reachDefinition(qualifiedName, lookup) {
     qualifiedName,
     lookup.pathConvention
   );
-  const fileRoot = filePath === null ? null : await lookup.parsedFile(filePath);
+  if (filePath === null) {
+    return null;
+  }
+  const fileRoot = await lookup.parsedFile(filePath);
   if (fileRoot === null) {
     return null;
   }
@@ -260,7 +345,7 @@ async function reachDefinition(qualifiedName, lookup) {
     return null;
   }
   const knownClasses = new Set(all.map((info) => info.qualifiedName));
-  return matches.map((info) => ({ info, knownClasses }));
+  return matches.map((info) => ({ info, knownClasses, file: filePath }));
 }
 function ancestryOf(name, blocks, lookup) {
   return chainOf(
@@ -352,17 +437,19 @@ function methodInAncestry(ancestry, name) {
     if (entry.type === "unfollowed") {
       return {
         type: "unsettled",
-        reason: `inherited from ${entry.name}, which this run did not read`
+        reason: `inherited from ${entry.name}, which this run did not read`,
+        cause: "unreadAncestor"
       };
     }
     const found = definitionIn(entry.blocks, name);
-    if (found.method !== null) {
-      return { type: "found", method: found.method };
+    if (found.method !== null && found.block !== null) {
+      return { type: "found", method: found.method, block: found.block };
     }
     if (found.dynamic) {
       return {
         type: "unsettled",
-        reason: "defined with define_method, which this reader does not follow"
+        reason: "defined with define_method, which this reader does not follow",
+        cause: "dynamicDefine"
       };
     }
   }
@@ -370,16 +457,21 @@ function methodInAncestry(ancestry, name) {
 }
 function definitionIn(blocks, name) {
   let method = null;
+  let block = null;
   let dynamic = false;
-  for (const block of blocks) {
-    const body = block.info.bodyNode;
+  for (const candidate of blocks) {
+    const body = candidate.info.bodyNode;
     if (body === null) {
       continue;
     }
-    method = instanceMethodsByName(body).get(name) ?? method;
+    const found = instanceMethodsByName(body).get(name);
+    if (found !== void 0) {
+      method = found;
+      block = candidate;
+    }
     dynamic ||= bareCallArgumentGroups(body, DEFINE_METHOD_CALL).length > 0;
   }
-  return { method, dynamic };
+  return { method, block, dynamic };
 }
 function inheritedStatements(ancestry, blockConfigures) {
   const statements = [];
@@ -401,9 +493,114 @@ function inheritedStatements(ancestry, blockConfigures) {
 }
 
 // src/discovery.ts
-import { dispatchByType as dispatchByType2, graphqlResolverBinding } from "@suss/behavioral-ir";
+import {
+  dispatchByType as dispatchByType2,
+  graphqlResolverBinding,
+  restBinding
+} from "@suss/behavioral-ir";
 import { unreadableReading } from "@suss/extractor";
 
+// src/envReads.ts
+import { runtimeConfigBinding } from "@suss/behavioral-ir";
+import { SKIP_CHILDREN as SKIP_CHILDREN2, walkDescendants as walkDescendants2 } from "@suss/extractor";
+var RUBY_ENV_RECOGNITION = "ruby-env";
+var DEFERRED_BODY_TYPES = /* @__PURE__ */ new Set(["method", "singleton_method", "lambda"]);
+function envReadEffects(root) {
+  const effects = [];
+  walkDescendants2(root, null, {
+    at: (node) => {
+      const read = envReadAt(node);
+      if (read !== null) {
+        effects.push(configReadEffect(read));
+      }
+    },
+    into: (node) => DEFERRED_BODY_TYPES.has(node.type) ? SKIP_CHILDREN2 : null
+  });
+  return effects;
+}
+function configReadEffect(read) {
+  return {
+    type: "interaction",
+    binding: runtimeConfigBinding({
+      recognition: RUBY_ENV_RECOGNITION,
+      deploymentTarget: "lambda",
+      instanceName: "<unknown>"
+    }),
+    callee: `ENV["${read.name}"]`,
+    interaction: {
+      class: "config-read",
+      name: read.name,
+      defaulted: read.defaulted
+    }
+  };
+}
+function envReadAt(node) {
+  if (node.type === "element_reference") {
+    return elementRead(node);
+  }
+  if (node.type === "call") {
+    return fetchRead(node);
+  }
+  return null;
+}
+function elementRead(node) {
+  const object2 = field(node, "object");
+  if (object2 === null || !isEnv(object2) || isAssignedTo(node)) {
+    return null;
+  }
+  const index = node.namedChildren.find(
+    (child) => child !== null && child.id !== object2.id
+  );
+  const name = index === void 0 ? null : stringLiteralValue(index);
+  if (name === null) {
+    return null;
+  }
+  return { name, defaulted: isDefaultedAt(node) };
+}
+function fetchRead(node) {
+  const receiver = field(node, "receiver");
+  if (receiver === null || !isEnv(receiver) || field(node, "method")?.text !== "fetch") {
+    return null;
+  }
+  const { positional } = readCallArgs(field(node, "arguments"));
+  const name = positional[0] === void 0 ? null : stringLiteralValue(positional[0]);
+  if (name === null) {
+    return null;
+  }
+  const hasDefault = positional.length > 1 || field(node, "block") !== null;
+  return { name, defaulted: hasDefault || isDefaultedAt(node) };
+}
+function isEnv(node) {
+  if (node.type === "constant") {
+    return node.text === "ENV";
+  }
+  return node.type === "scope_resolution" && field(node, "scope") === null && field(node, "name")?.text === "ENV";
+}
+function isAssignedTo(node) {
+  const parent = node.parent;
+  return parent !== null && (parent.type === "assignment" || parent.type === "operator_assignment") && field(parent, "left")?.id === node.id;
+}
+function isDefaultedAt(node) {
+  let child = node;
+  let parent = node.parent;
+  while (parent !== null) {
+    if (parent.type === "parenthesized_statements") {
+      child = parent;
+      parent = parent.parent;
+      continue;
+    }
+    if (parent.type !== "binary" || field(parent, "operator")?.text !== "||") {
+      return false;
+    }
+    if (field(parent, "left")?.id === child.id) {
+      return true;
+    }
+    child = parent;
+    parent = parent.parent;
+  }
+  return false;
+}
+
 // src/paths/effects.ts
 import { enumerateOrDegrade, sharedGatingConditions } from "@suss/extractor";
 
@@ -656,8 +853,18 @@ function withoutChainLinks(calls) {
   }
   return calls.filter((call) => !isLink.has(call.id));
 }
+function calleeMethodName(call) {
+  const method = field(call, "method");
+  if (method !== null) {
+    return method.text;
+  }
+  return field(call, "receiver") !== null ? "call" : children(call)[0]?.text;
+}
 function isPropertyRead(node) {
-  return field(node, "receiver") !== null && field(node, "arguments") === null;
+  if (field(node, "receiver") === null || field(node, "arguments") !== null) {
+    return false;
+  }
+  return calleeMethodName(node) !== "call";
 }
 function isRaise2(node) {
   const method = field(node, "method") ?? children(node)[0] ?? null;
@@ -677,11 +884,11 @@ function bodyCalls(node, found = []) {
 }
 function calleeText(call) {
   const receiver = field(call, "receiver");
-  const method = field(call, "method") ?? children(call)[0];
+  const method = calleeMethodName(call);
   if (method === void 0) {
     return call.text;
   }
-  return receiver === null ? method.text : `${receiver.text}.${method.text}`;
+  return receiver === null ? method : `${receiver.text}.${method}`;
 }
 function argOf(node) {
   const literal2 = LITERAL_ARGS[node.type]?.(node);
@@ -752,7 +959,7 @@ function invocationEffects(definitionNode) {
 }
 
 // src/storage.ts
-import { deriveOnDemand, evaluate } from "@suss/datalog";
+import { deriveOnDemand, evaluate as evaluate2 } from "@suss/datalog";
 
 // ../../../node_modules/zod/v4/classic/external.js
 var external_exports = {};
@@ -1434,8 +1641,8 @@ function assertNever(_x) {
 function assert(_) {
 }
 function getEnumValues(entries) {
-  const numericValues = Object.values(entries).filter((v2) => typeof v2 === "number");
-  const values = Object.entries(entries).filter(([k, _]) => numericValues.indexOf(+k) === -1).map(([_, v2]) => v2);
+  const numericValues = Object.values(entries).filter((v4) => typeof v4 === "number");
+  const values = Object.entries(entries).filter(([k, _]) => numericValues.indexOf(+k) === -1).map(([_, v4]) => v4);
   return values;
 }
 function joinValues(array2, separator = "|") {
@@ -1489,9 +1696,9 @@ function defineLazy(object2, key, getter) {
       }
       return value;
     },
-    set(v2) {
+    set(v4) {
       Object.defineProperty(object2, key, {
-        value: v2
+        value: v4
         // configurable: true,
       });
     },
@@ -1520,10 +1727,10 @@ function mergeDefs(...defs) {
 function cloneDef(schema) {
   return mergeDefs(schema._zod.def);
 }
-function getElementAtPath(obj, path4) {
-  if (!path4)
+function getElementAtPath(obj, path7) {
+  if (!path7)
     return obj;
-  return path4.reduce((acc, key) => acc?.[key], obj);
+  return path7.reduce((acc, key) => acc?.[key], obj);
 }
 function promiseAllObject(promisesObj) {
   const keys = Object.keys(promisesObj);
@@ -1932,11 +2139,11 @@ function explicitlyAborted(x, startIndex = 0) {
   }
   return false;
 }
-function prefixIssues(path4, issues) {
+function prefixIssues(path7, issues) {
   return issues.map((iss) => {
     var _a3;
     (_a3 = iss).path ?? (_a3.path = []);
-    iss.path.unshift(path4);
+    iss.path.unshift(path7);
     return iss;
   });
 }
@@ -2083,16 +2290,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, path7 = []) => {
     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 }, [...path7, ...issue2.path]));
       } else if (issue2.code === "invalid_key") {
-        processError({ issues: issue2.issues }, [...path4, ...issue2.path]);
+        processError({ issues: issue2.issues }, [...path7, ...issue2.path]);
       } else if (issue2.code === "invalid_element") {
-        processError({ issues: issue2.issues }, [...path4, ...issue2.path]);
+        processError({ issues: issue2.issues }, [...path7, ...issue2.path]);
       } else {
-        const fullpath = [...path4, ...issue2.path];
+        const fullpath = [...path7, ...issue2.path];
         if (fullpath.length === 0) {
           fieldErrors._errors.push(mapper(issue2));
         } else {
@@ -2119,17 +2326,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, path7 = []) => {
     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 }, [...path7, ...issue2.path]));
       } else if (issue2.code === "invalid_key") {
-        processError({ issues: issue2.issues }, [...path4, ...issue2.path]);
+        processError({ issues: issue2.issues }, [...path7, ...issue2.path]);
       } else if (issue2.code === "invalid_element") {
-        processError({ issues: issue2.issues }, [...path4, ...issue2.path]);
+        processError({ issues: issue2.issues }, [...path7, ...issue2.path]);
       } else {
-        const fullpath = [...path4, ...issue2.path];
+        const fullpath = [...path7, ...issue2.path];
         if (fullpath.length === 0) {
           result.errors.push(mapper(issue2));
           continue;
@@ -2161,8 +2368,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 path7 = _path.map((seg) => typeof seg === "object" ? seg.key : seg);
+  for (const seg of path7) {
     if (typeof seg === "number")
       segs.push(`[${seg}]`);
     else if (typeof seg === "symbol")
@@ -3178,10 +3385,10 @@ var $ZodUUID = /* @__PURE__ */ $constructor("$ZodUUID", (inst, def) => {
       v7: 7,
       v8: 8
     };
-    const v2 = versionMap[def.version];
-    if (v2 === void 0)
+    const v4 = versionMap[def.version];
+    if (v4 === void 0)
       throw new Error(`Invalid UUID version: "${def.version}"`);
-    def.pattern ?? (def.pattern = uuid(v2));
+    def.pattern ?? (def.pattern = uuid(v4));
   } else
     def.pattern ?? (def.pattern = uuid());
   $ZodStringFormat.init(inst, def);
@@ -3786,8 +3993,8 @@ var $ZodObject = /* @__PURE__ */ $constructor("$ZodObject", (inst, def) => {
       const field2 = shape[key]._zod;
       if (field2.values) {
         propValues[key] ?? (propValues[key] = /* @__PURE__ */ new Set());
-        for (const v2 of field2.values)
-          propValues[key].add(v2);
+        for (const v4 of field2.values)
+          propValues[key].add(v4);
       }
     }
     return propValues;
@@ -4082,10 +4289,10 @@ var $ZodDiscriminatedUnion = /* @__PURE__ */ $constructor("$ZodDiscriminatedUnio
       const pv = option._zod.propValues;
       if (!pv || Object.keys(pv).length === 0)
         throw new Error(`Invalid discriminated union option at index "${def.options.indexOf(option)}"`);
-      for (const [k, v2] of Object.entries(pv)) {
+      for (const [k, v4] of Object.entries(pv)) {
         if (!propValues[k])
           propValues[k] = /* @__PURE__ */ new Set();
-        for (const val of v2) {
+        for (const val of v4) {
           propValues[k].add(val);
         }
       }
@@ -4099,11 +4306,11 @@ var $ZodDiscriminatedUnion = /* @__PURE__ */ $constructor("$ZodDiscriminatedUnio
       const values = o._zod.propValues?.[def.discriminator];
       if (!values || values.size === 0)
         throw new Error(`Invalid discriminated union option at index "${def.options.indexOf(o)}"`);
-      for (const v2 of values) {
-        if (map2.has(v2)) {
-          throw new Error(`Duplicate discriminator value "${String(v2)}"`);
+      for (const v4 of values) {
+        if (map2.has(v4)) {
+          throw new Error(`Duplicate discriminator value "${String(v4)}"`);
         }
-        map2.set(v2, o);
+        map2.set(v4, o);
       }
     }
     return map2;
@@ -4742,8 +4949,8 @@ var $ZodPrefault = /* @__PURE__ */ $constructor("$ZodPrefault", (inst, def) => {
 var $ZodNonOptional = /* @__PURE__ */ $constructor("$ZodNonOptional", (inst, def) => {
   $ZodType.init(inst, def);
   defineLazy(inst._zod, "values", () => {
-    const v2 = def.innerType._zod.values;
-    return v2 ? new Set([...v2].filter((x) => x !== void 0)) : void 0;
+    const v4 = def.innerType._zod.values;
+    return v4 ? new Set([...v4].filter((x) => x !== void 0)) : void 0;
   });
   inst._zod.parse = (payload, ctx) => {
     const result = def.innerType._zod.run(payload, ctx);
@@ -7140,7 +7347,7 @@ var error17 = () => {
         if (issue2.values.length === 1) {
           return `\u05E2\u05E8\u05DA \u05DC\u05D0 \u05EA\u05E7\u05D9\u05DF: \u05D4\u05E2\u05E8\u05DA \u05D7\u05D9\u05D9\u05D1 \u05DC\u05D4\u05D9\u05D5\u05EA ${stringifyPrimitive(issue2.values[0])}`;
         }
-        const stringified = issue2.values.map((v2) => stringifyPrimitive(v2));
+        const stringified = issue2.values.map((v4) => stringifyPrimitive(v4));
         if (issue2.values.length === 2) {
           return `\u05E2\u05E8\u05DA \u05DC\u05D0 \u05EA\u05E7\u05D9\u05DF: \u05D4\u05D0\u05E4\u05E9\u05E8\u05D5\u05D9\u05D5\u05EA \u05D4\u05DE\u05EA\u05D0\u05D9\u05DE\u05D5\u05EA \u05D4\u05DF ${stringified[0]} \u05D0\u05D5 ${stringified[1]}`;
         }
@@ -11895,7 +12102,7 @@ function _set(Class2, valueType, params) {
 }
 // @__NO_SIDE_EFFECTS__
 function _enum(Class2, values, params) {
-  const entries = Array.isArray(values) ? Object.fromEntries(values.map((v2) => [v2, v2])) : values;
+  const entries = Array.isArray(values) ? Object.fromEntries(values.map((v4) => [v4, v4])) : values;
   return new Class2({
     type: "enum",
     entries,
@@ -12100,8 +12307,8 @@ function _stringbool(Classes, _params) {
   let truthyArray = params.truthy ?? ["true", "1", "yes", "on", "y", "enabled"];
   let falsyArray = params.falsy ?? ["false", "0", "no", "off", "n", "disabled"];
   if (params.case !== "sensitive") {
-    truthyArray = truthyArray.map((v2) => typeof v2 === "string" ? v2.toLowerCase() : v2);
-    falsyArray = falsyArray.map((v2) => typeof v2 === "string" ? v2.toLowerCase() : v2);
+    truthyArray = truthyArray.map((v4) => typeof v4 === "string" ? v4.toLowerCase() : v4);
+    falsyArray = falsyArray.map((v4) => typeof v4 === "string" ? v4.toLowerCase() : v4);
   }
   const truthySet = new Set(truthyArray);
   const falsySet = new Set(falsyArray);
@@ -12643,9 +12850,9 @@ var dateProcessor = (_schema, ctx, _json, _params) => {
 var enumProcessor = (schema, _ctx, json2, _params) => {
   const def = schema._zod.def;
   const values = getEnumValues(def.entries);
-  if (values.every((v2) => typeof v2 === "number"))
+  if (values.every((v4) => typeof v4 === "number"))
     json2.type = "number";
-  if (values.every((v2) => typeof v2 === "string"))
+  if (values.every((v4) => typeof v4 === "string"))
     json2.type = "string";
   json2.enum = values;
 };
@@ -12678,13 +12885,13 @@ var literalProcessor = (schema, ctx, json2, _params) => {
       json2.const = val;
     }
   } else {
-    if (vals.every((v2) => typeof v2 === "number"))
+    if (vals.every((v4) => typeof v4 === "number"))
       json2.type = "number";
-    if (vals.every((v2) => typeof v2 === "string"))
+    if (vals.every((v4) => typeof v4 === "string"))
       json2.type = "string";
-    if (vals.every((v2) => typeof v2 === "boolean"))
+    if (vals.every((v4) => typeof v4 === "boolean"))
       json2.type = "boolean";
-    if (vals.every((v2) => v2 === null))
+    if (vals.every((v4) => v4 === null))
       json2.type = "null";
     json2.enum = vals;
   }
@@ -12782,11 +12989,11 @@ var objectProcessor = (schema, ctx, _json, params) => {
   }
   const allKeys = new Set(Object.keys(shape));
   const requiredKeys = new Set([...allKeys].filter((key) => {
-    const v2 = def.shape[key]._zod;
+    const v4 = def.shape[key]._zod;
     if (ctx.io === "input") {
-      return v2.optin === void 0;
+      return v4.optin === void 0;
     } else {
-      return v2.optout === void 0;
+      return v4.optout === void 0;
     }
   }));
   if (requiredKeys.size > 0) {
@@ -12906,7 +13113,7 @@ var recordProcessor = (schema, ctx, _json, params) => {
   }
   const keyValues = keyType._zod.values;
   if (keyValues) {
-    const validKeyValues = [...keyValues].filter((v2) => typeof v2 === "string" || typeof v2 === "number");
+    const validKeyValues = [...keyValues].filter((v4) => typeof v4 === "string" || typeof v4 === "number");
     if (validKeyValues.length > 0) {
       json2.required = validKeyValues;
     }
@@ -13471,12 +13678,12 @@ function _installLazyMethods(inst, group, methods) {
         });
         return bound;
       },
-      set(v2) {
+      set(v4) {
         Object.defineProperty(this, key, {
           configurable: true,
           writable: true,
           enumerable: true,
-          value: v2
+          value: v4
         });
       }
     });
@@ -14364,7 +14571,7 @@ var ZodEnum = /* @__PURE__ */ $constructor("ZodEnum", (inst, def) => {
   };
 });
 function _enum2(values, params) {
-  const entries = Array.isArray(values) ? Object.fromEntries(values.map((v2) => [v2, v2])) : values;
+  const entries = Array.isArray(values) ? Object.fromEntries(values.map((v4) => [v4, v4])) : values;
   return new ZodEnum({
     type: "enum",
     entries,
@@ -14854,13 +15061,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 path7 = ref.slice(1).split("/").filter(Boolean);
+  if (path7.length === 0) {
     return ctx.rootSchema;
   }
   const defsKey = ctx.version === "draft-2020-12" ? "$defs" : "definitions";
-  if (path4[0] === defsKey) {
-    const key = path4[1];
+  if (path7[0] === defsKey) {
+    const key = path7[1];
     if (!key || !ctx.defs[key]) {
       throw new Error(`Reference not found: ${ref}`);
     }
@@ -14918,10 +15125,10 @@ function convertBaseSchema(schema, ctx) {
     if (enumValues.length === 1) {
       return z.literal(enumValues[0]);
     }
-    if (enumValues.every((v2) => typeof v2 === "string")) {
+    if (enumValues.every((v4) => typeof v4 === "string")) {
       return z.enum(enumValues);
     }
-    const literalSchemas = enumValues.map((v2) => z.literal(v2));
+    const literalSchemas = enumValues.map((v4) => z.literal(v4));
     if (literalSchemas.length < 2) {
       return literalSchemas[0];
     }
@@ -15620,8 +15827,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(path7) {
+  let normalized = path7.replace(/:([a-zA-Z_]\w*)/g, "{$1}");
   if (normalized.length > 1 && normalized.endsWith("/")) {
     normalized = normalized.slice(0, -1);
   }
@@ -15631,8 +15838,8 @@ function normalizePath(path4) {
   );
   return normalized;
 }
-function pathShape(path4) {
-  return normalizePath(path4).replace(/\{[^}]*\}/g, "{}");
+function pathShape(path7) {
+  return normalizePath(path7).replace(/\{[^}]*\}/g, "{}");
 }
 function methodsAgree(a, b) {
   if (a === null || b === null) {
@@ -15710,8 +15917,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 path7 = semantics.path === null ? "?" : normalizePath(semantics.path);
+      return `${method} ${path7}`;
     },
     /**
      * A route with both halves stated decides for itself: the method
@@ -15720,14 +15927,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, path7) {
       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, path7) ? "match" : "nomatch";
     },
     /**
      * A route the registration pattern admits is inside it. A route
@@ -16146,7 +16353,291 @@ function storageBinding(opts) {
 
 // ../../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 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 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 VALUE_STEP = constant("value");
 var NAMESPACE_IMPORT_NAME = "*";
 var NAMESPACE_IMPORT = constant(NAMESPACE_IMPORT_NAME);
@@ -16338,6 +16829,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(
@@ -16899,11 +17402,11 @@ var ANCESTRY_PROGRAM = deriveOnDemand(
 );
 function reachesBase(facts, classKey, bases) {
   facts.add("wantedAncestry", [classKey]);
-  evaluate(facts, ANCESTRY_PROGRAM.rules);
+  evaluate2(facts, ANCESTRY_PROGRAM.rules);
   return facts.lookup("wantedBaseName", 0, classKey).some((row) => bases.includes(String(row[1])));
 }
-function classBehind(facts, constant2) {
-  const wanted = `#${constant2.text}`;
+function classBehind(facts, constant3) {
+  const wanted = `#${constant3.text}`;
   const bound = new Set(
     facts.facts("binds").filter((row) => String(row[0]).endsWith(wanted)).map((row) => String(row[1]))
   );
@@ -16946,11 +17449,11 @@ function storageEffects(calls, options) {
     if (partOfOne.has(call.id)) {
       continue;
     }
-    const constant2 = rootConstant(call);
-    if (constant2 === null) {
+    const constant3 = rootConstant(call);
+    if (constant3 === null) {
       continue;
     }
-    const classKey = classBehind(options.facts, constant2);
+    const classKey = classBehind(options.facts, constant3);
     if (classKey === void 0) {
       continue;
     }
@@ -16968,7 +17471,7 @@ function storageEffects(calls, options) {
         recognition: "ruby-storage",
         storageSystem: pattern.storageSystem,
         scope: pattern.baseClasses[0] ?? "",
-        container: constant2.text
+        container: constant3.text
       }),
       callee: call.text,
       interaction: {
@@ -17084,7 +17587,8 @@ async function discoverUnits(root, options) {
   const knownClasses = new Set(classes.map((info) => info.qualifiedName));
   const fileBlocks = classes.map((info) => ({
     info,
-    knownClasses
+    knownClasses,
+    file: options.absoluteFile ?? options.filePath
   }));
   const units = [];
   for (const info of classes) {
@@ -17108,14 +17612,15 @@ async function discoverUnits(root, options) {
   }
   return units;
 }
-function reachesConfiguredBase(ancestry, self, pattern) {
+function reachesConfiguredBase(ancestry, self, baseClassNames) {
   return ancestry.some(
-    (entry) => entry.name !== self && pattern.baseClassNames.includes(entry.name)
+    (entry) => entry.name !== self && baseClassNames.includes(entry.name)
   );
 }
 function unitsFor(pattern, pack, info, ownBlocks, fileBlocks, options) {
   const table = {
-    graphqlObjectFields: (p) => graphqlObjectFieldUnits(p, pack, info, ownBlocks, fileBlocks, options)
+    graphqlObjectFields: (p) => graphqlObjectFieldUnits(p, pack, info, ownBlocks, fileBlocks, options),
+    controllerActions: (p) => controllerActionUnits(p, pack, info, ownBlocks, fileBlocks, options)
   };
   return dispatchByType2(table, pattern);
 }
@@ -17130,7 +17635,7 @@ async function graphqlObjectFieldUnits(pattern, pack, info, ownBlocks, fileBlock
     options.storage
   );
   const ancestry = await ancestryOf(info.qualifiedName, ownBlocks, ctx.lookup);
-  if (!reachesConfiguredBase(ancestry, info.qualifiedName, pattern)) {
+  if (!reachesConfiguredBase(ancestry, info.qualifiedName, pattern.baseClassNames)) {
     return [];
   }
   const typeName = graphqlTypeNameFromQualified(
@@ -17149,9 +17654,145 @@ async function graphqlObjectFieldUnits(pattern, pack, info, ownBlocks, fileBlock
       declsByName.set(decl.fieldName, decl);
     }
   }
-  return [...declsByName.values()].map(
-    (decl) => buildFieldUnit(pack, typeName, decl, options.filePath)
-  );
+  return [...declsByName.values()].map((decl) => {
+    const raw = buildFieldUnit(pack, typeName, decl, options.filePath);
+    if (decl.body.reachSeed !== void 0) {
+      options.onReachSeed?.(raw, decl.body.reachSeed);
+    }
+    return raw;
+  });
+}
+async function controllerActionUnits(pattern, pack, info, ownBlocks, fileBlocks, options) {
+  if (info.bodyNode === null || pattern.baseClassNames.includes(info.qualifiedName)) {
+    return [];
+  }
+  const lookup = {
+    root: pattern.root,
+    pathConvention: pattern.pathConvention,
+    ancestryRootClassNames: pattern.ancestryRootClassNames,
+    parsedFile: (absPath) => options.cache.get(absPath),
+    localDefinition: (name) => sameFileBlocks(name, fileBlocks)
+  };
+  const ancestry = await ancestryOf(info.qualifiedName, ownBlocks, lookup);
+  if (!reachesConfiguredBase(ancestry, info.qualifiedName, pattern.baseClassNames)) {
+    return [];
+  }
+  const units = [];
+  for (const block of ownBlocks) {
+    if (block.info.bodyNode === null) {
+      continue;
+    }
+    const visibility = instanceMethodVisibility(block.info.bodyNode);
+    for (const [actionName, method] of instanceMethodsByName(
+      block.info.bodyNode
+    )) {
+      if ((visibility.get(actionName) ?? "public") !== "public") {
+        continue;
+      }
+      const raw = buildControllerActionUnit(
+        pack,
+        pattern,
+        info.qualifiedName,
+        actionName,
+        method,
+        options.filePath,
+        options.storage
+      );
+      units.push(raw);
+      options.onReachSeed?.(raw, {
+        file: block.file,
+        node: method,
+        enclosingQualifiedName: info.qualifiedName
+      });
+    }
+  }
+  return units;
+}
+function buildControllerActionUnit(pack, pattern, controllerQualifiedName, actionName, method, filePath, storage) {
+  const range = rangeOf(method);
+  const route = pattern.routeFor(controllerQualifiedName, actionName);
+  const body = bodyOfMethod(method, storage);
+  return {
+    identity: {
+      name: actionName,
+      nameKind: "binding",
+      kind: "handler",
+      file: filePath,
+      range,
+      span: spanOf(method),
+      exportName: actionName,
+      exportPath: [controllerQualifiedName, actionName]
+    },
+    boundaryBinding: route === null ? null : restBinding({
+      transport: pack.protocol,
+      method: route.method,
+      path: route.path,
+      recognition: pack.name
+    }),
+    parameters: [],
+    branches: [
+      {
+        conditions: [],
+        terminal: {
+          kind: "response",
+          statusCode: { type: "literal", value: pattern.defaultStatusCode },
+          body: null,
+          exceptionType: null,
+          message: null,
+          component: null,
+          renderTree: null,
+          delegateTarget: null,
+          emitEvent: null,
+          location: range
+        },
+        effects: body.effects ?? [],
+        ...body.extraEffects === void 0 ? {} : { extraEffects: body.extraEffects },
+        location: range,
+        isDefault: true
+      }
+    ],
+    bodyContent: body.bodyContent ?? "absent",
+    dependencyCalls: [],
+    declaredContract: null
+  };
+}
+function routingGapUnit(pattern, gaps) {
+  const range = { start: 1, end: 1 };
+  return {
+    identity: {
+      name: "routes",
+      kind: "module-init",
+      file: pattern.routesFile,
+      range,
+      exportName: null,
+      exportPath: null
+    },
+    boundaryBinding: null,
+    parameters: [],
+    branches: [
+      {
+        conditions: [],
+        terminal: {
+          kind: "void",
+          statusCode: null,
+          body: null,
+          exceptionType: null,
+          message: null,
+          component: null,
+          renderTree: null,
+          delegateTarget: null,
+          emitEvent: null,
+          location: range
+        },
+        effects: [],
+        location: range,
+        isDefault: true
+      }
+    ],
+    readings: gaps.map((gap) => unreadableReading(gap, range)),
+    dependencyCalls: [],
+    declaredContract: null
+  };
 }
 function blockConfiguresCall(pattern) {
   const names = /* @__PURE__ */ new Set([
@@ -17192,12 +17833,15 @@ function branchesFor(body, range) {
 }
 function bodyOfMethod(method, storage) {
   const effects = invocationEffects(method);
-  const database = storage === void 0 ? [] : storageEffects(callsUnder(method), storage);
+  const extra = [
+    ...envReadEffects(method),
+    ...storage === void 0 ? [] : storageEffects(callsUnder(method), storage)
+  ];
   return {
     bodyContent: methodHasStatements(method) ? "statements" : "empty",
     readings: [],
     ...effects.length > 0 ? { effects } : {},
-    ...database.length > 0 ? { extraEffects: database } : {}
+    ...extra.length > 0 ? { extraEffects: extra } : {}
   };
 }
 function callsUnder(node, found = []) {
@@ -17221,7 +17865,14 @@ function methodNotSettled(reason, range) {
 }
 function bodyFromLookup(found, range, subject, nothingThere, storage) {
   const table = {
-    found: (lookup) => bodyOfMethod(lookup.method, storage),
+    found: (lookup) => ({
+      ...bodyOfMethod(lookup.method, storage),
+      reachSeed: {
+        file: lookup.block.file,
+        node: lookup.method,
+        enclosingQualifiedName: lookup.block.info.qualifiedName
+      }
+    }),
     unsettled: (lookup) => methodNotSettled(
       `${subject} could be answered by a method ${lookup.reason}, so whether one exists was not settled here`,
       range
@@ -17513,65 +18164,39 @@ function buildFieldUnit(pack, typeName, decl, filePath) {
   };
 }
 
-// src/facts.ts
-function unitKey(filePath, range, name) {
-  return `${filePath}:${range.start}-${range.end}#${name}`;
+// src/facts/values.ts
+function nodeId(filePath, node) {
+  return `${filePath}:${node.startIndex}-${node.endIndex}`;
 }
-function emitEntryFact(db, filePath, range, name) {
-  db.add("entry", [unitKey(filePath, range, name)]);
+function nameId(filePath, name) {
+  return `${filePath}#${name}`;
 }
-
-// src/parser.ts
-import fs2 from "fs";
-import path2 from "path";
-import { fileURLToPath } from "url";
-import { Language, Parser } from "web-tree-sitter";
-var GRAMMAR_PATH = path2.join(
-  path2.dirname(fileURLToPath(import.meta.url)),
-  "..",
-  "grammar",
-  "tree-sitter-ruby.wasm"
-);
-var languagePromise = null;
-function loadLanguage() {
-  languagePromise ??= (async () => {
-    if (!fs2.existsSync(GRAMMAR_PATH)) {
-      throw new Error(
-        `Ruby grammar not found at ${GRAMMAR_PATH}. See grammar/README.md.`
-      );
-    }
-    await Parser.init();
-    return Language.load(GRAMMAR_PATH);
-  })();
-  return languagePromise;
+function paramNameOf(param) {
+  return param.type === "identifier" ? param : field(param, "name") ?? null;
 }
-async function parseRuby(source) {
-  const language = await loadLanguage();
-  const parser = new Parser();
-  parser.setLanguage(language);
-  try {
-    const tree = parser.parse(source);
-    if (tree === null) {
-      throw new Error("tree-sitter produced no tree for this source");
+function declaredParamNames(method) {
+  const params = field(method, "parameters");
+  const declared = /* @__PURE__ */ new Set();
+  for (const param of params === null ? [] : children3(params)) {
+    const name = paramNameOf(param);
+    if (name !== null) {
+      declared.add(name.text);
     }
-    return tree;
-  } finally {
-    parser.delete();
   }
+  return declared;
 }
-
-// src/project.ts
-import fs3 from "fs";
-import path3 from "path";
-import { Database } from "@suss/datalog";
-import { assembleSummary } from "@suss/extractor";
-
-// src/facts/values.ts
-function nodeId(filePath, node) {
-  return `${filePath}:${node.startIndex}-${node.endIndex}`;
-}
-function nameId(filePath, name) {
-  return `${filePath}#${name}`;
+function readKey(filePath, node, enclosing) {
+  if (node.type !== "identifier" && node.type !== "constant") {
+    return nodeId(filePath, node);
+  }
+  const parent = node.parent;
+  if (parent !== null && parent.type === "call" && field(parent, "method")?.id === node.id && field(parent, "receiver") !== null) {
+    return isPropertyRead2(parent) ? nodeId(filePath, parent) : nodeId(filePath, node);
+  }
+  if (enclosing !== null && declaredParamNames(enclosing).has(node.text)) {
+    return `${nodeId(filePath, enclosing)}#${node.text}`;
+  }
+  return nameId(filePath, node.text);
 }
 var WRITTEN_VALUE_TYPES = /* @__PURE__ */ new Set([
   "string",
@@ -17733,6 +18358,9 @@ function emitExpressionFacts(emitter, node) {
     if (WRITTEN_VALUE_TYPES.has(child.type)) {
       add(emitter, "writtenValue", nodeId(emitter.filePath, child));
     }
+    if (child.type === "nil") {
+      add(emitter, "placeholderValue", nodeId(emitter.filePath, child));
+    }
   });
 }
 function implicitReturn(body) {
@@ -17749,7 +18377,7 @@ function emitMethodFacts(emitter, method) {
   const declared = /* @__PURE__ */ new Set();
   let position = 0;
   for (const param of params === null ? [] : children3(params)) {
-    const paramName = param.type === "identifier" ? param : field(param, "name") ?? null;
+    const paramName = paramNameOf(param);
     if (paramName !== null) {
       declared.add(paramName.text);
       const paramKey = `${funcKey}#${paramName.text}`;
@@ -17844,6 +18472,10 @@ function emitClassFacts(emitter, cls) {
       }
       continue;
     }
+    if (NESTING_TYPES.has(statement.type)) {
+      emitClassFacts(emitter, statement);
+      continue;
+    }
     if (!METHOD_TYPES.has(statement.type)) {
       continue;
     }
@@ -17867,7 +18499,7 @@ function emitValueFacts(db, filePath, root) {
   };
   const walk = (node) => {
     for (const child of children3(node)) {
-      if (child.type === "class") {
+      if (NESTING_TYPES.has(child.type)) {
         declaresName(child, emitClassFacts(emitter, child));
         continue;
       }
@@ -17885,7 +18517,6 @@ function emitValueFacts(db, filePath, root) {
 }
 
 // src/facts/constants.ts
-var NESTING_TYPES = /* @__PURE__ */ new Set(["class", "module"]);
 function children4(node) {
   return node.namedChildren.filter((child) => child !== null);
 }
@@ -17963,16 +18594,18 @@ function collectFileConstants(filePath, root) {
     }
   };
   walk(root, null, []);
-  return { definitions, references };
+  return { filePath, definitions, references };
 }
 function emitConstantBindings(db, perFile) {
   const byName = /* @__PURE__ */ new Map();
+  const fileOfDefinition = /* @__PURE__ */ new Map();
   const files = [...perFile];
   for (const file2 of files) {
     for (const definition of file2.definitions) {
       const found = byName.get(definition.qualifiedName) ?? [];
       found.push(definition.key);
       byName.set(definition.qualifiedName, found);
+      fileOfDefinition.set(definition.key, file2.filePath);
     }
   }
   const settles = (candidate) => {
@@ -17989,6 +18622,10 @@ function emitConstantBindings(db, perFile) {
         const key = settles(candidate);
         if (key !== null) {
           db.add("binds", [reference.key, key]);
+          const definedIn = fileOfDefinition.get(key);
+          if (definedIn !== void 0 && definedIn !== file2.filePath) {
+            db.add("rbConstantFrom", [file2.filePath, definedIn]);
+          }
           break;
         }
       }
@@ -17996,10 +18633,682 @@ function emitConstantBindings(db, perFile) {
   }
 }
 
+// src/facts/why.ts
+import fs4 from "fs";
+import path5 from "path";
+import { Database as Database4 } from "@suss/datalog";
+
+// src/parser.ts
+import fs2 from "fs";
+import path2 from "path";
+import { fileURLToPath } from "url";
+import { Language, Parser } from "web-tree-sitter";
+var GRAMMAR_PATH = path2.join(
+  path2.dirname(fileURLToPath(import.meta.url)),
+  "..",
+  "grammar",
+  "tree-sitter-ruby.wasm"
+);
+var languagePromise = null;
+var loadedLanguage = null;
+function loadLanguage() {
+  languagePromise ??= (async () => {
+    if (!fs2.existsSync(GRAMMAR_PATH)) {
+      throw new Error(
+        `Ruby grammar not found at ${GRAMMAR_PATH}. See grammar/README.md.`
+      );
+    }
+    await Parser.init();
+    const language = await Language.load(GRAMMAR_PATH);
+    loadedLanguage = language;
+    return language;
+  })();
+  return languagePromise;
+}
+async function parseRuby(source) {
+  const language = await loadLanguage();
+  return parseWith(language, source);
+}
+async function preloadRubyGrammar() {
+  await loadLanguage();
+}
+function parseRubySync(source) {
+  if (loadedLanguage === null) {
+    throw new Error(
+      "the Ruby grammar has not been loaded yet; call preloadRubyGrammar first"
+    );
+  }
+  return parseWith(loadedLanguage, source);
+}
+function parseWith(language, source) {
+  const parser = new Parser();
+  parser.setLanguage(language);
+  try {
+    const tree = parser.parse(source);
+    if (tree === null) {
+      throw new Error("tree-sitter produced no tree for this source");
+    }
+    return tree;
+  } finally {
+    parser.delete();
+  }
+}
+
+// src/project.ts
+import fs3 from "fs";
+import path4 from "path";
+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 buildRubyExtractionReport(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/facts.ts
+import path3 from "path";
+import { SKIP_CHILDREN as SKIP_CHILDREN3, walkDescendants as walkDescendants3 } from "@suss/extractor";
+function unitKey(filePath, range, name) {
+  return `${filePath}:${range.start}-${range.end}#${name}`;
+}
+function emitEntryFact(db, filePath, range, name) {
+  db.add("entry", [unitKey(filePath, range, name)]);
+}
+function emitRequireFacts(db, filePath, root, known) {
+  walkDescendants3(root, null, {
+    at: (node) => {
+      const target = requiredRelativePath(node);
+      if (target === null) {
+        return;
+      }
+      const resolved = path3.resolve(
+        path3.dirname(filePath),
+        target.endsWith(".rb") ? target : `${target}.rb`
+      );
+      if (known.has(resolved)) {
+        db.add("rbRequires", [filePath, resolved]);
+      }
+    },
+    into: (node) => node.type === "argument_list" ? SKIP_CHILDREN3 : null
+  });
+}
+function requiredRelativePath(node) {
+  if (node.type !== "call" || field(node, "receiver") !== null || field(node, "method")?.text !== "require_relative") {
+    return null;
+  }
+  const { positional } = readCallArgs(field(node, "arguments"));
+  return positional[0] === void 0 ? null : stringLiteralValue(positional[0]);
+}
+
+// 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 } from "@suss/extractor";
+
+// src/reach/resolveCallee.ts
+var DYNAMIC_SEND_NAMES = /* @__PURE__ */ new Set(["send", "public_send", "__send__"]);
+var stop = (reason) => ({
+  kind: "stopped",
+  reason
+});
+function followed(target) {
+  return { kind: "followed", target };
+}
+async function resolveCallee(call, site, ctx) {
+  const methodName = calleeMethodName(call);
+  if (methodName === void 0) {
+    return stop("noDeclaration");
+  }
+  if (DYNAMIC_SEND_NAMES.has(methodName)) {
+    return stop("unsettledValue");
+  }
+  const receiver = field(call, "receiver");
+  if (receiver === null || receiver.type === "self") {
+    return resolveImplicitSelf(methodName, site, ctx);
+  }
+  if (receiver.type === "identifier" && methodName === "call" && site.ownParameters.includes(receiver.text)) {
+    return stop("callerSupplied");
+  }
+  return resolveOnReceiver(receiver, methodName, site, ctx);
+}
+async function resolveMethodReference(name, site, ctx) {
+  const resolved = await resolveImplicitSelf(name, site, ctx);
+  return resolved.kind === "followed" ? resolved.target : null;
+}
+function leavesRoomForATopLevelMethod(reason) {
+  return reason === "noDeclaration" || reason === "outsideRun";
+}
+async function resolveImplicitSelf(methodName, site, ctx) {
+  if (site.enclosingQualifiedName !== null) {
+    const onClass = await methodOnAncestryOf(
+      site.enclosingQualifiedName,
+      methodName,
+      ctx
+    );
+    if (onClass.kind === "followed" || !leavesRoomForATopLevelMethod(onClass.reason)) {
+      return onClass;
+    }
+  }
+  return resolveTopLevelName(methodName, ctx);
+}
+function resolveTopLevelName(methodName, ctx) {
+  const candidates = ctx.topLevelMethods.get(methodName);
+  if (candidates === void 0 || candidates.length === 0) {
+    return stop("noDeclaration");
+  }
+  if (candidates.length > 1) {
+    return stop("multipleSources");
+  }
+  return followed(candidates[0]);
+}
+async function resolveOnReceiver(receiver, methodName, site, ctx) {
+  if (receiver.type === "call") {
+    const innerName = calleeMethodName(receiver);
+    const innerReceiver = field(receiver, "receiver");
+    if (innerName === "new" && innerReceiver !== null) {
+      const classRef = classRefOf(innerReceiver, site, ctx);
+      return classRef === null ? stop("unsettledValue") : methodOnAncestryOf(classRef, methodName, ctx);
+    }
+    const root = rootConstantOf(receiver);
+    if (root === null) {
+      return stop("unsettledValue");
+    }
+    return classRefOf(root, site, ctx) === null ? stop("outsideRun") : stop("unsettledValue");
+  }
+  if (receiver.type === "constant" || receiver.type === "scope_resolution") {
+    const classRef = classRefOf(receiver, site, ctx);
+    return classRef === null ? stop("outsideRun") : singletonMethodOn(classRef, methodName, ctx);
+  }
+  return stop("unsettledValue");
+}
+function rootConstantOf(node) {
+  if (node.type === "constant" || node.type === "scope_resolution") {
+    return node;
+  }
+  if (node.type !== "call") {
+    return null;
+  }
+  const receiver = field(node, "receiver");
+  return receiver === null ? null : rootConstantOf(receiver);
+}
+function classRefOf(node, site, ctx) {
+  if (node.type === "constant") {
+    const shadow = shadowingClassFor(node, site.nesting, ctx.knownClasses);
+    if (shadow !== null) {
+      return shadow;
+    }
+    const qualified = qualifyConstantRef(node, site.nesting);
+    return qualified !== null && ctx.knownClasses.has(qualified) ? qualified : null;
+  }
+  if (node.type === "scope_resolution") {
+    const qualified = qualifyConstantRef(node, site.nesting);
+    return qualified !== null && ctx.knownClasses.has(qualified) ? qualified : null;
+  }
+  return null;
+}
+async function methodOnAncestryOf(qualifiedName, methodName, ctx) {
+  const ownBlocks = ctx.lookup.localDefinition?.(qualifiedName) ?? null;
+  if (ownBlocks === null) {
+    return stop("outsideRun");
+  }
+  const ancestry = await ancestryOf(qualifiedName, ownBlocks, ctx.lookup);
+  const found = methodInAncestry(ancestry, methodName);
+  if (found.type === "found") {
+    return followed(reachedMethod(found.method, found.block, methodName));
+  }
+  if (found.type === "unsettled") {
+    return stop(
+      found.cause === "dynamicDefine" ? "unsettledValue" : "outsideRun"
+    );
+  }
+  return stop("noDeclaration");
+}
+function reachedMethod(node, block, name) {
+  return {
+    file: block.file,
+    node,
+    name,
+    exportPath: [block.info.qualifiedName, name],
+    enclosingQualifiedName: block.info.qualifiedName
+  };
+}
+function singletonMethodOn(qualifiedName, methodName, ctx) {
+  const ownBlocks = ctx.lookup.localDefinition?.(qualifiedName) ?? null;
+  if (ownBlocks === null) {
+    return stop("outsideRun");
+  }
+  for (const block of ownBlocks) {
+    if (block.info.bodyNode === null) {
+      continue;
+    }
+    const found = singletonMethodsByName(block.info.bodyNode).get(methodName);
+    if (found !== void 0) {
+      return followed(reachedMethod(found, block, methodName));
+    }
+  }
+  return 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"))]
+  )
+];
+async function reachedFunctions(seeds, options) {
+  const ctx = buildReachContext(options.files);
+  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: [],
+      enclosingQualifiedName: seed.enclosingQualifiedName
+    });
+    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 = await scanBody(source, ctx, options.displayPathOf);
+      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: "permissive"
+    });
+    summary.confidence = { source: "inferred_static", level: "low" };
+    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);
+  }
+  recordParameterGaps(parameterCallsByKey, summariesByKey, passedPositions);
+  return {
+    summaries,
+    targetsByKey,
+    stopsByKey,
+    argTargetsByKey,
+    parameterCallsByKey,
+    passedPositions
+  };
+}
+function keyOf(target) {
+  return nodeId(target.file, target.node);
+}
+function buildReachContext(files) {
+  const blocksByQualifiedName = /* @__PURE__ */ new Map();
+  const classes = [];
+  for (const { file: file2, root } of files) {
+    walkDefinitions(root, (info) => classes.push({ file: file2, info }));
+  }
+  const knownClasses = new Set(classes.map(({ info }) => info.qualifiedName));
+  for (const { file: file2, info } of classes) {
+    const list = blocksByQualifiedName.get(info.qualifiedName) ?? [];
+    list.push({ info, knownClasses, file: file2 });
+    blocksByQualifiedName.set(info.qualifiedName, list);
+  }
+  const topLevelMethods = /* @__PURE__ */ new Map();
+  for (const { file: file2, root } of files) {
+    for (const method of topLevelMethodNodes(root)) {
+      const name = field(method, "name")?.text;
+      if (name === void 0) {
+        continue;
+      }
+      const list = topLevelMethods.get(name) ?? [];
+      list.push({
+        file: file2,
+        node: method,
+        name,
+        exportPath: [name],
+        enclosingQualifiedName: null
+      });
+      topLevelMethods.set(name, list);
+    }
+  }
+  const lookup = {
+    root: "",
+    pathConvention: "railsUnderscore",
+    ancestryRootClassNames: [],
+    // Every class the run defines is already in `blocksByQualifiedName`
+    // above, so a name that misses there is outside the run and this
+    // never has a file on disk to read.
+    parsedFile: async () => null,
+    localDefinition: (name) => blocksByQualifiedName.get(name) ?? null
+  };
+  return { lookup, knownClasses, topLevelMethods };
+}
+function topLevelMethodNodes(root, found = []) {
+  for (const child of bodyStatements(root)) {
+    if (child.type === "method") {
+      found.push(child);
+      continue;
+    }
+    if (OWN_BODY_TYPES.has(child.type)) {
+      continue;
+    }
+    topLevelMethodNodes(child, found);
+  }
+  return found;
+}
+function nestingOf(qualifiedName) {
+  const parts = qualifiedName.split("::");
+  const out = [];
+  for (let depth = parts.length; depth >= 1; depth--) {
+    out.push(parts.slice(0, depth).join("::"));
+  }
+  return out;
+}
+var EMPTY_SCAN = {
+  followed: [],
+  stops: [],
+  targets: /* @__PURE__ */ new Map(),
+  argTargets: /* @__PURE__ */ new Map(),
+  parameterCalls: [],
+  passedPositions: /* @__PURE__ */ new Set()
+};
+function methodReferenceSymbol(node) {
+  const target = node.type === "block_argument" ? bodyStatements(node)[0] : node;
+  if (target === void 0 || target.type !== "call" || field(target, "receiver") !== null || field(target, "method")?.text !== "method") {
+    return null;
+  }
+  const args = field(target, "arguments");
+  const argChildren = args === null ? [] : bodyStatements(args);
+  return argChildren.length === 1 && argChildren[0]?.type === "simple_symbol" ? argChildren[0] : null;
+}
+async function scanBody(source, ctx, displayPathOf) {
+  const body = field(source.node, "body");
+  if (body === null) {
+    return EMPTY_SCAN;
+  }
+  const calls = withoutChainLinks(bodyCalls(body));
+  const ownParameters = positionalParameters(source.node).map((p) => p.name);
+  const site = {
+    enclosingQualifiedName: source.enclosingQualifiedName,
+    nesting: source.enclosingQualifiedName === null ? [] : nestingOf(source.enclosingQualifiedName),
+    ownParameters
+  };
+  const followed2 = [];
+  const stops = [];
+  const placements = new TargetPlacements();
+  const parameterCalls = [];
+  const passedPositions = /* @__PURE__ */ new Set();
+  const seen = /* @__PURE__ */ new Set();
+  const parameterCallsSeen = /* @__PURE__ */ new Set();
+  const recordPassedArgs = async (call, callee, calleeKey) => {
+    const args = field(call, "arguments");
+    if (args === null) {
+      return;
+    }
+    const argNodes = bodyStatements(args);
+    for (let position = 0; position < argNodes.length; position += 1) {
+      const symbol2 = methodReferenceSymbol(argNodes[position]);
+      if (symbol2 === null) {
+        continue;
+      }
+      const resolved = await resolveMethodReference(
+        symbol2.text.slice(1),
+        site,
+        ctx
+      );
+      if (resolved === null) {
+        continue;
+      }
+      const key = keyOf(resolved);
+      if (!seen.has(key)) {
+        seen.add(key);
+        followed2.push(resolved);
+      }
+      placements.placeArg(callee, position, {
+        file: displayPathOf(resolved.file),
+        span: spanOf(resolved.node)
+      });
+      if (calleeKey !== null) {
+        passedPositions.add(`${calleeKey}#${position}`);
+      }
+    }
+  };
+  for (const call of calls) {
+    const callee = calleeText(call);
+    const outcome = await resolveCallee(call, site, ctx);
+    const placed = outcome.kind === "followed" ? {
+      file: displayPathOf(outcome.target.file),
+      span: spanOf(outcome.target.node)
+    } : outcome.reason === "noDeclaration" ? null : { file: displayPathOf(source.file), span: spanOf(call) };
+    placements.place(callee, placed);
+    await recordPassedArgs(
+      call,
+      callee,
+      outcome.kind === "followed" ? keyOf(outcome.target) : null
+    );
+    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 receiverName = field(call, "receiver")?.text;
+        const parameterIndex = receiverName === void 0 ? -1 : ownParameters.indexOf(receiverName);
+        if (parameterIndex !== -1) {
+          parameterCallsSeen.add(callee);
+          parameterCalls.push({ callee, parameterIndex });
+        }
+      }
+      continue;
+    }
+    const key = keyOf(outcome.target);
+    if (!seen.has(key)) {
+      seen.add(key);
+      followed2.push(outcome.target);
+    }
+  }
+  return {
+    followed: followed2,
+    stops,
+    targets: placements.targets,
+    argTargets: placements.argTargets,
+    parameterCalls,
+    passedPositions
+  };
+}
+function libraryUnit(target, options) {
+  const { file: file2, node, name, exportPath } = target;
+  const body = bodyOfMethod(node, options.storage);
+  const range = rangeOf(node);
+  return {
+    identity: {
+      name,
+      nameKind: "binding",
+      kind: "library",
+      file: options.displayPathOf(file2),
+      range,
+      span: spanOf(node),
+      exportName: exportPath[0] ?? name,
+      exportPath
+    },
+    boundaryBinding: functionCallBinding({
+      transport: "in-process",
+      recognition: "reachable"
+    }),
+    parameters: positionalParameters(node),
+    branches: [
+      {
+        conditions: [],
+        terminal: {
+          kind: "return",
+          statusCode: null,
+          body: null,
+          exceptionType: null,
+          message: null,
+          component: null,
+          renderTree: null,
+          delegateTarget: null,
+          emitEvent: null,
+          location: range
+        },
+        effects: body.effects ?? [],
+        ...body.extraEffects === void 0 ? {} : { extraEffects: body.extraEffects },
+        location: range,
+        isDefault: true
+      }
+    ],
+    bodyContent: body.bodyContent ?? "absent",
+    dependencyCalls: [],
+    declaredContract: null
+  };
+}
+function positionalParameters(node) {
+  const parameters = field(node, "parameters");
+  if (parameters === null) {
+    return [];
+  }
+  const out = [];
+  let position = 0;
+  for (const param of bodyStatements(parameters)) {
+    const name = parameterName(param);
+    if (name === null) {
+      continue;
+    }
+    out.push({ name, position, role: name, typeText: null });
+    position += 1;
+  }
+  return out;
+}
+function parameterName(param) {
+  if (param.type === "identifier") {
+    return param.text;
+  }
+  const named = field(param, "name");
+  return named !== null && named.type === "identifier" ? named.text : null;
+}
+
+// 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
 async function extractRubyProject(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 ? path4.join(options.projectRoot, ".suss", "cache") : null)
+  );
+  const extractionCache = 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",
+    () => extractionCache.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 tallies = createPackTallies(options.packs);
   const constants = [];
   const cache = createFileCache(
     (source) => parseRuby(source).then((tree) => tree.rootNode),
@@ -18007,33 +19316,178 @@ async function extractRubyProject(options) {
   );
   const parsed = [];
   for (const file2 of options.files) {
-    const root = await cache.get(file2);
-    if (root === null) {
-      continue;
-    }
-    parsed.push({ file: file2, root });
-    emitValueFacts(db, file2, root);
-    constants.push(collectFileConstants(file2, root));
+    await timer.timeAsync("parse", async () => {
+      const root = await cache.get(file2);
+      if (root === null) {
+        return;
+      }
+      parsed.push({ file: file2, root });
+      emitValueFacts(db, file2, root);
+      constants.push(collectFileConstants(file2, root));
+    });
   }
-  emitConstantBindings(db, constants);
+  timer.time("discover", () => {
+    emitConstantBindings(db, constants);
+    const known = new Set(parsed.map(({ file: file2 }) => file2));
+    for (const { file: file2, root } of parsed) {
+      emitRequireFacts(db, file2, root, known);
+    }
+  });
   const storagePatterns = options.packs.flatMap((pack) => pack.storage ?? []);
+  const displayPathOf = (file2) => options.workspaceRoot !== void 0 ? path4.relative(options.workspaceRoot, file2) : file2;
+  const seeds = [];
+  const summariesBySeed = /* @__PURE__ */ new Map();
   for (const { file: file2, root } of parsed) {
-    const displayPath = options.workspaceRoot !== void 0 ? path3.relative(options.workspaceRoot, file2) : file2;
-    const rawUnits = await discoverUnits(root, {
-      packs: options.packs,
-      filePath: displayPath,
-      cache,
-      ...storagePatterns.length > 0 ? { storage: { facts: db, patterns: storagePatterns } } : {}
-    });
+    const displayPath = displayPathOf(file2);
+    const seedByRaw = /* @__PURE__ */ new Map();
+    const rawUnits = await timer.timeAsync(
+      "discover",
+      () => discoverUnits(root, {
+        packs: options.packs,
+        filePath: displayPath,
+        absoluteFile: file2,
+        cache,
+        ...storagePatterns.length > 0 ? { storage: { facts: db, patterns: storagePatterns } } : {},
+        onReachSeed: (raw, seed) => seedByRaw.set(raw, seed)
+      })
+    );
     for (const raw of rawUnits) {
-      const summary = assembleSummary(raw, { gapHandling: "permissive" });
+      const summary = timer.time(
+        "summarize",
+        () => assembleSummary2(raw, { gapHandling: "permissive" })
+      );
       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 seed = seedByRaw.get(raw);
+      if (seed === void 0) {
+        continue;
+      }
+      const key = nodeId(seed.file, seed.node);
+      const sharing = summariesBySeed.get(key);
+      if (sharing === void 0) {
+        seeds.push({
+          key,
+          file: seed.file,
+          node: seed.node,
+          enclosingQualifiedName: seed.enclosingQualifiedName
+        });
+        summariesBySeed.set(key, [summary]);
+      } else {
+        sharing.push(summary);
+      }
+    }
+    const loadTimeReads = timer.time("discover", () => envReadEffects(root));
+    if (loadTimeReads.length > 0) {
+      const summary = timer.time(
+        "summarize",
+        () => assembleSummary2(
+          moduleInitStructure({
+            name: path4.basename(displayPath),
+            file: displayPath,
+            range: rangeOf(root),
+            effects: loadTimeReads
+          }),
+          { gapHandling: "permissive" }
+        )
+      );
+      summary.confidence = { source: "inferred_static", level: "low" };
+      summaries.push(summary);
+    }
+  }
+  for (const pack of options.packs) {
+    for (const pattern of pack.discovery) {
+      if (pattern.type !== "controllerActions") {
+        continue;
+      }
+      const gaps = pattern.routingGaps?.() ?? [];
+      if (gaps.length === 0) {
+        continue;
+      }
+      const summary = timer.time(
+        "summarize",
+        () => assembleSummary2(routingGapUnit(pattern, gaps), {
+          gapHandling: "permissive"
+        })
+      );
+      summary.confidence = { source: "inferred_static", level: "low" };
+      summaries.push(summary);
     }
   }
+  const reached = await timer.timeAsync(
+    "summarize",
+    () => reachedFunctions(seeds, {
+      files: parsed,
+      displayPathOf,
+      ...storagePatterns.length > 0 ? { storage: { facts: db, patterns: storagePatterns } } : {}
+    })
+  );
+  for (const [key, owners] of summariesBySeed) {
+    for (const summary of owners) {
+      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));
+    }
+  }
+  recordParameterGaps2(
+    reached.parameterCallsByKey,
+    summariesBySeed,
+    reached.passedPositions
+  );
+  summaries.push(...reached.summaries);
+  const dependencies = fileDependenciesOf(db, displayPathOf);
+  stampModuleImports(summaries, (file2) => dependencies.get(file2) ?? []);
+  const idRoot = options.projectRoot ?? options.workspaceRoot;
+  for (const summary of summaries) {
+    const absoluteFile = options.workspaceRoot === void 0 ? summary.location.file : path4.resolve(options.workspaceRoot, summary.location.file);
+    summary.identity.id = summaryIdFromParts({
+      workspace: void 0,
+      file: idRoot === void 0 ? absoluteFile : path4.relative(idRoot, absoluteFile),
+      name: summary.identity.name,
+      exportPath: summary.identity.exportPath
+    });
+  }
+  disambiguateSummaryIds(summaries);
+  linkCallsToSummaries(summaries);
+  await timer.timeAsync("cache.write", async () => {
+    if (cacheDir === null || summaries.length === 0) {
+      return;
+    }
+    try {
+      await extractionCache.write(cacheInput, summaries);
+    } catch {
+    }
+  });
+  options.onExtractionReport?.(
+    buildRubyExtractionReport({
+      packs: options.packs,
+      tallies,
+      filesWalked: options.files.length,
+      summaries
+    })
+  );
+  options.onTiming?.(timer.report());
   return { summaries, facts: db };
 }
+function fileDependenciesOf(db, displayPathOf) {
+  const byFile = /* @__PURE__ */ new Map();
+  for (const relation of ["rbRequires", "rbConstantFrom"]) {
+    for (const [from, to] of db.facts(relation)) {
+      if (typeof from !== "string" || typeof to !== "string") {
+        continue;
+      }
+      const key = displayPathOf(from);
+      const seen = byFile.get(key) ?? [];
+      seen.push(displayPathOf(to));
+      byFile.set(key, seen);
+    }
+  }
+  return byFile;
+}
 var SKIPPED_DIRECTORIES = /* @__PURE__ */ new Set(["vendor", "node_modules", "tmp", ".git"]);
 function findRubyFiles(root) {
   const found = [];
@@ -18041,32 +19495,306 @@ function findRubyFiles(root) {
     for (const entry of fs3.readdirSync(dir, { withFileTypes: true })) {
       if (entry.isDirectory()) {
         if (!SKIPPED_DIRECTORIES.has(entry.name)) {
-          walk(path3.join(dir, entry.name));
+          walk(path4.join(dir, entry.name));
         }
         continue;
       }
       if (entry.isFile() && entry.name.endsWith(".rb")) {
-        found.push(path3.join(dir, entry.name));
+        found.push(path4.join(dir, entry.name));
       }
     }
   };
   walk(root);
   return found.sort();
 }
+
+// src/facts/resolve.ts
+import {
+  constant as constant2,
+  deriveOnDemand as deriveOnDemand2,
+  evaluate as evaluate4,
+  lit as lit3,
+  rule as rule3,
+  variable as v3
+} from "@suss/datalog";
+var RUBY_RULES = [
+  // `Loader.new` makes one of the class, which the shared rules already say
+  // about calling a class. Ruby writes it as a method read off the constant
+  // instead, so the read is what steps to the class here.
+  rule3(
+    "stepsTo",
+    [v3("x"), v3("cls"), VALUE_STEP],
+    [
+      lit3("readsProperty", v3("x"), v3("o"), constant2("new")),
+      lit3("comesTo", v3("o"), v3("cls")),
+      lit3("objectValue", v3("cls"))
+    ]
+  )
+];
+var RESOLUTION_PROGRAM = deriveOnDemand2(
+  [...RESOLUTION_RULES, ...RUBY_RULES, ...RESOLUTION_QUESTIONS],
+  ANSWER_RELATIONS
+);
+
+// src/facts/why.ts
+var WITNESS_RULES = [...RESOLUTION_RULES, ...RUBY_RULES];
+var METHOD_TYPES2 = /* @__PURE__ */ new Set(["method", "singleton_method"]);
+function namedChildrenOf(node) {
+  return node.namedChildren.filter((child) => child !== null);
+}
+function enclosingMethod(node) {
+  let current = node.parent;
+  while (current !== null) {
+    if (METHOD_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 (node.type === "constant") {
+      locations.set(`${file2}#${node.text}`, { file: file2, node });
+    }
+    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" || node.type === "constant") {
+    return node.text;
+  }
+  if (node.type === "method" || node.type === "singleton_method") {
+    return field(node, "name")?.text ?? node.text;
+  }
+  if (node.type === "class" || node.type === "module") {
+    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 RubyWhySession = class {
+  root;
+  db = new Database4();
+  locations = /* @__PURE__ */ new Map();
+  trees = /* @__PURE__ */ new Map();
+  constructor(options) {
+    this.root = path5.resolve(options.dir);
+    const constants = [];
+    for (const file2 of findRubyFiles(this.root)) {
+      const source = fs4.readFileSync(file2, "utf8");
+      const root = parseRubySync(source).rootNode;
+      this.trees.set(file2, root);
+      emitValueFacts(this.db, file2, root);
+      constants.push(collectFileConstants(file2, root));
+      indexFile(file2, root, this.locations);
+    }
+    emitConstantBindings(this.db, constants);
+  }
+  /**
+   * 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, "method");
+        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: WITNESS_RULES,
+      key: readKey(value.file, value.node, enclosingMethod(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 path5.isAbsolute(file2) ? file2 : path5.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 path5.relative(this.root, key);
+    }
+    return key;
+  }
+};
+
+// src/stubEvidence.ts
+import fs5 from "fs";
+import path6 from "path";
+import { SKIP_CHILDREN as SKIP_CHILDREN4, walkDescendants as walkDescendants4 } from "@suss/extractor";
+function bareLetters(name) {
+  return name.replaceAll(/[-_]/g, "").toLowerCase();
+}
+function isSpelledFrom(qualifiedName, packageName) {
+  const wanted = bareLetters(packageName);
+  const constants = qualifiedName.split("::");
+  return constants.some(
+    (_, end) => bareLetters(constants.slice(0, end + 1).join("")) === wanted
+  );
+}
+function isPackageRequire(target, packageName) {
+  const bundlerName = packageName.replaceAll("-", "_");
+  return target === bundlerName || target.startsWith(`${bundlerName}/`) || target === packageName || target.startsWith(`${packageName}/`);
+}
+function requireTarget(node) {
+  if (node.type !== "call" || field(node, "receiver") !== null || field(node, "method")?.text !== "require" && field(node, "method")?.text !== "require_relative") {
+    return null;
+  }
+  const { positional } = readCallArgs(field(node, "arguments"));
+  return positional[0] === void 0 ? null : stringLiteralValue(positional[0]);
+}
+function requireSitesIn(root, file2) {
+  const found = [];
+  walkDescendants4(root, null, {
+    at: (node) => {
+      const target = requireTarget(node);
+      if (target !== null) {
+        found.push({ target, file: file2, line: rangeOf(node).start });
+      }
+    },
+    into: (node) => node.type === "argument_list" ? SKIP_CHILDREN4 : null
+  });
+  return found;
+}
+function extendsSitesIn(root, file2, packageName) {
+  const found = [];
+  walkClasses(root, (info) => {
+    if (info.superclassQualifiedName !== null && isSpelledFrom(info.superclassQualifiedName, packageName)) {
+      found.push({
+        className: info.qualifiedName,
+        superclassName: info.superclassQualifiedName,
+        file: file2,
+        line: rangeOf(info.node).start
+      });
+    }
+  });
+  return found;
+}
+async function rubyStubEvidence(options) {
+  const requires = [];
+  const extendsSites = [];
+  for (const file2 of findRubyFiles(options.directory)) {
+    const source = fs5.readFileSync(file2, "utf8");
+    const tree = await parseRuby(source);
+    const displayPath = path6.relative(options.directory, file2);
+    for (const site of requireSitesIn(tree.rootNode, displayPath)) {
+      if (isPackageRequire(site.target, options.packageName)) {
+        requires.push(site);
+      }
+    }
+    extendsSites.push(
+      ...extendsSitesIn(tree.rootNode, displayPath, options.packageName)
+    );
+  }
+  return { requires, extendsSites };
+}
 export {
+  ADAPTER_VERSION,
+  RubyWhySession,
   ancestryOf,
+  bodyStatements,
+  booleanLiteralValue,
+  collectFileConstants,
   createFileCache,
   discoverUnits,
+  emitConstantBindings,
   emitEntryFact,
+  emitValueFacts,
   extractRubyProject,
+  field,
   findRubyFiles,
   graphqlTypeNameFromQualified,
+  hashKeySymbolName,
   inheritedStatements,
   methodInAncestry,
+  nodeId,
   parseRuby,
+  parseRubySync,
+  preloadRubyGrammar,
   qualifyConstantRef,
   reachDefinition,
+  readCallArgs,
+  readKey,
   resolveConstantFile,
+  rubyStubEvidence,
+  runStatements,
+  stringLiteralValue,
+  symbolValue,
   typeShapeFromNode,
   underscoreConstantPath,
   unitKey,