@suss/ir-core 0.33.0 → 0.34.0

package/dist/index.cjs

@@ -31,6 +31,7 @@ __export(index_exports, {
   FunctionCallSemanticsSchema: () => FunctionCallSemanticsSchema,
   GraphqlOperationSemanticsSchema: () => GraphqlOperationSemanticsSchema,
   GraphqlResolverSemanticsSchema: () => GraphqlResolverSemanticsSchema,
+  IoSemanticsSchema: () => IoSemanticsSchema,
   MessageBusSemanticsSchema: () => MessageBusSemanticsSchema,
   MetricSemanticsSchema: () => MetricSemanticsSchema,
   NOTHING_DEPLOYED: () => NOTHING_DEPLOYED,
@@ -43,6 +44,7 @@ __export(index_exports, {
   StorageSemanticsSchema: () => StorageSemanticsSchema,
   SuppressionFileSchema: () => SuppressionFileSchema,
   SuppressionRuleSchema: () => SuppressionRuleSchema,
+  TEST_TITLE_SEPARATOR: () => TEST_TITLE_SEPARATOR,
   TypeShapeSchema: () => TypeShapeSchema,
   UnitInvocationSemanticsSchema: () => UnitInvocationSemanticsSchema,
   applySuppressionsToFindings: () => applySuppressionsToFindings,
@@ -76,12 +78,17 @@ __export(index_exports, {
   groundBinding: () => groundBinding,
   groundedPairingKey: () => groundedPairingKey,
   hasNameHole: () => hasNameHole,
+  ioBinding: () => ioBinding,
+  ioIdentityKey: () => ioIdentityKey,
   isGraphqlOperationBinding: () => isGraphqlOperationBinding,
+  isModuleName: () => isModuleName,
+  labelWithDetail: () => labelWithDetail,
   leavesTheProcess: () => leavesTheProcess,
   messageBusBinding: () => messageBusBinding,
   methodsAgree: () => methodsAgree,
   metricBinding: () => metricBinding,
   metricIdentityKey: () => metricIdentityKey,
+  moduleExportBinding: () => moduleExportBinding,
   namePatternFromSub: () => namePatternFromSub,
   namePatternKey: () => namePatternKey,
   nameReference: () => nameReference,
@@ -121,6 +128,7 @@ __export(index_exports, {
   storageContainerLabel: () => storageContainerLabel,
   storageLabel: () => storageLabel,
   storageSystemLabel: () => storageSystemLabel,
+  testUnitName: () => testUnitName,
   typeDefinitionKey: () => typeDefinitionKey,
   unitIdentityKey: () => unitIdentityKey,
   unitInvocationBinding: () => unitInvocationBinding,
@@ -156,15 +164,15 @@ var graphqlOperationSemantics = defineBoundarySemantics({
   behavior: {
     /**
      * An operation gets a data-and-errors document back, which the
-     * GraphQL contract checker reads. Status codes say nothing here.
+     * GraphQL contract checker reads. Status codes do not apply.
      */
     exchangesHttpResponses: false,
     leavesTheProcess: true,
     reportsUnpairedItself: false,
     identityKey: () => null,
-    /** Keyless by design; the dedicated pass pairs it by its document. */
+    /** No key on purpose. The dedicated pass pairs an operation by its document. */
     canPair: () => true,
-    /** "query GetUser". The contract checker pairs it, the key does not. */
+    /** `query GetUser`. Only for display, since the contract checker does the pairing. */
     displayLabel(semantics) {
       return `${semantics.operationType} ${semantics.operationName ?? "<anonymous>"}`;
     }
@@ -187,22 +195,26 @@ function unitIdentityKey(deploymentTarget, instanceName) {
 function metricIdentityKey(metricSystem, metricType) {
   return `metric:${metricSystem} ${metricType}`;
 }
+function ioIdentityKey(target) {
+  return `io:${target}`;
+}
 
 // src/schemas.ts
-var import_zod12 = require("zod");
+var import_zod13 = require("zod");
 
 // src/semantics/registry.ts
-var import_zod11 = require("zod");
+var import_zod12 = require("zod");
 
 // src/semantics/functionCall.ts
 var import_zod2 = require("zod");
 var FunctionCallSemanticsSchema = import_zod2.z.object({
   name: import_zod2.z.literal("function-call"),
   /**
-   * Optional module identifier for cross-unit references
-   * (e.g. `"./components/Button"` for a React component, or the TS
-   * module path for a bare function export). Packs that don't do
-   * cross-module pairing can leave it unset.
+   * Where the function lives inside this repository. It is either the
+   * name of a module the project lists in `suss.json`, such as
+   * `"billing"`, or a module path, such as the file a server action is
+   * written in. A name has no separator in it and a path always does.
+   * Packs that don't do cross-module pairing can leave it unset.
    */
   module: import_zod2.z.string().optional(),
   /** Named export within the module, when applicable. */
@@ -227,35 +239,38 @@ var FunctionCallSemanticsSchema = import_zod2.z.object({
    */
   exportPath: import_zod2.z.array(import_zod2.z.string()).optional()
 });
+function isModuleName(module2) {
+  return !module2.includes("/") && !module2.includes("\\");
+}
 var functionCallSemantics = defineBoundarySemantics({
   name: "function-call",
   schema: FunctionCallSemanticsSchema,
-  // A call that never leaves the process does not produce a span, and
-  // the conventions do not name one. All of it is ours.
+  // A call inside the process does not produce a span, and the
+  // conventions have no attributes for it.
   semconv: {},
   behavior: {
-    /** A call returns a value, which is not a status and a body. */
+    /** A call returns a value, with no status. */
     exchangesHttpResponses: false,
     leavesTheProcess: false,
     reportsUnpairedItself: false,
     /**
-     * In-repo units (components, bare handlers) are keyless by design
-     * and pair through call edges rather than the keyed pass, so a
-     * missing key is not a boundary nothing can reach.
+     * In-repo units such as components have no key on purpose. They
+     * pair through call edges instead of the keyed pass, so a missing
+     * key does not make them unreachable.
      */
     canPair: () => true,
-    /**
-     * `"fn:<package>::<exportPath>"` when both are set, and
-     * `"fn:<module>::<exportName>"` for an in-repo unit that states its
-     * module, the way a server action does. Components and bare
-     * handlers state neither and have no key at all.
-     */
     rewritePaths(semantics, rewrite) {
-      if (semantics.module === void 0) {
+      if (semantics.module === void 0 || isModuleName(semantics.module)) {
         return semantics;
       }
       return { ...semantics, module: rewrite(semantics.module) };
     },
+    /**
+     * `"fn:<package>::<exportPath>"` when both are set, and
+     * `"fn:<module>::<exportName>"` for an in-repo unit that gives its
+     * module, as a server action does. Components and plain handlers
+     * give neither and have no key.
+     */
     identityKey(semantics) {
       if (semantics.package !== void 0 && semantics.exportPath !== void 0 && semantics.exportPath.length > 0) {
         return fnIdentityKey(semantics.package, semantics.exportPath);
@@ -284,14 +299,14 @@ var GraphqlResolverSemanticsSchema = import_zod3.z.object({
 var graphqlResolverSemantics = defineBoundarySemantics({
   name: "graphql-resolver",
   schema: GraphqlResolverSemanticsSchema,
-  // The conventions name the operation a client sent, not the
-  // resolver the server ran for one field of it.
+  // The conventions describe the operation a client sent. They have no
+  // attribute for the resolver the server ran for one field of it.
   semconv: {},
   behavior: {
-    /** A resolver returns a field value, not a status and a body. */
+    /** A resolver returns a field value, with no status. */
     exchangesHttpResponses: false,
-    // A query somebody sent from outside runs it, even though the
-    // server calls the function in its own process.
+    // A resolver runs because a client outside the process sent a query,
+    // even though the server calls it in its own process.
     leavesTheProcess: true,
     reportsUnpairedItself: false,
     /**
@@ -308,8 +323,32 @@ var graphqlResolverSemantics = defineBoundarySemantics({
   }
 });
 
-// src/semantics/messageBus.ts
+// src/semantics/io.ts
 var import_zod4 = require("zod");
+var IoSemanticsSchema = import_zod4.z.object({
+  name: import_zod4.z.literal("io"),
+  /** The stream, such as `stdout` or `stderr`. Null when the source does not say which. */
+  target: import_zod4.z.string().nullable()
+});
+var ioSemantics = defineBoundarySemantics({
+  name: "io",
+  schema: IoSemanticsSchema,
+  // The semantic conventions have no attribute for a process's own streams.
+  semconv: {},
+  behavior: {
+    exchangesHttpResponses: false,
+    leavesTheProcess: true,
+    reportsUnpairedItself: false,
+    identityKey(semantics) {
+      return semantics.target === null ? null : ioIdentityKey(semantics.target);
+    },
+    // Nothing declares the reading side, so a write has nothing to meet.
+    canPair: () => false
+  }
+});
+
+// src/semantics/messageBus.ts
+var import_zod5 = require("zod");
 
 // src/channel.ts
 function parseChannel(channel) {
@@ -335,12 +374,11 @@ function channelsPair(a, b) {
 }
 
 // src/semantics/messageBus.ts
-var MessageBusSemanticsSchema = import_zod4.z.object({
-  name: import_zod4.z.literal("message-bus"),
-  messageBus: import_zod4.z.enum([
-    // The conventions spell the two AWS buses this way, one with an
-    // underscore and one with a dot, so these are their strings and
-    // not a typo.
+var MessageBusSemanticsSchema = import_zod5.z.object({
+  name: import_zod5.z.literal("message-bus"),
+  messageBus: import_zod5.z.enum([
+    // The conventions write these two AWS buses differently, one with an
+    // underscore and one with a dot. Both are as the conventions give them.
     "aws_sqs",
     "aws.sns",
     "s3",
@@ -359,12 +397,13 @@ var MessageBusSemanticsSchema = import_zod4.z.object({
     "cloudflare-tail"
   ]),
   /**
-   * Stable channel identifier: a CFN logical id, a queue or topic name,
-   * a subject pattern, or `bus#detailType`. Null when this source does
-   * not say which channel, as with a send whose queue the code picks at
-   * runtime, or a receive whose queue the event-source mapping states.
+   * A stable channel identifier: a CloudFormation logical id, a queue or
+   * topic name, a subject pattern, or `bus#detailType`. Null when this
+   * source does not say which channel, as with a send whose queue the
+   * code picks at run time, or a receive whose queue is set in the
+   * event-source mapping.
    */
-  channel: import_zod4.z.string().min(1).nullable()
+  channel: import_zod5.z.string().min(1).nullable()
 });
 var messageBusSemantics = defineBoundarySemantics({
   name: "message-bus",
@@ -378,25 +417,26 @@ var messageBusSemantics = defineBoundarySemantics({
     exchangesHttpResponses: false,
     leavesTheProcess: true,
     /**
-     * `checkMessageBus` looks at every channel, including the unused
-     * ones, so the generic unmatched lists leave them alone.
+     * `checkMessageBus` reports every channel, unused ones included, so
+     * the generic unmatched list leaves them out.
      */
     reportsUnpairedItself: true,
     /**
-     * A channel unnamed here can still pair: the dedicated pass
-     * collapses env chains before comparing, so a consumer whose
-     * channel arrives at runtime meets the template that declares it.
+     * A channel that is null here can still pair. The dedicated pass
+     * follows environment variable chains before comparing, so a
+     * consumer whose channel is set at run time meets the template that
+     * declares it.
      */
     canPair: () => true,
     /**
      * `"bus:<messageBus> <subject>"`, or null when the channel is null
      * or its subject is empty.
      *
-     * The key has the subject in it and leaves out the bus, so a
-     * template writing `default#order.placed` and a handler writing
+     * The key has the subject and leaves out the bus, so a template
+     * writing `default#order.placed` and a handler writing
      * `order.placed` land in one bucket, where `sidesAgree` compares the
-     * buses. A side that cannot know its bus would otherwise be keyed
-     * away from the side that can.
+     * buses. Keying on the bus would separate a side that cannot know
+     * its bus from the side that can.
      *
      * The bus technology stays in, because a queue and an event router
      * are different destinations even with the same subject. Case stays
@@ -419,9 +459,9 @@ var messageBusSemantics = defineBoundarySemantics({
       return channelsPair(a.channel, b.channel);
     },
     /**
-     * The whole channel, bus included, unlike the identity key, which
-     * has the subject alone. Someone reading a list of unmatched
-     * channels wants to see which bus each one was on.
+     * The whole channel, bus included, where the identity key has only
+     * the subject. A reader looking at unmatched channels needs to see
+     * which bus each one was on.
      */
     displayLabel(semantics) {
       if (semantics.channel === null) {
@@ -433,25 +473,25 @@ var messageBusSemantics = defineBoundarySemantics({
 });
 
 // src/semantics/metric.ts
-var import_zod5 = require("zod");
-var MetricSemanticsSchema = import_zod5.z.object({
-  name: import_zod5.z.literal("metric"),
-  /** Which system the series lives in: cloud-monitoring, cloudwatch. */
-  metricSystem: import_zod5.z.string(),
+var import_zod6 = require("zod");
+var MetricSemanticsSchema = import_zod6.z.object({
+  name: import_zod6.z.literal("metric"),
+  /** The system the series is stored in, such as `cloud-monitoring` or `cloudwatch`. */
+  metricSystem: import_zod6.z.string(),
   /**
-   * The type string the system knows the metric by, spelled the way
-   * both sides spell it. Null when the source states one this reader
-   * could not settle, as with a query it could not read: a metric
-   * nobody could name pairs with nothing rather than with whatever
-   * happens to share its source text.
+   * The type string the system uses for the metric, written the same
+   * way on both sides. Null when the reader could not work the string
+   * out, as with a query it could not parse. A null type pairs with
+   * nothing, so it cannot pair with an unrelated metric that happens to
+   * share its source text.
    */
-  metricType: import_zod5.z.string().nullable()
+  metricType: import_zod6.z.string().nullable()
 });
 var metricSemantics = defineBoundarySemantics({
   name: "metric",
   schema: MetricSemanticsSchema,
-  // OpenTelemetry knows a metric by its instrument name, and has no
-  // attribute for the system it lives in or the type string it goes by.
+  // OpenTelemetry identifies a metric by its instrument name. It has no
+  // attribute for the metric's system or its type string.
   semconv: {},
   behavior: {
     exchangesHttpResponses: false,
@@ -467,7 +507,7 @@ var metricSemantics = defineBoundarySemantics({
 });
 
 // src/semantics/rest.ts
-var import_zod6 = require("zod");
+var import_zod7 = require("zod");
 
 // src/dispatch.ts
 function dispatchByType(table, value) {
@@ -814,23 +854,23 @@ function compareRanks(a, b) {
 }
 
 // src/semantics/rest.ts
-var RestSemanticsSchema = import_zod6.z.object({
-  name: import_zod6.z.literal("rest"),
+var RestSemanticsSchema = import_zod7.z.object({
+  name: import_zod7.z.literal("rest"),
   /**
    * Uppercase HTTP method ("GET", "POST", …), `"*"` for a handler that
    * responds to every method, or null when this source does not say
    * which method.
    */
-  method: import_zod6.z.string().min(1).nullable(),
+  method: import_zod7.z.string().min(1).nullable(),
   /** Normalized route path ("/users/{id}"), or null when this source does not give one. */
-  path: import_zod6.z.string().min(1).nullable(),
+  path: import_zod7.z.string().min(1).nullable(),
   /**
-   * Status codes the producing source explicitly declared (OpenAPI
-   * responses, CFN MethodResponses, ts-rest router statuses). They are
-   * kept here so the pairing layer can see them without unwrapping any
-   * metadata. Absent, or empty, for a source that was inferred.
+   * Status codes the producing source declared explicitly, such as
+   * OpenAPI responses or CloudFormation MethodResponses. They are kept
+   * here so the pairing layer can see them without unwrapping any
+   * metadata. Absent or empty for an inferred source.
    */
-  declaredResponses: import_zod6.z.array(import_zod6.z.number()).optional()
+  declaredResponses: import_zod7.z.array(import_zod7.z.number()).optional()
 });
 var OPENING_HOLE = /^\{([^{}]+)\}(.*)$/;
 function baseUrlReference(semantics) {
@@ -887,16 +927,15 @@ var restSemantics = defineBoundarySemantics({
       return `${semantics.method.toUpperCase()} ${normalizePath(semantics.path)}`;
     },
     /**
-     * The bucket has only the path in it, so a `"*"` route lands with
-     * the consumers that each specify a method, and `methodsAgree`
-     * settles it inside the bucket. The identity key stays what a reader
-     * sees and a suppression targets ("GET /users", "* /users"), and
-     * this key groups what a reader still tells apart.
+     * The bucket has only the path, so a `"*"` route lands with the
+     * consumers that each give a method, and `methodsAgree` compares the
+     * methods inside the bucket. The identity key is still what a reader
+     * sees and what a suppression targets ("GET /users", "* /users").
      *
-     * A parameter's name goes too. A spec written by hand says
-     * `{userId}` where the Express route that serves it says `:id`, and
-     * both match the same requests, so pairing on the name gave two
-     * boundaries that never met and a run with nothing to report.
+     * Parameter names are dropped too. A hand-written spec writes
+     * `{userId}` where the Express route that serves it writes `:id`,
+     * and both match the same requests. Pairing on the name would leave
+     * two boundaries that never meet.
      */
     pairingKey(semantics) {
       if (semantics.method === null || semantics.path === null) {
@@ -917,9 +956,9 @@ var restSemantics = defineBoundarySemantics({
       return semantics.path === null ? [] : pathSpecificity(normalizePath(semantics.path));
     },
     /**
-     * What the identity key says, with a missing half still readable:
-     * ANY when no method was stated, and ? when no path was. Null when
-     * neither was stated, because then there is nothing to show.
+     * The identity key, with a missing half still readable: `ANY` when
+     * the source gave no method, and `?` when it gave no path. Null when
+     * both are missing, since then there is nothing to show.
      */
     displayLabel(semantics) {
       if (semantics.method === null && semantics.path === null) {
@@ -930,11 +969,11 @@ var restSemantics = defineBoundarySemantics({
       return `${method} ${path}`;
     },
     /**
-     * A route with both halves stated decides for itself: the method
-     * through `methodsAgree` (so a `"*"` route matches every method),
-     * and the path through `routePathAdmits`. A route missing either
-     * half might still be the one that handles the request, and nothing
-     * here can settle that, so it abstains instead of refusing.
+     * With both halves present, the method goes through `methodsAgree`
+     * (so a `"*"` route matches every method) and the path through
+     * `routePathAdmits`. A route missing either half might still handle
+     * the request, and this declaration cannot settle that, so the
+     * result is `"unknown"`.
      */
     servesRequest(semantics, method, path) {
       if (semantics.method === null || semantics.path === null) {
@@ -947,8 +986,8 @@ var restSemantics = defineBoundarySemantics({
     },
     /**
      * A route the registration pattern admits is inside it. A route
-     * whose path this source never gave is left outside, because
-     * nothing here can show it is one the pattern covers.
+     * without a path counts as outside, because nothing shows that the
+     * pattern covers it.
      */
     withinScope(semantics, scope) {
       return semantics.path !== null && routePathAdmits(scope, semantics.path);
@@ -957,16 +996,12 @@ var restSemantics = defineBoundarySemantics({
      * A call whose base URL the deployment fills in, resolved to the
      * path it reaches.
      *
-     * The source cannot settle this on its own, which is why the
-     * adapter leaves the hole in. `API_BASE` could be
-     * `http://backend.internal`, and then the path is `/orders`. It
-     * could equally be `/api/v2`, and then the path is
-     * `/api/v2/orders`. Putting the deployed value in and reading the
-     * path back out gets the right one either way.
-     *
-     * Only a hole at the front is a base URL. A hole further along is a
-     * route parameter, and `/orders/{id}` means every id rather than a
-     * variable somebody set.
+     * The source cannot settle this on its own, so the adapter leaves
+     * the hole in. `API_BASE` could be `http://backend.internal`, and
+     * then the path is `/orders`. It could equally be `/api/v2`, and
+     * then the path is `/api/v2/orders`. Filling in the deployed value
+     * and reading the path back out gets the right one either way.
+     * `baseUrlReference` finds the hole that is the base URL.
      */
     groundName(semantics, deployment) {
       const reference = baseUrlReference(semantics);
@@ -983,7 +1018,7 @@ var restSemantics = defineBoundarySemantics({
     },
     nameReference: baseUrlReference,
     ruleBoundary: {
-      // "METHOD /path": one leading token, then an absolute path.
+      // "METHOD /path": one token, a space, then an absolute path.
       claims(raw) {
         return /^\S+ +\//.test(raw.trim());
       },
@@ -998,12 +1033,12 @@ var restSemantics = defineBoundarySemantics({
 });
 
 // src/semantics/runtimeConfig.ts
-var import_zod8 = require("zod");
+var import_zod9 = require("zod");
 
 // src/deployableUnit.ts
-var import_zod7 = require("zod");
-var DeployableUnitSchema = import_zod7.z.object({
-  deploymentTarget: import_zod7.z.enum([
+var import_zod8 = require("zod");
+var DeployableUnitSchema = import_zod8.z.object({
+  deploymentTarget: import_zod8.z.enum([
     "lambda",
     "ecs-task",
     "container",
@@ -1012,7 +1047,7 @@ var DeployableUnitSchema = import_zod7.z.object({
   ]),
   // An empty name would agree with every other empty name, so a unit
   // with no name has to leave the field off instead.
-  instanceName: import_zod7.z.string().min(1)
+  instanceName: import_zod8.z.string().min(1)
 });
 function ecsContainerInstanceName(taskDefinitionLogicalId, containerName) {
   return `${taskDefinitionLogicalId}/${containerName}`;
@@ -1023,14 +1058,14 @@ var RuntimeConfigSemanticsSchema = DeployableUnitSchema.partial({
   deploymentTarget: true,
   instanceName: true
 }).extend({
-  name: import_zod8.z.literal("runtime-config")
+  name: import_zod9.z.literal("runtime-config")
 });
 var runtimeConfigSemantics = defineBoundarySemantics({
   name: "runtime-config",
   schema: RuntimeConfigSemanticsSchema,
-  // service.name and cloud.resource_id name the same deployable, but
-  // instanceName is the deployment template's logical id, which is
-  // neither of those strings.
+  // service.name and cloud.resource_id identify the same deployable, but
+  // instanceName is the template's logical id, a different string from
+  // both.
   semconv: {},
   behavior: {
     /** A process reads its config at startup, and nothing replies. */
@@ -1039,46 +1074,53 @@ var runtimeConfigSemantics = defineBoundarySemantics({
     // comes from outside the code.
     leavesTheProcess: true,
     reportsUnpairedItself: false,
-    identityKey: () => null
+    identityKey: () => null,
+    // A reader sees which deployable's environment this is. Code that
+    // reads a variable does not say which deployable runs it, so a read
+    // has no name.
+    displayLabel(semantics) {
+      const instance = semantics.instanceName;
+      return instance === void 0 ? null : `runtime-config:${instance}`;
+    }
   }
 });
 
 // src/semantics/storage.ts
-var import_zod9 = require("zod");
-var StorageSemanticsSchema = import_zod9.z.object({
-  name: import_zod9.z.literal("storage"),
+var import_zod10 = require("zod");
+var StorageSemanticsSchema = import_zod10.z.object({
+  name: import_zod10.z.literal("storage"),
   /**
-   * Which store this is: postgresql, mysql, aws.dynamodb, or our own
-   * word for one OpenTelemetry never named, such as s3, or null when
-   * the source states one this reader could not settle. Two products'
-   * containers can share a name, so this keeps them apart. A null
-   * keeps none of them apart, and the pairing pass says what it does
-   * with one.
+   * The storage system: an OpenTelemetry value such as `postgresql` or
+   * `aws.dynamodb`, or suss's own word for one the conventions do not
+   * cover, such as `s3`. Null when the reader could not work out which
+   * system the source uses. Two products' containers can share a name,
+   * and this field keeps them apart. The pairing pass decides how to
+   * treat a null.
    */
-  storageSystem: import_zod9.z.string().nullable(),
+  storageSystem: import_zod10.z.string().nullable(),
   /**
    * The ORM, schema, or deployment scope. A single-database setup uses
    * `"default"`, and a monorepo with several schemas gives each one its
    * own value.
    */
-  scope: import_zod9.z.string(),
+  scope: import_zod10.z.string(),
   /**
-   * The table, bucket, collection, or index, as the source declares
-   * it, or null when the source states one this reader could not
-   * settle. A null container pairs with nothing, rather than with
-   * whatever its source text happens to spell. The string is in the
-   * boundary-name syntax: a literal, a pattern with `{}` holes, or a
-   * reference, and `parseBoundaryName` is the one reader of it.
+   * The table, bucket, collection or index, as the source declares it.
+   * Null when the reader could not work out the container, and a null
+   * container pairs with nothing, so it cannot match by accident of
+   * shared source text. The string uses the boundary-name syntax (a
+   * literal, a pattern with `{}` holes, or a reference), and only
+   * `parseBoundaryName` should read it.
    */
-  container: import_zod9.z.string().nullable(),
+  container: import_zod10.z.string().nullable(),
   /**
-   * A secondary way into the container, a DynamoDB global secondary
-   * index or an Elasticsearch alias, each with its own key fields.
-   * Null means the container's own primary way in. A query through an
+   * A secondary way into the container, such as a DynamoDB global
+   * secondary index or an Elasticsearch alias, each with its own key
+   * fields. Null means the container's primary key. A query through an
    * index and a query through the table are different accesses, so
    * they pair separately.
    */
-  accessPath: import_zod9.z.string().nullable()
+  accessPath: import_zod10.z.string().nullable()
 });
 function containerReference(semantics) {
   return semantics.container === null ? null : referenceFromName(semantics.container);
@@ -1088,21 +1130,21 @@ var storageSemantics = defineBoundarySemantics({
   schema: StorageSemanticsSchema,
   semconv: {
     storageSystem: { name: "db.system.name" },
-    // "default" is our word for a source that named no database.
+    // suss writes "default" when the source did not say which database.
     scope: { name: "db.namespace", placeholderValues: ["default"] },
     container: { name: "db.collection.name" }
-    // A secondary index has no attribute of its own, so accessPath
-    // stays our word.
+    // The conventions have no attribute for a secondary index, so
+    // accessPath is left out.
   },
   behavior: {
-    /** A query returns rows or items, not a status and a body. */
+    /** A query returns rows or items, with no status. */
     exchangesHttpResponses: false,
     leavesTheProcess: true,
     reportsUnpairedItself: false,
     identityKey: () => null,
     displayLabel: storageLabel,
     /**
-     * A container the source states as a variable is whatever the
+     * A container the source gives as a variable is whatever the
      * deployment sets that variable to. `{SUBSCRIBERS_TABLE}` in the
      * code and `prod-subscribers-v1` in the manifest are one table.
      */
@@ -1132,9 +1174,9 @@ function storageContainerLabel(semantics) {
 }
 
 // src/semantics/unitInvocation.ts
-var import_zod10 = require("zod");
+var import_zod11 = require("zod");
 var UnitInvocationSemanticsSchema = DeployableUnitSchema.extend({
-  name: import_zod10.z.literal("unit-invocation"),
+  name: import_zod11.z.literal("unit-invocation"),
   instanceName: DeployableUnitSchema.shape.instanceName.nullable()
 });
 function calleeReference(semantics) {
@@ -1164,9 +1206,9 @@ var unitInvocationSemantics = defineBoundarySemantics({
      */
     reportsUnpairedItself: false,
     /**
-     * A callee the source states only as a variable is not a name for
-     * anything until the deployment fills it in, so it keys as nothing
-     * rather than as a bucket that would agree with itself alone.
+     * A callee the source gives only as a variable has no name until the
+     * deployment fills it in. It gets no key, since a key built from the
+     * variable would pair only with itself.
      */
     identityKey(semantics) {
       if (semantics.instanceName === null || namesNothing(semantics.instanceName)) {
@@ -1187,11 +1229,10 @@ var unitInvocationSemantics = defineBoundarySemantics({
       );
     },
     /**
-     * A call that reads its callee's name out of the environment
-     * reaches whichever resource the template wires that variable to.
-     * The logical id is the answer rather than the deployed name,
-     * because the invoked unit's own summary is keyed by the logical
-     * id and neither side ever writes the other's string.
+     * A call that reads its callee's name from the environment reaches
+     * whichever resource the template wires that variable to. The name
+     * is grounded to the logical id and not the deployed name, because
+     * the invoked unit's own summary is keyed by the logical id.
      */
     groundName(semantics, deployment) {
       const reference = calleeReference(semantics);
@@ -1206,7 +1247,7 @@ var unitInvocationSemantics = defineBoundarySemantics({
 });
 
 // src/semantics/registry.ts
-var SemanticsSchema = import_zod11.z.discriminatedUnion("name", [
+var SemanticsSchema = import_zod12.z.discriminatedUnion("name", [
   restSemantics.schema,
   functionCallSemantics.schema,
   graphqlResolverSemantics.schema,
@@ -1215,7 +1256,8 @@ var SemanticsSchema = import_zod11.z.discriminatedUnion("name", [
   storageSemantics.schema,
   messageBusSemantics.schema,
   metricSemantics.schema,
-  unitInvocationSemantics.schema
+  unitInvocationSemantics.schema,
+  ioSemantics.schema
 ]);
 var DEFINITIONS = [
   restSemantics,
@@ -1226,7 +1268,8 @@ var DEFINITIONS = [
   storageSemantics,
   messageBusSemantics,
   metricSemantics,
-  unitInvocationSemantics
+  unitInvocationSemantics,
+  ioSemantics
 ];
 var BY_NAME = new Map(
   DEFINITIONS.map((d) => [d.name, d])
@@ -1249,90 +1292,95 @@ function allBehaviors() {
 }
 
 // src/schemas.ts
-var ConfidenceSourceSchema = import_zod12.z.enum([
+var ConfidenceSourceSchema = import_zod13.z.enum([
   "inferred_static",
   "inferred_ai",
   "declared",
   "derived"
 ]);
-var ConfidenceLevelSchema = import_zod12.z.enum(["high", "medium", "low"]);
-var CorroborationSchema = import_zod12.z.object({
-  outcome: import_zod12.z.enum(["observed", "refuted", "untested"]),
+var ConfidenceLevelSchema = import_zod13.z.enum(["high", "medium", "low"]);
+var CorroborationSchema = import_zod13.z.object({
+  outcome: import_zod13.z.enum(["observed", "refuted", "untested"]),
   /** Executions that produced a verdict for this claim. */
-  runs: import_zod12.z.number(),
+  runs: import_zod13.z.number(),
   /** Present when refuted: the input and observation that disagreed. */
-  counterexample: import_zod12.z.unknown().optional(),
+  counterexample: import_zod13.z.unknown().optional(),
   /** Present when untested: why no verdict was reachable. */
-  reason: import_zod12.z.string().optional()
+  reason: import_zod13.z.string().optional()
 });
-var ConfidenceInfoSchema = import_zod12.z.object({
+var ConfidenceInfoSchema = import_zod13.z.object({
   source: ConfidenceSourceSchema,
   level: ConfidenceLevelSchema,
   corroboration: CorroborationSchema.optional()
 });
-var SourceLocationSchema = import_zod12.z.object({
-  file: import_zod12.z.string(),
+var SourceLocationSchema = import_zod13.z.object({
+  file: import_zod13.z.string(),
   /** Line numbers, for a person reading the summary or an editor link. */
-  range: import_zod12.z.object({ start: import_zod12.z.number(), end: import_zod12.z.number() }),
+  range: import_zod13.z.object({ start: import_zod13.z.number(), end: import_zod13.z.number() }),
   /**
-   * Character offsets of the unit in its file. Identity and joins
-   * measure with these, since two functions can share a line and never
-   * an offset range; the line `range` above is the presentation of the
-   * same place. Absent on summaries no source position backs, a
-   * contract artifact's say.
+   * Character offsets of the unit in its file. Identity and joins use
+   * these, because two functions can share a line but never an offset
+   * range. `range` gives the same place in lines. Absent on a summary
+   * with no source position, such as one read from a contract.
    */
-  span: import_zod12.z.object({ start: import_zod12.z.number(), end: import_zod12.z.number() }).optional(),
-  exportName: import_zod12.z.string().nullable(),
+  span: import_zod13.z.object({ start: import_zod13.z.number(), end: import_zod13.z.number() }).optional(),
+  exportName: import_zod13.z.string().nullable(),
   /**
-   * The project the extract was pointed at, by the name that project
-   * calls itself.
+   * The project the extract ran on, by the name the project gives
+   * itself.
    *
    * Paths are relative to wherever the extract ran, so two services in
-   * one repository both report `src/handlers.ts`, and merging their
-   * summaries puts them on top of each other. This field is what tells
-   * them apart, and what a reader groups by.
+   * one repository can both report `src/handlers.ts`, and merging their
+   * summaries would mix them up. This field tells them apart, and a
+   * reader groups by it.
    */
-  workspace: import_zod12.z.string().optional()
+  workspace: import_zod13.z.string().optional(),
+  /**
+   * The module of the application the unit belongs to, by the name the
+   * project's `suss.json` gives it. Set only when the project lists its
+   * modules, and then on every unit whose file is under a module's root.
+   */
+  module: import_zod13.z.string().optional()
 });
-var BoundaryBindingSchema = import_zod12.z.object({
-  transport: import_zod12.z.string(),
+var BoundaryBindingSchema = import_zod13.z.object({
+  transport: import_zod13.z.string(),
   semantics: SemanticsSchema,
-  recognition: import_zod12.z.string()
+  recognition: import_zod13.z.string()
 });
 function typeDefinitionKey(ref) {
   return ref.def ?? null;
 }
-var TypeShapeSchema = import_zod12.z.lazy(
-  () => import_zod12.z.discriminatedUnion("type", [
-    import_zod12.z.object({
-      type: import_zod12.z.literal("record"),
-      properties: import_zod12.z.record(import_zod12.z.string(), TypeShapeSchema),
-      spreads: import_zod12.z.array(import_zod12.z.object({ sourceText: import_zod12.z.string() })).optional()
+var TypeShapeSchema = import_zod13.z.lazy(
+  () => import_zod13.z.discriminatedUnion("type", [
+    import_zod13.z.object({
+      type: import_zod13.z.literal("record"),
+      properties: import_zod13.z.record(import_zod13.z.string(), TypeShapeSchema),
+      spreads: import_zod13.z.array(import_zod13.z.object({ sourceText: import_zod13.z.string() })).optional()
     }),
-    import_zod12.z.object({ type: import_zod12.z.literal("dictionary"), values: TypeShapeSchema }),
-    import_zod12.z.object({ type: import_zod12.z.literal("array"), items: TypeShapeSchema }),
-    import_zod12.z.object({
-      type: import_zod12.z.literal("literal"),
-      value: import_zod12.z.union([import_zod12.z.string(), import_zod12.z.number(), import_zod12.z.boolean()]),
-      raw: import_zod12.z.string().optional()
+    import_zod13.z.object({ type: import_zod13.z.literal("dictionary"), values: TypeShapeSchema }),
+    import_zod13.z.object({ type: import_zod13.z.literal("array"), items: TypeShapeSchema }),
+    import_zod13.z.object({
+      type: import_zod13.z.literal("literal"),
+      value: import_zod13.z.union([import_zod13.z.string(), import_zod13.z.number(), import_zod13.z.boolean()]),
+      raw: import_zod13.z.string().optional()
     }),
-    import_zod12.z.object({ type: import_zod12.z.literal("text") }),
-    import_zod12.z.object({ type: import_zod12.z.literal("integer") }),
-    import_zod12.z.object({ type: import_zod12.z.literal("number") }),
-    import_zod12.z.object({ type: import_zod12.z.literal("boolean") }),
-    import_zod12.z.object({ type: import_zod12.z.literal("null") }),
-    import_zod12.z.object({ type: import_zod12.z.literal("undefined") }),
-    import_zod12.z.object({
-      type: import_zod12.z.literal("union"),
-      variants: import_zod12.z.array(TypeShapeSchema)
+    import_zod13.z.object({ type: import_zod13.z.literal("text") }),
+    import_zod13.z.object({ type: import_zod13.z.literal("integer") }),
+    import_zod13.z.object({ type: import_zod13.z.literal("number") }),
+    import_zod13.z.object({ type: import_zod13.z.literal("boolean") }),
+    import_zod13.z.object({ type: import_zod13.z.literal("null") }),
+    import_zod13.z.object({ type: import_zod13.z.literal("undefined") }),
+    import_zod13.z.object({
+      type: import_zod13.z.literal("union"),
+      variants: import_zod13.z.array(TypeShapeSchema)
     }),
-    import_zod12.z.object({
-      type: import_zod12.z.literal("ref"),
-      name: import_zod12.z.string(),
-      from: import_zod12.z.string().optional(),
-      def: import_zod12.z.string().optional()
+    import_zod13.z.object({
+      type: import_zod13.z.literal("ref"),
+      name: import_zod13.z.string(),
+      from: import_zod13.z.string().optional(),
+      def: import_zod13.z.string().optional()
     }),
-    import_zod12.z.object({ type: import_zod12.z.literal("unknown") })
+    import_zod13.z.object({ type: import_zod13.z.literal("unknown") })
   ])
 );
 var MAX_DEFINITION_DEPTH = 6;
@@ -1454,6 +1502,9 @@ function boundaryLabel(binding) {
 function displayLabel(binding) {
   return boundaryLabel(binding) ?? `${binding.semantics.name}:${binding.recognition}`;
 }
+function labelWithDetail(binding, detail) {
+  return `${boundaryLabel(binding) ?? binding.semantics.name} ${detail}`;
+}
 function normalizeRuleBoundary(raw) {
   const trimmed = raw.trim();
   for (const behavior of allBehaviors()) {
@@ -1617,8 +1668,8 @@ var PLATFORM_INJECTED_ENV_VARS = {
 };
 
 // src/relation.ts
-var import_zod13 = require("zod");
-var RelationSchema = import_zod13.z.enum([
+var import_zod14 = require("zod");
+var RelationSchema = import_zod14.z.enum([
   "provides",
   "reads",
   "writes",
@@ -1627,71 +1678,78 @@ var RelationSchema = import_zod13.z.enum([
 var EffectRelationSchema = RelationSchema.exclude(["provides"]);
 
 // src/suppressions.ts
-var import_zod14 = require("zod");
-var SuppressionSideSchema = import_zod14.z.object({
-  summary: import_zod14.z.string().optional(),
-  transitionId: import_zod14.z.string().optional()
+var import_zod15 = require("zod");
+var SuppressionSideSchema = import_zod15.z.object({
+  summary: import_zod15.z.string().optional(),
+  transitionId: import_zod15.z.string().optional()
 }).optional();
-var SuppressionRuleSchema = import_zod14.z.object({
+var SuppressionRuleSchema = import_zod15.z.object({
   /**
-   * The finding kind to match, behavioural or intent. It is an open
-   * string here because this package is below both IRs, and the loader
-   * is what validates it against the published kind enums.
+   * The finding kind to match, behavioral or intent. The schema accepts
+   * any string because ir-core cannot import either IR's kind enum. The
+   * CLI's loader checks it against both.
    */
-  kind: import_zod14.z.string().optional(),
+  kind: import_zod15.z.string().optional(),
   /**
-   * Boundary as a human-readable key, e.g. "GET /pet/{petId}" or
-   * "fn:@acme/api::getUser". REST keys are normalized via the same
-   * path normalizer the checkers use, so `:id` and `{id}` compare
-   * equal.
+   * The boundary's human-readable key, such as "GET /pet/{petId}" or
+   * "fn:@acme/api::getUser". A REST key goes through the same path
+   * normalizer the checkers use, so `:id` and `{id}` compare equal.
    */
-  boundary: import_zod14.z.string().optional(),
+  boundary: import_zod15.z.string().optional(),
   /**
-   * Consumer-side discriminators, the narrowest useful match. These
-   * mean something only for behavioural findings: a rule that
-   * specifies `consumer` never matches an intent finding, because an
-   * intent finding has no consumer side.
+   * Consumer-side discriminators, the narrowest useful match. They
+   * apply only to behavioral findings. A rule that sets `consumer`
+   * never matches an intent finding, because an intent finding has no
+   * consumer side.
    */
   consumer: SuppressionSideSchema,
   /**
-   * Provider-side discriminators, the mirror of `consumer`. A finding
-   * about a status the provider produces has its transition id on this
-   * side, and that id is the only handle narrow enough to pick out
-   * that one finding. As with `consumer`, a rule that specifies
-   * `provider` never matches an intent finding.
+   * Provider-side discriminators, matching the same fields as
+   * `consumer`. A finding about a status the provider produces has its
+   * transition id on this side, and that id is the only value narrow
+   * enough to pick out that one finding. As with `consumer`, a rule
+   * that sets `provider` never matches an intent finding.
    */
   provider: SuppressionSideSchema,
   /**
-   * "narrow", the default, requires kind plus one of boundary,
-   * consumer.transitionId, or provider.transitionId, which is enough
-   * to target a specific class of finding. "broad" opts in to
-   * kind-only or boundary-only matches, which also silence future
-   * regressions in that category.
+   * The title of one PRD scenario. A PRD finding's boundary is the
+   * whole PRD, so without this a rule accepts every scenario in it,
+   * including one added later. A rule that sets `scenario` matches
+   * only intent findings about a scenario with that title.
+   */
+  scenario: import_zod15.z.string().optional(),
+  /**
+   * "narrow", the default, requires `kind` plus one of `boundary`,
+   * `scenario`, `consumer.transitionId` or `provider.transitionId`, so
+   * the rule targets a specific class of finding. "broad" allows a
+   * match on kind alone or boundary alone, and such a rule also
+   * silences future regressions in that category.
    */
-  scope: import_zod14.z.enum(["narrow", "broad"]).default("narrow"),
+  scope: import_zod15.z.enum(["narrow", "broad"]).default("narrow"),
   /** Required human-written justification. */
-  reason: import_zod14.z.string().min(1),
+  reason: import_zod15.z.string().min(1),
   /** What to do when a finding matches. */
-  effect: import_zod14.z.enum(["mark", "downgrade", "hide"]).default("mark")
+  effect: import_zod15.z.enum(["mark", "downgrade", "hide"]).default("mark")
 }).strict();
-var SuppressionFileSchema = import_zod14.z.object({
-  version: import_zod14.z.literal(1),
-  rules: import_zod14.z.array(SuppressionRuleSchema)
+var SuppressionFileSchema = import_zod15.z.object({
+  version: import_zod15.z.literal(1),
+  rules: import_zod15.z.array(SuppressionRuleSchema)
 }).strict();
 function validateRule(rule) {
   if (rule.scope === "broad") {
-    if (rule.kind === void 0 && rule.boundary === void 0 && rule.consumer === void 0 && rule.provider === void 0) {
-      return "broad-scope rule must constrain at least one field (kind, boundary, consumer, or provider)";
+    if (rule.kind === void 0 && rule.boundary === void 0 && rule.scenario === void 0 && rule.consumer === void 0 && rule.provider === void 0) {
+      return "broad-scope rule must constrain at least one field (kind, boundary, scenario, consumer, or provider)";
     }
     return null;
   }
   const hasKind = rule.kind !== void 0;
   const hasBoundary = rule.boundary !== void 0;
+  const hasScenario = rule.scenario !== void 0;
   const hasTransition = rule.consumer?.transitionId !== void 0 || rule.provider?.transitionId !== void 0;
-  if (hasKind && (hasBoundary || hasTransition)) {
+  if (hasKind && (hasBoundary || hasScenario || hasTransition)) {
     return null;
   }
-  return "narrow-scope rule must specify kind AND (boundary OR consumer.transitionId OR provider.transitionId); set scope: 'broad' to silence wider categories";
+  return "narrow-scope rule must specify kind AND (boundary OR scenario OR consumer.transitionId OR provider.transitionId); set scope: 'broad' to silence wider categories";
 }
 function ruleBoundaryMatchesKey(ruleBoundary, key) {
   if (key === null) {
@@ -1743,6 +1801,12 @@ function countsForThreshold(finding) {
   return finding.suppressed.effect === "downgrade";
 }
 
+// src/testName.ts
+var TEST_TITLE_SEPARATOR = " > ";
+function testUnitName(titles) {
+  return titles.join(TEST_TITLE_SEPARATOR);
+}
+
 // src/typeShapeMatch.ts
 function bodyShapesMatch(actual, declared) {
   if (actual.type === "unknown" || declared.type === "unknown") {
@@ -1930,6 +1994,14 @@ function packageExportBinding(opts) {
     exportPath: opts.exportPath
   });
 }
+function moduleExportBinding(opts) {
+  return functionCallBinding({
+    transport: "in-process",
+    recognition: opts.recognition,
+    module: opts.module,
+    exportName: opts.exportName
+  });
+}
 function graphqlResolverBinding(opts) {
   return {
     transport: opts.transport,
@@ -2012,6 +2084,13 @@ function metricBinding(opts) {
     recognition: opts.recognition
   };
 }
+function ioBinding(opts) {
+  return {
+    transport: "in-process",
+    semantics: { name: "io", target: namedOrNull(opts.target, "io target") },
+    recognition: opts.recognition
+  };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   BoundaryBindingSchema,
@@ -2025,6 +2104,7 @@ function metricBinding(opts) {
   FunctionCallSemanticsSchema,
   GraphqlOperationSemanticsSchema,
   GraphqlResolverSemanticsSchema,
+  IoSemanticsSchema,
   MessageBusSemanticsSchema,
   MetricSemanticsSchema,
   NOTHING_DEPLOYED,
@@ -2037,6 +2117,7 @@ function metricBinding(opts) {
   StorageSemanticsSchema,
   SuppressionFileSchema,
   SuppressionRuleSchema,
+  TEST_TITLE_SEPARATOR,
   TypeShapeSchema,
   UnitInvocationSemanticsSchema,
   applySuppressionsToFindings,
@@ -2070,12 +2151,17 @@ function metricBinding(opts) {
   groundBinding,
   groundedPairingKey,
   hasNameHole,
+  ioBinding,
+  ioIdentityKey,
   isGraphqlOperationBinding,
+  isModuleName,
+  labelWithDetail,
   leavesTheProcess,
   messageBusBinding,
   methodsAgree,
   metricBinding,
   metricIdentityKey,
+  moduleExportBinding,
   namePatternFromSub,
   namePatternKey,
   nameReference,
@@ -2115,6 +2201,7 @@ function metricBinding(opts) {
   storageContainerLabel,
   storageLabel,
   storageSystemLabel,
+  testUnitName,
   typeDefinitionKey,
   unitIdentityKey,
   unitInvocationBinding,