@suss/ir-core 0.9.0 → 0.10.0

package/README.md

@@ -31,17 +31,39 @@ The boundary key uses only the subject, so both forms end up in the same bucket
 
 Schemas are the single source of truth (`@suss/ir-core/schemas`); the types are derived from them. The recursive `TypeShape` is a hand-written named export so consuming packages reference it by name across the package boundary rather than inlining the recursion.
 
-## Names with a hole in them
+## Boundary names
 
-A deployed resource is often called something built at deploy time. A template writes `!Sub "${StageName}-orders-v1"` and the code writes `` `${stage}-orders-v1` ``, so neither side states a string, both agree about the fixed text, and each spells the parameter its own way. A name is written here as fixed text with `{}` holes, and `namesAgree` says whether two of them are the same name.
+A container or an access path in a summary is a string that means one of three things, and the braces alone say which:
 
-A hole stops at the separator between it and what comes next. No separator works for every project, so the rule does not name one, it takes the separator from the pattern: when the fixed text after a hole starts with a character that is not a letter or a digit, that character divides the deploy-time value from the rest of the name, and the value may not contain it. So `{env}-publications-v1` covers `prod-publications-v1`, and it does not cover `prod-creator-publications-v1`, which the hole could only reach by swallowing a `-`.
+- A **literal** (`orders-v1`) is the name itself.
+- A **pattern** (`{stage}-orders-v1`) is fixed text with `{}` holes for the parts a deployment fills in. A template writes `!Sub "${StageName}-orders-v1"` and the code writes `` `${stage}-orders-v1` ``: neither states a string, both agree about the fixed text, and each spells the parameter its own way.
+- A **reference** (`{location.bucket}`, `{ORDER_TABLE}`) is one hole and no fixed text, saying where to go and ask rather than what the name is.
 
-A greedy hole was the earlier rule, and a module declaring both of those tables had one storage access pair with each of them. The table the code never touches keys on something else, so the run reported a selector mismatch on a boundary that code never reaches.
+`boundaryName.ts` owns the syntax in both directions. `parseBoundaryName` turns a string into the discriminated `BoundaryName` value, `boundaryNameString` turns one back into exactly the string it came from, and everything else, `namesAgree`, `namesNothing`, `fixedTextLength`, `referenceName`, `referenceFromName`, is a view over that pair. Nothing outside the module reads or writes the braces itself: a second parser can disagree about which of the three a string is, and a second printer can spell a value the parser cannot read back. Both have happened. The two halves of caller grounding once spelled a reference differently and never met (#456), which is why writing one and reading one are the same module rather than a format each side implements for itself. `check:name-syntax` in CI keeps it that way.
 
-A hole at the end of a name, and a hole whose next character is a letter or a digit, has no separator to stop at, and it still covers anything. That costs a pair when the value has the separator inside it: `{region}-orders` does not cover `us-east-1-orders`, though `orders-{region}` still covers `orders-us-east-1`. Missing a pair is the better failure of the two, since a wrong match reports findings about a store the code never touches.
+The wire format is the string. Summaries on disk carry `orders-v1`, `{stage}-orders-v1`, `{location.table}` unchanged, so nothing about this layout is a schema change, and an old summary reads the same as a new one.
 
-One name can still be covered by two patterns. A hole at the end covers anything, so `orders-{suffix}` and `orders-blue-{suffix}` both cover `orders-blue-v1`. Choosing between them belongs to whichever pass picks a provider for an access, and `fixedTextLength` is what such a pass ranks by: the pattern that states more fixed text is the more specific one, and two patterns that state the same amount settle nothing between them.
+### How two names pair
+
+`namesAgree` says whether two names are the same name. Two patterns agree when their fixed parts line up, since a hole on one side meets a hole on the other. A pattern and a literal agree when the fixed text is where the pattern says it is, which is what happens when one side hardcoded what the other parameterized. A reference agrees with nothing until something settles it, since one bare hole would otherwise agree with every name there is.
+
+A hole covers anything, because a name has no separator every project agrees on: a region is written `us-east-1`, and a hole that stopped at the first hyphen would miss it. The cost is that one name can be covered by two patterns, `orders-{suffix}` and `orders-blue-{suffix}` both cover `orders-blue-v1`, so choosing between them belongs to whichever pass picks a provider for an access. `fixedTextLength` is what such a pass ranks by: the pattern that states more fixed text is the more specific one, and two patterns that state the same amount settle nothing between them.
+
+### A name that says where to go and ask
+
+Some code cannot say what it reaches. A storage layer takes the bucket as an argument, and a service reads its table name out of the deployment. Neither states a name, and a name is what the rest of suss pairs on, so both write a reference instead.
+
+```ts
+referenceName({ root: "location", fields: ["bucket"] }); // "{location.bucket}"
+referenceName({ root: "ORDER_TABLE", fields: [] }); // "{ORDER_TABLE}"
+referenceFromName("{location.bucket}"); // { root: "location", fields: ["bucket"] }
+```
+
+The root is the value the code starts from, and the fields are what it reads inside that value. A language adapter writes one while reading source, and the checker settles it much later by joining over a whole run: `{location.bucket}` against what each caller passed for `location`, `{ORDER_TABLE}` against what the deployment sets. Whether the root is a parameter of the unit or a variable the deployment sets is not in the string, on purpose: it depends on the unit's inputs and their roles, which the grounding pass already has in hand, and a bare `{X}` is deliberately tried both ways there. A root kind written into the name would either be ignored or change which of those runs.
+
+### Two look-alike conventions that stay apart
+
+A REST route path also spells its parameters with braces (`/users/{id}`), but a route hole stops at the `/` between segments, so route paths keep their own comparison beside the REST semantics. A message-bus channel never uses braces at all; its `bus#subject` form has its own module, described above.
 
 ## Words OpenTelemetry already has
 

package/dist/{chunk-XUXN6DIX.js → chunk-HBAMPBAO.js}

@@ -503,7 +503,9 @@ var StorageSemanticsSchema = z9.object({
    * 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.
+   * 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.
    */
   container: z9.string().nullable(),
   /**

package/dist/index.cjs

@@ -43,6 +43,7 @@ __export(index_exports, {
   bodyShapesMatch: () => bodyShapesMatch,
   boundaryKey: () => boundaryKey,
   boundaryLabel: () => boundaryLabel,
+  boundaryNameString: () => boundaryNameString,
   busIdentityKey: () => busIdentityKey,
   busesAgree: () => busesAgree,
   canPair: () => canPair,
@@ -75,7 +76,12 @@ __export(index_exports, {
   normalizeRuleBoundary: () => normalizeRuleBoundary,
   packageExportBinding: () => packageExportBinding,
   pairingKey: () => pairingKey,
+  parseBoundaryName: () => parseBoundaryName,
   parseChannel: () => parseChannel,
+  patternHole: () => patternHole,
+  referenceFromName: () => referenceFromName,
+  referenceName: () => referenceName,
+  referenceOf: () => referenceOf,
   reportsUnpairedItself: () => reportsUnpairedItself,
   restBinding: () => restBinding,
   routePathAdmits: () => routePathAdmits,
@@ -596,7 +602,9 @@ var StorageSemanticsSchema = import_zod9.z.object({
    * 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.
+   * 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.
    */
   container: import_zod9.z.string().nullable(),
   /**
@@ -858,29 +866,47 @@ function servesRequest(binding, method, path) {
   return serves(binding.semantics, method, path);
 }
 
-// src/codeScope.ts
-function codeScopePath(raw) {
-  return raw.trim().replace(/^\.\//, "").replace(/\/+$/, "");
-}
-function fileInCodeScope(file, scope) {
-  const prefix = codeScopePath(scope);
-  if (prefix === "" || prefix === ".") {
-    return true;
-  }
-  const path = codeScopePath(file);
-  return path === prefix || path.startsWith(`${prefix}/`);
-}
-
 // src/dispatch.ts
 function dispatchByType(table, value) {
   const handler = table[value.type];
   return handler(value);
 }
 
-// src/namePattern.ts
-var HOLE = /\{[^}]*\}/g;
+// src/boundaryName.ts
+var HOLE_SPLIT = /(\{[^}]*\})/;
 var SUB_TOKEN = /\$\{([^}]*)\}/g;
 var SUB_ESCAPE = /\$\{!/;
+function isHole(piece) {
+  return piece.startsWith("{") && piece.endsWith("}");
+}
+function parseBoundaryName(name) {
+  const parts = name.split(HOLE_SPLIT).filter((piece) => piece !== "").map(
+    (piece) => isHole(piece) ? { type: "hole", label: piece.slice(1, -1) } : { type: "text", text: piece }
+  );
+  const only = parts.length === 1 ? parts[0] : void 0;
+  if (only !== void 0 && only.type === "hole") {
+    return { type: "reference", path: only.label.split(".") };
+  }
+  if (parts.some((part) => part.type === "hole")) {
+    return { type: "pattern", parts };
+  }
+  return { type: "literal", value: name };
+}
+var partString = {
+  text: (part) => part.text,
+  hole: (part) => patternHole(part.label)
+};
+var nameString = {
+  literal: (name) => name.value,
+  pattern: (name) => name.parts.map((part) => dispatchByType(partString, part)).join(""),
+  reference: (name) => patternHole(name.path.join("."))
+};
+function boundaryNameString(name) {
+  return dispatchByType(nameString, name);
+}
+function patternHole(label) {
+  return `{${label}}`;
+}
 function namePatternFromSub(value) {
   if (Array.isArray(value)) {
     return typeof value[0] === "string" ? namePatternFromSub(value[0]) : null;
@@ -891,56 +917,101 @@ function namePatternFromSub(value) {
   if (SUB_ESCAPE.test(value)) {
     return null;
   }
-  return value.replace(SUB_TOKEN, (_whole, inner) => `{${inner}}`);
+  return value.replace(
+    SUB_TOKEN,
+    (_whole, inner) => patternHole(inner)
+  );
 }
 function namesNothing(name) {
-  return /^\{[^}]*\}$/.test(name);
+  return parseBoundaryName(name).type === "reference";
 }
 function hasNameHole(name) {
-  HOLE.lastIndex = 0;
-  return HOLE.test(name);
+  return parseBoundaryName(name).type !== "literal";
 }
 function namePatternKey(name) {
-  return name.replace(HOLE, "{}");
+  return dispatchByType(
+    {
+      literal: (parsed) => parsed.value,
+      pattern: (parsed) => boundaryNameString({
+        type: "pattern",
+        parts: parsed.parts.map(
+          (part) => part.type === "hole" ? { type: "hole", label: "" } : part
+        )
+      }),
+      reference: () => patternHole("")
+    },
+    parseBoundaryName(name)
+  );
 }
 function fixedTextLength(name) {
-  return name.replace(HOLE, "").length;
-}
-function isHole(part) {
-  return part.startsWith("{") && part.endsWith("}");
+  return dispatchByType(
+    {
+      literal: (parsed) => parsed.value.length,
+      pattern: (parsed) => parsed.parts.reduce(
+        (total, part) => total + (part.type === "text" ? part.text.length : 0),
+        0
+      ),
+      reference: () => 0
+    },
+    parseBoundaryName(name)
+  );
 }
 function quote(text) {
   return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
-function holeSource(_following) {
-  return ".+";
-}
 function admits(pattern, name) {
-  const parts = pattern.split(/(\{[^}]*\})/);
-  const source = parts.map(
-    (part, index) => isHole(part) ? holeSource(parts[index + 1] ?? "") : quote(part)
-  ).join("");
+  const source = pattern.parts.map((part) => part.type === "hole" ? ".+" : quote(part.text)).join("");
   return new RegExp(`^${source}$`).test(name);
 }
 function namesAgree(a, b) {
-  if (namesNothing(a) || namesNothing(b)) {
+  const left = parseBoundaryName(a);
+  const right = parseBoundaryName(b);
+  if (left.type === "reference" || right.type === "reference") {
     return false;
   }
-  if (a === b) {
-    return true;
-  }
-  const aHasHole = hasNameHole(a);
-  const bHasHole = hasNameHole(b);
-  if (aHasHole && bHasHole) {
+  if (left.type === "pattern" && right.type === "pattern") {
     return namePatternKey(a) === namePatternKey(b);
   }
-  if (aHasHole) {
-    return admits(a, b);
+  if (left.type === "pattern") {
+    return admits(left, b);
   }
-  if (bHasHole) {
-    return admits(b, a);
+  if (right.type === "pattern") {
+    return admits(right, a);
   }
-  return false;
+  return a === b;
+}
+function referenceName(reference) {
+  const path = [reference.root, ...reference.fields];
+  if (path.some((part) => part === "")) {
+    return null;
+  }
+  return boundaryNameString({ type: "reference", path });
+}
+function referenceOf(name) {
+  if (name.type !== "reference") {
+    return null;
+  }
+  const root = name.path[0];
+  if (root === void 0 || name.path.some((part) => part === "")) {
+    return null;
+  }
+  return { root, fields: name.path.slice(1) };
+}
+function referenceFromName(name) {
+  return referenceOf(parseBoundaryName(name));
+}
+
+// src/codeScope.ts
+function codeScopePath(raw) {
+  return raw.trim().replace(/^\.\//, "").replace(/\/+$/, "");
+}
+function fileInCodeScope(file, scope) {
+  const prefix = codeScopePath(scope);
+  if (prefix === "" || prefix === ".") {
+    return true;
+  }
+  const path = codeScopePath(file);
+  return path === prefix || path.startsWith(`${prefix}/`);
 }
 
 // src/suppressions.ts
@@ -1343,6 +1414,7 @@ function metricBinding(opts) {
   bodyShapesMatch,
   boundaryKey,
   boundaryLabel,
+  boundaryNameString,
   busIdentityKey,
   busesAgree,
   canPair,
@@ -1375,7 +1447,12 @@ function metricBinding(opts) {
   normalizeRuleBoundary,
   packageExportBinding,
   pairingKey,
+  parseBoundaryName,
   parseChannel,
+  patternHole,
+  referenceFromName,
+  referenceName,
+  referenceOf,
   reportsUnpairedItself,
   restBinding,
   routePathAdmits,

package/dist/index.d.cts

@@ -243,6 +243,115 @@ declare function reportsUnpairedItself(binding: BoundaryBinding): boolean;
  */
 declare function servesRequest(binding: BoundaryBinding, method: string, path: string): MatchResult | null;
 
+/**
+ * The boundary-name syntax, parsed and printed in one place.
+ *
+ * A name in a summary means one of three things, told apart by the
+ * braces alone: a literal (`orders-v1`), a pattern with deploy-time
+ * holes (`{stage}-orders-v1`), or a reference saying where to go and
+ * ask (`{location.bucket}`, `{ORDER_TABLE}`). A second parser can
+ * disagree about which is which, and a second printer can spell a
+ * value this one cannot read back, so everything that touches the
+ * braces calls this module: `parseBoundaryName` and
+ * `boundaryNameString` are the two directions, and the helpers below
+ * are views over them. The package README tells the longer story,
+ * including why REST route paths and message-bus channels stay apart.
+ */
+/** One piece of a pattern: text the writer stated, or a hole. */
+type NamePart = {
+    type: "text";
+    text: string;
+} | {
+    type: "hole";
+    label: string;
+};
+/**
+ * What a name string means. A `reference` keeps its raw dot-separated
+ * path, and `referenceOf` is the view that checks the parts are all
+ * present, so a malformed spelling still classifies as a reference and
+ * still pairs with nothing.
+ */
+type BoundaryName = {
+    type: "literal";
+    value: string;
+} | {
+    type: "pattern";
+    parts: NamePart[];
+} | {
+    type: "reference";
+    path: string[];
+};
+/** What a name string means. The exact inverse of `boundaryNameString`. */
+declare function parseBoundaryName(name: string): BoundaryName;
+/** The one serializer. Everything a summary spells goes through here. */
+declare function boundaryNameString(name: BoundaryName): string;
+/**
+ * How a hole is spelled. A reader that assembles a pattern a part at a
+ * time, the way the adapter's name reader does, mints each hole here
+ * so the spelling cannot drift from the parse above.
+ */
+declare function patternHole(label: string): string;
+/**
+ * The name a CloudFormation `Fn::Sub` value states. The array form
+ * takes its template from the first element, and the variable map only
+ * says where a substitution comes from, which does not change the name.
+ */
+declare function namePatternFromSub(value: unknown): string | null;
+/**
+ * Whether a name says only that somebody else knows it. A wrapper that
+ * takes its bucket as an argument states `{location.bucket}` and
+ * nothing more, which says which parameter to ask rather than which
+ * bucket. A name like that agrees with nothing until something grounds
+ * it, since otherwise it would agree with every name there is.
+ */
+declare function namesNothing(name: string): boolean;
+/** Whether a name has anything a source left for deploy time to fill. */
+declare function hasNameHole(name: string): boolean;
+/**
+ * The form two patterns are compared in: every hole reduced to the same
+ * token, since the two sides pick their own name for the parameter.
+ */
+declare function namePatternKey(name: string): string;
+/** How much of a name the writer stated rather than left for deploy time. */
+declare function fixedTextLength(name: string): number;
+/**
+ * Whether two names are the same name. Two patterns agree when their
+ * fixed parts line up, since a hole on one side meets a hole on the
+ * other. A pattern and a concrete name agree when the fixed parts are
+ * where the pattern says they are, which is what happens when one side
+ * hardcoded what the other parameterized. A reference agrees with
+ * nothing on either side.
+ */
+declare function namesAgree(a: string, b: string): boolean;
+/** Where a reference says to go and ask. */
+interface Reference {
+    /**
+     * The value the code starts from: a parameter of the unit the
+     * reference was written in, or a variable the deployment sets. Which
+     * of those it is depends on the unit's inputs, so the reader that
+     * grounds a reference decides, not the string.
+     */
+    root: string;
+    /** The fields to read inside it, outermost first. */
+    fields: string[];
+}
+/**
+ * How a reference is written. Null when a part of it is empty, since a
+ * reference has to say what to ask about.
+ */
+declare function referenceName(reference: Reference): string | null;
+/**
+ * The place a parsed reference says to ask, or null for a name that is
+ * not a reference, or for a reference with a part missing, which says
+ * nothing anybody could answer.
+ */
+declare function referenceOf(name: BoundaryName): Reference | null;
+/**
+ * The reference a name states, or null when the name states a name
+ * rather than where to go and ask.
+ */
+declare function referenceFromName(name: string): Reference | null;
+
 /**
  * Deciding when two message-bus channel strings mean the same thing.
  *
@@ -325,53 +434,6 @@ declare function dispatchByType<T extends {
     type: string;
 }, R>(table: DispatchTable<T, R>, value: T): R;
 
-/**
- * A name two sides state with a hole in it.
- *
- * A deployed resource is often called something built at deploy time:
- * a template writes `!Sub "${StageName}-orders-v1"` and the code writes
- * `` `${stage}-orders-v1` ``. Neither side states a string, both agree
- * about the fixed text, and each spells the parameter its own way. So a
- * name is written here as fixed text with `{}` holes, and two names
- * agree when their fixed parts line up.
- *
- * A hole covers a whole parameter rather than one piece of a name,
- * because a name has no separator every project agrees on. Two
- * patterns that both cover one name are told apart by how much fixed
- * text each states, rather than by narrowing what a hole can cover.
- */
-/**
- * The name a CloudFormation `Fn::Sub` value states. The array form
- * takes its template from the first element, and the variable map only
- * says where a substitution comes from, which does not change the name.
- */
-declare function namePatternFromSub(value: unknown): string | null;
-/**
- * Whether a name says only that somebody else knows it. A wrapper that
- * takes its bucket as an argument states `{location.bucket}` and
- * nothing more, which says which parameter to ask rather than which
- * bucket. A name like that agrees with nothing until something grounds
- * it, since otherwise it would agree with every name there is.
- */
-declare function namesNothing(name: string): boolean;
-/** Whether a name has anything a source left for deploy time to fill. */
-declare function hasNameHole(name: string): boolean;
-/**
- * The form two patterns are compared in: every hole reduced to the same
- * token, since the two sides pick their own name for the parameter.
- */
-declare function namePatternKey(name: string): string;
-/** How much of a name the writer stated rather than left for deploy time. */
-declare function fixedTextLength(name: string): number;
-/**
- * Whether two names are the same name. Two patterns agree when their
- * fixed parts line up, since a hole on one side meets a hole on the
- * other. A pattern and a concrete name agree when the fixed parts are
- * where the pattern says they are, which is what happens when one side
- * hardcoded what the other parameterized.
- */
-declare function namesAgree(a: string, b: string): boolean;
-
 /**
  * The suppression pipeline, over the smallest finding both checkers share.
  *
@@ -622,4 +684,4 @@ declare function metricBinding(opts: {
     metricType: string | null;
 }): BoundaryBinding;
 
-export { type BoundaryBehavior, type BoundaryBinding, BoundaryBindingSchema, type BoundarySemanticsDefinition, type BusIdentityKey, type Channel, type ConfidenceInfo, ConfidenceInfoSchema, type ConfidenceLevel, ConfidenceLevelSchema, type ConfidenceSource, ConfidenceSourceSchema, type Corroboration, CorroborationSchema, DeployableUnit, type DispatchTable, type FindingSuppression, type FnIdentityKey, type GqlIdentityKey, type MatchResult, MessageBusSemantics, MessageBusTechnology, type MetricIdentityKey, type MetricSemantics, MetricSemanticsSchema, type ParsedChannel, Semantics, type SemconvAttribute, type SemconvMapping, type SourceLocation, SourceLocationSchema, type SuppressableSeverity, type SuppressibleFinding, type SuppressionFile, SuppressionFileSchema, type SuppressionRule, SuppressionRuleSchema, TypeShape, applySuppressionsToFindings, bodyShapesMatch, boundaryKey, boundaryLabel, busIdentityKey, busesAgree, canPair, channelsPair, codeScopePath, countsForThreshold, dispatchByType, displayLabel, exchangesHttpResponses, fileInCodeScope, fixedTextLength, fnIdentityKey, formatChannel, functionCallBinding, gqlIdentityKey, graphqlOperationBinding, graphqlResolverBinding, hasNameHole, isGraphqlOperationBinding, messageBusBinding, metricBinding, metricIdentityKey, namePatternFromSub, namePatternKey, namesAgree, namesNothing, normalizeRuleBoundary, packageExportBinding, pairingKey, parseChannel, reportsUnpairedItself, restBinding, ruleBoundaryMatchesKey, runtimeConfigBinding, semanticsAgree, semconvAttributes, servesRequest, storageBinding, validateRule };
+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 DispatchTable, type FindingSuppression, type FnIdentityKey, type GqlIdentityKey, type MatchResult, MessageBusSemantics, MessageBusTechnology, type MetricIdentityKey, type MetricSemantics, MetricSemanticsSchema, type NamePart, type ParsedChannel, type Reference, Semantics, type SemconvAttribute, type SemconvMapping, type SourceLocation, SourceLocationSchema, type SuppressableSeverity, type SuppressibleFinding, type SuppressionFile, SuppressionFileSchema, type SuppressionRule, SuppressionRuleSchema, TypeShape, applySuppressionsToFindings, bodyShapesMatch, boundaryKey, boundaryLabel, boundaryNameString, busIdentityKey, busesAgree, canPair, channelsPair, codeScopePath, countsForThreshold, dispatchByType, displayLabel, exchangesHttpResponses, fileInCodeScope, fixedTextLength, fnIdentityKey, formatChannel, functionCallBinding, gqlIdentityKey, graphqlOperationBinding, graphqlResolverBinding, hasNameHole, isGraphqlOperationBinding, messageBusBinding, metricBinding, metricIdentityKey, namePatternFromSub, namePatternKey, namesAgree, namesNothing, normalizeRuleBoundary, packageExportBinding, pairingKey, parseBoundaryName, parseChannel, patternHole, referenceFromName, referenceName, referenceOf, reportsUnpairedItself, restBinding, ruleBoundaryMatchesKey, runtimeConfigBinding, semanticsAgree, semconvAttributes, servesRequest, storageBinding, validateRule };

package/dist/index.d.ts

@@ -243,6 +243,115 @@ declare function reportsUnpairedItself(binding: BoundaryBinding): boolean;
  */
 declare function servesRequest(binding: BoundaryBinding, method: string, path: string): MatchResult | null;
 
+/**
+ * The boundary-name syntax, parsed and printed in one place.
+ *
+ * A name in a summary means one of three things, told apart by the
+ * braces alone: a literal (`orders-v1`), a pattern with deploy-time
+ * holes (`{stage}-orders-v1`), or a reference saying where to go and
+ * ask (`{location.bucket}`, `{ORDER_TABLE}`). A second parser can
+ * disagree about which is which, and a second printer can spell a
+ * value this one cannot read back, so everything that touches the
+ * braces calls this module: `parseBoundaryName` and
+ * `boundaryNameString` are the two directions, and the helpers below
+ * are views over them. The package README tells the longer story,
+ * including why REST route paths and message-bus channels stay apart.
+ */
+/** One piece of a pattern: text the writer stated, or a hole. */
+type NamePart = {
+    type: "text";
+    text: string;
+} | {
+    type: "hole";
+    label: string;
+};
+/**
+ * What a name string means. A `reference` keeps its raw dot-separated
+ * path, and `referenceOf` is the view that checks the parts are all
+ * present, so a malformed spelling still classifies as a reference and
+ * still pairs with nothing.
+ */
+type BoundaryName = {
+    type: "literal";
+    value: string;
+} | {
+    type: "pattern";
+    parts: NamePart[];
+} | {
+    type: "reference";
+    path: string[];
+};
+/** What a name string means. The exact inverse of `boundaryNameString`. */
+declare function parseBoundaryName(name: string): BoundaryName;
+/** The one serializer. Everything a summary spells goes through here. */
+declare function boundaryNameString(name: BoundaryName): string;
+/**
+ * How a hole is spelled. A reader that assembles a pattern a part at a
+ * time, the way the adapter's name reader does, mints each hole here
+ * so the spelling cannot drift from the parse above.
+ */
+declare function patternHole(label: string): string;
+/**
+ * The name a CloudFormation `Fn::Sub` value states. The array form
+ * takes its template from the first element, and the variable map only
+ * says where a substitution comes from, which does not change the name.
+ */
+declare function namePatternFromSub(value: unknown): string | null;
+/**
+ * Whether a name says only that somebody else knows it. A wrapper that
+ * takes its bucket as an argument states `{location.bucket}` and
+ * nothing more, which says which parameter to ask rather than which
+ * bucket. A name like that agrees with nothing until something grounds
+ * it, since otherwise it would agree with every name there is.
+ */
+declare function namesNothing(name: string): boolean;
+/** Whether a name has anything a source left for deploy time to fill. */
+declare function hasNameHole(name: string): boolean;
+/**
+ * The form two patterns are compared in: every hole reduced to the same
+ * token, since the two sides pick their own name for the parameter.
+ */
+declare function namePatternKey(name: string): string;
+/** How much of a name the writer stated rather than left for deploy time. */
+declare function fixedTextLength(name: string): number;
+/**
+ * Whether two names are the same name. Two patterns agree when their
+ * fixed parts line up, since a hole on one side meets a hole on the
+ * other. A pattern and a concrete name agree when the fixed parts are
+ * where the pattern says they are, which is what happens when one side
+ * hardcoded what the other parameterized. A reference agrees with
+ * nothing on either side.
+ */
+declare function namesAgree(a: string, b: string): boolean;
+/** Where a reference says to go and ask. */
+interface Reference {
+    /**
+     * The value the code starts from: a parameter of the unit the
+     * reference was written in, or a variable the deployment sets. Which
+     * of those it is depends on the unit's inputs, so the reader that
+     * grounds a reference decides, not the string.
+     */
+    root: string;
+    /** The fields to read inside it, outermost first. */
+    fields: string[];
+}
+/**
+ * How a reference is written. Null when a part of it is empty, since a
+ * reference has to say what to ask about.
+ */
+declare function referenceName(reference: Reference): string | null;
+/**
+ * The place a parsed reference says to ask, or null for a name that is
+ * not a reference, or for a reference with a part missing, which says
+ * nothing anybody could answer.
+ */
+declare function referenceOf(name: BoundaryName): Reference | null;
+/**
+ * The reference a name states, or null when the name states a name
+ * rather than where to go and ask.
+ */
+declare function referenceFromName(name: string): Reference | null;
+
 /**
  * Deciding when two message-bus channel strings mean the same thing.
  *
@@ -325,53 +434,6 @@ declare function dispatchByType<T extends {
     type: string;
 }, R>(table: DispatchTable<T, R>, value: T): R;
 
-/**
- * A name two sides state with a hole in it.
- *
- * A deployed resource is often called something built at deploy time:
- * a template writes `!Sub "${StageName}-orders-v1"` and the code writes
- * `` `${stage}-orders-v1` ``. Neither side states a string, both agree
- * about the fixed text, and each spells the parameter its own way. So a
- * name is written here as fixed text with `{}` holes, and two names
- * agree when their fixed parts line up.
- *
- * A hole covers a whole parameter rather than one piece of a name,
- * because a name has no separator every project agrees on. Two
- * patterns that both cover one name are told apart by how much fixed
- * text each states, rather than by narrowing what a hole can cover.
- */
-/**
- * The name a CloudFormation `Fn::Sub` value states. The array form
- * takes its template from the first element, and the variable map only
- * says where a substitution comes from, which does not change the name.
- */
-declare function namePatternFromSub(value: unknown): string | null;
-/**
- * Whether a name says only that somebody else knows it. A wrapper that
- * takes its bucket as an argument states `{location.bucket}` and
- * nothing more, which says which parameter to ask rather than which
- * bucket. A name like that agrees with nothing until something grounds
- * it, since otherwise it would agree with every name there is.
- */
-declare function namesNothing(name: string): boolean;
-/** Whether a name has anything a source left for deploy time to fill. */
-declare function hasNameHole(name: string): boolean;
-/**
- * The form two patterns are compared in: every hole reduced to the same
- * token, since the two sides pick their own name for the parameter.
- */
-declare function namePatternKey(name: string): string;
-/** How much of a name the writer stated rather than left for deploy time. */
-declare function fixedTextLength(name: string): number;
-/**
- * Whether two names are the same name. Two patterns agree when their
- * fixed parts line up, since a hole on one side meets a hole on the
- * other. A pattern and a concrete name agree when the fixed parts are
- * where the pattern says they are, which is what happens when one side
- * hardcoded what the other parameterized.
- */
-declare function namesAgree(a: string, b: string): boolean;
-
 /**
  * The suppression pipeline, over the smallest finding both checkers share.
  *
@@ -622,4 +684,4 @@ declare function metricBinding(opts: {
     metricType: string | null;
 }): BoundaryBinding;
 
-export { type BoundaryBehavior, type BoundaryBinding, BoundaryBindingSchema, type BoundarySemanticsDefinition, type BusIdentityKey, type Channel, type ConfidenceInfo, ConfidenceInfoSchema, type ConfidenceLevel, ConfidenceLevelSchema, type ConfidenceSource, ConfidenceSourceSchema, type Corroboration, CorroborationSchema, DeployableUnit, type DispatchTable, type FindingSuppression, type FnIdentityKey, type GqlIdentityKey, type MatchResult, MessageBusSemantics, MessageBusTechnology, type MetricIdentityKey, type MetricSemantics, MetricSemanticsSchema, type ParsedChannel, Semantics, type SemconvAttribute, type SemconvMapping, type SourceLocation, SourceLocationSchema, type SuppressableSeverity, type SuppressibleFinding, type SuppressionFile, SuppressionFileSchema, type SuppressionRule, SuppressionRuleSchema, TypeShape, applySuppressionsToFindings, bodyShapesMatch, boundaryKey, boundaryLabel, busIdentityKey, busesAgree, canPair, channelsPair, codeScopePath, countsForThreshold, dispatchByType, displayLabel, exchangesHttpResponses, fileInCodeScope, fixedTextLength, fnIdentityKey, formatChannel, functionCallBinding, gqlIdentityKey, graphqlOperationBinding, graphqlResolverBinding, hasNameHole, isGraphqlOperationBinding, messageBusBinding, metricBinding, metricIdentityKey, namePatternFromSub, namePatternKey, namesAgree, namesNothing, normalizeRuleBoundary, packageExportBinding, pairingKey, parseChannel, reportsUnpairedItself, restBinding, ruleBoundaryMatchesKey, runtimeConfigBinding, semanticsAgree, semconvAttributes, servesRequest, storageBinding, validateRule };
+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 DispatchTable, type FindingSuppression, type FnIdentityKey, type GqlIdentityKey, type MatchResult, MessageBusSemantics, MessageBusTechnology, type MetricIdentityKey, type MetricSemantics, MetricSemanticsSchema, type NamePart, type ParsedChannel, type Reference, Semantics, type SemconvAttribute, type SemconvMapping, type SourceLocation, SourceLocationSchema, type SuppressableSeverity, type SuppressibleFinding, type SuppressionFile, SuppressionFileSchema, type SuppressionRule, SuppressionRuleSchema, TypeShape, applySuppressionsToFindings, bodyShapesMatch, boundaryKey, boundaryLabel, boundaryNameString, busIdentityKey, busesAgree, canPair, channelsPair, codeScopePath, countsForThreshold, dispatchByType, displayLabel, exchangesHttpResponses, fileInCodeScope, fixedTextLength, fnIdentityKey, formatChannel, functionCallBinding, gqlIdentityKey, graphqlOperationBinding, graphqlResolverBinding, hasNameHole, isGraphqlOperationBinding, messageBusBinding, metricBinding, metricIdentityKey, namePatternFromSub, namePatternKey, namesAgree, namesNothing, normalizeRuleBoundary, packageExportBinding, pairingKey, parseBoundaryName, parseChannel, patternHole, referenceFromName, referenceName, referenceOf, reportsUnpairedItself, restBinding, ruleBoundaryMatchesKey, runtimeConfigBinding, semanticsAgree, semconvAttributes, servesRequest, storageBinding, validateRule };

package/dist/index.js

@@ -33,7 +33,7 @@ import {
   semconvMappingOf,
   typeDefinitionKey,
   withDefinitionsInlined
-} from "./chunk-XUXN6DIX.js";
+} from "./chunk-HBAMPBAO.js";
 
 // src/semconv.ts
 function semconvAttributes(binding) {
@@ -106,29 +106,47 @@ function servesRequest(binding, method, path) {
   return serves(binding.semantics, method, path);
 }
 
-// src/codeScope.ts
-function codeScopePath(raw) {
-  return raw.trim().replace(/^\.\//, "").replace(/\/+$/, "");
-}
-function fileInCodeScope(file, scope) {
-  const prefix = codeScopePath(scope);
-  if (prefix === "" || prefix === ".") {
-    return true;
-  }
-  const path = codeScopePath(file);
-  return path === prefix || path.startsWith(`${prefix}/`);
-}
-
 // src/dispatch.ts
 function dispatchByType(table, value) {
   const handler = table[value.type];
   return handler(value);
 }
 
-// src/namePattern.ts
-var HOLE = /\{[^}]*\}/g;
+// src/boundaryName.ts
+var HOLE_SPLIT = /(\{[^}]*\})/;
 var SUB_TOKEN = /\$\{([^}]*)\}/g;
 var SUB_ESCAPE = /\$\{!/;
+function isHole(piece) {
+  return piece.startsWith("{") && piece.endsWith("}");
+}
+function parseBoundaryName(name) {
+  const parts = name.split(HOLE_SPLIT).filter((piece) => piece !== "").map(
+    (piece) => isHole(piece) ? { type: "hole", label: piece.slice(1, -1) } : { type: "text", text: piece }
+  );
+  const only = parts.length === 1 ? parts[0] : void 0;
+  if (only !== void 0 && only.type === "hole") {
+    return { type: "reference", path: only.label.split(".") };
+  }
+  if (parts.some((part) => part.type === "hole")) {
+    return { type: "pattern", parts };
+  }
+  return { type: "literal", value: name };
+}
+var partString = {
+  text: (part) => part.text,
+  hole: (part) => patternHole(part.label)
+};
+var nameString = {
+  literal: (name) => name.value,
+  pattern: (name) => name.parts.map((part) => dispatchByType(partString, part)).join(""),
+  reference: (name) => patternHole(name.path.join("."))
+};
+function boundaryNameString(name) {
+  return dispatchByType(nameString, name);
+}
+function patternHole(label) {
+  return `{${label}}`;
+}
 function namePatternFromSub(value) {
   if (Array.isArray(value)) {
     return typeof value[0] === "string" ? namePatternFromSub(value[0]) : null;
@@ -139,56 +157,101 @@ function namePatternFromSub(value) {
   if (SUB_ESCAPE.test(value)) {
     return null;
   }
-  return value.replace(SUB_TOKEN, (_whole, inner) => `{${inner}}`);
+  return value.replace(
+    SUB_TOKEN,
+    (_whole, inner) => patternHole(inner)
+  );
 }
 function namesNothing(name) {
-  return /^\{[^}]*\}$/.test(name);
+  return parseBoundaryName(name).type === "reference";
 }
 function hasNameHole(name) {
-  HOLE.lastIndex = 0;
-  return HOLE.test(name);
+  return parseBoundaryName(name).type !== "literal";
 }
 function namePatternKey(name) {
-  return name.replace(HOLE, "{}");
+  return dispatchByType(
+    {
+      literal: (parsed) => parsed.value,
+      pattern: (parsed) => boundaryNameString({
+        type: "pattern",
+        parts: parsed.parts.map(
+          (part) => part.type === "hole" ? { type: "hole", label: "" } : part
+        )
+      }),
+      reference: () => patternHole("")
+    },
+    parseBoundaryName(name)
+  );
 }
 function fixedTextLength(name) {
-  return name.replace(HOLE, "").length;
-}
-function isHole(part) {
-  return part.startsWith("{") && part.endsWith("}");
+  return dispatchByType(
+    {
+      literal: (parsed) => parsed.value.length,
+      pattern: (parsed) => parsed.parts.reduce(
+        (total, part) => total + (part.type === "text" ? part.text.length : 0),
+        0
+      ),
+      reference: () => 0
+    },
+    parseBoundaryName(name)
+  );
 }
 function quote(text) {
   return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
-function holeSource(_following) {
-  return ".+";
-}
 function admits(pattern, name) {
-  const parts = pattern.split(/(\{[^}]*\})/);
-  const source = parts.map(
-    (part, index) => isHole(part) ? holeSource(parts[index + 1] ?? "") : quote(part)
-  ).join("");
+  const source = pattern.parts.map((part) => part.type === "hole" ? ".+" : quote(part.text)).join("");
   return new RegExp(`^${source}$`).test(name);
 }
 function namesAgree(a, b) {
-  if (namesNothing(a) || namesNothing(b)) {
+  const left = parseBoundaryName(a);
+  const right = parseBoundaryName(b);
+  if (left.type === "reference" || right.type === "reference") {
     return false;
   }
-  if (a === b) {
-    return true;
-  }
-  const aHasHole = hasNameHole(a);
-  const bHasHole = hasNameHole(b);
-  if (aHasHole && bHasHole) {
+  if (left.type === "pattern" && right.type === "pattern") {
     return namePatternKey(a) === namePatternKey(b);
   }
-  if (aHasHole) {
-    return admits(a, b);
+  if (left.type === "pattern") {
+    return admits(left, b);
   }
-  if (bHasHole) {
-    return admits(b, a);
+  if (right.type === "pattern") {
+    return admits(right, a);
   }
-  return false;
+  return a === b;
+}
+function referenceName(reference) {
+  const path = [reference.root, ...reference.fields];
+  if (path.some((part) => part === "")) {
+    return null;
+  }
+  return boundaryNameString({ type: "reference", path });
+}
+function referenceOf(name) {
+  if (name.type !== "reference") {
+    return null;
+  }
+  const root = name.path[0];
+  if (root === void 0 || name.path.some((part) => part === "")) {
+    return null;
+  }
+  return { root, fields: name.path.slice(1) };
+}
+function referenceFromName(name) {
+  return referenceOf(parseBoundaryName(name));
+}
+
+// src/codeScope.ts
+function codeScopePath(raw) {
+  return raw.trim().replace(/^\.\//, "").replace(/\/+$/, "");
+}
+function fileInCodeScope(file, scope) {
+  const prefix = codeScopePath(scope);
+  if (prefix === "" || prefix === ".") {
+    return true;
+  }
+  const path = codeScopePath(file);
+  return path === prefix || path.startsWith(`${prefix}/`);
 }
 
 // src/suppressions.ts
@@ -590,6 +653,7 @@ export {
   bodyShapesMatch,
   boundaryKey,
   boundaryLabel,
+  boundaryNameString,
   busIdentityKey,
   busesAgree,
   canPair,
@@ -622,7 +686,12 @@ export {
   normalizeRuleBoundary,
   packageExportBinding,
   pairingKey,
+  parseBoundaryName,
   parseChannel,
+  patternHole,
+  referenceFromName,
+  referenceName,
+  referenceOf,
   reportsUnpairedItself,
   restBinding,
   routePathAdmits,

package/dist/schemas.cjs

@@ -535,7 +535,9 @@ var StorageSemanticsSchema = import_zod9.z.object({
    * 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.
+   * 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.
    */
   container: import_zod9.z.string().nullable(),
   /**

package/dist/schemas.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@suss/ir-core",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "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": [