@suss/intent-ir 0.33.0 → 0.34.0

package/dist/index.d.cts

@@ -1,98 +1,21 @@
 import { z } from 'zod';
 import { EffectRelation, BoundaryBinding, TypeShape } from '@suss/ir-core';
+export { TEST_TITLE_SEPARATOR } from '@suss/ir-core';
 
-declare const IntentFindingKindSchema: z.ZodEnum<{
-    uncoveredOutcome: "uncoveredOutcome";
-    unimplementedBoundary: "unimplementedBoundary";
-    outcomeShapeMismatch: "outcomeShapeMismatch";
-    undeclaredOutcome: "undeclaredOutcome";
-    unkeyableBoundary: "unkeyableBoundary";
-    renamedBoundary: "renamedBoundary";
-    unreadInputField: "unreadInputField";
-    undeclaredInputRead: "undeclaredInputRead";
-    unlinkedScenario: "unlinkedScenario";
-    danglingScenarioLink: "danglingScenarioLink";
-    ambiguousScenarioLink: "ambiguousScenarioLink";
-    undescribedOutcome: "undescribedOutcome";
-}>;
-type IntentFindingKind = z.infer<typeof IntentFindingKindSchema>;
-declare const IntentFindingSeveritySchema: z.ZodEnum<{
-    error: "error";
-    warning: "warning";
-    info: "info";
-}>;
-type IntentFindingSeverity = z.infer<typeof IntentFindingSeveritySchema>;
-/** Which intent (and, when relevant, which outcome) a finding concerns. */
-declare const IntentRefSchema: z.ZodObject<{
-    name: z.ZodString;
-    outcomeId: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
-type IntentRef = z.infer<typeof IntentRefSchema>;
 /**
- * Suppression annotation stamped by the .sussignore pipeline. Kept
- * structurally identical to the behavioural `Finding.suppressed` shape
- * so @suss/ir-core's shared suppression pipeline operates on both.
+ * The intent file format a team writes, or `suss infer` drafts. There
+ * are two top-level forms, told apart by `kind`:
+ *
+ *   kind: boundary  system intent: what one boundary should do, as
+ *                   outcomes named by id.
+ *   kind: prd       outcome intent: human scenarios (when / expect)
+ *                   that refer to system-intent outcomes by id.
+ *
+ * Boundaries reuse @suss/ir-core's vocabulary, so intent and behavior
+ * describe a boundary the same way. A transition says how it ends and
+ * what it did, as DESIGN.md explains. `intentDocToSummary` normalizes a
+ * document into the form the checker compares against code.
  */
-declare const IntentFindingSuppressionSchema: z.ZodObject<{
-    reason: z.ZodString;
-    effect: z.ZodEnum<{
-        mark: "mark";
-        downgrade: "downgrade";
-        hide: "hide";
-    }>;
-    originalSeverity: z.ZodOptional<z.ZodEnum<{
-        error: "error";
-        warning: "warning";
-        info: "info";
-    }>>;
-}, z.core.$strip>;
-type IntentFindingSuppression = z.infer<typeof IntentFindingSuppressionSchema>;
-declare const IntentFindingSchema: z.ZodObject<{
-    kind: z.ZodEnum<{
-        uncoveredOutcome: "uncoveredOutcome";
-        unimplementedBoundary: "unimplementedBoundary";
-        outcomeShapeMismatch: "outcomeShapeMismatch";
-        undeclaredOutcome: "undeclaredOutcome";
-        unkeyableBoundary: "unkeyableBoundary";
-        renamedBoundary: "renamedBoundary";
-        unreadInputField: "unreadInputField";
-        undeclaredInputRead: "undeclaredInputRead";
-        unlinkedScenario: "unlinkedScenario";
-        danglingScenarioLink: "danglingScenarioLink";
-        ambiguousScenarioLink: "ambiguousScenarioLink";
-        undescribedOutcome: "undescribedOutcome";
-    }>;
-    severity: z.ZodEnum<{
-        error: "error";
-        warning: "warning";
-        info: "info";
-    }>;
-    boundary: z.ZodString;
-    intent: z.ZodObject<{
-        name: z.ZodString;
-        outcomeId: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>;
-    code: z.ZodOptional<z.ZodString>;
-    scenario: z.ZodOptional<z.ZodObject<{
-        title: z.ZodOptional<z.ZodString>;
-        link: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>>;
-    message: z.ZodString;
-    suppressed: z.ZodOptional<z.ZodObject<{
-        reason: z.ZodString;
-        effect: z.ZodEnum<{
-            mark: "mark";
-            downgrade: "downgrade";
-            hide: "hide";
-        }>;
-        originalSeverity: z.ZodOptional<z.ZodEnum<{
-            error: "error";
-            warning: "warning";
-            info: "info";
-        }>>;
-    }, z.core.$strip>>;
-}, z.core.$strip>;
-type IntentFinding = z.infer<typeof IntentFindingSchema>;
 
 declare const IntentSourceSchema: z.ZodDefault<z.ZodEnum<{
     author: "author";
@@ -110,18 +33,25 @@ declare const IntentSourceSchema: z.ZodDefault<z.ZodEnum<{
  */
 declare function blanksLeftEmpty(doc: unknown, failedFields: string[]): string[];
 /**
- * The same draft with a placeholder written into each blank, so a
- * reader after the parts a draft does state can validate it and have
- * them. Nothing that fills the blanks this way should show them to
- * anybody: the words are suss's, not the team's.
+ * The same draft with a placeholder in each blank, so a reader that
+ * wants the parts a draft does state can validate it and get them. Code
+ * that fills blanks this way must not show the placeholders to anybody,
+ * since those words come from suss and not from the team.
  */
 declare function fillBlanks(doc: unknown, blanks: string[]): unknown;
-interface AuthoredShape {
+type AuthoredShape = {
     type: z.infer<typeof PrimitiveTypeName> | "array" | "object";
     items?: AuthoredShape | undefined;
     properties?: Record<string, AuthoredShape> | undefined;
     required?: string[] | undefined;
-}
+} | {
+    const: AuthoredConstant;
+} | {
+    properties: Record<string, AuthoredShape>;
+    required?: string[] | undefined;
+};
+/** A literal a value has to equal, such as a finding kind or a flag that is always true. */
+type AuthoredConstant = string | number | boolean | null;
 declare const BodyShapeSchema: z.ZodUnion<readonly [z.ZodType<AuthoredShape, unknown, z.core.$ZodTypeInternals<AuthoredShape, unknown>>, z.ZodObject<{
     properties: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodType<AuthoredShape, unknown, z.core.$ZodTypeInternals<AuthoredShape, unknown>>>>;
     required: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -434,8 +364,26 @@ type DeclaredEffect = Partial<Record<EffectRelation, string>> & {
     fields?: string[];
     /** What it picks the item out by. */
     by?: string | string[];
+    /** The shape of what it writes, such as the report a command prints. */
+    shape?: BodyShape;
+    /**
+     * Where the value of a column under `fields` or `by` comes from, by
+     * column: `{ tenant_id: input.headers.x-tenant-id }`. Only a `results`
+     * line takes it.
+     */
+    from?: Record<string, string>;
 };
+/** What a source written in `from` starts with. */
+declare const INPUT_SOURCE_PREFIX = "input.";
+/** An effect as a change list states one, which says nothing of sources. */
+declare const EffectLineSchema: z.ZodUnion<[z.ZodType<DeclaredEffect, unknown, z.core.$ZodTypeInternals<DeclaredEffect, unknown>>, ...z.ZodType<DeclaredEffect, unknown, z.core.$ZodTypeInternals<DeclaredEffect, unknown>>[]]>;
+/** A `results` line, which can also say where a column's value comes from. */
 declare const EffectOutcomeSchema: z.ZodUnion<[z.ZodType<DeclaredEffect, unknown, z.core.$ZodTypeInternals<DeclaredEffect, unknown>>, ...z.ZodType<DeclaredEffect, unknown, z.core.$ZodTypeInternals<DeclaredEffect, unknown>>[]]>;
+/** One `always` line: an effect, and the outcomes that do not have to have it. */
+type DeclaredAlways = DeclaredEffect & {
+    except?: string[];
+};
+declare const AlwaysEffectSchema: z.ZodUnion<[z.ZodType<DeclaredAlways, unknown, z.core.$ZodTypeInternals<DeclaredAlways, unknown>>, ...z.ZodType<DeclaredAlways, unknown, z.core.$ZodTypeInternals<DeclaredAlways, unknown>>[]]>;
 /** One clause of a structured `when`, or the sentence for a guard that maps to none. */
 type WhenClause = string | ({
     where?: string;
@@ -465,6 +413,7 @@ declare const BoundaryTransitionSchema: z.ZodObject<{
     throws: z.ZodOptional<z.ZodPreprocess<z.ZodObject<{
         errorType: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
+    exits: z.ZodOptional<z.ZodNumber>;
     results: z.ZodOptional<z.ZodArray<z.ZodUnion<[z.ZodType<DeclaredEffect, unknown, z.core.$ZodTypeInternals<DeclaredEffect, unknown>>, ...z.ZodType<DeclaredEffect, unknown, z.core.$ZodTypeInternals<DeclaredEffect, unknown>>[]]>>>;
 }, z.core.$strict>;
 declare const BoundaryIntentSchema: z.ZodObject<{
@@ -696,14 +645,18 @@ declare const BoundaryIntentSchema: z.ZodObject<{
         throws: z.ZodOptional<z.ZodPreprocess<z.ZodObject<{
             errorType: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>>;
+        exits: z.ZodOptional<z.ZodNumber>;
         results: z.ZodOptional<z.ZodArray<z.ZodUnion<[z.ZodType<DeclaredEffect, unknown, z.core.$ZodTypeInternals<DeclaredEffect, unknown>>, ...z.ZodType<DeclaredEffect, unknown, z.core.$ZodTypeInternals<DeclaredEffect, unknown>>[]]>>>;
     }, z.core.$strict>>;
+    always: z.ZodOptional<z.ZodArray<z.ZodUnion<[z.ZodType<DeclaredAlways, unknown, z.core.$ZodTypeInternals<DeclaredAlways, unknown>>, ...z.ZodType<DeclaredAlways, unknown, z.core.$ZodTypeInternals<DeclaredAlways, unknown>>[]]>>>;
 }, z.core.$strict>;
 declare const PrdScenarioSchema: z.ZodObject<{
     title: z.ZodOptional<z.ZodString>;
     when: z.ZodString;
     expect: z.ZodString;
     link: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+    coveredBy: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+    about: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
 }, z.core.$strict>;
 declare const PrdSchema: z.ZodObject<{
     kind: z.ZodLiteral<"prd">;
@@ -720,6 +673,8 @@ declare const PrdSchema: z.ZodObject<{
         when: z.ZodString;
         expect: z.ZodString;
         link: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+        coveredBy: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+        about: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
     }, z.core.$strict>>;
 }, z.core.$strict>;
 declare const IntentDocSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -951,8 +906,10 @@ declare const IntentDocSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         throws: z.ZodOptional<z.ZodPreprocess<z.ZodObject<{
             errorType: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>>;
+        exits: z.ZodOptional<z.ZodNumber>;
         results: z.ZodOptional<z.ZodArray<z.ZodUnion<[z.ZodType<DeclaredEffect, unknown, z.core.$ZodTypeInternals<DeclaredEffect, unknown>>, ...z.ZodType<DeclaredEffect, unknown, z.core.$ZodTypeInternals<DeclaredEffect, unknown>>[]]>>>;
     }, z.core.$strict>>;
+    always: z.ZodOptional<z.ZodArray<z.ZodUnion<[z.ZodType<DeclaredAlways, unknown, z.core.$ZodTypeInternals<DeclaredAlways, unknown>>, ...z.ZodType<DeclaredAlways, unknown, z.core.$ZodTypeInternals<DeclaredAlways, unknown>>[]]>>>;
 }, z.core.$strict>, z.ZodObject<{
     kind: z.ZodLiteral<"prd">;
     title: z.ZodString;
@@ -968,6 +925,8 @@ declare const IntentDocSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         when: z.ZodString;
         expect: z.ZodString;
         link: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+        coveredBy: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+        about: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
     }, z.core.$strict>>;
 }, z.core.$strict>], "kind">;
 type IntentDoc = z.infer<typeof IntentDocSchema>;
@@ -997,26 +956,79 @@ declare const PrimitiveTypeName: z.ZodEnum<{
 }>;
 type PrimitiveTypeName = z.infer<typeof PrimitiveTypeName>;
 
+/**
+ * How a PRD scenario spells the test that covers it, the way the test
+ * runner prints it. vitest and RSpec write the file, each describe or
+ * context title, then the test's own title, joined with ` > `. pytest
+ * prints a node id, the file, any class, then the test function, joined
+ * with `::`. Both come apart into the same file and title path, and a
+ * test unit's name is that title path joined with ` > `, so one lookup
+ * serves every runner.
+ */
+
+/** What separates the file, a class and a test function in a pytest node id. */
+declare const NODE_ID_SEPARATOR = "::";
+/** One `coveredBy` entry, split into the test file and its title path. */
+interface CoveringTestSpelling {
+    /** The entry as the author wrote it. */
+    spelledAs: string;
+    /** The test file, with the workspace in front when the author wrote one. */
+    file: string;
+    /** The suite titles, outermost first, then the test's own title. Empty when the entry has none. */
+    titles: string[];
+}
+declare function toCoveringTest(spelledAs: string): CoveringTestSpelling;
+
+/**
+ * The normalized intent form the checker compares against behavioral
+ * summaries.
+ *
+ * The authoring schema is built to be easy to write, and this form is
+ * built to be easy to check: boundaries as @suss/ir-core
+ * `BoundaryBinding`s, body shapes as `TypeShape`s, and one flat
+ * outcome list per boundary intent.
+ */
+
 /**
  * How a boundary outcome ends. `effect` is an outcome that declares
  * only what it did, which is what a queue consumer or a table writer
  * has to say instead of a status.
  */
-type IntentOutcomeKind = "response" | "return" | "throw" | "effect";
+type IntentOutcomeKind = "response" | "return" | "throw" | "exit" | "effect";
 /** One effect an outcome has, in the verbs `suss ask` asks with. */
 interface IntentEffect {
     does: EffectRelation;
-    /** The boundary it reaches, as the author spelled it. */
+    /** The boundary it reaches, as the author wrote it. */
     names: string;
     /** The columns it touches. Empty when the doc states none. */
     fields: string[];
     /** What it picks the item out by. Empty when the doc states none. */
     by: string[];
+    /** The shape of what it writes, when the doc states one. */
+    shape?: TypeShape;
+    /** Where the value of each column the doc gives a source for comes from. */
+    from?: IntentValueSource[];
+}
+/** Where a `results` line says one column's value comes from. */
+interface IntentValueSource {
+    /** The column, one the line lists under `fields` or `by`. */
+    column: string;
+    /** The path off the boundary's input: `input.headers.x-tenant-id` is `["headers", "x-tenant-id"]`. */
+    path: string[];
 }
 /**
- * One clause of what a branch turned on. A clause whose subject is a
- * boundary is the one the checker compares; the rest carry through for
- * a reader.
+ * An effect every transition producing a declared outcome has. A
+ * `results` line is satisfied by one transition; this is satisfied only
+ * when none of them lacks it.
+ */
+interface IntentAlways {
+    effect: IntentEffect;
+    /** The outcome ids whose transitions do not have to have it. */
+    except: string[];
+}
+/**
+ * One clause of what a branch turned on. The checker compares a clause
+ * whose subject is a boundary, and the rest are kept for a reader.
  */
 interface IntentCondition {
     /** The boundary the guard read, when the clause says one. */
@@ -1029,14 +1041,14 @@ interface IntentCondition {
     said: string;
 }
 interface IntentOutcome {
-    /** Author-declared id PRD scenarios reference. */
+    /** The id the author gave the outcome, which PRD scenarios link to. */
     id: string;
     /** What the branch turned on, as one line, for a reader. */
     when: string;
     /** The same, clause by clause, for the checker to compare. */
     conditions: IntentCondition[];
     kind: IntentOutcomeKind;
-    /** Set only for `response` outcomes (REST status code). */
+    /** The REST status code of a `response` outcome, or the exit code of an `exit` one. */
     status: number | null;
     /** Response / return body shape, when declared. */
     body: TypeShape | null;
@@ -1067,6 +1079,8 @@ interface BoundaryIntentSummary {
     /** Empty for a doc with no `receives` block, which states nothing about the input. */
     receives: IntentInputField[];
     outcomes: IntentOutcome[];
+    /** Empty for a doc with no `always` block. */
+    always: IntentAlways[];
 }
 interface PrdScenarioSummary {
     title: string | null;
@@ -1076,6 +1090,10 @@ interface PrdScenarioSummary {
     expect: string;
     /** Qualified outcome refs (`<intent-name>.<outcome-id>`); empty when unlinked. */
     link: string[];
+    /** The tests the scenario lists as covering it. Empty when it lists none. */
+    coveredBy: CoveringTestSpelling[];
+    /** What a covering test has to reach. Empty means the PRD's linked boundaries. */
+    about: string[];
 }
 interface PrdSummary {
     kind: "prd";
@@ -1089,5 +1107,247 @@ type IntentSummary = BoundaryIntentSummary | PrdSummary;
 declare function intentDocToSummary(doc: IntentDoc): IntentSummary;
 declare function toBoundaryBinding(boundary: Boundary): BoundaryBinding;
 declare function toReceives(boundary: Boundary): IntentInputField[];
+/** One `results` line, or a change list's effect, in the form the checker compares. */
+declare function toIntentEffect(declared: DeclaredEffect): IntentEffect;
+
+/**
+ * The change list: the behavior changes an agent says it will make for
+ * one request, written before it edits anything.
+ *
+ * It takes the boundary intent vocabulary line by line. A subject is a
+ * boundary spelled the way `suss ask` spells it, or an effect written the
+ * way a `results` line is. Each entry adds one verb, `adds`, `removes` or
+ * `changes`, and leaves out `when`, `purpose` and `audience`, which an
+ * agent cannot know before it has written the code. `explained` lists the
+ * changes the agent made without being asked and keeps, each with why.
+ *
+ * The CLI compares a list with two readings of the code and says which
+ * entries are done, and which changes nobody asked for.
+ */
+
+declare const VERBS: readonly ["adds", "removes", "changes"];
+type ChangeVerb = (typeof VERBS)[number];
+declare const ChangeEntrySchema: z.ZodObject<{
+    asked: z.ZodOptional<z.ZodString>;
+    note: z.ZodOptional<z.ZodString>;
+    adds: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodUnion<[z.ZodType<DeclaredEffect, unknown, z.core.$ZodTypeInternals<DeclaredEffect, unknown>>, ...z.ZodType<DeclaredEffect, unknown, z.core.$ZodTypeInternals<DeclaredEffect, unknown>>[]]>]>>;
+    removes: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodUnion<[z.ZodType<DeclaredEffect, unknown, z.core.$ZodTypeInternals<DeclaredEffect, unknown>>, ...z.ZodType<DeclaredEffect, unknown, z.core.$ZodTypeInternals<DeclaredEffect, unknown>>[]]>]>>;
+    changes: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodUnion<[z.ZodType<DeclaredEffect, unknown, z.core.$ZodTypeInternals<DeclaredEffect, unknown>>, ...z.ZodType<DeclaredEffect, unknown, z.core.$ZodTypeInternals<DeclaredEffect, unknown>>[]]>]>>;
+    outcomes: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodNumber, z.ZodEnum<{
+        returns: "returns";
+        throws: "throws";
+    }>, z.ZodObject<{
+        throws: z.ZodString;
+    }, z.core.$strict>]>>>;
+    at: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+declare const ExplainedEntrySchema: z.ZodObject<{
+    why: z.ZodString;
+    adds: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodUnion<[z.ZodType<DeclaredEffect, unknown, z.core.$ZodTypeInternals<DeclaredEffect, unknown>>, ...z.ZodType<DeclaredEffect, unknown, z.core.$ZodTypeInternals<DeclaredEffect, unknown>>[]]>]>>;
+    removes: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodUnion<[z.ZodType<DeclaredEffect, unknown, z.core.$ZodTypeInternals<DeclaredEffect, unknown>>, ...z.ZodType<DeclaredEffect, unknown, z.core.$ZodTypeInternals<DeclaredEffect, unknown>>[]]>]>>;
+    changes: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodUnion<[z.ZodType<DeclaredEffect, unknown, z.core.$ZodTypeInternals<DeclaredEffect, unknown>>, ...z.ZodType<DeclaredEffect, unknown, z.core.$ZodTypeInternals<DeclaredEffect, unknown>>[]]>]>>;
+    outcomes: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodNumber, z.ZodEnum<{
+        returns: "returns";
+        throws: "throws";
+    }>, z.ZodObject<{
+        throws: z.ZodString;
+    }, z.core.$strict>]>>>;
+    at: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+declare const ChangeListSchema: z.ZodObject<{
+    asked: z.ZodOptional<z.ZodString>;
+    changes: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        asked: z.ZodOptional<z.ZodString>;
+        note: z.ZodOptional<z.ZodString>;
+        adds: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodUnion<[z.ZodType<DeclaredEffect, unknown, z.core.$ZodTypeInternals<DeclaredEffect, unknown>>, ...z.ZodType<DeclaredEffect, unknown, z.core.$ZodTypeInternals<DeclaredEffect, unknown>>[]]>]>>;
+        removes: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodUnion<[z.ZodType<DeclaredEffect, unknown, z.core.$ZodTypeInternals<DeclaredEffect, unknown>>, ...z.ZodType<DeclaredEffect, unknown, z.core.$ZodTypeInternals<DeclaredEffect, unknown>>[]]>]>>;
+        changes: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodUnion<[z.ZodType<DeclaredEffect, unknown, z.core.$ZodTypeInternals<DeclaredEffect, unknown>>, ...z.ZodType<DeclaredEffect, unknown, z.core.$ZodTypeInternals<DeclaredEffect, unknown>>[]]>]>>;
+        outcomes: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodNumber, z.ZodEnum<{
+            returns: "returns";
+            throws: "throws";
+        }>, z.ZodObject<{
+            throws: z.ZodString;
+        }, z.core.$strict>]>>>;
+        at: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+    explained: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        why: z.ZodString;
+        adds: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodUnion<[z.ZodType<DeclaredEffect, unknown, z.core.$ZodTypeInternals<DeclaredEffect, unknown>>, ...z.ZodType<DeclaredEffect, unknown, z.core.$ZodTypeInternals<DeclaredEffect, unknown>>[]]>]>>;
+        removes: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodUnion<[z.ZodType<DeclaredEffect, unknown, z.core.$ZodTypeInternals<DeclaredEffect, unknown>>, ...z.ZodType<DeclaredEffect, unknown, z.core.$ZodTypeInternals<DeclaredEffect, unknown>>[]]>]>>;
+        changes: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodUnion<[z.ZodType<DeclaredEffect, unknown, z.core.$ZodTypeInternals<DeclaredEffect, unknown>>, ...z.ZodType<DeclaredEffect, unknown, z.core.$ZodTypeInternals<DeclaredEffect, unknown>>[]]>]>>;
+        outcomes: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodNumber, z.ZodEnum<{
+            returns: "returns";
+            throws: "throws";
+        }>, z.ZodObject<{
+            throws: z.ZodString;
+        }, z.core.$strict>]>>>;
+        at: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+type ChangeList = z.infer<typeof ChangeListSchema>;
+type ChangeEntry = z.infer<typeof ChangeEntrySchema>;
+type ExplainedEntry = z.infer<typeof ExplainedEntrySchema>;
+/** What an entry is about: a boundary by its spelling, or an effect. */
+type ChangeSubject = {
+    kind: "boundary";
+    names: string;
+} | {
+    kind: "effect";
+    effect: IntentEffect;
+};
+/** An outcome an entry lists, in the terms the intent checker compares. */
+type ChangeOutcome = Pick<IntentOutcome, "kind" | "status" | "errorType">;
+interface IntentChange {
+    verb: ChangeVerb;
+    subject: ChangeSubject;
+    outcomes: ChangeOutcome[];
+    /** The boundary an effect happens at. Null means any boundary. */
+    at: string | null;
+    /** The developer's words that asked for the entry: its own quote, or else the list's. */
+    asked: string | null;
+    note: string | null;
+}
+interface ExplainedChange {
+    verb: ChangeVerb;
+    subject: ChangeSubject;
+    outcomes: ChangeOutcome[];
+    at: string | null;
+    why: string;
+}
+interface ChangeListSummary {
+    asked: string | null;
+    changes: IntentChange[];
+    explained: ExplainedChange[];
+}
+/** A change list, or each place where it does not fit the schema. */
+type ParsedChangeList = {
+    ok: true;
+    list: ChangeListSummary;
+} | {
+    ok: false;
+    problems: Array<{
+        path: string;
+        message: string;
+    }>;
+};
+/** Validates a change list that is already parsed from YAML or JSON, and converts it. */
+declare function parseChangeList(raw: unknown): ParsedChangeList;
+declare function changeListToSummary(list: ChangeList): ChangeListSummary;
+
+/**
+ * The findings the intent checker emits.
+ *
+ * A behavioral `Finding` compares two peers, a provider and a consumer,
+ * each with a source location. An intent finding checks coverage from
+ * one side: the team declared something, and the question is whether
+ * the code does it. Intent is identified by a name and an outcome id,
+ * with no file or range, so an intent finding has its own fields, and
+ * PRD scenario findings add to them.
+ */
+
+declare const IntentFindingKindSchema: z.ZodEnum<{
+    uncoveredOutcome: "uncoveredOutcome";
+    unimplementedBoundary: "unimplementedBoundary";
+    outcomeShapeMismatch: "outcomeShapeMismatch";
+    undeclaredOutcome: "undeclaredOutcome";
+    unkeyableBoundary: "unkeyableBoundary";
+    renamedBoundary: "renamedBoundary";
+    pathWithoutEffect: "pathWithoutEffect";
+    valueFromElsewhere: "valueFromElsewhere";
+    unreadInputField: "unreadInputField";
+    undeclaredInputRead: "undeclaredInputRead";
+    unlinkedScenario: "unlinkedScenario";
+    danglingScenarioLink: "danglingScenarioLink";
+    ambiguousScenarioLink: "ambiguousScenarioLink";
+    missingCoveringTest: "missingCoveringTest";
+    testMissesSubject: "testMissesSubject";
+    coveringTestSkipped: "coveringTestSkipped";
+    undescribedOutcome: "undescribedOutcome";
+}>;
+type IntentFindingKind = z.infer<typeof IntentFindingKindSchema>;
+declare const IntentFindingSeveritySchema: z.ZodEnum<{
+    error: "error";
+    warning: "warning";
+    info: "info";
+}>;
+type IntentFindingSeverity = z.infer<typeof IntentFindingSeveritySchema>;
+/** Which intent (and, when relevant, which outcome) a finding concerns. */
+declare const IntentRefSchema: z.ZodObject<{
+    name: z.ZodString;
+    outcomeId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type IntentRef = z.infer<typeof IntentRefSchema>;
+/**
+ * The annotation the `.sussignore` pipeline adds to a matched finding.
+ * It stays structurally identical to the behavioral
+ * `Finding.suppressed`, so @suss/ir-core's shared suppression pipeline
+ * works on both.
+ */
+declare const IntentFindingSuppressionSchema: z.ZodObject<{
+    reason: z.ZodString;
+    effect: z.ZodEnum<{
+        mark: "mark";
+        downgrade: "downgrade";
+        hide: "hide";
+    }>;
+    originalSeverity: z.ZodOptional<z.ZodEnum<{
+        error: "error";
+        warning: "warning";
+        info: "info";
+    }>>;
+}, z.core.$strip>;
+type IntentFindingSuppression = z.infer<typeof IntentFindingSuppressionSchema>;
+declare const IntentFindingSchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        uncoveredOutcome: "uncoveredOutcome";
+        unimplementedBoundary: "unimplementedBoundary";
+        outcomeShapeMismatch: "outcomeShapeMismatch";
+        undeclaredOutcome: "undeclaredOutcome";
+        unkeyableBoundary: "unkeyableBoundary";
+        renamedBoundary: "renamedBoundary";
+        pathWithoutEffect: "pathWithoutEffect";
+        valueFromElsewhere: "valueFromElsewhere";
+        unreadInputField: "unreadInputField";
+        undeclaredInputRead: "undeclaredInputRead";
+        unlinkedScenario: "unlinkedScenario";
+        danglingScenarioLink: "danglingScenarioLink";
+        ambiguousScenarioLink: "ambiguousScenarioLink";
+        missingCoveringTest: "missingCoveringTest";
+        testMissesSubject: "testMissesSubject";
+        coveringTestSkipped: "coveringTestSkipped";
+        undescribedOutcome: "undescribedOutcome";
+    }>;
+    severity: z.ZodEnum<{
+        error: "error";
+        warning: "warning";
+        info: "info";
+    }>;
+    boundary: z.ZodString;
+    intent: z.ZodObject<{
+        name: z.ZodString;
+        outcomeId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    code: z.ZodOptional<z.ZodString>;
+    scenario: z.ZodOptional<z.ZodObject<{
+        title: z.ZodOptional<z.ZodString>;
+        link: z.ZodOptional<z.ZodString>;
+        coveredBy: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    message: z.ZodString;
+    suppressed: z.ZodOptional<z.ZodObject<{
+        reason: z.ZodString;
+        effect: z.ZodEnum<{
+            mark: "mark";
+            downgrade: "downgrade";
+            hide: "hide";
+        }>;
+        originalSeverity: z.ZodOptional<z.ZodEnum<{
+            error: "error";
+            warning: "warning";
+            info: "info";
+        }>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type IntentFinding = z.infer<typeof IntentFindingSchema>;
 
-export { ACCEPTS_NULL, type AuthoredBoundary, type AuthoredInputField, type AuthoredReceives, type AuthoredRestReceives, type AuthoredShape, type BodyShape, BodyShapeSchema, type Boundary, type BoundaryIntent, type BoundaryIntentSummary, BoundarySchema, type BoundaryTransition, type EffectOutcome, type IntentCondition, type IntentDoc, IntentDocSchema, type IntentEffect, type IntentFinding, type IntentFindingKind, IntentFindingKindSchema, IntentFindingSchema, type IntentFindingSeverity, IntentFindingSeveritySchema, type IntentFindingSuppression, IntentFindingSuppressionSchema, type IntentInputField, type IntentOutcome, type IntentOutcomeKind, type IntentRef, IntentRefSchema, type IntentSource, IntentSourceSchema, type IntentSummary, type Prd, type PrdScenario, type PrdScenarioSummary, type PrdSummary, PrimitiveTypeName, type When, type WhenClause, blanksLeftEmpty, fillBlanks, intentDocToSummary, toBoundaryBinding, toReceives };
+export { ACCEPTS_NULL, AlwaysEffectSchema, type AuthoredBoundary, type AuthoredConstant, type AuthoredInputField, type AuthoredReceives, type AuthoredRestReceives, type AuthoredShape, type BodyShape, BodyShapeSchema, type Boundary, type BoundaryIntent, type BoundaryIntentSummary, BoundarySchema, type BoundaryTransition, type ChangeEntry, type ChangeList, ChangeListSchema, type ChangeListSummary, type ChangeOutcome, type ChangeSubject, type ChangeVerb, type CoveringTestSpelling, type DeclaredAlways, type DeclaredEffect, EffectLineSchema, type EffectOutcome, EffectOutcomeSchema, type ExplainedChange, type ExplainedEntry, INPUT_SOURCE_PREFIX, type IntentAlways, type IntentChange, type IntentCondition, type IntentDoc, IntentDocSchema, type IntentEffect, type IntentFinding, type IntentFindingKind, IntentFindingKindSchema, IntentFindingSchema, type IntentFindingSeverity, IntentFindingSeveritySchema, type IntentFindingSuppression, IntentFindingSuppressionSchema, type IntentInputField, type IntentOutcome, type IntentOutcomeKind, type IntentRef, IntentRefSchema, type IntentSource, IntentSourceSchema, type IntentSummary, type IntentValueSource, NODE_ID_SEPARATOR, type ParsedChangeList, type Prd, type PrdScenario, type PrdScenarioSummary, type PrdSummary, PrimitiveTypeName, type When, type WhenClause, blanksLeftEmpty, changeListToSummary, fillBlanks, intentDocToSummary, parseChangeList, toBoundaryBinding, toCoveringTest, toIntentEffect, toReceives };