@suss/checker-intent 0.20.0 → 0.21.1

package/README.md

@@ -22,13 +22,63 @@ For each boundary intent, it pairs against the code summaries that share
 the same boundary key, and emits:
 
 - `unimplementedBoundary`: the intent declares a boundary no code produces.
-- `uncoveredOutcome`: a declared outcome (response / return / throw) the code never produces.
+- `uncoveredOutcome`: a declared outcome (response / return / throw), or a declared effect, that the code never produces.
 - `outcomeShapeMismatch`: a matched outcome whose body shape disagrees with intent.
-- `undeclaredOutcome`: code produces a REST status the intent doesn't declare (info; intent under-specifies).
+- `undeclaredOutcome`: code produces a REST status, or reaches a boundary, that the intent doesn't declare (info; intent under-specifies).
+- `unkeyableBoundary`: the intent's boundary has no key to pair on, so nothing was compared (warning).
+- `undescribedOutcome`: a declared outcome no PRD scenario links to (info).
 
 v0 checks system intent (`kind: boundary`). PRD outcome intent
 (`kind: prd`), which covers scenarios and links, is a separate pass.
 
+## How a declared effect is compared
+
+An outcome can declare the effects it has, written the way `suss ask` asks about one:
+
+```yaml
+results:
+  - writes: aws.dynamodb:Invoices
+  - invokes: unit:lambda ArchiveWorker
+```
+
+Both directions are checked, and both resolve the boundary with `namesBoundary` in `@suss/ir-core`, the same matcher that settles what somebody types at `suss ask`. So `writes: Invoices` and `writes: aws.dynamodb:Invoices` both pick out the table, exactly as the two spellings do at the command line, and there is no second parser here to drift from that one.
+
+For each declared effect, the pass walks what the matching code transitions reached, each a verb from `relationsOf` and the binding it reached, and reports `uncoveredOutcome` when nothing there matches what the intent said. An outcome that declares an ending narrows to the transitions that end that way; an outcome that declares only effects is checked against every transition of the unit.
+
+For the other direction, the pass walks every boundary the unit's transitions reach and reports `undeclaredOutcome` for each one no outcome declares. An intent listing three writes on a unit doing four has one nobody wrote down. It is info rather than an error for the same reason an undeclared status is: an intent doc declares the floor rather than a closed list, so code beyond it usually means somebody has not written that part down yet.
+
+An access whose container the code cannot settle (a wrapper handed its table as an argument) spells a name with a hole in it and matches nothing here, because grounding that name is the storage pass's job and this pass loads no contracts. An invoke that reads its callee out of an env var is in the same position: the code spells it `unit:lambda {ARCHIVE_WORKER_FUNCTION}`, collapsing that chain is the unit-invocation pass's job, and a document has to spell the callee the way the code does for the two to line up.
+
+## How a declared condition is compared
+
+A `when` clause that says which boundary the branch read is compared too, which is what makes `when` more than prose.
+
+`boundaryGuardsOf` in `@suss/behavioral-ir` says, for each branch of the code, which boundary its guards turned on and whether the guard passed because something was there. A declared outcome then narrows to the branches whose guards match every boundary clause the intent stated, and `uncoveredOutcome` reports one that produces the ending on a different condition. So an intent saying "404 when a read of `aws.dynamodb:Invoices` finds nothing" fails when the code's 404 turns on the row being present.
+
+The boundary resolves through `namesBoundary` again, and `finds` has to agree when the clause states it. A clause about an input, and a clause left as a sentence, are prose to this pass and are not compared: the paths and the words have no counterpart in the summary to check against.
+
+## The coverage question, both ways
+
+The three scenario kinds ask whether a scenario points at an outcome that exists. `undescribedOutcome` asks it the other way: which declared behaviour has nobody written down a reason for. That is the question a product reader has, and the two artifacts to answer it from are the same two.
+
+It stays quiet until at least one PRD is loaded, since before that the answer is every outcome. `suss infer prd` writes a scenario per outcome, so a fresh set of drafts starts with none of these and they appear as the boundary documents grow outcomes past what the PRDs cover.
+
+## Which summaries count as the code
+
+Two rules narrow the summaries an intent doc is compared against, and both are about not arguing with a document over something that was never its job.
+
+A consumer at the same key is a caller. A client calling `GET /users/{id}` shares the key with the route and provides nothing, so comparing outcomes against its returns would report every declared outcome as uncovered.
+
+A summary a manifest produced is a declaration. A CloudFormation queue resource says the channel exists and stops there, so it has no transition that could satisfy an outcome, and the code that does is the handler in the same run. Summaries with `confidence.source: "declared"` are left out for that reason. A boundary with nothing else behind it still reports `unimplementedBoundary`, which is the state it is in: declared and not written yet.
+
+The handler behind a queue needs the declaration for its identity even so, because a SAM template decides which queue delivers to it and its own summary has no channel. `withDeclaredDelivery` in `@suss/behavioral-ir` puts the two together by the deployable unit they both give, and both this pass and `suss infer intent` call it before they index anything by boundary key. It fills in only what a summary left null, and only from a declaration, so a channel the code stated for itself stays as it is.
+
+## Which boundaries can be paired
+
+`whatWouldKeyIt` says, per protocol, what an intent doc needs before it can be paired, and the message on an `unkeyableBoundary` finding and the reason `suss infer intent` reports for a boundary it skipped both come from it.
+
+A store is the case worth knowing: it has no identity key at all, by design in `@suss/ir-core`, so a `kind: boundary` doc for one is authorable and always unkeyable. Naming the store as the target of an effect on the boundary that touches it is what pairs today.
+
 ## Where it fits in suss
 
 This package depends on `@suss/intent-ir` (the intent shapes and

package/dist/index.cjs

@@ -21,7 +21,8 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   applyIntentSuppressions: () => applyIntentSuppressions,
-  checkIntentAgreement: () => checkIntentAgreement
+  checkIntentAgreement: () => checkIntentAgreement,
+  whatWouldKeyIt: () => whatWouldKeyIt
 });
 module.exports = __toCommonJS(index_exports);
 var import_behavioral_ir = require("@suss/behavioral-ir");
@@ -32,6 +33,7 @@ function checkIntentAgreement(intents, code) {
   const unchecked = [];
   const codeByBoundary = indexCodeByBoundary(code);
   const boundaryByName = indexBoundaryIntentsByName(intents);
+  const deploymentOfUnit = (0, import_behavioral_ir.deploymentOf)(code);
   for (const intent of intents) {
     if (intent.kind === "prd") {
       const result2 = checkPrdCoverage(intent, boundaryByName);
@@ -39,14 +41,54 @@ function checkIntentAgreement(intents, code) {
       checked.push(result2.checked);
       continue;
     }
-    const result = checkBoundaryIntent(intent, codeByBoundary);
+    const result = checkBoundaryIntent(
+      intent,
+      codeByBoundary,
+      deploymentOfUnit
+    );
     findings.push(...withProvenance(result.findings, intent.source));
     checked.push(...result.checked);
     unchecked.push(...result.unchecked);
   }
+  findings.push(...checkOutcomesDescribed(intents));
   return { findings, checked, unchecked };
 }
-function checkBoundaryIntent(intent, codeByBoundary) {
+function checkOutcomesDescribed(intents) {
+  const prds = intents.filter((intent) => intent.kind === "prd");
+  if (prds.length === 0) {
+    return [];
+  }
+  const linked = new Set(
+    prds.flatMap((prd) => prd.scenarios.flatMap((scenario) => scenario.link))
+  );
+  const findings = [];
+  for (const intent of intents) {
+    if (intent.kind !== "boundary") {
+      continue;
+    }
+    for (const outcome of intent.outcomes) {
+      if (linked.has(`${intent.name}.${outcome.id}`)) {
+        continue;
+      }
+      findings.push(
+        ...withProvenance(
+          [
+            {
+              kind: "undescribedOutcome",
+              severity: "info",
+              boundary: (0, import_ir_core.boundaryKey)(intent.boundary) ?? intent.name,
+              intent: { name: intent.name, outcomeId: outcome.id },
+              message: `Intent "${intent.name}" declares ${outcome.id} and no PRD scenario says why it is there.`
+            }
+          ],
+          intent.source
+        )
+      );
+    }
+  }
+  return findings;
+}
+function checkBoundaryIntent(intent, codeByBoundary, deploymentOfUnit) {
   const key = (0, import_ir_core.pairingKey)(intent.boundary);
   if (key === null) {
     return {
@@ -54,9 +96,9 @@ function checkBoundaryIntent(intent, codeByBoundary) {
         {
           kind: "unkeyableBoundary",
           severity: "warning",
-          boundary: unkeyedBoundaryLabel(intent.boundary),
+          boundary: (0, import_ir_core.displayLabel)(intent.boundary),
           intent: { name: intent.name },
-          message: `Intent "${intent.name}" has a ${intent.boundary.semantics.name} boundary that can't be keyed for pairing (function-call boundaries need package + exportPath); it was not checked against code.`
+          message: `Intent "${intent.name}" has a ${intent.boundary.semantics.name} boundary that can't be keyed for pairing (${whatWouldKeyIt(intent.boundary.semantics.name)}); it was not checked against code.`
         }
       ],
       checked: [],
@@ -99,7 +141,9 @@ function checkBoundaryIntent(intent, codeByBoundary) {
   }
   const findings = [];
   for (const impl of impls) {
-    findings.push(...compareIntentToImpl(intent, impl, label));
+    findings.push(
+      ...compareIntentToImpl(intent, impl, label, deploymentOfUnit(impl))
+    );
   }
   return {
     findings,
@@ -259,10 +303,13 @@ function applyIntentSuppressions(findings, rules, opts = {}) {
 }
 function indexCodeByBoundary(code) {
   const byKey = /* @__PURE__ */ new Map();
-  for (const summary of code) {
+  for (const summary of (0, import_behavioral_ir.withDeclaredDelivery)(code)) {
     if (import_behavioral_ir.BOUNDARY_ROLE[summary.kind] !== "provider") {
       continue;
     }
+    if (summary.confidence.source === "declared") {
+      continue;
+    }
     const binding = summary.identity.boundaryBinding;
     if (binding === null) {
       continue;
@@ -280,13 +327,34 @@ function indexCodeByBoundary(code) {
   }
   return byKey;
 }
-function compareIntentToImpl(intent, impl, boundary) {
+function compareIntentToImpl(intent, impl, boundary, deployment) {
   const findings = [];
   const ref = codeRef(impl);
-  const codeOutcomes = impl.transitions.map(toCodeOutcome).filter((o) => o !== null);
+  const calls = (0, import_behavioral_ir.boundaryCalls)(impl);
+  const codeOutcomes = impl.transitions.map((t) => toCodeOutcome(t, calls, deployment)).filter((o) => o !== null);
+  const everyEffect = impl.transitions.flatMap(
+    (t) => codeEffectsOf(t, deployment)
+  );
   for (const outcome of intent.outcomes) {
-    const matches = codeOutcomes.filter((co) => outcomeMatches(outcome, co));
-    if (matches.length === 0) {
+    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))) {
+        continue;
+      }
+      findings.push({
+        kind: "uncoveredOutcome",
+        severity: "error",
+        boundary,
+        intent: { name: intent.name, outcomeId: outcome.id },
+        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)}`
+      });
+    }
+    if (outcome.kind === "effect") {
+      continue;
+    }
+    const ending = codeOutcomes.filter((co) => outcomeMatches(outcome, co));
+    if (ending.length === 0) {
       findings.push({
         kind: "uncoveredOutcome",
         severity: "error",
@@ -297,6 +365,26 @@ function compareIntentToImpl(intent, impl, boundary) {
       });
       continue;
     }
+    const stated = outcome.conditions.filter(
+      (c) => c.at !== null
+    );
+    const matches = stated.length === 0 ? ending : ending.filter(
+      (co) => stated.every((c) => conditionMet(c, co.turnsOn))
+    );
+    if (matches.length === 0) {
+      const unmet = stated.find(
+        (c) => !ending.some((co) => conditionMet(c, co.turnsOn))
+      );
+      findings.push({
+        kind: "uncoveredOutcome",
+        severity: "error",
+        boundary,
+        intent: { name: intent.name, outcomeId: outcome.id },
+        code: ref,
+        message: `Intent "${intent.name}" declares ${describeOutcome(outcome)} at ${boundary} when ${unmet?.said ?? outcome.when}; ${impl.identity.name} produces it on a different condition.`
+      });
+      continue;
+    }
     const declaredBody = outcome.body;
     if (declaredBody === null) {
       continue;
@@ -340,17 +428,70 @@ function compareIntentToImpl(intent, impl, boundary) {
       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 said = /* @__PURE__ */ new Set();
+  for (const made of everyEffect) {
+    const spelled = `${made.does} ${made.label}`;
+    if (said.has(spelled) || declaredEffects.some((effect) => effectMatches(effect, made))) {
+      continue;
+    }
+    said.add(spelled);
+    findings.push({
+      kind: "undeclaredOutcome",
+      severity: "info",
+      boundary,
+      intent: { name: intent.name },
+      code: ref,
+      message: `${impl.identity.name} ${spelled} at ${boundary}; intent "${intent.name}" does not declare it.`
+    });
+  }
   return findings;
 }
-function toCodeOutcome(t) {
+function unsettledNote(reached, declared, deployment) {
+  const variables = /* @__PURE__ */ new Set();
+  for (const made of reached) {
+    const reference = (0, import_ir_core.nameReference)(made.binding);
+    const variable = reference === null ? null : deployment.variableFor(reference);
+    if (made.does === declared.does && variable !== null) {
+      variables.add(variable);
+    }
+  }
+  if (variables.size === 0) {
+    return "";
+  }
+  const named = [...variables].sort().join(", ");
+  return ` The code says which one through ${named}, and nothing in this run says what that is set to. Read the deployment that sets it in and check again.`;
+}
+function effectMatches(declared, made) {
+  return declared.does === made.does && (0, import_ir_core.namesBoundary)(declared.names, made.binding) && statesAll(declared.fields, made.fields) && statesAll(declared.by, made.by);
+}
+function statesAll(declared, made) {
+  if (declared.length === 0 || made.length === 0 || made.includes(import_ir_core.EVERY_FIELD)) {
+    return true;
+  }
+  return declared.every((one) => made.includes(one));
+}
+function conditionMet(declared, turnsOn) {
+  return turnsOn.some(
+    (guard) => guard.does === declared.at.does && (0, import_ir_core.namesBoundary)(declared.at.names, guard.binding) && (declared.finds === null || declared.finds === guard.polarity)
+  );
+}
+function toCodeOutcome(t, calls, deployment) {
   const output = t.output;
+  const effects = codeEffectsOf(t, deployment);
+  const turnsOn = (0, import_behavioral_ir.boundaryGuardsOf)(t, calls).map((guard) => ({
+    ...guard,
+    binding: (0, import_behavioral_ir.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,
       body: output.body ?? null,
-      errorType: null
+      errorType: null,
+      effects,
+      turnsOn
     };
   }
   if (output.type === "return") {
@@ -358,7 +499,9 @@ function toCodeOutcome(t) {
       kind: "return",
       status: null,
       body: output.value,
-      errorType: null
+      errorType: null,
+      effects,
+      turnsOn
     };
   }
   if (output.type === "throw") {
@@ -366,11 +509,40 @@ function toCodeOutcome(t) {
       kind: "throw",
       status: null,
       body: null,
-      errorType: output.exceptionType
+      errorType: output.exceptionType,
+      effects,
+      turnsOn
     };
   }
   return null;
 }
+function codeEffectsOf(t, deployment) {
+  const reached = [];
+  for (const effect of t.effects) {
+    if (effect.type !== "interaction") {
+      continue;
+    }
+    if ((0, import_behavioral_ir.goesThroughRelation)(effect.interaction)) {
+      continue;
+    }
+    const binding = (0, import_behavioral_ir.groundBinding)(effect.binding, deployment);
+    const label = (0, import_ir_core.displayLabel)(binding);
+    const touched = accessDetail(effect.interaction);
+    for (const does of (0, import_behavioral_ir.relationsOf)(effect.interaction)) {
+      reached.push({ does, binding, label, ...touched });
+    }
+  }
+  return reached;
+}
+function accessDetail(interaction) {
+  if (interaction.class !== "storage-access") {
+    return { fields: [], by: [] };
+  }
+  return {
+    fields: interaction.fields,
+    by: interaction.selector ?? []
+  };
+}
 function outcomeMatches(intent, code) {
   if (intent.kind !== code.kind) {
     return false;
@@ -383,14 +555,20 @@ function outcomeMatches(intent, code) {
   }
   return true;
 }
-function unkeyedBoundaryLabel(binding) {
-  const semantics = binding.semantics;
-  if (semantics.name === "function-call") {
-    const target = semantics.module ?? semantics.package ?? "?";
-    return `fn:${target}::${semantics.exportName ?? "?"}`;
-  }
-  return semantics.name;
+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",
+  "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"
+};
 function describeOutcome(outcome) {
   if (outcome.kind === "response") {
     return `status ${outcome.status}`;
@@ -400,8 +578,21 @@ function describeOutcome(outcome) {
   }
   return "a return value";
 }
+function describeEffect(effect) {
+  const detail = [
+    effect.fields.length > 0 ? `of ${effect.fields.join(", ")}` : null,
+    effect.by.length > 0 ? `by ${effect.by.join(", ")}` : null
+  ].filter((part) => part !== null);
+  return [EFFECT_PHRASE[effect.does], effect.names, ...detail].join(" ");
+}
+var EFFECT_PHRASE = {
+  reads: "a read of",
+  writes: "a write to",
+  invokes: "an invoke of"
+};
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   applyIntentSuppressions,
-  checkIntentAgreement
+  checkIntentAgreement,
+  whatWouldKeyIt
 });

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 import { BehavioralSummary } from '@suss/behavioral-ir';
 import { IntentFinding, IntentSummary } from '@suss/intent-ir';
 export { IntentFinding } from '@suss/intent-ir';
-import { SuppressionRule } from '@suss/ir-core';
+import { SuppressionRule, Semantics } from '@suss/ir-core';
 
 /** A boundary intent that was paired and compared against code. */
 interface CheckedBoundaryIntent {
@@ -81,5 +81,11 @@ declare function checkIntentAgreement(intents: IntentSummary[], code: Behavioral
 declare function applyIntentSuppressions(findings: IntentFinding[], rules: SuppressionRule[], opts?: {
     keepHidden?: boolean;
 }): IntentFinding[];
+/**
+ * What each protocol needs before an intent doc written against one of
+ * its boundaries can be paired, in the doc author's terms. The
+ * drafter says the same thing about a boundary it could not write.
+ */
+declare function whatWouldKeyIt(protocol: Semantics["name"]): string;
 
-export { type CheckIntentResult, type CheckedBoundaryIntent, type CheckedIntent, type CheckedPrd, type UncheckedIntent, applyIntentSuppressions, checkIntentAgreement };
+export { type CheckIntentResult, type CheckedBoundaryIntent, type CheckedIntent, type CheckedPrd, type UncheckedIntent, applyIntentSuppressions, checkIntentAgreement, whatWouldKeyIt };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { BehavioralSummary } from '@suss/behavioral-ir';
 import { IntentFinding, IntentSummary } from '@suss/intent-ir';
 export { IntentFinding } from '@suss/intent-ir';
-import { SuppressionRule } from '@suss/ir-core';
+import { SuppressionRule, Semantics } from '@suss/ir-core';
 
 /** A boundary intent that was paired and compared against code. */
 interface CheckedBoundaryIntent {
@@ -81,5 +81,11 @@ declare function checkIntentAgreement(intents: IntentSummary[], code: Behavioral
 declare function applyIntentSuppressions(findings: IntentFinding[], rules: SuppressionRule[], opts?: {
     keepHidden?: boolean;
 }): IntentFinding[];
+/**
+ * What each protocol needs before an intent doc written against one of
+ * its boundaries can be paired, in the doc author's terms. The
+ * drafter says the same thing about a boundary it could not write.
+ */
+declare function whatWouldKeyIt(protocol: Semantics["name"]): string;
 
-export { type CheckIntentResult, type CheckedBoundaryIntent, type CheckedIntent, type CheckedPrd, type UncheckedIntent, applyIntentSuppressions, checkIntentAgreement };
+export { type CheckIntentResult, type CheckedBoundaryIntent, type CheckedIntent, type CheckedPrd, type UncheckedIntent, applyIntentSuppressions, checkIntentAgreement, whatWouldKeyIt };

package/dist/index.js

@@ -1,9 +1,23 @@
 // src/index.ts
-import { BOUNDARY_ROLE, summaryRef } from "@suss/behavioral-ir";
+import {
+  BOUNDARY_ROLE,
+  boundaryCalls,
+  boundaryGuardsOf,
+  deploymentOf,
+  goesThroughRelation,
+  groundBinding,
+  relationsOf,
+  summaryRef,
+  withDeclaredDelivery
+} from "@suss/behavioral-ir";
 import {
   applySuppressionsToFindings,
   bodyShapesMatch,
   boundaryKey,
+  displayLabel,
+  EVERY_FIELD,
+  nameReference,
+  namesBoundary,
   pairingKey,
   ruleBoundaryMatchesKey,
   semanticsAgree
@@ -14,6 +28,7 @@ function checkIntentAgreement(intents, code) {
   const unchecked = [];
   const codeByBoundary = indexCodeByBoundary(code);
   const boundaryByName = indexBoundaryIntentsByName(intents);
+  const deploymentOfUnit = deploymentOf(code);
   for (const intent of intents) {
     if (intent.kind === "prd") {
       const result2 = checkPrdCoverage(intent, boundaryByName);
@@ -21,14 +36,54 @@ function checkIntentAgreement(intents, code) {
       checked.push(result2.checked);
       continue;
     }
-    const result = checkBoundaryIntent(intent, codeByBoundary);
+    const result = checkBoundaryIntent(
+      intent,
+      codeByBoundary,
+      deploymentOfUnit
+    );
     findings.push(...withProvenance(result.findings, intent.source));
     checked.push(...result.checked);
     unchecked.push(...result.unchecked);
   }
+  findings.push(...checkOutcomesDescribed(intents));
   return { findings, checked, unchecked };
 }
-function checkBoundaryIntent(intent, codeByBoundary) {
+function checkOutcomesDescribed(intents) {
+  const prds = intents.filter((intent) => intent.kind === "prd");
+  if (prds.length === 0) {
+    return [];
+  }
+  const linked = new Set(
+    prds.flatMap((prd) => prd.scenarios.flatMap((scenario) => scenario.link))
+  );
+  const findings = [];
+  for (const intent of intents) {
+    if (intent.kind !== "boundary") {
+      continue;
+    }
+    for (const outcome of intent.outcomes) {
+      if (linked.has(`${intent.name}.${outcome.id}`)) {
+        continue;
+      }
+      findings.push(
+        ...withProvenance(
+          [
+            {
+              kind: "undescribedOutcome",
+              severity: "info",
+              boundary: boundaryKey(intent.boundary) ?? intent.name,
+              intent: { name: intent.name, outcomeId: outcome.id },
+              message: `Intent "${intent.name}" declares ${outcome.id} and no PRD scenario says why it is there.`
+            }
+          ],
+          intent.source
+        )
+      );
+    }
+  }
+  return findings;
+}
+function checkBoundaryIntent(intent, codeByBoundary, deploymentOfUnit) {
   const key = pairingKey(intent.boundary);
   if (key === null) {
     return {
@@ -36,9 +91,9 @@ function checkBoundaryIntent(intent, codeByBoundary) {
         {
           kind: "unkeyableBoundary",
           severity: "warning",
-          boundary: unkeyedBoundaryLabel(intent.boundary),
+          boundary: displayLabel(intent.boundary),
           intent: { name: intent.name },
-          message: `Intent "${intent.name}" has a ${intent.boundary.semantics.name} boundary that can't be keyed for pairing (function-call boundaries need package + exportPath); it was not checked against code.`
+          message: `Intent "${intent.name}" has a ${intent.boundary.semantics.name} boundary that can't be keyed for pairing (${whatWouldKeyIt(intent.boundary.semantics.name)}); it was not checked against code.`
         }
       ],
       checked: [],
@@ -81,7 +136,9 @@ function checkBoundaryIntent(intent, codeByBoundary) {
   }
   const findings = [];
   for (const impl of impls) {
-    findings.push(...compareIntentToImpl(intent, impl, label));
+    findings.push(
+      ...compareIntentToImpl(intent, impl, label, deploymentOfUnit(impl))
+    );
   }
   return {
     findings,
@@ -241,10 +298,13 @@ function applyIntentSuppressions(findings, rules, opts = {}) {
 }
 function indexCodeByBoundary(code) {
   const byKey = /* @__PURE__ */ new Map();
-  for (const summary of code) {
+  for (const summary of withDeclaredDelivery(code)) {
     if (BOUNDARY_ROLE[summary.kind] !== "provider") {
       continue;
     }
+    if (summary.confidence.source === "declared") {
+      continue;
+    }
     const binding = summary.identity.boundaryBinding;
     if (binding === null) {
       continue;
@@ -262,13 +322,34 @@ function indexCodeByBoundary(code) {
   }
   return byKey;
 }
-function compareIntentToImpl(intent, impl, boundary) {
+function compareIntentToImpl(intent, impl, boundary, deployment) {
   const findings = [];
   const ref = codeRef(impl);
-  const codeOutcomes = impl.transitions.map(toCodeOutcome).filter((o) => o !== null);
+  const calls = boundaryCalls(impl);
+  const codeOutcomes = impl.transitions.map((t) => toCodeOutcome(t, calls, deployment)).filter((o) => o !== null);
+  const everyEffect = impl.transitions.flatMap(
+    (t) => codeEffectsOf(t, deployment)
+  );
   for (const outcome of intent.outcomes) {
-    const matches = codeOutcomes.filter((co) => outcomeMatches(outcome, co));
-    if (matches.length === 0) {
+    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))) {
+        continue;
+      }
+      findings.push({
+        kind: "uncoveredOutcome",
+        severity: "error",
+        boundary,
+        intent: { name: intent.name, outcomeId: outcome.id },
+        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)}`
+      });
+    }
+    if (outcome.kind === "effect") {
+      continue;
+    }
+    const ending = codeOutcomes.filter((co) => outcomeMatches(outcome, co));
+    if (ending.length === 0) {
       findings.push({
         kind: "uncoveredOutcome",
         severity: "error",
@@ -279,6 +360,26 @@ function compareIntentToImpl(intent, impl, boundary) {
       });
       continue;
     }
+    const stated = outcome.conditions.filter(
+      (c) => c.at !== null
+    );
+    const matches = stated.length === 0 ? ending : ending.filter(
+      (co) => stated.every((c) => conditionMet(c, co.turnsOn))
+    );
+    if (matches.length === 0) {
+      const unmet = stated.find(
+        (c) => !ending.some((co) => conditionMet(c, co.turnsOn))
+      );
+      findings.push({
+        kind: "uncoveredOutcome",
+        severity: "error",
+        boundary,
+        intent: { name: intent.name, outcomeId: outcome.id },
+        code: ref,
+        message: `Intent "${intent.name}" declares ${describeOutcome(outcome)} at ${boundary} when ${unmet?.said ?? outcome.when}; ${impl.identity.name} produces it on a different condition.`
+      });
+      continue;
+    }
     const declaredBody = outcome.body;
     if (declaredBody === null) {
       continue;
@@ -322,17 +423,70 @@ function compareIntentToImpl(intent, impl, boundary) {
       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 said = /* @__PURE__ */ new Set();
+  for (const made of everyEffect) {
+    const spelled = `${made.does} ${made.label}`;
+    if (said.has(spelled) || declaredEffects.some((effect) => effectMatches(effect, made))) {
+      continue;
+    }
+    said.add(spelled);
+    findings.push({
+      kind: "undeclaredOutcome",
+      severity: "info",
+      boundary,
+      intent: { name: intent.name },
+      code: ref,
+      message: `${impl.identity.name} ${spelled} at ${boundary}; intent "${intent.name}" does not declare it.`
+    });
+  }
   return findings;
 }
-function toCodeOutcome(t) {
+function unsettledNote(reached, declared, deployment) {
+  const variables = /* @__PURE__ */ new Set();
+  for (const made of reached) {
+    const reference = nameReference(made.binding);
+    const variable = reference === null ? null : deployment.variableFor(reference);
+    if (made.does === declared.does && variable !== null) {
+      variables.add(variable);
+    }
+  }
+  if (variables.size === 0) {
+    return "";
+  }
+  const named = [...variables].sort().join(", ");
+  return ` The code says which one through ${named}, and nothing in this run says what that is set to. Read the deployment that sets it in and check again.`;
+}
+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 statesAll(declared, made) {
+  if (declared.length === 0 || made.length === 0 || made.includes(EVERY_FIELD)) {
+    return true;
+  }
+  return declared.every((one) => made.includes(one));
+}
+function conditionMet(declared, turnsOn) {
+  return turnsOn.some(
+    (guard) => guard.does === declared.at.does && namesBoundary(declared.at.names, guard.binding) && (declared.finds === null || declared.finds === guard.polarity)
+  );
+}
+function toCodeOutcome(t, calls, deployment) {
   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,
       body: output.body ?? null,
-      errorType: null
+      errorType: null,
+      effects,
+      turnsOn
     };
   }
   if (output.type === "return") {
@@ -340,7 +494,9 @@ function toCodeOutcome(t) {
       kind: "return",
       status: null,
       body: output.value,
-      errorType: null
+      errorType: null,
+      effects,
+      turnsOn
     };
   }
   if (output.type === "throw") {
@@ -348,11 +504,40 @@ function toCodeOutcome(t) {
       kind: "throw",
       status: null,
       body: null,
-      errorType: output.exceptionType
+      errorType: output.exceptionType,
+      effects,
+      turnsOn
     };
   }
   return null;
 }
+function codeEffectsOf(t, deployment) {
+  const reached = [];
+  for (const effect of t.effects) {
+    if (effect.type !== "interaction") {
+      continue;
+    }
+    if (goesThroughRelation(effect.interaction)) {
+      continue;
+    }
+    const binding = groundBinding(effect.binding, deployment);
+    const label = displayLabel(binding);
+    const touched = accessDetail(effect.interaction);
+    for (const does of relationsOf(effect.interaction)) {
+      reached.push({ does, binding, label, ...touched });
+    }
+  }
+  return reached;
+}
+function accessDetail(interaction) {
+  if (interaction.class !== "storage-access") {
+    return { fields: [], by: [] };
+  }
+  return {
+    fields: interaction.fields,
+    by: interaction.selector ?? []
+  };
+}
 function outcomeMatches(intent, code) {
   if (intent.kind !== code.kind) {
     return false;
@@ -365,14 +550,20 @@ function outcomeMatches(intent, code) {
   }
   return true;
 }
-function unkeyedBoundaryLabel(binding) {
-  const semantics = binding.semantics;
-  if (semantics.name === "function-call") {
-    const target = semantics.module ?? semantics.package ?? "?";
-    return `fn:${target}::${semantics.exportName ?? "?"}`;
-  }
-  return semantics.name;
+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",
+  "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"
+};
 function describeOutcome(outcome) {
   if (outcome.kind === "response") {
     return `status ${outcome.status}`;
@@ -382,7 +573,20 @@ function describeOutcome(outcome) {
   }
   return "a return value";
 }
+function describeEffect(effect) {
+  const detail = [
+    effect.fields.length > 0 ? `of ${effect.fields.join(", ")}` : null,
+    effect.by.length > 0 ? `by ${effect.by.join(", ")}` : null
+  ].filter((part) => part !== null);
+  return [EFFECT_PHRASE[effect.does], effect.names, ...detail].join(" ");
+}
+var EFFECT_PHRASE = {
+  reads: "a read of",
+  writes: "a write to",
+  invokes: "an invoke of"
+};
 export {
   applyIntentSuppressions,
-  checkIntentAgreement
+  checkIntentAgreement,
+  whatWouldKeyIt
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suss/checker-intent",
-  "version": "0.20.0",
+  "version": "0.21.1",
   "type": "module",
   "description": "Pair team-authored intent (IntentSummary) against derived code (BehavioralSummary) and report where they diverge.",
   "keywords": [
@@ -47,9 +47,9 @@
     "zod": "^4.0.0"
   },
   "dependencies": {
-    "@suss/behavioral-ir": "0.20.0",
-    "@suss/intent-ir": "0.20.0",
-    "@suss/ir-core": "0.20.0"
+    "@suss/behavioral-ir": "0.21.1",
+    "@suss/intent-ir": "0.21.1",
+    "@suss/ir-core": "0.21.1"
   },
   "devDependencies": {
     "tsup": "*",