@suss/checker-intent 0.0.1

package/LICENSE

@@ -0,0 +1,205 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable by
+      such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and do not
+          modify the License. You may add Your own attribution notices
+          within Derivative Works that You distribute, alongside or as an
+          addendum to the NOTICE text from the Work, provided that such
+          additional attribution notices cannot be construed as modifying
+          the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor has
+      been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format please. Also add information on
+      how to contact you by electronic and paper mail.
+
+      If the program does not interact with users remotely through a computer
+      network, then your name and employer's name (e.g., your institution)
+      is sufficient to fill in the "name of copyright owner" field. Feel
+      free to omit the "name of employer" line if you are in no way affiliated
+      with any institution.
+
+      Copyright 2026 Nimbus Cloud AI LLC
+
+      Licensed under the Apache License, Version 2.0 (the "License");
+      you may not use this file except in compliance with the License.
+      You may obtain a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+      See the License for the specific language governing permissions and
+      limitations under the License.

package/README.md

@@ -0,0 +1,47 @@
+# @suss/checker-intent
+
+Pair team-authored intent against derived code and report where the code
+fails to satisfy what the team declared.
+
+## What this package is
+
+The intent half of suss's checking, separate from `@suss/checker` (the
+behavioural peer checker) by design. The inputs differ — `IntentSummary`
+(from `@suss/contract-intent`) on one side, `BehavioralSummary` on the
+other — and so does the output: an `IntentFinding` is one-sided coverage
+("the team declared X; does the code do it?"), not a symmetric
+provider↔consumer mismatch.
+
+```ts
+import { checkIntentAgreement } from "@suss/checker-intent";
+
+const findings = checkIntentAgreement(intentSummaries, codeSummaries);
+```
+
+For each boundary intent, it pairs against the code summaries sharing 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.
+- `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).
+
+v0 checks system intent (`kind: boundary`). PRD outcome intent
+(`kind: prd`) — scenario / link coverage — is a separate pass.
+
+## Where it sits in suss
+
+Depends on `@suss/intent-ir` (intent shapes + `IntentFinding`),
+`@suss/behavioral-ir` (code summaries), and `@suss/ir-core` for the
+shared comparison primitives (`boundaryKey`, `bodyShapesMatch`) it must
+agree on with the behavioural checker. It does **not** depend on
+`@suss/checker`. The full design is in
+[`docs/internal/proposals/intent-specs.md`](../../docs/internal/proposals/intent-specs.md).
+
+## Coverage
+
+![coverage](../../.github/badges/coverage-checker-intent.svg)
+
+## License
+
+Apache-2.0

package/dist/index.cjs

@@ -0,0 +1,403 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  applyIntentSuppressions: () => applyIntentSuppressions,
+  checkIntentAgreement: () => checkIntentAgreement
+});
+module.exports = __toCommonJS(index_exports);
+var import_behavioral_ir = require("@suss/behavioral-ir");
+var import_ir_core = require("@suss/ir-core");
+function checkIntentAgreement(intents, code) {
+  const findings = [];
+  const checked = [];
+  const unchecked = [];
+  const codeByBoundary = indexCodeByBoundary(code);
+  const boundaryByName = indexBoundaryIntentsByName(intents);
+  for (const intent of intents) {
+    if (intent.kind === "prd") {
+      const result2 = checkPrdCoverage(intent, boundaryByName);
+      findings.push(...withProvenance(result2.findings, intent.source));
+      checked.push(result2.checked);
+      continue;
+    }
+    const result = checkBoundaryIntent(intent, codeByBoundary);
+    findings.push(...withProvenance(result.findings, intent.source));
+    checked.push(...result.checked);
+    unchecked.push(...result.unchecked);
+  }
+  return { findings, checked, unchecked };
+}
+function checkBoundaryIntent(intent, codeByBoundary) {
+  const key = (0, import_ir_core.boundaryKey)(intent.boundary);
+  if (key === null) {
+    return {
+      findings: [
+        {
+          kind: "unkeyableBoundary",
+          severity: "warning",
+          boundary: unkeyedBoundaryLabel(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.`
+        }
+      ],
+      checked: [],
+      unchecked: [
+        {
+          intent: intent.name,
+          reason: "unkeyable",
+          detail: "boundary can't be keyed for pairing against code"
+        }
+      ]
+    };
+  }
+  const impls = codeByBoundary.get(key) ?? [];
+  if (impls.length === 0) {
+    return {
+      findings: [
+        {
+          kind: "unimplementedBoundary",
+          severity: "error",
+          boundary: key,
+          intent: { name: intent.name },
+          message: `Intent "${intent.name}" declares boundary ${key} with ${intent.outcomes.length} outcome(s); no code produces this boundary.`
+        }
+      ],
+      // The comparison ran — finding no implementation IS the result.
+      checked: [
+        {
+          kind: "boundary",
+          intent: intent.name,
+          boundary: key,
+          implementations: []
+        }
+      ],
+      unchecked: []
+    };
+  }
+  const findings = [];
+  for (const impl of impls) {
+    findings.push(...compareIntentToImpl(intent, impl, key));
+  }
+  return {
+    findings,
+    checked: [
+      {
+        kind: "boundary",
+        intent: intent.name,
+        boundary: key,
+        implementations: impls.map(codeRef)
+      }
+    ],
+    unchecked: []
+  };
+}
+function codeRef(impl) {
+  return `${impl.location.file}::${impl.identity.name}`;
+}
+function checkPrdCoverage(prd, boundaryByName) {
+  const findings = [];
+  let resolved = 0;
+  let unlinked = 0;
+  prd.scenarios.forEach((scenario, index) => {
+    const label = scenarioLabel(scenario.title, index);
+    if (scenario.link.length === 0) {
+      unlinked += 1;
+      findings.push({
+        kind: "unlinkedScenario",
+        severity: "info",
+        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.`
+      });
+      return;
+    }
+    let allResolved = true;
+    for (const ref of scenario.link) {
+      const finding = resolveScenarioLink(
+        prd,
+        scenario.title,
+        label,
+        ref,
+        boundaryByName
+      );
+      if (finding !== null) {
+        findings.push(finding);
+        allResolved = false;
+      }
+    }
+    if (allResolved) {
+      resolved += 1;
+    }
+  });
+  return {
+    findings,
+    checked: {
+      kind: "prd",
+      intent: prd.title,
+      scenarios: prd.scenarios.length,
+      resolved,
+      unlinked
+    }
+  };
+}
+function resolveScenarioLink(prd, scenarioTitle, label, ref, boundaryByName) {
+  const dot = ref.indexOf(".");
+  const name = dot >= 0 ? ref.slice(0, dot) : ref;
+  const outcomeId = dot >= 0 ? ref.slice(dot + 1) : "";
+  const scenarioRef = {
+    ...scenarioTitle !== null ? { title: scenarioTitle } : {},
+    link: ref
+  };
+  const matches = boundaryByName.get(name) ?? [];
+  if (matches.length === 0) {
+    return {
+      kind: "danglingScenarioLink",
+      severity: "warning",
+      boundary: prdBoundaryLabel(prd),
+      intent: { name: prd.title },
+      scenario: scenarioRef,
+      message: `Scenario ${label} in PRD "${prd.title}" links to "${ref}", but no boundary intent named "${name}" is loaded.`
+    };
+  }
+  if (matches.length > 1) {
+    return {
+      kind: "ambiguousScenarioLink",
+      severity: "warning",
+      boundary: prdBoundaryLabel(prd),
+      intent: { name: prd.title },
+      scenario: scenarioRef,
+      message: `Scenario ${label} in PRD "${prd.title}" links to "${ref}", but ${matches.length} boundary intents are named "${name}"; rename them so the link resolves to one.`
+    };
+  }
+  const target = matches[0];
+  if (outcomeId === "" || !target.outcomes.some((o) => o.id === outcomeId)) {
+    const known = target.outcomes.map((o) => o.id).join(", ");
+    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.
+      boundary: (0, import_ir_core.boundaryKey)(target.boundary) ?? prdBoundaryLabel(prd),
+      intent: { name: prd.title },
+      scenario: scenarioRef,
+      message: `Scenario ${label} in PRD "${prd.title}" links to "${ref}", but boundary intent "${name}" declares no outcome "${outcomeId}" (known outcomes: ${known}).`
+    };
+  }
+  return null;
+}
+function scenarioLabel(title, index) {
+  return title !== null ? `"${title}"` : `#${index + 1}`;
+}
+function prdBoundaryLabel(prd) {
+  return `prd:${prd.title}`;
+}
+function indexBoundaryIntentsByName(intents) {
+  const byName = /* @__PURE__ */ new Map();
+  for (const intent of intents) {
+    if (intent.kind !== "boundary") {
+      continue;
+    }
+    const bucket = byName.get(intent.name);
+    if (bucket === void 0) {
+      byName.set(intent.name, [intent]);
+    } else {
+      bucket.push(intent);
+    }
+  }
+  return byName;
+}
+var SEVERITY_DOWNGRADE = {
+  error: "warning",
+  warning: "info",
+  info: "info"
+};
+function withProvenance(findings, source) {
+  if (source !== "inferred") {
+    return findings;
+  }
+  return findings.map((f) => ({
+    ...f,
+    severity: SEVERITY_DOWNGRADE[f.severity]
+  }));
+}
+function applyIntentSuppressions(findings, rules, opts = {}) {
+  return (0, import_ir_core.applySuppressionsToFindings)(
+    findings,
+    rules,
+    (rule, finding) => {
+      if (rule.consumer !== void 0) {
+        return false;
+      }
+      return rule.boundary === void 0 || (0, import_ir_core.ruleBoundaryMatchesKey)(rule.boundary, finding.boundary);
+    },
+    opts
+  );
+}
+function indexCodeByBoundary(code) {
+  const byKey = /* @__PURE__ */ new Map();
+  for (const summary of code) {
+    if (import_behavioral_ir.BOUNDARY_ROLE[summary.kind] !== "provider") {
+      continue;
+    }
+    const binding = summary.identity.boundaryBinding;
+    if (binding === null) {
+      continue;
+    }
+    const key = (0, import_ir_core.boundaryKey)(binding);
+    if (key === null) {
+      continue;
+    }
+    const bucket = byKey.get(key);
+    if (bucket === void 0) {
+      byKey.set(key, [summary]);
+    } else {
+      bucket.push(summary);
+    }
+  }
+  return byKey;
+}
+function compareIntentToImpl(intent, impl, boundary) {
+  const findings = [];
+  const ref = codeRef(impl);
+  const codeOutcomes = impl.transitions.map(toCodeOutcome).filter((o) => o !== null);
+  for (const outcome of intent.outcomes) {
+    const matches = codeOutcomes.filter((co) => outcomeMatches(outcome, co));
+    if (matches.length === 0) {
+      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}; ${impl.identity.name} has no transition that produces it.`
+      });
+      continue;
+    }
+    const declaredBody = outcome.body;
+    if (declaredBody === null) {
+      continue;
+    }
+    const bodied = matches.filter(
+      (m) => m.body !== null
+    );
+    if (bodied.length === 0) {
+      continue;
+    }
+    const verdicts = bodied.map((m) => (0, import_ir_core.bodyShapesMatch)(m.body, declaredBody));
+    if (verdicts.some((v) => v !== "nomatch")) {
+      continue;
+    }
+    findings.push({
+      kind: "outcomeShapeMismatch",
+      severity: "error",
+      boundary,
+      intent: { name: intent.name, outcomeId: outcome.id },
+      code: ref,
+      message: `Body shape for ${describeOutcome(outcome)} at ${boundary} disagrees with intent "${intent.name}": ${impl.identity.name} produces an incompatible shape.`
+    });
+  }
+  const declared = new Set(
+    intent.outcomes.filter((o) => o.kind === "response" && o.status !== null).map((o) => o.status)
+  );
+  const undeclaredStatuses = /* @__PURE__ */ new Set();
+  for (const co of codeOutcomes) {
+    if (co.kind !== "response" || co.status === null || declared.has(co.status)) {
+      continue;
+    }
+    undeclaredStatuses.add(co.status);
+  }
+  for (const status of undeclaredStatuses) {
+    findings.push({
+      kind: "undeclaredOutcome",
+      severity: "info",
+      boundary,
+      intent: { name: intent.name },
+      code: ref,
+      message: `${impl.identity.name} produces status ${status} at ${boundary}; intent "${intent.name}" does not declare it.`
+    });
+  }
+  return findings;
+}
+function toCodeOutcome(t) {
+  const output = t.output;
+  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
+    };
+  }
+  if (output.type === "return") {
+    return {
+      kind: "return",
+      status: null,
+      body: output.value,
+      errorType: null
+    };
+  }
+  if (output.type === "throw") {
+    return {
+      kind: "throw",
+      status: null,
+      body: null,
+      errorType: output.exceptionType
+    };
+  }
+  return null;
+}
+function outcomeMatches(intent, code) {
+  if (intent.kind !== code.kind) {
+    return false;
+  }
+  if (intent.kind === "response") {
+    return intent.status === code.status;
+  }
+  if (intent.kind === "throw") {
+    return intent.errorType === null || code.errorType === null || intent.errorType === code.errorType;
+  }
+  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 describeOutcome(outcome) {
+  if (outcome.kind === "response") {
+    return `status ${outcome.status}`;
+  }
+  if (outcome.kind === "throw") {
+    return outcome.errorType !== null ? `throw ${outcome.errorType}` : "a thrown error";
+  }
+  return "a return value";
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  applyIntentSuppressions,
+  checkIntentAgreement
+});

package/dist/index.d.cts

@@ -0,0 +1,85 @@
+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';
+
+/** A boundary intent that was paired and compared against code. */
+interface CheckedBoundaryIntent {
+    kind: "boundary";
+    /** The intent doc's `name`. */
+    intent: string;
+    /** The boundary key it paired on. */
+    boundary: string;
+    /** Implementations compared, as `${file}::${name}`. Empty when none. */
+    implementations: string[];
+}
+/** A PRD whose scenario links were resolved against the loaded system intents. */
+interface CheckedPrd {
+    kind: "prd";
+    /** The PRD doc's `title`. */
+    intent: string;
+    /** Total scenarios walked. */
+    scenarios: number;
+    /** Scenarios whose every link resolved to a declared outcome (had >=1 link). */
+    resolved: number;
+    /** Scenarios carrying no structured link (a valid pending state). */
+    unlinked: number;
+}
+/**
+ * A declared intent that was compared — either a boundary intent paired
+ * against code or a PRD whose scenario links were resolved. Discriminated
+ * on `kind` so callers render both without a parallel structure; when a
+ * third doc kind (workflow) ships it extends this union.
+ */
+type CheckedIntent = CheckedBoundaryIntent | CheckedPrd;
+/** An intent doc that was loaded but not compared, and why. */
+interface UncheckedIntent {
+    /** The intent doc's `name` (boundary) or `title` (prd). */
+    intent: string;
+    reason: "unkeyable";
+    /** Human-readable explanation, render-ready. */
+    detail: string;
+}
+/**
+ * The full result of an intent-agreement pass. Mirrors the behavioural
+ * checker's shape philosophy (`checkAll` → findings + pairs +
+ * unmatched): findings are what to fix; checked / unchecked are the
+ * coverage accounting — which declared intent was actually compared.
+ * Callers render or gate on this without knowing which doc kinds the
+ * checker compared — boundary intents and PRDs both land in `checked`
+ * (a discriminated union). `unchecked` is reserved for intent that
+ * couldn't be compared at all (an unkeyable boundary), never silently
+ * dropped.
+ */
+interface CheckIntentResult {
+    findings: IntentFinding[];
+    checked: CheckedIntent[];
+    unchecked: UncheckedIntent[];
+}
+/**
+ * Compare every loaded intent doc against what's known. Boundary intents
+ * pair against the code summaries sharing their boundary key; PRDs resolve
+ * each scenario's link against the loaded boundary intents (coverage). An
+ * intent that can't be compared (an unkeyable boundary) is reported in
+ * `unchecked`, never silently dropped.
+ *
+ * Findings against `source: "inferred"` intent are downgraded one severity
+ * level — the intent describes what the code did when the inference ran, so
+ * a divergence is most likely a code change since, not an authoring error.
+ * Curation (`"inferred, curated"`) restores full severity.
+ */
+declare function checkIntentAgreement(intents: IntentSummary[], code: BehavioralSummary[]): CheckIntentResult;
+/**
+ * Apply .sussignore rules to intent findings, using the shared
+ * pipeline from @suss/ir-core (same rule shape and semantics as the
+ * behavioural checker's `applySuppressions`). Rule discriminators map
+ * as: `kind` → the intent finding kind; `boundary` → the finding's
+ * boundary key (exact for `fn:` / `gql:` keys, path-normalized for
+ * REST). A rule that specifies `consumer` never matches an intent
+ * finding — there is no consumer side.
+ */
+declare function applyIntentSuppressions(findings: IntentFinding[], rules: SuppressionRule[], opts?: {
+    keepHidden?: boolean;
+}): IntentFinding[];
+
+export { type CheckIntentResult, type CheckedBoundaryIntent, type CheckedIntent, type CheckedPrd, type UncheckedIntent, applyIntentSuppressions, checkIntentAgreement };

package/dist/index.d.ts

@@ -0,0 +1,85 @@
+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';
+
+/** A boundary intent that was paired and compared against code. */
+interface CheckedBoundaryIntent {
+    kind: "boundary";
+    /** The intent doc's `name`. */
+    intent: string;
+    /** The boundary key it paired on. */
+    boundary: string;
+    /** Implementations compared, as `${file}::${name}`. Empty when none. */
+    implementations: string[];
+}
+/** A PRD whose scenario links were resolved against the loaded system intents. */
+interface CheckedPrd {
+    kind: "prd";
+    /** The PRD doc's `title`. */
+    intent: string;
+    /** Total scenarios walked. */
+    scenarios: number;
+    /** Scenarios whose every link resolved to a declared outcome (had >=1 link). */
+    resolved: number;
+    /** Scenarios carrying no structured link (a valid pending state). */
+    unlinked: number;
+}
+/**
+ * A declared intent that was compared — either a boundary intent paired
+ * against code or a PRD whose scenario links were resolved. Discriminated
+ * on `kind` so callers render both without a parallel structure; when a
+ * third doc kind (workflow) ships it extends this union.
+ */
+type CheckedIntent = CheckedBoundaryIntent | CheckedPrd;
+/** An intent doc that was loaded but not compared, and why. */
+interface UncheckedIntent {
+    /** The intent doc's `name` (boundary) or `title` (prd). */
+    intent: string;
+    reason: "unkeyable";
+    /** Human-readable explanation, render-ready. */
+    detail: string;
+}
+/**
+ * The full result of an intent-agreement pass. Mirrors the behavioural
+ * checker's shape philosophy (`checkAll` → findings + pairs +
+ * unmatched): findings are what to fix; checked / unchecked are the
+ * coverage accounting — which declared intent was actually compared.
+ * Callers render or gate on this without knowing which doc kinds the
+ * checker compared — boundary intents and PRDs both land in `checked`
+ * (a discriminated union). `unchecked` is reserved for intent that
+ * couldn't be compared at all (an unkeyable boundary), never silently
+ * dropped.
+ */
+interface CheckIntentResult {
+    findings: IntentFinding[];
+    checked: CheckedIntent[];
+    unchecked: UncheckedIntent[];
+}
+/**
+ * Compare every loaded intent doc against what's known. Boundary intents
+ * pair against the code summaries sharing their boundary key; PRDs resolve
+ * each scenario's link against the loaded boundary intents (coverage). An
+ * intent that can't be compared (an unkeyable boundary) is reported in
+ * `unchecked`, never silently dropped.
+ *
+ * Findings against `source: "inferred"` intent are downgraded one severity
+ * level — the intent describes what the code did when the inference ran, so
+ * a divergence is most likely a code change since, not an authoring error.
+ * Curation (`"inferred, curated"`) restores full severity.
+ */
+declare function checkIntentAgreement(intents: IntentSummary[], code: BehavioralSummary[]): CheckIntentResult;
+/**
+ * Apply .sussignore rules to intent findings, using the shared
+ * pipeline from @suss/ir-core (same rule shape and semantics as the
+ * behavioural checker's `applySuppressions`). Rule discriminators map
+ * as: `kind` → the intent finding kind; `boundary` → the finding's
+ * boundary key (exact for `fn:` / `gql:` keys, path-normalized for
+ * REST). A rule that specifies `consumer` never matches an intent
+ * finding — there is no consumer side.
+ */
+declare function applyIntentSuppressions(findings: IntentFinding[], rules: SuppressionRule[], opts?: {
+    keepHidden?: boolean;
+}): IntentFinding[];
+
+export { type CheckIntentResult, type CheckedBoundaryIntent, type CheckedIntent, type CheckedPrd, type UncheckedIntent, applyIntentSuppressions, checkIntentAgreement };

package/dist/index.js

@@ -0,0 +1,382 @@
+// src/index.ts
+import { BOUNDARY_ROLE } from "@suss/behavioral-ir";
+import {
+  applySuppressionsToFindings,
+  bodyShapesMatch,
+  boundaryKey,
+  ruleBoundaryMatchesKey
+} from "@suss/ir-core";
+function checkIntentAgreement(intents, code) {
+  const findings = [];
+  const checked = [];
+  const unchecked = [];
+  const codeByBoundary = indexCodeByBoundary(code);
+  const boundaryByName = indexBoundaryIntentsByName(intents);
+  for (const intent of intents) {
+    if (intent.kind === "prd") {
+      const result2 = checkPrdCoverage(intent, boundaryByName);
+      findings.push(...withProvenance(result2.findings, intent.source));
+      checked.push(result2.checked);
+      continue;
+    }
+    const result = checkBoundaryIntent(intent, codeByBoundary);
+    findings.push(...withProvenance(result.findings, intent.source));
+    checked.push(...result.checked);
+    unchecked.push(...result.unchecked);
+  }
+  return { findings, checked, unchecked };
+}
+function checkBoundaryIntent(intent, codeByBoundary) {
+  const key = boundaryKey(intent.boundary);
+  if (key === null) {
+    return {
+      findings: [
+        {
+          kind: "unkeyableBoundary",
+          severity: "warning",
+          boundary: unkeyedBoundaryLabel(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.`
+        }
+      ],
+      checked: [],
+      unchecked: [
+        {
+          intent: intent.name,
+          reason: "unkeyable",
+          detail: "boundary can't be keyed for pairing against code"
+        }
+      ]
+    };
+  }
+  const impls = codeByBoundary.get(key) ?? [];
+  if (impls.length === 0) {
+    return {
+      findings: [
+        {
+          kind: "unimplementedBoundary",
+          severity: "error",
+          boundary: key,
+          intent: { name: intent.name },
+          message: `Intent "${intent.name}" declares boundary ${key} with ${intent.outcomes.length} outcome(s); no code produces this boundary.`
+        }
+      ],
+      // The comparison ran — finding no implementation IS the result.
+      checked: [
+        {
+          kind: "boundary",
+          intent: intent.name,
+          boundary: key,
+          implementations: []
+        }
+      ],
+      unchecked: []
+    };
+  }
+  const findings = [];
+  for (const impl of impls) {
+    findings.push(...compareIntentToImpl(intent, impl, key));
+  }
+  return {
+    findings,
+    checked: [
+      {
+        kind: "boundary",
+        intent: intent.name,
+        boundary: key,
+        implementations: impls.map(codeRef)
+      }
+    ],
+    unchecked: []
+  };
+}
+function codeRef(impl) {
+  return `${impl.location.file}::${impl.identity.name}`;
+}
+function checkPrdCoverage(prd, boundaryByName) {
+  const findings = [];
+  let resolved = 0;
+  let unlinked = 0;
+  prd.scenarios.forEach((scenario, index) => {
+    const label = scenarioLabel(scenario.title, index);
+    if (scenario.link.length === 0) {
+      unlinked += 1;
+      findings.push({
+        kind: "unlinkedScenario",
+        severity: "info",
+        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.`
+      });
+      return;
+    }
+    let allResolved = true;
+    for (const ref of scenario.link) {
+      const finding = resolveScenarioLink(
+        prd,
+        scenario.title,
+        label,
+        ref,
+        boundaryByName
+      );
+      if (finding !== null) {
+        findings.push(finding);
+        allResolved = false;
+      }
+    }
+    if (allResolved) {
+      resolved += 1;
+    }
+  });
+  return {
+    findings,
+    checked: {
+      kind: "prd",
+      intent: prd.title,
+      scenarios: prd.scenarios.length,
+      resolved,
+      unlinked
+    }
+  };
+}
+function resolveScenarioLink(prd, scenarioTitle, label, ref, boundaryByName) {
+  const dot = ref.indexOf(".");
+  const name = dot >= 0 ? ref.slice(0, dot) : ref;
+  const outcomeId = dot >= 0 ? ref.slice(dot + 1) : "";
+  const scenarioRef = {
+    ...scenarioTitle !== null ? { title: scenarioTitle } : {},
+    link: ref
+  };
+  const matches = boundaryByName.get(name) ?? [];
+  if (matches.length === 0) {
+    return {
+      kind: "danglingScenarioLink",
+      severity: "warning",
+      boundary: prdBoundaryLabel(prd),
+      intent: { name: prd.title },
+      scenario: scenarioRef,
+      message: `Scenario ${label} in PRD "${prd.title}" links to "${ref}", but no boundary intent named "${name}" is loaded.`
+    };
+  }
+  if (matches.length > 1) {
+    return {
+      kind: "ambiguousScenarioLink",
+      severity: "warning",
+      boundary: prdBoundaryLabel(prd),
+      intent: { name: prd.title },
+      scenario: scenarioRef,
+      message: `Scenario ${label} in PRD "${prd.title}" links to "${ref}", but ${matches.length} boundary intents are named "${name}"; rename them so the link resolves to one.`
+    };
+  }
+  const target = matches[0];
+  if (outcomeId === "" || !target.outcomes.some((o) => o.id === outcomeId)) {
+    const known = target.outcomes.map((o) => o.id).join(", ");
+    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.
+      boundary: boundaryKey(target.boundary) ?? prdBoundaryLabel(prd),
+      intent: { name: prd.title },
+      scenario: scenarioRef,
+      message: `Scenario ${label} in PRD "${prd.title}" links to "${ref}", but boundary intent "${name}" declares no outcome "${outcomeId}" (known outcomes: ${known}).`
+    };
+  }
+  return null;
+}
+function scenarioLabel(title, index) {
+  return title !== null ? `"${title}"` : `#${index + 1}`;
+}
+function prdBoundaryLabel(prd) {
+  return `prd:${prd.title}`;
+}
+function indexBoundaryIntentsByName(intents) {
+  const byName = /* @__PURE__ */ new Map();
+  for (const intent of intents) {
+    if (intent.kind !== "boundary") {
+      continue;
+    }
+    const bucket = byName.get(intent.name);
+    if (bucket === void 0) {
+      byName.set(intent.name, [intent]);
+    } else {
+      bucket.push(intent);
+    }
+  }
+  return byName;
+}
+var SEVERITY_DOWNGRADE = {
+  error: "warning",
+  warning: "info",
+  info: "info"
+};
+function withProvenance(findings, source) {
+  if (source !== "inferred") {
+    return findings;
+  }
+  return findings.map((f) => ({
+    ...f,
+    severity: SEVERITY_DOWNGRADE[f.severity]
+  }));
+}
+function applyIntentSuppressions(findings, rules, opts = {}) {
+  return applySuppressionsToFindings(
+    findings,
+    rules,
+    (rule, finding) => {
+      if (rule.consumer !== void 0) {
+        return false;
+      }
+      return rule.boundary === void 0 || ruleBoundaryMatchesKey(rule.boundary, finding.boundary);
+    },
+    opts
+  );
+}
+function indexCodeByBoundary(code) {
+  const byKey = /* @__PURE__ */ new Map();
+  for (const summary of code) {
+    if (BOUNDARY_ROLE[summary.kind] !== "provider") {
+      continue;
+    }
+    const binding = summary.identity.boundaryBinding;
+    if (binding === null) {
+      continue;
+    }
+    const key = boundaryKey(binding);
+    if (key === null) {
+      continue;
+    }
+    const bucket = byKey.get(key);
+    if (bucket === void 0) {
+      byKey.set(key, [summary]);
+    } else {
+      bucket.push(summary);
+    }
+  }
+  return byKey;
+}
+function compareIntentToImpl(intent, impl, boundary) {
+  const findings = [];
+  const ref = codeRef(impl);
+  const codeOutcomes = impl.transitions.map(toCodeOutcome).filter((o) => o !== null);
+  for (const outcome of intent.outcomes) {
+    const matches = codeOutcomes.filter((co) => outcomeMatches(outcome, co));
+    if (matches.length === 0) {
+      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}; ${impl.identity.name} has no transition that produces it.`
+      });
+      continue;
+    }
+    const declaredBody = outcome.body;
+    if (declaredBody === null) {
+      continue;
+    }
+    const bodied = matches.filter(
+      (m) => m.body !== null
+    );
+    if (bodied.length === 0) {
+      continue;
+    }
+    const verdicts = bodied.map((m) => bodyShapesMatch(m.body, declaredBody));
+    if (verdicts.some((v) => v !== "nomatch")) {
+      continue;
+    }
+    findings.push({
+      kind: "outcomeShapeMismatch",
+      severity: "error",
+      boundary,
+      intent: { name: intent.name, outcomeId: outcome.id },
+      code: ref,
+      message: `Body shape for ${describeOutcome(outcome)} at ${boundary} disagrees with intent "${intent.name}": ${impl.identity.name} produces an incompatible shape.`
+    });
+  }
+  const declared = new Set(
+    intent.outcomes.filter((o) => o.kind === "response" && o.status !== null).map((o) => o.status)
+  );
+  const undeclaredStatuses = /* @__PURE__ */ new Set();
+  for (const co of codeOutcomes) {
+    if (co.kind !== "response" || co.status === null || declared.has(co.status)) {
+      continue;
+    }
+    undeclaredStatuses.add(co.status);
+  }
+  for (const status of undeclaredStatuses) {
+    findings.push({
+      kind: "undeclaredOutcome",
+      severity: "info",
+      boundary,
+      intent: { name: intent.name },
+      code: ref,
+      message: `${impl.identity.name} produces status ${status} at ${boundary}; intent "${intent.name}" does not declare it.`
+    });
+  }
+  return findings;
+}
+function toCodeOutcome(t) {
+  const output = t.output;
+  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
+    };
+  }
+  if (output.type === "return") {
+    return {
+      kind: "return",
+      status: null,
+      body: output.value,
+      errorType: null
+    };
+  }
+  if (output.type === "throw") {
+    return {
+      kind: "throw",
+      status: null,
+      body: null,
+      errorType: output.exceptionType
+    };
+  }
+  return null;
+}
+function outcomeMatches(intent, code) {
+  if (intent.kind !== code.kind) {
+    return false;
+  }
+  if (intent.kind === "response") {
+    return intent.status === code.status;
+  }
+  if (intent.kind === "throw") {
+    return intent.errorType === null || code.errorType === null || intent.errorType === code.errorType;
+  }
+  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 describeOutcome(outcome) {
+  if (outcome.kind === "response") {
+    return `status ${outcome.status}`;
+  }
+  if (outcome.kind === "throw") {
+    return outcome.errorType !== null ? `throw ${outcome.errorType}` : "a thrown error";
+  }
+  return "a return value";
+}
+export {
+  applyIntentSuppressions,
+  checkIntentAgreement
+};

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@suss/checker-intent",
+  "version": "0.0.1",
+  "type": "module",
+  "description": "Pair team-authored intent (IntentSummary) against derived code (BehavioralSummary) and report where they diverge.",
+  "keywords": [
+    "suss",
+    "intent",
+    "checker",
+    "coverage"
+  ],
+  "license": "Apache-2.0",
+  "author": "Nimbus Cloud AI LLC",
+  "homepage": "https://github.com/nimbuscloud-ai/suss/tree/main/packages/checker-intent#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nimbuscloud-ai/suss.git",
+    "directory": "packages/checker-intent"
+  },
+  "bugs": {
+    "url": "https://github.com/nimbuscloud-ai/suss/issues"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "zod": "^4.0.0"
+  },
+  "dependencies": {
+    "@suss/behavioral-ir": "0.0.1",
+    "@suss/intent-ir": "0.0.1",
+    "@suss/ir-core": "0.0.1"
+  },
+  "devDependencies": {
+    "tsup": "*",
+    "typescript": "*",
+    "vitest": "*",
+    "zod": "^4.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}