@suss/extractor 0.34.0 → 0.34.1

package/dist/index.cjs

@@ -35,6 +35,7 @@ __export(index_exports, {
   IdSet: () => IdSet,
   KeptParses: () => KeptParses,
   MAX_ENTRIES: () => MAX_ENTRIES,
+  MAX_HELPER_PATHS: () => MAX_HELPER_PATHS,
   MAX_PATHS: () => MAX_PATHS,
   MODULE_SURFACE_RECOGNITION: () => MODULE_SURFACE_RECOGNITION,
   PathBudgetExceeded: () => PathBudgetExceeded,
@@ -65,12 +66,15 @@ __export(index_exports, {
   firstWrittenReading: () => firstWrittenReading,
   formatPackHealth: () => formatPackHealth,
   guardsHoldOn: () => guardsHoldOn,
+  helperPathsOnVariables: () => helperPathsOnVariables,
   httpRouteDiscovery: () => httpRouteDiscovery,
   isListedTestFile: () => isListedTestFile,
+  makeIgnoredDirectory: () => makeIgnoredDirectory,
   makeTransitionId: () => makeTransitionId,
   mapReading: () => mapReading,
   markReturnsAsExitCode: () => markReturnsAsExitCode,
   matchesTestFileName: () => matchesTestFileName,
+  mergeReadShapes: () => mergeReadShapes,
   moduleInitStructure: () => moduleInitStructure,
   moduleOfFile: () => moduleOfFile,
   noopTimer: () => noopTimer,
@@ -79,6 +83,7 @@ __export(index_exports, {
   projectFileStamp: () => projectFileStamp,
   rawConditionToPredicate: () => rawConditionToPredicate,
   recordPackFailure: () => recordPackFailure,
+  redirectDeliveryWhenSet: () => redirectDeliveryWhenSet,
   registrationHelperDiscovery: () => registrationHelperDiscovery,
   routeHelperIndex: () => routeHelperIndex,
   runDigest: () => runDigest,
@@ -87,6 +92,7 @@ __export(index_exports, {
   settleModules: () => settleModules,
   sharedGatingConditions: () => sharedGatingConditions,
   sourceRefsOf: () => sourceRefsOf,
+  splitAtHandOffs: () => splitAtHandOffs,
   stampMayMissAWrite: () => stampMayMissAWrite,
   stampModuleImports: () => stampModuleImports,
   stampModules: () => stampModules,
@@ -94,6 +100,7 @@ __export(index_exports, {
   summaryCountsByPack: () => summaryCountsByPack,
   tallyUnit: () => tallyUnit,
   terminalToOutput: () => terminalToOutput,
+  throughHelper: () => throughHelper,
   unreadableReading: () => unreadableReading,
   unwrapJsonStringify: () => unwrapJsonStringify,
   valueToReadFurtherFrom: () => valueToReadFurtherFrom,
@@ -103,7 +110,7 @@ __export(index_exports, {
 });
 module.exports = __toCommonJS(index_exports);
 var import_node_crypto4 = require("crypto");
-var import_behavioral_ir6 = require("@suss/behavioral-ir");
+var import_behavioral_ir7 = require("@suss/behavioral-ir");
 
 // src/contractStatusGaps.ts
 var import_behavioral_ir = require("@suss/behavioral-ir");
@@ -282,29 +289,82 @@ function composeOne(summary, chain, keepGaps) {
   if (wrappers.length === 0) {
     return narrowed;
   }
-  const responses = respondedInstead(wrappers);
-  const handled = handledThrows(wrappers);
-  const transitions = beside(summary, responses, handled);
+  const responses = settledUncaught(respondedInstead(wrappers), wrappers);
+  const unitOwn = settledUncaught(summary.transitions, wrappers);
+  const own = [...responses, ...unitOwn];
+  const handled = handledThrows(wrappers, thrownBy(own));
+  const transitions = beside(summary, unitOwn, responses, handled);
   if (!keepGaps) {
     return transitions === summary.transitions ? narrowed : { ...narrowed, transitions };
   }
   const gaps = withContractStatusGaps(
     summary,
-    [...responses, ...summary.transitions],
-    handled
+    own,
+    everyHandlerOutcome(wrappers)
   );
   if (transitions === summary.transitions && gaps === summary.gaps) {
     return narrowed;
   }
   return { ...narrowed, transitions, gaps };
 }
-function beside(summary, responses, handled) {
-  const throws = summary.transitions.some((t) => t.output.type === "throw");
-  const onThrow = throws ? handled : [];
-  if (responses.length === 0 && onThrow.length === 0) {
+function beside(summary, unitOwn, responses, handled) {
+  if (responses.length === 0 && handled.length === 0 && unitOwn === summary.transitions) {
     return summary.transitions;
   }
-  return withDistinctIds([...responses, ...summary.transitions, ...onThrow]);
+  return withDistinctIds([...responses, ...unitOwn, ...handled]);
+}
+function settledUncaught(transitions, wrappers) {
+  const handlers = wrappers.filter(
+    (wrapper) => wrapper.reference.onThrow === true
+  );
+  let changed = false;
+  const settled = transitions.flatMap((transition) => {
+    const { output } = transition;
+    if (output.type !== "throw") {
+      return [transition];
+    }
+    const caught = caughtOnRoute(handlers, output);
+    if (caught === "sure") {
+      changed = true;
+      return [markedCaught(transition)];
+    }
+    if (output.statusWhenUncaught === void 0) {
+      return [transition];
+    }
+    changed = true;
+    const response = {
+      ...transition,
+      output: {
+        type: "response",
+        statusCode: { type: "literal", value: output.statusWhenUncaught },
+        body: null,
+        headers: {}
+      }
+    };
+    return caught === "uncertain" ? [transition, response] : [response];
+  });
+  return changed ? settled : transitions;
+}
+function markedCaught(transition) {
+  return {
+    ...transition,
+    metadata: (0, import_behavioral_ir2.withWrapperMetadata)(transition.metadata, {
+      ...(0, import_behavioral_ir2.readWrapperMetadata)(transition),
+      caught: true
+    })
+  };
+}
+function caughtOnRoute(handlers, thrown) {
+  if (handlers.some((handler) => handler.reference.catches === void 0)) {
+    return "sure";
+  }
+  const matches = handlers.map(
+    (handler) => catchMatch(handler.reference, thrown)
+  );
+  if (matches.includes("yes")) {
+    return "sure";
+  }
+  return matches.includes("maybe") ? "uncertain" : "no";
 }
 function respondedInstead(wrappers) {
   return wrappers.flatMap(
@@ -316,11 +376,91 @@ function respondedInstead(wrappers) {
     )
   );
 }
-function handledThrows(wrappers) {
+function thrownBy(transitions) {
+  return transitions.flatMap(
+    (t) => t.output.type === "throw" ? [t.output] : []
+  );
+}
+function everyHandlerOutcome(wrappers) {
   return wrappers.flatMap(
     (wrapper) => wrapper.reference.onThrow === true ? attribute(wrapper.summary.transitions, wrapper.reference) : []
   );
 }
+function handledThrows(wrappers, thrown) {
+  const caught = catchesAny(wrappers, thrown);
+  return [...oncePerHandler(wrappers, caught)].flatMap(
+    ([wrapper, how]) => attribute(
+      wrapper.summary.transitions,
+      wrapper.reference,
+      how === "uncertain"
+    )
+  );
+}
+function oncePerHandler(wrappers, caught) {
+  const byHandler = /* @__PURE__ */ new Map();
+  for (const wrapper of wrappers) {
+    const how = caught.get(wrapper);
+    if (how === void 0) {
+      continue;
+    }
+    const earlier = byHandler.get(wrapper.summary);
+    if (earlier === void 0 || earlier[1] === "uncertain" && how === "sure") {
+      byHandler.set(wrapper.summary, [wrapper, how]);
+    }
+  }
+  return new Map(byHandler.values());
+}
+function catchesAny(wrappers, thrown) {
+  const caught = /* @__PURE__ */ new Map();
+  if (thrown.length === 0) {
+    return caught;
+  }
+  const handlers = wrappers.filter(
+    (wrapper) => wrapper.reference.onThrow === true
+  );
+  for (const handler of handlers) {
+    if (handler.reference.catches === void 0) {
+      caught.set(handler, "sure");
+    }
+  }
+  const listing = handlers.filter(
+    (handler) => handler.reference.catches !== void 0
+  );
+  for (const one of thrown) {
+    for (const [handler, how] of catchersOf(listing, one)) {
+      if (caught.get(handler) !== "sure") {
+        caught.set(handler, how);
+      }
+    }
+  }
+  return caught;
+}
+function catchersOf(handlers, thrown) {
+  const found = [];
+  for (const handler of handlers) {
+    const match = catchMatch(handler.reference, thrown);
+    if (match === "yes") {
+      found.push([handler, found.length === 0 ? "sure" : "uncertain"]);
+      return found;
+    }
+    if (match === "maybe") {
+      found.push([handler, "uncertain"]);
+    }
+  }
+  return found;
+}
+function catchMatch(reference, thrown) {
+  const ancestors = thrown.exceptionAncestors;
+  if (thrown.exceptionType === null || ancestors === void 0) {
+    return "maybe";
+  }
+  const classes = /* @__PURE__ */ new Set([thrown.exceptionType, ...ancestors]);
+  if ((reference.catches ?? []).some((name) => classes.has(name))) {
+    return "yes";
+  }
+  const unread = thrown.ancestryIncomplete === true && reference.mayCatchUnreadClasses === true;
+  return unread || reference.mayCatchAny === true ? "maybe" : "no";
+}
 function withContractStatusGaps(summary, composed, handled) {
   const contract = (0, import_behavioral_ir2.readHttpMetadata)(summary)?.declaredContract;
   const binding = summary.identity.boundaryBinding;
@@ -351,10 +491,13 @@ function coversUnit(reference, summary) {
   const binding = summary.identity.boundaryBinding;
   return binding !== null && (0, import_behavioral_ir2.withinScope)(binding, reference.scope);
 }
-function attribute(transitions, reference) {
+function attribute(transitions, reference, catchUncertain = false) {
   return transitions.map((transition) => ({
     ...transition,
-    metadata: (0, import_behavioral_ir2.withWrapperMetadata)(transition.metadata, { from: reference })
+    metadata: (0, import_behavioral_ir2.withWrapperMetadata)(transition.metadata, {
+      from: reference,
+      ...catchUncertain ? { catchUncertain } : {}
+    })
   }));
 }
 function withDistinctIds(transitions) {
@@ -467,6 +610,104 @@ function markExitCodeFrom(summary, marked) {
   summary.metadata = left;
 }
 
+// src/helperHandOff.ts
+var import_behavioral_ir4 = require("@suss/behavioral-ir");
+var MAX_HELPER_PATHS = 16;
+function throughHelper(branch, at, helperBranches) {
+  return helperBranches.map((helper) => {
+    const conditions = [...branch.conditions, ...helper.conditions];
+    const expectedInput = mergeReadShapes(
+      branch.expectedInput ?? null,
+      helper.expectedInput ?? null
+    );
+    const reads = expectedInput === null ? {} : { expectedInput };
+    if (helper.terminal.kind !== "throw" && helper.terminal.kind !== "exit") {
+      return {
+        ...branch,
+        ...reads,
+        conditions,
+        isDefault: branch.isDefault && helper.isDefault
+      };
+    }
+    return {
+      ...branch,
+      ...reads,
+      conditions,
+      terminal: { ...helper.terminal, location: at },
+      location: at,
+      isDefault: false
+    };
+  });
+}
+function mergeReadShapes(a, b) {
+  if (a === null || b === null) {
+    return a ?? b;
+  }
+  if (a.type !== "record" || b.type !== "record") {
+    return a.type === "record" ? a : b;
+  }
+  const properties = { ...a.properties };
+  for (const [name, shape] of Object.entries(b.properties)) {
+    const known = properties[name];
+    properties[name] = known === void 0 ? shape : mergeReadShapes(known, shape) ?? shape;
+  }
+  return { ...a, properties };
+}
+function splitAtHandOffs(branch, sites, from = 0) {
+  for (let index = from; index < sites.length; index++) {
+    const site = sites[index];
+    const reached = site.alwaysRuns === true || runsBefore(site.line, branch.terminal.location.end);
+    if (!reached || !guardsHoldOn(site.preconditions, branch.conditions)) {
+      continue;
+    }
+    return throughHelper(branch, site.at, site.helper).flatMap(
+      (path7) => path7.terminal === branch.terminal ? splitAtHandOffs(path7, sites, index + 1) : [path7]
+    );
+  }
+  return [branch];
+}
+function helperPathsOnVariables(helperBranches, passed) {
+  const renamed = helperBranches.map((branch) => ({
+    ...branch,
+    conditions: branch.conditions.map((condition) => ({
+      ...condition,
+      structured: condition.structured === null ? null : onCallerVariables(condition.structured, passed)
+    }))
+  }));
+  const variables = new Set(passed.values());
+  const testsWhatItGot = renamed.some(
+    (branch) => branch.conditions.some(
+      (condition) => condition.structured !== null && (0, import_behavioral_ir4.predicateRefs)(condition.structured).some(
+        (ref) => variables.has(rootName(ref) ?? "")
+      )
+    )
+  );
+  return testsWhatItGot && renamed.length <= MAX_HELPER_PATHS ? renamed : null;
+}
+function onCallerVariables(predicate, passed) {
+  const rename = (ref) => {
+    if (ref.type === "derived") {
+      return { ...ref, from: rename(ref.from) };
+    }
+    if (ref.type === "input") {
+      const name = passed.get(ref.inputRef);
+      return name === void 0 ? ref : { type: "dependency", name, accessChain: ref.path };
+    }
+    if (ref.type === "dependency") {
+      const name = passed.get(ref.name);
+      return name === void 0 ? ref : { ...ref, name };
+    }
+    return ref;
+  };
+  return (0, import_behavioral_ir4.replacePredicateRefs)(predicate, rename);
+}
+function rootName(ref) {
+  if (ref.type === "derived") {
+    return rootName(ref.from);
+  }
+  return ref.type === "dependency" ? ref.name : null;
+}
+
 // src/moduleImports.ts
 function stampModuleImports(summaries, importsOf) {
   const byFile = /* @__PURE__ */ new Map();
@@ -720,7 +961,7 @@ var configuredCallOption = import_zod.z.object({
 }).strict();
 
 // src/paths/enumeratePaths.ts
-var import_behavioral_ir4 = require("@suss/behavioral-ir");
+var import_behavioral_ir5 = require("@suss/behavioral-ir");
 var MAX_PATHS = 256;
 var UnmodeledFlow = class extends Error {
 };
@@ -764,12 +1005,12 @@ var loopCompletedCond = (headerText, exit) => fixedCond(
   exit === "throw" ? "earlyThrow" : "earlyReturn"
 );
 var catchEntryCond = () => fixedCond(
-  { sourceText: import_behavioral_ir4.CATCH_ENTRY_TEXT, expression: null },
+  { sourceText: import_behavioral_ir5.CATCH_ENTRY_TEXT, expression: null },
   "positive",
   "catchBlock"
 );
-function classify(path6, home, isAncestorOrSelf) {
-  return path6.map((cond) => {
+function classify(path7, home, isAncestorOrSelf) {
+  return path7.map((cond) => {
     if (cond.branchStmt === null) {
       return cond.info;
     }
@@ -834,9 +1075,16 @@ function chargeBudget(state) {
     );
   }
 }
-function recordTerminal(ctx, terminal, home, path6) {
+function limitOpenPaths(paths) {
+  if (paths.length > MAX_PATHS) {
+    throw new PathBudgetExceeded(
+      `path budget exceeded, more than ${MAX_PATHS} paths`
+    );
+  }
+}
+function recordTerminal(ctx, terminal, home, path7) {
   chargeBudget(ctx.state);
-  const info = classify(path6, home, ctx.isAncestorOrSelf);
+  const info = classify(path7, home, ctx.isAncestorOrSelf);
   const existing = ctx.state.byTerminal.get(terminal) ?? [];
   existing.push(info);
   ctx.state.byTerminal.set(terminal, existing);
@@ -847,15 +1095,15 @@ function containsTerminal(ctx, stmt) {
   }
   return childrenOf(stmt).some((child) => containsTerminal(ctx, child));
 }
-function stepIf(stmt, path6, ctx) {
+function stepIf(stmt, path7, ctx) {
   const thenExit = exitKindOfList(stmt.thenBody);
   const elseExit = stmt.elseBody === null ? null : exitKindOfList(stmt.elseBody);
   const thenPath = [
-    ...path6,
+    ...path7,
     branchCond(stmt, stmt.condition, "positive", elseExit)
   ];
   const elsePath = [
-    ...path6,
+    ...path7,
     branchCond(
       stmt,
       stmt.condition,
@@ -872,7 +1120,7 @@ function stepIf(stmt, path6, ctx) {
   }
   return out;
 }
-function stepSwitch(stmt, path6, ctx) {
+function stepSwitch(stmt, path7, ctx) {
   const out = [];
   const negations = [];
   let defaultRanBody = false;
@@ -882,7 +1130,7 @@ function stepSwitch(stmt, path6, ctx) {
     if (hasStrayBreak(group.body)) {
       throw new UnmodeledFlow("non-trailing break in switch clause");
     }
-    const groupPath = group.condition === null ? [...path6, ...negations] : [...path6, fixedCond(group.condition, "positive", "explicit")];
+    const groupPath = group.condition === null ? [...path7, ...negations] : [...path7, fixedCond(group.condition, "positive", "explicit")];
     const conts = enumerate(ctx, group.body, groupPath);
     if (conts.length > 0) {
       if (!group.hasTrailingBreak && !fallthroughSafe) {
@@ -899,24 +1147,24 @@ function stepSwitch(stmt, path6, ctx) {
     }
   }
   if (!defaultRanBody) {
-    out.push([...path6, ...negations]);
+    out.push([...path7, ...negations]);
   }
   return out;
 }
-function stepLoop(stmt, path6, ctx) {
+function stepLoop(stmt, path7, ctx) {
   const bodyExit = exitKindOfList(stmt.body);
   if (containsTerminal(ctx, stmt)) {
     enumerate(ctx, stmt.body, [
-      ...path6,
+      ...path7,
       loopIterationCond(stmt.condition.sourceText)
     ]);
   }
   if (bodyExit !== null) {
-    return [[...path6, loopCompletedCond(stmt.condition.sourceText, bodyExit)]];
+    return [[...path7, loopCompletedCond(stmt.condition.sourceText, bodyExit)]];
   }
-  return [path6];
+  return [path7];
 }
-function stepTry(stmt, path6, ctx) {
+function stepTry(stmt, path7, ctx) {
   if (stmt.finallyBody !== null) {
     const finallyHasTerminal = stmt.finallyBody.some(
       (s) => containsTerminal(ctx, s)
@@ -926,22 +1174,22 @@ function stepTry(stmt, path6, ctx) {
     }
   }
   const out = [];
-  out.push(...enumerate(ctx, stmt.tryBody, path6));
+  out.push(...enumerate(ctx, stmt.tryBody, path7));
   if (stmt.catchBody !== null) {
-    const catchPath = [...path6, catchEntryCond()];
+    const catchPath = [...path7, catchEntryCond()];
     out.push(...enumerate(ctx, stmt.catchBody, catchPath));
   }
   return out;
 }
-function stepExit(stmt, path6, ctx) {
+function stepExit(stmt, path7, ctx) {
   const collector = ctx.state.callbackExits[ctx.state.callbackExits.length - 1];
   if (collector !== void 0 && (stmt.exit === "return" || stmt.exit === "throw")) {
-    collector.push(path6);
+    collector.push(path7);
   }
   return [];
 }
-function stepOpaque(_stmt, path6, _ctx) {
-  return [path6];
+function stepOpaque(_stmt, path7, _ctx) {
+  return [path7];
 }
 var stepHandlers = {
   if: stepIf,
@@ -951,22 +1199,23 @@ var stepHandlers = {
   exit: stepExit,
   opaque: stepOpaque
 };
-function stepCallback(ctx, body, path6) {
+function stepCallback(ctx, body, path7) {
   const exits = [];
   ctx.state.callbackExits.push(exits);
   let fellThrough;
   try {
-    fellThrough = enumerate(ctx, body, path6);
+    fellThrough = enumerate(ctx, body, path7);
   } finally {
     ctx.state.callbackExits.pop();
   }
   const out = [...fellThrough, ...exits];
-  return out.length === 0 ? [path6] : out;
+  return out.length === 0 ? [path7] : out;
 }
-function stepStatement(ctx, stmt, path6) {
-  let paths = [path6];
+function stepStatement(ctx, stmt, path7) {
+  let paths = [path7];
   for (const body of stmt.callbacks ?? []) {
     paths = paths.flatMap((each) => stepCallback(ctx, body, each));
+    limitOpenPaths(paths);
   }
   const ownTerminals = ctx.terminalsByStmt.get(stmt) ?? [];
   for (const each of withRejoined(paths)) {
@@ -983,7 +1232,7 @@ function stepStatement(ctx, stmt, path6) {
     )
   );
 }
-function soleDisagreement(left, right) {
+function soleDisagreement(left, right, keepsArms) {
   if (left.length !== right.length) {
     return null;
   }
@@ -1002,9 +1251,10 @@ function soleDisagreement(left, right) {
     }
     found = at;
   }
-  return found;
+  const test = found === null ? null : left[found]?.info.expression ?? null;
+  return test !== null && keepsArms(test) ? null : found;
 }
-function mergeRejoined(paths) {
+function mergeRejoined(paths, keepsArms = KEEPS_NO_ARMS) {
   let current = paths;
   for (let round = 0; round < current.length; round++) {
     const out = [];
@@ -1019,7 +1269,11 @@ function mergeRejoined(paths) {
         if (taken.has(j)) {
           continue;
         }
-        const at = soleDisagreement(combined, current[j]);
+        const at = soleDisagreement(
+          combined,
+          current[j],
+          keepsArms
+        );
         if (at === null) {
           continue;
         }
@@ -1045,21 +1299,18 @@ function enumerate(ctx, stmts, prefix) {
   let frontiers = [[...prefix]];
   for (const stmt of stmts) {
     const nextFrontiers = [];
-    for (const path6 of mergeRejoined(frontiers)) {
-      nextFrontiers.push(...stepStatement(ctx, stmt, path6));
+    for (const path7 of mergeRejoined(frontiers, ctx.keepsArms)) {
+      nextFrontiers.push(...stepStatement(ctx, stmt, path7));
     }
     frontiers = nextFrontiers;
-    if (frontiers.length > MAX_PATHS) {
-      throw new PathBudgetExceeded(
-        `path budget exceeded, more than ${MAX_PATHS} paths`
-      );
-    }
+    limitOpenPaths(frontiers);
     if (frontiers.length === 0) {
       break;
     }
   }
   return frontiers;
 }
+var KEEPS_NO_ARMS = () => false;
 function buildParentMap(statements) {
   const parentOf = /* @__PURE__ */ new Map();
   const visit = (stmt, parent) => {
@@ -1093,13 +1344,14 @@ function enumerateStructuredPaths(input) {
   };
   const ctx = {
     terminalsByStmt: input.terminalsByStmt,
+    keepsArms: input.keepsArms ?? KEEPS_NO_ARMS,
     state,
     isAncestorOrSelf
   };
   const continuations = withRejoined(enumerate(ctx, input.statements, []));
-  for (const path6 of continuations) {
+  for (const path7 of continuations) {
     chargeBudget(state);
-    state.fallthrough.push(classify(path6, null, isAncestorOrSelf));
+    state.fallthrough.push(classify(path7, null, isAncestorOrSelf));
   }
   return { byTerminal: state.byTerminal, fallthrough: state.fallthrough };
 }
@@ -1142,8 +1394,8 @@ function sharedGatingConditions(paths, readPredicate) {
     return [];
   }
   const shared = new Set(first.map(keyOf2));
-  for (const path6 of rest) {
-    const here = new Set(path6.map(keyOf2));
+  for (const path7 of rest) {
+    const here = new Set(path7.map(keyOf2));
     for (const value of shared) {
       if (!here.has(value)) {
         shared.delete(value);
@@ -1251,15 +1503,12 @@ var EnclosingNodes = class {
 
 // src/paths/nodeWalk.ts
 var SKIP_CHILDREN = /* @__PURE__ */ Symbol("skipChildren");
-function walkDescendants(root, carried, visitor) {
-  for (const child of root.namedChildren) {
-    if (child === null) {
-      continue;
-    }
+function walkDescendants(root, carried, childrenOf2, visitor) {
+  for (const child of childrenOf2(root)) {
     visitor.at(child, carried);
     const inner = visitor.into(child, carried);
     if (inner !== SKIP_CHILDREN) {
-      walkDescendants(child, inner, visitor);
+      walkDescendants(child, inner, childrenOf2, visitor);
     }
   }
 }
@@ -1338,6 +1587,11 @@ function valueToReadFurtherFrom(reading) {
   return reading.kind === "written" ? reading.value : null;
 }
 
+// src/redirectOption.ts
+function redirectDeliveryWhenSet(option, value) {
+  return option.handsBack.includes(value) ? "response" : "followed";
+}
+
 // src/testFiles.ts
 function isListedTestFile(file, listed) {
   if (listed === void 0) {
@@ -1506,7 +1760,8 @@ function extractionConfigStamp(config) {
     ["workspaceRoot", config.workspaceRoot],
     ["projectRoot", config.projectRoot],
     ["importRoots", config.importRoots?.join(import_node_path4.default.delimiter)],
-    ["modules", modulesStamp(config.modules)]
+    ["modules", modulesStamp(config.modules)],
+    ["walkedDirectory", config.walkedDirectory]
   ];
   return parts.flatMap(
     ([name, value]) => value === void 0 ? [] : [`${name}=${value}`]
@@ -1534,7 +1789,8 @@ function analysisBundles() {
 // src/cache.ts
 var import_node_crypto3 = require("crypto");
 var import_promises2 = __toESM(require("fs/promises"), 1);
-var import_node_path5 = __toESM(require("path"), 1);
+var import_node_path6 = __toESM(require("path"), 1);
+var import_files = require("@suss/behavioral-ir/files");
 
 // src/cacheStamps.ts
 var import_node_crypto2 = require("crypto");
@@ -1642,6 +1898,17 @@ function fileStampEquals(a, b) {
   return a.path === b.path && a.mtimeMs === b.mtimeMs && a.size === b.size;
 }
 
+// src/ignoredDirectory.ts
+var import_node_fs3 = __toESM(require("fs"), 1);
+var import_node_path5 = __toESM(require("path"), 1);
+function makeIgnoredDirectory(dir) {
+  import_node_fs3.default.mkdirSync(dir, { recursive: true });
+  const ignore = import_node_path5.default.join(dir, ".gitignore");
+  if (!import_node_fs3.default.existsSync(ignore)) {
+    import_node_fs3.default.writeFileSync(ignore, "*\n");
+  }
+}
+
 // src/cache.ts
 var SCHEMA_VERSION = "9";
 var MAX_ENTRIES = 2;
@@ -1666,7 +1933,7 @@ function createCacheLayer(cacheDir) {
   const lookupWith = async (input, run) => {
     const entryDir = entryDirFor(cacheDir, input);
     const manifest = await manifests.readAtRunStart(
-      import_node_path5.default.join(entryDir, "manifest.json")
+      import_node_path6.default.join(entryDir, "manifest.json")
     );
     if (manifest === null) {
       return missDiag(await describeAbsentEntry(cacheDir));
@@ -1706,7 +1973,7 @@ function createCacheLayer(cacheDir) {
     async plan(input) {
       const entryDir = entryDirFor(cacheDir, input);
       const manifest = await manifests.readAgain(
-        import_node_path5.default.join(entryDir, "manifest.json")
+        import_node_path6.default.join(entryDir, "manifest.json")
       );
       if (manifest === null || manifest.roots === void 0 || manifest.rootMeta === void 0 || manifest.owners === void 0) {
         return null;
@@ -1725,7 +1992,7 @@ function createCacheLayer(cacheDir) {
     async write(input, summaries, attribution) {
       const entryDir = entryDirFor(cacheDir, input);
       const previous = await manifests.readAgain(
-        import_node_path5.default.join(entryDir, "manifest.json")
+        import_node_path6.default.join(entryDir, "manifest.json")
       );
       manifests.forget();
       const known = runs.get(input);
@@ -1750,11 +2017,8 @@ function createCacheLayer(cacheDir) {
         summaries,
         ...attribution === void 0 ? {} : encodeAttribution(attribution)
       };
-      await import_promises2.default.mkdir(entryDir, { recursive: true });
-      await import_promises2.default.writeFile(
-        import_node_path5.default.join(entryDir, "manifest.json"),
-        JSON.stringify(manifest)
-      );
+      makeIgnoredDirectory(cacheDir);
+      (0, import_files.writeDocumentFile)(import_node_path6.default.join(entryDir, "manifest.json"), manifest);
       await evictOldEntries(cacheDir, entryDir);
     }
   };
@@ -1951,7 +2215,7 @@ function entryDirFor(cacheDir, input) {
     input.configPath ?? ""
   ].join(" ");
   const name = (0, import_node_crypto3.createHash)("sha256").update(key).digest("hex").slice(0, 16);
-  return import_node_path5.default.join(cacheDir, `${ENTRY_PREFIX}${name}`);
+  return import_node_path6.default.join(cacheDir, `${ENTRY_PREFIX}${name}`);
 }
 function isEntryDir(name) {
   return ENTRY_DIR_NAME.test(name);
@@ -1965,11 +2229,11 @@ async function markUsed(entryDir) {
 }
 async function evictOldEntries(cacheDir, keepDir) {
   try {
-    await import_promises2.default.rm(import_node_path5.default.join(cacheDir, "manifest.json"), { force: true });
+    await import_promises2.default.rm(import_node_path6.default.join(cacheDir, "manifest.json"), { force: true });
     const entries = await import_promises2.default.readdir(cacheDir, { withFileTypes: true });
     const dirs = await Promise.all(
       entries.filter((e) => e.isDirectory() && isEntryDir(e.name)).map(async (e) => {
-        const dir = import_node_path5.default.join(cacheDir, e.name);
+        const dir = import_node_path6.default.join(cacheDir, e.name);
         const stat = await import_promises2.default.stat(dir);
         return { dir, mtimeMs: stat.mtimeMs };
       })
@@ -2016,15 +2280,14 @@ async function manifestStamp(manifestPath) {
 }
 async function readManifest(manifestPath) {
   try {
-    const raw = await import_promises2.default.readFile(manifestPath, "utf-8");
-    return JSON.parse(raw);
+    return (0, import_files.readJsonFile)(manifestPath);
   } catch {
     return null;
   }
 }
 
 // src/extractionReport.ts
-var import_behavioral_ir5 = require("@suss/behavioral-ir");
+var import_behavioral_ir6 = require("@suss/behavioral-ir");
 var emptyTally = () => ({
   candidateFiles: 0,
   unitsDiscovered: 0,
@@ -2074,7 +2337,7 @@ function summaryCountsByPack(summaries) {
     }
     const entry = counts.get(recognition) ?? emptyCounts();
     entry.bound += 1;
-    if (import_behavioral_ir5.BOUNDARY_ROLE[summary.kind] === "provider") {
+    if (import_behavioral_ir6.BOUNDARY_ROLE[summary.kind] === "provider") {
       entry.providers += 1;
     }
     if (summary.transitions.length > 0) {
@@ -2510,6 +2773,7 @@ function unreadSentences(raw) {
     ...raw.branches.flatMap(readingsOfBranch)
   ];
   return [
+    ...raw.readFailure !== void 0 ? [raw.readFailure] : [],
     ...raw.unreadBinding !== void 0 ? [raw.unreadBinding] : [],
     ...handedOver.map(unreadReasonOf).filter((reason) => reason !== null)
   ];
@@ -2519,17 +2783,17 @@ function effectsOfBranch(branch) {
     ...branch.effects.map(effectToIR),
     ...branch.extraEffects ?? []
   ];
-  return (0, import_behavioral_ir6.foldRepeatedEffects)(effects.map(withNormalizedCallee));
+  return (0, import_behavioral_ir7.foldRepeatedEffects)(effects.map(withNormalizedCallee));
 }
 function provenanceOf(raw, effects) {
   if (raw.length === 0) {
     return [];
   }
-  const positionOf = new Map(effects.map((one, at) => [(0, import_behavioral_ir6.effectKey)(one), at]));
+  const positionOf = new Map(effects.map((one, at) => [(0, import_behavioral_ir7.effectKey)(one), at]));
   const bySlot = /* @__PURE__ */ new Map();
   const said = /* @__PURE__ */ new Map();
   for (const one of raw) {
-    const effect = positionOf.get((0, import_behavioral_ir6.effectKey)(withNormalizedCallee(one.effect)));
+    const effect = positionOf.get((0, import_behavioral_ir7.effectKey)(withNormalizedCallee(one.effect)));
     if (effect === void 0) {
       continue;
     }
@@ -2561,7 +2825,7 @@ function withNormalizedCallee(effect) {
   if (effect.callee === void 0) {
     return effect;
   }
-  return { ...effect, callee: (0, import_behavioral_ir6.normalizeCalleeText)(effect.callee) };
+  return { ...effect, callee: (0, import_behavioral_ir7.normalizeCalleeText)(effect.callee) };
 }
 function assembleSummary(raw, options = DEFAULT_OPTIONS) {
   const transitions = raw.branches.map((rawBranch) => {
@@ -2626,28 +2890,28 @@ function buildMetadata(raw) {
   let metadata = {};
   const http = buildHttpMetadataValue(raw);
   if (http !== null) {
-    metadata = (0, import_behavioral_ir6.withHttpMetadata)(metadata, http);
+    metadata = (0, import_behavioral_ir7.withHttpMetadata)(metadata, http);
   }
   const graphql = buildGraphqlMetadataValue(raw);
   if (graphql !== null) {
-    metadata = (0, import_behavioral_ir6.withGraphqlMetadata)(metadata, graphql);
+    metadata = (0, import_behavioral_ir7.withGraphqlMetadata)(metadata, graphql);
   }
   if (raw.sourceDocumentLabel !== void 0) {
-    metadata = (0, import_behavioral_ir6.withSourceDocumentMetadata)(metadata, {
+    metadata = (0, import_behavioral_ir7.withSourceDocumentMetadata)(metadata, {
       label: raw.sourceDocumentLabel
     });
   }
   if (raw.mount !== void 0) {
-    metadata = (0, import_behavioral_ir6.withMountMetadata)(metadata, raw.mount);
+    metadata = (0, import_behavioral_ir7.withMountMetadata)(metadata, raw.mount);
   }
   if (raw.wrappers !== void 0 && raw.wrappers.length > 0) {
-    metadata = (0, import_behavioral_ir6.withWrapperMetadata)(metadata, { applied: raw.wrappers });
+    metadata = (0, import_behavioral_ir7.withWrapperMetadata)(metadata, { applied: raw.wrappers });
   }
   if (raw.requestSpelling !== void 0) {
-    metadata = (0, import_behavioral_ir6.withRequestSpellingMetadata)(metadata, raw.requestSpelling);
+    metadata = (0, import_behavioral_ir7.withRequestSpellingMetadata)(metadata, raw.requestSpelling);
   }
   if (raw.test !== void 0) {
-    metadata = (0, import_behavioral_ir6.withTestMetadata)(metadata, raw.test);
+    metadata = (0, import_behavioral_ir7.withTestMetadata)(metadata, raw.test);
   }
   return Object.keys(metadata).length > 0 ? metadata : null;
 }
@@ -2672,6 +2936,12 @@ function buildHttpMetadataValue(raw) {
   if (raw.failureDelivery !== void 0) {
     http.failureDelivery = raw.failureDelivery;
   }
+  if (raw.redirectDelivery !== void 0) {
+    http.redirectDelivery = raw.redirectDelivery;
+  }
+  if (raw.declaredStatuses !== void 0 && raw.declaredStatuses.length > 0) {
+    http.declaredStatuses = raw.declaredStatuses;
+  }
   return Object.keys(http).length > 0 ? http : null;
 }
 function buildGraphqlMetadataValue(raw) {
@@ -2700,7 +2970,7 @@ function answersWithHttpResponses(raw) {
   if (raw.boundaryBinding === null || raw.boundaryBinding === void 0) {
     return true;
   }
-  return (0, import_behavioral_ir6.exchangesHttpResponses)(raw.boundaryBinding);
+  return (0, import_behavioral_ir7.exchangesHttpResponses)(raw.boundaryBinding);
 }
 function detectGaps(raw, transitions, options) {
   if (options.gapHandling === "silent") {
@@ -2739,13 +3009,16 @@ function detectGaps(raw, transitions, options) {
   return gaps;
 }
 function bodyWentUnread(raw) {
+  if (raw.readFailure !== void 0) {
+    return true;
+  }
   if (raw.bodyContent === "absent" || raw.bodyContent === "elsewhere") {
     return true;
   }
   return raw.bodyContent === "statements" && raw.branches.length === 0;
 }
 function describeUnreadBody(raw) {
-  if (!bodyWentUnread(raw)) {
+  if (!bodyWentUnread(raw) || raw.readFailure !== void 0) {
     return null;
   }
   if (raw.bodyContent === "absent") {
@@ -2817,10 +3090,16 @@ var terminalConverters = {
         headers: {}
       };
     }
+    const ancestry = t.exceptionAncestry;
     return {
       type: "throw",
       exceptionType: t.exceptionType,
-      message: t.message
+      message: t.message,
+      ...ancestry === void 0 ? {} : {
+        exceptionAncestors: ancestry.ancestors,
+        ...ancestry.incomplete ? { ancestryIncomplete: true } : {}
+      },
+      ...t.statusWhenUncaught === void 0 ? {} : { statusWhenUncaught: t.statusWhenUncaught }
     };
   },
   render: (t) => ({
@@ -2895,6 +3174,7 @@ function paramToInput(param) {
   IdSet,
   KeptParses,
   MAX_ENTRIES,
+  MAX_HELPER_PATHS,
   MAX_PATHS,
   MODULE_SURFACE_RECOGNITION,
   PathBudgetExceeded,
@@ -2925,12 +3205,15 @@ function paramToInput(param) {
   firstWrittenReading,
   formatPackHealth,
   guardsHoldOn,
+  helperPathsOnVariables,
   httpRouteDiscovery,
   isListedTestFile,
+  makeIgnoredDirectory,
   makeTransitionId,
   mapReading,
   markReturnsAsExitCode,
   matchesTestFileName,
+  mergeReadShapes,
   moduleInitStructure,
   moduleOfFile,
   noopTimer,
@@ -2939,6 +3222,7 @@ function paramToInput(param) {
   projectFileStamp,
   rawConditionToPredicate,
   recordPackFailure,
+  redirectDeliveryWhenSet,
   registrationHelperDiscovery,
   routeHelperIndex,
   runDigest,
@@ -2947,6 +3231,7 @@ function paramToInput(param) {
   settleModules,
   sharedGatingConditions,
   sourceRefsOf,
+  splitAtHandOffs,
   stampMayMissAWrite,
   stampModuleImports,
   stampModules,
@@ -2954,6 +3239,7 @@ function paramToInput(param) {
   summaryCountsByPack,
   tallyUnit,
   terminalToOutput,
+  throughHelper,
   unreadableReading,
   unwrapJsonStringify,
   valueToReadFurtherFrom,