@suss/ir-core 0.22.1 → 0.22.3

package/dist/{chunk-PPQWK62O.js → chunk-I4WQM6F5.js}

@@ -470,6 +470,203 @@ function statesAnOrigin(text) {
   return SCHEME_ORIGIN.test(text) || PROTOCOL_RELATIVE_ORIGIN.test(text);
 }
 
+// src/semantics/pathPattern.ts
+var HOLE_RANGE_SUFFIX = {
+  one: "",
+  optional: "?",
+  many: "+",
+  any: "*"
+};
+function rangedHole(name, range) {
+  return patternHole(`${name}${HOLE_RANGE_SUFFIX[range]}`);
+}
+var UNSPELLABLE_OPTION = /[()|?#{}]/;
+function setPiece(options) {
+  if (options.some((option) => UNSPELLABLE_OPTION.test(option))) {
+    return null;
+  }
+  return `(${options.join("|")})`;
+}
+var ONE = { kind: "one" };
+var OPTIONAL = { kind: "optional" };
+var STAR = { kind: "star" };
+var HOLE_SEGMENT = /^\{[^{}]*?([?+*]?)\}$/;
+var SET_PIECE = /\(([^()]*)\)/;
+var ALTERNATIVE_CAP = 64;
+function alternativesOf(path) {
+  let alternatives = [path];
+  for (; ; ) {
+    const next = [];
+    let expanded = false;
+    for (const alternative of alternatives) {
+      const set = SET_PIECE.exec(alternative);
+      if (set === null || set.index === void 0) {
+        next.push(alternative);
+        continue;
+      }
+      expanded = true;
+      const head = alternative.slice(0, set.index);
+      const tail = alternative.slice(set.index + set[0].length);
+      for (const option of (set[1] ?? "").split("|")) {
+        next.push(head + option + tail);
+      }
+    }
+    if (!expanded) {
+      return alternatives;
+    }
+    if (next.length > ALTERNATIVE_CAP) {
+      return [path.replace(new RegExp(SET_PIECE, "g"), "{value}")];
+    }
+    alternatives = next;
+  }
+}
+var HOLE_RANGE_ITEMS = {
+  "": [ONE],
+  "?": [OPTIONAL],
+  "+": [ONE, STAR],
+  "*": [STAR]
+};
+function escapedForRegex(text) {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function shapedItem(segment) {
+  const source = segment.split(/(\{[^}]*\}|\*)/g).map((part) => {
+    if (part === "*") {
+      return ".*";
+    }
+    if (part.startsWith("{")) {
+      return "[^/]+";
+    }
+    return escapedForRegex(part);
+  }).join("");
+  return {
+    kind: "shaped",
+    shape: segment.replace(/\{[^}]*\}/g, "{}"),
+    test: new RegExp(`^${source}$`)
+  };
+}
+function itemsOf(segment) {
+  if (segment === "*") {
+    return [STAR];
+  }
+  const hole = HOLE_SEGMENT.exec(segment);
+  if (hole !== null) {
+    return HOLE_RANGE_ITEMS[hole[1] ?? ""] ?? [ONE];
+  }
+  if (segment.includes("{") || segment.includes("*")) {
+    return [shapedItem(segment)];
+  }
+  return [{ kind: "text", text: segment }];
+}
+function segmentsOf(alternative) {
+  const trimmed = alternative.startsWith("/") ? alternative.slice(1) : alternative;
+  return trimmed === "" ? [] : trimmed.split("/");
+}
+function patternOf(path) {
+  return alternativesOf(path).map(
+    (alternative) => segmentsOf(alternative).flatMap(itemsOf)
+  );
+}
+function literalItemsOf(path) {
+  return segmentsOf(path).map((text) => ({ kind: "text", text }));
+}
+function absorbsAnything(item) {
+  return item.kind === "one" || item.kind === "optional" || item.kind === "star";
+}
+function meetOnOneSegment(a, b) {
+  if (absorbsAnything(a) || absorbsAnything(b)) {
+    return true;
+  }
+  if (a.kind === "text" && b.kind === "text") {
+    return a.text === b.text;
+  }
+  if (a.kind === "text" && b.kind === "shaped") {
+    return b.test.test(a.text);
+  }
+  if (a.kind === "shaped" && b.kind === "text") {
+    return a.test.test(b.text);
+  }
+  return a.kind === "shaped" && b.kind === "shaped" && a.shape === b.shape;
+}
+function skippable(item) {
+  return item.kind === "optional" || item.kind === "star";
+}
+function itemsMeet(a, b) {
+  const width = b.length + 1;
+  const seen = new Uint8Array((a.length + 1) * width);
+  const queue = [0];
+  seen[0] = 1;
+  const visit = (i, j) => {
+    const at = i * width + j;
+    if (seen[at] === 0) {
+      seen[at] = 1;
+      queue.push(at);
+    }
+  };
+  while (queue.length > 0) {
+    const at = queue.pop();
+    const i = Math.floor(at / width);
+    const j = at % width;
+    if (i === a.length && j === b.length) {
+      return true;
+    }
+    const left = a[i];
+    const right = b[j];
+    if (left !== void 0 && skippable(left)) {
+      visit(i + 1, j);
+    }
+    if (right !== void 0 && skippable(right)) {
+      visit(i, j + 1);
+    }
+    if (left !== void 0 && right !== void 0) {
+      if (meetOnOneSegment(left, right)) {
+        visit(
+          left.kind === "star" ? i : i + 1,
+          right.kind === "star" ? j : j + 1
+        );
+      }
+    }
+  }
+  return false;
+}
+function pathsMeet(a, b) {
+  const left = patternOf(a);
+  const right = patternOf(b);
+  return left.some((one) => right.some((other) => itemsMeet(one, other)));
+}
+function patternAdmits(declared, request) {
+  const literal = literalItemsOf(request);
+  return patternOf(declared).some((items) => itemsMeet(items, literal));
+}
+function pathSpansShapes(path) {
+  return /\{[^{}]*[?+*]\}|\(|(?:^|\/)\*(?:\/|$)/.test(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) => [
+    countOf(items, ["text"]),
+    countOf(items, ["shaped"]),
+    -countOf(items, ["optional", "star"])
+  ]);
+  const loosest = ranks.reduce(
+    (low, rank) => compareRanks(rank, low) < 0 ? rank : low
+  );
+  return [...loosest, 1 - alternatives.length];
+}
+function compareRanks(a, b) {
+  const length = Math.max(a.length, b.length);
+  for (let index = 0; index < length; index += 1) {
+    const difference = (a[index] ?? 0) - (b[index] ?? 0);
+    if (difference !== 0) {
+      return difference;
+    }
+  }
+  return 0;
+}
+
 // src/semantics/rest.ts
 var RestSemanticsSchema = z6.object({
   name: z6.literal("rest"),
@@ -495,7 +692,7 @@ function baseUrlReference(semantics) {
   return label === void 0 ? null : referenceFromName(patternHole(label));
 }
 function normalizePath(path) {
-  let normalized = path.replace(/:([a-zA-Z_]\w*)/g, "{$1}");
+  let normalized = path.replace(/:([a-zA-Z_]\w*)([?+*]?)/g, "{$1$2}");
   if (normalized.length > 1 && normalized.endsWith("/")) {
     normalized = normalized.slice(0, -1);
   }
@@ -506,7 +703,7 @@ function normalizePath(path) {
   return normalized;
 }
 function pathShape(path) {
-  return normalizePath(path).replace(/\{[^}]*\}/g, "{}");
+  return normalizePath(path).replace(/\{[^{}]*?([?+*]?)\}/g, "{$1}");
 }
 function methodsAgree(a, b) {
   if (a === null || b === null) {
@@ -514,22 +711,11 @@ function methodsAgree(a, b) {
   }
   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)
-  );
+  return patternAdmits(normalizePath(declaredPath), normalizePath(requestPath));
+}
+function routePathsMeet(a, b) {
+  return pathsMeet(normalizePath(a), normalizePath(b));
 }
 var restSemantics = defineBoundarySemantics({
   name: "rest",
@@ -574,6 +760,15 @@ var restSemantics = defineBoundarySemantics({
     sidesAgree(a, b) {
       return methodsAgree(a.method, b.method);
     },
+    spansBuckets(semantics) {
+      return semantics.path !== null && pathSpansShapes(normalizePath(semantics.path));
+    },
+    bucketsMeet(a, b) {
+      return a.path !== null && b.path !== null && routePathsMeet(a.path, b.path);
+    },
+    bucketRank(semantics) {
+      return semantics.path === null ? [] : pathSpecificity(normalizePath(semantics.path));
+    },
     /**
      * What the identity key says, with a missing half still readable:
      * ANY when no method was stated, and ? when no path was. Null when
@@ -1049,11 +1244,15 @@ export {
   referenceFromName,
   pathAfterOrigin,
   statesAnOrigin,
+  rangedHole,
+  setPiece,
+  compareRanks,
   RestSemanticsSchema,
   normalizePath,
   pathShape,
   methodsAgree,
   routePathAdmits,
+  routePathsMeet,
   DeployableUnitSchema,
   ecsContainerInstanceName,
   RuntimeConfigSemanticsSchema,

package/dist/index.cjs

@@ -51,11 +51,14 @@ __export(index_exports, {
   boundaryKey: () => boundaryKey,
   boundaryLabel: () => boundaryLabel,
   boundaryNameString: () => boundaryNameString,
+  bucketRank: () => bucketRank,
+  bucketsMeet: () => bucketsMeet,
   busIdentityKey: () => busIdentityKey,
   busesAgree: () => busesAgree,
   canPair: () => canPair,
   channelsPair: () => channelsPair,
   codeScopePath: () => codeScopePath,
+  compareRanks: () => compareRanks,
   countsForThreshold: () => countsForThreshold,
   dispatchByType: () => dispatchByType,
   displayLabel: () => displayLabel,
@@ -93,6 +96,7 @@ __export(index_exports, {
   pathAfterOrigin: () => pathAfterOrigin,
   pathShape: () => pathShape,
   patternHole: () => patternHole,
+  rangedHole: () => rangedHole,
   referenceFromName: () => referenceFromName,
   referenceName: () => referenceName,
   referenceOf: () => referenceOf,
@@ -100,11 +104,14 @@ __export(index_exports, {
   resourceNameIn: () => resourceNameIn,
   restBinding: () => restBinding,
   routePathAdmits: () => routePathAdmits,
+  routePathsMeet: () => routePathsMeet,
   ruleBoundaryMatchesKey: () => ruleBoundaryMatchesKey,
   runtimeConfigBinding: () => runtimeConfigBinding,
   semanticsAgree: () => semanticsAgree,
   semconvAttributes: () => semconvAttributes,
   servesRequest: () => servesRequest,
+  setPiece: () => setPiece,
+  spansBuckets: () => spansBuckets,
   spellingTokens: () => spellingTokens,
   statesAnOrigin: () => statesAnOrigin,
   storageBinding: () => storageBinding,
@@ -592,6 +599,203 @@ function statesAnOrigin(text) {
   return SCHEME_ORIGIN.test(text) || PROTOCOL_RELATIVE_ORIGIN.test(text);
 }
 
+// src/semantics/pathPattern.ts
+var HOLE_RANGE_SUFFIX = {
+  one: "",
+  optional: "?",
+  many: "+",
+  any: "*"
+};
+function rangedHole(name, range) {
+  return patternHole(`${name}${HOLE_RANGE_SUFFIX[range]}`);
+}
+var UNSPELLABLE_OPTION = /[()|?#{}]/;
+function setPiece(options) {
+  if (options.some((option) => UNSPELLABLE_OPTION.test(option))) {
+    return null;
+  }
+  return `(${options.join("|")})`;
+}
+var ONE = { kind: "one" };
+var OPTIONAL = { kind: "optional" };
+var STAR = { kind: "star" };
+var HOLE_SEGMENT = /^\{[^{}]*?([?+*]?)\}$/;
+var SET_PIECE = /\(([^()]*)\)/;
+var ALTERNATIVE_CAP = 64;
+function alternativesOf(path) {
+  let alternatives = [path];
+  for (; ; ) {
+    const next = [];
+    let expanded = false;
+    for (const alternative of alternatives) {
+      const set = SET_PIECE.exec(alternative);
+      if (set === null || set.index === void 0) {
+        next.push(alternative);
+        continue;
+      }
+      expanded = true;
+      const head = alternative.slice(0, set.index);
+      const tail = alternative.slice(set.index + set[0].length);
+      for (const option of (set[1] ?? "").split("|")) {
+        next.push(head + option + tail);
+      }
+    }
+    if (!expanded) {
+      return alternatives;
+    }
+    if (next.length > ALTERNATIVE_CAP) {
+      return [path.replace(new RegExp(SET_PIECE, "g"), "{value}")];
+    }
+    alternatives = next;
+  }
+}
+var HOLE_RANGE_ITEMS = {
+  "": [ONE],
+  "?": [OPTIONAL],
+  "+": [ONE, STAR],
+  "*": [STAR]
+};
+function escapedForRegex(text) {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function shapedItem(segment) {
+  const source = segment.split(/(\{[^}]*\}|\*)/g).map((part) => {
+    if (part === "*") {
+      return ".*";
+    }
+    if (part.startsWith("{")) {
+      return "[^/]+";
+    }
+    return escapedForRegex(part);
+  }).join("");
+  return {
+    kind: "shaped",
+    shape: segment.replace(/\{[^}]*\}/g, "{}"),
+    test: new RegExp(`^${source}$`)
+  };
+}
+function itemsOf(segment) {
+  if (segment === "*") {
+    return [STAR];
+  }
+  const hole = HOLE_SEGMENT.exec(segment);
+  if (hole !== null) {
+    return HOLE_RANGE_ITEMS[hole[1] ?? ""] ?? [ONE];
+  }
+  if (segment.includes("{") || segment.includes("*")) {
+    return [shapedItem(segment)];
+  }
+  return [{ kind: "text", text: segment }];
+}
+function segmentsOf(alternative) {
+  const trimmed = alternative.startsWith("/") ? alternative.slice(1) : alternative;
+  return trimmed === "" ? [] : trimmed.split("/");
+}
+function patternOf(path) {
+  return alternativesOf(path).map(
+    (alternative) => segmentsOf(alternative).flatMap(itemsOf)
+  );
+}
+function literalItemsOf(path) {
+  return segmentsOf(path).map((text) => ({ kind: "text", text }));
+}
+function absorbsAnything(item) {
+  return item.kind === "one" || item.kind === "optional" || item.kind === "star";
+}
+function meetOnOneSegment(a, b) {
+  if (absorbsAnything(a) || absorbsAnything(b)) {
+    return true;
+  }
+  if (a.kind === "text" && b.kind === "text") {
+    return a.text === b.text;
+  }
+  if (a.kind === "text" && b.kind === "shaped") {
+    return b.test.test(a.text);
+  }
+  if (a.kind === "shaped" && b.kind === "text") {
+    return a.test.test(b.text);
+  }
+  return a.kind === "shaped" && b.kind === "shaped" && a.shape === b.shape;
+}
+function skippable(item) {
+  return item.kind === "optional" || item.kind === "star";
+}
+function itemsMeet(a, b) {
+  const width = b.length + 1;
+  const seen = new Uint8Array((a.length + 1) * width);
+  const queue = [0];
+  seen[0] = 1;
+  const visit = (i, j) => {
+    const at = i * width + j;
+    if (seen[at] === 0) {
+      seen[at] = 1;
+      queue.push(at);
+    }
+  };
+  while (queue.length > 0) {
+    const at = queue.pop();
+    const i = Math.floor(at / width);
+    const j = at % width;
+    if (i === a.length && j === b.length) {
+      return true;
+    }
+    const left = a[i];
+    const right = b[j];
+    if (left !== void 0 && skippable(left)) {
+      visit(i + 1, j);
+    }
+    if (right !== void 0 && skippable(right)) {
+      visit(i, j + 1);
+    }
+    if (left !== void 0 && right !== void 0) {
+      if (meetOnOneSegment(left, right)) {
+        visit(
+          left.kind === "star" ? i : i + 1,
+          right.kind === "star" ? j : j + 1
+        );
+      }
+    }
+  }
+  return false;
+}
+function pathsMeet(a, b) {
+  const left = patternOf(a);
+  const right = patternOf(b);
+  return left.some((one) => right.some((other) => itemsMeet(one, other)));
+}
+function patternAdmits(declared, request) {
+  const literal = literalItemsOf(request);
+  return patternOf(declared).some((items) => itemsMeet(items, literal));
+}
+function pathSpansShapes(path) {
+  return /\{[^{}]*[?+*]\}|\(|(?:^|\/)\*(?:\/|$)/.test(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) => [
+    countOf(items, ["text"]),
+    countOf(items, ["shaped"]),
+    -countOf(items, ["optional", "star"])
+  ]);
+  const loosest = ranks.reduce(
+    (low, rank) => compareRanks(rank, low) < 0 ? rank : low
+  );
+  return [...loosest, 1 - alternatives.length];
+}
+function compareRanks(a, b) {
+  const length = Math.max(a.length, b.length);
+  for (let index = 0; index < length; index += 1) {
+    const difference = (a[index] ?? 0) - (b[index] ?? 0);
+    if (difference !== 0) {
+      return difference;
+    }
+  }
+  return 0;
+}
+
 // src/semantics/rest.ts
 var RestSemanticsSchema = import_zod6.z.object({
   name: import_zod6.z.literal("rest"),
@@ -617,7 +821,7 @@ function baseUrlReference(semantics) {
   return label === void 0 ? null : referenceFromName(patternHole(label));
 }
 function normalizePath(path) {
-  let normalized = path.replace(/:([a-zA-Z_]\w*)/g, "{$1}");
+  let normalized = path.replace(/:([a-zA-Z_]\w*)([?+*]?)/g, "{$1$2}");
   if (normalized.length > 1 && normalized.endsWith("/")) {
     normalized = normalized.slice(0, -1);
   }
@@ -628,7 +832,7 @@ function normalizePath(path) {
   return normalized;
 }
 function pathShape(path) {
-  return normalizePath(path).replace(/\{[^}]*\}/g, "{}");
+  return normalizePath(path).replace(/\{[^{}]*?([?+*]?)\}/g, "{$1}");
 }
 function methodsAgree(a, b) {
   if (a === null || b === null) {
@@ -636,22 +840,11 @@ function methodsAgree(a, b) {
   }
   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)
-  );
+  return patternAdmits(normalizePath(declaredPath), normalizePath(requestPath));
+}
+function routePathsMeet(a, b) {
+  return pathsMeet(normalizePath(a), normalizePath(b));
 }
 var restSemantics = defineBoundarySemantics({
   name: "rest",
@@ -696,6 +889,15 @@ var restSemantics = defineBoundarySemantics({
     sidesAgree(a, b) {
       return methodsAgree(a.method, b.method);
     },
+    spansBuckets(semantics) {
+      return semantics.path !== null && pathSpansShapes(normalizePath(semantics.path));
+    },
+    bucketsMeet(a, b) {
+      return a.path !== null && b.path !== null && routePathsMeet(a.path, b.path);
+    },
+    bucketRank(semantics) {
+      return semantics.path === null ? [] : pathSpecificity(normalizePath(semantics.path));
+    },
     /**
      * What the identity key says, with a missing half still readable:
      * ANY when no method was stated, and ? when no path was. Null when
@@ -1199,6 +1401,19 @@ function semanticsAgree(a, b) {
   const agree = behaviorOf(a).sidesAgree;
   return agree === void 0 ? true : agree(a, b);
 }
+function spansBuckets(binding) {
+  return behaviorOf(binding.semantics).spansBuckets?.(binding.semantics) ?? false;
+}
+function bucketsMeet(a, b) {
+  if (a.semantics.name !== b.semantics.name) {
+    return false;
+  }
+  const meet = behaviorOf(a.semantics).bucketsMeet;
+  return meet !== void 0 && meet(a.semantics, b.semantics);
+}
+function bucketRank(binding) {
+  return behaviorOf(binding.semantics).bucketRank?.(binding.semantics) ?? [];
+}
 function boundaryLabel(binding) {
   const behavior = behaviorOf(binding.semantics);
   return (behavior.displayLabel ?? behavior.identityKey)(binding.semantics);
@@ -1740,11 +1955,14 @@ function metricBinding(opts) {
   boundaryKey,
   boundaryLabel,
   boundaryNameString,
+  bucketRank,
+  bucketsMeet,
   busIdentityKey,
   busesAgree,
   canPair,
   channelsPair,
   codeScopePath,
+  compareRanks,
   countsForThreshold,
   dispatchByType,
   displayLabel,
@@ -1782,6 +2000,7 @@ function metricBinding(opts) {
   pathAfterOrigin,
   pathShape,
   patternHole,
+  rangedHole,
   referenceFromName,
   referenceName,
   referenceOf,
@@ -1789,11 +2008,14 @@ function metricBinding(opts) {
   resourceNameIn,
   restBinding,
   routePathAdmits,
+  routePathsMeet,
   ruleBoundaryMatchesKey,
   runtimeConfigBinding,
   semanticsAgree,
   semconvAttributes,
   servesRequest,
+  setPiece,
+  spansBuckets,
   spellingTokens,
   statesAnOrigin,
   storageBinding,

package/dist/index.d.cts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
-import { T as TypeShape, M as MessageBusSemantics, D as DeployableUnit, 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-Dn1AzzWd.cjs';
-export { f as DeployableUnitSchema, E as EVERY_FIELD, 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 StorageSemantics, q as StorageSemanticsSchema, r as TypeShapeSchema, s as ecsContainerInstanceName, t as methodsAgree, u as normalizePath, v as pathShape, w as routePathAdmits, x as storageContainerLabel, y as storageLabel, z as typeDefinitionKey, A as withDefinitionsInlined } from './schemas-Dn1AzzWd.cjs';
+import { T as TypeShape, M as MessageBusSemantics, D as DeployableUnit, 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-BDB_vB6m.cjs';
+export { f as DeployableUnitSchema, E as EVERY_FIELD, 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 StorageSemantics, q as StorageSemanticsSchema, r as TypeShapeSchema, s as ecsContainerInstanceName, t as methodsAgree, u as normalizePath, v as pathShape, w as routePathAdmits, x as routePathsMeet, y as storageContainerLabel, z as storageLabel, A as typeDefinitionKey, H as withDefinitionsInlined } from './schemas-BDB_vB6m.cjs';
 
 /**
  * The boundary-name syntax, parsed and printed in one place.
@@ -248,6 +248,24 @@ interface BoundaryBehavior<S extends {
      * does not define it always agrees.
      */
     sidesAgree?(a: S, b: S): boolean;
+    /**
+     * Whether this boundary's bucket can meet buckets with other keys. A
+     * REST path with a hole that spans some number of segments has a key
+     * of its own and serves what several other keys serve, so the pairing
+     * pass compares it against every bucket on the other side with
+     * `bucketsMeet`. A variant that does not define it meets only its own
+     * key.
+     */
+    spansBuckets?(semantics: S): boolean;
+    /** Whether two buckets describe at least one boundary in common. */
+    bucketsMeet?(a: S, b: S): boolean;
+    /**
+     * How narrowly this bucket states what it serves, compared
+     * lexicographically. When a consumer meets more than one bucket, the
+     * one ranking highest is the one it reaches, and an even contest is
+     * reported rather than paired.
+     */
+    bucketRank?(semantics: S): readonly number[];
     /** The line a reader sees for this boundary. Defaults to `identityKey`. */
     displayLabel?(semantics: S): string | null;
     /**
@@ -484,6 +502,12 @@ declare function groundBinding(binding: BoundaryBinding, deployment: Deployment)
 declare function nameReference(binding: BoundaryBinding): Reference | null;
 declare function pairingKey(binding: BoundaryBinding): string | null;
 declare function semanticsAgree(a: Semantics, b: Semantics): boolean;
+/** Whether the binding's bucket can meet buckets with other keys. */
+declare function spansBuckets(binding: BoundaryBinding): boolean;
+/** Whether two bindings' buckets describe a boundary in common. */
+declare function bucketsMeet(a: BoundaryBinding, b: BoundaryBinding): boolean;
+/** How narrowly the binding's bucket states what it serves; see `compareRanks`. */
+declare function bucketRank(binding: BoundaryBinding): readonly number[];
 declare function boundaryLabel(binding: BoundaryBinding): string | null;
 declare function displayLabel(binding: BoundaryBinding): string;
 /**
@@ -671,6 +695,33 @@ declare const EffectRelationSchema: z.ZodEnum<{
 }>;
 type EffectRelation = z.infer<typeof EffectRelationSchema>;
 
+/**
+ * pathPattern.ts: whether two route paths describe a request in common.
+ *
+ * A normalized path is text with holes in it. `{id}` is exactly one
+ * segment, `{tenant?}` is zero or one, `{rest+}` is one or more and
+ * `{rest*}` is zero or more, the modifiers Express puts on `:name`. A
+ * bare `*` segment is zero or more segments, Express 4's reading of a
+ * star. A set piece is written `(v1|v2)` and matches any one of its
+ * options, and an option can contain a slash.
+ *
+ * `pathsMeet` expands the sets into alternatives, splits each one into
+ * segments, and walks the two segment lists with a reachability table
+ * in which a hole absorbs as many segments as its range allows.
+ */
+/** How many segments a hole takes, in the words the value domain uses. */
+type HoleRange = "one" | "optional" | "many" | "any";
+/** How a hole taking `range` segments is spelled in a path. */
+declare function rangedHole(name: string, range: HoleRange): string;
+/**
+ * How a piece that is one of several texts is spelled in a path, or
+ * null when an option would be read as something else, such as a set
+ * boundary or the start of a query.
+ */
+declare function setPiece(options: readonly string[]): string | null;
+/** Negative when `a` ranks below `b`, positive above, zero when equal. */
+declare function compareRanks(a: readonly number[], b: readonly number[]): number;
+
 /**
  * The suppression pipeline, over the smallest finding both checkers share.
  *
@@ -957,4 +1008,4 @@ declare function metricBinding(opts: {
     metricType: string | null;
 }): BoundaryBinding;
 
-export { type BoundaryBehavior, type BoundaryBinding, BoundaryBindingSchema, type BoundaryName, type BoundarySemanticsDefinition, type BusIdentityKey, type Channel, type ConfidenceInfo, ConfidenceInfoSchema, type ConfidenceLevel, ConfidenceLevelSchema, type ConfidenceSource, ConfidenceSourceSchema, type Corroboration, CorroborationSchema, DeployableUnit, type Deployment, type DispatchTable, type EffectRelation, EffectRelationSchema, type FindingSuppression, type FnIdentityKey, type GqlIdentityKey, type MatchResult, MessageBusSemantics, MessageBusTechnology, type MetricIdentityKey, type MetricSemantics, MetricSemanticsSchema, NOTHING_DEPLOYED, type NamePart, type ParsedChannel, type Reference, type Relation, RelationSchema, Semantics, type SemconvAttribute, type SemconvMapping, type SourceLocation, SourceLocationSchema, type SuppressableSeverity, type SuppressibleFinding, type SuppressionFile, SuppressionFileSchema, type SuppressionRule, SuppressionRuleSchema, TypeShape, type UnitIdentityKey, type UnitInvocationSemantics, UnitInvocationSemanticsSchema, applySuppressionsToFindings, bindingIs, bindingTokens, bodyShapesMatch, boundaryKey, boundaryLabel, boundaryNameString, busIdentityKey, busesAgree, canPair, channelsPair, codeScopePath, countsForThreshold, dispatchByType, displayLabel, exchangesHttpResponses, fileInCodeScope, fixedTextLength, fnIdentityKey, formatChannel, functionCallBinding, gqlIdentityKey, graphqlOperationBinding, graphqlResolverBinding, groundBinding, groundedPairingKey, hasNameHole, isGraphqlOperationBinding, messageBusBinding, metricBinding, metricIdentityKey, namePatternFromSub, namePatternKey, nameReference, namesAgree, namesBoundary, namesBoundaryExactly, namesNothing, normalizeRuleBoundary, packageExportBinding, pairingKey, parseBoundaryName, parseChannel, pathAfterOrigin, patternHole, referenceFromName, referenceName, referenceOf, reportsUnpairedItself, resourceNameIn, restBinding, ruleBoundaryMatchesKey, runtimeConfigBinding, semanticsAgree, semconvAttributes, servesRequest, spellingTokens, statesAnOrigin, storageBinding, unitIdentityKey, unitInvocationBinding, validateRule, withRewrittenPaths, withinScope };
+export { type BoundaryBehavior, type BoundaryBinding, BoundaryBindingSchema, type BoundaryName, type BoundarySemanticsDefinition, type BusIdentityKey, type Channel, type ConfidenceInfo, ConfidenceInfoSchema, type ConfidenceLevel, ConfidenceLevelSchema, type ConfidenceSource, ConfidenceSourceSchema, type Corroboration, CorroborationSchema, DeployableUnit, type Deployment, type DispatchTable, type EffectRelation, EffectRelationSchema, type FindingSuppression, type FnIdentityKey, type GqlIdentityKey, type HoleRange, type MatchResult, MessageBusSemantics, MessageBusTechnology, type MetricIdentityKey, type MetricSemantics, MetricSemanticsSchema, NOTHING_DEPLOYED, type NamePart, type ParsedChannel, type Reference, type Relation, RelationSchema, Semantics, type SemconvAttribute, type SemconvMapping, type SourceLocation, SourceLocationSchema, type SuppressableSeverity, type SuppressibleFinding, type SuppressionFile, SuppressionFileSchema, type SuppressionRule, SuppressionRuleSchema, TypeShape, type UnitIdentityKey, type UnitInvocationSemantics, UnitInvocationSemanticsSchema, applySuppressionsToFindings, bindingIs, bindingTokens, bodyShapesMatch, boundaryKey, boundaryLabel, boundaryNameString, bucketRank, bucketsMeet, busIdentityKey, busesAgree, canPair, channelsPair, codeScopePath, compareRanks, countsForThreshold, dispatchByType, displayLabel, exchangesHttpResponses, fileInCodeScope, fixedTextLength, fnIdentityKey, formatChannel, functionCallBinding, gqlIdentityKey, graphqlOperationBinding, graphqlResolverBinding, groundBinding, groundedPairingKey, hasNameHole, isGraphqlOperationBinding, messageBusBinding, metricBinding, metricIdentityKey, namePatternFromSub, namePatternKey, nameReference, namesAgree, namesBoundary, namesBoundaryExactly, namesNothing, normalizeRuleBoundary, packageExportBinding, pairingKey, parseBoundaryName, parseChannel, pathAfterOrigin, patternHole, rangedHole, referenceFromName, referenceName, referenceOf, reportsUnpairedItself, resourceNameIn, restBinding, ruleBoundaryMatchesKey, runtimeConfigBinding, semanticsAgree, semconvAttributes, servesRequest, setPiece, spansBuckets, spellingTokens, statesAnOrigin, storageBinding, unitIdentityKey, unitInvocationBinding, validateRule, withRewrittenPaths, withinScope };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
-import { T as TypeShape, M as MessageBusSemantics, D as DeployableUnit, 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-Dn1AzzWd.js';
-export { f as DeployableUnitSchema, E as EVERY_FIELD, 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 StorageSemantics, q as StorageSemanticsSchema, r as TypeShapeSchema, s as ecsContainerInstanceName, t as methodsAgree, u as normalizePath, v as pathShape, w as routePathAdmits, x as storageContainerLabel, y as storageLabel, z as typeDefinitionKey, A as withDefinitionsInlined } from './schemas-Dn1AzzWd.js';
+import { T as TypeShape, M as MessageBusSemantics, D as DeployableUnit, 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-BDB_vB6m.js';
+export { f as DeployableUnitSchema, E as EVERY_FIELD, 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 StorageSemantics, q as StorageSemanticsSchema, r as TypeShapeSchema, s as ecsContainerInstanceName, t as methodsAgree, u as normalizePath, v as pathShape, w as routePathAdmits, x as routePathsMeet, y as storageContainerLabel, z as storageLabel, A as typeDefinitionKey, H as withDefinitionsInlined } from './schemas-BDB_vB6m.js';
 
 /**
  * The boundary-name syntax, parsed and printed in one place.
@@ -248,6 +248,24 @@ interface BoundaryBehavior<S extends {
      * does not define it always agrees.
      */
     sidesAgree?(a: S, b: S): boolean;
+    /**
+     * Whether this boundary's bucket can meet buckets with other keys. A
+     * REST path with a hole that spans some number of segments has a key
+     * of its own and serves what several other keys serve, so the pairing
+     * pass compares it against every bucket on the other side with
+     * `bucketsMeet`. A variant that does not define it meets only its own
+     * key.
+     */
+    spansBuckets?(semantics: S): boolean;
+    /** Whether two buckets describe at least one boundary in common. */
+    bucketsMeet?(a: S, b: S): boolean;
+    /**
+     * How narrowly this bucket states what it serves, compared
+     * lexicographically. When a consumer meets more than one bucket, the
+     * one ranking highest is the one it reaches, and an even contest is
+     * reported rather than paired.
+     */
+    bucketRank?(semantics: S): readonly number[];
     /** The line a reader sees for this boundary. Defaults to `identityKey`. */
     displayLabel?(semantics: S): string | null;
     /**
@@ -484,6 +502,12 @@ declare function groundBinding(binding: BoundaryBinding, deployment: Deployment)
 declare function nameReference(binding: BoundaryBinding): Reference | null;
 declare function pairingKey(binding: BoundaryBinding): string | null;
 declare function semanticsAgree(a: Semantics, b: Semantics): boolean;
+/** Whether the binding's bucket can meet buckets with other keys. */
+declare function spansBuckets(binding: BoundaryBinding): boolean;
+/** Whether two bindings' buckets describe a boundary in common. */
+declare function bucketsMeet(a: BoundaryBinding, b: BoundaryBinding): boolean;
+/** How narrowly the binding's bucket states what it serves; see `compareRanks`. */
+declare function bucketRank(binding: BoundaryBinding): readonly number[];
 declare function boundaryLabel(binding: BoundaryBinding): string | null;
 declare function displayLabel(binding: BoundaryBinding): string;
 /**
@@ -671,6 +695,33 @@ declare const EffectRelationSchema: z.ZodEnum<{
 }>;
 type EffectRelation = z.infer<typeof EffectRelationSchema>;
 
+/**
+ * pathPattern.ts: whether two route paths describe a request in common.
+ *
+ * A normalized path is text with holes in it. `{id}` is exactly one
+ * segment, `{tenant?}` is zero or one, `{rest+}` is one or more and
+ * `{rest*}` is zero or more, the modifiers Express puts on `:name`. A
+ * bare `*` segment is zero or more segments, Express 4's reading of a
+ * star. A set piece is written `(v1|v2)` and matches any one of its
+ * options, and an option can contain a slash.
+ *
+ * `pathsMeet` expands the sets into alternatives, splits each one into
+ * segments, and walks the two segment lists with a reachability table
+ * in which a hole absorbs as many segments as its range allows.
+ */
+/** How many segments a hole takes, in the words the value domain uses. */
+type HoleRange = "one" | "optional" | "many" | "any";
+/** How a hole taking `range` segments is spelled in a path. */
+declare function rangedHole(name: string, range: HoleRange): string;
+/**
+ * How a piece that is one of several texts is spelled in a path, or
+ * null when an option would be read as something else, such as a set
+ * boundary or the start of a query.
+ */
+declare function setPiece(options: readonly string[]): string | null;
+/** Negative when `a` ranks below `b`, positive above, zero when equal. */
+declare function compareRanks(a: readonly number[], b: readonly number[]): number;
+
 /**
  * The suppression pipeline, over the smallest finding both checkers share.
  *
@@ -957,4 +1008,4 @@ declare function metricBinding(opts: {
     metricType: string | null;
 }): BoundaryBinding;
 
-export { type BoundaryBehavior, type BoundaryBinding, BoundaryBindingSchema, type BoundaryName, type BoundarySemanticsDefinition, type BusIdentityKey, type Channel, type ConfidenceInfo, ConfidenceInfoSchema, type ConfidenceLevel, ConfidenceLevelSchema, type ConfidenceSource, ConfidenceSourceSchema, type Corroboration, CorroborationSchema, DeployableUnit, type Deployment, type DispatchTable, type EffectRelation, EffectRelationSchema, type FindingSuppression, type FnIdentityKey, type GqlIdentityKey, type MatchResult, MessageBusSemantics, MessageBusTechnology, type MetricIdentityKey, type MetricSemantics, MetricSemanticsSchema, NOTHING_DEPLOYED, type NamePart, type ParsedChannel, type Reference, type Relation, RelationSchema, Semantics, type SemconvAttribute, type SemconvMapping, type SourceLocation, SourceLocationSchema, type SuppressableSeverity, type SuppressibleFinding, type SuppressionFile, SuppressionFileSchema, type SuppressionRule, SuppressionRuleSchema, TypeShape, type UnitIdentityKey, type UnitInvocationSemantics, UnitInvocationSemanticsSchema, applySuppressionsToFindings, bindingIs, bindingTokens, bodyShapesMatch, boundaryKey, boundaryLabel, boundaryNameString, busIdentityKey, busesAgree, canPair, channelsPair, codeScopePath, countsForThreshold, dispatchByType, displayLabel, exchangesHttpResponses, fileInCodeScope, fixedTextLength, fnIdentityKey, formatChannel, functionCallBinding, gqlIdentityKey, graphqlOperationBinding, graphqlResolverBinding, groundBinding, groundedPairingKey, hasNameHole, isGraphqlOperationBinding, messageBusBinding, metricBinding, metricIdentityKey, namePatternFromSub, namePatternKey, nameReference, namesAgree, namesBoundary, namesBoundaryExactly, namesNothing, normalizeRuleBoundary, packageExportBinding, pairingKey, parseBoundaryName, parseChannel, pathAfterOrigin, patternHole, referenceFromName, referenceName, referenceOf, reportsUnpairedItself, resourceNameIn, restBinding, ruleBoundaryMatchesKey, runtimeConfigBinding, semanticsAgree, semconvAttributes, servesRequest, spellingTokens, statesAnOrigin, storageBinding, unitIdentityKey, unitInvocationBinding, validateRule, withRewrittenPaths, withinScope };
+export { type BoundaryBehavior, type BoundaryBinding, BoundaryBindingSchema, type BoundaryName, type BoundarySemanticsDefinition, type BusIdentityKey, type Channel, type ConfidenceInfo, ConfidenceInfoSchema, type ConfidenceLevel, ConfidenceLevelSchema, type ConfidenceSource, ConfidenceSourceSchema, type Corroboration, CorroborationSchema, DeployableUnit, type Deployment, type DispatchTable, type EffectRelation, EffectRelationSchema, type FindingSuppression, type FnIdentityKey, type GqlIdentityKey, type HoleRange, type MatchResult, MessageBusSemantics, MessageBusTechnology, type MetricIdentityKey, type MetricSemantics, MetricSemanticsSchema, NOTHING_DEPLOYED, type NamePart, type ParsedChannel, type Reference, type Relation, RelationSchema, Semantics, type SemconvAttribute, type SemconvMapping, type SourceLocation, SourceLocationSchema, type SuppressableSeverity, type SuppressibleFinding, type SuppressionFile, SuppressionFileSchema, type SuppressionRule, SuppressionRuleSchema, TypeShape, type UnitIdentityKey, type UnitInvocationSemantics, UnitInvocationSemanticsSchema, applySuppressionsToFindings, bindingIs, bindingTokens, bodyShapesMatch, boundaryKey, boundaryLabel, boundaryNameString, bucketRank, bucketsMeet, busIdentityKey, busesAgree, canPair, channelsPair, codeScopePath, compareRanks, countsForThreshold, dispatchByType, displayLabel, exchangesHttpResponses, fileInCodeScope, fixedTextLength, fnIdentityKey, formatChannel, functionCallBinding, gqlIdentityKey, graphqlOperationBinding, graphqlResolverBinding, groundBinding, groundedPairingKey, hasNameHole, isGraphqlOperationBinding, messageBusBinding, metricBinding, metricIdentityKey, namePatternFromSub, namePatternKey, nameReference, namesAgree, namesBoundary, namesBoundaryExactly, namesNothing, normalizeRuleBoundary, packageExportBinding, pairingKey, parseBoundaryName, parseChannel, pathAfterOrigin, patternHole, rangedHole, referenceFromName, referenceName, referenceOf, reportsUnpairedItself, resourceNameIn, restBinding, ruleBoundaryMatchesKey, runtimeConfigBinding, semanticsAgree, semconvAttributes, servesRequest, setPiece, spansBuckets, spellingTokens, statesAnOrigin, storageBinding, unitIdentityKey, unitInvocationBinding, validateRule, withRewrittenPaths, withinScope };

package/dist/index.js

@@ -24,6 +24,7 @@ import {
   busIdentityKey,
   busesAgree,
   channelsPair,
+  compareRanks,
   dispatchByType,
   ecsContainerInstanceName,
   fixedTextLength,
@@ -43,18 +44,21 @@ import {
   pathAfterOrigin,
   pathShape,
   patternHole,
+  rangedHole,
   referenceFromName,
   referenceName,
   referenceOf,
   routePathAdmits,
+  routePathsMeet,
   semconvMappingOf,
+  setPiece,
   statesAnOrigin,
   storageContainerLabel,
   storageLabel,
   typeDefinitionKey,
   unitIdentityKey,
   withDefinitionsInlined
-} from "./chunk-PPQWK62O.js";
+} from "./chunk-I4WQM6F5.js";
 
 // src/semconv.ts
 function semconvAttributes(binding) {
@@ -114,6 +118,19 @@ function semanticsAgree(a, b) {
   const agree = behaviorOf(a).sidesAgree;
   return agree === void 0 ? true : agree(a, b);
 }
+function spansBuckets(binding) {
+  return behaviorOf(binding.semantics).spansBuckets?.(binding.semantics) ?? false;
+}
+function bucketsMeet(a, b) {
+  if (a.semantics.name !== b.semantics.name) {
+    return false;
+  }
+  const meet = behaviorOf(a.semantics).bucketsMeet;
+  return meet !== void 0 && meet(a.semantics, b.semantics);
+}
+function bucketRank(binding) {
+  return behaviorOf(binding.semantics).bucketRank?.(binding.semantics) ?? [];
+}
 function boundaryLabel(binding) {
   const behavior = behaviorOf(binding.semantics);
   return (behavior.displayLabel ?? behavior.identityKey)(binding.semantics);
@@ -654,11 +671,14 @@ export {
   boundaryKey,
   boundaryLabel,
   boundaryNameString,
+  bucketRank,
+  bucketsMeet,
   busIdentityKey,
   busesAgree,
   canPair,
   channelsPair,
   codeScopePath,
+  compareRanks,
   countsForThreshold,
   dispatchByType,
   displayLabel,
@@ -696,6 +716,7 @@ export {
   pathAfterOrigin,
   pathShape,
   patternHole,
+  rangedHole,
   referenceFromName,
   referenceName,
   referenceOf,
@@ -703,11 +724,14 @@ export {
   resourceNameIn,
   restBinding,
   routePathAdmits,
+  routePathsMeet,
   ruleBoundaryMatchesKey,
   runtimeConfigBinding,
   semanticsAgree,
   semconvAttributes,
   servesRequest,
+  setPiece,
+  spansBuckets,
   spellingTokens,
   statesAnOrigin,
   storageBinding,

package/dist/{schemas-Dn1AzzWd.d.cts → schemas-BDB_vB6m.d.cts}

@@ -178,7 +178,8 @@ type RestSemantics = z.infer<typeof RestSemanticsSchema>;
 /**
  * Normalize a route path to a canonical form for matching.
  *
- * - Converts Express-style params (`:id`) to brace-style (`{id}`)
+ * - Converts Express-style params (`:id`) to brace-style (`{id}`), and
+ *   keeps a range modifier (`:id?`, `:rest+`, `:rest*`) inside the braces
  * - Strips trailing slashes (except bare `/`)
  * - Lowercases the static segments (params stay case-sensitive)
  */
@@ -189,6 +190,8 @@ declare function normalizePath(path: string): string;
  * requests each one serves, and what deciding whether two sides
  * describe one endpoint rests on. The name a parameter is written
  * under is worth keeping in a report and worth nothing in a comparison.
+ * A parameter's range stays, since `{tenant?}` serves a different set
+ * of requests from `{tenant}`.
  */
 declare function pathShape(path: string): string;
 /**
@@ -201,8 +204,15 @@ declare function pathShape(path: string): string;
  * here, so a wildcard pairs with whatever methods consumers write.
  */
 declare function methodsAgree(a: string | null, b: string | null): boolean;
-/** Whether a declared route path admits a concrete request path. */
+/**
+ * Whether a declared route path admits a concrete request path. Both
+ * sides compare on their normalized forms, and a hole in the request
+ * is text like any other, so a route inside a mount pattern is admitted
+ * by it and a wider route is not.
+ */
 declare function routePathAdmits(declaredPath: string, requestPath: string): boolean;
+/** Whether two declared route paths serve at least one request in common. */
+declare function routePathsMeet(a: string, b: string): boolean;
 
 /**
  * The pairing key is `(deploymentTarget, instanceName)`, which is
@@ -491,4 +501,4 @@ declare const TypeShapeSchema: z.ZodType<TypeShape>;
  */
 declare function withDefinitionsInlined(shape: TypeShape, definitions: Record<string, TypeShape> | undefined, depth?: number, inProgress?: ReadonlySet<string>): TypeShape;
 
-export { withDefinitionsInlined as A, BoundaryBindingSchema as B, ConfidenceInfoSchema as C, type DeployableUnit as D, EVERY_FIELD as E, 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 StorageSemantics as p, StorageSemanticsSchema as q, TypeShapeSchema as r, ecsContainerInstanceName as s, methodsAgree as t, normalizePath as u, pathShape as v, routePathAdmits as w, storageContainerLabel as x, storageLabel as y, typeDefinitionKey as z };
+export { typeDefinitionKey as A, BoundaryBindingSchema as B, ConfidenceInfoSchema as C, type DeployableUnit as D, EVERY_FIELD as E, type FunctionCallSemantics as F, type GraphqlOperationSemantics as G, withDefinitionsInlined as H, 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 StorageSemantics as p, StorageSemanticsSchema as q, TypeShapeSchema as r, ecsContainerInstanceName as s, methodsAgree as t, normalizePath as u, pathShape as v, routePathAdmits as w, routePathsMeet as x, storageContainerLabel as y, storageLabel as z };

package/dist/{schemas-Dn1AzzWd.d.ts → schemas-BDB_vB6m.d.ts}

@@ -178,7 +178,8 @@ type RestSemantics = z.infer<typeof RestSemanticsSchema>;
 /**
  * Normalize a route path to a canonical form for matching.
  *
- * - Converts Express-style params (`:id`) to brace-style (`{id}`)
+ * - Converts Express-style params (`:id`) to brace-style (`{id}`), and
+ *   keeps a range modifier (`:id?`, `:rest+`, `:rest*`) inside the braces
  * - Strips trailing slashes (except bare `/`)
  * - Lowercases the static segments (params stay case-sensitive)
  */
@@ -189,6 +190,8 @@ declare function normalizePath(path: string): string;
  * requests each one serves, and what deciding whether two sides
  * describe one endpoint rests on. The name a parameter is written
  * under is worth keeping in a report and worth nothing in a comparison.
+ * A parameter's range stays, since `{tenant?}` serves a different set
+ * of requests from `{tenant}`.
  */
 declare function pathShape(path: string): string;
 /**
@@ -201,8 +204,15 @@ declare function pathShape(path: string): string;
  * here, so a wildcard pairs with whatever methods consumers write.
  */
 declare function methodsAgree(a: string | null, b: string | null): boolean;
-/** Whether a declared route path admits a concrete request path. */
+/**
+ * Whether a declared route path admits a concrete request path. Both
+ * sides compare on their normalized forms, and a hole in the request
+ * is text like any other, so a route inside a mount pattern is admitted
+ * by it and a wider route is not.
+ */
 declare function routePathAdmits(declaredPath: string, requestPath: string): boolean;
+/** Whether two declared route paths serve at least one request in common. */
+declare function routePathsMeet(a: string, b: string): boolean;
 
 /**
  * The pairing key is `(deploymentTarget, instanceName)`, which is
@@ -491,4 +501,4 @@ declare const TypeShapeSchema: z.ZodType<TypeShape>;
  */
 declare function withDefinitionsInlined(shape: TypeShape, definitions: Record<string, TypeShape> | undefined, depth?: number, inProgress?: ReadonlySet<string>): TypeShape;
 
-export { withDefinitionsInlined as A, BoundaryBindingSchema as B, ConfidenceInfoSchema as C, type DeployableUnit as D, EVERY_FIELD as E, 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 StorageSemantics as p, StorageSemanticsSchema as q, TypeShapeSchema as r, ecsContainerInstanceName as s, methodsAgree as t, normalizePath as u, pathShape as v, routePathAdmits as w, storageContainerLabel as x, storageLabel as y, typeDefinitionKey as z };
+export { typeDefinitionKey as A, BoundaryBindingSchema as B, ConfidenceInfoSchema as C, type DeployableUnit as D, EVERY_FIELD as E, type FunctionCallSemantics as F, type GraphqlOperationSemantics as G, withDefinitionsInlined as H, 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 StorageSemantics as p, StorageSemanticsSchema as q, TypeShapeSchema as r, ecsContainerInstanceName as s, methodsAgree as t, normalizePath as u, pathShape as v, routePathAdmits as w, routePathsMeet as x, storageContainerLabel as y, storageLabel as z };

package/dist/schemas.cjs

@@ -405,6 +405,187 @@ function pathAfterOrigin(text) {
   return cut === -1 ? withoutOrigin : withoutOrigin.slice(0, cut);
 }
 
+// src/semantics/pathPattern.ts
+var ONE = { kind: "one" };
+var OPTIONAL = { kind: "optional" };
+var STAR = { kind: "star" };
+var HOLE_SEGMENT = /^\{[^{}]*?([?+*]?)\}$/;
+var SET_PIECE = /\(([^()]*)\)/;
+var ALTERNATIVE_CAP = 64;
+function alternativesOf(path) {
+  let alternatives = [path];
+  for (; ; ) {
+    const next = [];
+    let expanded = false;
+    for (const alternative of alternatives) {
+      const set = SET_PIECE.exec(alternative);
+      if (set === null || set.index === void 0) {
+        next.push(alternative);
+        continue;
+      }
+      expanded = true;
+      const head = alternative.slice(0, set.index);
+      const tail = alternative.slice(set.index + set[0].length);
+      for (const option of (set[1] ?? "").split("|")) {
+        next.push(head + option + tail);
+      }
+    }
+    if (!expanded) {
+      return alternatives;
+    }
+    if (next.length > ALTERNATIVE_CAP) {
+      return [path.replace(new RegExp(SET_PIECE, "g"), "{value}")];
+    }
+    alternatives = next;
+  }
+}
+var HOLE_RANGE_ITEMS = {
+  "": [ONE],
+  "?": [OPTIONAL],
+  "+": [ONE, STAR],
+  "*": [STAR]
+};
+function escapedForRegex(text) {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function shapedItem(segment) {
+  const source = segment.split(/(\{[^}]*\}|\*)/g).map((part) => {
+    if (part === "*") {
+      return ".*";
+    }
+    if (part.startsWith("{")) {
+      return "[^/]+";
+    }
+    return escapedForRegex(part);
+  }).join("");
+  return {
+    kind: "shaped",
+    shape: segment.replace(/\{[^}]*\}/g, "{}"),
+    test: new RegExp(`^${source}$`)
+  };
+}
+function itemsOf(segment) {
+  if (segment === "*") {
+    return [STAR];
+  }
+  const hole = HOLE_SEGMENT.exec(segment);
+  if (hole !== null) {
+    return HOLE_RANGE_ITEMS[hole[1] ?? ""] ?? [ONE];
+  }
+  if (segment.includes("{") || segment.includes("*")) {
+    return [shapedItem(segment)];
+  }
+  return [{ kind: "text", text: segment }];
+}
+function segmentsOf(alternative) {
+  const trimmed = alternative.startsWith("/") ? alternative.slice(1) : alternative;
+  return trimmed === "" ? [] : trimmed.split("/");
+}
+function patternOf(path) {
+  return alternativesOf(path).map(
+    (alternative) => segmentsOf(alternative).flatMap(itemsOf)
+  );
+}
+function literalItemsOf(path) {
+  return segmentsOf(path).map((text) => ({ kind: "text", text }));
+}
+function absorbsAnything(item) {
+  return item.kind === "one" || item.kind === "optional" || item.kind === "star";
+}
+function meetOnOneSegment(a, b) {
+  if (absorbsAnything(a) || absorbsAnything(b)) {
+    return true;
+  }
+  if (a.kind === "text" && b.kind === "text") {
+    return a.text === b.text;
+  }
+  if (a.kind === "text" && b.kind === "shaped") {
+    return b.test.test(a.text);
+  }
+  if (a.kind === "shaped" && b.kind === "text") {
+    return a.test.test(b.text);
+  }
+  return a.kind === "shaped" && b.kind === "shaped" && a.shape === b.shape;
+}
+function skippable(item) {
+  return item.kind === "optional" || item.kind === "star";
+}
+function itemsMeet(a, b) {
+  const width = b.length + 1;
+  const seen = new Uint8Array((a.length + 1) * width);
+  const queue = [0];
+  seen[0] = 1;
+  const visit = (i, j) => {
+    const at = i * width + j;
+    if (seen[at] === 0) {
+      seen[at] = 1;
+      queue.push(at);
+    }
+  };
+  while (queue.length > 0) {
+    const at = queue.pop();
+    const i = Math.floor(at / width);
+    const j = at % width;
+    if (i === a.length && j === b.length) {
+      return true;
+    }
+    const left = a[i];
+    const right = b[j];
+    if (left !== void 0 && skippable(left)) {
+      visit(i + 1, j);
+    }
+    if (right !== void 0 && skippable(right)) {
+      visit(i, j + 1);
+    }
+    if (left !== void 0 && right !== void 0) {
+      if (meetOnOneSegment(left, right)) {
+        visit(
+          left.kind === "star" ? i : i + 1,
+          right.kind === "star" ? j : j + 1
+        );
+      }
+    }
+  }
+  return false;
+}
+function pathsMeet(a, b) {
+  const left = patternOf(a);
+  const right = patternOf(b);
+  return left.some((one) => right.some((other) => itemsMeet(one, other)));
+}
+function patternAdmits(declared, request) {
+  const literal = literalItemsOf(request);
+  return patternOf(declared).some((items) => itemsMeet(items, literal));
+}
+function pathSpansShapes(path) {
+  return /\{[^{}]*[?+*]\}|\(|(?:^|\/)\*(?:\/|$)/.test(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) => [
+    countOf(items, ["text"]),
+    countOf(items, ["shaped"]),
+    -countOf(items, ["optional", "star"])
+  ]);
+  const loosest = ranks.reduce(
+    (low, rank) => compareRanks(rank, low) < 0 ? rank : low
+  );
+  return [...loosest, 1 - alternatives.length];
+}
+function compareRanks(a, b) {
+  const length = Math.max(a.length, b.length);
+  for (let index = 0; index < length; index += 1) {
+    const difference = (a[index] ?? 0) - (b[index] ?? 0);
+    if (difference !== 0) {
+      return difference;
+    }
+  }
+  return 0;
+}
+
 // src/semantics/rest.ts
 var RestSemanticsSchema = import_zod6.z.object({
   name: import_zod6.z.literal("rest"),
@@ -430,7 +611,7 @@ function baseUrlReference(semantics) {
   return label === void 0 ? null : referenceFromName(patternHole(label));
 }
 function normalizePath(path) {
-  let normalized = path.replace(/:([a-zA-Z_]\w*)/g, "{$1}");
+  let normalized = path.replace(/:([a-zA-Z_]\w*)([?+*]?)/g, "{$1$2}");
   if (normalized.length > 1 && normalized.endsWith("/")) {
     normalized = normalized.slice(0, -1);
   }
@@ -441,7 +622,7 @@ function normalizePath(path) {
   return normalized;
 }
 function pathShape(path) {
-  return normalizePath(path).replace(/\{[^}]*\}/g, "{}");
+  return normalizePath(path).replace(/\{[^{}]*?([?+*]?)\}/g, "{$1}");
 }
 function methodsAgree(a, b) {
   if (a === null || b === null) {
@@ -449,22 +630,11 @@ function methodsAgree(a, b) {
   }
   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)
-  );
+  return patternAdmits(normalizePath(declaredPath), normalizePath(requestPath));
+}
+function routePathsMeet(a, b) {
+  return pathsMeet(normalizePath(a), normalizePath(b));
 }
 var restSemantics = defineBoundarySemantics({
   name: "rest",
@@ -509,6 +679,15 @@ var restSemantics = defineBoundarySemantics({
     sidesAgree(a, b) {
       return methodsAgree(a.method, b.method);
     },
+    spansBuckets(semantics) {
+      return semantics.path !== null && pathSpansShapes(normalizePath(semantics.path));
+    },
+    bucketsMeet(a, b) {
+      return a.path !== null && b.path !== null && routePathsMeet(a.path, b.path);
+    },
+    bucketRank(semantics) {
+      return semantics.path === null ? [] : pathSpecificity(normalizePath(semantics.path));
+    },
     /**
      * What the identity key says, with a missing half still readable:
      * ANY when no method was stated, and ? when no path was. Null when

package/dist/schemas.d.cts

@@ -1,2 +1,2 @@
 import 'zod';
-export { B as BoundaryBindingSchema, C as ConfidenceInfoSchema, a as ConfidenceLevelSchema, b as ConfidenceSourceSchema, c as CorroborationSchema, f as DeployableUnitSchema, g as FunctionCallSemanticsSchema, h as GraphqlOperationSemanticsSchema, j as GraphqlResolverSemanticsSchema, k as MessageBusSemanticsSchema, l as RestSemanticsSchema, n as RuntimeConfigSemanticsSchema, o as SemanticsSchema, d as SourceLocationSchema, q as StorageSemanticsSchema, T as TypeShape, r as TypeShapeSchema, z as typeDefinitionKey, A as withDefinitionsInlined } from './schemas-Dn1AzzWd.cjs';
+export { B as BoundaryBindingSchema, C as ConfidenceInfoSchema, a as ConfidenceLevelSchema, b as ConfidenceSourceSchema, c as CorroborationSchema, f as DeployableUnitSchema, g as FunctionCallSemanticsSchema, h as GraphqlOperationSemanticsSchema, j as GraphqlResolverSemanticsSchema, k as MessageBusSemanticsSchema, l as RestSemanticsSchema, n as RuntimeConfigSemanticsSchema, o as SemanticsSchema, d as SourceLocationSchema, q as StorageSemanticsSchema, T as TypeShape, r as TypeShapeSchema, A as typeDefinitionKey, H as withDefinitionsInlined } from './schemas-BDB_vB6m.cjs';

package/dist/schemas.d.ts

@@ -1,2 +1,2 @@
 import 'zod';
-export { B as BoundaryBindingSchema, C as ConfidenceInfoSchema, a as ConfidenceLevelSchema, b as ConfidenceSourceSchema, c as CorroborationSchema, f as DeployableUnitSchema, g as FunctionCallSemanticsSchema, h as GraphqlOperationSemanticsSchema, j as GraphqlResolverSemanticsSchema, k as MessageBusSemanticsSchema, l as RestSemanticsSchema, n as RuntimeConfigSemanticsSchema, o as SemanticsSchema, d as SourceLocationSchema, q as StorageSemanticsSchema, T as TypeShape, r as TypeShapeSchema, z as typeDefinitionKey, A as withDefinitionsInlined } from './schemas-Dn1AzzWd.js';
+export { B as BoundaryBindingSchema, C as ConfidenceInfoSchema, a as ConfidenceLevelSchema, b as ConfidenceSourceSchema, c as CorroborationSchema, f as DeployableUnitSchema, g as FunctionCallSemanticsSchema, h as GraphqlOperationSemanticsSchema, j as GraphqlResolverSemanticsSchema, k as MessageBusSemanticsSchema, l as RestSemanticsSchema, n as RuntimeConfigSemanticsSchema, o as SemanticsSchema, d as SourceLocationSchema, q as StorageSemanticsSchema, T as TypeShape, r as TypeShapeSchema, A as typeDefinitionKey, H as withDefinitionsInlined } from './schemas-BDB_vB6m.js';

package/dist/schemas.js

@@ -17,7 +17,7 @@ import {
   TypeShapeSchema,
   typeDefinitionKey,
   withDefinitionsInlined
-} from "./chunk-PPQWK62O.js";
+} from "./chunk-I4WQM6F5.js";
 export {
   BoundaryBindingSchema,
   ConfidenceInfoSchema,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suss/ir-core",
-  "version": "0.22.1",
+  "version": "0.22.3",
   "type": "module",
   "description": "Shared IR primitives for suss — type shapes, boundary bindings, source locations, and confidence. Imported by both @suss/behavioral-ir and @suss/intent-ir so neither depends on the other.",
   "keywords": [