@suss/intent-ir 0.33.0 → 0.34.0

package/dist/index.js

@@ -1,95 +1,45 @@
-// src/findings.ts
-import { z } from "zod";
-var IntentFindingKindSchema = z.enum([
-  // System intent (kind: boundary) vs code:
-  "uncoveredOutcome",
-  // intent declares an outcome the code never produces
-  "unimplementedBoundary",
-  // intent boundary has no implementing code at all
-  "outcomeShapeMismatch",
-  // a matched outcome whose body shapes disagree
-  "undeclaredOutcome",
-  // code produces a REST status the intent doesn't declare
-  "unkeyableBoundary",
-  // intent boundary can't be keyed, so it can't be checked
-  "renamedBoundary",
-  // a declared store vanished and an undeclared one of the same system appeared with the same outcomes
-  // What the boundary is handed: the `receives` block against the paths
-  // the unit reads off its input.
-  "unreadInputField",
-  // intent declares a field no transition of the unit reads
-  "undeclaredInputRead",
-  // the unit reads a path the receives block does not list
-  // Outcome intent (kind: prd), scenario link coverage against system
-  // intent. These concretise the proposal's "scenario not linked /
-  // dangling / ambiguous" set (design/proposals/intent-specs.md);
-  // the proposal deferred concrete names to implementation time.
-  "unlinkedScenario",
-  // scenario carries no structured link (info — a valid pending state)
-  "danglingScenarioLink",
-  // link names an intent / outcome no boundary intent declares
-  "ambiguousScenarioLink",
-  // link resolves to two or more boundary intents sharing the name
-  // The same coverage question asked the other way: which declared
-  // behaviour has nobody written a reason for.
-  "undescribedOutcome"
-  // a declared outcome no PRD scenario links to (info)
-]);
-var IntentFindingSeveritySchema = z.enum(["error", "warning", "info"]);
-var IntentRefSchema = z.object({
-  /** The intent doc's `name` (boundary) or `title` (prd). */
-  name: z.string(),
-  /** The declared outcome id, when the finding is outcome-specific. */
-  outcomeId: z.string().optional()
-});
-var IntentFindingSuppressionSchema = z.object({
-  /** The rule's human-written justification. */
-  reason: z.string(),
-  effect: z.enum(["mark", "downgrade", "hide"]),
-  /** Original severity, present only when effect is "downgrade". */
-  originalSeverity: IntentFindingSeveritySchema.optional()
-});
-var IntentFindingSchema = z.object({
-  kind: IntentFindingKindSchema,
-  severity: IntentFindingSeveritySchema,
-  /**
-   * Human-readable boundary label: e.g. `GET /users/:id` or
-   * `fn:@suss/cli::contract`. The key the intent and code were paired on.
-   */
-  boundary: z.string(),
-  /** The intent side of the finding. */
-  intent: IntentRefSchema,
-  /**
-   * The matched code summary as `${file}::${name}`, when the finding
-   * concerns a specific implementation. Absent for unimplementedBoundary.
-   */
-  code: z.string().optional(),
-  /**
-   * PRD-scenario extension: present only on outcome-intent findings
-   * (unlinkedScenario / danglingScenarioLink / ambiguousScenarioLink).
-   * Identifies the scenario (by its optional title) and the qualified
-   * outcome ref (`<intent-name>.<outcome-id>`) that failed to resolve.
-   * The peer / boundary findings leave it unset. This is the "intent
-   * finding extension" decision 2 of the proposal anticipated.
-   */
-  scenario: z.object({
-    title: z.string().optional(),
-    link: z.string().optional()
-  }).optional(),
-  message: z.string(),
-  /** Present when a .sussignore rule matched this finding. */
-  suppressed: IntentFindingSuppressionSchema.optional()
-});
+// src/changeList.ts
+import { z as z2 } from "zod";
 
 // src/schema.ts
-import { z as z2 } from "zod";
+import { z } from "zod";
 import {
   EffectRelationSchema,
   MessageBusSemanticsSchema,
   StorageSemanticsSchema,
   UnitInvocationSemanticsSchema
 } from "@suss/ir-core";
-var IntentSourceSchema = z2.enum(["author", "inferred", "inferred, curated"]).default("author").describe(
+
+// src/coveringTest.ts
+import { TEST_TITLE_SEPARATOR } from "@suss/ir-core";
+var NODE_ID_SEPARATOR = "::";
+function toCoveringTest(spelledAs) {
+  if (!spelledAs.includes(TEST_TITLE_SEPARATOR)) {
+    return nodeIdSpelling(spelledAs);
+  }
+  const [file, ...titles] = spelledAs.split(TEST_TITLE_SEPARATOR);
+  return { spelledAs, file: file.trim(), titles };
+}
+function nodeIdSpelling(spelledAs) {
+  const parts = spelledAs.trim().split(NODE_ID_SEPARATOR);
+  const last = parts.length - 1;
+  parts[last] = parts[last].replace(/\[.*\]$/, "");
+  let fileAt = last;
+  while (fileAt >= 0 && !/[./]/.test(parts[fileAt])) {
+    fileAt -= 1;
+  }
+  if (fileAt < 0) {
+    return { spelledAs, file: spelledAs.trim(), titles: [] };
+  }
+  return {
+    spelledAs,
+    file: parts.slice(0, fileAt + 1).join(NODE_ID_SEPARATOR),
+    titles: parts.slice(fileAt + 1)
+  };
+}
+
+// src/schema.ts
+var IntentSourceSchema = z.enum(["author", "inferred", "inferred, curated"]).default("author").describe(
   "Where the document came from: somebody wrote it, suss inferred it, or suss inferred it and somebody has since curated it."
 );
 var UNCURATED_SOURCE = "inferred";
@@ -125,7 +75,7 @@ function fillBlanks(doc, blanks) {
   }));
   return filled;
 }
-var PrimitiveTypeName = z2.enum([
+var PrimitiveTypeName = z.enum([
   "string",
   "integer",
   "number",
@@ -133,76 +83,83 @@ var PrimitiveTypeName = z2.enum([
   "null",
   "unknown"
 ]);
-var ShapeSchema = z2.lazy(
-  () => z2.union([
-    z2.object({ type: PrimitiveTypeName }),
-    z2.object({ type: z2.literal("array"), items: ShapeSchema.optional() }),
-    z2.object({
-      type: z2.literal("object"),
-      properties: z2.record(z2.string(), ShapeSchema).optional(),
-      required: z2.array(z2.string()).optional()
+var ShapeSchema = z.lazy(
+  () => z.union([
+    z.object({ type: PrimitiveTypeName }),
+    z.object({ type: z.literal("array"), items: ShapeSchema.optional() }),
+    z.object({
+      type: z.literal("object"),
+      properties: z.record(z.string(), ShapeSchema).optional(),
+      required: z.array(z.string()).optional()
+    }),
+    z.strictObject({
+      const: z.union([z.string(), z.number(), z.boolean(), z.null()])
+    }),
+    z.strictObject({
+      properties: z.record(z.string(), ShapeSchema),
+      required: z.array(z.string()).optional()
     })
   ])
 );
-var BodyShapeSchema = z2.union([
+var BodyShapeSchema = z.union([
   ShapeSchema,
-  z2.object({
-    properties: z2.record(z2.string(), ShapeSchema).optional(),
-    required: z2.array(z2.string()).optional()
+  z.object({
+    properties: z.record(z.string(), ShapeSchema).optional(),
+    required: z.array(z.string()).optional()
   })
 ]);
 var REQUIRED = {
-  required: z2.boolean().default(false).describe("Whether the boundary needs this field.")
+  required: z.boolean().default(false).describe("Whether the boundary needs this field.")
 };
-var InputFieldSchema = z2.union([
-  z2.strictObject({ ...REQUIRED, type: PrimitiveTypeName }),
-  z2.strictObject({
+var InputFieldSchema = z.union([
+  z.strictObject({ ...REQUIRED, type: PrimitiveTypeName }),
+  z.strictObject({
     ...REQUIRED,
-    type: z2.literal("array"),
+    type: z.literal("array"),
     items: ShapeSchema.optional()
   }),
-  z2.strictObject({
+  z.strictObject({
     ...REQUIRED,
-    type: z2.literal("object"),
-    properties: z2.record(z2.string(), ShapeSchema).optional()
+    type: z.literal("object"),
+    properties: z.record(z.string(), ShapeSchema).optional()
   }),
-  z2.strictObject(REQUIRED)
+  z.strictObject(REQUIRED)
 ]);
-var ReceivesSchema = z2.record(z2.string().min(1), InputFieldSchema).describe(
+var ReceivesSchema = z.record(z.string().min(1), InputFieldSchema).describe(
   "The fields the boundary is handed, by field name. On a function-call boundary a name is a parameter, on a message bus it is a field of the message body."
 ).optional();
-var RestReceivesSchema = z2.strictObject({
-  headers: z2.record(z2.string().min(1), InputFieldSchema).describe("The request headers the boundary depends on, by name.").optional(),
-  query: z2.record(z2.string().min(1), InputFieldSchema).describe("The query-string parameters the boundary depends on, by name.").optional(),
-  params: z2.record(z2.string().min(1), InputFieldSchema).describe("The path parameters the boundary depends on, by name.").optional(),
+var RestReceivesSchema = z.strictObject({
+  headers: z.record(z.string().min(1), InputFieldSchema).describe("The request headers the boundary depends on, by name.").optional(),
+  query: z.record(z.string().min(1), InputFieldSchema).describe("The query-string parameters the boundary depends on, by name.").optional(),
+  params: z.record(z.string().min(1), InputFieldSchema).describe("The path parameters the boundary depends on, by name.").optional(),
   body: BodyShapeSchema.describe(
     "The shape of the request body the boundary depends on."
   ).optional()
 }).describe("The parts of the request the boundary depends on.").optional();
-var RestBoundarySchema = z2.strictObject({
-  transport: z2.literal("http").default("http"),
-  semantics: z2.literal("rest"),
-  method: z2.string().min(1).describe("The HTTP method the route handles."),
-  path: z2.string().min(1).describe("The route path, written the way the framework declares it."),
+var RestBoundarySchema = z.strictObject({
+  transport: z.literal("http").default("http"),
+  semantics: z.literal("rest"),
+  method: z.string().min(1).describe("The HTTP method the route handles."),
+  path: z.string().min(1).describe("The route path, written the way the framework declares it."),
   receives: RestReceivesSchema
 });
-var FunctionCallBoundarySchema = z2.strictObject({
-  transport: z2.string().default("in-process"),
-  semantics: z2.literal("function-call"),
-  module: z2.string().describe(
+var FunctionCallBoundarySchema = z.strictObject({
+  transport: z.string().default("in-process"),
+  semantics: z.literal("function-call"),
+  module: z.string().describe(
     "The repo-relative module path, when the boundary is a unit inside this repository."
   ).optional(),
-  exportName: z2.string().describe("The name the module or package exports the function under.").optional(),
-  package: z2.string().describe(
+  exportName: z.string().describe("The name the module or package exports the function under.").optional(),
+  package: z.string().describe(
     "The package name, when the boundary is something a package publishes."
   ).optional(),
-  exportPath: z2.array(z2.string()).describe(
+  exportPath: z.array(z.string()).describe(
     "The path to the export inside the package: the sub-path, then any nested names."
   ).optional(),
   receives: ReceivesSchema
 });
-var MessageBusBoundarySchema = z2.strictObject({
-  semantics: z2.literal("message-bus"),
+var MessageBusBoundarySchema = z.strictObject({
+  semantics: z.literal("message-bus"),
   messageBus: MessageBusSemanticsSchema.shape.messageBus.describe(
     "Which bus carries the message, in the name suss gives that bus."
   ),
@@ -211,8 +168,8 @@ var MessageBusBoundarySchema = z2.strictObject({
   ),
   receives: ReceivesSchema
 });
-var StorageBoundarySchema = z2.strictObject({
-  semantics: z2.literal("storage"),
+var StorageBoundarySchema = z.strictObject({
+  semantics: z.literal("storage"),
   storageSystem: StorageSemanticsSchema.shape.storageSystem.default(null).describe(
     "Which store this is: postgresql, aws.dynamodb, s3, and so on. Null when the document does not say which engine."
   ),
@@ -227,8 +184,8 @@ var StorageBoundarySchema = z2.strictObject({
   ),
   receives: ReceivesSchema
 });
-var UnitInvocationBoundarySchema = z2.strictObject({
-  semantics: z2.literal("unit-invocation"),
+var UnitInvocationBoundarySchema = z.strictObject({
+  semantics: z.literal("unit-invocation"),
   deploymentTarget: UnitInvocationSemanticsSchema.shape.deploymentTarget.describe(
     "What sort of deployed thing this is: a Lambda function, an ECS task's container, a plain container, a k8s deployment or an edge worker."
   ),
@@ -237,57 +194,80 @@ var UnitInvocationBoundarySchema = z2.strictObject({
   ),
   receives: ReceivesSchema
 });
-var BoundarySchema = z2.discriminatedUnion("semantics", [
+var BoundarySchema = z.discriminatedUnion("semantics", [
   RestBoundarySchema,
   FunctionCallBoundarySchema,
   MessageBusBoundarySchema,
   StorageBoundarySchema,
   UnitInvocationBoundarySchema
 ]);
-var ResponseOutcomeSchema = z2.object({
-  status: z2.number().int().min(100).max(599).describe("The HTTP status code the response carries."),
+var ResponseOutcomeSchema = z.object({
+  status: z.number().int().min(100).max(599).describe("The HTTP status code the response carries."),
   body: BodyShapeSchema.describe("The shape of the response body.").optional()
 });
-var ReturnsOutcomeSchema = z2.object({
+var ReturnsOutcomeSchema = z.object({
   body: BodyShapeSchema.describe("The shape of the returned value.").optional()
 });
-var ThrowsOutcomeSchema = z2.object({
-  errorType: z2.string().describe("The name of the error class this outcome raises.").optional()
+var ThrowsOutcomeSchema = z.object({
+  errorType: z.string().describe("The name of the error class this outcome raises.").optional()
 });
 function emptyIfNull(schema) {
-  return z2.preprocess((v) => v === null ? {} : v, schema).meta({ [ACCEPTS_NULL]: true });
+  return z.preprocess((v) => v === null ? {} : v, schema).meta({ [ACCEPTS_NULL]: true });
 }
 var ACCEPTS_NULL = "x-suss-accepts-null";
-var ONE_OR_MORE = z2.union([
-  z2.string().min(1),
-  z2.array(z2.string().min(1)).min(1)
+var INPUT_SOURCE_PREFIX = "input.";
+var SourcesSchema = z.record(
+  z.string().min(1),
+  z.string().regex(/^input\.[^.]+(\.[^.]+)*$/, {
+    message: "a source is written input.<path>, such as input.headers.x-tenant-id or input.body.email"
+  })
+).describe(
+  "Where the value of a column the line lists under fields or by comes from, keyed by the column: input.<path>, spelled the way receives spells it."
+);
+var ONE_OR_MORE = z.union([
+  z.string().min(1),
+  z.array(z.string().min(1)).min(1)
 ]);
-var EFFECT_BY_VERB = EffectRelationSchema.options.map(
-  (verb) => z2.strictObject({
-    [verb]: z2.string().min(1),
-    fields: z2.array(z2.string().min(1)).min(1).optional(),
-    by: ONE_OR_MORE.optional()
+function effectByVerb(extra = {}) {
+  return EffectRelationSchema.options.map(
+    (verb) => z.strictObject({
+      [verb]: z.string().min(1),
+      fields: z.array(z.string().min(1)).min(1).optional(),
+      by: ONE_OR_MORE.optional(),
+      shape: BodyShapeSchema.describe(
+        "The shape of what the effect writes, such as the report a command prints."
+      ).optional(),
+      ...extra
+    })
+  );
+}
+var EffectLineSchema = z.union(effectByVerb());
+var EffectOutcomeSchema = z.union(
+  effectByVerb({ from: SourcesSchema.optional() })
+);
+var AlwaysEffectSchema = z.union(
+  effectByVerb({
+    except: z.array(z.string().min(1)).min(1).describe("The ids of the outcomes that do not have to have the effect.").optional()
   })
 );
-var EffectOutcomeSchema = z2.union(EFFECT_BY_VERB);
 var CHECKS = {
   /** What a lookup came back with. */
-  finds: z2.enum(["nothing", "something"]),
+  finds: z.enum(["nothing", "something"]),
   /** What state the value was in: `set`, `missing`, `null`, `a string`. */
-  is: z2.string().min(1),
+  is: z.string().min(1),
   /** The value it was equal to. */
-  equals: z2.union([z2.string(), z2.number(), z2.boolean(), z2.null()]),
+  equals: z.union([z.string(), z.number(), z.boolean(), z.null()]),
   /** A property it had. */
-  has: z2.string().min(1)
+  has: z.string().min(1)
 };
 var SUBJECT_KEYS = [
   ...EffectRelationSchema.options,
   "input"
 ];
 var WHEN_CLAUSE_BY_SUBJECT = SUBJECT_KEYS.map(
-  (key) => z2.strictObject({
-    [key]: z2.string().min(1),
-    where: z2.string().min(1).optional(),
+  (key) => z.strictObject({
+    [key]: z.string().min(1),
+    where: z.string().min(1).optional(),
     ...Object.fromEntries(
       Object.entries(CHECKS).map(([check, schema]) => [
         check,
@@ -303,12 +283,12 @@ var WHEN_CLAUSE_BY_SUBJECT = SUBJECT_KEYS.map(
     }
   )
 );
-var WhenSchema = z2.union([
-  z2.string().min(1),
-  z2.array(z2.union([z2.string().min(1), ...WHEN_CLAUSE_BY_SUBJECT])).min(1)
+var WhenSchema = z.union([
+  z.string().min(1),
+  z.array(z.union([z.string().min(1), ...WHEN_CLAUSE_BY_SUBJECT])).min(1)
 ]);
-var BoundaryTransitionSchema = z2.strictObject({
-  id: z2.string().min(1).describe(
+var BoundaryTransitionSchema = z.strictObject({
+  id: z.string().min(1).describe(
     "The outcome's name. A PRD scenario links to it as <intent-name>.<id>."
   ),
   when: WhenSchema.describe(
@@ -317,58 +297,149 @@ var BoundaryTransitionSchema = z2.strictObject({
   response: emptyIfNull(ResponseOutcomeSchema).describe("This outcome sends an HTTP response.").optional(),
   returns: emptyIfNull(ReturnsOutcomeSchema).describe("This outcome returns a value to its caller.").optional(),
   throws: emptyIfNull(ThrowsOutcomeSchema).describe("This outcome raises an error.").optional(),
-  results: z2.array(EffectOutcomeSchema).min(1).describe(
+  exits: z.number().int().min(0).max(255).describe("This outcome ends the process with this exit code.").optional(),
+  results: z.array(EffectOutcomeSchema).min(1).describe(
     "The effects this outcome has, written in the same verbs suss ask uses: reads, writes, invokes."
   ).optional()
 }).refine((t) => endingsOf(t).length <= 1, {
-  message: "a transition ends one way: give it at most one of response, returns, or throws"
+  message: "a transition ends one way: give it at most one of response, returns, throws, or exits"
 }).refine((t) => endingsOf(t).length === 1 || t.results !== void 0, {
-  message: "each transition must declare an outcome: response, returns, throws, or the effects it results in"
+  message: "each transition must declare an outcome: response, returns, throws, exits, or the effects it results in"
 });
 function endingsOf(t) {
-  return [t.response, t.returns, t.throws].filter((o) => o !== void 0);
+  return [t.response, t.returns, t.throws, t.exits].filter(
+    (o) => o !== void 0
+  );
 }
-var BoundaryIntentSchema = z2.strictObject({
-  kind: z2.literal("boundary").describe("Makes this document boundary intent for one boundary."),
-  name: z2.string().min(1).describe(
+var BoundaryIntentFields = z.strictObject({
+  kind: z.literal("boundary").describe("Makes this document boundary intent for one boundary."),
+  name: z.string().min(1).describe(
     "What this document is called. A PRD scenario links to an outcome of it as <name>.<outcome-id>."
   ),
-  purpose: z2.string().min(1).describe("What the boundary is for, in the author's own words."),
-  audience: z2.string().min(1).describe("Who calls this boundary and depends on what it does."),
+  purpose: z.string().min(1).describe("What the boundary is for, in the author's own words."),
+  audience: z.string().min(1).describe("Who calls this boundary and depends on what it does."),
   source: IntentSourceSchema,
   boundary: BoundarySchema.describe(
     "Which boundary in the code the document is about."
   ),
-  transitions: z2.array(BoundaryTransitionSchema).min(1).describe("Every outcome the boundary can produce, one entry each.")
+  transitions: z.array(BoundaryTransitionSchema).min(1).describe("Every outcome the boundary can produce, one entry each."),
+  always: z.array(AlwaysEffectSchema).min(1).describe(
+    "Effects that every transition producing a declared outcome has, apart from the outcomes listed under except."
+  ).optional()
+});
+var BoundaryIntentSchema = BoundaryIntentFields.superRefine((doc, ctx) => {
+  for (const [line, entry] of (doc.always ?? []).entries()) {
+    for (const [at, id] of (entry.except ?? []).entries()) {
+      const problem = exceptProblem(doc.transitions, id);
+      if (problem !== null) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["always", line, "except", at],
+          message: problem
+        });
+      }
+    }
+  }
+  for (const [at, transition] of doc.transitions.entries()) {
+    for (const [line, effect] of (transition.results ?? []).entries()) {
+      for (const column of Object.keys(effect.from ?? {})) {
+        if (!listsColumn(effect, column)) {
+          ctx.addIssue({
+            code: "custom",
+            path: ["transitions", at, "results", line, "from", column],
+            message: `from says where ${column} comes from, and the line lists ${column} under neither fields nor by`
+          });
+        }
+      }
+    }
+  }
 });
-var PrdScenarioSchema = z2.strictObject({
-  title: z2.string().min(1).describe("A short name for the scenario.").optional(),
-  when: z2.string().min(1).describe("The condition the scenario covers, in the author's own words."),
-  expect: z2.string().min(1).describe("What should happen then, in the author's own words."),
+function listsColumn(effect, column) {
+  return (effect.fields ?? []).includes(column) || oneOrMore(effect.by).includes(column);
+}
+function exceptProblem(transitions, id) {
+  const outcome = transitions.find((t) => t.id === id);
+  if (outcome === void 0) {
+    return `except lists ${id}, and no transition has that id (known: ${transitions.map((t) => t.id).join(", ")})`;
+  }
+  if (endingsOf(outcome).length === 0) {
+    return `except lists ${id}, which states only its effects; an outcome with no response, returns, throws or exits matches every transition, so it cannot be exempted`;
+  }
+  return null;
+}
+var PrdScenarioSchema = z.strictObject({
+  title: z.string().min(1).describe("A short name for the scenario.").optional(),
+  when: z.string().min(1).describe("The condition the scenario covers, in the author's own words."),
+  expect: z.string().min(1).describe("What should happen then, in the author's own words."),
   /**
-   * Optional structured link(s) to system-intent outcomes
-   * (`<intent-name>.<outcome-id>`). A scenario without `link` is a
-   * valid pending-link state: fully human-readable, not yet machine-
-   * linked. The link is filled in later by a facilitator (a person, a
-   * platform, or an LLM at authoring time), never required to author.
+   * Links to system-intent outcomes, each written
+   * `<intent-name>.<outcome-id>`. A scenario is backed by a link or by
+   * `coveredBy`, and the checker warns about one with neither. The
+   * schema still accepts it, so a PRD can be written before either
+   * exists.
    *
-   * (The human-readable parts are `when` / `expect`; the field is named
-   * `link`, not `then`, because a data object with a `then` property is
-   * treated as a thenable by Promise resolution, a latent footgun.)
+   * The field is `link` and not `then`, because Promise resolution
+   * treats an object with a `then` property as a thenable.
    */
-  link: z2.union([z2.string().min(1), z2.array(z2.string().min(1)).min(1)]).describe(
+  link: ONE_OR_MORE.describe(
     "The boundary-intent outcomes this scenario is about, each written <intent-name>.<outcome-id>."
+  ).optional(),
+  /**
+   * The tests that exercise this scenario, for a promise about which
+   * values come back that no outcome can state. Each is spelled the way
+   * the runner prints it, as `toCoveringTest` reads it.
+   */
+  coveredBy: ONE_OR_MORE.describe(
+    "The tests that exercise this scenario, each written the way its runner prints it: for vitest or RSpec, the test file, then each describe or context title, then the test's own title, joined with ' > '; for pytest, the node id, as in tests/test_orders.py::TestCancel::test_twice."
+  ).optional(),
+  about: ONE_OR_MORE.describe(
+    "What a covering test has to reach for the scenario to count as covered: a boundary or a unit, spelled the way suss ask takes one. Without it, a test has to reach one of the boundaries the PRD's other scenarios link to."
   ).optional()
 });
-var PrdSchema = z2.strictObject({
-  kind: z2.literal("prd").describe("Makes this document a PRD, a set of scenarios for a feature."),
-  title: z2.string().min(1).describe("What this document is called."),
-  purpose: z2.string().min(1).describe("What the feature is for, in the author's own words."),
-  audience: z2.string().min(1).describe("Who the feature is for."),
+var PrdFields = z.strictObject({
+  kind: z.literal("prd").describe("Makes this document a PRD, a set of scenarios for a feature."),
+  title: z.string().min(1).describe("What this document is called."),
+  purpose: z.string().min(1).describe("What the feature is for, in the author's own words."),
+  audience: z.string().min(1).describe("Who the feature is for."),
   source: IntentSourceSchema,
-  scenarios: z2.array(PrdScenarioSchema).min(1).describe("The situations the feature covers, one entry each.")
+  scenarios: z.array(PrdScenarioSchema).min(1).describe("The situations the feature covers, one entry each.")
 });
-var IntentDocSchema = z2.discriminatedUnion("kind", [
+var PrdSchema = PrdFields.superRefine((doc, ctx) => {
+  const linksAnything = doc.scenarios.some((s) => s.link !== void 0);
+  for (const [at, scenario] of doc.scenarios.entries()) {
+    const label = scenario.title === void 0 ? `#${at + 1}` : `"${scenario.title}"`;
+    for (const [line, spelled] of oneOrMore(scenario.coveredBy).entries()) {
+      if (toCoveringTest(spelled).titles.length === 0) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["scenarios", at, "coveredBy", line],
+          message: `scenario ${label} lists the test "${spelled}", which has no title; write the file, then each describe title, then the test's own title, joined with " > ", or for pytest the node id, file::test_name`
+        });
+      }
+    }
+    if (scenario.about !== void 0 && scenario.coveredBy === void 0) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["scenarios", at, "about"],
+        message: `scenario ${label} says what a covering test has to reach, and lists no test under coveredBy`
+      });
+    }
+    if (scenario.coveredBy !== void 0 && scenario.about === void 0 && !linksAnything) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["scenarios", at, "about"],
+        message: `scenario ${label} lists a covering test, and no scenario in this PRD links to an outcome, so there is nothing to check the test reaches; say what it has to reach under about`
+      });
+    }
+  }
+});
+function oneOrMore(written) {
+  if (written === void 0) {
+    return [];
+  }
+  return typeof written === "string" ? [written] : written;
+}
+var IntentDocSchema = z.discriminatedUnion("kind", [
   BoundaryIntentSchema,
   PrdSchema
 ]);
@@ -397,7 +468,11 @@ function boundaryIntentToSummary(doc) {
     source: doc.source,
     boundary: toBoundaryBinding(doc.boundary),
     receives: toReceives(doc.boundary),
-    outcomes: doc.transitions.map(toOutcome)
+    outcomes: doc.transitions.map(toOutcome),
+    always: (doc.always ?? []).map((declared) => ({
+      effect: toIntentEffect(declared),
+      except: declared.except ?? []
+    }))
   };
 }
 function prdToSummary(doc) {
@@ -411,7 +486,9 @@ function prdToSummary(doc) {
       title: s.title ?? null,
       when: s.when,
       expect: s.expect,
-      link: s.link === void 0 ? [] : Array.isArray(s.link) ? s.link : [s.link]
+      link: oneOrMore(s.link),
+      coveredBy: oneOrMore(s.coveredBy).map(toCoveringTest),
+      about: oneOrMore(s.about)
     }))
   };
 }
@@ -514,23 +591,24 @@ function toReceives(boundary) {
   return read(boundary);
 }
 var VERBS = EffectRelationSchema2.options;
-function toEffect(declared) {
+function toIntentEffect(declared) {
   const [does, names] = Object.entries(declared).find(
     ([key]) => VERBS.includes(key)
   );
+  const shape = declared.shape === void 0 ? null : bodyToTypeShape(declared.shape);
+  const from = Object.entries(declared.from ?? {}).map(([column, source]) => ({
+    column,
+    path: source.slice(INPUT_SOURCE_PREFIX.length).split(".")
+  }));
   return {
     does,
     names,
     fields: declared.fields ?? [],
-    by: oneOrMore(declared.by)
+    by: oneOrMore(declared.by),
+    ...shape === null ? {} : { shape },
+    ...from.length === 0 ? {} : { from }
   };
 }
-function oneOrMore(written) {
-  if (written === void 0) {
-    return [];
-  }
-  return typeof written === "string" ? [written] : written;
-}
 function subjectOf(clause) {
   for (const does of VERBS) {
     const names = clause[does];
@@ -568,7 +646,7 @@ function whenAsOneLine(when) {
   return typeof when === "string" ? when : toConditions(when).map((condition) => condition.said).join(" and ");
 }
 function toOutcome(t) {
-  const effects = (t.results ?? []).map(toEffect);
+  const effects = (t.results ?? []).map(toIntentEffect);
   const base = {
     id: t.id,
     when: whenAsOneLine(t.when),
@@ -602,9 +680,21 @@ function toOutcome(t) {
       errorType: t.throws.errorType ?? null
     };
   }
+  if (t.exits !== void 0) {
+    return {
+      ...base,
+      kind: "exit",
+      status: t.exits,
+      body: null,
+      errorType: null
+    };
+  }
   return { ...base, kind: "effect", status: null, body: null, errorType: null };
 }
 function bodyToTypeShape(body) {
+  if ("const" in body) {
+    return constantShape(body.const);
+  }
   if (!("type" in body)) {
     if (body.properties === void 0) {
       return null;
@@ -614,6 +704,12 @@ function bodyToTypeShape(body) {
   return shapeToTypeShape(body);
 }
 function shapeToTypeShape(shape) {
+  if ("const" in shape) {
+    return constantShape(shape.const);
+  }
+  if (!("type" in shape)) {
+    return recordShape(shape.properties);
+  }
   if (shape.type === "array") {
     return {
       type: "array",
@@ -625,6 +721,9 @@ function shapeToTypeShape(shape) {
   }
   return PRIMITIVE_TYPE_SHAPES[shape.type];
 }
+function constantShape(value) {
+  return value === null ? { type: "null" } : { type: "literal", value };
+}
 function recordShape(authored) {
   const properties = {};
   for (const [name, prop] of Object.entries(authored)) {
@@ -640,10 +739,223 @@ var PRIMITIVE_TYPE_SHAPES = {
   null: { type: "null" },
   unknown: { type: "unknown" }
 };
+
+// src/changeList.ts
+var VERBS2 = ["adds", "removes", "changes"];
+var OutcomeWordSchema = z2.union([
+  z2.number().int().min(100).max(599),
+  z2.enum(["returns", "throws"]),
+  z2.strictObject({ throws: z2.string().min(1) })
+]);
+var SubjectSchema = z2.union([z2.string().min(1), EffectLineSchema]);
+var ENTRY_FIELDS = {
+  adds: SubjectSchema.optional(),
+  removes: SubjectSchema.optional(),
+  changes: SubjectSchema.optional(),
+  outcomes: z2.array(OutcomeWordSchema).min(1).describe(
+    "The outcomes the boundary should have: statuses, returns or throws."
+  ).optional(),
+  at: z2.string().min(1).describe("The boundary an effect happens at, spelled as suss spells it.").optional()
+};
+function verbsOf(entry) {
+  return VERBS2.filter((verb) => entry[verb] !== void 0);
+}
+function subjectOf2(entry) {
+  const [verb] = verbsOf(entry);
+  return verb === void 0 ? void 0 : entry[verb];
+}
+function withEntryRules(schema) {
+  return schema.refine((entry) => verbsOf(entry).length === 1, {
+    message: "an entry has exactly one of adds, removes or changes"
+  }).refine(
+    (entry) => entry.at === void 0 || typeof subjectOf2(entry) !== "string",
+    {
+      message: "at says which boundary an effect happens at, so it goes with an effect; a boundary entry names its boundary itself"
+    }
+  ).refine(
+    (entry) => entry.outcomes === void 0 || typeof subjectOf2(entry) === "string",
+    {
+      message: "outcomes belong to a boundary; an effect entry says what it touches instead"
+    }
+  );
+}
+var ChangeEntrySchema = withEntryRules(
+  z2.strictObject({
+    ...ENTRY_FIELDS,
+    asked: z2.string().min(1).describe(
+      "The developer's words that asked for this entry, when they are not the list's."
+    ).optional(),
+    note: z2.string().min(1).describe("What the change is, for a subject suss has no words for.").optional()
+  })
+);
+var ExplainedEntrySchema = withEntryRules(
+  z2.strictObject({
+    ...ENTRY_FIELDS,
+    why: z2.string().min(1).describe("Why the change stays, for the developer to read.")
+  })
+);
+var ChangeListSchema = z2.strictObject({
+  asked: z2.string().min(1).describe("The developer's request, quoted.").optional(),
+  changes: z2.array(ChangeEntrySchema).default([]).describe("Each behavior change the agent intends, one per entry."),
+  explained: z2.array(ExplainedEntrySchema).default([]).describe(
+    "Changes nobody asked for that the agent keeps, each with the reason."
+  )
+});
+var WORD_OUTCOMES = {
+  returns: { kind: "return", status: null, errorType: null },
+  throws: { kind: "throw", status: null, errorType: null }
+};
+function toOutcome2(word) {
+  if (typeof word === "number") {
+    return { kind: "response", status: word, errorType: null };
+  }
+  if (typeof word === "string") {
+    return WORD_OUTCOMES[word];
+  }
+  return { kind: "throw", status: null, errorType: word.throws };
+}
+function toSubject(written) {
+  return typeof written === "string" ? { kind: "boundary", names: written } : { kind: "effect", effect: toIntentEffect(written) };
+}
+function commonOf(entry) {
+  const [verb] = verbsOf(entry);
+  return {
+    verb,
+    subject: toSubject(entry[verb]),
+    outcomes: (entry.outcomes ?? []).map(toOutcome2),
+    at: entry.at ?? null
+  };
+}
+function parseChangeList(raw) {
+  const result = ChangeListSchema.safeParse(raw);
+  if (result.success) {
+    return { ok: true, list: changeListToSummary(result.data) };
+  }
+  return {
+    ok: false,
+    problems: result.error.issues.map((issue) => ({
+      path: issue.path.join("."),
+      message: issue.message
+    }))
+  };
+}
+function changeListToSummary(list) {
+  const asked = list.asked ?? null;
+  return {
+    asked,
+    changes: list.changes.map((entry) => ({
+      ...commonOf(entry),
+      asked: entry.asked ?? asked,
+      note: entry.note ?? null
+    })),
+    explained: list.explained.map((entry) => ({
+      ...commonOf(entry),
+      why: entry.why
+    }))
+  };
+}
+
+// src/findings.ts
+import { z as z3 } from "zod";
+var IntentFindingKindSchema = z3.enum([
+  // System intent (kind: boundary) vs code:
+  "uncoveredOutcome",
+  // intent declares an outcome the code never produces
+  "unimplementedBoundary",
+  // intent boundary has no implementing code at all
+  "outcomeShapeMismatch",
+  // a matched outcome whose body shapes disagree
+  "undeclaredOutcome",
+  // code produces a REST status the intent doesn't declare
+  "unkeyableBoundary",
+  // intent boundary can't be keyed, so it can't be checked
+  "renamedBoundary",
+  // a declared store vanished and an undeclared one of the same system appeared with the same outcomes
+  "pathWithoutEffect",
+  // a transition producing a declared outcome lacks an effect the always block says every outcome has
+  "valueFromElsewhere",
+  // a column's value comes from somewhere other than the source a results line gives
+  // What the boundary is handed: the `receives` block against the paths
+  // the unit reads off its input.
+  "unreadInputField",
+  // intent declares a field no transition of the unit reads
+  "undeclaredInputRead",
+  // the unit reads a path the receives block does not list
+  // Outcome intent (kind: prd): whether each scenario's link resolves to
+  // a system-intent outcome.
+  "unlinkedScenario",
+  // scenario has neither a link nor a covering test
+  "danglingScenarioLink",
+  // link names an intent / outcome no boundary intent declares
+  "ambiguousScenarioLink",
+  // link resolves to two or more boundary intents sharing the name
+  // The same question for a scenario backed by a test: whether the test
+  // it lists exists, runs, and reaches what the scenario is about.
+  "missingCoveringTest",
+  // coveredBy lists a test no summary here is
+  "testMissesSubject",
+  // the test never reaches the subject, or reaches it only through a mock
+  "coveringTestSkipped",
+  // the test is marked to be skipped, so it does not run
+  // The same coverage question asked the other way: which declared
+  // behaviour has nobody written a reason for.
+  "undescribedOutcome"
+  // a declared outcome no PRD scenario links to (info)
+]);
+var IntentFindingSeveritySchema = z3.enum(["error", "warning", "info"]);
+var IntentRefSchema = z3.object({
+  /** The intent doc's `name` (boundary) or `title` (prd). */
+  name: z3.string(),
+  /** The declared outcome id, when the finding is outcome-specific. */
+  outcomeId: z3.string().optional()
+});
+var IntentFindingSuppressionSchema = z3.object({
+  /** The rule's human-written justification. */
+  reason: z3.string(),
+  effect: z3.enum(["mark", "downgrade", "hide"]),
+  /** Original severity, present only when effect is "downgrade". */
+  originalSeverity: IntentFindingSeveritySchema.optional()
+});
+var IntentFindingSchema = z3.object({
+  kind: IntentFindingKindSchema,
+  severity: IntentFindingSeveritySchema,
+  /**
+   * Human-readable boundary label: e.g. `GET /users/:id` or
+   * `fn:@suss/cli::contract`. The key the intent and code were paired on.
+   */
+  boundary: z3.string(),
+  /** The intent side of the finding. */
+  intent: IntentRefSchema,
+  /**
+   * The matched code summary as `${file}::${name}`, when the finding
+   * concerns a specific implementation. Absent for unimplementedBoundary.
+   */
+  code: z3.string().optional(),
+  /**
+   * Present only on outcome-intent findings. It gives the scenario, by
+   * its optional title, and the qualified outcome ref
+   * (`<intent-name>.<outcome-id>`) that failed to resolve, or the
+   * `coveredBy` entry whose test failed the check. Boundary findings
+   * leave it unset.
+   */
+  scenario: z3.object({
+    title: z3.string().optional(),
+    link: z3.string().optional(),
+    coveredBy: z3.string().optional()
+  }).optional(),
+  message: z3.string(),
+  /** Present when a .sussignore rule matched this finding. */
+  suppressed: IntentFindingSuppressionSchema.optional()
+});
 export {
   ACCEPTS_NULL,
+  AlwaysEffectSchema,
   BodyShapeSchema,
   BoundarySchema,
+  ChangeListSchema,
+  EffectLineSchema,
+  EffectOutcomeSchema,
+  INPUT_SOURCE_PREFIX,
   IntentDocSchema,
   IntentFindingKindSchema,
   IntentFindingSchema,
@@ -651,9 +963,15 @@ export {
   IntentFindingSuppressionSchema,
   IntentRefSchema,
   IntentSourceSchema,
+  NODE_ID_SEPARATOR,
+  TEST_TITLE_SEPARATOR,
   blanksLeftEmpty,
+  changeListToSummary,
   fillBlanks,
   intentDocToSummary,
+  parseChangeList,
   toBoundaryBinding,
+  toCoveringTest,
+  toIntentEffect,
   toReceives
 };