@suss/intent-ir 0.20.0 → 0.21.1

package/README.md

@@ -6,9 +6,109 @@ The team-authored side of the loop: what the code was *meant* to do, in a form t
 
 Two citizens, discriminated by `kind`, both built on `@suss/ir-core` so intent and behaviour describe boundaries the same way:
 
-- **System intent** (`kind: boundary`): what one boundary should do, as named outcomes. The boundary is REST **or** function-call; each outcome is a `response` (status + body), a `returns` (a function/handler return value), or a `throws` (an error). The function-call form is what lets suss check its own non-HTTP surface.
+- **System intent** (`kind: boundary`): what one boundary should do, as named outcomes. The boundary is REST, function-call, message-bus, storage or unit-invocation, and every field of one comes off the `@suss/ir-core` schema for that protocol.
 - **Outcome intent** (`kind: prd`): human `when` / `expect` scenarios, each with an optional `link` to a system-intent outcome (`<intent-name>.<outcome-id>`). A scenario with no `link` is a valid state to be in: it reads fully, and nothing has linked it to an outcome yet.
 
+## What an outcome is
+
+A transition says three things: what it turned on, how it ends, and what it did.
+
+**What it turned on**: `when`, a list of clauses in the same verbs `results` uses.
+
+```yaml
+transitions:
+  - id: invoice-not-found
+    when:
+      - reads: aws.dynamodb:Invoices
+        finds: nothing
+    response:
+      status: 404
+
+  - id: invoice-settled
+    when:
+      - reads: aws.dynamodb:Invoices
+        finds: something
+        where: settledAt is set
+    response:
+      status: 409
+
+  - id: invoice-returned
+    when:
+      - reads: aws.dynamodb:Invoices
+        finds: something
+        where: settledAt is missing
+    response:
+      status: 200
+    results:
+      - reads: aws.dynamodb:Invoices
+        by: invoiceId
+```
+
+A clause says which subject, then at most one thing about it.
+
+The subject is a boundary verb (`reads`, `writes`) whose value is the boundary's name, or `input:` with the path the caller sent. Those come from the IR's own subject types: a guard on the result of a call that crossed a boundary becomes the boundary form, one on an input becomes `input:`, and anything else falls back.
+
+The check is one of `finds` (`nothing` or `something`, what a lookup came back with), `is` (`set`, `missing`, `null`, `a string`), `equals`, or `has`. `where` narrows the clause with whatever the guard said about a deeper read of the same result.
+
+A fall-through branch states its own condition rather than pointing at the ones above it, since the summary records that branch's guards as the negations of theirs. `otherwise` is left for the one case that has none to state, which is a default branch the summary recorded nothing for. A word that means "not the branches above" would change what it claims the moment somebody inserts a transition over it, in a file people hand-edit.
+
+A guard that maps to none of this keeps a sentence, and `when` written as one plain string stays valid, which is what existing authored documents use.
+
+The point of naming the boundary is that the line survives a rename of the variable the source used, and that the checker can compare it. `when: "!doc.send().Item"` could do neither.
+
+**How it ends**: at most one of `response` (a status and a body), `returns` (a function or handler return value), or `throws` (an error).
+
+**What it did**: `results`, a list of the effects the outcome has, written in the verbs `suss ask` asks with.
+
+```yaml
+transitions:
+  - id: invoice-recorded
+    when: the message gives an invoice id we have not recorded
+    returns:
+      body:
+        properties:
+          recorded: { type: boolean }
+    results:
+      - writes: aws.dynamodb:Invoices
+```
+
+`suss ask "what writes aws.dynamodb:Invoices"` is the question and this is the assertion, spelled the same way. The key is the verb, `reads`, `writes` or `invokes`, which are the three `relationsOf` in `@suss/behavioral-ir` gives an effect. The value is the boundary's own name, the string every report writes and `namesBoundary` in `@suss/ir-core` resolves, so what you type in a document and what you type at `ask` pick out the same boundary. Nothing here is per protocol, so a queue consumer and a table writer say what they do without a fourth outcome shape each.
+
+`invokes` is the verb for calling a deployed unit by name, which is how a service built out of Lambdas hangs together:
+
+```yaml
+    results:
+      - invokes: unit:lambda ArchiveWorker
+```
+
+A run that reads the deployment template gives a unit its name, so the boundary a document declares is `unit:lambda ReportBuilder`. The callee on a `results` line is spelled the same way, even when the invoking code reaches it through an env var: `deploymentOf` in `@suss/behavioral-ir` says which resource the template points that variable at, and the drafter and the intent checker both go through it, so a document says which function rather than which variable. A run with no template in it has nothing to put in, and then the line keeps the code's own spelling, `unit:lambda {ARCHIVE_WORKER_FUNCTION}`, and the document's header says which variable it is waiting on. A store the code reaches through a variable works the same way.
+
+A clause can go further, since the summary does. `fields` is the columns the access touches and `by` is what it picks the item out by:
+
+```yaml
+    results:
+      - reads: aws.dynamodb:Accounts
+        by: accountId
+      - writes: aws.dynamodb:Profiles
+        fields: [email, phone, address]
+```
+
+Both are optional and a clause with only the verb and the name means what it always did. What they buy is that "the customer's contact details are erased" stops being satisfied by any write at all to that table. The checker asks that the access cover every column the clause stated; an access that states none is unread rather than empty (no pack parses a DynamoDB `UpdateExpression`), and one that asked for every column covers whatever the clause stated.
+
+The outcome id stays free-form on purpose. That is where a person writes what the outcome means, and it is what a PRD scenario links to: `invoice-intake.invoice-recorded`, read as "a duplicate delivery changes nothing". A `kind: prd` document is the level where a scenario reads as prose; `kind: boundary` is system intent for engineers, so it stays structural.
+
+Adding `results` changes nothing about `response`, `returns` and `throws`. A doc that states only those parses and pairs the way it always did.
+
+## Which boundaries pair, and which are pending
+
+A boundary intent pairs when its boundary has a key. REST has one from its method and path, a function-call export has one from its package and export path, a message-bus boundary has one from its channel, and an invoked unit has one from its deployment target and the name the platform knows it by. A unit whose name only the runtime settles has none, so a document for one is authorable and reported `unkeyableBoundary`.
+
+A store has none. `storage.ts` in `@suss/ir-core` returns null for a storage identity key on purpose: a container name can be a pattern with holes that only a caller or the deployment settles, and the storage pass in `@suss/checker` grounds it before pairing. So a `kind: boundary` doc whose boundary is a store is authorable, and the checker reports it as `unkeyableBoundary` and puts it in `unchecked` rather than pretending to have compared it. That is the same pending state a module-level function-call boundary is in.
+
+What does pair today is a store named as the target of an effect: put `- writes: aws.dynamodb:Invoices` on an outcome of the boundary that touches the store, and the checker compares it against the storage accesses on that boundary's transitions.
+
+Every boundary kind has a name of its own in `@suss/ir-core`, `storageLabel` being the one this change added, so an effect always takes a label and never a structured block. A binding with no name at all, a REST call whose method and path the code never settles, is left out of a draft rather than written as a string nobody would type back.
+
 ```ts
 import { IntentDocSchema, intentDocToSummary } from "@suss/intent-ir";
 
@@ -26,7 +126,7 @@ It is a peer of `@suss/behavioral-ir`; both build on `@suss/ir-core`. Readers (e
 
 ## Status
 
-v0: REST + function-call system intent, PRD outcome intent with optional links. The checker integration and reader migration build on this.
+v0: REST, function-call, message-bus, storage and unit-invocation system intent, effects as outcomes, PRD outcome intent with optional links. GraphQL, runtime-config and metric boundaries have no block yet.
 
 ## Coverage
 

package/dist/index.cjs

@@ -29,7 +29,9 @@ __export(index_exports, {
   IntentFindingSuppressionSchema: () => IntentFindingSuppressionSchema,
   IntentRefSchema: () => IntentRefSchema,
   IntentSourceSchema: () => IntentSourceSchema,
-  intentDocToSummary: () => intentDocToSummary
+  blanksLeftEmpty: () => blanksLeftEmpty,
+  intentDocToSummary: () => intentDocToSummary,
+  toBoundaryBinding: () => toBoundaryBinding
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -55,8 +57,12 @@ var IntentFindingKindSchema = import_zod.z.enum([
   // scenario carries no structured link (info — a valid pending state)
   "danglingScenarioLink",
   // link names an intent / outcome no boundary intent declares
-  "ambiguousScenarioLink"
+  "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 = import_zod.z.enum(["error", "warning", "info"]);
 var IntentRefSchema = import_zod.z.object({
@@ -106,7 +112,23 @@ var IntentFindingSchema = import_zod.z.object({
 
 // src/schema.ts
 var import_zod2 = require("zod");
+var import_ir_core = require("@suss/ir-core");
 var IntentSourceSchema = import_zod2.z.enum(["author", "inferred", "inferred, curated"]).default("author");
+var UNCURATED_SOURCE = "inferred";
+var CURATED_FIELDS = ["title", "purpose", "audience", "when", "expect"];
+function blankIn(field) {
+  return field.slice(field.lastIndexOf(".") + 1);
+}
+function blanksLeftEmpty(doc, failedFields) {
+  if (doc.source !== UNCURATED_SOURCE) {
+    return [];
+  }
+  const blanks = failedFields.map(blankIn);
+  if (blanks.length === 0 || !blanks.every((field) => CURATED_FIELDS.includes(field))) {
+    return [];
+  }
+  return CURATED_FIELDS.filter((blank) => blanks.includes(blank));
+}
 var PrimitiveTypeName = import_zod2.z.enum([
   "string",
   "integer",
@@ -151,9 +173,29 @@ var FunctionCallBoundarySchema = import_zod2.z.object({
   /** Path to the export within the package (sub-path + nested names). */
   exportPath: import_zod2.z.array(import_zod2.z.string()).optional()
 });
+var MessageBusBoundarySchema = import_zod2.z.object({
+  semantics: import_zod2.z.literal("message-bus"),
+  messageBus: import_ir_core.MessageBusSemanticsSchema.shape.messageBus,
+  channel: import_ir_core.MessageBusSemanticsSchema.shape.channel.default(null)
+});
+var StorageBoundarySchema = import_zod2.z.object({
+  semantics: import_zod2.z.literal("storage"),
+  storageSystem: import_ir_core.StorageSemanticsSchema.shape.storageSystem,
+  scope: import_ir_core.StorageSemanticsSchema.shape.scope.default("default"),
+  container: import_ir_core.StorageSemanticsSchema.shape.container.default(null),
+  accessPath: import_ir_core.StorageSemanticsSchema.shape.accessPath.default(null)
+});
+var UnitInvocationBoundarySchema = import_zod2.z.object({
+  semantics: import_zod2.z.literal("unit-invocation"),
+  deploymentTarget: import_ir_core.UnitInvocationSemanticsSchema.shape.deploymentTarget,
+  instanceName: import_ir_core.UnitInvocationSemanticsSchema.shape.instanceName.default(null)
+});
 var BoundarySchema = import_zod2.z.discriminatedUnion("semantics", [
   RestBoundarySchema,
-  FunctionCallBoundarySchema
+  FunctionCallBoundarySchema,
+  MessageBusBoundarySchema,
+  StorageBoundarySchema,
+  UnitInvocationBoundarySchema
 ]);
 var ResponseOutcomeSchema = import_zod2.z.object({
   status: import_zod2.z.number().int().min(100).max(599),
@@ -168,18 +210,70 @@ var ThrowsOutcomeSchema = import_zod2.z.object({
 function emptyIfNull(schema) {
   return import_zod2.z.preprocess((v) => v === null ? {} : v, schema);
 }
+var ONE_OR_MORE = import_zod2.z.union([
+  import_zod2.z.string().min(1),
+  import_zod2.z.array(import_zod2.z.string().min(1)).min(1)
+]);
+var EFFECT_BY_VERB = import_ir_core.EffectRelationSchema.options.map(
+  (verb) => import_zod2.z.strictObject({
+    [verb]: import_zod2.z.string().min(1),
+    fields: import_zod2.z.array(import_zod2.z.string().min(1)).min(1).optional(),
+    by: ONE_OR_MORE.optional()
+  })
+);
+var EffectOutcomeSchema = import_zod2.z.union(EFFECT_BY_VERB);
+var CHECKS = {
+  /** What a lookup came back with. */
+  finds: import_zod2.z.enum(["nothing", "something"]),
+  /** What state the value was in: `set`, `missing`, `null`, `a string`. */
+  is: import_zod2.z.string().min(1),
+  /** The value it was equal to. */
+  equals: import_zod2.z.union([import_zod2.z.string(), import_zod2.z.number(), import_zod2.z.boolean(), import_zod2.z.null()]),
+  /** A property it had. */
+  has: import_zod2.z.string().min(1)
+};
+var SUBJECT_KEYS = [
+  ...import_ir_core.EffectRelationSchema.options,
+  "input"
+];
+var WHEN_CLAUSE_BY_SUBJECT = SUBJECT_KEYS.map(
+  (key) => import_zod2.z.strictObject({
+    [key]: import_zod2.z.string().min(1),
+    where: import_zod2.z.string().min(1).optional(),
+    ...Object.fromEntries(
+      Object.entries(CHECKS).map(([check, schema]) => [
+        check,
+        schema.optional()
+      ])
+    )
+  }).refine(
+    (clause) => Object.keys(CHECKS).filter(
+      (check) => clause[check] !== void 0
+    ).length <= 1,
+    {
+      message: `a when clause says at most one of ${Object.keys(CHECKS).join(", ")} about its subject`
+    }
+  )
+);
+var WhenSchema = import_zod2.z.union([
+  import_zod2.z.string().min(1),
+  import_zod2.z.array(import_zod2.z.union([import_zod2.z.string().min(1), ...WHEN_CLAUSE_BY_SUBJECT])).min(1)
+]);
 var BoundaryTransitionSchema = import_zod2.z.object({
   id: import_zod2.z.string().min(1),
-  when: import_zod2.z.string().min(1),
+  when: WhenSchema,
   response: emptyIfNull(ResponseOutcomeSchema).optional(),
   returns: emptyIfNull(ReturnsOutcomeSchema).optional(),
-  throws: emptyIfNull(ThrowsOutcomeSchema).optional()
-}).refine(
-  (t) => [t.response, t.returns, t.throws].filter((o) => o !== void 0).length === 1,
-  {
-    message: "each transition must declare exactly one outcome: response, returns, or throws"
-  }
-);
+  throws: emptyIfNull(ThrowsOutcomeSchema).optional(),
+  results: import_zod2.z.array(EffectOutcomeSchema).min(1).optional()
+}).refine((t) => endingsOf(t).length <= 1, {
+  message: "a transition ends one way: give it at most one of response, returns, or throws"
+}).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"
+});
+function endingsOf(t) {
+  return [t.response, t.returns, t.throws].filter((o) => o !== void 0);
+}
 var BoundaryIntentSchema = import_zod2.z.object({
   kind: import_zod2.z.literal("boundary"),
   /** Name PRDs reference outcomes through: `<name>.<transition-id>`. */
@@ -223,7 +317,7 @@ var IntentDocSchema = import_zod2.z.discriminatedUnion("kind", [
 ]);
 
 // src/summary.ts
-var import_ir_core = require("@suss/ir-core");
+var import_ir_core2 = require("@suss/ir-core");
 function intentDocToSummary(doc) {
   if (doc.kind === "prd") {
     return prdToSummary(doc);
@@ -256,26 +350,105 @@ function prdToSummary(doc) {
     }))
   };
 }
-function toBoundaryBinding(boundary) {
-  if (boundary.semantics === "rest") {
-    return (0, import_ir_core.restBinding)({
-      transport: boundary.transport,
-      method: boundary.method,
-      path: boundary.path,
-      recognition: "intent"
-    });
-  }
-  return (0, import_ir_core.functionCallBinding)({
+var BINDINGS = {
+  rest: (boundary) => (0, import_ir_core2.restBinding)({
+    transport: boundary.transport,
+    method: boundary.method,
+    path: boundary.path,
+    recognition: "intent"
+  }),
+  "function-call": (boundary) => (0, import_ir_core2.functionCallBinding)({
     transport: boundary.transport,
     recognition: "intent",
     ...boundary.module !== void 0 ? { module: boundary.module } : {},
     ...boundary.exportName !== void 0 ? { exportName: boundary.exportName } : {},
     ...boundary.package !== void 0 ? { package: boundary.package } : {},
     ...boundary.exportPath !== void 0 ? { exportPath: boundary.exportPath } : {}
-  });
+  }),
+  "message-bus": (boundary) => (0, import_ir_core2.messageBusBinding)({
+    recognition: "intent",
+    messageBus: boundary.messageBus,
+    channel: boundary.channel
+  }),
+  "unit-invocation": (boundary) => (0, import_ir_core2.unitInvocationBinding)({
+    recognition: "intent",
+    deploymentTarget: boundary.deploymentTarget,
+    instanceName: boundary.instanceName
+  }),
+  storage: (boundary) => (0, import_ir_core2.storageBinding)({
+    recognition: "intent",
+    storageSystem: boundary.storageSystem,
+    scope: boundary.scope,
+    container: boundary.container,
+    accessPath: boundary.accessPath
+  })
+};
+function toBoundaryBinding(boundary) {
+  const build = BINDINGS[boundary.semantics];
+  return build(boundary);
+}
+var VERBS = import_ir_core2.EffectRelationSchema.options;
+function toEffect(declared) {
+  const [does, names] = Object.entries(declared).find(
+    ([key]) => VERBS.includes(key)
+  );
+  return {
+    does,
+    names,
+    fields: declared.fields ?? [],
+    by: oneOrMore(declared.by)
+  };
+}
+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];
+    if (names !== void 0) {
+      return { does, names, fields: [], by: [] };
+    }
+  }
+  return null;
+}
+function toCondition(clause) {
+  if (typeof clause === "string") {
+    return { at: null, input: null, finds: null, said: clause };
+  }
+  const at = subjectOf(clause);
+  return {
+    at,
+    input: clause.input ?? null,
+    finds: clause.finds ?? null,
+    said: saidAsOneLine(clause, at)
+  };
+}
+function saidAsOneLine(clause, at) {
+  const subject = at !== null ? `${at.does} ${at.names}` : `input ${String(clause.input)}`;
+  const check = CHECK_KEYS.map(
+    (key) => clause[key] === void 0 ? null : `${key} ${String(clause[key])}`
+  ).find((said) => said !== null);
+  const narrows = clause.where === void 0 ? null : `where ${clause.where}`;
+  return [subject, check, narrows].filter((part) => part !== null).join(" ");
+}
+var CHECK_KEYS = ["finds", "is", "equals", "has"];
+function toConditions(when) {
+  return (typeof when === "string" ? [when] : when).map(toCondition);
+}
+function whenAsOneLine(when) {
+  return typeof when === "string" ? when : toConditions(when).map((condition) => condition.said).join(" and ");
 }
 function toOutcome(t) {
-  const base = { id: t.id, when: t.when };
+  const effects = (t.results ?? []).map(toEffect);
+  const base = {
+    id: t.id,
+    when: whenAsOneLine(t.when),
+    conditions: toConditions(t.when),
+    effects
+  };
   if (t.response !== void 0) {
     return {
       ...base,
@@ -294,13 +467,16 @@ function toOutcome(t) {
       errorType: null
     };
   }
-  return {
-    ...base,
-    kind: "throw",
-    status: null,
-    body: null,
-    errorType: t.throws?.errorType ?? null
-  };
+  if (t.throws !== void 0) {
+    return {
+      ...base,
+      kind: "throw",
+      status: null,
+      body: null,
+      errorType: t.throws.errorType ?? null
+    };
+  }
+  return { ...base, kind: "effect", status: null, body: null, errorType: null };
 }
 function bodyToTypeShape(body) {
   if (!("type" in body)) {
@@ -349,5 +525,7 @@ var PRIMITIVE_TYPE_SHAPES = {
   IntentFindingSuppressionSchema,
   IntentRefSchema,
   IntentSourceSchema,
-  intentDocToSummary
+  blanksLeftEmpty,
+  intentDocToSummary,
+  toBoundaryBinding
 });

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { BoundaryBinding, TypeShape } from '@suss/ir-core';
+import { EffectRelation, BoundaryBinding, TypeShape } from '@suss/ir-core';
 
 declare const IntentFindingKindSchema: z.ZodEnum<{
     uncoveredOutcome: "uncoveredOutcome";
@@ -10,6 +10,7 @@ declare const IntentFindingKindSchema: z.ZodEnum<{
     unlinkedScenario: "unlinkedScenario";
     danglingScenarioLink: "danglingScenarioLink";
     ambiguousScenarioLink: "ambiguousScenarioLink";
+    undescribedOutcome: "undescribedOutcome";
 }>;
 type IntentFindingKind = z.infer<typeof IntentFindingKindSchema>;
 declare const IntentFindingSeveritySchema: z.ZodEnum<{
@@ -53,6 +54,7 @@ declare const IntentFindingSchema: z.ZodObject<{
         unlinkedScenario: "unlinkedScenario";
         danglingScenarioLink: "danglingScenarioLink";
         ambiguousScenarioLink: "ambiguousScenarioLink";
+        undescribedOutcome: "undescribedOutcome";
     }>;
     severity: z.ZodEnum<{
         error: "error";
@@ -91,6 +93,16 @@ declare const IntentSourceSchema: z.ZodDefault<z.ZodEnum<{
     inferred: "inferred";
     "inferred, curated": "inferred, curated";
 }>>;
+/**
+ * The blanks a draft is still waiting on, given which fields its schema
+ * failures landed on. Empty for a doc that failed some other way, so a
+ * reader can tell an uncurated draft from a broken file.
+ *
+ * `suss infer intent` writes those fields empty, which the schema
+ * rejects on purpose: an uncurated draft is not something to check yet,
+ * and a placeholder that validated would read as finished.
+ */
+declare function blanksLeftEmpty(doc: unknown, failedFields: string[]): string[];
 interface AuthoredShape {
     type: z.infer<typeof PrimitiveTypeName> | "array" | "object";
     items?: AuthoredShape | undefined;
@@ -113,10 +125,59 @@ declare const BoundarySchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     exportName: z.ZodOptional<z.ZodString>;
     package: z.ZodOptional<z.ZodString>;
     exportPath: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>, z.ZodObject<{
+    semantics: z.ZodLiteral<"message-bus">;
+    messageBus: z.ZodEnum<{
+        aws_sqs: "aws_sqs";
+        "aws.sns": "aws.sns";
+        s3: "s3";
+        eventbridge: "eventbridge";
+        bullmq: "bullmq";
+        kafka: "kafka";
+        nats: "nats";
+        "cloudflare-queues": "cloudflare-queues";
+        "cloudflare-cron": "cloudflare-cron";
+        "cloudflare-tail": "cloudflare-tail";
+    }>;
+    channel: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>, z.ZodObject<{
+    semantics: z.ZodLiteral<"storage">;
+    storageSystem: z.ZodString;
+    scope: z.ZodDefault<z.ZodString>;
+    container: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    accessPath: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>, z.ZodObject<{
+    semantics: z.ZodLiteral<"unit-invocation">;
+    deploymentTarget: z.ZodEnum<{
+        lambda: "lambda";
+        "ecs-task": "ecs-task";
+        container: "container";
+        "k8s-deployment": "k8s-deployment";
+        worker: "worker";
+    }>;
+    instanceName: z.ZodDefault<z.ZodNullable<z.ZodString>>;
 }, z.core.$strip>], "semantics">;
+/** One effect, written `- writes: postgresql:invoices`. */
+type DeclaredEffect = Partial<Record<EffectRelation, string>> & {
+    /** The columns it touches, when the outcome turns on which ones. */
+    fields?: string[];
+    /** What it picks the item out by. */
+    by?: string | string[];
+};
+declare const EffectOutcomeSchema: z.ZodUnion<[z.ZodType<DeclaredEffect, unknown, z.core.$ZodTypeInternals<DeclaredEffect, unknown>>, ...z.ZodType<DeclaredEffect, unknown, z.core.$ZodTypeInternals<DeclaredEffect, unknown>>[]]>;
+/** One clause of a structured `when`, or the sentence for a guard that maps to none. */
+type WhenClause = string | ({
+    where?: string;
+} & Partial<Record<EffectRelation | "input", string>> & {
+    finds?: "nothing" | "something";
+    is?: string;
+    equals?: string | number | boolean | null;
+    has?: string;
+});
+declare const WhenSchema: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodType<WhenClause, unknown, z.core.$ZodTypeInternals<WhenClause, unknown>>, ...z.ZodType<WhenClause, unknown, z.core.$ZodTypeInternals<WhenClause, unknown>>[]]>>]>;
 declare const BoundaryTransitionSchema: z.ZodObject<{
     id: z.ZodString;
-    when: z.ZodString;
+    when: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodType<WhenClause, unknown, z.core.$ZodTypeInternals<WhenClause, unknown>>, ...z.ZodType<WhenClause, unknown, z.core.$ZodTypeInternals<WhenClause, unknown>>[]]>>]>;
     response: z.ZodOptional<z.ZodPreprocess<z.ZodObject<{
         status: z.ZodNumber;
         body: z.ZodOptional<z.ZodUnion<readonly [z.ZodType<AuthoredShape, unknown, z.core.$ZodTypeInternals<AuthoredShape, unknown>>, z.ZodObject<{
@@ -133,6 +194,7 @@ declare const BoundaryTransitionSchema: z.ZodObject<{
     throws: z.ZodOptional<z.ZodPreprocess<z.ZodObject<{
         errorType: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
+    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.$strip>;
 declare const BoundaryIntentSchema: z.ZodObject<{
     kind: z.ZodLiteral<"boundary">;
@@ -156,10 +218,41 @@ declare const BoundaryIntentSchema: z.ZodObject<{
         exportName: z.ZodOptional<z.ZodString>;
         package: z.ZodOptional<z.ZodString>;
         exportPath: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>, z.ZodObject<{
+        semantics: z.ZodLiteral<"message-bus">;
+        messageBus: z.ZodEnum<{
+            aws_sqs: "aws_sqs";
+            "aws.sns": "aws.sns";
+            s3: "s3";
+            eventbridge: "eventbridge";
+            bullmq: "bullmq";
+            kafka: "kafka";
+            nats: "nats";
+            "cloudflare-queues": "cloudflare-queues";
+            "cloudflare-cron": "cloudflare-cron";
+            "cloudflare-tail": "cloudflare-tail";
+        }>;
+        channel: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>, z.ZodObject<{
+        semantics: z.ZodLiteral<"storage">;
+        storageSystem: z.ZodString;
+        scope: z.ZodDefault<z.ZodString>;
+        container: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        accessPath: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>, z.ZodObject<{
+        semantics: z.ZodLiteral<"unit-invocation">;
+        deploymentTarget: z.ZodEnum<{
+            lambda: "lambda";
+            "ecs-task": "ecs-task";
+            container: "container";
+            "k8s-deployment": "k8s-deployment";
+            worker: "worker";
+        }>;
+        instanceName: z.ZodDefault<z.ZodNullable<z.ZodString>>;
     }, z.core.$strip>], "semantics">;
     transitions: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
-        when: z.ZodString;
+        when: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodType<WhenClause, unknown, z.core.$ZodTypeInternals<WhenClause, unknown>>, ...z.ZodType<WhenClause, unknown, z.core.$ZodTypeInternals<WhenClause, unknown>>[]]>>]>;
         response: z.ZodOptional<z.ZodPreprocess<z.ZodObject<{
             status: z.ZodNumber;
             body: z.ZodOptional<z.ZodUnion<readonly [z.ZodType<AuthoredShape, unknown, z.core.$ZodTypeInternals<AuthoredShape, unknown>>, z.ZodObject<{
@@ -176,6 +269,7 @@ declare const BoundaryIntentSchema: z.ZodObject<{
         throws: z.ZodOptional<z.ZodPreprocess<z.ZodObject<{
             errorType: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>>;
+        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.$strip>>;
 }, z.core.$strip>;
 declare const PrdScenarioSchema: z.ZodObject<{
@@ -223,10 +317,41 @@ declare const IntentDocSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         exportName: z.ZodOptional<z.ZodString>;
         package: z.ZodOptional<z.ZodString>;
         exportPath: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>, z.ZodObject<{
+        semantics: z.ZodLiteral<"message-bus">;
+        messageBus: z.ZodEnum<{
+            aws_sqs: "aws_sqs";
+            "aws.sns": "aws.sns";
+            s3: "s3";
+            eventbridge: "eventbridge";
+            bullmq: "bullmq";
+            kafka: "kafka";
+            nats: "nats";
+            "cloudflare-queues": "cloudflare-queues";
+            "cloudflare-cron": "cloudflare-cron";
+            "cloudflare-tail": "cloudflare-tail";
+        }>;
+        channel: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>, z.ZodObject<{
+        semantics: z.ZodLiteral<"storage">;
+        storageSystem: z.ZodString;
+        scope: z.ZodDefault<z.ZodString>;
+        container: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        accessPath: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>, z.ZodObject<{
+        semantics: z.ZodLiteral<"unit-invocation">;
+        deploymentTarget: z.ZodEnum<{
+            lambda: "lambda";
+            "ecs-task": "ecs-task";
+            container: "container";
+            "k8s-deployment": "k8s-deployment";
+            worker: "worker";
+        }>;
+        instanceName: z.ZodDefault<z.ZodNullable<z.ZodString>>;
     }, z.core.$strip>], "semantics">;
     transitions: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
-        when: z.ZodString;
+        when: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodType<WhenClause, unknown, z.core.$ZodTypeInternals<WhenClause, unknown>>, ...z.ZodType<WhenClause, unknown, z.core.$ZodTypeInternals<WhenClause, unknown>>[]]>>]>;
         response: z.ZodOptional<z.ZodPreprocess<z.ZodObject<{
             status: z.ZodNumber;
             body: z.ZodOptional<z.ZodUnion<readonly [z.ZodType<AuthoredShape, unknown, z.core.$ZodTypeInternals<AuthoredShape, unknown>>, z.ZodObject<{
@@ -243,6 +368,7 @@ declare const IntentDocSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         throws: z.ZodOptional<z.ZodPreprocess<z.ZodObject<{
             errorType: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>>;
+        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.$strip>>;
 }, z.core.$strip>, z.ZodObject<{
     kind: z.ZodLiteral<"prd">;
@@ -265,8 +391,12 @@ type IntentDoc = z.infer<typeof IntentDocSchema>;
 type BoundaryIntent = z.infer<typeof BoundaryIntentSchema>;
 type Prd = z.infer<typeof PrdSchema>;
 type PrdScenario = z.infer<typeof PrdScenarioSchema>;
+type When = z.infer<typeof WhenSchema>;
 type Boundary = z.infer<typeof BoundarySchema>;
+/** A boundary block as somebody writes it, before defaults are put in. */
+type AuthoredBoundary = z.input<typeof BoundarySchema>;
 type BoundaryTransition = z.infer<typeof BoundaryTransitionSchema>;
+type EffectOutcome = z.infer<typeof EffectOutcomeSchema>;
 type BodyShape = z.infer<typeof BodyShapeSchema>;
 type IntentSource = z.infer<typeof IntentSourceSchema>;
 declare const PrimitiveTypeName: z.ZodEnum<{
@@ -279,13 +409,44 @@ declare const PrimitiveTypeName: z.ZodEnum<{
 }>;
 type PrimitiveTypeName = z.infer<typeof PrimitiveTypeName>;
 
-/** How a boundary outcome resolves, the cross-kind unification. */
-type IntentOutcomeKind = "response" | "return" | "throw";
+/**
+ * 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";
+/** 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. */
+    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[];
+}
+/**
+ * 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.
+ */
+interface IntentCondition {
+    /** The boundary the guard read, when the clause says one. */
+    at: IntentEffect | null;
+    /** What the caller sent, when the clause says that instead. */
+    input: string | null;
+    /** Whether the lookup came back with something, when the clause says. */
+    finds: "nothing" | "something" | null;
+    /** The clause as one line, for a finding to quote. */
+    said: string;
+}
 interface IntentOutcome {
     /** Author-declared id PRD scenarios reference. */
     id: string;
-    /** The condition, in human terms (opaque to the checker). */
+    /** 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). */
     status: number | null;
@@ -293,6 +454,8 @@ interface IntentOutcome {
     body: TypeShape | null;
     /** Error type name, set only for `throw` outcomes when declared. */
     errorType: string | null;
+    /** The effects this outcome declares. Empty when it declares none. */
+    effects: IntentEffect[];
 }
 interface BoundaryIntentSummary {
     kind: "boundary";
@@ -322,5 +485,6 @@ interface PrdSummary {
 }
 type IntentSummary = BoundaryIntentSummary | PrdSummary;
 declare function intentDocToSummary(doc: IntentDoc): IntentSummary;
+declare function toBoundaryBinding(boundary: Boundary): BoundaryBinding;
 
-export { type BodyShape, BodyShapeSchema, type Boundary, type BoundaryIntent, type BoundaryIntentSummary, BoundarySchema, type BoundaryTransition, type IntentDoc, IntentDocSchema, type IntentFinding, type IntentFindingKind, IntentFindingKindSchema, IntentFindingSchema, type IntentFindingSeverity, IntentFindingSeveritySchema, type IntentFindingSuppression, IntentFindingSuppressionSchema, type IntentOutcome, type IntentOutcomeKind, type IntentRef, IntentRefSchema, type IntentSource, IntentSourceSchema, type IntentSummary, type Prd, type PrdScenario, type PrdScenarioSummary, type PrdSummary, PrimitiveTypeName, intentDocToSummary };
+export { type AuthoredBoundary, 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 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, intentDocToSummary, toBoundaryBinding };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { BoundaryBinding, TypeShape } from '@suss/ir-core';
+import { EffectRelation, BoundaryBinding, TypeShape } from '@suss/ir-core';
 
 declare const IntentFindingKindSchema: z.ZodEnum<{
     uncoveredOutcome: "uncoveredOutcome";
@@ -10,6 +10,7 @@ declare const IntentFindingKindSchema: z.ZodEnum<{
     unlinkedScenario: "unlinkedScenario";
     danglingScenarioLink: "danglingScenarioLink";
     ambiguousScenarioLink: "ambiguousScenarioLink";
+    undescribedOutcome: "undescribedOutcome";
 }>;
 type IntentFindingKind = z.infer<typeof IntentFindingKindSchema>;
 declare const IntentFindingSeveritySchema: z.ZodEnum<{
@@ -53,6 +54,7 @@ declare const IntentFindingSchema: z.ZodObject<{
         unlinkedScenario: "unlinkedScenario";
         danglingScenarioLink: "danglingScenarioLink";
         ambiguousScenarioLink: "ambiguousScenarioLink";
+        undescribedOutcome: "undescribedOutcome";
     }>;
     severity: z.ZodEnum<{
         error: "error";
@@ -91,6 +93,16 @@ declare const IntentSourceSchema: z.ZodDefault<z.ZodEnum<{
     inferred: "inferred";
     "inferred, curated": "inferred, curated";
 }>>;
+/**
+ * The blanks a draft is still waiting on, given which fields its schema
+ * failures landed on. Empty for a doc that failed some other way, so a
+ * reader can tell an uncurated draft from a broken file.
+ *
+ * `suss infer intent` writes those fields empty, which the schema
+ * rejects on purpose: an uncurated draft is not something to check yet,
+ * and a placeholder that validated would read as finished.
+ */
+declare function blanksLeftEmpty(doc: unknown, failedFields: string[]): string[];
 interface AuthoredShape {
     type: z.infer<typeof PrimitiveTypeName> | "array" | "object";
     items?: AuthoredShape | undefined;
@@ -113,10 +125,59 @@ declare const BoundarySchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     exportName: z.ZodOptional<z.ZodString>;
     package: z.ZodOptional<z.ZodString>;
     exportPath: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>, z.ZodObject<{
+    semantics: z.ZodLiteral<"message-bus">;
+    messageBus: z.ZodEnum<{
+        aws_sqs: "aws_sqs";
+        "aws.sns": "aws.sns";
+        s3: "s3";
+        eventbridge: "eventbridge";
+        bullmq: "bullmq";
+        kafka: "kafka";
+        nats: "nats";
+        "cloudflare-queues": "cloudflare-queues";
+        "cloudflare-cron": "cloudflare-cron";
+        "cloudflare-tail": "cloudflare-tail";
+    }>;
+    channel: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>, z.ZodObject<{
+    semantics: z.ZodLiteral<"storage">;
+    storageSystem: z.ZodString;
+    scope: z.ZodDefault<z.ZodString>;
+    container: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    accessPath: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>, z.ZodObject<{
+    semantics: z.ZodLiteral<"unit-invocation">;
+    deploymentTarget: z.ZodEnum<{
+        lambda: "lambda";
+        "ecs-task": "ecs-task";
+        container: "container";
+        "k8s-deployment": "k8s-deployment";
+        worker: "worker";
+    }>;
+    instanceName: z.ZodDefault<z.ZodNullable<z.ZodString>>;
 }, z.core.$strip>], "semantics">;
+/** One effect, written `- writes: postgresql:invoices`. */
+type DeclaredEffect = Partial<Record<EffectRelation, string>> & {
+    /** The columns it touches, when the outcome turns on which ones. */
+    fields?: string[];
+    /** What it picks the item out by. */
+    by?: string | string[];
+};
+declare const EffectOutcomeSchema: z.ZodUnion<[z.ZodType<DeclaredEffect, unknown, z.core.$ZodTypeInternals<DeclaredEffect, unknown>>, ...z.ZodType<DeclaredEffect, unknown, z.core.$ZodTypeInternals<DeclaredEffect, unknown>>[]]>;
+/** One clause of a structured `when`, or the sentence for a guard that maps to none. */
+type WhenClause = string | ({
+    where?: string;
+} & Partial<Record<EffectRelation | "input", string>> & {
+    finds?: "nothing" | "something";
+    is?: string;
+    equals?: string | number | boolean | null;
+    has?: string;
+});
+declare const WhenSchema: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodType<WhenClause, unknown, z.core.$ZodTypeInternals<WhenClause, unknown>>, ...z.ZodType<WhenClause, unknown, z.core.$ZodTypeInternals<WhenClause, unknown>>[]]>>]>;
 declare const BoundaryTransitionSchema: z.ZodObject<{
     id: z.ZodString;
-    when: z.ZodString;
+    when: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodType<WhenClause, unknown, z.core.$ZodTypeInternals<WhenClause, unknown>>, ...z.ZodType<WhenClause, unknown, z.core.$ZodTypeInternals<WhenClause, unknown>>[]]>>]>;
     response: z.ZodOptional<z.ZodPreprocess<z.ZodObject<{
         status: z.ZodNumber;
         body: z.ZodOptional<z.ZodUnion<readonly [z.ZodType<AuthoredShape, unknown, z.core.$ZodTypeInternals<AuthoredShape, unknown>>, z.ZodObject<{
@@ -133,6 +194,7 @@ declare const BoundaryTransitionSchema: z.ZodObject<{
     throws: z.ZodOptional<z.ZodPreprocess<z.ZodObject<{
         errorType: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
+    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.$strip>;
 declare const BoundaryIntentSchema: z.ZodObject<{
     kind: z.ZodLiteral<"boundary">;
@@ -156,10 +218,41 @@ declare const BoundaryIntentSchema: z.ZodObject<{
         exportName: z.ZodOptional<z.ZodString>;
         package: z.ZodOptional<z.ZodString>;
         exportPath: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>, z.ZodObject<{
+        semantics: z.ZodLiteral<"message-bus">;
+        messageBus: z.ZodEnum<{
+            aws_sqs: "aws_sqs";
+            "aws.sns": "aws.sns";
+            s3: "s3";
+            eventbridge: "eventbridge";
+            bullmq: "bullmq";
+            kafka: "kafka";
+            nats: "nats";
+            "cloudflare-queues": "cloudflare-queues";
+            "cloudflare-cron": "cloudflare-cron";
+            "cloudflare-tail": "cloudflare-tail";
+        }>;
+        channel: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>, z.ZodObject<{
+        semantics: z.ZodLiteral<"storage">;
+        storageSystem: z.ZodString;
+        scope: z.ZodDefault<z.ZodString>;
+        container: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        accessPath: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>, z.ZodObject<{
+        semantics: z.ZodLiteral<"unit-invocation">;
+        deploymentTarget: z.ZodEnum<{
+            lambda: "lambda";
+            "ecs-task": "ecs-task";
+            container: "container";
+            "k8s-deployment": "k8s-deployment";
+            worker: "worker";
+        }>;
+        instanceName: z.ZodDefault<z.ZodNullable<z.ZodString>>;
     }, z.core.$strip>], "semantics">;
     transitions: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
-        when: z.ZodString;
+        when: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodType<WhenClause, unknown, z.core.$ZodTypeInternals<WhenClause, unknown>>, ...z.ZodType<WhenClause, unknown, z.core.$ZodTypeInternals<WhenClause, unknown>>[]]>>]>;
         response: z.ZodOptional<z.ZodPreprocess<z.ZodObject<{
             status: z.ZodNumber;
             body: z.ZodOptional<z.ZodUnion<readonly [z.ZodType<AuthoredShape, unknown, z.core.$ZodTypeInternals<AuthoredShape, unknown>>, z.ZodObject<{
@@ -176,6 +269,7 @@ declare const BoundaryIntentSchema: z.ZodObject<{
         throws: z.ZodOptional<z.ZodPreprocess<z.ZodObject<{
             errorType: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>>;
+        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.$strip>>;
 }, z.core.$strip>;
 declare const PrdScenarioSchema: z.ZodObject<{
@@ -223,10 +317,41 @@ declare const IntentDocSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         exportName: z.ZodOptional<z.ZodString>;
         package: z.ZodOptional<z.ZodString>;
         exportPath: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>, z.ZodObject<{
+        semantics: z.ZodLiteral<"message-bus">;
+        messageBus: z.ZodEnum<{
+            aws_sqs: "aws_sqs";
+            "aws.sns": "aws.sns";
+            s3: "s3";
+            eventbridge: "eventbridge";
+            bullmq: "bullmq";
+            kafka: "kafka";
+            nats: "nats";
+            "cloudflare-queues": "cloudflare-queues";
+            "cloudflare-cron": "cloudflare-cron";
+            "cloudflare-tail": "cloudflare-tail";
+        }>;
+        channel: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>, z.ZodObject<{
+        semantics: z.ZodLiteral<"storage">;
+        storageSystem: z.ZodString;
+        scope: z.ZodDefault<z.ZodString>;
+        container: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+        accessPath: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>, z.ZodObject<{
+        semantics: z.ZodLiteral<"unit-invocation">;
+        deploymentTarget: z.ZodEnum<{
+            lambda: "lambda";
+            "ecs-task": "ecs-task";
+            container: "container";
+            "k8s-deployment": "k8s-deployment";
+            worker: "worker";
+        }>;
+        instanceName: z.ZodDefault<z.ZodNullable<z.ZodString>>;
     }, z.core.$strip>], "semantics">;
     transitions: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
-        when: z.ZodString;
+        when: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodType<WhenClause, unknown, z.core.$ZodTypeInternals<WhenClause, unknown>>, ...z.ZodType<WhenClause, unknown, z.core.$ZodTypeInternals<WhenClause, unknown>>[]]>>]>;
         response: z.ZodOptional<z.ZodPreprocess<z.ZodObject<{
             status: z.ZodNumber;
             body: z.ZodOptional<z.ZodUnion<readonly [z.ZodType<AuthoredShape, unknown, z.core.$ZodTypeInternals<AuthoredShape, unknown>>, z.ZodObject<{
@@ -243,6 +368,7 @@ declare const IntentDocSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         throws: z.ZodOptional<z.ZodPreprocess<z.ZodObject<{
             errorType: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>>;
+        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.$strip>>;
 }, z.core.$strip>, z.ZodObject<{
     kind: z.ZodLiteral<"prd">;
@@ -265,8 +391,12 @@ type IntentDoc = z.infer<typeof IntentDocSchema>;
 type BoundaryIntent = z.infer<typeof BoundaryIntentSchema>;
 type Prd = z.infer<typeof PrdSchema>;
 type PrdScenario = z.infer<typeof PrdScenarioSchema>;
+type When = z.infer<typeof WhenSchema>;
 type Boundary = z.infer<typeof BoundarySchema>;
+/** A boundary block as somebody writes it, before defaults are put in. */
+type AuthoredBoundary = z.input<typeof BoundarySchema>;
 type BoundaryTransition = z.infer<typeof BoundaryTransitionSchema>;
+type EffectOutcome = z.infer<typeof EffectOutcomeSchema>;
 type BodyShape = z.infer<typeof BodyShapeSchema>;
 type IntentSource = z.infer<typeof IntentSourceSchema>;
 declare const PrimitiveTypeName: z.ZodEnum<{
@@ -279,13 +409,44 @@ declare const PrimitiveTypeName: z.ZodEnum<{
 }>;
 type PrimitiveTypeName = z.infer<typeof PrimitiveTypeName>;
 
-/** How a boundary outcome resolves, the cross-kind unification. */
-type IntentOutcomeKind = "response" | "return" | "throw";
+/**
+ * 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";
+/** 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. */
+    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[];
+}
+/**
+ * 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.
+ */
+interface IntentCondition {
+    /** The boundary the guard read, when the clause says one. */
+    at: IntentEffect | null;
+    /** What the caller sent, when the clause says that instead. */
+    input: string | null;
+    /** Whether the lookup came back with something, when the clause says. */
+    finds: "nothing" | "something" | null;
+    /** The clause as one line, for a finding to quote. */
+    said: string;
+}
 interface IntentOutcome {
     /** Author-declared id PRD scenarios reference. */
     id: string;
-    /** The condition, in human terms (opaque to the checker). */
+    /** 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). */
     status: number | null;
@@ -293,6 +454,8 @@ interface IntentOutcome {
     body: TypeShape | null;
     /** Error type name, set only for `throw` outcomes when declared. */
     errorType: string | null;
+    /** The effects this outcome declares. Empty when it declares none. */
+    effects: IntentEffect[];
 }
 interface BoundaryIntentSummary {
     kind: "boundary";
@@ -322,5 +485,6 @@ interface PrdSummary {
 }
 type IntentSummary = BoundaryIntentSummary | PrdSummary;
 declare function intentDocToSummary(doc: IntentDoc): IntentSummary;
+declare function toBoundaryBinding(boundary: Boundary): BoundaryBinding;
 
-export { type BodyShape, BodyShapeSchema, type Boundary, type BoundaryIntent, type BoundaryIntentSummary, BoundarySchema, type BoundaryTransition, type IntentDoc, IntentDocSchema, type IntentFinding, type IntentFindingKind, IntentFindingKindSchema, IntentFindingSchema, type IntentFindingSeverity, IntentFindingSeveritySchema, type IntentFindingSuppression, IntentFindingSuppressionSchema, type IntentOutcome, type IntentOutcomeKind, type IntentRef, IntentRefSchema, type IntentSource, IntentSourceSchema, type IntentSummary, type Prd, type PrdScenario, type PrdScenarioSummary, type PrdSummary, PrimitiveTypeName, intentDocToSummary };
+export { type AuthoredBoundary, 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 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, intentDocToSummary, toBoundaryBinding };

package/dist/index.js

@@ -20,8 +20,12 @@ var IntentFindingKindSchema = z.enum([
   // scenario carries no structured link (info — a valid pending state)
   "danglingScenarioLink",
   // link names an intent / outcome no boundary intent declares
-  "ambiguousScenarioLink"
+  "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({
@@ -71,7 +75,28 @@ var IntentFindingSchema = z.object({
 
 // src/schema.ts
 import { z as z2 } from "zod";
+import {
+  EffectRelationSchema,
+  MessageBusSemanticsSchema,
+  StorageSemanticsSchema,
+  UnitInvocationSemanticsSchema
+} from "@suss/ir-core";
 var IntentSourceSchema = z2.enum(["author", "inferred", "inferred, curated"]).default("author");
+var UNCURATED_SOURCE = "inferred";
+var CURATED_FIELDS = ["title", "purpose", "audience", "when", "expect"];
+function blankIn(field) {
+  return field.slice(field.lastIndexOf(".") + 1);
+}
+function blanksLeftEmpty(doc, failedFields) {
+  if (doc.source !== UNCURATED_SOURCE) {
+    return [];
+  }
+  const blanks = failedFields.map(blankIn);
+  if (blanks.length === 0 || !blanks.every((field) => CURATED_FIELDS.includes(field))) {
+    return [];
+  }
+  return CURATED_FIELDS.filter((blank) => blanks.includes(blank));
+}
 var PrimitiveTypeName = z2.enum([
   "string",
   "integer",
@@ -116,9 +141,29 @@ var FunctionCallBoundarySchema = z2.object({
   /** Path to the export within the package (sub-path + nested names). */
   exportPath: z2.array(z2.string()).optional()
 });
+var MessageBusBoundarySchema = z2.object({
+  semantics: z2.literal("message-bus"),
+  messageBus: MessageBusSemanticsSchema.shape.messageBus,
+  channel: MessageBusSemanticsSchema.shape.channel.default(null)
+});
+var StorageBoundarySchema = z2.object({
+  semantics: z2.literal("storage"),
+  storageSystem: StorageSemanticsSchema.shape.storageSystem,
+  scope: StorageSemanticsSchema.shape.scope.default("default"),
+  container: StorageSemanticsSchema.shape.container.default(null),
+  accessPath: StorageSemanticsSchema.shape.accessPath.default(null)
+});
+var UnitInvocationBoundarySchema = z2.object({
+  semantics: z2.literal("unit-invocation"),
+  deploymentTarget: UnitInvocationSemanticsSchema.shape.deploymentTarget,
+  instanceName: UnitInvocationSemanticsSchema.shape.instanceName.default(null)
+});
 var BoundarySchema = z2.discriminatedUnion("semantics", [
   RestBoundarySchema,
-  FunctionCallBoundarySchema
+  FunctionCallBoundarySchema,
+  MessageBusBoundarySchema,
+  StorageBoundarySchema,
+  UnitInvocationBoundarySchema
 ]);
 var ResponseOutcomeSchema = z2.object({
   status: z2.number().int().min(100).max(599),
@@ -133,18 +178,70 @@ var ThrowsOutcomeSchema = z2.object({
 function emptyIfNull(schema) {
   return z2.preprocess((v) => v === null ? {} : v, schema);
 }
+var ONE_OR_MORE = z2.union([
+  z2.string().min(1),
+  z2.array(z2.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()
+  })
+);
+var EffectOutcomeSchema = z2.union(EFFECT_BY_VERB);
+var CHECKS = {
+  /** What a lookup came back with. */
+  finds: z2.enum(["nothing", "something"]),
+  /** What state the value was in: `set`, `missing`, `null`, `a string`. */
+  is: z2.string().min(1),
+  /** The value it was equal to. */
+  equals: z2.union([z2.string(), z2.number(), z2.boolean(), z2.null()]),
+  /** A property it had. */
+  has: z2.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(),
+    ...Object.fromEntries(
+      Object.entries(CHECKS).map(([check, schema]) => [
+        check,
+        schema.optional()
+      ])
+    )
+  }).refine(
+    (clause) => Object.keys(CHECKS).filter(
+      (check) => clause[check] !== void 0
+    ).length <= 1,
+    {
+      message: `a when clause says at most one of ${Object.keys(CHECKS).join(", ")} about its subject`
+    }
+  )
+);
+var WhenSchema = z2.union([
+  z2.string().min(1),
+  z2.array(z2.union([z2.string().min(1), ...WHEN_CLAUSE_BY_SUBJECT])).min(1)
+]);
 var BoundaryTransitionSchema = z2.object({
   id: z2.string().min(1),
-  when: z2.string().min(1),
+  when: WhenSchema,
   response: emptyIfNull(ResponseOutcomeSchema).optional(),
   returns: emptyIfNull(ReturnsOutcomeSchema).optional(),
-  throws: emptyIfNull(ThrowsOutcomeSchema).optional()
-}).refine(
-  (t) => [t.response, t.returns, t.throws].filter((o) => o !== void 0).length === 1,
-  {
-    message: "each transition must declare exactly one outcome: response, returns, or throws"
-  }
-);
+  throws: emptyIfNull(ThrowsOutcomeSchema).optional(),
+  results: z2.array(EffectOutcomeSchema).min(1).optional()
+}).refine((t) => endingsOf(t).length <= 1, {
+  message: "a transition ends one way: give it at most one of response, returns, or throws"
+}).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"
+});
+function endingsOf(t) {
+  return [t.response, t.returns, t.throws].filter((o) => o !== void 0);
+}
 var BoundaryIntentSchema = z2.object({
   kind: z2.literal("boundary"),
   /** Name PRDs reference outcomes through: `<name>.<transition-id>`. */
@@ -189,8 +286,12 @@ var IntentDocSchema = z2.discriminatedUnion("kind", [
 
 // src/summary.ts
 import {
+  EffectRelationSchema as EffectRelationSchema2,
   functionCallBinding,
-  restBinding
+  messageBusBinding,
+  restBinding,
+  storageBinding,
+  unitInvocationBinding
 } from "@suss/ir-core";
 function intentDocToSummary(doc) {
   if (doc.kind === "prd") {
@@ -224,26 +325,105 @@ function prdToSummary(doc) {
     }))
   };
 }
-function toBoundaryBinding(boundary) {
-  if (boundary.semantics === "rest") {
-    return restBinding({
-      transport: boundary.transport,
-      method: boundary.method,
-      path: boundary.path,
-      recognition: "intent"
-    });
-  }
-  return functionCallBinding({
+var BINDINGS = {
+  rest: (boundary) => restBinding({
+    transport: boundary.transport,
+    method: boundary.method,
+    path: boundary.path,
+    recognition: "intent"
+  }),
+  "function-call": (boundary) => functionCallBinding({
     transport: boundary.transport,
     recognition: "intent",
     ...boundary.module !== void 0 ? { module: boundary.module } : {},
     ...boundary.exportName !== void 0 ? { exportName: boundary.exportName } : {},
     ...boundary.package !== void 0 ? { package: boundary.package } : {},
     ...boundary.exportPath !== void 0 ? { exportPath: boundary.exportPath } : {}
-  });
+  }),
+  "message-bus": (boundary) => messageBusBinding({
+    recognition: "intent",
+    messageBus: boundary.messageBus,
+    channel: boundary.channel
+  }),
+  "unit-invocation": (boundary) => unitInvocationBinding({
+    recognition: "intent",
+    deploymentTarget: boundary.deploymentTarget,
+    instanceName: boundary.instanceName
+  }),
+  storage: (boundary) => storageBinding({
+    recognition: "intent",
+    storageSystem: boundary.storageSystem,
+    scope: boundary.scope,
+    container: boundary.container,
+    accessPath: boundary.accessPath
+  })
+};
+function toBoundaryBinding(boundary) {
+  const build = BINDINGS[boundary.semantics];
+  return build(boundary);
+}
+var VERBS = EffectRelationSchema2.options;
+function toEffect(declared) {
+  const [does, names] = Object.entries(declared).find(
+    ([key]) => VERBS.includes(key)
+  );
+  return {
+    does,
+    names,
+    fields: declared.fields ?? [],
+    by: oneOrMore(declared.by)
+  };
+}
+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];
+    if (names !== void 0) {
+      return { does, names, fields: [], by: [] };
+    }
+  }
+  return null;
+}
+function toCondition(clause) {
+  if (typeof clause === "string") {
+    return { at: null, input: null, finds: null, said: clause };
+  }
+  const at = subjectOf(clause);
+  return {
+    at,
+    input: clause.input ?? null,
+    finds: clause.finds ?? null,
+    said: saidAsOneLine(clause, at)
+  };
+}
+function saidAsOneLine(clause, at) {
+  const subject = at !== null ? `${at.does} ${at.names}` : `input ${String(clause.input)}`;
+  const check = CHECK_KEYS.map(
+    (key) => clause[key] === void 0 ? null : `${key} ${String(clause[key])}`
+  ).find((said) => said !== null);
+  const narrows = clause.where === void 0 ? null : `where ${clause.where}`;
+  return [subject, check, narrows].filter((part) => part !== null).join(" ");
+}
+var CHECK_KEYS = ["finds", "is", "equals", "has"];
+function toConditions(when) {
+  return (typeof when === "string" ? [when] : when).map(toCondition);
+}
+function whenAsOneLine(when) {
+  return typeof when === "string" ? when : toConditions(when).map((condition) => condition.said).join(" and ");
 }
 function toOutcome(t) {
-  const base = { id: t.id, when: t.when };
+  const effects = (t.results ?? []).map(toEffect);
+  const base = {
+    id: t.id,
+    when: whenAsOneLine(t.when),
+    conditions: toConditions(t.when),
+    effects
+  };
   if (t.response !== void 0) {
     return {
       ...base,
@@ -262,13 +442,16 @@ function toOutcome(t) {
       errorType: null
     };
   }
-  return {
-    ...base,
-    kind: "throw",
-    status: null,
-    body: null,
-    errorType: t.throws?.errorType ?? null
-  };
+  if (t.throws !== void 0) {
+    return {
+      ...base,
+      kind: "throw",
+      status: null,
+      body: null,
+      errorType: t.throws.errorType ?? null
+    };
+  }
+  return { ...base, kind: "effect", status: null, body: null, errorType: null };
 }
 function bodyToTypeShape(body) {
   if (!("type" in body)) {
@@ -316,5 +499,7 @@ export {
   IntentFindingSuppressionSchema,
   IntentRefSchema,
   IntentSourceSchema,
-  intentDocToSummary
+  blanksLeftEmpty,
+  intentDocToSummary,
+  toBoundaryBinding
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suss/intent-ir",
-  "version": "0.20.0",
+  "version": "0.21.1",
   "type": "module",
   "description": "Intent IR for suss — the team-authored side of the loop. PRD (outcome) intent and system intent, in shapes that pair against derived behavioral summaries.",
   "keywords": [
@@ -47,7 +47,7 @@
     "zod": "^4.0.0"
   },
   "dependencies": {
-    "@suss/ir-core": "0.20.0"
+    "@suss/ir-core": "0.21.1"
   },
   "devDependencies": {
     "tsup": "*",