@suss/ir-core 0.5.8 → 0.5.10

package/dist/index.cjs

@@ -42,7 +42,9 @@ __export(index_exports, {
   bodyShapesMatch: () => bodyShapesMatch,
   boundaryKey: () => boundaryKey,
   boundaryLabel: () => boundaryLabel,
+  busIdentityKey: () => busIdentityKey,
   busesAgree: () => busesAgree,
+  canPair: () => canPair,
   channelsPair: () => channelsPair,
   codeScopePath: () => codeScopePath,
   countsForThreshold: () => countsForThreshold,
@@ -51,10 +53,13 @@ __export(index_exports, {
   ecsContainerInstanceName: () => ecsContainerInstanceName,
   exchangesHttpResponses: () => exchangesHttpResponses,
   fileInCodeScope: () => fileInCodeScope,
+  fnIdentityKey: () => fnIdentityKey,
   formatChannel: () => formatChannel,
   functionCallBinding: () => functionCallBinding,
+  gqlIdentityKey: () => gqlIdentityKey,
   graphqlOperationBinding: () => graphqlOperationBinding,
   graphqlResolverBinding: () => graphqlResolverBinding,
+  isGraphqlOperationBinding: () => isGraphqlOperationBinding,
   messageBusBinding: () => messageBusBinding,
   methodsAgree: () => methodsAgree,
   normalizePath: () => normalizePath,
@@ -76,13 +81,7 @@ __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
+// src/semantics/graphqlOperation.ts
 var import_zod = require("zod");
 
 // src/semantics/definition.ts
@@ -90,18 +89,63 @@ function defineBoundarySemantics(definition) {
   return definition;
 }
 
+// src/semantics/graphqlOperation.ts
+var GraphqlOperationSemanticsSchema = import_zod.z.object({
+  name: import_zod.z.literal("graphql-operation"),
+  /** Optional operation name. An anonymous query or mutation leaves it unset. */
+  operationName: import_zod.z.string().optional(),
+  operationType: import_zod.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,
+    /** Keyless by design; the dedicated pass pairs it by its document. */
+    canPair: () => true,
+    /** "query GetUser". The contract checker pairs it, the key does not. */
+    displayLabel(semantics) {
+      return `${semantics.operationType} ${semantics.operationName ?? "<anonymous>"}`;
+    }
+  }
+});
+
+// src/identityKeys.ts
+function gqlIdentityKey(typeName, fieldName) {
+  return `gql:${typeName}.${fieldName}`;
+}
+function fnIdentityKey(packageName, exportPath) {
+  return `fn:${packageName}::${exportPath.join(".")}`;
+}
+function busIdentityKey(messageBus, subject) {
+  return `bus:${messageBus} ${subject}`;
+}
+
+// src/schemas.ts
+var import_zod10 = require("zod");
+
+// src/semantics/registry.ts
+var import_zod9 = require("zod");
+
 // src/semantics/functionCall.ts
-var FunctionCallSemanticsSchema = import_zod.z.object({
-  name: import_zod.z.literal("function-call"),
+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.
    */
-  module: import_zod.z.string().optional(),
+  module: import_zod2.z.string().optional(),
   /** Named export within the module, when applicable. */
-  exportName: import_zod.z.string().optional(),
+  exportName: import_zod2.z.string().optional(),
   /**
    * Package name, as written in `package.json`, when this identity
    * refers to a public package export, for example
@@ -110,7 +154,7 @@ var FunctionCallSemanticsSchema = import_zod.z.object({
    * `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(),
+  package: import_zod2.z.string().optional(),
   /**
    * Path to the exported binding within the package, starting with the
    * sub-path key when one is used. Examples:
@@ -120,7 +164,7 @@ var FunctionCallSemanticsSchema = import_zod.z.object({
    * 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()
+  exportPath: import_zod2.z.array(import_zod2.z.string()).optional()
 });
 var functionCallSemantics = defineBoundarySemantics({
   name: "function-call",
@@ -129,6 +173,12 @@ var functionCallSemantics = defineBoundarySemantics({
     /** A call returns a value, which is not a status and a body. */
     exchangesHttpResponses: 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.
+     */
+    canPair: () => true,
     /**
      * `"fn:<package>::<exportPath>"` when both are set. Other in-process
      * function-call units, such as components and bare handlers inside
@@ -136,39 +186,13 @@ var functionCallSemantics = defineBoundarySemantics({
      */
     identityKey(semantics) {
       if (semantics.package !== void 0 && semantics.exportPath !== void 0 && semantics.exportPath.length > 0) {
-        return `fn:${semantics.package}::${semantics.exportPath.join(".")}`;
+        return fnIdentityKey(semantics.package, semantics.exportPath);
       }
       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({
@@ -198,7 +222,7 @@ var graphqlResolverSemantics = defineBoundarySemantics({
       if (semantics.typeName === null || semantics.fieldName === "") {
         return null;
       }
-      return `gql:${semantics.typeName}.${semantics.fieldName}`;
+      return gqlIdentityKey(semantics.typeName, semantics.fieldName);
     }
   }
 });
@@ -260,6 +284,12 @@ var messageBusSemantics = defineBoundarySemantics({
      * ones, so the generic unmatched lists leave them alone.
      */
     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.
+     */
+    canPair: () => true,
     /**
      * `"bus:<messageBus> <subject>"`, or null when the channel is null
      * or its subject is empty.
@@ -282,7 +312,7 @@ var messageBusSemantics = defineBoundarySemantics({
       if (subject === "") {
         return null;
       }
-      return `bus:${semantics.messageBus} ${subject}`;
+      return busIdentityKey(semantics.messageBus, subject);
     },
     sidesAgree(a, b) {
       if (a.channel === null || b.channel === null) {
@@ -477,8 +507,13 @@ var StorageRelationalSemanticsSchema = import_zod8.z.object({
    * and a monorepo with several schemas gives each one its own value.
    */
   scope: import_zod8.z.string(),
-  /** The table or model name, as declared in the schema. */
-  table: import_zod8.z.string()
+  /**
+   * The table or model name as the schema declares it, or null when
+   * the source states one this reader could not settle. A null table
+   * pairs with nothing, rather than with whatever its source text
+   * happens to spell.
+   */
+  table: import_zod8.z.string().nullable()
 });
 var storageRelationalSemantics = defineBoundarySemantics({
   name: "storage-relational",
@@ -677,6 +712,13 @@ function normalizeRuleBoundary(raw) {
 function exchangesHttpResponses(binding) {
   return behaviorOf(binding.semantics).exchangesHttpResponses;
 }
+function canPair(binding) {
+  const behavior = behaviorOf(binding.semantics);
+  if (behavior.canPair !== void 0) {
+    return behavior.canPair(binding.semantics);
+  }
+  return pairingKey(binding) !== null;
+}
 function reportsUnpairedItself(binding) {
   return behaviorOf(binding.semantics).reportsUnpairedItself;
 }
@@ -1033,6 +1075,9 @@ function graphqlOperationBinding(opts) {
     recognition: opts.recognition
   };
 }
+function isGraphqlOperationBinding(binding) {
+  return binding != null && GraphqlOperationSemanticsSchema.safeParse(binding.semantics).success;
+}
 function runtimeConfigBinding(opts) {
   return {
     transport: "os",
@@ -1051,7 +1096,7 @@ function storageRelationalBinding(opts) {
       name: "storage-relational",
       storageSystem: opts.storageSystem,
       scope: opts.scope,
-      table: opts.table
+      table: namedOrNull(opts.table, "storage table")
     },
     recognition: opts.recognition
   };
@@ -1091,7 +1136,9 @@ function messageBusBinding(opts) {
   bodyShapesMatch,
   boundaryKey,
   boundaryLabel,
+  busIdentityKey,
   busesAgree,
+  canPair,
   channelsPair,
   codeScopePath,
   countsForThreshold,
@@ -1100,10 +1147,13 @@ function messageBusBinding(opts) {
   ecsContainerInstanceName,
   exchangesHttpResponses,
   fileInCodeScope,
+  fnIdentityKey,
   formatChannel,
   functionCallBinding,
+  gqlIdentityKey,
   graphqlOperationBinding,
   graphqlResolverBinding,
+  isGraphqlOperationBinding,
   messageBusBinding,
   methodsAgree,
   normalizePath,

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
-import { T as TypeShape, S as Semantics, B as BoundaryBindingSchema, C as ConfidenceInfoSchema, a as ConfidenceLevelSchema, b as ConfidenceSourceSchema, c as CorroborationSchema, d as SourceLocationSchema, M as MessageBusTechnology } from './schemas-BWvfkxSH.cjs';
-export { D as DeployableUnit, e as DeployableUnitSchema, F as FunctionCallSemantics, f as FunctionCallSemanticsSchema, G as GraphqlOperationSemantics, g as GraphqlOperationSemanticsSchema, h as GraphqlResolverSemantics, i as GraphqlResolverSemanticsSchema, j as MessageBusSemantics, k as MessageBusSemanticsSchema, R as RestSemantics, l as RestSemanticsSchema, m as RuntimeConfigSemantics, n as RuntimeConfigSemanticsSchema, o as SemanticsSchema, p as StorageRelationalSemantics, q as StorageRelationalSemanticsSchema, r as TypeShapeSchema, s as ecsContainerInstanceName, t as methodsAgree, u as normalizePath, v as routePathAdmits, w as typeDefinitionKey, x as withDefinitionsInlined } from './schemas-BWvfkxSH.cjs';
+import { T as TypeShape, M as MessageBusSemantics, S as Semantics, B as BoundaryBindingSchema, C as ConfidenceInfoSchema, a as ConfidenceLevelSchema, b as ConfidenceSourceSchema, c as CorroborationSchema, d as SourceLocationSchema, e as MessageBusTechnology } from './schemas-N9GyG0Sn.cjs';
+export { D as DeployableUnit, f as DeployableUnitSchema, F as FunctionCallSemantics, g as FunctionCallSemanticsSchema, G as GraphqlOperationSemantics, h as GraphqlOperationSemanticsSchema, i as GraphqlResolverSemantics, j as GraphqlResolverSemanticsSchema, k as MessageBusSemanticsSchema, R as RestSemantics, l as RestSemanticsSchema, m as RuntimeConfigSemantics, n as RuntimeConfigSemanticsSchema, o as SemanticsSchema, p as StorageRelationalSemantics, q as StorageRelationalSemanticsSchema, r as TypeShapeSchema, s as ecsContainerInstanceName, t as methodsAgree, u as normalizePath, v as routePathAdmits, w as typeDefinitionKey, x as withDefinitionsInlined } from './schemas-N9GyG0Sn.cjs';
 
 /**
  * Comparing two TypeShapes structurally.
@@ -104,6 +104,13 @@ interface BoundaryBehavior<S extends {
      * paired with nothing, so the generic unmatched list can leave it out.
      */
     reportsUnpairedItself: boolean;
+    /**
+     * Whether a boundary with these semantics can pair with anything.
+     * Defaults to a non-null pairing key. A protocol whose dedicated
+     * pass pairs keyless boundaries overrides it, the way GraphQL
+     * operations pair by document rather than by key.
+     */
+    canPair?(semantics: S): boolean;
 }
 /**
  * One protocol in full: the schema for its identity fields, and the
@@ -118,6 +125,23 @@ interface BoundarySemanticsDefinition<Z extends z.ZodType<{
     behavior: BoundaryBehavior<z.infer<Z>>;
 }
 
+declare const IdentityKeyBrand: unique symbol;
+/** `gql:Type.field`, the boundary key both GraphQL sides pair on. */
+type GqlIdentityKey = `gql:${string}.${string}` & {
+    readonly [IdentityKeyBrand]: "gql";
+};
+declare function gqlIdentityKey(typeName: string, fieldName: string): GqlIdentityKey;
+/** `fn:package::export.path`, the key a package-export boundary pairs on. */
+type FnIdentityKey = `fn:${string}::${string}` & {
+    readonly [IdentityKeyBrand]: "fn";
+};
+declare function fnIdentityKey(packageName: string, exportPath: readonly string[]): FnIdentityKey;
+/** `bus:technology subject`, with the technology closed off the schema. */
+type BusIdentityKey = `bus:${MessageBusSemantics["messageBus"]} ${string}` & {
+    readonly [IdentityKeyBrand]: "bus";
+};
+declare function busIdentityKey(messageBus: MessageBusSemantics["messageBus"], subject: string): BusIdentityKey;
+
 /**
  * Keys for a boundary binding, and whether two of them agree. Every
  * function here asks the binding's protocol and returns whatever it
@@ -143,6 +167,11 @@ declare function displayLabel(binding: BoundaryBinding): string;
  */
 declare function normalizeRuleBoundary(raw: string): string;
 declare function exchangesHttpResponses(binding: BoundaryBinding): boolean;
+/**
+ * Whether anything can pair with this binding: it has a pairing key,
+ * or its protocol pairs keyless boundaries in a dedicated pass.
+ */
+declare function canPair(binding: BoundaryBinding): boolean;
 declare function reportsUnpairedItself(binding: BoundaryBinding): boolean;
 /**
  * Null means the protocol does not address its boundaries by method and
@@ -171,7 +200,17 @@ interface ParsedChannel {
     subject: string;
 }
 declare function parseChannel(channel: string): ParsedChannel;
-declare function formatChannel(bus: string | null, subject: string): string;
+declare const ChannelBrand: unique symbol;
+/**
+ * `bus#subject`, or the bare subject when no source said the bus. The
+ * unqualified form is legal, so fields keep the type string and the
+ * mint is the whole win: a channel assembled by hand cannot claim the
+ * brand, and the format has one spelling (#167).
+ */
+type Channel = string & {
+    readonly [ChannelBrand]: "channel";
+};
+declare function formatChannel(bus: string | null, subject: string): Channel;
 declare function busesAgree(a: string | null, b: string | null): boolean;
 declare function channelsPair(a: string, b: string): boolean;
 
@@ -418,6 +457,12 @@ declare function graphqlOperationBinding(opts: {
     operationType: "query" | "mutation" | "subscription";
     operationName?: string;
 }): BoundaryBinding;
+/**
+ * Whether a binding is the consumer side of a GraphQL boundary,
+ * settled by the protocol's own schema so callers do not compare the
+ * semantics tag themselves.
+ */
+declare function isGraphqlOperationBinding(binding: BoundaryBinding | null | undefined): boolean;
 /**
  * Build a runtime-config binding, the provider side of a runtime
  * configuration channel (env vars on a Lambda, ECS task, container, or
@@ -439,7 +484,8 @@ declare function storageRelationalBinding(opts: {
     recognition: string;
     storageSystem: "postgres" | "mysql" | "sqlite";
     scope: string;
-    table: string;
+    /** Null when the source names a table this reader could not settle. */
+    table: string | null;
 }): BoundaryBinding;
 /**
  * Build a message-bus binding, the boundary between a producer that
@@ -452,4 +498,4 @@ declare function messageBusBinding(opts: {
     channel: string | null;
 }): BoundaryBinding;
 
-export { type BoundaryBehavior, type BoundaryBinding, BoundaryBindingSchema, type BoundarySemanticsDefinition, type ConfidenceInfo, ConfidenceInfoSchema, type ConfidenceLevel, ConfidenceLevelSchema, type ConfidenceSource, ConfidenceSourceSchema, type Corroboration, CorroborationSchema, type DispatchTable, type FindingSuppression, type MatchResult, MessageBusTechnology, type ParsedChannel, Semantics, type SourceLocation, SourceLocationSchema, type SuppressableSeverity, type SuppressibleFinding, type SuppressionFile, SuppressionFileSchema, type SuppressionRule, SuppressionRuleSchema, TypeShape, applySuppressionsToFindings, bodyShapesMatch, boundaryKey, boundaryLabel, busesAgree, channelsPair, codeScopePath, countsForThreshold, dispatchByType, displayLabel, exchangesHttpResponses, fileInCodeScope, formatChannel, functionCallBinding, graphqlOperationBinding, graphqlResolverBinding, messageBusBinding, normalizeRuleBoundary, packageExportBinding, pairingKey, parseChannel, reportsUnpairedItself, restBinding, ruleBoundaryMatchesKey, runtimeConfigBinding, semanticsAgree, servesRequest, storageRelationalBinding, validateRule };
+export { type BoundaryBehavior, type BoundaryBinding, BoundaryBindingSchema, type BoundarySemanticsDefinition, type BusIdentityKey, type Channel, type ConfidenceInfo, ConfidenceInfoSchema, type ConfidenceLevel, ConfidenceLevelSchema, type ConfidenceSource, ConfidenceSourceSchema, type Corroboration, CorroborationSchema, type DispatchTable, type FindingSuppression, type FnIdentityKey, type GqlIdentityKey, type MatchResult, MessageBusSemantics, MessageBusTechnology, type ParsedChannel, Semantics, type SourceLocation, SourceLocationSchema, type SuppressableSeverity, type SuppressibleFinding, type SuppressionFile, SuppressionFileSchema, type SuppressionRule, SuppressionRuleSchema, TypeShape, applySuppressionsToFindings, bodyShapesMatch, boundaryKey, boundaryLabel, busIdentityKey, busesAgree, canPair, channelsPair, codeScopePath, countsForThreshold, dispatchByType, displayLabel, exchangesHttpResponses, fileInCodeScope, fnIdentityKey, formatChannel, functionCallBinding, gqlIdentityKey, graphqlOperationBinding, graphqlResolverBinding, isGraphqlOperationBinding, messageBusBinding, normalizeRuleBoundary, packageExportBinding, pairingKey, parseChannel, reportsUnpairedItself, restBinding, ruleBoundaryMatchesKey, runtimeConfigBinding, semanticsAgree, servesRequest, storageRelationalBinding, validateRule };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
-import { T as TypeShape, S as Semantics, B as BoundaryBindingSchema, C as ConfidenceInfoSchema, a as ConfidenceLevelSchema, b as ConfidenceSourceSchema, c as CorroborationSchema, d as SourceLocationSchema, M as MessageBusTechnology } from './schemas-BWvfkxSH.js';
-export { D as DeployableUnit, e as DeployableUnitSchema, F as FunctionCallSemantics, f as FunctionCallSemanticsSchema, G as GraphqlOperationSemantics, g as GraphqlOperationSemanticsSchema, h as GraphqlResolverSemantics, i as GraphqlResolverSemanticsSchema, j as MessageBusSemantics, k as MessageBusSemanticsSchema, R as RestSemantics, l as RestSemanticsSchema, m as RuntimeConfigSemantics, n as RuntimeConfigSemanticsSchema, o as SemanticsSchema, p as StorageRelationalSemantics, q as StorageRelationalSemanticsSchema, r as TypeShapeSchema, s as ecsContainerInstanceName, t as methodsAgree, u as normalizePath, v as routePathAdmits, w as typeDefinitionKey, x as withDefinitionsInlined } from './schemas-BWvfkxSH.js';
+import { T as TypeShape, M as MessageBusSemantics, S as Semantics, B as BoundaryBindingSchema, C as ConfidenceInfoSchema, a as ConfidenceLevelSchema, b as ConfidenceSourceSchema, c as CorroborationSchema, d as SourceLocationSchema, e as MessageBusTechnology } from './schemas-N9GyG0Sn.js';
+export { D as DeployableUnit, f as DeployableUnitSchema, F as FunctionCallSemantics, g as FunctionCallSemanticsSchema, G as GraphqlOperationSemantics, h as GraphqlOperationSemanticsSchema, i as GraphqlResolverSemantics, j as GraphqlResolverSemanticsSchema, k as MessageBusSemanticsSchema, R as RestSemantics, l as RestSemanticsSchema, m as RuntimeConfigSemantics, n as RuntimeConfigSemanticsSchema, o as SemanticsSchema, p as StorageRelationalSemantics, q as StorageRelationalSemanticsSchema, r as TypeShapeSchema, s as ecsContainerInstanceName, t as methodsAgree, u as normalizePath, v as routePathAdmits, w as typeDefinitionKey, x as withDefinitionsInlined } from './schemas-N9GyG0Sn.js';
 
 /**
  * Comparing two TypeShapes structurally.
@@ -104,6 +104,13 @@ interface BoundaryBehavior<S extends {
      * paired with nothing, so the generic unmatched list can leave it out.
      */
     reportsUnpairedItself: boolean;
+    /**
+     * Whether a boundary with these semantics can pair with anything.
+     * Defaults to a non-null pairing key. A protocol whose dedicated
+     * pass pairs keyless boundaries overrides it, the way GraphQL
+     * operations pair by document rather than by key.
+     */
+    canPair?(semantics: S): boolean;
 }
 /**
  * One protocol in full: the schema for its identity fields, and the
@@ -118,6 +125,23 @@ interface BoundarySemanticsDefinition<Z extends z.ZodType<{
     behavior: BoundaryBehavior<z.infer<Z>>;
 }
 
+declare const IdentityKeyBrand: unique symbol;
+/** `gql:Type.field`, the boundary key both GraphQL sides pair on. */
+type GqlIdentityKey = `gql:${string}.${string}` & {
+    readonly [IdentityKeyBrand]: "gql";
+};
+declare function gqlIdentityKey(typeName: string, fieldName: string): GqlIdentityKey;
+/** `fn:package::export.path`, the key a package-export boundary pairs on. */
+type FnIdentityKey = `fn:${string}::${string}` & {
+    readonly [IdentityKeyBrand]: "fn";
+};
+declare function fnIdentityKey(packageName: string, exportPath: readonly string[]): FnIdentityKey;
+/** `bus:technology subject`, with the technology closed off the schema. */
+type BusIdentityKey = `bus:${MessageBusSemantics["messageBus"]} ${string}` & {
+    readonly [IdentityKeyBrand]: "bus";
+};
+declare function busIdentityKey(messageBus: MessageBusSemantics["messageBus"], subject: string): BusIdentityKey;
+
 /**
  * Keys for a boundary binding, and whether two of them agree. Every
  * function here asks the binding's protocol and returns whatever it
@@ -143,6 +167,11 @@ declare function displayLabel(binding: BoundaryBinding): string;
  */
 declare function normalizeRuleBoundary(raw: string): string;
 declare function exchangesHttpResponses(binding: BoundaryBinding): boolean;
+/**
+ * Whether anything can pair with this binding: it has a pairing key,
+ * or its protocol pairs keyless boundaries in a dedicated pass.
+ */
+declare function canPair(binding: BoundaryBinding): boolean;
 declare function reportsUnpairedItself(binding: BoundaryBinding): boolean;
 /**
  * Null means the protocol does not address its boundaries by method and
@@ -171,7 +200,17 @@ interface ParsedChannel {
     subject: string;
 }
 declare function parseChannel(channel: string): ParsedChannel;
-declare function formatChannel(bus: string | null, subject: string): string;
+declare const ChannelBrand: unique symbol;
+/**
+ * `bus#subject`, or the bare subject when no source said the bus. The
+ * unqualified form is legal, so fields keep the type string and the
+ * mint is the whole win: a channel assembled by hand cannot claim the
+ * brand, and the format has one spelling (#167).
+ */
+type Channel = string & {
+    readonly [ChannelBrand]: "channel";
+};
+declare function formatChannel(bus: string | null, subject: string): Channel;
 declare function busesAgree(a: string | null, b: string | null): boolean;
 declare function channelsPair(a: string, b: string): boolean;
 
@@ -418,6 +457,12 @@ declare function graphqlOperationBinding(opts: {
     operationType: "query" | "mutation" | "subscription";
     operationName?: string;
 }): BoundaryBinding;
+/**
+ * Whether a binding is the consumer side of a GraphQL boundary,
+ * settled by the protocol's own schema so callers do not compare the
+ * semantics tag themselves.
+ */
+declare function isGraphqlOperationBinding(binding: BoundaryBinding | null | undefined): boolean;
 /**
  * Build a runtime-config binding, the provider side of a runtime
  * configuration channel (env vars on a Lambda, ECS task, container, or
@@ -439,7 +484,8 @@ declare function storageRelationalBinding(opts: {
     recognition: string;
     storageSystem: "postgres" | "mysql" | "sqlite";
     scope: string;
-    table: string;
+    /** Null when the source names a table this reader could not settle. */
+    table: string | null;
 }): BoundaryBinding;
 /**
  * Build a message-bus binding, the boundary between a producer that
@@ -452,4 +498,4 @@ declare function messageBusBinding(opts: {
     channel: string | null;
 }): BoundaryBinding;
 
-export { type BoundaryBehavior, type BoundaryBinding, BoundaryBindingSchema, type BoundarySemanticsDefinition, type ConfidenceInfo, ConfidenceInfoSchema, type ConfidenceLevel, ConfidenceLevelSchema, type ConfidenceSource, ConfidenceSourceSchema, type Corroboration, CorroborationSchema, type DispatchTable, type FindingSuppression, type MatchResult, MessageBusTechnology, type ParsedChannel, Semantics, type SourceLocation, SourceLocationSchema, type SuppressableSeverity, type SuppressibleFinding, type SuppressionFile, SuppressionFileSchema, type SuppressionRule, SuppressionRuleSchema, TypeShape, applySuppressionsToFindings, bodyShapesMatch, boundaryKey, boundaryLabel, busesAgree, channelsPair, codeScopePath, countsForThreshold, dispatchByType, displayLabel, exchangesHttpResponses, fileInCodeScope, formatChannel, functionCallBinding, graphqlOperationBinding, graphqlResolverBinding, messageBusBinding, normalizeRuleBoundary, packageExportBinding, pairingKey, parseChannel, reportsUnpairedItself, restBinding, ruleBoundaryMatchesKey, runtimeConfigBinding, semanticsAgree, servesRequest, storageRelationalBinding, validateRule };
+export { type BoundaryBehavior, type BoundaryBinding, BoundaryBindingSchema, type BoundarySemanticsDefinition, type BusIdentityKey, type Channel, type ConfidenceInfo, ConfidenceInfoSchema, type ConfidenceLevel, ConfidenceLevelSchema, type ConfidenceSource, ConfidenceSourceSchema, type Corroboration, CorroborationSchema, type DispatchTable, type FindingSuppression, type FnIdentityKey, type GqlIdentityKey, type MatchResult, MessageBusSemantics, MessageBusTechnology, type ParsedChannel, Semantics, type SourceLocation, SourceLocationSchema, type SuppressableSeverity, type SuppressibleFinding, type SuppressionFile, SuppressionFileSchema, type SuppressionRule, SuppressionRuleSchema, TypeShape, applySuppressionsToFindings, bodyShapesMatch, boundaryKey, boundaryLabel, busIdentityKey, busesAgree, canPair, channelsPair, codeScopePath, countsForThreshold, dispatchByType, displayLabel, exchangesHttpResponses, fileInCodeScope, fnIdentityKey, formatChannel, functionCallBinding, gqlIdentityKey, graphqlOperationBinding, graphqlResolverBinding, isGraphqlOperationBinding, messageBusBinding, normalizeRuleBoundary, packageExportBinding, pairingKey, parseChannel, reportsUnpairedItself, restBinding, ruleBoundaryMatchesKey, runtimeConfigBinding, semanticsAgree, servesRequest, storageRelationalBinding, validateRule };

package/dist/index.js

@@ -17,17 +17,20 @@ import {
   TypeShapeSchema,
   allBehaviors,
   behaviorOf,
+  busIdentityKey,
   busesAgree,
   channelsPair,
   ecsContainerInstanceName,
+  fnIdentityKey,
   formatChannel,
+  gqlIdentityKey,
   methodsAgree,
   normalizePath,
   parseChannel,
   routePathAdmits,
   typeDefinitionKey,
   withDefinitionsInlined
-} from "./chunk-5KE7OWN3.js";
+} from "./chunk-WKR5SU4N.js";
 
 // src/boundaryKey.ts
 function boundaryKey(binding) {
@@ -63,6 +66,13 @@ function normalizeRuleBoundary(raw) {
 function exchangesHttpResponses(binding) {
   return behaviorOf(binding.semantics).exchangesHttpResponses;
 }
+function canPair(binding) {
+  const behavior = behaviorOf(binding.semantics);
+  if (behavior.canPair !== void 0) {
+    return behavior.canPair(binding.semantics);
+  }
+  return pairingKey(binding) !== null;
+}
 function reportsUnpairedItself(binding) {
   return behaviorOf(binding.semantics).reportsUnpairedItself;
 }
@@ -419,6 +429,9 @@ function graphqlOperationBinding(opts) {
     recognition: opts.recognition
   };
 }
+function isGraphqlOperationBinding(binding) {
+  return binding != null && GraphqlOperationSemanticsSchema.safeParse(binding.semantics).success;
+}
 function runtimeConfigBinding(opts) {
   return {
     transport: "os",
@@ -437,7 +450,7 @@ function storageRelationalBinding(opts) {
       name: "storage-relational",
       storageSystem: opts.storageSystem,
       scope: opts.scope,
-      table: opts.table
+      table: namedOrNull(opts.table, "storage table")
     },
     recognition: opts.recognition
   };
@@ -476,7 +489,9 @@ export {
   bodyShapesMatch,
   boundaryKey,
   boundaryLabel,
+  busIdentityKey,
   busesAgree,
+  canPair,
   channelsPair,
   codeScopePath,
   countsForThreshold,
@@ -485,10 +500,13 @@ export {
   ecsContainerInstanceName,
   exchangesHttpResponses,
   fileInCodeScope,
+  fnIdentityKey,
   formatChannel,
   functionCallBinding,
+  gqlIdentityKey,
   graphqlOperationBinding,
   graphqlResolverBinding,
+  isGraphqlOperationBinding,
   messageBusBinding,
   methodsAgree,
   normalizePath,

package/dist/{schemas-BWvfkxSH.d.cts → schemas-CaX7_SZ4.d.cts}

@@ -429,4 +429,4 @@ declare const TypeShapeSchema: z.ZodType<TypeShape>;
  */
 declare function withDefinitionsInlined(shape: TypeShape, definitions: Record<string, TypeShape> | undefined, depth?: number, inProgress?: ReadonlySet<string>): TypeShape;
 
-export { BoundaryBindingSchema as B, ConfidenceInfoSchema as C, type DeployableUnit as D, type FunctionCallSemantics as F, type GraphqlOperationSemantics as G, type MessageBusTechnology as M, type RestSemantics as R, type Semantics as S, type TypeShape as T, ConfidenceLevelSchema as a, ConfidenceSourceSchema as b, CorroborationSchema as c, SourceLocationSchema as d, DeployableUnitSchema as e, FunctionCallSemanticsSchema as f, GraphqlOperationSemanticsSchema as g, type GraphqlResolverSemantics as h, GraphqlResolverSemanticsSchema as i, type MessageBusSemantics as j, MessageBusSemanticsSchema as k, RestSemanticsSchema as l, type RuntimeConfigSemantics as m, RuntimeConfigSemanticsSchema as n, SemanticsSchema as o, type StorageRelationalSemantics as p, StorageRelationalSemanticsSchema as q, TypeShapeSchema as r, ecsContainerInstanceName as s, methodsAgree as t, normalizePath as u, routePathAdmits as v, typeDefinitionKey as w, withDefinitionsInlined as x };
+export { BoundaryBindingSchema as B, ConfidenceInfoSchema as C, type DeployableUnit as D, type FunctionCallSemantics as F, type GraphqlOperationSemantics as G, type MessageBusSemantics as M, type RestSemantics as R, type Semantics as S, type TypeShape as T, ConfidenceLevelSchema as a, ConfidenceSourceSchema as b, CorroborationSchema as c, SourceLocationSchema as d, type MessageBusTechnology as e, DeployableUnitSchema as f, FunctionCallSemanticsSchema as g, GraphqlOperationSemanticsSchema as h, type GraphqlResolverSemantics as i, GraphqlResolverSemanticsSchema as j, MessageBusSemanticsSchema as k, RestSemanticsSchema as l, type RuntimeConfigSemantics as m, RuntimeConfigSemanticsSchema as n, SemanticsSchema as o, type StorageRelationalSemantics as p, StorageRelationalSemanticsSchema as q, TypeShapeSchema as r, ecsContainerInstanceName as s, methodsAgree as t, normalizePath as u, routePathAdmits as v, typeDefinitionKey as w, withDefinitionsInlined as x };

package/dist/{schemas-BWvfkxSH.d.ts → schemas-CaX7_SZ4.d.ts}

@@ -429,4 +429,4 @@ declare const TypeShapeSchema: z.ZodType<TypeShape>;
  */
 declare function withDefinitionsInlined(shape: TypeShape, definitions: Record<string, TypeShape> | undefined, depth?: number, inProgress?: ReadonlySet<string>): TypeShape;
 
-export { BoundaryBindingSchema as B, ConfidenceInfoSchema as C, type DeployableUnit as D, type FunctionCallSemantics as F, type GraphqlOperationSemantics as G, type MessageBusTechnology as M, type RestSemantics as R, type Semantics as S, type TypeShape as T, ConfidenceLevelSchema as a, ConfidenceSourceSchema as b, CorroborationSchema as c, SourceLocationSchema as d, DeployableUnitSchema as e, FunctionCallSemanticsSchema as f, GraphqlOperationSemanticsSchema as g, type GraphqlResolverSemantics as h, GraphqlResolverSemanticsSchema as i, type MessageBusSemantics as j, MessageBusSemanticsSchema as k, RestSemanticsSchema as l, type RuntimeConfigSemantics as m, RuntimeConfigSemanticsSchema as n, SemanticsSchema as o, type StorageRelationalSemantics as p, StorageRelationalSemanticsSchema as q, TypeShapeSchema as r, ecsContainerInstanceName as s, methodsAgree as t, normalizePath as u, routePathAdmits as v, typeDefinitionKey as w, withDefinitionsInlined as x };
+export { BoundaryBindingSchema as B, ConfidenceInfoSchema as C, type DeployableUnit as D, type FunctionCallSemantics as F, type GraphqlOperationSemantics as G, type MessageBusSemantics as M, type RestSemantics as R, type Semantics as S, type TypeShape as T, ConfidenceLevelSchema as a, ConfidenceSourceSchema as b, CorroborationSchema as c, SourceLocationSchema as d, type MessageBusTechnology as e, DeployableUnitSchema as f, FunctionCallSemanticsSchema as g, GraphqlOperationSemanticsSchema as h, type GraphqlResolverSemantics as i, GraphqlResolverSemanticsSchema as j, MessageBusSemanticsSchema as k, RestSemanticsSchema as l, type RuntimeConfigSemantics as m, RuntimeConfigSemanticsSchema as n, SemanticsSchema as o, type StorageRelationalSemantics as p, StorageRelationalSemanticsSchema as q, TypeShapeSchema as r, ecsContainerInstanceName as s, methodsAgree as t, normalizePath as u, routePathAdmits as v, typeDefinitionKey as w, withDefinitionsInlined as x };