@suss/ir-core 0.33.1 → 0.34.1

package/dist/schemas.cjs

@@ -40,10 +40,10 @@ __export(schemas_exports, {
   withDefinitionsInlined: () => withDefinitionsInlined
 });
 module.exports = __toCommonJS(schemas_exports);
-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_zod = require("zod");
@@ -64,6 +64,9 @@ function unitIdentityKey(deploymentTarget, instanceName) {
 function metricIdentityKey(metricSystem, metricType) {
   return `metric:${metricSystem} ${metricType}`;
 }
+function ioIdentityKey(target) {
+  return `io:${target}`;
+}
 
 // src/semantics/definition.ts
 function defineBoundarySemantics(definition) {
@@ -74,10 +77,11 @@ function defineBoundarySemantics(definition) {
 var FunctionCallSemanticsSchema = import_zod.z.object({
   name: import_zod.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_zod.z.string().optional(),
   /** Named export within the module, when applicable. */
@@ -102,35 +106,38 @@ var FunctionCallSemanticsSchema = import_zod.z.object({
    */
   exportPath: import_zod.z.array(import_zod.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);
@@ -161,15 +168,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>"}`;
     }
@@ -192,14 +199,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,
     /**
@@ -216,8 +223,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) {
@@ -237,12 +268,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",
@@ -261,12 +291,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",
@@ -280,25 +311,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
@@ -321,9 +353,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) {
@@ -335,25 +367,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,
@@ -369,7 +401,7 @@ var metricSemantics = defineBoundarySemantics({
 });
 
 // src/semantics/rest.ts
-var import_zod6 = require("zod");
+var import_zod7 = require("zod");
 
 // src/boundaryName.ts
 var HOLE_SPLIT = /(\{[^}]*\})/;
@@ -417,6 +449,38 @@ function pathAfterOrigin(text) {
   const cut = withoutOrigin.search(/[?#]/);
   return cut === -1 ? withoutOrigin : withoutOrigin.slice(0, cut);
 }
+var PRIVATE_SUFFIXES = [
+  "local",
+  "internal",
+  "localhost",
+  "lan",
+  "home.arpa",
+  "svc",
+  "test",
+  "example",
+  "invalid",
+  "example.com",
+  "example.net",
+  "example.org"
+];
+var PRIVATE_IPV4 = /^(?:127\.|10\.|192\.168\.|169\.254\.|172\.(?:1[6-9]|2\d|3[01])\.|0\.0\.0\.0$)/;
+function hostnameOf(host) {
+  const lower = host.toLowerCase();
+  const name = lower.startsWith("[") ? lower.slice(0, lower.indexOf("]") + 1) : lower.split(":")[0] ?? lower;
+  return name.replace(/\.$/, "");
+}
+function hostCanBeOwn(host) {
+  const name = hostnameOf(host);
+  if (name === "[::1]" || /^\[f[cd]/.test(name) || PRIVATE_IPV4.test(name)) {
+    return true;
+  }
+  if (!name.includes(".")) {
+    return true;
+  }
+  return PRIVATE_SUFFIXES.some(
+    (suffix) => name === suffix || name.endsWith(`.${suffix}`)
+  );
+}
 
 // src/semantics/pathPattern.ts
 var ONE = { kind: "one" };
@@ -467,14 +531,18 @@ function shapedItem(segment) {
       return ".*";
     }
     if (part.startsWith("{")) {
-      return "[^/]+";
+      return /[?*]\}$/.test(part) ? "[^/]*" : "[^/]+";
     }
     return escapedForRegex(part);
   }).join("");
+  const holes = segment.match(/\{[^}]*\}|\*/g) ?? [];
+  const text = segment.replace(/\{[^}]*\}|\*/g, "");
   return {
     kind: "shaped",
     shape: segment.replace(/\{[^}]*\}/g, "{}"),
-    test: new RegExp(`^${source}$`)
+    test: new RegExp(`^${source}$`),
+    bare: holes.every((hole) => hole === "*" || /[?*]\}$/.test(hole)) ? text : null,
+    textLength: text.length
   };
 }
 function itemsOf(segment) {
@@ -494,10 +562,35 @@ function segmentsOf(alternative) {
   const trimmed = alternative.startsWith("/") ? alternative.slice(1) : alternative;
   return trimmed === "" ? [] : trimmed.split("/");
 }
+function patternSegmentsOf(alternative) {
+  const segments = segmentsOf(alternative);
+  const first = segments[0];
+  const opensWithBaseUrl = !alternative.startsWith("/") && first !== void 0 && HOLE_SEGMENT.test(first);
+  return opensWithBaseUrl ? segments.slice(1) : segments;
+}
+function pathAfterBaseUrl(path) {
+  const segments = segmentsOf(path);
+  const first = segments[0];
+  if (path.startsWith("/") || first === void 0 || segments.length < 2 || !HOLE_SEGMENT.test(first)) {
+    return path;
+  }
+  return `/${segments.slice(1).join("/")}`;
+}
+var PATTERNS = /* @__PURE__ */ new Map();
+var PATTERN_CACHE_LIMIT = 5e4;
 function patternOf(path) {
-  return alternativesOf(path).map(
-    (alternative) => segmentsOf(alternative).flatMap(itemsOf)
+  const known = PATTERNS.get(path);
+  if (known !== void 0) {
+    return known;
+  }
+  const pattern = alternativesOf(path).map(
+    (alternative) => patternSegmentsOf(alternative).flatMap(itemsOf)
   );
+  if (PATTERNS.size >= PATTERN_CACHE_LIMIT) {
+    PATTERNS.clear();
+  }
+  PATTERNS.set(path, pattern);
+  return pattern;
 }
 function literalItemsOf(path) {
   return segmentsOf(path).map((text) => ({ kind: "text", text }));
@@ -576,17 +669,104 @@ function pathSpansShapes(path) {
 function countOf(items, kinds) {
   return items.filter((item) => kinds.includes(item.kind)).length;
 }
-function pathSpecificity(path) {
-  const alternatives = patternOf(path);
-  const ranks = alternatives.map((items) => [
+function readingSpecificity(items) {
+  return [
     countOf(items, ["text"]),
     countOf(items, ["shaped"]),
     -countOf(items, ["optional", "star"])
-  ]);
-  const loosest = ranks.reduce(
-    (low, rank) => compareRanks(rank, low) < 0 ? rank : low
+  ];
+}
+function segmentFit(route, request) {
+  if (!meetOnOneSegment(route, request)) {
+    return "apart";
+  }
+  if (request.kind === "text") {
+    if (route.kind === "text") {
+      return "stated";
+    }
+    return route.kind === "shaped" ? "shaped" : "free";
+  }
+  if (absorbsAnything(route)) {
+    return "free";
+  }
+  if (request.kind !== "shaped") {
+    return "guess";
+  }
+  if (route.kind === "shaped") {
+    return "free";
+  }
+  return route.kind === "text" && request.bare === route.text ? "stated" : "guess";
+}
+function shapedText(item) {
+  return item.kind === "shaped" ? item.textLength : 0;
+}
+function betterFit(a, b) {
+  return a === void 0 || compareRanks(b, a) > 0;
+}
+function bestFit(route, request) {
+  const width = request.length + 1;
+  const best = new Array((route.length + 1) * width);
+  best[0] = [0, 0];
+  const offer = (i, j, fit) => {
+    const at = i * width + j;
+    if (betterFit(best[at], fit)) {
+      best[at] = fit;
+    }
+  };
+  for (let reached = 0; reached <= route.length + request.length; reached += 1) {
+    for (let i = Math.max(0, reached - request.length); i <= Math.min(route.length, reached); i += 1) {
+      const j = reached - i;
+      const fit = best[i * width + j];
+      if (fit === void 0) {
+        continue;
+      }
+      const left = route[i];
+      const right = request[j];
+      if (left !== void 0 && skippable(left)) {
+        offer(i + 1, j, fit);
+      }
+      if (right !== void 0 && skippable(right)) {
+        offer(i, j + 1, fit);
+      }
+      if (left === void 0 || right === void 0) {
+        continue;
+      }
+      if (left.kind === "star" && right.kind === "star") {
+        continue;
+      }
+      const kind = segmentFit(left, right);
+      if (kind === "apart" || kind === "guess") {
+        continue;
+      }
+      offer(
+        left.kind === "star" ? i : i + 1,
+        right.kind === "star" ? j : j + 1,
+        [
+          fit[0] + (kind === "stated" ? 1 : 0),
+          fit[1] + (kind === "shaped" ? shapedText(left) : 0)
+        ]
+      );
+    }
+  }
+  return best[route.length * width + request.length] ?? null;
+}
+function requestRank(route, request) {
+  let found = null;
+  for (const routeItems of patternOf(route)) {
+    for (const requestItems of patternOf(request)) {
+      const fit = bestFit(routeItems, requestItems);
+      const rank = fit === null ? null : [...fit, ...readingSpecificity(routeItems)];
+      if (rank !== null && (found === null || compareRanks(rank, found) > 0)) {
+        found = rank;
+      }
+    }
+  }
+  return found;
+}
+function isCatchAll(route) {
+  return patternOf(route).some(
+    (items) => items.length > 0 && items.every(absorbsAnything) && items.some((item) => item.kind === "star")
   );
-  return [...loosest, 1 - alternatives.length];
 }
 function compareRanks(a, b) {
   const length = Math.max(a.length, b.length);
@@ -600,23 +780,34 @@ 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(),
+  /**
+   * The host a client wrote in an absolute URL, with its port
+   * (`api.example.com:8443`). A piece suss could not read is written
+   * `{name}`. Absent for a relative URL and for a route.
+   */
+  host: import_zod7.z.string().min(1).optional(),
+  /**
+   * True for a route the framework also serves with `.{format}` after
+   * its path, the way Rails serves `/search.json` from `get "search"`.
+   */
+  optionalFormat: import_zod7.z.boolean().optional()
 });
 var OPENING_HOLE = /^\{([^{}]+)\}(.*)$/;
 function baseUrlReference(semantics) {
@@ -624,7 +815,10 @@ function baseUrlReference(semantics) {
   return label === void 0 ? null : referenceFromName(patternHole(label));
 }
 function normalizePath(path) {
-  let normalized = path.replace(/:([a-zA-Z_]\w*)([?+*]?)/g, "{$1$2}");
+  let normalized = withoutParameterConstraints(path).replace(
+    /:([a-zA-Z_]\w*)([?+*]?)/g,
+    "{$1$2}"
+  );
   if (normalized.length > 1 && normalized.endsWith("/")) {
     normalized = normalized.slice(0, -1);
   }
@@ -634,6 +828,46 @@ function normalizePath(path) {
   );
   return normalized;
 }
+function withoutParameterConstraints(path) {
+  let out = "";
+  let i = 0;
+  while (i < path.length) {
+    const name = /^:[a-zA-Z_]\w*\(/.exec(path.slice(i));
+    if (name === null) {
+      out += path[i];
+      i += 1;
+      continue;
+    }
+    const open = i + name[0].length - 1;
+    const close = closingParenthesis(path, open);
+    if (close === -1) {
+      return out + path.slice(i);
+    }
+    out += path.slice(i, open);
+    i = close + 1;
+  }
+  return out;
+}
+function closingParenthesis(text, open) {
+  let depth = 0;
+  for (let i = open; i < text.length; i += 1) {
+    const char = text[i];
+    if (char === "\\") {
+      i += 1;
+      continue;
+    }
+    if (char === "(") {
+      depth += 1;
+    }
+    if (char === ")") {
+      depth -= 1;
+      if (depth === 0) {
+        return i;
+      }
+    }
+  }
+  return -1;
+}
 function pathShape(path) {
   return normalizePath(path).replace(/\{[^{}]*?([?+*]?)\}/g, "{$1}");
 }
@@ -646,8 +880,39 @@ function methodsAgree(a, b) {
 function routePathAdmits(declaredPath, requestPath) {
   return patternAdmits(normalizePath(declaredPath), normalizePath(requestPath));
 }
-function routePathsMeet(a, b) {
-  return pathsMeet(normalizePath(a), normalizePath(b));
+function readHost(semantics) {
+  const host = semantics.host;
+  return host === void 0 || /[{(]/.test(host) ? void 0 : host;
+}
+function hostsAgree(a, b) {
+  return readHost(a) === readHost(b);
+}
+function hostUnread(semantics) {
+  if (semantics.host !== void 0) {
+    return readHost(semantics) === void 0;
+  }
+  return baseUrlReference(semantics) !== null;
+}
+function servedPath(semantics, path) {
+  const normalized = normalizePath(path);
+  return semantics.optionalFormat === true ? `${normalized}(|.{format})` : normalized;
+}
+function withoutHost(semantics) {
+  const { host: _host, ...rest } = semantics;
+  return rest;
+}
+function groundedBaseUrl(semantics, deployment) {
+  const reference = baseUrlReference(semantics);
+  if (reference === null) {
+    return null;
+  }
+  const base = deployment.setTo(reference);
+  if (base === null) {
+    return null;
+  }
+  const rest = OPENING_HOLE.exec(semantics.path ?? "")?.[2] ?? "";
+  const grounded = pathAfterOrigin(`${base}${rest}`);
+  return { ...semantics, path: grounded === "" ? "/" : grounded };
 }
 var restSemantics = defineBoundarySemantics({
   name: "rest",
@@ -673,39 +938,65 @@ 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) {
         return null;
       }
-      return `rest ${pathShape(semantics.path)}`;
+      const shape = pathShape(pathAfterBaseUrl(normalizePath(semantics.path)));
+      const host = readHost(semantics);
+      return host === void 0 ? `rest ${shape}` : `rest //${host}${shape}`;
+    },
+    /**
+     * A spec writes `/teams/{team_id}` where the route that serves it
+     * writes `/teams/:id`. The method stays in, so a `"*"` handler is
+     * never compared with the document for one method.
+     */
+    operationKey(semantics) {
+      if (semantics.method === null || semantics.path === null) {
+        return null;
+      }
+      return `${semantics.method.toUpperCase()} ${pathShape(semantics.path)}`;
     },
     sidesAgree(a, b) {
-      return methodsAgree(a.method, b.method);
+      return methodsAgree(a.method, b.method) && hostsAgree(a, b);
     },
     spansBuckets(semantics) {
-      return semantics.path !== null && pathSpansShapes(normalizePath(semantics.path));
+      return semantics.path !== null && (semantics.optionalFormat === true || pathSpansShapes(normalizePath(semantics.path)));
     },
     bucketsMeet(a, b) {
-      return a.path !== null && b.path !== null && routePathsMeet(a.path, b.path);
+      return a.path !== null && b.path !== null && hostsAgree(a, b) && pathsMeet(servedPath(a, a.path), servedPath(b, b.path));
     },
-    bucketRank(semantics) {
-      return semantics.path === null ? [] : pathSpecificity(normalizePath(semantics.path));
+    /**
+     * A catch-all route never takes a call whose host suss could not
+     * read, since nothing else ties that call to this app.
+     */
+    pairRank(provider, consumer) {
+      if (provider.path === null || consumer.path === null) {
+        return [];
+      }
+      const route = normalizePath(provider.path);
+      if (hostUnread(consumer) && isCatchAll(route)) {
+        return null;
+      }
+      return requestRank(
+        servedPath(provider, provider.path),
+        normalizePath(consumer.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) {
@@ -716,11 +1007,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) {
@@ -733,43 +1024,41 @@ 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);
     },
     /**
      * A call whose base URL the deployment fills in, resolved to the
-     * path it reaches.
+     * path it reaches, and a call to a host that can be the project's
+     * own, with the host left out so it meets the route.
      *
-     * 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 a base URL 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, and
+     * a base the deployment sets counts as the app's own.
      */
-    groundName(semantics, deployment) {
-      const reference = baseUrlReference(semantics);
-      if (reference === null) {
-        return null;
-      }
-      const base = deployment.setTo(reference);
-      if (base === null) {
+    /** A listed host matches with or without the port the call gives. */
+    withoutOwnHost(semantics, ownHosts) {
+      const host = semantics.host?.toLowerCase();
+      if (host === void 0) {
         return null;
       }
-      const rest = OPENING_HOLE.exec(semantics.path ?? "")?.[2] ?? "";
-      const grounded = pathAfterOrigin(`${base}${rest}`);
-      return { ...semantics, path: grounded === "" ? "/" : grounded };
+      return ownHosts.has(host) || ownHosts.has(host.replace(/:\d+$/, "")) ? withoutHost(semantics) : null;
+    },
+    groundName(semantics, deployment) {
+      const based = groundedBaseUrl(semantics, deployment);
+      const grounded = based ?? semantics;
+      const host = readHost(grounded);
+      return host !== void 0 && hostCanBeOwn(host) ? withoutHost(grounded) : based;
     },
     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());
       },
@@ -784,12 +1073,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",
@@ -798,7 +1087,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)
 });
 
 // src/semantics/runtimeConfig.ts
@@ -806,14 +1095,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. */
@@ -822,46 +1111,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);
@@ -871,21 +1167,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.
      */
@@ -914,9 +1210,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) {
@@ -946,9 +1242,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)) {
@@ -969,11 +1265,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);
@@ -988,7 +1283,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,
@@ -997,7 +1292,8 @@ var SemanticsSchema = import_zod11.z.discriminatedUnion("name", [
   storageSemantics.schema,
   messageBusSemantics.schema,
   metricSemantics.schema,
-  unitInvocationSemantics.schema
+  unitInvocationSemantics.schema,
+  ioSemantics.schema
 ]);
 var DEFINITIONS = [
   restSemantics,
@@ -1008,97 +1304,103 @@ var DEFINITIONS = [
   storageSemantics,
   messageBusSemantics,
   metricSemantics,
-  unitInvocationSemantics
+  unitInvocationSemantics,
+  ioSemantics
 ];
 var BY_NAME = new Map(
   DEFINITIONS.map((d) => [d.name, d])
 );
 
 // 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_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.
    */
-  workspace: import_zod12.z.string().optional()
+  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;