@suss/ir-core 0.3.1 → 0.4.0

package/dist/index.cjs

@@ -41,23 +41,34 @@ __export(index_exports, {
   applySuppressionsToFindings: () => applySuppressionsToFindings,
   bodyShapesMatch: () => bodyShapesMatch,
   boundaryKey: () => boundaryKey,
+  boundaryLabel: () => boundaryLabel,
   busesAgree: () => busesAgree,
   channelsPair: () => channelsPair,
   codeScopePath: () => codeScopePath,
   countsForThreshold: () => countsForThreshold,
   dispatchByType: () => dispatchByType,
+  displayLabel: () => displayLabel,
+  ecsContainerInstanceName: () => ecsContainerInstanceName,
+  exchangesHttpResponses: () => exchangesHttpResponses,
   fileInCodeScope: () => fileInCodeScope,
+  formatChannel: () => formatChannel,
   functionCallBinding: () => functionCallBinding,
   graphqlOperationBinding: () => graphqlOperationBinding,
   graphqlResolverBinding: () => graphqlResolverBinding,
   messageBusBinding: () => messageBusBinding,
+  methodsAgree: () => methodsAgree,
   normalizePath: () => normalizePath,
   normalizeRuleBoundary: () => normalizeRuleBoundary,
   packageExportBinding: () => packageExportBinding,
+  pairingKey: () => pairingKey,
   parseChannel: () => parseChannel,
+  reportsUnpairedItself: () => reportsUnpairedItself,
   restBinding: () => restBinding,
+  routePathAdmits: () => routePathAdmits,
   ruleBoundaryMatchesKey: () => ruleBoundaryMatchesKey,
   runtimeConfigBinding: () => runtimeConfigBinding,
+  semanticsAgree: () => semanticsAgree,
+  servesRequest: () => servesRequest,
   storageRelationalBinding: () => storageRelationalBinding,
   typeDefinitionKey: () => typeDefinitionKey,
   validateRule: () => validateRule,
@@ -66,56 +77,20 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/schemas.ts
+var import_zod10 = require("zod");
+
+// src/semantics/registry.ts
+var import_zod9 = require("zod");
+
+// src/semantics/functionCall.ts
 var import_zod = require("zod");
-var ConfidenceSourceSchema = import_zod.z.enum([
-  "inferred_static",
-  "inferred_ai",
-  "declared",
-  "derived"
-]);
-var ConfidenceLevelSchema = import_zod.z.enum(["high", "medium", "low"]);
-var CorroborationSchema = import_zod.z.object({
-  outcome: import_zod.z.enum(["observed", "refuted", "untested"]),
-  /** Executions that produced a verdict for this claim. */
-  runs: import_zod.z.number(),
-  /** Present when refuted: the input and observation that disagreed. */
-  counterexample: import_zod.z.unknown().optional(),
-  /** Present when untested: why no verdict was reachable. */
-  reason: import_zod.z.string().optional()
-});
-var ConfidenceInfoSchema = import_zod.z.object({
-  source: ConfidenceSourceSchema,
-  level: ConfidenceLevelSchema,
-  corroboration: CorroborationSchema.optional()
-});
-var SourceLocationSchema = import_zod.z.object({
-  file: import_zod.z.string(),
-  range: import_zod.z.object({ start: import_zod.z.number(), end: import_zod.z.number() }),
-  exportName: import_zod.z.string().nullable(),
-  /**
-   * What the extract was pointed at, as that project calls itself.
-   *
-   * A path is relative to wherever the extract ran, so two services in
-   * one repository both say `src/handlers.ts` and merging their
-   * summaries puts them on top of each other. This is what tells them
-   * apart, and what a reader groups by.
-   */
-  workspace: import_zod.z.string().optional()
-});
-var RestSemanticsSchema = import_zod.z.object({
-  name: import_zod.z.literal("rest"),
-  /** Uppercase HTTP method ("GET", "POST", …). */
-  method: import_zod.z.string(),
-  /** Normalized route path ("/users/{id}"). */
-  path: import_zod.z.string(),
-  /**
-   * Status codes the producing source explicitly declared (OpenAPI
-   * responses, CFN MethodResponses, ts-rest router statuses). Kept here
-   * so the pairing layer can still see them without unwrapping metadata.
-   * Empty / absent for inferred sources.
-   */
-  declaredResponses: import_zod.z.array(import_zod.z.number()).optional()
-});
+
+// src/semantics/definition.ts
+function defineBoundarySemantics(definition) {
+  return definition;
+}
+
+// src/semantics/functionCall.ts
 var FunctionCallSemanticsSchema = import_zod.z.object({
   name: import_zod.z.literal("function-call"),
   /**
@@ -128,117 +103,503 @@ var FunctionCallSemanticsSchema = import_zod.z.object({
   /** Named export within the module, when applicable. */
   exportName: import_zod.z.string().optional(),
   /**
-   * Package name (as written in `package.json`) when this identity
-   * refers to a public package export — e.g. `"@suss/behavioral-ir"`.
-   * Set alongside `exportPath` by packs that resolve a package's
-   * public surface (the `packageExports` discovery variant). Distinct
-   * from `module`, which is a repo-relative module path for
-   * intra-repo pairing.
+   * Package name, as written in `package.json`, when this identity
+   * refers to a public package export, for example
+   * `"@suss/behavioral-ir"`. Packs that resolve a package's public
+   * surface (the `packageExports` discovery variant) set it alongside
+   * `exportPath`. It is different from `module`, which is a
+   * repo-relative module path used for pairing inside one repo.
    */
   package: import_zod.z.string().optional(),
   /**
-   * Path to the exported binding within the package, starting with
-   * the sub-path key when one is used. Examples:
-   *   `["parseSummary"]`              — root export
-   *   `["schemas", "BoundaryBindingSchema"]` — sub-path `./schemas`
+   * Path to the exported binding within the package, starting with the
+   * sub-path key when one is used. Examples:
+   *   `["parseSummary"]`: a root export
+   *   `["schemas", "BoundaryBindingSchema"]`: the sub-path `./schemas`
    *
-   * The first segment is the sub-path without the leading `./`
-   * (`"."` → omitted). The last segment is the exported name.
+   * The first segment is the sub-path without the leading `./`, and
+   * `"."` is left out. The last segment is the exported name.
    */
   exportPath: import_zod.z.array(import_zod.z.string()).optional()
 });
-var GraphqlResolverSemanticsSchema = import_zod.z.object({
-  name: import_zod.z.literal("graphql-resolver"),
-  /** GraphQL type the resolver attaches to: "Query", "Mutation", "Subscription", or an object-type name. */
-  typeName: import_zod.z.string(),
+var functionCallSemantics = defineBoundarySemantics({
+  name: "function-call",
+  schema: FunctionCallSemanticsSchema,
+  behavior: {
+    /** A call returns a value, which is not a status and a body. */
+    exchangesHttpResponses: false,
+    reportsUnpairedItself: false,
+    /**
+     * `"fn:<package>::<exportPath>"` when both are set. Other in-process
+     * function-call units, such as components and bare handlers inside
+     * one repo, have no key at all.
+     */
+    identityKey(semantics) {
+      if (semantics.package !== void 0 && semantics.exportPath !== void 0 && semantics.exportPath.length > 0) {
+        return `fn:${semantics.package}::${semantics.exportPath.join(".")}`;
+      }
+      return null;
+    }
+  }
+});
+
+// src/semantics/graphqlOperation.ts
+var import_zod2 = require("zod");
+var GraphqlOperationSemanticsSchema = import_zod2.z.object({
+  name: import_zod2.z.literal("graphql-operation"),
+  /** Optional operation name. An anonymous query or mutation leaves it unset. */
+  operationName: import_zod2.z.string().optional(),
+  operationType: import_zod2.z.enum(["query", "mutation", "subscription"])
+});
+var graphqlOperationSemantics = defineBoundarySemantics({
+  name: "graphql-operation",
+  schema: GraphqlOperationSemanticsSchema,
+  behavior: {
+    /**
+     * An operation gets a data-and-errors document back, which the
+     * GraphQL contract checker reads. Status codes say nothing here.
+     */
+    exchangesHttpResponses: false,
+    reportsUnpairedItself: false,
+    identityKey: () => null,
+    /** "query GetUser". The contract checker pairs it, the key does not. */
+    displayLabel(semantics) {
+      return `${semantics.operationType} ${semantics.operationName ?? "<anonymous>"}`;
+    }
+  }
+});
+
+// src/semantics/graphqlResolver.ts
+var import_zod3 = require("zod");
+var GraphqlResolverSemanticsSchema = import_zod3.z.object({
+  name: import_zod3.z.literal("graphql-resolver"),
+  /**
+   * GraphQL type the resolver attaches to: "Query", "Mutation",
+   * "Subscription", or an object-type name. Null when the source never
+   * says which one, as with a `@Resolver()` class that has no argument.
+   */
+  typeName: import_zod3.z.string().min(1).nullable(),
   /** Field name on that type. */
-  fieldName: import_zod.z.string()
+  fieldName: import_zod3.z.string()
 });
-var GraphqlOperationSemanticsSchema = import_zod.z.object({
-  name: import_zod.z.literal("graphql-operation"),
-  /** Optional operation name — anonymous queries / mutations leave this unset. */
-  operationName: import_zod.z.string().optional(),
-  operationType: import_zod.z.enum(["query", "mutation", "subscription"])
+var graphqlResolverSemantics = defineBoundarySemantics({
+  name: "graphql-resolver",
+  schema: GraphqlResolverSemanticsSchema,
+  behavior: {
+    /** A resolver returns a field value, not a status and a body. */
+    exchangesHttpResponses: false,
+    reportsUnpairedItself: false,
+    /**
+     * `"gql:<TypeName>.<fieldName>"`, or null when the type is null or
+     * the field is empty, which is how a resolver reports that the
+     * source never gave them.
+     */
+    identityKey(semantics) {
+      if (semantics.typeName === null || semantics.fieldName === "") {
+        return null;
+      }
+      return `gql:${semantics.typeName}.${semantics.fieldName}`;
+    }
+  }
 });
-var DeployableUnitSchema = import_zod.z.object({
-  deploymentTarget: import_zod.z.enum([
+
+// src/semantics/messageBus.ts
+var import_zod4 = require("zod");
+
+// src/channel.ts
+function parseChannel(channel) {
+  const hash = channel.indexOf("#");
+  if (hash === -1) {
+    return { bus: null, subject: channel };
+  }
+  return { bus: channel.slice(0, hash), subject: channel.slice(hash + 1) };
+}
+function formatChannel(bus, subject) {
+  if (bus === null) {
+    return subject;
+  }
+  return `${bus}#${subject}`;
+}
+function busesAgree(a, b) {
+  return a === null || b === null || a === b;
+}
+function channelsPair(a, b) {
+  const left = parseChannel(a);
+  const right = parseChannel(b);
+  return left.subject === right.subject && busesAgree(left.bus, right.bus);
+}
+
+// src/semantics/messageBus.ts
+var MessageBusSemanticsSchema = import_zod4.z.object({
+  name: import_zod4.z.literal("message-bus"),
+  messageBus: import_zod4.z.enum([
+    "sqs",
+    "sns",
+    "s3",
+    "eventbridge",
+    "bullmq",
+    "kafka",
+    "nats"
+  ]),
+  /**
+   * 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.
+   */
+  channel: import_zod4.z.string().min(1).nullable()
+});
+var messageBusSemantics = defineBoundarySemantics({
+  name: "message-bus",
+  schema: MessageBusSemanticsSchema,
+  behavior: {
+    /** A message goes onto the channel and nothing comes back. */
+    exchangesHttpResponses: false,
+    /**
+     * `checkMessageBus` looks at every channel, including the unused
+     * ones, so the generic unmatched lists leave them alone.
+     */
+    reportsUnpairedItself: 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
+     * `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.
+     *
+     * The bus technology stays in, because a queue and an event router
+     * are different destinations even with the same subject. Case stays
+     * too, because AWS compares detail-types and queue ids byte for byte.
+     */
+    identityKey(semantics) {
+      if (semantics.channel === null) {
+        return null;
+      }
+      const { subject } = parseChannel(semantics.channel);
+      if (subject === "") {
+        return null;
+      }
+      return `bus:${semantics.messageBus} ${subject}`;
+    },
+    sidesAgree(a, b) {
+      if (a.channel === null || b.channel === null) {
+        return false;
+      }
+      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.
+     */
+    displayLabel(semantics) {
+      if (semantics.channel === null) {
+        return `bus:${semantics.messageBus} (channel named at runtime)`;
+      }
+      return `bus:${semantics.messageBus} ${semantics.channel}`;
+    }
+  }
+});
+
+// src/semantics/rest.ts
+var import_zod5 = require("zod");
+var RestSemanticsSchema = import_zod5.z.object({
+  name: import_zod5.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_zod5.z.string().min(1).nullable(),
+  /** Normalized route path ("/users/{id}"), or null when this source does not give one. */
+  path: import_zod5.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.
+   */
+  declaredResponses: import_zod5.z.array(import_zod5.z.number()).optional()
+});
+function normalizePath(path) {
+  let normalized = path.replace(/:([a-zA-Z_]\w*)/g, "{$1}");
+  if (normalized.length > 1 && normalized.endsWith("/")) {
+    normalized = normalized.slice(0, -1);
+  }
+  normalized = normalized.replace(
+    /\{[^}]+\}|[^{]+/g,
+    (segment) => segment.startsWith("{") ? segment : segment.toLowerCase()
+  );
+  return normalized;
+}
+function methodsAgree(a, b) {
+  if (a === null || b === null) {
+    return false;
+  }
+  return a === b || a === "*" || b === "*";
+}
+function routePathRegex(pattern) {
+  const source = pattern.split(/(\{[^}]+\}|\*)/g).map((part) => {
+    if (part === "*") {
+      return ".*";
+    }
+    if (part.startsWith("{") && part.endsWith("}")) {
+      return "[^/]+";
+    }
+    return part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  }).join("");
+  return new RegExp(`^${source}$`);
+}
+function routePathAdmits(declaredPath, requestPath) {
+  return routePathRegex(normalizePath(declaredPath)).test(
+    normalizePath(requestPath)
+  );
+}
+var restSemantics = defineBoundarySemantics({
+  name: "rest",
+  schema: RestSemanticsSchema,
+  behavior: {
+    /** A request goes out, a status and a body come back. */
+    exchangesHttpResponses: true,
+    reportsUnpairedItself: false,
+    /** `"METHOD /normalized/path"`, or null when either half is missing. */
+    identityKey(semantics) {
+      if (semantics.method === null || semantics.path === null) {
+        return null;
+      }
+      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.
+     */
+    pairingKey(semantics) {
+      if (semantics.method === null || semantics.path === null) {
+        return null;
+      }
+      return `rest ${normalizePath(semantics.path)}`;
+    },
+    sidesAgree(a, b) {
+      return methodsAgree(a.method, b.method);
+    },
+    /**
+     * 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.
+     */
+    displayLabel(semantics) {
+      if (semantics.method === null && semantics.path === null) {
+        return null;
+      }
+      const method = semantics.method === null ? "ANY" : semantics.method.toUpperCase();
+      const path = semantics.path === null ? "?" : normalizePath(semantics.path);
+      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.
+     */
+    servesRequest(semantics, method, path) {
+      if (semantics.method === null || semantics.path === null) {
+        return "unknown";
+      }
+      if (!methodsAgree(semantics.method, method.toUpperCase())) {
+        return "nomatch";
+      }
+      return routePathAdmits(semantics.path, path) ? "match" : "nomatch";
+    },
+    ruleBoundary: {
+      // "METHOD /path": one leading token, then an absolute path.
+      claims(raw) {
+        return /^\S+ +\//.test(raw.trim());
+      },
+      normalize(raw) {
+        const trimmed = raw.trim();
+        const spaceIdx = trimmed.indexOf(" ");
+        const method = trimmed.slice(0, spaceIdx).toUpperCase();
+        return `${method} ${normalizePath(trimmed.slice(spaceIdx + 1).trim())}`;
+      }
+    }
+  }
+});
+
+// src/semantics/runtimeConfig.ts
+var import_zod7 = require("zod");
+
+// src/deployableUnit.ts
+var import_zod6 = require("zod");
+var DeployableUnitSchema = import_zod6.z.object({
+  deploymentTarget: import_zod6.z.enum([
     "lambda",
     "ecs-task",
     "container",
     "k8s-deployment"
   ]),
   // An empty name would agree with every other empty name, so a unit
-  // that names nothing has to leave the field off instead.
-  instanceName: import_zod.z.string().min(1)
+  // with no name has to leave the field off instead.
+  instanceName: import_zod6.z.string().min(1)
 });
+function ecsContainerInstanceName(taskDefinitionLogicalId, containerName) {
+  return `${taskDefinitionLogicalId}/${containerName}`;
+}
+
+// src/semantics/runtimeConfig.ts
 var RuntimeConfigSemanticsSchema = DeployableUnitSchema.extend({
-  name: import_zod.z.literal("runtime-config")
+  name: import_zod7.z.literal("runtime-config")
+});
+var runtimeConfigSemantics = defineBoundarySemantics({
+  name: "runtime-config",
+  schema: RuntimeConfigSemanticsSchema,
+  behavior: {
+    /** A process reads its config at startup, and nothing replies. */
+    exchangesHttpResponses: false,
+    reportsUnpairedItself: false,
+    identityKey: () => null
+  }
 });
-var StorageRelationalSemanticsSchema = import_zod.z.object({
-  name: import_zod.z.literal("storage-relational"),
-  storageSystem: import_zod.z.enum(["postgres", "mysql", "sqlite"]),
+
+// src/semantics/storageRelational.ts
+var import_zod8 = require("zod");
+var StorageRelationalSemanticsSchema = import_zod8.z.object({
+  name: import_zod8.z.literal("storage-relational"),
+  storageSystem: import_zod8.z.enum(["postgres", "mysql", "sqlite"]),
   /**
-   * ORM / driver scope. Defaults to `"default"` for single-database
-   * setups; monorepos with multiple schemas use distinct values.
+   * The ORM or driver scope. A single-database setup uses `"default"`,
+   * and a monorepo with several schemas gives each one its own value.
    */
-  scope: import_zod.z.string(),
-  /** Table / model name as declared in the schema. */
-  table: import_zod.z.string()
+  scope: import_zod8.z.string(),
+  /** The table or model name, as declared in the schema. */
+  table: import_zod8.z.string()
 });
-var MessageBusSemanticsSchema = import_zod.z.object({
-  name: import_zod.z.literal("message-bus"),
-  messageBus: import_zod.z.enum(["sqs", "eventbridge", "bullmq", "kafka", "nats"]),
-  /** Stable channel identifier — CFN logical id, queue/topic name, subject pattern, `bus#detailType`. */
-  channel: import_zod.z.string()
+var storageRelationalSemantics = defineBoundarySemantics({
+  name: "storage-relational",
+  schema: StorageRelationalSemanticsSchema,
+  behavior: {
+    /** A query returns rows, not a status and a body. */
+    exchangesHttpResponses: false,
+    reportsUnpairedItself: false,
+    identityKey: () => null
+  }
 });
-var SemanticsSchema = import_zod.z.discriminatedUnion("name", [
-  RestSemanticsSchema,
-  FunctionCallSemanticsSchema,
-  GraphqlResolverSemanticsSchema,
-  GraphqlOperationSemanticsSchema,
-  RuntimeConfigSemanticsSchema,
-  StorageRelationalSemanticsSchema,
-  MessageBusSemanticsSchema
+
+// src/semantics/registry.ts
+var SemanticsSchema = import_zod9.z.discriminatedUnion("name", [
+  restSemantics.schema,
+  functionCallSemantics.schema,
+  graphqlResolverSemantics.schema,
+  graphqlOperationSemantics.schema,
+  runtimeConfigSemantics.schema,
+  storageRelationalSemantics.schema,
+  messageBusSemantics.schema
+]);
+var DEFINITIONS = [
+  restSemantics,
+  functionCallSemantics,
+  graphqlResolverSemantics,
+  graphqlOperationSemantics,
+  runtimeConfigSemantics,
+  storageRelationalSemantics,
+  messageBusSemantics
+];
+var BY_NAME = new Map(
+  DEFINITIONS.map((d) => [d.name, d])
+);
+function behaviorOf(semantics) {
+  const definition = BY_NAME.get(semantics.name);
+  if (definition === void 0) {
+    throw new Error(`no boundary behavior for semantics "${semantics.name}"`);
+  }
+  return definition.behavior;
+}
+function allBehaviors() {
+  return DEFINITIONS.map((d) => d.behavior);
+}
+
+// src/schemas.ts
+var ConfidenceSourceSchema = import_zod10.z.enum([
+  "inferred_static",
+  "inferred_ai",
+  "declared",
+  "derived"
 ]);
-var BoundaryBindingSchema = import_zod.z.object({
-  transport: import_zod.z.string(),
+var ConfidenceLevelSchema = import_zod10.z.enum(["high", "medium", "low"]);
+var CorroborationSchema = import_zod10.z.object({
+  outcome: import_zod10.z.enum(["observed", "refuted", "untested"]),
+  /** Executions that produced a verdict for this claim. */
+  runs: import_zod10.z.number(),
+  /** Present when refuted: the input and observation that disagreed. */
+  counterexample: import_zod10.z.unknown().optional(),
+  /** Present when untested: why no verdict was reachable. */
+  reason: import_zod10.z.string().optional()
+});
+var ConfidenceInfoSchema = import_zod10.z.object({
+  source: ConfidenceSourceSchema,
+  level: ConfidenceLevelSchema,
+  corroboration: CorroborationSchema.optional()
+});
+var SourceLocationSchema = import_zod10.z.object({
+  file: import_zod10.z.string(),
+  range: import_zod10.z.object({ start: import_zod10.z.number(), end: import_zod10.z.number() }),
+  exportName: import_zod10.z.string().nullable(),
+  /**
+   * The project the extract was pointed at, by the name that project
+   * calls 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.
+   */
+  workspace: import_zod10.z.string().optional()
+});
+var BoundaryBindingSchema = import_zod10.z.object({
+  transport: import_zod10.z.string(),
   semantics: SemanticsSchema,
-  recognition: import_zod.z.string()
+  recognition: import_zod10.z.string()
 });
 function typeDefinitionKey(ref) {
   return ref.def ?? null;
 }
-var TypeShapeSchema = import_zod.z.lazy(
-  () => import_zod.z.discriminatedUnion("type", [
-    import_zod.z.object({
-      type: import_zod.z.literal("record"),
-      properties: import_zod.z.record(import_zod.z.string(), TypeShapeSchema),
-      spreads: import_zod.z.array(import_zod.z.object({ sourceText: import_zod.z.string() })).optional()
+var TypeShapeSchema = import_zod10.z.lazy(
+  () => import_zod10.z.discriminatedUnion("type", [
+    import_zod10.z.object({
+      type: import_zod10.z.literal("record"),
+      properties: import_zod10.z.record(import_zod10.z.string(), TypeShapeSchema),
+      spreads: import_zod10.z.array(import_zod10.z.object({ sourceText: import_zod10.z.string() })).optional()
     }),
-    import_zod.z.object({ type: import_zod.z.literal("dictionary"), values: TypeShapeSchema }),
-    import_zod.z.object({ type: import_zod.z.literal("array"), items: TypeShapeSchema }),
-    import_zod.z.object({
-      type: import_zod.z.literal("literal"),
-      value: import_zod.z.union([import_zod.z.string(), import_zod.z.number(), import_zod.z.boolean()]),
-      raw: import_zod.z.string().optional()
+    import_zod10.z.object({ type: import_zod10.z.literal("dictionary"), values: TypeShapeSchema }),
+    import_zod10.z.object({ type: import_zod10.z.literal("array"), items: TypeShapeSchema }),
+    import_zod10.z.object({
+      type: import_zod10.z.literal("literal"),
+      value: import_zod10.z.union([import_zod10.z.string(), import_zod10.z.number(), import_zod10.z.boolean()]),
+      raw: import_zod10.z.string().optional()
     }),
-    import_zod.z.object({ type: import_zod.z.literal("text") }),
-    import_zod.z.object({ type: import_zod.z.literal("integer") }),
-    import_zod.z.object({ type: import_zod.z.literal("number") }),
-    import_zod.z.object({ type: import_zod.z.literal("boolean") }),
-    import_zod.z.object({ type: import_zod.z.literal("null") }),
-    import_zod.z.object({ type: import_zod.z.literal("undefined") }),
-    import_zod.z.object({
-      type: import_zod.z.literal("union"),
-      variants: import_zod.z.array(TypeShapeSchema)
+    import_zod10.z.object({ type: import_zod10.z.literal("text") }),
+    import_zod10.z.object({ type: import_zod10.z.literal("integer") }),
+    import_zod10.z.object({ type: import_zod10.z.literal("number") }),
+    import_zod10.z.object({ type: import_zod10.z.literal("boolean") }),
+    import_zod10.z.object({ type: import_zod10.z.literal("null") }),
+    import_zod10.z.object({ type: import_zod10.z.literal("undefined") }),
+    import_zod10.z.object({
+      type: import_zod10.z.literal("union"),
+      variants: import_zod10.z.array(TypeShapeSchema)
     }),
-    import_zod.z.object({
-      type: import_zod.z.literal("ref"),
-      name: import_zod.z.string(),
-      from: import_zod.z.string().optional(),
-      def: import_zod.z.string().optional()
+    import_zod10.z.object({
+      type: import_zod10.z.literal("ref"),
+      name: import_zod10.z.string(),
+      from: import_zod10.z.string().optional(),
+      def: import_zod10.z.string().optional()
     }),
-    import_zod.z.object({ type: import_zod.z.literal("unknown") })
+    import_zod10.z.object({ type: import_zod10.z.literal("unknown") })
   ])
 );
 var MAX_DEFINITION_DEPTH = 6;
@@ -282,65 +643,49 @@ function withDefinitionsInlined(shape, definitions, depth = 0, inProgress = /* @
   return shape;
 }
 
-// src/channel.ts
-function parseChannel(channel) {
-  const hash = channel.indexOf("#");
-  if (hash === -1) {
-    return { bus: null, subject: channel };
-  }
-  return { bus: channel.slice(0, hash), subject: channel.slice(hash + 1) };
-}
-function busesAgree(a, b) {
-  return a === null || b === null || a === b;
+// src/boundaryKey.ts
+function boundaryKey(binding) {
+  return behaviorOf(binding.semantics).identityKey(binding.semantics);
 }
-function channelsPair(a, b) {
-  const left = parseChannel(a);
-  const right = parseChannel(b);
-  return left.subject === right.subject && busesAgree(left.bus, right.bus);
+function pairingKey(binding) {
+  const behavior = behaviorOf(binding.semantics);
+  return (behavior.pairingKey ?? behavior.identityKey)(binding.semantics);
 }
-
-// src/boundaryKey.ts
-function normalizePath(path) {
-  let normalized = path.replace(/:([a-zA-Z_]\w*)/g, "{$1}");
-  if (normalized.length > 1 && normalized.endsWith("/")) {
-    normalized = normalized.slice(0, -1);
+function semanticsAgree(a, b) {
+  if (a.name !== b.name) {
+    return false;
   }
-  normalized = normalized.replace(
-    /\{[^}]+\}|[^{]+/g,
-    (segment) => segment.startsWith("{") ? segment : segment.toLowerCase()
-  );
-  return normalized;
+  const agree = behaviorOf(a).sidesAgree;
+  return agree === void 0 ? true : agree(a, b);
 }
-function boundaryKey(binding) {
-  const semantics = binding.semantics;
-  if (semantics.name === "rest") {
-    if (semantics.method === "" || semantics.path === "") {
-      return null;
-    }
-    const method = semantics.method.toUpperCase();
-    const path = normalizePath(semantics.path);
-    return `${method} ${path}`;
-  }
-  if (semantics.name === "graphql-resolver") {
-    if (semantics.typeName === "" || semantics.fieldName === "") {
-      return null;
-    }
-    return `gql:${semantics.typeName}.${semantics.fieldName}`;
-  }
-  if (semantics.name === "message-bus") {
-    const { subject } = parseChannel(semantics.channel);
-    if (subject === "") {
-      return null;
+function boundaryLabel(binding) {
+  const behavior = behaviorOf(binding.semantics);
+  return (behavior.displayLabel ?? behavior.identityKey)(binding.semantics);
+}
+function displayLabel(binding) {
+  return boundaryLabel(binding) ?? `${binding.semantics.name}:${binding.recognition}`;
+}
+function normalizeRuleBoundary(raw) {
+  const trimmed = raw.trim();
+  for (const behavior of allBehaviors()) {
+    if (behavior.ruleBoundary?.claims(trimmed) === true) {
+      return behavior.ruleBoundary.normalize(trimmed);
     }
-    return `bus:${semantics.messageBus} ${subject}`;
   }
-  if (semantics.name === "function-call") {
-    if (semantics.package !== void 0 && semantics.exportPath !== void 0 && semantics.exportPath.length > 0) {
-      return `fn:${semantics.package}::${semantics.exportPath.join(".")}`;
-    }
+  return trimmed;
+}
+function exchangesHttpResponses(binding) {
+  return behaviorOf(binding.semantics).exchangesHttpResponses;
+}
+function reportsUnpairedItself(binding) {
+  return behaviorOf(binding.semantics).reportsUnpairedItself;
+}
+function servesRequest(binding, method, path) {
+  const serves = behaviorOf(binding.semantics).servesRequest;
+  if (serves === void 0) {
     return null;
   }
-  return null;
+  return serves(binding.semantics, method, path);
 }
 
 // src/codeScope.ts
@@ -363,56 +708,56 @@ function dispatchByType(table, value) {
 }
 
 // src/suppressions.ts
-var import_zod2 = require("zod");
-var SuppressionSideSchema = import_zod2.z.object({
-  summary: import_zod2.z.string().optional(),
-  transitionId: import_zod2.z.string().optional()
+var import_zod11 = require("zod");
+var SuppressionSideSchema = import_zod11.z.object({
+  summary: import_zod11.z.string().optional(),
+  transitionId: import_zod11.z.string().optional()
 }).optional();
-var SuppressionRuleSchema = import_zod2.z.object({
+var SuppressionRuleSchema = import_zod11.z.object({
   /**
-   * Finding kind to match — any behavioural or intent finding kind.
-   * Open here (this package sits below both IRs); the loader
-   * validates against the published kind enums.
+   * 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.
    */
-  kind: import_zod2.z.string().optional(),
+  kind: import_zod11.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.
    */
-  boundary: import_zod2.z.string().optional(),
+  boundary: import_zod11.z.string().optional(),
   /**
-   * Consumer-side discriminators (narrowest useful match). Only
-   * meaningful for behavioural findings — a rule that specifies
-   * `consumer` never matches an intent finding, which has no
-   * consumer side.
+   * 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: SuppressionSideSchema,
   /**
    * Provider-side discriminators, the mirror of `consumer`. A finding
-   * about a status the provider produces carries its transition id on
-   * this side, and that id is the only handle narrow enough to name
-   * that one finding. Like `consumer`, a rule that specifies
+   * 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: SuppressionSideSchema,
   /**
-   * "narrow" (default): requires kind plus one of boundary,
-   * consumer.transitionId, or provider.transitionId — enough to
-   * target a specific finding class. "broad" opts in to kind-only or
-   * boundary-only matches, which silence future regressions in that
-   * category too.
+   * "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.
    */
-  scope: import_zod2.z.enum(["narrow", "broad"]).default("narrow"),
+  scope: import_zod11.z.enum(["narrow", "broad"]).default("narrow"),
   /** Required human-written justification. */
-  reason: import_zod2.z.string().min(1),
+  reason: import_zod11.z.string().min(1),
   /** What to do when a finding matches. */
-  effect: import_zod2.z.enum(["mark", "downgrade", "hide"]).default("mark")
+  effect: import_zod11.z.enum(["mark", "downgrade", "hide"]).default("mark")
 }).strict();
-var SuppressionFileSchema = import_zod2.z.object({
-  version: import_zod2.z.literal(1),
-  rules: import_zod2.z.array(SuppressionRuleSchema)
+var SuppressionFileSchema = import_zod11.z.object({
+  version: import_zod11.z.literal(1),
+  rules: import_zod11.z.array(SuppressionRuleSchema)
 }).strict();
 function validateRule(rule) {
   if (rule.scope === "broad") {
@@ -429,16 +774,6 @@ function validateRule(rule) {
   }
   return "narrow-scope rule must specify kind AND (boundary OR consumer.transitionId OR provider.transitionId); set scope: 'broad' to silence wider categories";
 }
-function normalizeRuleBoundary(raw) {
-  const trimmed = raw.trim();
-  const spaceIdx = trimmed.indexOf(" ");
-  if (spaceIdx < 0) {
-    return trimmed;
-  }
-  const method = trimmed.slice(0, spaceIdx).toUpperCase();
-  const path = trimmed.slice(spaceIdx + 1);
-  return `${method} ${normalizePath(path)}`;
-}
 function ruleBoundaryMatchesKey(ruleBoundary, key) {
   if (key === null) {
     return false;
@@ -634,13 +969,22 @@ function allowsUndefined(shape) {
 }
 
 // src/index.ts
+function namedOrNull(value, field) {
+  if (value === "") {
+    throw new Error(
+      `${field} is an empty string; write null when the source does not name it`
+    );
+  }
+  return value;
+}
 function restBinding(opts) {
+  const method = namedOrNull(opts.method, "rest method");
   return {
     transport: opts.transport,
     semantics: {
       name: "rest",
-      method: opts.method.toUpperCase(),
-      path: opts.path,
+      method: method === null ? null : method.toUpperCase(),
+      path: namedOrNull(opts.path, "rest path"),
       ...opts.declaredResponses !== void 0 ? { declaredResponses: opts.declaredResponses } : {}
     },
     recognition: opts.recognition
@@ -672,7 +1016,7 @@ function graphqlResolverBinding(opts) {
     transport: opts.transport,
     semantics: {
       name: "graphql-resolver",
-      typeName: opts.typeName,
+      typeName: namedOrNull(opts.typeName, "resolver typeName"),
       fieldName: opts.fieldName
     },
     recognition: opts.recognition
@@ -718,7 +1062,7 @@ function messageBusBinding(opts) {
     semantics: {
       name: "message-bus",
       messageBus: opts.messageBus,
-      channel: opts.channel
+      channel: namedOrNull(opts.channel, "message-bus channel")
     },
     recognition: opts.recognition
   };
@@ -746,23 +1090,34 @@ function messageBusBinding(opts) {
   applySuppressionsToFindings,
   bodyShapesMatch,
   boundaryKey,
+  boundaryLabel,
   busesAgree,
   channelsPair,
   codeScopePath,
   countsForThreshold,
   dispatchByType,
+  displayLabel,
+  ecsContainerInstanceName,
+  exchangesHttpResponses,
   fileInCodeScope,
+  formatChannel,
   functionCallBinding,
   graphqlOperationBinding,
   graphqlResolverBinding,
   messageBusBinding,
+  methodsAgree,
   normalizePath,
   normalizeRuleBoundary,
   packageExportBinding,
+  pairingKey,
   parseChannel,
+  reportsUnpairedItself,
   restBinding,
+  routePathAdmits,
   ruleBoundaryMatchesKey,
   runtimeConfigBinding,
+  semanticsAgree,
+  servesRequest,
   storageRelationalBinding,
   typeDefinitionKey,
   validateRule,