@suss/checker-intent 0.33.1 → 0.34.1

package/dist/index.js

@@ -6,6 +6,7 @@ import {
   deploymentOf,
   goesThroughRelation,
   groundBinding,
+  readProcessMetadata,
   relationsOf,
   summaryRef,
   withDeclaredDelivery,
@@ -24,6 +25,228 @@ import {
   semanticsAgree
 } from "@suss/ir-core";
 
+// src/coveringTests.ts
+import { readTestMetadata } from "@suss/behavioral-ir";
+import { callSpellings, functionOf } from "@suss/checker";
+function checkCoveringTests(claims, lookup) {
+  const verdicts = [];
+  const waiting = [];
+  for (const [at, claim] of claims.entries()) {
+    const found = lookup.test(claim.spelled);
+    if (!found.found) {
+      verdicts.push(finding(claim, "missingCoveringTest", found.message));
+      continue;
+    }
+    if (readTestMetadata(found.unit)?.skipped === true) {
+      verdicts.push(
+        finding(
+          claim,
+          "coveringTestSkipped",
+          "which is marked to be skipped, so it does not run"
+        )
+      );
+      continue;
+    }
+    const subject = subjectOf(claim, lookup);
+    if ("message" in subject) {
+      verdicts.push(finding(claim, "testMissesSubject", subject.message));
+      continue;
+    }
+    verdicts.push(null);
+    waiting.push({
+      at,
+      unit: found.unit,
+      test: functionOf(found.unit),
+      subject
+    });
+  }
+  if (waiting.length === 0) {
+    return verdicts.map((verdict) => verdict ?? { kind: "covered" });
+  }
+  const honouring = lookup.facts.reachedFromEach(
+    waiting.map((one) => one.test),
+    { pastMocks: true }
+  );
+  const missed = waiting.filter(
+    (one) => pathInto(one.test, honouring.get(one.test), one.subject) === null && callOnSubjectClass(one.test, one.subject, lookup, true) === null
+  );
+  const ignoring = missed.length === 0 ? /* @__PURE__ */ new Map() : lookup.facts.reachedFromEach(missed.map((one) => one.test));
+  for (const one of waiting) {
+    const claim = claims[one.at];
+    if (!missed.includes(one)) {
+      verdicts[one.at] = { kind: "covered" };
+      continue;
+    }
+    const reached = ignoring.get(one.test);
+    const throughMock = pathInto(one.test, reached, one.subject) ?? callOnSubjectClass(one.test, one.subject, lookup, false);
+    if (throughMock !== null) {
+      verdicts[one.at] = finding(
+        claim,
+        "testMissesSubject",
+        `which reaches ${one.subject.label} only through a call its mocks replace (${mocksOf(lookup, one.test).join(", ")}), by ${callSpellings(throughMock).join(" -> ")}`
+      );
+      continue;
+    }
+    const unfollowed = unfollowedOnTheWay(one.unit, one.test, reached, lookup);
+    const nameMatches = unfollowedToSubject(one.unit, one.subject, lookup);
+    verdicts[one.at] = unfollowed.length === 0 && nameMatches.length === 0 ? finding(
+      claim,
+      "testMissesSubject",
+      `which never reaches ${one.subject.label}`
+    ) : notChecked(claim, one.subject, nameMatches, unfollowed);
+  }
+  return verdicts.map((verdict) => verdict ?? { kind: "covered" });
+}
+var CALLS_LISTED = 3;
+function notChecked(claim, subject, nameMatches, unfollowed) {
+  const calls = nameMatches.length > 0 ? nameMatches : unfollowed;
+  const listed = calls.slice(0, CALLS_LISTED).join(", ");
+  const more = calls.length > CALLS_LISTED ? `, and ${calls.length - CALLS_LISTED} more` : "";
+  const why = nameMatches.length > 0 ? `it calls ${listed}${more}, and suss could not follow that call to ${subject.label}` : `it never reaches ${subject.label} through the calls suss followed, and suss could not follow ${listed}${more}`;
+  return {
+    kind: "unchecked",
+    unchecked: {
+      intent: claim.prd.title,
+      reason: "unfollowedCall",
+      scenario: claim.label,
+      coveredBy: claim.spelled.spelledAs,
+      detail: `Scenario ${claim.label} lists the test "${claim.spelled.spelledAs}": ${why}.`
+    }
+  };
+}
+function unfollowedOnTheWay(test, key, reached, lookup) {
+  const units = [
+    test,
+    ...[...reached?.functions.keys() ?? []].filter((fn) => fn !== key).flatMap((fn) => lookup.facts.units.get(fn) ?? [])
+  ];
+  const found = /* @__PURE__ */ new Set();
+  for (const unit of units) {
+    for (const gap of unit.gaps) {
+      if (gap.type === "unfollowedCall" && gap.callee !== void 0) {
+        found.add(gap.callee);
+      }
+    }
+  }
+  return [...found];
+}
+function subjectOf(claim, lookup) {
+  if (claim.subjects.length === 0) {
+    return {
+      message: "and the PRD links to no boundary a test could be checked against; say what it has to reach under about"
+    };
+  }
+  const found = [];
+  for (const spelledAs of claim.subjects) {
+    const one = lookup.subject(spelledAs);
+    if (!one.found) {
+      return {
+        message: `and what it has to reach, ${spelledAs}, is nothing in these summaries: ${one.message.replace(/\.$/, "")}`
+      };
+    }
+    found.push({ ...one, classes: one.classes ?? [] });
+  }
+  return {
+    target: {
+      functions: found.flatMap((one) => one.target.functions),
+      keys: found.flatMap((one) => one.target.keys),
+      at: found.flatMap((one) => one.target.at ?? [])
+    },
+    label: found.map((one) => one.label).join(" or "),
+    classes: found.flatMap((one) => one.classes)
+  };
+}
+function pathInto(test, reached, subject) {
+  const into = [...subject.target.functions, ...subject.target.at ?? []];
+  if (into.includes(test)) {
+    return [];
+  }
+  const paths = [
+    ...into.map((fn) => reached?.functions.get(fn)),
+    ...subject.target.keys.map((key) => reached?.keys.get(key))
+  ].filter((path) => path !== void 0);
+  if (paths.length === 0) {
+    return null;
+  }
+  return paths.reduce(
+    (shortest, path) => path.length < shortest.length ? path : shortest
+  );
+}
+function callOnSubjectClass(test, subject, lookup, honourMocks) {
+  const classes = new Set(subject.classes.map(classKey));
+  if (classes.size === 0) {
+    return null;
+  }
+  const units = lookup.facts.units.get(test) ?? [];
+  const mocks = honourMocks ? units.flatMap((unit) => readTestMetadata(unit)?.mocks ?? []) : [];
+  for (const effect of units.flatMap(
+    (unit) => unit.transitions.flatMap((transition) => transition.effects)
+  )) {
+    if (effect.type !== "invocation" || effect.receiverClass === void 0 || !classes.has(classKey(effect.receiverClass))) {
+      continue;
+    }
+    const method = lastName(effect.callee);
+    if (mocks.some((mock) => replaces(mock, effect.receiverClass, method))) {
+      continue;
+    }
+    return [{ callee: effect.callee, to: null, recorded: "written" }];
+  }
+  return null;
+}
+function classKey(sentTo) {
+  return `${sentTo.file}#${sentTo.name}`;
+}
+function replaces(mock, sentTo, method) {
+  if (mock.module === void 0) {
+    return mock.name === method;
+  }
+  return mock.module === sentTo?.file && (mock.name === void 0 || mock.name === method);
+}
+function unfollowedToSubject(test, subject, lookup) {
+  const names = /* @__PURE__ */ new Set([
+    ...[...subject.target.functions, ...subject.target.at ?? []].flatMap(
+      (fn) => (lookup.facts.units.get(fn) ?? []).map(
+        (unit) => lastName(unit.identity.name)
+      )
+    ),
+    ...subject.target.keys.map(lastName)
+  ]);
+  const unfollowed = test.transitions.flatMap(
+    (transition) => transition.effects.flatMap(
+      (effect) => effect.type === "invocation" && effect.summary === void 0 && names.has(lastName(effect.callee)) ? [effect.callee] : []
+    )
+  );
+  return [...new Set(unfollowed)];
+}
+function lastName(spelled) {
+  return spelled.split(/::|\./).at(-1) ?? spelled;
+}
+function mocksOf(lookup, test) {
+  const units = lookup.facts.units.get(test) ?? [];
+  return [
+    ...new Set(
+      units.flatMap(
+        (unit) => (readTestMetadata(unit)?.mocks ?? []).map((mock) => mock.written)
+      )
+    )
+  ];
+}
+function finding(claim, kind, why) {
+  return {
+    kind: "finding",
+    finding: {
+      kind,
+      severity: "warning",
+      boundary: `prd:${claim.prd.title}`,
+      intent: { name: claim.prd.title },
+      scenario: {
+        ...claim.scenarioTitle !== null ? { title: claim.scenarioTitle } : {},
+        coveredBy: claim.spelled.spelledAs
+      },
+      message: `Scenario ${claim.label} in PRD "${claim.prd.title}" lists the test "${claim.spelled.spelledAs}", ${why}.`
+    }
+  };
+}
+
 // src/receivedInput.ts
 import { boundaryInputReads, formatPath } from "@suss/behavioral-ir";
 function overlaps(a, b) {
@@ -59,7 +282,7 @@ function checkReceivesBlock(pairing) {
     return [];
   }
   const read = result.reads.paths;
-  const unread = declared.filter(
+  const unread2 = declared.filter(
     (field) => !read.some((path) => overlaps(path, field.path))
   );
   const alreadyDescribed = DESCRIBED_WITHOUT_LISTING[pairing.intent.boundary.semantics.name];
@@ -67,7 +290,7 @@ function checkReceivesBlock(pairing) {
     (path) => !declared.some((field) => overlaps(path, field.path)) && !alreadyDescribed(declared, path)
   );
   return [
-    ...unread.map((field) => unreadFinding(pairing, field)),
+    ...unread2.map((field) => unreadFinding(pairing, field)),
     ...undeclaredFindings(pairing, undeclared)
   ];
 }
@@ -81,7 +304,8 @@ var DESCRIBED_WITHOUT_LISTING = {
   "graphql-resolver": LISTS_EVERYTHING,
   "graphql-operation": LISTS_EVERYTHING,
   "runtime-config": LISTS_EVERYTHING,
-  metric: LISTS_EVERYTHING
+  metric: LISTS_EVERYTHING,
+  io: LISTS_EVERYTHING
 };
 function unreadFinding(pairing, field) {
   const needsIt = field.required ? " and needs it" : "";
@@ -115,11 +339,107 @@ function undeclaredFindings(pairing, undeclared) {
   return findings;
 }
 
+// src/valueSources.ts
+import { boundarySourcePathOf, formatPath as formatPath2 } from "@suss/behavioral-ir";
+function checkValueSources(claim, matched) {
+  const checked = { findings: [], unchecked: [] };
+  for (const source of claim.effect.from ?? []) {
+    const found = matched.flatMap(
+      (made) => slotsFor(claim.effect, source.column, made).flatMap(
+        (slot) => slot.from.map((written) => {
+          const ref = unconverted(written);
+          return { ref, path: pathOf(claim, ref), line: made.line };
+        })
+      )
+    );
+    if (found.some((one) => samePath(one.path, source.path))) {
+      continue;
+    }
+    const known = found.filter(
+      (one) => one.path !== null || one.ref.type === "literal"
+    );
+    if (known.length > 0) {
+      checked.findings.push(elsewhere(claim, source, known));
+      continue;
+    }
+    checked.unchecked.push(unread(claim, source, found));
+  }
+  return checked;
+}
+function slotsFor(effect, column, made) {
+  const kinds = /* @__PURE__ */ new Set([
+    ...effect.by.includes(column) ? ["selector"] : [],
+    ...effect.fields.includes(column) ? ["field"] : []
+  ]);
+  return (made.slots ?? []).filter(
+    (slot) => slot.at.name === column && kinds.has(slot.at.slot)
+  );
+}
+function unconverted(ref) {
+  return ref.type === "derived" && ref.derivation.type === "methodCall" ? unconverted(ref.from) : ref;
+}
+function pathOf(claim, ref) {
+  const binding = claim.intent.boundary;
+  return ref.type === "input" ? boundarySourcePathOf(claim.impl, binding, ref) : null;
+}
+function samePath(code, declared) {
+  if (code === null || code.length !== declared.length) {
+    return false;
+  }
+  const left = comparable(code);
+  const right = comparable(declared);
+  return left.every((segment, at) => segment === right[at]);
+}
+function spell(one) {
+  if (one.path !== null) {
+    return `input.${formatPath2(one.path)}`;
+  }
+  return one.ref.type === "literal" ? `the literal ${JSON.stringify(one.ref.value)}` : "somewhere it could not follow";
+}
+function doing(claim) {
+  const { effect, outcome } = claim;
+  return `${outcome.id} ${effect.does} ${effect.names}`;
+}
+function elsewhere(claim, source, known) {
+  const said = [
+    ...new Set(
+      known.map(
+        (one) => one.line === void 0 ? spell(one) : `${spell(one)} (in the transition at line ${one.line})`
+      )
+    )
+  ];
+  return {
+    kind: "valueFromElsewhere",
+    severity: "error",
+    boundary: claim.boundary,
+    intent: { name: claim.intent.name, outcomeId: claim.outcome.id },
+    code: claim.code,
+    message: `Intent "${claim.intent.name}" says ${doing(claim)} with ${source.column} taken from input.${formatPath2(source.path)}; ${claim.impl.identity.name} takes it from ${said.join(" and ")}. Take the value from the source the intent gives, or correct the document.`
+  };
+}
+function unread(claim, source, found) {
+  const stopped = [
+    ...new Set(
+      found.flatMap(
+        (one) => one.ref.type === "unresolved" ? [one.ref.sourceText] : []
+      )
+    )
+  ];
+  const why = stopped.length === 0 ? `nothing in the summary says where ${source.column} comes from` : `the walk from ${source.column} stopped at ${stopped.map((text) => `\`${text}\``).join(" and ")}, which it cannot follow`;
+  return {
+    intent: claim.intent.name,
+    reason: "unreadValue",
+    outcomeId: claim.outcome.id,
+    detail: `${doing(claim)} with ${source.column} taken from input.${formatPath2(source.path)}: ${why}.`
+  };
+}
+
 // src/index.ts
-function checkIntentAgreement(intents, code) {
+function checkIntentAgreement(intents, code, tests) {
   const findings = [];
   const checked = [];
   const unchecked = [];
+  const claims = [];
   const codeByBoundary = indexCodeByBoundary(code);
   const boundaryByName = indexBoundaryIntentsByName(intents);
   const deploymentOfUnit = deploymentOf(code);
@@ -129,6 +449,7 @@ function checkIntentAgreement(intents, code) {
       const result2 = checkPrdCoverage(intent, boundaryByName);
       findings.push(...withProvenance(result2.findings, intent.source));
       checked.push(result2.checked);
+      claims.push(...result2.claims);
       continue;
     }
     const result = checkBoundaryIntent(
@@ -141,9 +462,44 @@ function checkIntentAgreement(intents, code) {
     checked.push(...result.checked);
     unchecked.push(...result.unchecked);
   }
+  if (tests !== void 0) {
+    const scenarioTests = checkScenarioTests(claims, tests);
+    findings.push(...scenarioTests.findings);
+    unchecked.push(...scenarioTests.unchecked);
+  }
   findings.push(...checkOutcomesDescribed(intents));
   return { findings, checked, unchecked };
 }
+function checkScenarioTests(claims, tests) {
+  const verdicts = checkCoveringTests(
+    claims.map((one) => one.claim),
+    tests
+  );
+  const failed = /* @__PURE__ */ new Set();
+  const findings = [];
+  const unchecked = [];
+  for (const [at, verdict] of verdicts.entries()) {
+    if (verdict.kind === "covered") {
+      continue;
+    }
+    const { claim, checked, scenario } = claims[at];
+    failed.add(`${checked.intent}\0${scenario}`);
+    if (verdict.kind === "finding") {
+      findings.push(...withProvenance([verdict.finding], claim.prd.source));
+      continue;
+    }
+    unchecked.push(verdict.unchecked);
+  }
+  const counted = /* @__PURE__ */ new Set();
+  for (const { checked, scenario } of claims) {
+    const key = `${checked.intent}\0${scenario}`;
+    if (!failed.has(key) && !counted.has(key)) {
+      counted.add(key);
+      checked.covered += 1;
+    }
+  }
+  return { findings, unchecked };
+}
 function checkOutcomesDescribed(intents) {
   const prds = intents.filter((intent) => intent.kind === "prd");
   if (prds.length === 0) {
@@ -218,7 +574,7 @@ function checkBoundaryIntent(intent, codeByBoundary, deploymentOfUnit, wrappersO
           message: `Intent "${intent.name}" declares boundary ${label} with ${intent.outcomes.length} outcome(s); no code produces this boundary.`
         }
       ],
-      // The comparison ran: finding no implementation IS the result.
+      // The comparison ran, and finding no implementation is its result.
       checked: [
         {
           kind: "boundary",
@@ -231,6 +587,7 @@ function checkBoundaryIntent(intent, codeByBoundary, deploymentOfUnit, wrappersO
     };
   }
   const findings = [];
+  const unchecked = [];
   for (const impl of impls) {
     findings.push(
       ...compareIntentToImpl(
@@ -238,7 +595,8 @@ function checkBoundaryIntent(intent, codeByBoundary, deploymentOfUnit, wrappersO
         impl,
         label,
         deploymentOfUnit(impl),
-        wrappersOfUnit(impl)
+        wrappersOfUnit(impl),
+        unchecked
       )
     );
   }
@@ -252,7 +610,7 @@ function checkBoundaryIntent(intent, codeByBoundary, deploymentOfUnit, wrappersO
         implementations: impls.map(codeRef)
       }
     ],
-    unchecked: []
+    unchecked
   };
 }
 function codeRef(impl) {
@@ -260,50 +618,76 @@ function codeRef(impl) {
 }
 function checkPrdCoverage(prd, boundaryByName) {
   const findings = [];
-  let resolved = 0;
-  let unlinked = 0;
+  const claims = [];
+  const checked = {
+    kind: "prd",
+    intent: prd.title,
+    scenarios: prd.scenarios.length,
+    resolved: 0,
+    covered: 0,
+    unlinked: 0
+  };
+  const fallbackSubjects = linkedBoundaryKeys(prd, boundaryByName);
   prd.scenarios.forEach((scenario, index) => {
     const label = scenarioLabel(scenario.title, index);
-    if (scenario.link.length === 0) {
-      unlinked += 1;
+    for (const spelled of scenario.coveredBy) {
+      claims.push({
+        claim: {
+          prd,
+          scenarioTitle: scenario.title,
+          label,
+          spelled,
+          subjects: scenario.about.length > 0 ? scenario.about : fallbackSubjects
+        },
+        checked,
+        scenario: index
+      });
+    }
+    if (scenario.link.length === 0 && scenario.coveredBy.length === 0) {
+      checked.unlinked += 1;
       findings.push({
         kind: "unlinkedScenario",
-        severity: "info",
+        severity: "warning",
         boundary: prdBoundaryLabel(prd),
         intent: { name: prd.title },
         ...scenario.title !== null ? { scenario: { title: scenario.title } } : {},
-        message: `Scenario ${label} in PRD "${prd.title}" has no structured link to a system-intent outcome; it reads on its own, but its coverage can't be checked until a link is added.`
+        message: `Scenario ${label} in PRD "${prd.title}" has neither a link to a boundary outcome nor a covering test, so nothing checks it; add a link, or list the test that covers it under coveredBy.`
       });
       return;
     }
+    if (scenario.link.length === 0) {
+      return;
+    }
     let allResolved = true;
     for (const ref of scenario.link) {
-      const finding = resolveScenarioLink(
+      const finding2 = resolveScenarioLink(
         prd,
         scenario.title,
         label,
         ref,
         boundaryByName
       );
-      if (finding !== null) {
-        findings.push(finding);
+      if (finding2 !== null) {
+        findings.push(finding2);
         allResolved = false;
       }
     }
     if (allResolved) {
-      resolved += 1;
+      checked.resolved += 1;
     }
   });
-  return {
-    findings,
-    checked: {
-      kind: "prd",
-      intent: prd.title,
-      scenarios: prd.scenarios.length,
-      resolved,
-      unlinked
+  return { findings, checked, claims };
+}
+function linkedBoundaryKeys(prd, boundaryByName) {
+  const keys = /* @__PURE__ */ new Set();
+  for (const ref of prd.scenarios.flatMap((scenario) => scenario.link)) {
+    const matches = boundaryByName.get(ref.split(".")[0]) ?? [];
+    const key = matches.length === 1 ? boundaryKey(matches[0].boundary) : null;
+    if (key !== null) {
+      keys.add(key);
     }
-  };
+  }
+  return [...keys];
 }
 function resolveScenarioLink(prd, scenarioTitle, label, ref, boundaryByName) {
   const dot = ref.indexOf(".");
@@ -340,8 +724,8 @@ function resolveScenarioLink(prd, scenarioTitle, label, ref, boundaryByName) {
     return {
       kind: "danglingScenarioLink",
       severity: "warning",
-      // The intent resolved even though the outcome didn't, key on its
-      // boundary so a narrow .sussignore rule can target this finding.
+      // The intent resolved, so the finding is keyed on its boundary,
+      // where a narrow .sussignore rule can match it.
       boundary: boundaryKey(target.boundary) ?? prdBoundaryLabel(prd),
       intent: { name: prd.title },
       scenario: scenarioRef,
@@ -389,11 +773,14 @@ function applyIntentSuppressions(findings, rules, opts = {}) {
   return applySuppressionsToFindings(
     findings,
     rules,
-    (rule, finding) => {
+    (rule, finding2) => {
       if (rule.consumer !== void 0 || rule.provider !== void 0) {
         return false;
       }
-      return rule.boundary === void 0 || ruleBoundaryMatchesKey(rule.boundary, finding.boundary);
+      if (rule.scenario !== void 0 && rule.scenario !== finding2.scenario?.title) {
+        return false;
+      }
+      return rule.boundary === void 0 || ruleBoundaryMatchesKey(rule.boundary, finding2.boundary);
     },
     opts
   );
@@ -424,11 +811,12 @@ function indexCodeByBoundary(code) {
   }
   return byKey;
 }
-function compareIntentToImpl(intent, impl, boundary, deployment, wrappers) {
+function compareIntentToImpl(intent, impl, boundary, deployment, wrappers, unchecked) {
   const findings = [];
   const ref = codeRef(impl);
   const calls = boundaryCalls(impl);
-  const codeOutcomes = impl.transitions.map((t) => toCodeOutcome(t, calls, deployment)).filter((o) => o !== null);
+  const returnIsExitCode = readProcessMetadata(impl)?.exitCodeFrom === "return";
+  const codeOutcomes = impl.transitions.map((t) => toCodeOutcome(t, calls, deployment, returnIsExitCode)).filter((o) => o !== null);
   const everyEffect = impl.transitions.flatMap(
     (t) => codeEffectsOf(t, deployment)
   );
@@ -437,10 +825,27 @@ function compareIntentToImpl(intent, impl, boundary, deployment, wrappers) {
   for (const outcome of intent.outcomes) {
     const reached = outcome.kind === "effect" ? everyEffect : codeOutcomes.filter((co) => outcomeMatches(outcome, co)).flatMap((co) => co.effects);
     for (const effect of outcome.effects) {
-      if (reached.some((made) => effectMatches(effect, made))) {
+      const matched = reached.filter((made) => effectMatches(effect, made));
+      if (matched.length > 0) {
+        if (!writesDeclaredShape(effect, matched)) {
+          findings.push({
+            kind: "outcomeShapeMismatch",
+            severity: "error",
+            boundary,
+            intent: { name: intent.name, outcomeId: outcome.id },
+            code: ref,
+            message: `Intent "${intent.name}" says ${outcome.id} results in ${describeEffect(effect)} at ${boundary} with a declared shape; what ${impl.identity.name} writes there has an incompatible shape.`
+          });
+        }
+        const sources = checkValueSources(
+          { intent, outcome, effect, impl, boundary, code: ref },
+          matched
+        );
+        findings.push(...sources.findings);
+        unchecked.push(...sources.unchecked);
         continue;
       }
-      const finding = {
+      const finding2 = {
         kind: "uncoveredOutcome",
         severity: "error",
         boundary,
@@ -448,10 +853,10 @@ function compareIntentToImpl(intent, impl, boundary, deployment, wrappers) {
         code: ref,
         message: `Intent "${intent.name}" declares that ${outcome.id} results in ${describeEffect(effect)} at ${boundary}; no transition of ${impl.identity.name} does that.${unsettledNote(reached, effect, deployment)}`
       };
-      findings.push(finding);
+      findings.push(finding2);
       if (neverTouchesBoundary(effect.names, everyEffect)) {
         vanished.push({
-          finding,
+          finding: finding2,
           boundary: effect.names,
           does: effect.does,
           kind: "effect",
@@ -475,9 +880,7 @@ function compareIntentToImpl(intent, impl, boundary, deployment, wrappers) {
       });
       continue;
     }
-    const stated = outcome.conditions.filter(
-      (c) => c.at !== null
-    );
+    const stated = boundaryClauses(outcome);
     const matches = stated.length === 0 ? ending : ending.filter(
       (co) => stated.every((c) => conditionMet(c, co.turnsOn))
     );
@@ -485,7 +888,7 @@ function compareIntentToImpl(intent, impl, boundary, deployment, wrappers) {
       const unmet = stated.find(
         (c) => !ending.some((co) => conditionMet(c, co.turnsOn))
       );
-      const finding = {
+      const finding2 = {
         kind: "uncoveredOutcome",
         severity: "error",
         boundary,
@@ -500,10 +903,10 @@ function compareIntentToImpl(intent, impl, boundary, deployment, wrappers) {
           everyEffect
         )
       };
-      findings.push(finding);
+      findings.push(finding2);
       if (unmet !== void 0 && neverTouchesBoundary(unmet.at.names, everyEffect)) {
         vanished.push({
-          finding,
+          finding: finding2,
           boundary: unmet.at.names,
           does: unmet.at.does,
           kind: "condition",
@@ -556,7 +959,20 @@ function compareIntentToImpl(intent, impl, boundary, deployment, wrappers) {
       message: `${impl.identity.name} produces status ${status} at ${boundary}; intent "${intent.name}" does not declare it.`
     });
   }
-  const declaredEffects = intent.outcomes.flatMap((o) => o.effects);
+  const always = checkAlwaysEffects(
+    intent,
+    impl,
+    boundary,
+    codeOutcomes,
+    everyEffect,
+    deployment
+  );
+  findings.push(...always.findings);
+  vanished.push(...always.vanished);
+  const declaredEffects = [
+    ...intent.outcomes.flatMap((o) => o.effects),
+    ...intent.always.map((a) => a.effect)
+  ];
   const said = /* @__PURE__ */ new Set();
   for (const made of everyEffect) {
     const spelled = `${made.does} ${made.label}`;
@@ -564,7 +980,7 @@ function compareIntentToImpl(intent, impl, boundary, deployment, wrappers) {
       continue;
     }
     said.add(spelled);
-    const finding = {
+    const finding2 = {
       kind: "undeclaredOutcome",
       severity: "info",
       boundary,
@@ -572,8 +988,8 @@ function compareIntentToImpl(intent, impl, boundary, deployment, wrappers) {
       code: ref,
       message: `${impl.identity.name} ${spelled} at ${boundary}; intent "${intent.name}" does not declare it.`
     };
-    findings.push(finding);
-    undeclared.push({ finding, boundary: made.label, does: made.does });
+    findings.push(finding2);
+    undeclared.push({ finding: finding2, boundary: made.label, does: made.does });
   }
   findings.push(
     ...checkReceivesBlock({ intent, impl, wrappers, boundary, code: ref })
@@ -639,7 +1055,7 @@ function foldRenamedBoundaries(intent, impl, boundary, ref, findings, vanished,
       message: `Intent "${intent.name}" declares ${pairing.from}; ${impl.identity.name} ${joinVerbs(pairing.does)} ${pairing.to} instead, with the same outcomes. If the store was renamed, update the intent.`
     });
   }
-  return [...findings.filter((finding) => !explained.has(finding)), ...renamed];
+  return [...findings.filter((finding2) => !explained.has(finding2)), ...renamed];
 }
 function matchRenamedBoundaries(vanishedByBoundary, undeclaredByBoundary) {
   const candidatesFor = /* @__PURE__ */ new Map();
@@ -743,6 +1159,16 @@ function unsettledNote(reached, declared, deployment) {
 function effectMatches(declared, made) {
   return declared.does === made.does && namesBoundary(declared.names, made.binding) && statesAll(declared.fields, made.fields) && statesAll(declared.by, made.by);
 }
+function writesDeclaredShape(declared, matched) {
+  if (declared.shape === void 0) {
+    return true;
+  }
+  const shape = declared.shape;
+  const stated = matched.flatMap(
+    (made) => made.payload === void 0 ? [] : [made.payload]
+  );
+  return stated.length === 0 || stated.some((payload) => bodyShapesMatch(payload, shape) !== "nomatch");
+}
 function statesAll(declared, made) {
   if (declared.length === 0 || made.length === 0 || made.includes(EVERY_FIELD)) {
     return true;
@@ -754,22 +1180,81 @@ function conditionMet(declared, turnsOn) {
     (guard) => guard.does === declared.at.does && namesBoundary(declared.at.names, guard.binding) && (declared.finds === null || declared.finds === guard.polarity)
   );
 }
-function toCodeOutcome(t, calls, deployment) {
+function toCodeOutcome(t, calls, deployment, returnIsExitCode) {
+  const ending = endingOf(t, returnIsExitCode);
+  if (ending === null) {
+    return null;
+  }
+  return {
+    ...ending,
+    effects: codeEffectsOf(t, deployment),
+    turnsOn: boundaryGuardsOf(t, calls).map((guard) => ({
+      ...guard,
+      binding: groundBinding(guard.binding, deployment)
+    })),
+    line: t.location.start
+  };
+}
+function boundaryClauses(outcome) {
+  return outcome.conditions.filter((c) => c.at !== null);
+}
+function producesOutcome(outcome, co) {
+  if (outcome.kind === "effect") {
+    return true;
+  }
+  return outcomeMatches(outcome, co) && boundaryClauses(outcome).every((c) => conditionMet(c, co.turnsOn));
+}
+function checkAlwaysEffects(intent, impl, boundary, codeOutcomes, everyEffect, deployment) {
+  const findings = [];
+  const vanished = [];
+  if (intent.always.length === 0) {
+    return { findings, vanished };
+  }
+  for (const co of codeOutcomes) {
+    const produced = intent.outcomes.filter((o) => producesOutcome(o, co));
+    if (produced.length === 0) {
+      continue;
+    }
+    for (const always of intent.always) {
+      if (produced.some((o) => always.except.includes(o.id))) {
+        continue;
+      }
+      if (co.effects.some((made) => effectMatches(always.effect, made))) {
+        continue;
+      }
+      const outcome = produced.find((o) => o.kind !== "effect") ?? produced[0];
+      const finding2 = {
+        kind: "pathWithoutEffect",
+        severity: "error",
+        boundary,
+        intent: { name: intent.name, outcomeId: outcome.id },
+        code: codeRef(impl),
+        message: `Intent "${intent.name}" says every outcome results in ${describeEffect(always.effect)} at ${boundary}; the transition of ${impl.identity.name} at line ${co.line}, which produces ${describeProduced(outcome)}, does not. Add the effect on that path, or list ${outcome.id} under except.${unsettledNote(co.effects, always.effect, deployment)}`
+      };
+      findings.push(finding2);
+      if (neverTouchesBoundary(always.effect.names, everyEffect)) {
+        vanished.push({
+          finding: finding2,
+          boundary: always.effect.names,
+          does: always.effect.does,
+          kind: "effect",
+          effect: always.effect,
+          reached: co.effects
+        });
+      }
+    }
+  }
+  return { findings, vanished };
+}
+function endingOf(t, returnIsExitCode = false) {
   const output = t.output;
-  const effects = codeEffectsOf(t, deployment);
-  const turnsOn = boundaryGuardsOf(t, calls).map((guard) => ({
-    ...guard,
-    binding: groundBinding(guard.binding, deployment)
-  }));
   if (output.type === "response") {
-    const status = output.statusCode !== null && output.statusCode.type === "literal" ? Number(output.statusCode.value) : null;
     return {
       kind: "response",
-      status: status !== null && Number.isFinite(status) ? status : null,
+      status: literalNumber(output.statusCode),
       body: output.body ?? null,
       errorType: null,
-      effects,
-      turnsOn
+      exitCode: null
     };
   }
   if (output.type === "return") {
@@ -778,8 +1263,7 @@ function toCodeOutcome(t, calls, deployment) {
       status: null,
       body: output.value,
       errorType: null,
-      effects,
-      turnsOn
+      exitCode: returnIsExitCode ? returnedNumber(output.value) : null
     };
   }
   if (output.type === "throw") {
@@ -788,15 +1272,33 @@ function toCodeOutcome(t, calls, deployment) {
       status: null,
       body: null,
       errorType: output.exceptionType,
-      effects,
-      turnsOn
+      exitCode: null
+    };
+  }
+  if (output.type === "exit") {
+    return {
+      kind: "exit",
+      status: literalNumber(output.code),
+      body: null,
+      errorType: null,
+      exitCode: null
     };
   }
   return null;
 }
+function literalNumber(ref) {
+  if (ref === null || ref.type !== "literal") {
+    return null;
+  }
+  const value = Number(ref.value);
+  return Number.isFinite(value) ? value : null;
+}
+function returnedNumber(shape) {
+  return shape !== null && shape.type === "literal" && typeof shape.value === "number" ? shape.value : null;
+}
 function codeEffectsOf(t, deployment) {
   const reached = [];
-  for (const effect of t.effects) {
+  for (const [at, effect] of t.effects.entries()) {
     if (effect.type !== "interaction") {
       continue;
     }
@@ -806,13 +1308,27 @@ function codeEffectsOf(t, deployment) {
     const binding = groundBinding(effect.binding, deployment);
     const label = displayLabel(binding);
     const touched = accessDetail(effect.interaction);
+    const slots = (t.provenance ?? []).filter((one) => one.at.effect === at);
     for (const does of relationsOf(effect.interaction)) {
-      reached.push({ does, binding, label, ...touched });
+      reached.push({
+        does,
+        binding,
+        label,
+        ...touched,
+        ...slots.length === 0 ? {} : { slots },
+        line: t.location.start
+      });
     }
   }
   return reached;
 }
 function accessDetail(interaction) {
+  if (interaction.class === "config-read") {
+    return { fields: [interaction.name], by: [] };
+  }
+  if (interaction.class === "stream-write") {
+    return interaction.payload === null ? { fields: [], by: [] } : { fields: [], by: [], payload: interaction.payload };
+  }
   if (interaction.class !== "storage-access") {
     return { fields: [], by: [] };
   }
@@ -822,6 +1338,9 @@ function accessDetail(interaction) {
   };
 }
 function outcomeMatches(intent, code) {
+  if (intent.kind === "exit") {
+    return exitsWith(intent.status, code);
+  }
   if (intent.kind !== code.kind) {
     return false;
   }
@@ -833,19 +1352,29 @@ function outcomeMatches(intent, code) {
   }
   return true;
 }
+function exitsWith(code, ending) {
+  if (code === null) {
+    return false;
+  }
+  if (ending.kind === "exit") {
+    return ending.status === code;
+  }
+  return ending.kind === "return" && ending.exitCode === code;
+}
 function whatWouldKeyIt(protocol) {
   return WHAT_KEYS[protocol];
 }
 var WHAT_KEYS = {
   rest: "a REST boundary needs a method and a path",
-  "function-call": "a function-call boundary needs package + exportPath",
+  "function-call": "a function-call boundary needs package + exportPath, or module + exportName where the module is one suss.json lists",
   "message-bus": "a message-bus boundary needs a channel",
   storage: "a store has no key at all: write it as `- writes: <store>` on an outcome of the boundary that touches it instead",
   "graphql-resolver": "a resolver needs a type name and a field name",
   "graphql-operation": "an operation pairs by document rather than by key",
   "runtime-config": "a runtime-config boundary needs a deployment target and an instance name",
   metric: "a metric needs a system and a type",
-  "unit-invocation": "an invoked unit needs a deployment target and the name the platform knows it by"
+  "unit-invocation": "an invoked unit needs a deployment target and the name the platform knows it by",
+  io: "a stream is never a boundary of its own: write it as `- writes: io:stdout` on an outcome of the unit that prints"
 };
 function describeOutcome(outcome) {
   if (outcome.kind === "response") {
@@ -854,8 +1383,17 @@ function describeOutcome(outcome) {
   if (outcome.kind === "throw") {
     return outcome.errorType !== null ? `throw ${outcome.errorType}` : "a thrown error";
   }
+  if (outcome.kind === "exit") {
+    return `exit code ${outcome.status}`;
+  }
   return "a return value";
 }
+function describeProduced(outcome) {
+  if (outcome.kind === "effect") {
+    return outcome.id;
+  }
+  return `${outcome.id} (${describeOutcome(outcome)})`;
+}
 function describeEffect(effect) {
   const detail = [
     effect.fields.length > 0 ? `of ${effect.fields.join(", ")}` : null,
@@ -869,7 +1407,12 @@ var EFFECT_PHRASE = {
   invokes: "an invoke of"
 };
 export {
+  accessDetail,
   applyIntentSuppressions,
   checkIntentAgreement,
+  codeEffectsOf,
+  effectMatches,
+  endingOf,
+  outcomeMatches,
   whatWouldKeyIt
 };